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.internal.json.JsonFields;
020import com.revetsec.internal.json.JsonFieldException;
021import com.revetsec.oauth.TokenResponse;
022import com.revetsec.json.JsonArray;
023import com.revetsec.json.JsonString;
024import org.jspecify.annotations.NonNull;
025import org.jspecify.annotations.Nullable;
026import javax.annotation.concurrent.Immutable;
027import java.time.Instant;
028import java.util.List;
029import java.util.Optional;
030import java.util.Set;
031
032/**
033 * One fully validated code-flow authentication. The exact issuer and subject pair is the stable account key
034 * (OpenID Connect Core section 5.7); email is never an account key. No public constructor or parse-only factory exists.
035 *
036 * @author <a href="https://www.revetkn.com">Mark Allen</a>
037 * @since 1.0.0
038 */
039@Immutable
040public final class OidcAuthentication {
041        private final String clientId;
042        private final @Nullable Object owner;
043        private final IdToken idToken;
044        private final TokenResponse tokens;
045        private final OidcSessionReference sessionReference;
046        OidcAuthentication(@NonNull IdToken idToken, @NonNull TokenResponse tokens, @NonNull String clientId) {
047                this(idToken, tokens, clientId, null);
048        }
049        OidcAuthentication(@NonNull IdToken idToken, @NonNull TokenResponse tokens, @NonNull String clientId, @Nullable Object owner) {
050                this(idToken, tokens, clientId, owner, Set.of());
051        }
052        OidcAuthentication(@NonNull IdToken idToken, @NonNull TokenResponse tokens, @NonNull String clientId, @Nullable Object owner,
053                        @NonNull Set<@NonNull String> requiredAcrValues) {
054                this.owner = owner;
055                this.clientId = java.util.Objects.requireNonNull(clientId);
056                this.idToken = idToken; this.tokens = tokens; this.sessionReference = new OidcSessionReference(idToken, clientId, requiredAcrValues);
057        }
058        @NonNull String clientId() { return this.clientId; }
059        @SuppressWarnings("ReferenceEquality") // A private client capability requires identical ownership, never value equality.
060        boolean belongsTo(@NonNull Object owner) { return this.owner == owner; }
061        @NonNull OidcAuthentication withTokens(@NonNull TokenResponse tokens) { return new OidcAuthentication(this.idToken, tokens, this.clientId, this.owner, this.sessionReference.getRequiredAcrValues()); }
062        /**
063         * Returns the exact validated issuer.
064         *
065         * @return issuer
066         * @since 1.0.0
067         */
068        public @NonNull String getIssuer() { return this.idToken.getClaims().getIssuer().orElseThrow(); }
069        /**
070         * Returns the validated subject, scoped to this issuer.
071         *
072         * @return subject
073         * @since 1.0.0
074         */
075        public @NonNull String getSubject() { return this.idToken.getClaims().getSubject().orElseThrow(); }
076        /**
077         * Returns the validated ID token.
078         *
079         * @return ID token
080         * @since 1.0.0
081         */
082        public @NonNull IdToken getIdToken() { return this.idToken; }
083        /**
084         * Returns endpoint tokens only after ID-token validation.
085         *
086         * @return tokens
087         * @since 1.0.0
088         */
089        public @NonNull TokenResponse getTokens() { return this.tokens; }
090        /**
091         * Returns the validated authentication time when present.
092         *
093         * @return authentication time
094         * @since 1.0.0
095         */
096        public @NonNull Optional<@NonNull Instant> getAuthenticationTime() {
097                try { return JsonFields.numericDate(this.idToken.getClaims().toJsonObject(), "auth_time"); }
098                catch (JsonFieldException impossible) { throw new IllegalStateException("Validated authentication time is invalid."); }
099        }
100        /**
101         * Returns the validated ACR when present.
102         *
103         * @return ACR
104         * @since 1.0.0
105         */
106        public @NonNull Optional<@NonNull String> getAuthenticationContextClassReference() {
107                return this.idToken.getClaims().getClaim("acr").map(value -> ((JsonString) value).getValue());
108        }
109        /**
110         * Returns validated authentication method references, or an empty list.
111         *
112         * @return authentication methods
113         * @since 1.0.0
114         */
115        public @NonNull List<@NonNull String> getAuthenticationMethodReferences() {
116                return this.idToken.getClaims().getClaim("amr").map(value -> ((JsonArray) value).getElements().stream()
117                                .map(element -> ((JsonString) element).getValue()).toList()).orElse(List.of());
118        }
119        /**
120         * Returns a persistence reference for continuity checks. It is not proof of identity.
121         *
122         * @return session reference
123         * @since 1.0.0
124         */
125        public @NonNull OidcSessionReference getSessionReference() { return this.sessionReference; }
126        /**
127         * Redacts identity and credentials.
128         *
129         * @return a redacted description
130         * @since 1.0.0
131         */
132        @Override public @NonNull String toString() { return "OidcAuthentication{identity=<redacted>, tokens=<redacted>}"; }
133}