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 com.revetsec.internal.encoding.StrictUtf8;
022import org.jspecify.annotations.NonNull;
023
024import javax.annotation.concurrent.ThreadSafe;
025import java.util.Arrays;
026import java.util.Base64;
027
028import static java.util.Objects.requireNonNull;
029
030/**
031 * Bounded application-held correlation secret for selected WebAuthn and TOTP operations.
032 * <p>
033 * The binding is not identity, permission, freshness, uniqueness or a one-use authorization grant. Applications
034 * still authorize the current session/action and atomically consume their own pending state. WebAuthn retains its
035 * canonical 43-character boundary; TOTP retains its historical nonempty, well-formed 1,024-code-unit boundary.
036 *
037 * @author <a href="https://www.revetkn.com">Mark Allen</a>
038 * @since 1.0.0
039 */
040@ThreadSafe
041public final class OperationBinding {
042    /**
043     * Maximum trusted-persistence spelling retained for the TOTP compatibility profile.
044     *
045     * @since 1.0.0
046     */
047    public static final @NonNull Integer MAXIMUM_CODE_UNITS = 1_024;
048
049    private final @NonNull String value;
050
051    private OperationBinding(@NonNull String value) { this.value = value; }
052
053    /**
054     * Generates a fresh 32-byte correlation secret in canonical unpadded Base64URL form.
055     *
056     * @return a fresh 43-character binding
057     * @since 1.0.0
058     */
059    @CheckReturnValue
060    public static @NonNull OperationBinding fresh() {
061        byte[] bytes = EntropySource.fromDefaults().nextBytes(32);
062        try {
063            return new OperationBinding(Base64.getUrlEncoder().withoutPadding().encodeToString(bytes));
064        } finally {
065            Arrays.fill(bytes, (byte) 0);
066        }
067    }
068
069    /**
070     * Restores an exact TOTP-compatible value from application-controlled trusted persistence.
071     * This is not a parser for untrusted browser or request input.
072     *
073     * @param value exact persisted correlation secret
074     * @return the bounded exact value
075     * @throws IllegalArgumentException if empty, longer than 1,024 Java UTF-16 code units or not well-formed UTF-16
076     * @since 1.0.0
077     */
078    @CheckReturnValue
079    public static @NonNull OperationBinding fromTrustedPersistence(@NonNull String value) {
080        requireNonNull(value);
081        if (value.isEmpty() || value.length() > MAXIMUM_CODE_UNITS || !StrictUtf8.isWellFormed(value))
082            throw new IllegalArgumentException("Invalid operation binding");
083        return new OperationBinding(value);
084    }
085
086    /**
087     * Emits the correlation secret for protected persistence, an affected Revetsec operation or exact comparison.
088     * Never log, diagnose or expose this value to a browser response.
089     *
090     * @return the exact secret spelling
091     * @since 1.0.0
092     */
093    public @NonNull String toSecretString() { return this.value; }
094
095    /** @return a fixed redacted description */
096    @Override public @NonNull String toString() { return "OperationBinding{<redacted>}"; }
097}