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}