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.Limits;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023import javax.annotation.concurrent.Immutable;
024import javax.annotation.concurrent.NotThreadSafe;
025import java.net.URI;
026import java.util.List;
027import java.util.Objects;
028import java.util.Optional;
029
030/**
031 * Immutable SCIM capability advertisement. The application must implement every enabled
032 * operation; the facade checks registered filtering policies and configured processing bounds.
033 * The password-change flag advertises application support; it does not authorize credential
034 * changes or reject schema-bound write-only password input when false. Password handling and
035 * authorization belong to the application; response rendering omits returned-never values.
036 * Bulk is always unsupported. Builders and copying perform no application callbacks.
037 * @since 1.0.0
038 */
039@Immutable
040@CheckReturnValue
041public final class ScimServiceProviderConfig {
042    private final boolean patchSupported;
043    private final boolean filterSupported;
044    private final boolean sortSupported;
045    private final boolean changePasswordSupported;
046    private final boolean etagSupported;
047    private final int filterMaximumResults;
048    private final @NonNull ScimPaginationConfig pagination;
049    private final @NonNull List<@NonNull ScimAuthenticationScheme> authenticationSchemes;
050    private final @Nullable URI documentationUri;
051
052    private ScimServiceProviderConfig(@NonNull Builder builder) {
053        patchSupported = Boolean.TRUE.equals(builder.patchSupported);
054        filterSupported = Boolean.TRUE.equals(builder.filterSupported);
055        sortSupported = Boolean.TRUE.equals(builder.sortSupported);
056        changePasswordSupported = Boolean.TRUE.equals(builder.changePasswordSupported);
057        etagSupported = builder.etagSupported == null || builder.etagSupported;
058        filterMaximumResults = Limits.SCIM_PAGE_SIZE.require(builder.filterMaximumResults == null
059                ? Limits.SCIM_PAGE_SIZE.getDefaultIntValue() : builder.filterMaximumResults);
060        pagination = builder.pagination == null ? ScimPaginationConfig.builder().build() : builder.pagination;
061        authenticationSchemes = builder.authenticationSchemes;
062        documentationUri = builder.documentationUri;
063        int primaryCount = 0;
064        for (ScimAuthenticationScheme scheme : authenticationSchemes)
065            if (scheme.isPrimary()) primaryCount++;
066        if (primaryCount > 1)
067            throw new IllegalArgumentException("SCIM authentication schemes may have only one primary value.");
068    }
069
070    /**
071     * Starts with PATCH/filter/sort disabled, password-change advertising false, ETags enabled
072     * and default pagination. The password advertisement does not disable password input or
073     * enable a credential handler. Applications authorize and process supplied password values.
074     * @return a new builder
075     * @since 1.0.0
076     */
077    public static @NonNull Builder builder() { return new Builder(); }
078
079    /**
080     * Returns whether PATCH is advertised.
081     * @return whether PATCH is advertised
082     * @since 1.0.0
083     */
084    public @NonNull Boolean isPatchSupported() { return patchSupported; }
085
086    /**
087     * Returns whether filtering is advertised.
088     * @return whether filtering is advertised
089     * @since 1.0.0
090     */
091    public @NonNull Boolean isFilterSupported() { return filterSupported; }
092
093    /**
094     * Returns whether sorting is advertised.
095     * @return whether sorting is advertised
096     * @since 1.0.0
097     */
098    public @NonNull Boolean isSortSupported() { return sortSupported; }
099
100    /**
101     * Returns whether password changes are advertised.
102     * False does not reject schema-bound password input; true does not authorize that input,
103     * enable PATCH, or change the standard User password's write-only/returned-never facets.
104     * @return whether password changes are advertised
105     * @since 1.0.0
106     */
107    public @NonNull Boolean isChangePasswordSupported() { return changePasswordSupported; }
108
109    /**
110     * Returns whether entity tags are advertised.
111     * @return whether entity tags are advertised
112     * @since 1.0.0
113     */
114    public @NonNull Boolean isEtagSupported() { return etagSupported; }
115
116    /**
117     * Returns the maximum advertised filtered result count.
118     * @return the maximum advertised filtered result count
119     * @since 1.0.0
120     */
121    public @NonNull Integer getFilterMaximumResults() { return filterMaximumResults; }
122
123    /**
124     * Returns the immutable pagination advertisement.
125     * @return the immutable pagination advertisement
126     * @since 1.0.0
127     */
128    public @NonNull ScimPaginationConfig getPagination() { return pagination; }
129
130    /**
131     * Returns the immutable authentication-scheme descriptions.
132     * @return the immutable authentication-scheme descriptions
133     * @since 1.0.0
134     */
135    public @NonNull List<@NonNull ScimAuthenticationScheme> getAuthenticationSchemes() { return authenticationSchemes; }
136
137    /**
138     * Returns the optional documentation URI.
139     * @return the optional documentation URI
140     * @since 1.0.0
141     */
142    public @NonNull Optional<@NonNull URI> getDocumentationUri() { return Optional.ofNullable(documentationUri); }
143
144    /**
145     * Compares all advertised capability characteristics.
146     * @param other the comparison value
147     * @return whether advertisements are equal
148     * @since 1.0.0
149     */
150    @Override public boolean equals(@Nullable Object other) {
151        return this == other || (other instanceof ScimServiceProviderConfig value
152                && patchSupported == value.patchSupported && filterSupported == value.filterSupported
153                && sortSupported == value.sortSupported && changePasswordSupported == value.changePasswordSupported
154                && etagSupported == value.etagSupported && filterMaximumResults == value.filterMaximumResults
155                && pagination.equals(value.pagination) && authenticationSchemes.equals(value.authenticationSchemes)
156                && Objects.equals(documentationUri, value.documentationUri));
157    }
158
159    /**
160     * Returns the advertisement hash.
161     * @return the advertisement hash
162     * @since 1.0.0
163     */
164    @Override public int hashCode() {
165        return Objects.hash(patchSupported, filterSupported, sortSupported, changePasswordSupported,
166                etagSupported, filterMaximumResults, pagination, authenticationSchemes, documentationUri);
167    }
168
169    /**
170     * Returns a fixed redacted description.
171     * @return a fixed redacted description
172     * @since 1.0.0
173     */
174    @Override public @NonNull String toString() { return "ScimServiceProviderConfig{<redacted>}"; }
175
176    /**
177     * Mutable, non-thread-safe capability configuration; null restores the stated default.
178     * @since 1.0.0
179     */
180    @NotThreadSafe
181    @CheckReturnValue
182    public static final class Builder {
183        private @Nullable Boolean patchSupported;
184        private @Nullable Boolean filterSupported;
185        private @Nullable Boolean sortSupported;
186        private @Nullable Boolean changePasswordSupported;
187        private @Nullable Boolean etagSupported;
188        private @Nullable Integer filterMaximumResults;
189        private @Nullable ScimPaginationConfig pagination;
190        private @NonNull List<@NonNull ScimAuthenticationScheme> authenticationSchemes = List.of();
191        private @Nullable URI documentationUri;
192        private Builder() {}
193
194        /**
195         * Sets patchSupported; null restores false.
196         * @param value the replacement, or null to restore its default
197         * @return this builder
198         * @since 1.0.0
199         */
200        public @NonNull Builder patchSupported(@Nullable Boolean value) { patchSupported = value; return this; }
201
202        /**
203         * Sets filterSupported; null restores false.
204         * @param value the replacement, or null to restore its default
205         * @return this builder
206         * @since 1.0.0
207         */
208        public @NonNull Builder filterSupported(@Nullable Boolean value) { filterSupported = value; return this; }
209
210        /**
211         * Sets sortSupported; null restores false.
212         * @param value the replacement, or null to restore its default
213         * @return this builder
214         * @since 1.0.0
215         */
216        public @NonNull Builder sortSupported(@Nullable Boolean value) { sortSupported = value; return this; }
217
218        /**
219         * Sets the password-change capability advertisement; null restores false.
220         * This setting neither authorizes nor handles credential changes. It does not gate
221         * schema-bound password input, enable PATCH, or make passwords returnable in responses.
222         * @param value the replacement, or null to restore its default
223         * @return this builder
224         * @since 1.0.0
225         */
226        public @NonNull Builder changePasswordSupported(@Nullable Boolean value) { changePasswordSupported = value; return this; }
227
228        /**
229         * Sets etagSupported; null restores true.
230         * @param value the replacement, or null to restore its default
231         * @return this builder
232         * @since 1.0.0
233         */
234        public @NonNull Builder etagSupported(@Nullable Boolean value) { etagSupported = value; return this; }
235
236        /**
237         * Sets filterMaximumResults; null restores 1000.
238         * @param value the replacement, or null to restore its default
239         * @return this builder
240         * @since 1.0.0
241         */
242        public @NonNull Builder filterMaximumResults(@Nullable Integer value) { filterMaximumResults = value; return this; }
243
244        /**
245         * Sets pagination; null restores fresh defaults.
246         * @param value the replacement, or null to restore its default
247         * @return this builder
248         * @since 1.0.0
249         */
250        public @NonNull Builder pagination(@Nullable ScimPaginationConfig value) { pagination = value; return this; }
251
252        /**
253         * Sets authenticationSchemes; null restores empty.
254         * @param value the replacement, or null to restore its default
255         * @return this builder
256         * @since 1.0.0
257         */
258        public @NonNull Builder authenticationSchemes(@Nullable List<@NonNull ScimAuthenticationScheme> value) { if (value == null) authenticationSchemes = List.of();
259            else {
260                ScimSchemas.requireDefinitionCount(value.size());
261                for (ScimAuthenticationScheme scheme : value) Objects.requireNonNull(scheme);
262                authenticationSchemes = List.copyOf(value);
263            }; return this; }
264
265        /**
266         * Sets documentationUri; null restores absent.
267         * @param value the replacement, or null to restore its default
268         * @return this builder
269         * @since 1.0.0
270         */
271        public @NonNull Builder documentationUri(@Nullable URI value) { documentationUri = value == null ? null : ScimSchemas.requireDocumentationUri(value); return this; }
272
273        /**
274         * Checks bounded advertisement characteristics and creates an immutable snapshot.
275         * @return the capability advertisement
276         * @since 1.0.0
277         */
278        public @NonNull ScimServiceProviderConfig build() { return new ScimServiceProviderConfig(this); }
279    }
280}