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}