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.oidc;
018
019import com.revetsec.BrowserBinding;
020import com.revetsec.StateSealer;
021import com.revetsec.internal.crypto.SealedStateAccess;
022import com.revetsec.internal.crypto.SealedStateType;
023import com.revetsec.internal.http.Deadline;
024import com.revetsec.oauth.PendingAuthorizationSaveResult;
025import com.revetsec.oauth.PendingAuthorizationStore;
026import com.google.errorprone.annotations.CheckReturnValue;
027import org.jspecify.annotations.NonNull;
028import javax.annotation.concurrent.Immutable;
029import java.net.URI;
030import java.time.Duration;
031import java.time.Instant;
032import static java.util.Objects.requireNonNull;
033
034/**
035 * One bounded pending logout correlation record, separate from login. It holds no ID token, nonce, PKCE verifier,
036 * access/refresh credential or authentication proof. Browser delivery requires SAVED on the store path. A sealed
037 * cookie must be cleared on every callback and supplies no atomic concurrent single-use guarantee.
038 * @author <a href="https://www.revetkn.com">Mark Allen</a>
039 * @since 1.0.0
040 */
041@Immutable
042public final class PendingOidcLogout {
043        private final @NonNull String issuer, clientId, state;
044        private final @NonNull URI callbackUri;
045        private final @NonNull Instant createdAt, expiresAt;
046        PendingOidcLogout(@NonNull String issuer, @NonNull String clientId, @NonNull URI callbackUri, @NonNull String state, @NonNull Instant createdAt, @NonNull Instant expiresAt) {
047                OidcLogoutSupport.text(requireNonNull(issuer), OidcLogoutSupport.FIELD_LIMIT); if (issuer.isEmpty()) throw OidcLogoutSupport.invalid();
048                OidcLogoutSupport.client(requireNonNull(clientId)); OidcLogoutSupport.text(requireNonNull(callbackUri).toString(), OidcLogoutSupport.FIELD_LIMIT); OidcLogoutSupport.state(requireNonNull(state));
049                OidcLogoutPendingCodec.interval(requireNonNull(createdAt), requireNonNull(expiresAt));
050                this.issuer = issuer; this.clientId = clientId; this.callbackUri = callbackUri; this.state = state; this.createdAt = createdAt; this.expiresAt = expiresAt;
051        }
052        @NonNull String state() { return this.state; }
053        /** Returns the configured issuer, not authenticated identity.
054         * @return issuer
055         * @since 1.0.0
056         */
057        public @NonNull String getIssuer() { return this.issuer; }
058        /** Returns the configured client identifier.
059         * @return client identifier
060         * @since 1.0.0
061         */
062        public @NonNull String getClientId() { return this.clientId; }
063        /** Returns the fixed registered logout callback.
064         * @return callback URI
065         * @since 1.0.0
066         */
067        public @NonNull URI getCallbackUri() { return this.callbackUri; }
068        /** Returns when correlation state was created.
069         * @return creation instant
070         * @since 1.0.0
071         */
072        public @NonNull Instant getCreatedAt() { return this.createdAt; }
073        /** Returns exact expiry; equality is expired.
074         * @return expiry instant
075         * @since 1.0.0
076         */
077        public @NonNull Instant getExpiresAt() { return this.expiresAt; }
078        /**
079         * Seals under the dedicated pending-logout type and exact expiry. Cookie size is limited by the existing sealer
080         * profile; no cap is raised. Clear the browser cookie on every callback, including failure/exception paths.
081         * @param sealer application-owned sealer
082         * @param context fixed browser-cookie context
083         * @return typed sealed pending cookie
084         * @throws NullPointerException if a required argument is null
085         * @throws OidcLogoutException if the storage profile, interruption or provider prevents sealing
086         * @since 1.0.0
087         */
088        public @NonNull String toSealedForm(@NonNull StateSealer sealer, @NonNull String context) {
089                requireNonNull(sealer); requireNonNull(context); OidcLogoutSupport.interrupted();
090                try { String sealed = SealedStateAccess.get().seal(sealer, SealedStateType.PENDING_OIDC_LOGOUT, OidcLogoutPendingCodec.encode(this, null), context, this.expiresAt); OidcLogoutSupport.interrupted(); return sealed; }
091                catch (OidcLogoutException failure) { throw failure; }
092                catch (IllegalArgumentException invalid) { throw OidcLogoutSupport.failure(OidcLogoutException.Reason.STORAGE_PROFILE_UNSUPPORTED); }
093                catch (VirtualMachineError fatal) { throw fatal; }
094                catch (RuntimeException | Error unavailable) { OidcLogoutSupport.interrupted(); throw OidcLogoutSupport.failure(OidcLogoutException.Reason.PROVIDER_UNAVAILABLE); }
095        }
096        /**
097         * Saves using a five-second convenience budget. Only SAVED permits browser delivery; uncertain writes are never retried.
098         * @param store trusted opaque atomic store
099         * @param browserBinding nonempty browser-specific secret, at most512UTF8bytes
100         * @return fixed save outcome
101         * @since 1.0.0
102         */
103        @CheckReturnValue
104        public @NonNull PendingAuthorizationSaveResult saveToResult(@NonNull PendingAuthorizationStore store, @NonNull BrowserBinding browserBinding) { return saveToResult(store, requireNonNull(browserBinding), Duration.ofSeconds(5)); }
105        @CheckReturnValue
106        @NonNull PendingAuthorizationSaveResult saveToResult(@NonNull PendingAuthorizationStore store, @NonNull String browserBinding) { return saveToResult(store, browserBinding, Duration.ofSeconds(5)); }
107        /**
108         * Saves the complete browser-bound record under one shrinking caller budget. UNAVAILABLE before provider entry
109         * has no save effect. A late/null/throwing/possibly completed store call returns INDETERMINATE, never safe retry.
110         * Existing store capacities apply and may refuse this record without evicting live state.
111         * @param store trusted opaque atomic store
112         * @param browserBinding nonempty browser-specific secret, at most512UTF8bytes
113         * @param remaining the caller's remaining operation budget
114         * @return fixed save outcome; only SAVED permits browser delivery
115         * @throws NullPointerException if a required argument is null
116         * @throws IllegalArgumentException if browser binding is outside the profile
117         * @since 1.0.0
118         */
119        @CheckReturnValue
120        public @NonNull PendingAuthorizationSaveResult saveToResult(@NonNull PendingAuthorizationStore store, @NonNull BrowserBinding browserBinding, @NonNull Duration remaining) {
121                return saveToResult(store, requireNonNull(browserBinding).toSecretString(), remaining);
122        }
123        @CheckReturnValue
124        @NonNull PendingAuthorizationSaveResult saveToResult(@NonNull PendingAuthorizationStore store, @NonNull String browserBinding, @NonNull Duration remaining) {
125                requireNonNull(store); requireNonNull(browserBinding); requireNonNull(remaining); OidcLogoutSupport.binding(browserBinding);
126                if (remaining.isZero() || remaining.isNegative() || Thread.currentThread().isInterrupted()) return PendingAuthorizationSaveResult.UNAVAILABLE;
127                Deadline deadline = Deadline.fromNow(remaining); String record; Duration allowance;
128                try { record = OidcLogoutPendingCodec.encode(this, OidcLogoutPendingCodec.digest(browserBinding)); allowance = OidcLogoutSupport.remaining(deadline); }
129                catch (RuntimeException unavailable) { return PendingAuthorizationSaveResult.UNAVAILABLE; }
130                try {
131                        PendingAuthorizationSaveResult result = store.save(browserBinding, this.state, record, this.expiresAt, allowance);
132                        return result == null || deadline.isExpired() || Thread.currentThread().isInterrupted() ? PendingAuthorizationSaveResult.INDETERMINATE : result;
133                } catch (VirtualMachineError fatal) { throw fatal; }
134                catch (Throwable failure) { if (failure instanceof InterruptedException) Thread.currentThread().interrupt(); return PendingAuthorizationSaveResult.INDETERMINATE; }
135        }
136        /** Redacts state and browser data.
137         * @return redacted description
138         * @since 1.0.0
139         */
140        @Override public @NonNull String toString() { return "PendingOidcLogout{correlation=<redacted>}"; }
141}