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.webauthn; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import org.jspecify.annotations.NonNull; 021import org.jspecify.annotations.Nullable; 022 023import javax.annotation.concurrent.Immutable; 024import javax.annotation.concurrent.NotThreadSafe; 025import java.time.Duration; 026 027/** Bounded parser, ceremony and store-operation settings for a WebAuthn relying party. 028 * Values are application-selected, while Revetsec enforces the protocol bounds. 029 * @since 1.0.0 */ 030@Immutable 031public final class WebAuthnSettings { 032 private static final int DEFAULT_BODY = 64 * 1_024; 033 private static final int DEFAULT_CLIENT_DATA = 8 * 1_024; 034 private static final int DEFAULT_ATTESTATION = 16 * 1_024; 035 private static final int DEFAULT_AUTHENTICATOR_DATA = 8 * 1_024; 036 private static final int DEFAULT_EXCLUSIONS = 64; 037 private static final @NonNull Duration DEFAULT_LIFETIME = Duration.ofMinutes(5); 038 private static final @NonNull Duration DEFAULT_TIMEOUT = Duration.ofSeconds(5); 039 040 private final int maximumResponseBodyBytes; 041 private final int maximumClientDataJsonBytes; 042 private final int maximumAttestationObjectBytes; 043 private final int maximumAuthenticatorDataBytes; 044 private final int maximumExcludedCredentials; 045 private final @NonNull Duration ceremonyLifetime; 046 private final @NonNull Duration operationTimeout; 047 048 private WebAuthnSettings(@NonNull Builder builder) { 049 this.maximumResponseBodyBytes = builder.maximumResponseBodyBytes; 050 this.maximumClientDataJsonBytes = builder.maximumClientDataJsonBytes; 051 this.maximumAttestationObjectBytes = builder.maximumAttestationObjectBytes; 052 this.maximumAuthenticatorDataBytes = builder.maximumAuthenticatorDataBytes; 053 this.maximumExcludedCredentials = builder.maximumExcludedCredentials; 054 this.ceremonyLifetime = builder.ceremonyLifetime; 055 this.operationTimeout = builder.operationTimeout; 056 } 057 058 /** Starts a settings builder with the selected profile defaults. 059 * @return builder 060 * @since 1.0.0 */ 061 @CheckReturnValue public static @NonNull Builder builder() { return new Builder(); } 062 /** Returns the raw completion body limit. 063 * @return maximum raw completion body bytes 064 * @since 1.0.0 */ 065 public @NonNull Integer getMaximumResponseBodyBytes() { return this.maximumResponseBodyBytes; } 066 /** Returns the decoded client data limit. 067 * @return maximum decoded clientDataJSON bytes 068 * @since 1.0.0 */ 069 public @NonNull Integer getMaximumClientDataJsonBytes() { return this.maximumClientDataJsonBytes; } 070 /** Returns the decoded attestation object limit. 071 * @return maximum decoded attestationObject bytes 072 * @since 1.0.0 */ 073 public @NonNull Integer getMaximumAttestationObjectBytes() { return this.maximumAttestationObjectBytes; } 074 /** Returns the decoded authenticator data limit. 075 * @return maximum decoded authenticatorData bytes 076 * @since 1.0.0 */ 077 public @NonNull Integer getMaximumAuthenticatorDataBytes() { return this.maximumAuthenticatorDataBytes; } 078 /** Returns the active credential exclusion limit. 079 * @return maximum active credential IDs admitted before enrollment is refused 080 * @since 1.0.0 */ 081 public @NonNull Integer getMaximumExcludedCredentials() { return this.maximumExcludedCredentials; } 082 /** Returns the validity duration of a ceremony. 083 * @return ceremony validity duration 084 * @since 1.0.0 */ 085 public @NonNull Duration getCeremonyLifetime() { return this.ceremonyLifetime; } 086 /** Returns the caller-thread operation budget. 087 * @return caller-thread operation budget 088 * @since 1.0.0 */ 089 public @NonNull Duration getOperationTimeout() { return this.operationTimeout; } 090 /** Redacts configuration details. 091 * @return fixed description 092 * @since 1.0.0 */ 093 @Override public @NonNull String toString() { return "WebAuthnSettings{<redacted>}"; } 094 095 /** One caller-thread settings builder. Passing null to a setter restores its default. 096 * @since 1.0.0 */ 097 @NotThreadSafe @CheckReturnValue public static final class Builder { 098 private int maximumResponseBodyBytes = DEFAULT_BODY; 099 private int maximumClientDataJsonBytes = DEFAULT_CLIENT_DATA; 100 private int maximumAttestationObjectBytes = DEFAULT_ATTESTATION; 101 private int maximumAuthenticatorDataBytes = DEFAULT_AUTHENTICATOR_DATA; 102 private int maximumExcludedCredentials = DEFAULT_EXCLUSIONS; 103 private @NonNull Duration ceremonyLifetime = DEFAULT_LIFETIME; 104 private @NonNull Duration operationTimeout = DEFAULT_TIMEOUT; 105 private Builder() { } 106 107 /** Sets the raw completion body limit. 108 * @param value byte limit, 1 through 262144, or null for default 109 * @return this builder 110 * @since 1.0.0 */ 111 public @NonNull Builder maximumResponseBodyBytes(@Nullable Integer value) { 112 this.maximumResponseBodyBytes = bounded(value, DEFAULT_BODY, 1, 256 * 1_024); 113 return this; 114 } 115 /** Sets the decoded client data limit. 116 * @param value byte limit, 1 through 16384, or null for default 117 * @return this builder 118 * @since 1.0.0 */ 119 public @NonNull Builder maximumClientDataJsonBytes(@Nullable Integer value) { 120 this.maximumClientDataJsonBytes = bounded(value, DEFAULT_CLIENT_DATA, 1, 16 * 1_024); 121 return this; 122 } 123 /** Sets the decoded attestation object limit. 124 * @param value byte limit, 1 through 65536, or null for default 125 * @return this builder 126 * @since 1.0.0 */ 127 public @NonNull Builder maximumAttestationObjectBytes(@Nullable Integer value) { 128 this.maximumAttestationObjectBytes = bounded(value, DEFAULT_ATTESTATION, 1, 64 * 1_024); 129 return this; 130 } 131 /** Sets the decoded authenticator data limit. 132 * @param value byte limit, 37 through 32768, or null for default 133 * @return this builder 134 * @since 1.0.0 */ 135 public @NonNull Builder maximumAuthenticatorDataBytes(@Nullable Integer value) { 136 this.maximumAuthenticatorDataBytes = bounded(value, DEFAULT_AUTHENTICATOR_DATA, 37, 32 * 1_024); 137 return this; 138 } 139 /** Sets the active credential exclusion limit. 140 * @param value enrollment exclusion limit, 1 through 64, or null for default 141 * @return this builder 142 * @since 1.0.0 */ 143 public @NonNull Builder maximumExcludedCredentials(@Nullable Integer value) { 144 this.maximumExcludedCredentials = bounded(value, DEFAULT_EXCLUSIONS, 1, 64); 145 return this; 146 } 147 /** Sets the ceremony validity duration. 148 * @param value 30 seconds through 10 minutes, or null for default 149 * @return this builder 150 * @since 1.0.0 */ 151 public @NonNull Builder ceremonyLifetime(@Nullable Duration value) { 152 this.ceremonyLifetime = bounded(value, DEFAULT_LIFETIME, 153 Duration.ofSeconds(30), Duration.ofMinutes(10)); 154 return this; 155 } 156 /** Sets the caller-thread operation budget. 157 * @param value one second through 30 seconds, or null for default 158 * @return this builder 159 * @since 1.0.0 */ 160 public @NonNull Builder operationTimeout(@Nullable Duration value) { 161 this.operationTimeout = bounded(value, DEFAULT_TIMEOUT, 162 Duration.ofSeconds(1), Duration.ofSeconds(30)); 163 return this; 164 } 165 /** Builds a stable settings snapshot. 166 * @return immutable settings 167 * @since 1.0.0 */ 168 @CheckReturnValue public @NonNull WebAuthnSettings build() { return new WebAuthnSettings(this); } 169 /** @return fixed description 170 * @since 1.0.0 */ 171 @Override public @NonNull String toString() { return "WebAuthnSettings.Builder{<redacted>}"; } 172 } 173 174 private static int bounded(@Nullable Integer value, int defaultValue, int minimum, int maximum) { 175 if (value == null) return defaultValue; 176 if (value < minimum || value > maximum) throw new IllegalArgumentException("Invalid WebAuthn limit"); 177 return value; 178 } 179 180 private static @NonNull Duration bounded(@Nullable Duration value, @NonNull Duration defaultValue, 181 @NonNull Duration minimum, @NonNull Duration maximum) { 182 if (value == null) return defaultValue; 183 if (value.compareTo(minimum) < 0 || value.compareTo(maximum) > 0) 184 throw new IllegalArgumentException("Invalid WebAuthn duration"); 185 return value; 186 } 187}