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}