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 static java.util.Objects.requireNonNull; 020 021import com.google.errorprone.annotations.CheckReturnValue; 022 023import org.jspecify.annotations.NonNull; 024 025import java.time.Instant; 026 027import javax.annotation.concurrent.Immutable; 028 029/** 030 * Immutable bounded encrypted cache carrier. This is storage data, never authenticated metadata or 031 * a fresh-fetch proof. Core authentication and current policy/time checks are required before use. 032 * Providers preserve all fields exactly. The expiry is a storage cleanup hint, not permission to 033 * use a document; provider TTL may only shorten retention. 034 * 035 * @author <a href="https://www.revetkn.com">Mark Allen</a> 036 * @since 1.0.0 037 */ 038@Immutable 039@CheckReturnValue 040public final class OAuthClientMetadataCacheEntry { 041 private final @NonNull OAuthClientMetadataCacheKey key; 042 private final @NonNull String version; 043 private final @NonNull Instant expiresAt; 044 private final @NonNull String sealedForm; 045 046 private OAuthClientMetadataCacheEntry( 047 @NonNull OAuthClientMetadataCacheKey key, 048 @NonNull String version, 049 @NonNull Instant expiresAt, 050 @NonNull String sealedForm) { 051 this.key = key; 052 this.version = version; 053 this.expiresAt = expiresAt; 054 this.sealedForm = sealedForm; 055 } 056 057 /** 058 * Reconstructs syntax-bounded storage fields without authenticating their contents. 059 * 060 * @param key the exact address 061 * @param version a canonical base64url 32-byte nonce; core writes use a fresh version on every 062 * replacement 063 * @param expiresAt a finite whole-second UTC expiry hint, distinct from authenticated freshness 064 * @param sealedForm the exact nonempty ASCII encrypted envelope, at most 16384 characters 065 * @return the bounded carrier 066 * @throws NullPointerException if an argument is null 067 * @throws IllegalArgumentException if a field is invalid 068 * @since 1.0.0 069 */ 070 public static @NonNull OAuthClientMetadataCacheEntry fromStoredForm( 071 @NonNull OAuthClientMetadataCacheKey key, 072 @NonNull String version, 073 @NonNull Instant expiresAt, 074 @NonNull String sealedForm) { 075 requireNonNull(key); 076 OAuthStoreFormat.nonce(version); 077 OAuthStoreFormat.retention(OAuthStoreKey.Kind.GRANT, expiresAt); 078 OAuthStoreFormat.sealed(sealedForm, 16384); 079 return new OAuthClientMetadataCacheEntry(key, version, expiresAt, sealedForm); 080 } 081 082 /** 083 * Returns the exact address. 084 * 085 * @return the address 086 * @since 1.0.0 087 */ 088 public @NonNull OAuthClientMetadataCacheKey getKey() { 089 return this.key; 090 } 091 092 /** 093 * Returns the exact comparison nonce, not a freshness ordering value. 094 * 095 * @return the opaque version 096 * @since 1.0.0 097 */ 098 public @NonNull String getVersion() { 099 return this.version; 100 } 101 102 /** 103 * Returns the unauthenticated storage expiry hint. 104 * 105 * @return the expiry hint 106 * @since 1.0.0 107 */ 108 public @NonNull Instant getExpiresAt() { 109 return this.expiresAt; 110 } 111 112 /** 113 * Releases the encrypted envelope for persistence; never log it or render it in a browser 114 * response. 115 * 116 * @return the exact envelope 117 * @since 1.0.0 118 */ 119 public @NonNull String toSealedForm() { 120 return this.sealedForm; 121 } 122 123 /** 124 * Redacts every field. 125 * 126 * @return a fixed description 127 * @since 1.0.0 128 */ 129 @Override 130 public @NonNull String toString() { 131 return "OAuthClientMetadataCacheEntry{record=<redacted>}"; 132 } 133}