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}