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}