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 * Opaque issuer storage address. Reconstruction checks syntax and grants no protocol authority.
030 * Persist the exact storage string; identifiers are sensitive and diagnostics redact them.
031 * @author <a href="https://www.revetkn.com">Mark Allen</a>
032 *
033 * @since 1.0.0
034 */
035@Immutable
036@CheckReturnValue
037public final class OAuthStoreKey {
038 private final @NonNull String storageKey;
039 private final OAuthStoreKey.@NonNull Kind kind;
040 private OAuthStoreKey(@NonNull String storageKey, OAuthStoreKey.@NonNull Kind kind) {
041  this.storageKey = storageKey; this.kind = kind;
042 }
043 /**
044  * Reconstructs a storage address, bounded to 256 ASCII characters and the current canonical format.
045  * The issuer checks its namespace before using this address. This does not authenticate a record.
046  * @param storageKey the exact persisted address
047  * @return the bounded address
048  * @throws NullPointerException if the argument is null
049  * @throws IllegalArgumentException if its format is invalid
050  * @since 1.0.0
051  */
052 public static @NonNull OAuthStoreKey fromStoredForm(@NonNull String storageKey) {
053  return new OAuthStoreKey(storageKey, OAuthStoreFormat.keyKind(storageKey));
054 }
055 /**
056  * Releases the sensitive opaque address for persistence; never log it.
057  * @return the exact storage address
058  * @since 1.0.0
059  */
060 public @NonNull String getStorageKey() { return this.storageKey; }
061 /**
062  * Returns the storage record kind, which alone confers no authority.
063  * @return the record kind
064  * @since 1.0.0
065  */
066 public OAuthStoreKey.@NonNull Kind getKind() { return this.kind; }
067 /**
068  * Compares exact storage addresses.
069  * @param other the possible address
070  * @return whether the addresses are equal
071  * @since 1.0.0
072  */
073 @Override public boolean equals(@Nullable Object other) {
074  return other instanceof OAuthStoreKey key && this.storageKey.equals(key.storageKey);
075 }
076 /**
077  * Returns the exact address hash.
078  * @return the address hash
079  * @since 1.0.0
080  */
081 @Override public int hashCode() { return this.storageKey.hashCode(); }
082 /**
083  * Redacts the address.
084  * @return a fixed description
085  * @since 1.0.0
086  */
087 @Override public @NonNull String toString() { return "OAuthStoreKey{address=<redacted>}"; }
088 /**
089  * Issuer storage record kinds; a later release may add values. Store backends must not switch exhaustively
090  * without a rejecting default. Permanent fence kinds must never be TTL evicted.
091  * @author <a href="https://www.revetkn.com">Mark Allen</a>
092  * @since 1.0.0
093  */
094 @Immutable
095 public enum Kind {
096  /** Permanent issuer epoch and clock fence. */
097  ISSUER_STATE,
098  /** Permanent issuer-local subject epoch. */
099  SUBJECT_STATE,
100  /** Browser-bound authorization interaction. */
101  INTERACTION,
102  /** Authorization code or retained consumption proof. */
103  CODE,
104  /** Authorization grant and revocation state. */
105  GRANT,
106  /** Issued access-token identifier and binding. */
107  ACCESS_TOKEN,
108  /** Rotating refresh credential or retained reuse proof. */
109  REFRESH_TOKEN
110 }
111}