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}