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.saml;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.Immutable;
023import java.util.Optional;
024
025/**
026 * The result of completing an SP-initiated SAML login. Only success contains identity.
027 * Backend uncertainty and outage remain distinct from a protocol rejection.
028 *
029 * @since 1.0.0
030 */
031@Immutable
032public sealed interface SamlAuthenticationResult permits SamlAuthenticationResult.Succeeded,
033        SamlAuthenticationResult.StatusReceived, SamlAuthenticationResult.Rejected,
034        SamlAuthenticationResult.Unavailable,
035        SamlAuthenticationResult.Indeterminate {
036    /**
037     * A fully validated, replay-fenced authentication.
038     *
039     * @since 1.0.0
040     */
041    @Immutable
042    final class Succeeded implements SamlAuthenticationResult {
043        private final @NonNull SamlAuthentication authentication;
044        private final @Nullable String applicationData;
045        Succeeded(@NonNull SamlAuthentication authentication) { this(authentication, null); }
046        Succeeded(@NonNull SamlAuthentication authentication, @Nullable String applicationData) {
047            this.authentication = authentication;
048            this.applicationData = applicationData;
049        }
050        /**
051         * Returns the checked identity.
052         *
053         * @return authentication
054         * @since 1.0.0
055         */
056        public @NonNull SamlAuthentication getAuthentication() { return authentication; }
057        /**
058         * Returns the local application hint from authenticated pending state. The application
059         * validates it as a local route before use; it never came from RelayState.
060         * @return optional application data
061         * @since 1.0.0
062         */
063        public @NonNull Optional<@NonNull String> getApplicationData() {
064            return Optional.ofNullable(applicationData);
065        }
066        /**
067         * Redacts the identity.
068         *
069         * @since 1.0.0
070         */
071        @Override public @NonNull String toString() { return "SamlAuthenticationResult.Succeeded{<redacted>}"; }
072    }
073
074    /**
075     * A request-bound non-success IdP status. Authentication reports whether a verified Response
076     * signature covered that status. It never contains an identity.
077     *
078     * @since 1.0.0
079     */
080    @Immutable
081    final class StatusReceived implements SamlAuthenticationResult {
082        private final @NonNull StatusCode statusCode;
083        private final boolean authenticated;
084        StatusReceived(@NonNull StatusCode statusCode, boolean authenticated) {
085            this.statusCode = statusCode;
086            this.authenticated = authenticated;
087        }
088        /**
089         * Returns a bounded status classification. A recognized immediate AuthnFailed,
090         * NoAuthnContext or RequestDenied subcode under Requester/Responder supplies the
091         * classification; otherwise the primary code supplies it. Deeper extension codes
092         * are shape-checked but do not override it. This classification alone is not
093         * signature proof; consult {@link #isAuthenticated()} separately.
094         *
095         * @return status code
096         * @since 1.0.0
097         */
098        public @NonNull StatusCode getStatusCode() { return statusCode; }
099        /**
100         * Reports whether the trusted IdP signed the Response containing this status.
101         *
102         * @return true when authenticated
103         * @since 1.0.0
104         */
105        public @NonNull Boolean isAuthenticated() { return authenticated; }
106        /**
107         * Redacts the received response.
108         *
109         * @return fixed description
110         * @since 1.0.0
111         */
112        @Override public @NonNull String toString() {
113            return "SamlAuthenticationResult.StatusReceived{" + statusCode + ", authenticated="
114                    + authenticated + "}";
115        }
116    }
117
118    /**
119     * Bounded classification of a SAML non-success StatusCode.
120     *
121     * @since 1.0.0
122     */
123    @Immutable
124    enum StatusCode {
125        /** The IdP could not authenticate the principal. */ AUTHN_FAILED,
126        /** The requested authentication context was unavailable. */ NO_AUTHN_CONTEXT,
127        /** The IdP denied the request. */ REQUEST_DENIED,
128        /** The IdP rejected the request as invalid. */ REQUESTER,
129        /** The IdP failed to process the request. */ RESPONDER,
130        /** The IdP rejected a SAML version. */ VERSION_MISMATCH,
131        /** A validly shaped status used another code. */ OTHER
132    }
133
134    /**
135     * A fixed local validation rejection.
136     *
137     * @since 1.0.0
138     */
139    @Immutable
140    final class Rejected implements SamlAuthenticationResult {
141        private final @NonNull Reason reason;
142        Rejected(@NonNull Reason reason) { this.reason = reason; }
143        /**
144         * Returns the fixed rejection reason.
145         *
146         * @return reason
147         * @since 1.0.0
148         */
149        public @NonNull Reason getReason() { return reason; }
150        /**
151         * Contains no submitted values.
152         *
153         * @since 1.0.0
154         */
155        @Override public @NonNull String toString() { return "SamlAuthenticationResult.Rejected{" + reason + "}"; }
156    }
157
158    /**
159     * A required local capability or backend was unavailable.
160     *
161     * @since 1.0.0
162     */
163    @Immutable
164    enum Unavailable implements SamlAuthenticationResult {
165        /** The required operation was unavailable. */ INSTANCE
166    }
167
168    /**
169     * A replay mutation may have succeeded, so the caller must reconcile before retrying.
170     *
171     * @since 1.0.0
172     */
173    @Immutable
174    enum Indeterminate implements SamlAuthenticationResult {
175        /** The replay mutation outcome is uncertain. */ INSTANCE
176    }
177
178    /**
179     * Bounded local validation reasons, with no raw input attached.
180     *
181     * @since 1.0.0
182     */
183    @Immutable
184    enum Reason {
185        /** The browser-bound pending state is absent, expired or inconsistent. */ PENDING,
186        /** The POST binding, XML or SAML structure is invalid. */ MESSAGE,
187        /** A required signature is missing or invalid. */ SIGNATURE,
188        /** Decryption failed, with one opaque reason for all decryption failures. */ DECRYPTION,
189        /** The IdP issuer does not match the trusted connection. */ ISSUER,
190        /** Destination does not match the configured ACS. */ DESTINATION,
191        /** Request binding does not match. */ REQUEST_BINDING,
192        /** The SAML status is not successful. */ STATUS,
193        /** Subject or NameID is invalid. */ SUBJECT,
194        /** Bearer confirmation is invalid. */ CONFIRMATION,
195        /** Assertion conditions or audience are invalid. */ CONDITIONS,
196        /** Authentication statement is invalid. */ AUTHN_STATEMENT,
197        /** The signed assertion is too old or in the future. */ RESPONSE_AGE,
198        /** The assertion has already been accepted. */ REPLAYED,
199        /** Assertion content is unsupported or malformed. */ ASSERTION_SHAPE
200    }
201}