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;
020
021import javax.annotation.concurrent.Immutable;
022import java.net.URI;
023
024/**
025 * A prepared SP-initiated login, a configuration rejection, or an unavailable signing/time source.
026 * Only {@link Prepared} can be sent to the browser.
027 *
028 * @since 1.0.0
029 */
030@Immutable
031public sealed interface SamlAuthenticationRequestResult permits SamlAuthenticationRequestResult.Prepared,
032        SamlAuthenticationRequestResult.PostPrepared, SamlAuthenticationRequestResult.Rejected,
033        SamlAuthenticationRequestResult.Unavailable {
034    /**
035     * A Redirect-binding request and the pending state that must accompany the browser.
036     *
037     * @since 1.0.0
038     */
039    @Immutable
040    final class Prepared implements SamlAuthenticationRequestResult {
041        private final @NonNull URI redirectUri;
042        private final @NonNull PendingSamlAuthentication pending;
043        Prepared(@NonNull URI redirectUri, @NonNull PendingSamlAuthentication pending) {
044            this.redirectUri = redirectUri;
045            this.pending = pending;
046        }
047        /**
048         * Returns the IdP redirect URI.
049         *
050         * @return URI
051         * @since 1.0.0
052         */
053        public @NonNull URI getRedirectUri() { return redirectUri; }
054        /**
055         * Returns the pending state for this request.
056         *
057         * @return pending login
058         * @since 1.0.0
059         */
060        public @NonNull PendingSamlAuthentication getPendingAuthentication() { return pending; }
061        /**
062         * Redacts the request and state.
063         *
064         * @since 1.0.0
065         */
066        @Override public @NonNull String toString() { return "SamlAuthenticationRequestResult.Prepared{<redacted>}"; }
067    }
068
069    /**
070     * A POST-binding request and its browser pending state.
071     *
072     * @since 1.0.0
073     */
074    @Immutable
075    final class PostPrepared implements SamlAuthenticationRequestResult {
076        private final @NonNull SamlPostForm form;
077        private final @NonNull PendingSamlAuthentication pending;
078        PostPrepared(@NonNull SamlPostForm form, @NonNull PendingSamlAuthentication pending) {
079            this.form = form;
080            this.pending = pending;
081        }
082        /**
083         * Returns the IdP-bound form.
084         *
085         * @return form
086         * @since 1.0.0
087         */
088        public @NonNull SamlPostForm getPostForm() { return form; }
089        /**
090         * Returns the pending login state.
091         *
092         * @return pending state
093         * @since 1.0.0
094         */
095        public @NonNull PendingSamlAuthentication getPendingAuthentication() { return pending; }
096        /**
097         * Redacts the request.
098         *
099         * @return redacted description
100         * @since 1.0.0
101         */
102        @Override public @NonNull String toString() {
103            return "SamlAuthenticationRequestResult.PostPrepared{<redacted>}";
104        }
105    }
106
107    /**
108     * A local configuration rejection discovered when preparing a request.
109     *
110     * @since 1.0.0
111     */
112    @Immutable
113    enum Rejected implements SamlAuthenticationRequestResult {
114        /** The IdP requires signing, but the SP cannot prepare a valid request. */ CONFIGURATION
115    }
116
117    /**
118     * The time, randomness or signing capability was unavailable.
119     *
120     * @since 1.0.0
121     */
122    @Immutable
123    enum Unavailable implements SamlAuthenticationRequestResult {
124        /** The operation could not produce a request. */ INSTANCE
125    }
126}