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 */
016package com.revetsec.password;
017
018import com.google.errorprone.annotations.CheckReturnValue;
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.NotThreadSafe;
024
025/** Input and stored-cost ceilings applied around admitted password preparation/KDF work.
026 * These ceilings are independent of the work gate: an accepted stored memory cost above that
027 * gate's total budget is intentionally unavailable. Configure the memory ceiling at or below
028 * the gate when every accepted cost must be serviceable.
029 * @since 1.0.0 */
030@Immutable
031public final class PasswordVerificationLimits {
032    private static final int DEFAULT_MAXIMUM_STORED_FORM_CHARS = 512;
033    private static final int DEFAULT_MAXIMUM_PASSWORD_CHARS = 1_024;
034    private static final int DEFAULT_MAXIMUM_PASSWORD_UTF8_BYTES = 4_096;
035    private static final int DEFAULT_MAXIMUM_ARGON2ID_MEMORY_KIB = 131_072;
036    private static final int DEFAULT_MAXIMUM_ARGON2ID_PASSES = 6;
037    private static final int DEFAULT_MAXIMUM_ARGON2ID_LANES = 8;
038    private final int maximumStoredFormChars;
039    private final int maximumPasswordChars;
040    private final int maximumPasswordUtf8Bytes;
041    private final int maximumArgon2idMemoryKiB;
042    private final int maximumArgon2idPasses;
043    private final int maximumArgon2idLanes;
044
045    private PasswordVerificationLimits(@NonNull Builder builder) {
046        this.maximumStoredFormChars = builder.maximumStoredFormChars;
047        this.maximumPasswordChars = builder.maximumPasswordChars;
048        this.maximumPasswordUtf8Bytes = builder.maximumPasswordUtf8Bytes;
049        this.maximumArgon2idMemoryKiB = builder.maximumArgon2idMemoryKiB;
050        this.maximumArgon2idPasses = builder.maximumArgon2idPasses;
051        this.maximumArgon2idLanes = builder.maximumArgon2idLanes;
052    }
053
054    /** Conservative verification ceilings suitable for initial configuration.
055     * @return the limits
056     * @since 1.0.0 */
057    public static @NonNull PasswordVerificationLimits fromDefaults() { return new Builder().build(); }
058
059    /** Starts a builder from conservative limits.
060     * @return the builder
061     * @since 1.0.0 */
062    public static @NonNull Builder builder() { return new Builder(); }
063
064    /** Returns the stored-form length limit.
065     * @return maximum stored-form characters
066     * @since 1.0.0 */
067    public @NonNull Integer getMaximumStoredFormChars() { return maximumStoredFormChars; }
068
069    /** Returns the input length limit before normalization.
070     * @return maximum input UTF-16 code units before normalization
071     * @since 1.0.0 */
072    public @NonNull Integer getMaximumPasswordChars() { return maximumPasswordChars; }
073
074    /** Returns the password byte length limit after normalization.
075     * @return maximum normalized UTF-8 bytes
076     * @since 1.0.0 */
077    public @NonNull Integer getMaximumPasswordUtf8Bytes() { return maximumPasswordUtf8Bytes; }
078
079    /** Returns the maximum accepted Argon2id memory cost.
080     * @return maximum Argon2id verification memory in KiB
081     * @since 1.0.0 */
082    public @NonNull Integer getMaximumArgon2idMemoryKiB() { return maximumArgon2idMemoryKiB; }
083
084    /** Returns the maximum accepted Argon2id time cost.
085     * @return maximum Argon2id verification passes
086     * @since 1.0.0 */
087    public @NonNull Integer getMaximumArgon2idPasses() { return maximumArgon2idPasses; }
088
089    /** Returns the maximum accepted Argon2id parallelism.
090     * @return maximum Argon2id verification lanes
091     * @since 1.0.0 */
092    public @NonNull Integer getMaximumArgon2idLanes() { return maximumArgon2idLanes; }
093
094    /** Mutable construction helper; no cryptographic or provider work runs during construction.
095     * @since 1.0.0 */
096    @NotThreadSafe
097    @CheckReturnValue
098    public static final class Builder {
099        private int maximumStoredFormChars = DEFAULT_MAXIMUM_STORED_FORM_CHARS;
100        private int maximumPasswordChars = DEFAULT_MAXIMUM_PASSWORD_CHARS;
101        private int maximumPasswordUtf8Bytes = DEFAULT_MAXIMUM_PASSWORD_UTF8_BYTES;
102        private int maximumArgon2idMemoryKiB = DEFAULT_MAXIMUM_ARGON2ID_MEMORY_KIB;
103        private int maximumArgon2idPasses = DEFAULT_MAXIMUM_ARGON2ID_PASSES;
104        private int maximumArgon2idLanes = DEFAULT_MAXIMUM_ARGON2ID_LANES;
105
106        private Builder() { }
107
108        /** Sets the stored-form length limit.
109         * @param value maximum stored-form characters, or null to restore the default
110         * @return this builder
111         * @since 1.0.0 */
112        public @NonNull Builder maximumStoredFormChars(@Nullable Integer value) {
113            maximumStoredFormChars = value == null ? DEFAULT_MAXIMUM_STORED_FORM_CHARS : value; return this;
114        }
115
116        /** Sets the input length limit before normalization.
117         * @param value maximum input UTF-16 code units, or null to restore the default
118         * @return this builder
119         * @since 1.0.0 */
120        public @NonNull Builder maximumPasswordChars(@Nullable Integer value) {
121            maximumPasswordChars = value == null ? DEFAULT_MAXIMUM_PASSWORD_CHARS : value; return this;
122        }
123
124        /** Sets the password byte length limit after normalization.
125         * @param value maximum normalized UTF-8 bytes, or null to restore the default
126         * @return this builder
127         * @since 1.0.0 */
128        public @NonNull Builder maximumPasswordUtf8Bytes(@Nullable Integer value) {
129            maximumPasswordUtf8Bytes = value == null ? DEFAULT_MAXIMUM_PASSWORD_UTF8_BYTES : value; return this;
130        }
131
132        /** Sets the maximum accepted Argon2id memory cost.
133         * @param value maximum Argon2id verification memory in KiB, or null to restore the default
134         * @return this builder
135         * @since 1.0.0 */
136        public @NonNull Builder maximumArgon2idMemoryKiB(@Nullable Integer value) {
137            maximumArgon2idMemoryKiB = value == null ? DEFAULT_MAXIMUM_ARGON2ID_MEMORY_KIB : value; return this;
138        }
139
140        /** Sets the maximum accepted Argon2id time cost.
141         * @param value maximum Argon2id verification passes, or null to restore the default
142         * @return this builder
143         * @since 1.0.0 */
144        public @NonNull Builder maximumArgon2idPasses(@Nullable Integer value) {
145            maximumArgon2idPasses = value == null ? DEFAULT_MAXIMUM_ARGON2ID_PASSES : value; return this;
146        }
147
148        /** Sets the maximum accepted Argon2id parallelism.
149         * @param value maximum Argon2id verification lanes, or null to restore the default
150         * @return this builder
151         * @since 1.0.0 */
152        public @NonNull Builder maximumArgon2idLanes(@Nullable Integer value) {
153            maximumArgon2idLanes = value == null ? DEFAULT_MAXIMUM_ARGON2ID_LANES : value; return this;
154        }
155
156        /** Validates the ceilings without performing I/O or allocating KDF memory.
157         * @return immutable limits
158         * @since 1.0.0 */
159        public @NonNull PasswordVerificationLimits build() {
160            // A native form with a 64-character pepper key ID is at most 184 characters.
161            if (maximumStoredFormChars < 192 || maximumStoredFormChars > 4_096
162                    || maximumPasswordChars < 64 || maximumPasswordChars > 16_384
163                    || maximumPasswordUtf8Bytes < 256 || maximumPasswordUtf8Bytes > 65_536
164                    || maximumArgon2idMemoryKiB < 19_456 || maximumArgon2idMemoryKiB > 262_144
165                    || maximumArgon2idPasses < 2 || maximumArgon2idPasses > 10
166                    || maximumArgon2idLanes < 1 || maximumArgon2idLanes > 8) {
167                throw new IllegalArgumentException("Invalid password verification limits");
168            }
169            return new PasswordVerificationLimits(this);
170        }
171    }
172}