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.saml.SamlPostBindingMessage;
020import com.revetsec.saml.SamlPostBindingParseResult;
021import com.revetsec.saml.SamlPostForm;
022import com.revetsec.saml.SamlAuthenticationRequestResult;
023import com.revetsec.saml.SamlLogoutRedirectResult;
024import com.revetsec.saml.SamlLogoutResponseRedirectResult;
025import com.revetsec.saml.SamlLogoutPostResult;
026import com.revetsec.saml.SamlLogoutResponsePostResult;
027import com.revetsec.saml.SamlRedirectBindingMessage;
028import com.revetsec.saml.SamlRedirectBindingParseResult;
029import com.soklet.HttpMethod;
030import com.soklet.MarshaledResponse;
031import com.soklet.Request;
032import com.soklet.Response;
033import com.soklet.ResponseCookie;
034import org.jspecify.annotations.NonNull;
035import org.jspecify.annotations.Nullable;
036import javax.annotation.concurrent.ThreadSafe;
037import java.net.URI;
038import java.nio.charset.StandardCharsets;
039import java.util.HashMap;
040import java.util.List;
041import java.util.Map;
042import java.util.Set;
043
044import static java.util.Objects.requireNonNull;
045
046/**
047 * Thin SAML transport helpers for application-routed Soklet endpoints. Core performs all SAML
048 * parsing, signature, pending, audience and replay decisions. The application owns cookies,
049 * IdP selection, local sessions and response policy.
050 *
051 * @since 1.0.0
052 */
053@ThreadSafe
054public final class SokletSaml {
055    private SokletSaml() { }
056
057    /**
058     * Parses a raw ACS POST body and every materialized Content-Type value, preserving duplicates.
059     *
060     * @param request application-routed ACS request
061     * @return an oversized transport outcome or core's untrusted POST-binding parse result
062     * @throws IllegalArgumentException if the application route is not POST
063     * @since 1.0.0
064     */
065    @CheckReturnValue
066    public static @NonNull SokletRequestResult<@NonNull SamlPostBindingParseResult> postBindingResultFor(@NonNull Request request) {
067        requireNonNull(request);
068        if (request.getHttpMethod() != HttpMethod.POST)
069            throw new IllegalArgumentException("SAML ACS route requires POST");
070        if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge();
071        return SokletRequestResult.fromResult(SamlPostBindingMessage.fromFormBodyResult(
072                SokletOAuth.bodyBytesFor(request),
073                SokletOAuth.collectHeaderValues(request, "Content-Type"),
074                request.getRawQuery().orElse(null)));
075    }
076
077    /**
078     * Parses an original logout POST body and every Content-Type value, preserving duplicates.
079     * The application supplies its browser-bound pending state to core when completing SP logout;
080     * a pending cookie for a cross-site POST requires Secure, HttpOnly and SameSite=None.
081     *
082     * @param request application-routed logout POST request
083     * @return an oversized transport outcome or core's untrusted logout POST-binding parse result
084     * @throws IllegalArgumentException if the application route is not POST
085     * @since 1.0.0
086     */
087    @CheckReturnValue
088    public static @NonNull SokletRequestResult<@NonNull SamlPostBindingParseResult> postLogoutBindingResultFor(@NonNull Request request) {
089        requireNonNull(request);
090        if (request.getHttpMethod() != HttpMethod.POST)
091            throw new IllegalArgumentException("SAML logout route requires POST");
092        if (Boolean.TRUE.equals(request.isContentTooLarge())) return SokletRequestResult.fromTooLarge();
093        return SokletRequestResult.fromResult(SamlPostBindingMessage.fromLogoutFormBodyResult(
094                SokletOAuth.bodyBytesFor(request),
095                SokletOAuth.collectHeaderValues(request, "Content-Type"),
096                request.getRawQuery().orElse(null)));
097    }
098
099    /**
100     * Parses the untouched query string for HTTP-Redirect logout signature verification.
101     *
102     * @param request application-routed logout GET request
103     * @return an oversized transport outcome or core's untrusted Redirect-binding parse result
104     * @since 1.0.0
105     */
106    @CheckReturnValue
107    public static @NonNull SamlRedirectBindingParseResult redirectBindingResultFor(@NonNull Request request) {
108        requireNonNull(request);
109        if (request.getHttpMethod() != HttpMethod.GET)
110            return SamlRedirectBindingParseResult.Rejected.INSTANCE;
111        return SamlRedirectBindingMessage.fromRawQueryResult(request.getRawQuery().orElse(""));
112    }
113
114    /**
115     * Sends a core-prepared authentication Redirect with no-store and no-referrer headers.
116     *
117     * @param prepared core-prepared authentication request
118     * @param cookies application-selected response cookies
119     * @return Soklet redirect response
120     * @since 1.0.0
121     */
122    @CheckReturnValue
123    public static @NonNull Response authenticationRedirect(
124            SamlAuthenticationRequestResult.@NonNull Prepared prepared,
125            @NonNull Set<@NonNull ResponseCookie> cookies) {
126        return preparedRedirect(requireNonNull(prepared).getRedirectUri(), cookies);
127    }
128
129    /**
130     * Sends a core-prepared SP logout Redirect.
131     *
132     * @param prepared core-prepared logout request
133     * @param cookies application-selected response cookies
134     * @return Soklet redirect response
135     * @since 1.0.0
136     */
137    @CheckReturnValue
138    public static @NonNull Response logoutRedirect(SamlLogoutRedirectResult.@NonNull Prepared prepared,
139            @NonNull Set<@NonNull ResponseCookie> cookies) {
140        return preparedRedirect(requireNonNull(prepared).getRedirectUri(), cookies);
141    }
142
143    /**
144     * Sends a core-prepared answer to an IdP logout request.
145     *
146     * @param prepared core-prepared logout response
147     * @param cookies application-selected response cookies
148     * @return Soklet redirect response
149     * @since 1.0.0
150     */
151    @CheckReturnValue
152    public static @NonNull Response logoutResponseRedirect(
153            SamlLogoutResponseRedirectResult.@NonNull Prepared prepared,
154            @NonNull Set<@NonNull ResponseCookie> cookies) {
155        return preparedRedirect(requireNonNull(prepared).getRedirectUri(), cookies);
156    }
157
158    /**
159     * Sends a core-prepared SP logout POST form. Set the browser-bound pending cookie and CSP
160     * before delivery; a cross-site POST pending cookie requires Secure, HttpOnly and SameSite=None.
161     *
162     * @param prepared core-prepared logout request
163     * @param cspNonce application-generated nonce, or null for manual submission
164     * @return exact UTF-8 HTML response
165     * @since 1.0.0
166     */
167    @CheckReturnValue
168    public static @NonNull MarshaledResponse logoutPostFormResponse(
169            SamlLogoutPostResult.@NonNull Prepared prepared, @Nullable String cspNonce) {
170        return postFormResponse(requireNonNull(prepared).getPostForm(), cspNonce);
171    }
172
173    /**
174     * Sends a core-prepared POST answer to an IdP logout request. The application sets its CSP.
175     *
176     * @param prepared core-prepared logout response
177     * @param cspNonce application-generated nonce, or null for manual submission
178     * @return exact UTF-8 HTML response
179     * @since 1.0.0
180     */
181    @CheckReturnValue
182    public static @NonNull MarshaledResponse logoutResponsePostFormResponse(
183            SamlLogoutResponsePostResult.@NonNull Prepared prepared, @Nullable String cspNonce) {
184        return postFormResponse(requireNonNull(prepared).getPostForm(), cspNonce);
185    }
186
187    private static @NonNull Response preparedRedirect(@NonNull URI destination,
188            @NonNull Set<@NonNull ResponseCookie> cookies) {
189        if (!"https".equalsIgnoreCase(requireNonNull(destination).getScheme()))
190            throw new IllegalArgumentException("SAML Redirect requires HTTPS");
191        return SokletOAuth.redirect(destination, requireNonNull(cookies));
192    }
193
194    /**
195     * Sends a core-prepared POST form with no-store headers. The application sets a CSP header
196     * appropriate to its page and chooses the pending cookie before calling this helper.
197     *
198     * @param form core-prepared SAML authentication or logout form
199     * @param cspNonce application-generated nonce, or null for manual submission
200     * @return exact UTF-8 HTML response
201     * @since 1.0.0
202     */
203    @CheckReturnValue
204    public static @NonNull MarshaledResponse postFormResponse(@NonNull SamlPostForm form,
205            @Nullable String cspNonce) {
206        requireNonNull(form);
207        Map<String, List<String>> headers = new HashMap<>();
208        form.getHeaders().forEach((name, value) -> headers.put(name, List.of(value)));
209        return MarshaledResponse.withStatusCode(200).headers(Map.copyOf(headers))
210                .body(form.toHtml(cspNonce).getBytes(StandardCharsets.UTF_8)).build();
211    }
212}