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; 024import org.jspecify.annotations.Nullable; 025 026import javax.annotation.concurrent.Immutable; 027 028/** 029 * Bounded opaque address for optional client-metadata storage. Reconstructing an address grants no 030 * authority. The core binds stable issuer/configuration and exact client identities; providers 031 * preserve the string exactly. 032 * 033 * @author <a href="https://www.revetkn.com">Mark Allen</a> 034 * @since 1.0.0 035 */ 036@Immutable 037@CheckReturnValue 038public final class OAuthClientMetadataCacheKey { 039 private static final @NonNull String PREFIX = "revetsec:cimd-cache:1:"; 040 private final @NonNull String storageKey; 041 042 private OAuthClientMetadataCacheKey(@NonNull String value) { 043 this.storageKey = value; 044 } 045 046 /** 047 * Reconstructs the current address format: fixed prefix, two canonical 32-byte base64url 048 * digests separated by a colon. This checks bounded syntax only; it does not verify namespace 049 * or record authenticity. 050 * 051 * @param value the exact persisted string 052 * @return the bounded address 053 * @throws NullPointerException if value is null 054 * @throws IllegalArgumentException if the format is invalid 055 * @since 1.0.0 056 */ 057 public static @NonNull OAuthClientMetadataCacheKey fromStoredForm(@NonNull String value) { 058 requireNonNull(value); 059 int offset = PREFIX.length(); 060 if (value.length() != offset + 87 061 || !value.startsWith(PREFIX) 062 || value.charAt(offset + 43) != ':') 063 throw new IllegalArgumentException("Invalid client metadata cache address."); 064 OAuthStoreFormat.nonce(value.substring(offset, offset + 43)); 065 OAuthStoreFormat.nonce(value.substring(offset + 44)); 066 return new OAuthClientMetadataCacheKey(value); 067 } 068 069 /** 070 * Releases the opaque storage string; keep it out of logs and responses. 071 * 072 * @return the exact address 073 * @since 1.0.0 074 */ 075 public @NonNull String getStorageKey() { 076 return this.storageKey; 077 } 078 079 /** 080 * Compares exact addresses. 081 * 082 * @param other the possible address 083 * @return whether they match 084 * @since 1.0.0 085 */ 086 @Override 087 public boolean equals(@Nullable Object other) { 088 return other instanceof OAuthClientMetadataCacheKey key 089 && this.storageKey.equals(key.storageKey); 090 } 091 092 /** 093 * Returns the address hash. 094 * 095 * @return the hash 096 * @since 1.0.0 097 */ 098 @Override 099 public int hashCode() { 100 return this.storageKey.hashCode(); 101 } 102 103 /** 104 * Redacts the address. 105 * 106 * @return a fixed description 107 * @since 1.0.0 108 */ 109 @Override 110 public @NonNull String toString() { 111 return "OAuthClientMetadataCacheKey{address=<redacted>}"; 112 } 113}