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}