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}