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 static java.util.Objects.requireNonNull; 020 021import com.google.errorprone.annotations.CheckReturnValue; 022import org.jspecify.annotations.NonNull; 023import org.jspecify.annotations.Nullable; 024 025import javax.annotation.concurrent.Immutable; 026import java.util.Collections; 027import java.util.LinkedHashSet; 028import java.util.List; 029import java.util.Optional; 030import java.util.Set; 031 032/** 033 * Ordered, ID-only Group membership instructions and the remaining resource operations. 034 * Applications execute both parts in original operation-index order under one authorization 035 * decision, transaction and version predicate. Existing member metadata and represented order 036 * must be retained when adding an existing ID or retaining an ID during replacement; removing 037 * then adding an ID creates a new member without the removed metadata. 038 * <p> 039 * Reduction does not inspect current membership and cannot establish whether anything changed. 040 * Applications require assigned, unique member IDs in their keyed storage snapshot and preserve 041 * whether the optional members attribute is absent or holds an empty array. Duplicate IDs in a 042 * whole-array replacement require full evaluation. 043 * Explicit value getters may disclose personal data; diagnostics redact them. 044 * 045 * @since 1.0.0 046 */ 047@Immutable 048@CheckReturnValue 049public final class ScimMembershipPatch { 050 private final @NonNull ScimResourceType resourceType; 051 private final @NonNull List<@NonNull Step> steps; 052 private final @Nullable ScimPatchRequest remainingPatchRequest; 053 private final @NonNull Set<@NonNull ScimAttributePath> requestedAttributePaths; 054 private final @NonNull Set<@NonNull ScimAttributePath> suppliedAttributePaths; 055 056 ScimMembershipPatch(@NonNull ScimResourceType resourceType, 057 @NonNull List<@NonNull Step> steps, @Nullable ScimPatchRequest remainingPatchRequest, 058 @NonNull Set<@NonNull ScimAttributePath> requestedAttributePaths, 059 @NonNull Set<@NonNull ScimAttributePath> suppliedAttributePaths) { 060 this.resourceType = requireNonNull(resourceType); 061 this.steps = List.copyOf(steps); 062 this.remainingPatchRequest = remainingPatchRequest; 063 this.requestedAttributePaths = Collections.unmodifiableSet(new LinkedHashSet<>(requestedAttributePaths)); 064 this.suppliedAttributePaths = Collections.unmodifiableSet(new LinkedHashSet<>(suppliedAttributePaths)); 065 } 066 067 /** Returns the original resource-type registration. 068 * @return resource type 069 * @since 1.0.0 070 */ 071 public @NonNull ScimResourceType getResourceType() { return resourceType; } 072 073 /** Returns membership steps in original request order. 074 * @return immutable ordered steps 075 * @since 1.0.0 076 */ 077 public @NonNull List<@NonNull Step> getSteps() { return steps; } 078 079 /** Returns remaining nonmember operations with their original indexes and private provenance. 080 * @return the remaining request, or empty when every operation was reduced 081 * @since 1.0.0 082 */ 083 public @NonNull Optional<@NonNull ScimPatchRequest> getRemainingPatchRequest() { 084 return Optional.ofNullable(remainingPatchRequest); 085 } 086 087 /** Returns attempted canonical paths from the complete original request, including no-op attempts. 088 * @return immutable requested paths 089 * @since 1.0.0 090 */ 091 public @NonNull Set<@NonNull ScimAttributePath> getRequestedAttributePaths() { return requestedAttributePaths; } 092 093 /** Returns canonical paths actually supplied by the complete original request. 094 * @return immutable supplied paths 095 * @since 1.0.0 096 */ 097 public @NonNull Set<@NonNull ScimAttributePath> getSuppliedAttributePaths() { return suppliedAttributePaths; } 098 099 /** Returns a fixed redacted diagnostic. 100 * @return redacted description 101 * @since 1.0.0 102 */ 103 @Override public @NonNull String toString() { return "ScimMembershipPatch{<redacted>}"; } 104 105 /** One executable membership instruction at its original zero-based operation position. 106 * @since 1.0.0 107 */ 108 @Immutable 109 @CheckReturnValue 110 public static final class Step { 111 private final int operationIndex; 112 private final @NonNull Kind kind; 113 private final @NonNull List<@NonNull String> values; 114 115 Step(int operationIndex, @NonNull Kind kind, @NonNull List<@NonNull String> values) { 116 this.operationIndex = operationIndex; 117 this.kind = requireNonNull(kind); 118 this.values = List.copyOf(values); 119 } 120 121 /** Returns the original zero-based operation index. 122 * @return original index 123 * @since 1.0.0 124 */ 125 public @NonNull Integer getOperationIndex() { return operationIndex; } 126 127 /** Returns the instruction kind. 128 * @return kind 129 * @since 1.0.0 130 */ 131 public @NonNull Kind getKind() { return kind; } 132 133 /** Returns exact IDs in input order; CLEAR has an empty list. 134 * @return immutable ID values, which may contain personal data 135 * @since 1.0.0 136 */ 137 public @NonNull List<@NonNull String> getValues() { return values; } 138 139 /** Returns a fixed redacted diagnostic. 140 * @return redacted description 141 * @since 1.0.0 142 */ 143 @Override public @NonNull String toString() { return "ScimMembershipPatch.Step{<redacted>}"; } 144 } 145 146 /** Ordered instruction kinds; compare member IDs exactly, regardless of text collation. 147 * @since 1.0.0 148 */ 149 @Immutable 150 public enum Kind { 151 /** Append IDs absent from current membership, preserving existing metadata and order. 152 * An empty values list is a no-op that preserves absent, empty or assigned membership. */ 153 ADD_IDS, 154 /** Remove the exact IDs if present; absent IDs are no-ops. 155 * Removing the last value from an existing members array leaves it present and empty. */ 156 REMOVE_IDS, 157 /** Remove the optional members attribute, yielding absence rather than a present empty array. 158 * This differs from REPLACE_IDS with an empty list. */ 159 CLEAR, 160 /** Replace represented sequence, retaining metadata for surviving exact IDs; an empty list represents an empty array. */ 161 REPLACE_IDS 162 } 163}