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}