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 com.google.errorprone.annotations.CheckReturnValue;
020import org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.ThreadSafe;
024import java.time.Duration;
025
026/**
027 * Redacted caller-thread events for SAML service-provider operations. Hooks must be fast and
028 * thread-safe. Revetsec contains hook failures except virtual-machine errors and restores
029 * interruption. Events contain no connection, subject, request ID, XML, key or browser state.
030 * A terminal event follows each start event when an operation returns or throws an ordinary
031 * runtime exception. A {@link Outcome#SUCCEEDED} login means Revetsec authenticated the SAML
032 * response; the application still decides whether to create a local session.
033 *
034 * @since 1.0.0
035 */
036@ThreadSafe
037public interface SamlObserver {
038    /**
039     * Returns the shared observer whose hooks do nothing.
040     *
041     * @return disabled observer
042     * @since 1.0.0
043     */
044    @CheckReturnValue
045    static @NonNull SamlObserver disabledInstance() { return DisabledSamlObserver.INSTANCE; }
046
047    /**
048     * Called before a SAML SP operation.
049     *
050     * @param operation fixed operation kind
051     * @since 1.0.0
052     */
053    default void willHandleOperation(@NonNull Operation operation) {}
054
055    /**
056     * Called when an operation returns a sealed result or throws an ordinary runtime exception.
057     *
058     * @param operation fixed operation kind
059     * @param outcome fixed result classification
060     * @param elapsed monotonic elapsed duration
061     * @since 1.0.0
062     */
063    default void didHandleOperation(@NonNull Operation operation, @NonNull Outcome outcome,
064            @NonNull Duration elapsed) {}
065
066    /**
067     * Called when an SP builds after explicitly acknowledging disabled JVM-global XML-signature
068     * secure validation. No runtime property value or protocol data is exposed.
069     *
070     * @since 1.0.0
071     */
072    default void didAcknowledgeGlobalSecureValidationDisabled() {}
073
074    /**
075     * Fixed SAML SP operation kinds.
076     *
077     * @since 1.0.0
078     */
079    @Immutable
080    enum Operation {
081        /** Prepare a Redirect sign-in request. */ BEGIN_AUTHENTICATION,
082        /** Prepare a POST sign-in request. */ BEGIN_POST_AUTHENTICATION,
083        /** Complete a request-bound sign-in. */ COMPLETE_AUTHENTICATION,
084        /** Complete an explicitly permitted IdP-initiated sign-in. */ COMPLETE_UNSOLICITED_AUTHENTICATION,
085        /** Check an IdP-initiated logout request. */ ACCEPT_LOGOUT_REQUEST,
086        /** Prepare an SP-initiated logout request. */ BEGIN_LOGOUT,
087        /** Complete an SP-initiated logout response. */ COMPLETE_LOGOUT,
088        /** Prepare a response to a checked IdP logout request. */ RESPOND_TO_LOGOUT_REQUEST
089    }
090
091    /**
092     * Fixed outcomes without protocol payloads.
093     *
094     * @since 1.0.0
095     */
096    @Immutable
097    enum Outcome {
098        /** A checked identity, request, response or redirect was produced. */ SUCCEEDED,
099        /** A request-bound IdP status without complete success, including partial logout, was received. */ STATUS_RECEIVED,
100        /** Revetsec rejected input or configuration. */ REJECTED,
101        /** Required local work or infrastructure was unavailable. */ UNAVAILABLE,
102        /** A required state transition may have occurred. */ INDETERMINATE,
103        /** An unexpected runtime exception escaped unchanged. */ FAILED
104    }
105}
106
107final class DisabledSamlObserver implements SamlObserver {
108    static final @NonNull SamlObserver INSTANCE = new DisabledSamlObserver();
109    private DisabledSamlObserver() {}
110}