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}