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 org.jspecify.annotations.NonNull;
019import org.jspecify.annotations.Nullable;
020
021import javax.annotation.concurrent.ThreadSafe;
022import java.util.concurrent.atomic.AtomicBoolean;
023import java.util.concurrent.locks.ReentrantLock;
024
025import static java.util.Objects.requireNonNull;
026
027/** Explicit in-memory, process-local admission for expensive password work. Share one instance
028 * across every hasher in a process; each JVM needs its own gate to bound that JVM's CPU and memory.
029 * Its temporary counters are discarded on restart and are never shared across nodes.
030 * Admission waits interruptibly for short reservation-counter updates. The gate never queues
031 * for KDF capacity or starts worker threads; exhausted capacity yields an operation result.
032 * Password preparation, hashing and application callbacks run outside the accounting lock.
033 * One permit covers normalization/encoding, pepper lookup and KDF cleanup; it is not released
034 * between those phases. Input length caps do not guarantee a normalization wall-time bound.
035 * Applications separately own shared per-account/edge attempt admission and durable credential storage.
036 * @since 1.0.0 */
037@ThreadSafe
038public final class PasswordWorkGate {
039    private final int maximumConcurrentCalls;
040    private final int maximumMemoryKiB;
041    private final @NonNull ReentrantLock lock = new ReentrantLock();
042    private int activeCalls;
043    private int reservedMemoryKiB;
044
045    private PasswordWorkGate(int maximumConcurrentCalls, int maximumMemoryKiB) {
046        this.maximumConcurrentCalls = maximumConcurrentCalls;
047        this.maximumMemoryKiB = maximumMemoryKiB;
048    }
049
050    /** Creates a bounded in-memory work gate for one JVM. Reuse the returned instance across all
051     * hashers in that JVM. Separate calls create independent gates; this factory supplies no
052     * default concurrency or memory budget and performs no distributed attempt throttling.
053     * @param maximumConcurrentCalls maximum simultaneous password operations, from 1 through 256
054     * @param maximumMemoryKiB aggregate Argon2id memory reservation in KiB, from 19,456 through 4,194,304
055     * @return the gate
056     * @throws IllegalArgumentException if either limit is outside its supported range
057     * @since 1.0.0 */
058    public static @NonNull PasswordWorkGate fromInMemoryLimits(@NonNull Integer maximumConcurrentCalls,
059            @NonNull Integer maximumMemoryKiB) {
060        requireNonNull(maximumConcurrentCalls);
061        requireNonNull(maximumMemoryKiB);
062        if (maximumConcurrentCalls < 1 || maximumConcurrentCalls > 256
063                || maximumMemoryKiB < 19_456 || maximumMemoryKiB > 4_194_304) {
064            throw new IllegalArgumentException("Invalid password work limits");
065        }
066        return new PasswordWorkGate(maximumConcurrentCalls, maximumMemoryKiB);
067    }
068
069    /** Returns the concurrency limit for admitted password operations.
070     * @return the maximum simultaneous password operations
071     * @since 1.0.0 */
072    public @NonNull Integer getMaximumConcurrentCalls() { return maximumConcurrentCalls; }
073
074    /** Returns the shared memory reservation limit.
075     * @return the aggregate Argon2id memory reservation in KiB
076     * @since 1.0.0 */
077    public @NonNull Integer getMaximumMemoryKiB() { return maximumMemoryKiB; }
078
079    @Nullable Permit tryAcquire(int memoryKiB) {
080        try {
081            lock.lockInterruptibly();
082        } catch (InterruptedException e) {
083            Thread.currentThread().interrupt();
084            return null;
085        }
086        try {
087            if (memoryKiB < 0 || memoryKiB > maximumMemoryKiB || activeCalls >= maximumConcurrentCalls
088                    || reservedMemoryKiB > maximumMemoryKiB - memoryKiB) return null;
089            activeCalls++;
090            reservedMemoryKiB += memoryKiB;
091            return new Permit(this, memoryKiB);
092        } finally {
093            lock.unlock();
094        }
095    }
096
097    private void release(int memoryKiB) {
098        lock.lock();
099        try {
100            activeCalls--;
101            reservedMemoryKiB -= memoryKiB;
102        } finally {
103            lock.unlock();
104        }
105    }
106
107    @ThreadSafe
108    static final class Permit implements AutoCloseable {
109        private final @NonNull PasswordWorkGate gate;
110        private final int memoryKiB;
111        private final @NonNull AtomicBoolean closed = new AtomicBoolean();
112
113        private Permit(@NonNull PasswordWorkGate gate, int memoryKiB) {
114            this.gate = gate;
115            this.memoryKiB = memoryKiB;
116        }
117
118        @Override public void close() {
119            if (closed.compareAndSet(false, true)) gate.release(memoryKiB);
120        }
121    }
122}