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;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import com.revetsec.internal.crypto.EntropySource;
021import org.jspecify.annotations.NonNull;
022
023import javax.annotation.concurrent.ThreadSafe;
024import java.util.Arrays;
025import java.util.Base64;
026
027import static java.util.Objects.requireNonNull;
028
029/**
030 * Bounded application-held correlation secret for browser pending workflows.
031 * <p>
032 * This value is not an authenticated browser, user, session, permission or recovery admission. A value restored
033 * from trusted persistence retains only its exact spelling; syntactic validity does not establish randomness,
034 * provenance or ownership. Untrusted request input must remain an untrusted comparison candidate and must not be
035 * passed to {@link #fromTrustedPersistence(String)} merely to obtain this type.
036 * <p>
037 * The restoration ceiling is 65,536 Java UTF-16 code units. Individual protocols and stores retain every narrower
038 * rule, including strict UTF-8 where already required. The broad carrier deliberately preserves unmatched-surrogate
039 * spellings used by retained SAML pending state; it does not normalize text.
040 *
041 * @author <a href="https://www.revetkn.com">Mark Allen</a>
042 * @since 1.0.0
043 */
044@ThreadSafe
045public final class BrowserBinding {
046    /**
047     * Maximum restored Java UTF-16 code units.
048     *
049     * @since 1.0.0
050     */
051    public static final @NonNull Integer MAXIMUM_CODE_UNITS = 65_536;
052
053    private final @NonNull String value;
054
055    private BrowserBinding(@NonNull String value) { this.value = value; }
056
057    /**
058     * Generates a fresh 32-byte application correlation secret in canonical unpadded Base64URL form.
059     *
060     * @return a fresh 43-character binding
061     * @since 1.0.0
062     */
063    @CheckReturnValue
064    public static @NonNull BrowserBinding fresh() {
065        byte[] bytes = EntropySource.fromDefaults().nextBytes(32);
066        try {
067            return new BrowserBinding(Base64.getUrlEncoder().withoutPadding().encodeToString(bytes));
068        } finally {
069            Arrays.fill(bytes, (byte) 0);
070        }
071    }
072
073    /**
074     * Restores the exact value from application-controlled trusted persistence.
075     * This is not a parser for cookies, form fields, query parameters or other request input.
076     *
077     * @param value exact persisted correlation secret
078     * @return the bounded exact value
079     * @throws IllegalArgumentException if empty or longer than 65,536 Java UTF-16 code units
080     * @since 1.0.0
081     */
082    @CheckReturnValue
083    public static @NonNull BrowserBinding fromTrustedPersistence(@NonNull String value) {
084        requireNonNull(value);
085        if (value.isEmpty() || value.length() > MAXIMUM_CODE_UNITS)
086            throw new IllegalArgumentException("Invalid browser binding");
087        return new BrowserBinding(value);
088    }
089
090    /**
091     * Emits the correlation secret for protected persistence, an affected Revetsec operation or exact comparison.
092     * Never log, diagnose or expose this value to a browser response.
093     *
094     * @return the exact secret spelling
095     * @since 1.0.0
096     */
097    public @NonNull String toSecretString() { return this.value; }
098
099    /** @return a fixed redacted description */
100    @Override public @NonNull String toString() { return "BrowserBinding{<redacted>}"; }
101}