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}