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.soklet; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import com.revetsec.scim.ScimAttributeSelectionResult; 021import com.revetsec.scim.ScimIfMatchResult; 022import com.revetsec.scim.ScimIfNoneMatchResult; 023import com.revetsec.scim.ScimQueryParseResult; 024import com.revetsec.scim.ScimPatchParseResult; 025import com.revetsec.scim.ScimResource; 026import com.revetsec.scim.ScimResourceParseResult; 027import com.revetsec.scim.ScimResourceType; 028import com.revetsec.scim.ScimResponse; 029import com.revetsec.scim.ScimServiceProvider; 030import com.soklet.MarshaledResponse; 031import com.soklet.Request; 032import org.jspecify.annotations.NonNull; 033 034import javax.annotation.concurrent.ThreadSafe; 035import java.util.AbstractList; 036import java.util.List; 037import java.util.Map; 038 039import static java.util.Objects.requireNonNull; 040 041/** 042 * Thin SCIM transport helpers for application-routed Soklet endpoints. Applications select the authenticated caller, 043 * tenant, resource type and transaction, and enforce route methods. Each parser invokes one core operation using the 044 * unchanged materialized raw query, body and physical header occurrences. 045 * Reject {@link Request#isContentTooLarge()} before invoking a body helper, using an application response such as 046 * {@code provider.errorResponse(ScimError.requestTooLargeInstance())}. Body helpers also fail closed if the caller 047 * omits this check. Soklet discards an oversized request body; the transport cannot pass it to core. 048 * Configure upstream body, complete-request and header limits before requests are materialized. The application 049 * also supplies authentication challenges and method-specific Allow headers when composing transport responses. 050 * 051 * @since 1.0.0 052 */ 053@ThreadSafe 054public final class SokletScim { 055 private SokletScim() { } 056 057 /** Parses the untouched resource-list query. 058 * @param provider the application's configured service provider 059 * @param resourceType the application-selected registered resource type 060 * @param request the materialized routed request 061 * @return the core query result 062 * @since 1.0.0 063 */ 064 @CheckReturnValue 065 public static @NonNull ScimQueryParseResult queryResultFor(@NonNull ScimServiceProvider provider, 066 @NonNull ScimResourceType resourceType, @NonNull Request request) { 067 requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request); 068 return provider.parseQueryResult(resourceType, request.getRawQuery().orElse("")); 069 } 070 071 /** Parses unchanged SearchRequest bytes and original Content-Type occurrences. 072 * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response. 073 * @param provider the application's configured service provider 074 * @param resourceType the application-selected registered resource type 075 * @param request the materialized routed request 076 * @return the core query result 077 078 * @since 1.0.0 079 */ 080 @CheckReturnValue 081 public static @NonNull SokletRequestResult<@NonNull ScimQueryParseResult> searchRequestResultFor(@NonNull ScimServiceProvider provider, 082 @NonNull ScimResourceType resourceType, @NonNull Request request) { 083 requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request); 084 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 085 return SokletRequestResult.fromResult(provider.parseSearchRequestResult(resourceType, headerValues(request, "Content-Type"), 086 SokletOAuth.bodyBytesFor(request))); 087 } 088 089 /** Parses unchanged create-resource bytes and original Content-Type occurrences. 090 * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response. 091 * @param provider the application's configured service provider 092 * @param resourceType the application-selected registered resource type 093 * @param request the materialized routed request 094 * @return the core candidate resource result 095 096 * @since 1.0.0 097 */ 098 @CheckReturnValue 099 public static @NonNull SokletRequestResult<@NonNull ScimResourceParseResult> resourceResultFor(@NonNull ScimServiceProvider provider, 100 @NonNull ScimResourceType resourceType, @NonNull Request request) { 101 requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request); 102 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 103 return SokletRequestResult.fromResult(provider.parseResourceResult(resourceType, headerValues(request, "Content-Type"), 104 SokletOAuth.bodyBytesFor(request))); 105 } 106 107 /** Parses unchanged replacement bytes against the application-selected current resource. 108 * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response. 109 * @param provider the application's configured service provider 110 * @param resourceType the application-selected registered resource type 111 * @param current the authoritative current resource used by the application transaction 112 * @param request the materialized routed request 113 * @return the core replacement candidate result 114 115 * @since 1.0.0 116 */ 117 @CheckReturnValue 118 public static @NonNull SokletRequestResult<@NonNull ScimResourceParseResult> replacementResultFor(@NonNull ScimServiceProvider provider, 119 @NonNull ScimResourceType resourceType, @NonNull ScimResource current, @NonNull Request request) { 120 requireNonNull(provider); requireNonNull(resourceType); requireNonNull(current); requireNonNull(request); 121 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 122 return SokletRequestResult.fromResult(provider.parseReplacementResult(resourceType, current, headerValues(request, "Content-Type"), 123 SokletOAuth.bodyBytesFor(request))); 124 } 125 126 /** Parses unchanged PatchOp bytes and original Content-Type occurrences. 127 * The application should reject {@code request.isContentTooLarge()} to emit an appropriate HTTP response. 128 * @param provider the application's configured service provider 129 * @param resourceType the application-selected registered resource type 130 * @param request the materialized routed request 131 * @return the core schema-bound PATCH request result 132 133 * @since 1.0.0 134 */ 135 @CheckReturnValue 136 public static @NonNull SokletRequestResult<@NonNull ScimPatchParseResult> patchRequestResultFor(@NonNull ScimServiceProvider provider, 137 @NonNull ScimResourceType resourceType, @NonNull Request request) { 138 requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request); 139 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 140 return SokletRequestResult.fromResult(provider.parsePatchRequestResult(resourceType, headerValues(request, "Content-Type"), 141 SokletOAuth.bodyBytesFor(request))); 142 } 143 144 /** Parses resource-response selection from the unchanged raw query. 145 * @param provider the application's configured service provider 146 * @param resourceType the application-selected registered resource type 147 * @param request the materialized routed request 148 * @return the core attribute-selection result 149 * @since 1.0.0 150 */ 151 @CheckReturnValue 152 public static @NonNull ScimAttributeSelectionResult attributeSelectionResultFor(@NonNull ScimServiceProvider provider, 153 @NonNull ScimResourceType resourceType, @NonNull Request request) { 154 requireNonNull(provider); requireNonNull(resourceType); requireNonNull(request); 155 return provider.parseAttributeSelectionResult(resourceType, request.getRawQuery().orElse("")); 156 } 157 158 /** Checks every original If-Match occurrence against the same current resource used by the application write. 159 * @param provider the application's configured service provider 160 * @param current the authoritative current resource 161 * @param request the materialized routed request 162 * @return the core conditional result 163 * @since 1.0.0 164 */ 165 @CheckReturnValue 166 public static @NonNull ScimIfMatchResult ifMatchResultFor(@NonNull ScimServiceProvider provider, 167 @NonNull ScimResource current, @NonNull Request request) { 168 requireNonNull(provider); requireNonNull(current); requireNonNull(request); 169 return provider.checkIfMatchResult(headerValues(request, "If-Match"), current); 170 } 171 172 /** Checks every original If-None-Match occurrence for application-routed GET or HEAD handling. 173 * @param provider the application's configured service provider 174 * @param current the authoritative current resource 175 * @param request the materialized routed request 176 * @return the core conditional result 177 * @since 1.0.0 178 */ 179 @CheckReturnValue 180 public static @NonNull ScimIfNoneMatchResult ifNoneMatchResultFor(@NonNull ScimServiceProvider provider, 181 @NonNull ScimResource current, @NonNull Request request) { 182 requireNonNull(provider); requireNonNull(current); requireNonNull(request); 183 return provider.checkIfNoneMatchResult(headerValues(request, "If-None-Match"), current); 184 } 185 186 /** Emits exactly the core-prepared status, header occurrences and body bytes, which may contain personal data. 187 * @param response the restricted core-prepared response 188 * @return the exact-byte Soklet response 189 * @since 1.0.0 190 */ 191 @CheckReturnValue 192 public static @NonNull MarshaledResponse responseFor(@NonNull ScimResponse response) { 193 requireNonNull(response); 194 MarshaledResponse.Builder builder = MarshaledResponse.withStatusCode(response.getStatusCode()).headers(response.getHeaders()); 195 byte[] bytes = response.toHttpBodyWithPersonalData(); 196 // Soklet requires no entity for 204/304; supplying even a zero-length entity is rejected at dispatch. 197 if (bytes.length > 0) builder.body(bytes); 198 return builder.build(); 199 } 200 201 /** A bounded core parser can inspect occurrence counts before any hostile collection is copied or joined. */ 202 private static @NonNull List<@NonNull String> headerValues(@NonNull Request request, @NonNull String name) { 203 return new HeaderValues(request.getHeaders(), name); 204 } 205 206 @ThreadSafe 207 private static final class HeaderValues extends AbstractList<@NonNull String> { 208 private final @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> fields; 209 private final @NonNull String name; 210 private HeaderValues(@NonNull Map<@NonNull String, @NonNull List<@NonNull String>> fields, @NonNull String name) { 211 this.fields = fields; this.name = name; 212 } 213 @Override public int size() { 214 long count = 0; 215 for (Map.Entry<String, List<String>> field : fields.entrySet()) if (sameName(name, field.getKey())) { 216 count += field.getValue().size(); 217 if (count >= Integer.MAX_VALUE) return Integer.MAX_VALUE; 218 } 219 return (int) count; 220 } 221 @Override public @NonNull String get(int index) { 222 if (index < 0) throw new IndexOutOfBoundsException(); 223 for (Map.Entry<String, List<String>> field : fields.entrySet()) if (sameName(name, field.getKey())) { 224 List<String> values = field.getValue(); 225 if (index < values.size()) return values.get(index); 226 index -= values.size(); 227 } 228 throw new IndexOutOfBoundsException(); 229 } 230 } 231 232 private static boolean sameName(@NonNull String expected, @NonNull String actual) { 233 if (expected.length() != actual.length()) return false; 234 for (int index = 0; index < expected.length(); ++index) { 235 char left = expected.charAt(index), right = actual.charAt(index); 236 if (left >= 'A' && left <= 'Z') left = (char) (left + 32); 237 if (right >= 'A' && right <= 'Z') right = (char) (right + 32); 238 if (left != right) return false; 239 } 240 return true; 241 } 242}