001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.scim;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.internal.json.AsciiCase;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023import javax.annotation.concurrent.Immutable;
024import javax.annotation.concurrent.NotThreadSafe;
025import java.util.ArrayList;
026import java.util.List;
027import java.util.Objects;
028import java.util.Optional;
029
030/**
031 * Immutable application-resource registration. Endpoints are authority-free absolute paths
032 * beneath the trusted service-provider base URI, without traversal, query or fragment.
033 *
034 * @since 1.0.0
035 */
036@Immutable
037@CheckReturnValue
038public final class ScimResourceType {
039    private final @NonNull String name;
040    private final @Nullable String id;
041    private final @Nullable String description;
042    private final @NonNull String endpoint;
043    private final @NonNull ScimSchema schema;
044    private final @NonNull List<@NonNull ScimSchemaExtension> schemaExtensions;
045    private final boolean patchResponseNoContent;
046    private final int definitionCount;
047    private final boolean standardGroupSchema;
048    private final boolean standardUserSchema;
049    private final @Nullable String standardEnterpriseManagerPath;
050    private final @Nullable String standardEnterpriseManagerValuePath;
051
052    private ScimResourceType(@NonNull Builder builder) { this(builder, false); }
053
054    private ScimResourceType(@NonNull Builder builder, boolean allowDiscovery) {
055        if (builder.endpoint == null || builder.schema == null)
056            throw new IllegalStateException("A SCIM resource type requires an endpoint and core schema.");
057        name = builder.name;
058        id = builder.id;
059        description = builder.description;
060        endpoint = builder.endpoint;
061        ScimSchema configured = builder.schema;
062        ScimSchema builtinGroup = ScimSchema.groupInstance();
063        ScimSchema builtinUser = ScimSchema.userInstance();
064        // Prove every trusted builtin facet once. Equivalent rebuilt definitions
065        // use builtin attribute spellings throughout binding, storage and typed views.
066        standardGroupSchema = configured.equals(builtinGroup);
067        standardUserSchema = configured.equals(builtinUser);
068        schema = standardGroupSchema ? canonicalBuiltin(configured, builtinGroup)
069                : standardUserSchema ? canonicalBuiltin(configured, builtinUser) : configured;
070        if (schema.isDiscovery() && !allowDiscovery)
071            throw new IllegalArgumentException("Discovery schemas cannot define application resource types.");
072        List<ScimSchemaExtension> extensions = new ArrayList<>();
073        ScimSchema builtinEnterprise = ScimSchema.enterpriseUserInstance();
074        String managerPath = null;
075        for (ScimSchemaExtension extension : builder.schemaExtensions) {
076            ScimSchema extensionSchema = extension.getSchema();
077            if (extensionSchema.equals(builtinEnterprise)) {
078                ScimSchema canonical = canonicalBuiltin(extensionSchema, builtinEnterprise);
079                extensions.add(ScimSchemaExtension.fromSchema(canonical, extension.isRequired()));
080                managerPath = canonical.getId() + ":manager";
081            } else extensions.add(extension);
082        }
083        schemaExtensions = List.copyOf(extensions);
084        standardEnterpriseManagerPath = managerPath;
085        standardEnterpriseManagerValuePath = managerPath == null ? null : managerPath + ".value";
086        patchResponseNoContent = Boolean.TRUE.equals(builder.patchResponseNoContent);
087        int definitions = ScimSchemas.commonDefinitionCount();
088        for (ScimAttributeDefinition attribute : schema.getAttributes()) definitions += attribute.definitionCount();
089        java.util.HashSet<@NonNull String> ids = new java.util.HashSet<>();
090        ids.add(AsciiCase.fold(schema.getId()));
091        for (ScimSchemaExtension extension : schemaExtensions) {
092            if (!ids.add(AsciiCase.fold(extension.getSchema().getId())))
093                throw new IllegalArgumentException("Duplicate SCIM schema registration.");
094            for (ScimAttributeDefinition attribute : extension.getSchema().getAttributes())
095                definitions += attribute.definitionCount();
096        }
097        ScimSchemas.requireDefinitionCount(definitions);
098        definitionCount = definitions;
099    }
100
101    int definitionCount() { return definitionCount; }
102    boolean hasStandardGroupSchema() { return standardGroupSchema; }
103    boolean hasStandardUserSchema() { return standardUserSchema; }
104    boolean hasStandardEnterpriseUserSchema() { return standardEnterpriseManagerPath != null; }
105    boolean isStandardEnterpriseManagerPath(@NonNull String path) { return path.equals(standardEnterpriseManagerPath); }
106    boolean isStandardEnterpriseManagerValuePath(@NonNull String path) { return path.equals(standardEnterpriseManagerValuePath); }
107
108    @SuppressWarnings("ReferenceEquality") // Preserve builtin singleton optional fast paths; rebuilt schemas remain distinct.
109    private static @NonNull ScimSchema canonicalBuiltin(@NonNull ScimSchema configured, @NonNull ScimSchema builtin) {
110        // The caller has already proved complete semantic equality, including all facets.
111        return configured == builtin ? configured
112                : ScimSchema.withId(configured.getId()).name(configured.getName())
113                        .description(configured.getDescription().orElse(null))
114                        .attributes(builtin.getAttributes()).build();
115    }
116
117    static @NonNull ScimResourceType discovery(@NonNull ScimSchema schema, @NonNull String name,
118            @NonNull String endpoint) {
119        if (!schema.isDiscovery())
120            throw new IllegalArgumentException("Internal discovery registration requires a discovery schema.");
121        return new ScimResourceType(withName(name).schema(schema).endpoint(endpoint), true);
122    }
123
124    /**
125     * Starts a resource type with its required bounded token name.
126     * @param name the resource type name
127     * @return a new builder
128     * @since 1.0.0
129     */
130    public static @NonNull Builder withName(@NonNull String name) {
131        return new Builder(ScimSchemas.requireName(name));
132    }
133
134    /**
135     * Returns the shared standard core User registration without schema extensions and with PATCH 200.
136     * Register the Enterprise User schema explicitly through {@link Builder#schemaExtensions(List)}
137     * when the application supports that extension. This registration does not enable PATCH.
138     * @return the shared User resource type
139     * @since 1.0.0
140     */
141    public static @NonNull ScimResourceType userInstance() { return Defaults.USER; }
142
143    /**
144     * Returns the standard Group registration with PATCH 204.
145     * @return the shared Group resource type
146     * @since 1.0.0
147     */
148    public static @NonNull ScimResourceType groupInstance() { return Defaults.GROUP; }
149
150    /**
151     * Returns the resource type name.
152     * @return the resource type name
153     * @since 1.0.0
154     */
155    public @NonNull String getName() { return name; }
156
157    /**
158     * Returns the optional trusted discovery identifier.
159     * @return the optional trusted discovery identifier
160     * @since 1.0.0
161     */
162    public @NonNull Optional<@NonNull String> getId() { return Optional.ofNullable(id); }
163
164    /**
165     * Returns the optional description.
166     * @return the optional description
167     * @since 1.0.0
168     */
169    public @NonNull Optional<@NonNull String> getDescription() { return Optional.ofNullable(description); }
170
171    /**
172     * Returns the bounded endpoint path.
173     * @return the bounded endpoint path
174     * @since 1.0.0
175     */
176    public @NonNull String getEndpoint() { return endpoint; }
177
178    /**
179     * Returns the core schema.
180     * An equal rebuilt standard User or Group retains its configured identifier, name and
181     * description and uses the builtin attribute spellings.
182     * @return the core schema
183     * @since 1.0.0
184     */
185    public @NonNull ScimSchema getSchema() { return schema; }
186
187    /**
188     * Returns the immutable extension registrations. An equal rebuilt Enterprise User
189     * extension retains its configured identifier, name, description and required
190     * characteristic and uses the builtin attribute spellings.
191     * @return the immutable extension registrations
192     * @since 1.0.0
193     */
194    public @NonNull List<@NonNull ScimSchemaExtension> getSchemaExtensions() { return schemaExtensions; }
195    /** Canonicalizes a registered path for authorization rules and supplied-path comparisons.
196     * Core schema paths become unqualified; extension paths retain the registered schema URI.
197     * This only resolves schema spelling and does not authorize an operation or a caller.
198     * @param path a parsed attribute path
199     * @return its canonical registered form, or empty for an unknown path
200     * @since 1.0.0
201     */
202    public @NonNull Optional<@NonNull ScimAttributePath> canonicalAttributePath(
203            @NonNull ScimAttributePath path) {
204        return ScimSchemas.canonicalPath(this, Objects.requireNonNull(path));
205    }
206
207    /**
208     * Returns whether an unprojected PATCH response uses 204.
209     * @return whether an unprojected PATCH response uses 204
210     * @since 1.0.0
211     */
212    public @NonNull Boolean isPatchResponseNoContent() { return patchResponseNoContent; }
213
214    /**
215     * Compares complete semantic registrations. An equal name alone is insufficient.
216     * @param other the comparison value
217     * @return whether all registration characteristics are equal
218     * @since 1.0.0
219     */
220    @Override public boolean equals(@Nullable Object other) {
221        return this == other || (other instanceof ScimResourceType value
222                && name.equals(value.name) && Objects.equals(id, value.id)
223                && Objects.equals(description, value.description) && endpoint.equals(value.endpoint)
224                && schema.equals(value.schema) && schemaExtensions.equals(value.schemaExtensions)
225                && patchResponseNoContent == value.patchResponseNoContent);
226    }
227
228    /**
229     * Returns the complete semantic registration hash.
230     * @return the semantic hash
231     * @since 1.0.0
232     */
233    @Override public int hashCode() {
234        return Objects.hash(name, id, description, endpoint, schema, schemaExtensions,
235                patchResponseNoContent);
236    }
237
238    /**
239     * Returns a fixed redacted description.
240     * @return a fixed redacted description
241     * @since 1.0.0
242     */
243    @Override public @NonNull String toString() { return "ScimResourceType{<redacted>}"; }
244
245    private static final class Defaults {
246        private static final @NonNull ScimResourceType USER = withName("User").id("User").endpoint("/Users")
247                .schema(ScimSchema.userInstance()).build();
248        private static final @NonNull ScimResourceType GROUP = withName("Group").id("Group").endpoint("/Groups")
249                .schema(ScimSchema.groupInstance()).patchResponseNoContent(true).build();
250        private Defaults() {}
251    }
252
253    /**
254     * Mutable, non-thread-safe complete resource-type configuration.
255     * Null restores absent, unset, empty or false according to the property.
256     * @since 1.0.0
257     */
258    @NotThreadSafe
259    @CheckReturnValue
260    public static final class Builder {
261        private final @NonNull String name;
262        private @Nullable String id;
263        private @Nullable String description;
264        private @Nullable String endpoint;
265        private @Nullable ScimSchema schema;
266        private @NonNull List<@NonNull ScimSchemaExtension> schemaExtensions = List.of();
267        private @Nullable Boolean patchResponseNoContent;
268        private Builder(@NonNull String name) { this.name = name; }
269
270        /**
271         * Sets id; null restores absent.
272         * @param value the replacement, or null to restore its default
273         * @return this builder
274         * @since 1.0.0
275         */
276        public @NonNull Builder id(@Nullable String value) { id = value == null ? null : ScimSchemas.requireIdentifier(value); return this; }
277
278        /**
279         * Sets description; null restores absent.
280         * @param value the replacement, or null to restore its default
281         * @return this builder
282         * @since 1.0.0
283         */
284        public @NonNull Builder description(@Nullable String value) { description = value == null ? null : ScimSchemas.requireText(value, false); return this; }
285
286        /**
287         * Sets endpoint; null restores unset.
288         * @param value the replacement, or null to restore its default
289         * @return this builder
290         * @since 1.0.0
291         */
292        public @NonNull Builder endpoint(@Nullable String value) { endpoint = value == null ? null : ScimSchemas.requireEndpoint(value); return this; }
293
294        /**
295         * Sets schema; null restores unset.
296         * @param value the replacement, or null to restore its default
297         * @return this builder
298         * @since 1.0.0
299         */
300        public @NonNull Builder schema(@Nullable ScimSchema value) { schema = value; return this; }
301
302        /**
303         * Sets schemaExtensions; null restores empty.
304         * @param value the replacement, or null to restore its default
305         * @return this builder
306         * @since 1.0.0
307         */
308        public @NonNull Builder schemaExtensions(@Nullable List<@NonNull ScimSchemaExtension> value) { schemaExtensions = value == null ? List.of() : ScimSchemas.extensions(value); return this; }
309
310        /**
311         * Sets patchResponseNoContent; null restores false.
312         * @param value the replacement, or null to restore its default
313         * @return this builder
314         * @since 1.0.0
315         */
316        public @NonNull Builder patchResponseNoContent(@Nullable Boolean value) { patchResponseNoContent = value; return this; }
317
318        /**
319         * Validates endpoint, schemas and aggregate bounds and creates an immutable registration.
320         * @return the resource type
321         * @since 1.0.0
322         */
323        public @NonNull ScimResourceType build() { return new ScimResourceType(this); }
324    }
325}