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 */ 016package com.revetsec.soklet; 017 018import com.google.errorprone.annotations.CheckReturnValue; 019import com.revetsec.BrowserBinding; 020import com.revetsec.oauth.server.OAuthAuthorizationResult; 021import com.revetsec.oauth.server.OAuthAuthorizationServer; 022import com.revetsec.oauth.server.OAuthIntrospectionResult; 023import com.revetsec.oauth.server.OAuthRevocationResult; 024import com.revetsec.oauth.server.OAuthServerResponse; 025import com.revetsec.oauth.server.OAuthTokenResult; 026import com.soklet.MarshaledResponse; 027import com.soklet.Request; 028import org.jspecify.annotations.NonNull; 029import javax.annotation.concurrent.ThreadSafe; 030import java.util.AbstractList; 031import java.util.AbstractMap; 032import java.util.AbstractSet; 033import java.util.Iterator; 034import java.util.LinkedHashMap; 035import java.util.List; 036import java.util.Map; 037import java.util.Optional; 038import java.util.Set; 039import static java.util.Objects.requireNonNull; 040 041/** 042 * Thin issuer transport for application-routed Soklet requests and prepared core responses. Applications own 043 * route/issuer association, TLS, allocation/framing limits, sessions, authentication, consent and CSRF. These 044 * helpers use no decoded query/form map and make no user or authorization decision. 045 * <p> 046 * Soklet 4 exposes header values as lists. Every materialized occurrence and exact string reaches core; 047 * its bounds and protocol rules remain authoritative. 048 * @since 1.0.0 049 */ 050@ThreadSafe 051public final class SokletOAuthAuthorizationServer { 052 053 private SokletOAuthAuthorizationServer() {} 054 055 /** 056 * Admits raw authorization input with an independent app-owned browser binding. 057 * @param server configured issuer 058 * @param request request on the configured authorization route 059 * @param browserBinding canonical random binding retained in the protected application session 060 * @return an oversized transport outcome or core's restricted interaction or rejection 061 * @throws NullPointerException if a required argument is null 062 * @since 1.0.0 063 */ 064 @CheckReturnValue 065 public static @NonNull SokletRequestResult<@NonNull OAuthAuthorizationResult> beginAuthorizationResultFor(@NonNull OAuthAuthorizationServer server, 066 @NonNull Request request, @NonNull BrowserBinding browserBinding) { 067 requireNonNull(server); requireNonNull(request); requireNonNull(browserBinding); 068 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 069 return SokletRequestResult.fromResult(server.beginAuthorizationResult(request.getHttpMethod().name(), request.getRawQuery().orElse(null), 070 SokletOAuth.bodyBytesFor(request), headersFor(request), browserBinding)); 071 } 072 073 /** 074 * Handles unchanged token form bytes and every materialized header occurrence. 075 * @param server configured issuer 076 * @param request request on the configured token route 077 * @return an oversized transport outcome or core's committed response or rejection 078 * @throws NullPointerException if a required argument is null 079 * @since 1.0.0 080 */ 081 @CheckReturnValue 082 public static @NonNull SokletRequestResult<@NonNull OAuthTokenResult> tokenResultFor(@NonNull OAuthAuthorizationServer server, @NonNull Request request) { 083 requireNonNull(server); requireNonNull(request); 084 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 085 return SokletRequestResult.fromResult(server.tokenResult(request.getHttpMethod().name(), request.getRawQuery().orElse(null), 086 SokletOAuth.bodyBytesFor(request), headersFor(request))); 087 } 088 089 /** 090 * Handles raw revocation input; optional endpoint configuration remains a core precondition. 091 * @param server configured issuer 092 * @param request request on the configured revocation route 093 * @return an oversized transport outcome or core's committed response or rejection 094 * @throws NullPointerException if a required argument is null 095 * @since 1.0.0 096 */ 097 @CheckReturnValue 098 public static @NonNull SokletRequestResult<@NonNull OAuthRevocationResult> revocationResultFor(@NonNull OAuthAuthorizationServer server, @NonNull Request request) { 099 requireNonNull(server); requireNonNull(request); 100 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 101 return SokletRequestResult.fromResult(server.revokeResult(request.getHttpMethod().name(), request.getRawQuery().orElse(null), 102 SokletOAuth.bodyBytesFor(request), headersFor(request))); 103 } 104 105 /** 106 * Handles raw introspection input without selecting caller/resource authorization in the adapter. 107 * @param server configured issuer 108 * @param request request on the configured introspection route 109 * @return an oversized transport outcome or core's committed response or rejection 110 * @throws NullPointerException if a required argument is null 111 * @since 1.0.0 112 */ 113 @CheckReturnValue 114 public static @NonNull SokletRequestResult<@NonNull OAuthIntrospectionResult> introspectionResultFor(@NonNull OAuthAuthorizationServer server, @NonNull Request request) { 115 requireNonNull(server); requireNonNull(request); 116 if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge(); 117 return SokletRequestResult.fromResult(server.introspectionResult(request.getHttpMethod().name(), request.getRawQuery().orElse(null), 118 SokletOAuth.bodyBytesFor(request), headersFor(request))); 119 } 120 121 /** 122 * Emits the exact prepared body, headers, status and optional credential-bearing Location without JSON 123 * marshalling or redirect regeneration. A bodyless prepared response remains absent rather than becoming 124 * an explicit zero-byte body, so Soklet's default HEAD handling retains the prepared GET representation 125 * length for metadata and JWKS without emitting a body. 126 * Keep this response out of diagnostics; add app cookies at the edge. 127 * @param response restricted core response, possibly containing credentials or personal data 128 * @return exact-byte Soklet response 129 * @throws NullPointerException if response is null 130 * @since 1.0.0 131 */ 132 @CheckReturnValue 133 public static @NonNull MarshaledResponse responseFor(@NonNull OAuthServerResponse response) { 134 requireNonNull(response); 135 Optional<String> location = response.getLocationWithCredentials().map(SokletOAuth::redirectLocation); 136 Map<String, List<String>> headers = new LinkedHashMap<>(); 137 response.getHeaders().forEach((name, values) -> headers.put(name, List.copyOf(values))); 138 location.ifPresent(value -> headers.put("Location", List.of(value))); 139 MarshaledResponse.Builder builder = MarshaledResponse.withStatusCode(response.getStatusCode()).headers(headers); 140 byte[] body = response.toHttpBodyWithCredentials(); 141 if (body.length != 0) 142 builder.body(body); 143 return builder.build(); 144 } 145 146 /** Lazy read-only views let core check occurrence/byte bounds before copying hostile header collections. */ 147 private static @NonNull Map<@NonNull String, @NonNull List<@NonNull String>> headersFor(@NonNull Request request) { 148 Map<String, List<String>> fields = request.getHeaders(); 149 return new AbstractMap<>() { 150 @Override public @NonNull Set<Map.@NonNull Entry<@NonNull String, @NonNull List<@NonNull String>>> entrySet() { 151 return new AbstractSet<>() { 152 @Override public int size() { return fields.size(); } 153 @Override public @NonNull Iterator<Map.@NonNull Entry<@NonNull String, @NonNull List<@NonNull String>>> iterator() { 154 Iterator<Map.Entry<String, List<String>>> entries = fields.entrySet().iterator(); 155 return new Iterator<>() { 156 @Override public boolean hasNext() { return entries.hasNext(); } 157 @Override public Map.@NonNull Entry<@NonNull String, @NonNull List<@NonNull String>> next() { 158 Map.Entry<String, List<String>> field = entries.next(); 159 List<String> values = field.getValue(); 160 List<String> view = new AbstractList<>() { 161 @Override public int size() { return values.size(); } 162 @Override public @NonNull String get(int index) { 163 if (index < 0 || index >= values.size()) throw new IndexOutOfBoundsException(); 164 Iterator<String> iterator = values.iterator(); 165 for (int i = 0; i < index; i++) iterator.next(); 166 return iterator.next(); 167 } 168 }; 169 return new SimpleImmutableEntry<>(field.getKey(), view); 170 } 171 }; 172 } 173 }; 174 } 175 }; 176 } 177}