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.oauth.RefreshToken;
020import com.revetsec.oauth.TokenResponse;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023import javax.annotation.concurrent.Immutable;
024import java.util.Optional;
025import static java.util.Objects.requireNonNull;
026
027/**
028 * Checked values from one refresh, released after any returned ID token passes signature, profile and original-session
029 * continuity checks. An omitted ID token yields no new identity. The original reference remains a continuity
030 * comparison value and is not proof of identity. Applications serialize concurrent refreshes and store tokens.
031 * @author <a href="https://www.revetkn.com">Mark Allen</a>
032 * @since 1.0.0
033 */
034@Immutable
035public final class OidcRefresh {
036        private final TokenResponse tokens;
037        private final @Nullable IdToken idToken;
038        private final RefreshToken refreshToken;
039        private final OidcSessionReference original;
040        private final @Nullable Object owner;
041        OidcRefresh(@NonNull TokenResponse tokens, @Nullable IdToken idToken, @NonNull RefreshToken previous, @NonNull OidcSessionReference original) {
042                this(tokens, idToken, previous, original, null);
043        }
044        OidcRefresh(@NonNull TokenResponse tokens, @Nullable IdToken idToken, @NonNull RefreshToken previous,
045                        @NonNull OidcSessionReference original, @Nullable Object owner) {
046                this.owner = owner;
047                this.tokens = requireNonNull(tokens); this.idToken = idToken; this.original = requireNonNull(original);
048                this.refreshToken = tokens.getRefreshToken().orElse(requireNonNull(previous));
049        }
050        @SuppressWarnings("ReferenceEquality") // Logout hint creation requires the exact producing client's private capability.
051        boolean belongsTo(@NonNull Object owner) { return this.owner == owner; }
052        /**
053         * Returns the endpoint tokens. The raw id_token is absent from its safe parameter view.
054         * @return token response
055         * @since 1.0.0
056         */
057        public @NonNull TokenResponse getTokens() { return this.tokens; }
058        /**
059         * Returns the newly verified ID token, if the provider returned one. An absent value establishes no new identity.
060         * @return verified ID token
061         * @since 1.0.0
062         */
063        public @NonNull Optional<@NonNull IdToken> getIdToken() { return Optional.ofNullable(this.idToken); }
064        /**
065         * Returns the replacement refresh token, or the previous token when no replacement was returned.
066         * @return refresh credential to retain securely
067         * @since 1.0.0
068         */
069        public @NonNull RefreshToken getRefreshToken() { return this.refreshToken; }
070        /**
071         * Returns the original reference for subsequent refresh comparisons. Parsing it never authenticates identity.
072         * @return original continuity reference
073         * @since 1.0.0
074         */
075        public @NonNull OidcSessionReference getSessionReference() { return this.original; }
076        /**
077         * Redacts tokens and continuity data.
078         * @return redacted description
079         * @since 1.0.0
080         */
081        @Override public @NonNull String toString() { return "OidcRefresh{credentials=<redacted>, session=<redacted>}"; }
082}