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}