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.oauth.server; 018 019import org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021import com.google.errorprone.annotations.CheckReturnValue; 022import javax.annotation.concurrent.Immutable; 023import java.util.Optional; 024import static java.util.Objects.requireNonNull; 025import java.net.URI; 026import java.time.Instant; 027import java.util.Map; 028import java.util.Set; 029 030/** 031 * A restricted view of a checked, pending browser interaction. The application owns login, session fixation 032 * and CSRF protection. The secret interaction handle is not a subject or proof of user authentication. 033 * Client display text is untrusted and must be escaped. Identity equality and diagnostics disclose no data. 034 * @since 1.0.0 035 */ 036@Immutable 037public final class OAuthServerInteraction { 038 private final @NonNull String value, clientId; 039 private final @Nullable String clientName; 040 private final @NonNull URI redirectUri; 041 private final @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> scopes; 042 private final @NonNull Instant expires; 043 private OAuthServerInteraction(@NonNull String value, @NonNull String clientId, @Nullable String clientName, 044 @NonNull URI redirectUri, @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> scopes, @NonNull Instant expires) { 045 this.value=value; this.clientId=clientId; this.clientName=clientName; this.redirectUri=redirectUri; 046 this.scopes=Map.copyOf(scopes); this.expires=expires; 047 } 048 // The engine supplies only a freshly authenticated pending record, never a previous UI view. 049 static @NonNull OAuthServerInteraction fromRecord(@NonNull String value, @NonNull OAuthAuthorizationRecord record, 050 @Nullable String clientName, @NonNull OAuthServerIngressLimits limits) { 051 OAuthStoreFormat.nonce(value); requireNonNull(record); requireNonNull(limits); 052 if (!record.text("status").equals("PENDING") || !OAuthAuthorizationRecord.equalDigest(OAuthAuthorizationRecord.credentialDigest(value),record.text("id"))) throw OAuthStoreFormat.invalid(); 053 if (clientName!=null) OAuthServerConfiguration.text(clientName,OAuthServerConfiguration.MAXIMUM_TEXT_LENGTH); 054 return new OAuthServerInteraction(value,record.text("clientId"),clientName,URI.create(record.text("redirect")), 055 Map.of(record.text("resource"),Set.copyOf(record.scopes(limits))),record.expires()); 056 } 057 /** Returns the secret continuation handle; use only inside the protected application session. 058 * @return secret continuation handle 059 * @since 1.0.0 060 */ 061 @CheckReturnValue public @NonNull String getInteractionValue() { return this.value; } 062 /** Returns the checked client identifier. 063 * @return checked client identifier 064 * @since 1.0.0 065 */ 066 @CheckReturnValue public @NonNull String getClientId() { return this.clientId; } 067 /** Returns optional untrusted display text that the application must escape. 068 * @return optional display text 069 * @since 1.0.0 070 */ 071 @CheckReturnValue public @NonNull Optional<@NonNull String> getClientName() { return Optional.ofNullable(this.clientName); } 072 /** Returns the exact checked return destination for display, without state or issued credentials. 073 * @return selected registered redirect URI 074 * @since 1.0.0 075 */ 076 @CheckReturnValue public @NonNull URI getRedirectUri() { return this.redirectUri; } 077 /** Returns the immutable exact requested resource and scopes for explicit application approval. 078 * @return requested scopes by resource 079 * @since 1.0.0 080 */ 081 @CheckReturnValue public @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> getRequestedScopesByResource() { return this.scopes; } 082 /** Returns the pending interaction expiry; completion rechecks current authoritative state. 083 * @return expiry instant 084 * @since 1.0.0 085 */ 086 @CheckReturnValue public @NonNull Instant getExpiresAt() { return this.expires; } 087 /** Returns a fixed redacted description. 088 * @return fixed redacted description 089 * @since 1.0.0 090 */ 091 @Override public @NonNull String toString() { return "OAuthServerInteraction{<redacted>}"; } 092}