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 com.google.errorprone.annotations.CheckReturnValue; 020import org.jspecify.annotations.NonNull; 021import org.jspecify.annotations.Nullable; 022import javax.annotation.concurrent.Immutable; 023import java.time.Instant; 024import java.util.List; 025import java.util.Optional; 026import static java.util.Objects.requireNonNull; 027 028/** 029 * Immutable encrypted persistence carrier, not an authenticated authorization proof. 030 * The engine authenticates its address, version, retention and schema before using it. 031 * Backends preserve all fields exactly and never substitute retention for credential expiry. 032 * @author <a href="https://www.revetkn.com">Mark Allen</a> 033 * 034 * @since 1.0.0 035 */ 036@Immutable 037@CheckReturnValue 038public final class OAuthStoreEntry { 039 private final @NonNull OAuthStoreKey key; 040 private final @NonNull String version; 041 private final @NonNull Instant retainUntil; 042 private final @NonNull String sealedForm; 043 private OAuthStoreEntry(@NonNull OAuthStoreKey key, @NonNull String version, 044 @NonNull Instant retainUntil, @NonNull String sealedForm) { 045 this.key = key; this.version = version; this.retainUntil = retainUntil; this.sealedForm = sealedForm; 046 } 047 /** 048 * Reconstructs bounded persisted transport fields; this does not validate the encrypted payload. 049 * Permanent issuer/subject fences require the whole-second Instant.MAX sentinel and must never 050 * be TTL deleted. Other kinds require a finite whole-second retention instant. 051 * @param key the persisted address 052 * @param version the canonical base64url encoding of a 32-byte version nonce 053 * @param retainUntil physical cleanup horizon, distinct from credential expiry 054 * @param sealedForm encrypted ASCII envelope, at most 16,384 characters 055 * @return the bounded storage carrier 056 * @throws NullPointerException if an argument is null 057 * @throws IllegalArgumentException if a transport field is invalid 058 * @since 1.0.0 059 */ 060 public static @NonNull OAuthStoreEntry fromStoredForm(@NonNull OAuthStoreKey key, @NonNull String version, 061 @NonNull Instant retainUntil, @NonNull String sealedForm) { 062 requireNonNull(key); OAuthStoreFormat.nonce(version); OAuthStoreFormat.retention(key.getKind(), retainUntil); 063 OAuthStoreFormat.sealed(sealedForm, 16_384); 064 return new OAuthStoreEntry(key, version, retainUntil, sealedForm); 065 } 066 /** Returns the storage address. 067 * @return the address 068 * @since 1.0.0 */ 069 public @NonNull OAuthStoreKey getKey() { return this.key; } 070 /** Returns the opaque version for exact CAS comparison. 071 * @return the version 072 * @since 1.0.0 */ 073 public @NonNull String getVersion() { return this.version; } 074 /** Returns physical cleanup authority only. 075 * @return the retention horizon 076 * @since 1.0.0 */ 077 public @NonNull Instant getRetainUntil() { return this.retainUntil; } 078 /** 079 * Releases the encrypted storage envelope. Keep it out of diagnostics and browser responses. 080 * @return the exact encrypted envelope 081 * @since 1.0.0 082 */ 083 public @NonNull String toSealedForm() { return this.sealedForm; } 084 /** Redacts all persisted fields. 085 * @return a fixed description 086 * @since 1.0.0 */ 087 @Override public @NonNull String toString() { return "OAuthStoreEntry{record=<redacted>}"; } 088}