aicodeman 1.44.0 → 1.46.0

package/dist/web/agent-inbox.js

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Agent inbox: a per-session mailbox other agents (or the user) post to,
+ * and the receiving agent reads when it chooses to.
+ *
+ * The other agent-to-agent channel, `POST /api/sessions/:id/input`, types into the
+ * receiver's composer. That is right for a prompt and wrong for a message: every
+ * delivery starts or interrupts a turn, the receiver cannot defer it, and it is one
+ * line only. The inbox stores instead of typing. Nothing here ever reaches a pane.
+ *
+ * Invariants (each pinned in `test/agent-inbox.test.ts`):
+ * - **Read until ack.** A read hands out every pending message and removes nothing.
+ *   A message goes only when the receiver acknowledges its id. "Read and dropped"
+ *   and "done" must not look the same to the sender (discussion #558, the 09-23 case).
+ * - **Seen is the receiver's alone.** `read(…, { receiver: true })` marks what it
+ *   handed out as seen; any other read is a peek and changes nothing. The route
+ *   decides who the receiver is; this module only takes the flag.
+ * - **Bounded, and full refuses.** `MAX_MESSAGES_PER_INBOX`, `MAX_MESSAGE_BYTES` and
+ *   `MAX_INBOX_BYTES`. A post that would cross any of them is refused so the sender
+ *   learns. The oldest message is never dropped to make room.
+ * - **TTL from the message's own timestamp** (`MESSAGE_TTL_MS`). A restore keeps
+ *   `createdAt`, so a restart does not restart the clock. Expiry is lazy: every
+ *   accessor sweeps the inbox it touches, `summary()` and `snapshot()` sweep all.
+ * - **No IO, no `Session` import.** Persistence (`agent-inbox-persistence.ts`) hooks
+ *   `onChange`; long-poll waiters live in `session-wait-registry.ts`.
+ *
+ * @consumedby web/routes/inbox-routes, web/agent-inbox-persistence, web/server
+ * @module web/agent-inbox
+ */
+import { randomUUID } from 'node:crypto';
+// ─── Bounds ──────────────────────────────────────────────────────────────────
+/** Messages one inbox holds before posts are refused. */
+export const MAX_MESSAGES_PER_INBOX = 200;
+/** UTF-8 bytes per message. A bigger payload belongs in the workspace; post its path. */
+export const MAX_MESSAGE_BYTES = 16_384;
+/** UTF-8 bytes of message text one inbox holds before posts are refused. */
+export const MAX_INBOX_BYTES = 512 * 1024;
+/** A message older than this is gone, read or not (same span as the approvals inbox). */
+export const MESSAGE_TTL_MS = 12 * 60 * 60 * 1000;
+// ─── Store ───────────────────────────────────────────────────────────────────
+export class AgentInbox {
+    now;
+    inboxes = new Map();
+    /** Any mutation (post, seen, ack, expiry, drop, prune, restore excluded). Persistence hooks this. */
+    onChange;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /**
+     * Store a message for `sessionId`. `from` is the RESOLVED sender (the route's job),
+     * never a client-supplied label.
+     */
+    post(sessionId, from, text) {
+        if (text.length === 0)
+            return { ok: false, reason: 'empty' };
+        const bytes = Buffer.byteLength(text, 'utf8');
+        if (bytes > MAX_MESSAGE_BYTES)
+            return { ok: false, reason: 'message-too-large' };
+        const queue = this.live(sessionId);
+        if (queue.length >= MAX_MESSAGES_PER_INBOX)
+            return { ok: false, reason: 'inbox-full-count' };
+        if (inboxBytes(queue) + bytes > MAX_INBOX_BYTES)
+            return { ok: false, reason: 'inbox-full-bytes' };
+        const stored = { id: randomUUID(), from, text, createdAt: this.now(), seenAt: null };
+        queue.push(stored);
+        this.inboxes.set(sessionId, queue);
+        this.onChange?.();
+        return { ok: true, message: view(stored), pending: queue.length, unseen: countUnseen(queue) };
+    }
+    /**
+     * Every pending message, oldest first. Removes nothing. With `receiver`, the
+     * messages handed out are marked seen (each keeps its first `seenAt`); without it
+     * this is a peek and changes nothing at all.
+     */
+    read(sessionId, options) {
+        const queue = this.live(sessionId);
+        const messages = queue.map(view);
+        if (options.receiver) {
+            let marked = false;
+            const at = this.now();
+            for (const m of queue) {
+                if (m.seenAt !== null)
+                    continue;
+                m.seenAt = at;
+                marked = true;
+            }
+            if (marked)
+                this.onChange?.();
+        }
+        return { messages, pending: queue.length, unseen: countUnseen(queue) };
+    }
+    /** Messages no receiver read has handed out yet. A `?wait=` read parks while this is 0. */
+    unseenCount(sessionId) {
+        return countUnseen(this.live(sessionId));
+    }
+    pendingCount(sessionId) {
+        return this.live(sessionId).length;
+    }
+    /**
+     * Remove the given messages. Idempotent: an id that is unknown or already gone is
+     * not an error, so a retry after a lost response succeeds. Returns how many went.
+     */
+    ack(sessionId, ids) {
+        const queue = this.live(sessionId);
+        if (queue.length === 0 || ids.length === 0)
+            return 0;
+        const drop = new Set(ids);
+        const kept = queue.filter((m) => !drop.has(m.id));
+        const removed = queue.length - kept.length;
+        if (removed === 0)
+            return 0;
+        this.store(sessionId, kept);
+        this.onChange?.();
+        return removed;
+    }
+    /** Per-session counts for every inbox that holds anything. Never blocks. */
+    summary() {
+        const out = new Map();
+        for (const sessionId of [...this.inboxes.keys()]) {
+            const queue = this.live(sessionId);
+            if (queue.length === 0)
+                continue;
+            const unseen = queue.filter((m) => m.seenAt === null);
+            out.set(sessionId, {
+                pending: queue.length,
+                unseen: unseen.length,
+                oldestUnseenAt: unseen.length > 0 ? unseen[0].createdAt : null,
+            });
+        }
+        return out;
+    }
+    /** The session was DELETED: its mail goes with it. Not called on detach or shutdown. */
+    drop(sessionId) {
+        if (this.inboxes.delete(sessionId))
+            this.onChange?.();
+    }
+    /**
+     * Boot-time sweep, run only after the session restore succeeded: discard inboxes
+     * whose session did not come back. Every route needs a live session, so an orphan
+     * could otherwise never be removed. Returns how many inboxes were dropped.
+     */
+    pruneExcept(keep) {
+        const alive = new Set(keep);
+        let dropped = 0;
+        for (const sessionId of [...this.inboxes.keys()]) {
+            if (alive.has(sessionId))
+                continue;
+            this.inboxes.delete(sessionId);
+            dropped++;
+        }
+        if (dropped > 0)
+            this.onChange?.();
+        return dropped;
+    }
+    /** Whole-store snapshot for persistence, expired messages already swept. */
+    snapshot() {
+        const inboxes = {};
+        for (const sessionId of [...this.inboxes.keys()]) {
+            const queue = this.live(sessionId);
+            if (queue.length > 0)
+                inboxes[sessionId] = queue.map((m) => ({ ...m }));
+        }
+        return { version: 1, inboxes };
+    }
+    /**
+     * Replace the store from a snapshot (server boot). Malformed input is skipped entry
+     * by entry rather than thrown: a corrupt file must not stop the server. Expired
+     * messages are not restored, and the caps hold for what is. Does not fire
+     * `onChange`: writing back what was just read would be a no-op at best.
+     */
+    restore(snapshot) {
+        const data = snapshot;
+        this.inboxes.clear();
+        if (!data || data.version !== 1 || typeof data.inboxes !== 'object' || data.inboxes === null)
+            return 0;
+        const cutoff = this.now() - MESSAGE_TTL_MS;
+        let restored = 0;
+        for (const [sessionId, raw] of Object.entries(data.inboxes)) {
+            if (!Array.isArray(raw))
+                continue;
+            const queue = [];
+            let bytes = 0;
+            // Oldest first whatever order the file has, so the caps keep the oldest mail,
+            // which is the rule for posts too.
+            const entries = raw
+                .filter((entry) => isStoredMessage(entry) && entry.createdAt > cutoff)
+                .sort((a, b) => a.createdAt - b.createdAt);
+            for (const entry of entries) {
+                const size = Buffer.byteLength(entry.text, 'utf8');
+                if (queue.length >= MAX_MESSAGES_PER_INBOX || bytes + size > MAX_INBOX_BYTES)
+                    break;
+                queue.push({ ...entry });
+                bytes += size;
+            }
+            if (queue.length === 0)
+                continue;
+            this.inboxes.set(sessionId, queue);
+            restored += queue.length;
+        }
+        return restored;
+    }
+    /** Test hook: back to an empty store with no listener. */
+    resetForTests() {
+        this.inboxes.clear();
+        this.onChange = undefined;
+    }
+    /** The inbox with expired messages swept out (fires `onChange` when it swept any). */
+    live(sessionId) {
+        const queue = this.inboxes.get(sessionId);
+        if (!queue)
+            return [];
+        const cutoff = this.now() - MESSAGE_TTL_MS;
+        // Every message, not only queue[0]: a clock stepping back can put an older
+        // createdAt behind a newer one. At most 200 entries, so the scan is cheap.
+        if (!queue.some((m) => m.createdAt <= cutoff))
+            return queue;
+        const kept = queue.filter((m) => m.createdAt > cutoff);
+        this.store(sessionId, kept);
+        this.onChange?.();
+        return kept;
+    }
+    store(sessionId, queue) {
+        if (queue.length === 0)
+            this.inboxes.delete(sessionId);
+        else
+            this.inboxes.set(sessionId, queue);
+    }
+}
+function view(m) {
+    return { id: m.id, from: m.from, text: m.text, createdAt: m.createdAt, seen: m.seenAt !== null };
+}
+function countUnseen(queue) {
+    let n = 0;
+    for (const m of queue)
+        if (m.seenAt === null)
+            n++;
+    return n;
+}
+function inboxBytes(queue) {
+    let total = 0;
+    for (const m of queue)
+        total += Buffer.byteLength(m.text, 'utf8');
+    return total;
+}
+function isStoredMessage(value) {
+    const m = value;
+    return (!!m &&
+        typeof m.id === 'string' &&
+        (m.from === null || typeof m.from === 'string') &&
+        typeof m.text === 'string' &&
+        m.text.length > 0 &&
+        Buffer.byteLength(m.text, 'utf8') <= MAX_MESSAGE_BYTES &&
+        typeof m.createdAt === 'number' &&
+        Number.isFinite(m.createdAt) &&
+        (m.seenAt === null || typeof m.seenAt === 'number'));
+}
+/** Process-wide store used by the routes and the server wiring. Tests construct their own. */
+export const agentInbox = new AgentInbox();
+//# sourceMappingURL=agent-inbox.js.map

package/dist/web/agent-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-inbox.js","sourceRoot":"","sources":["../../src/web/agent-inbox.ts"],"names":[],"mappings":"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"}

package/dist/web/middleware/auth.d.ts

@@ -26,6 +26,8 @@ interface AuthState {
     hookSecretFailures: StaleExpirationMap<string, number> | null;
     /** Per-username Basic-auth failure bucket (multi-user only). */
     userFailures: StaleExpirationMap<string, number> | null;
+    /** Per-(username, client IP) Basic-auth failure bucket (multi-user only). */
+    userIpFailures: StaleExpirationMap<string, number> | null;
 }
 /**
  * The landing-page case of serveLostWebviewFrame, for the index route. Without

package/dist/web/middleware/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/web/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAgD,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAoB1G,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAIlF,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;KACrB;CACF;AAGD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,8EAA8E;AAC9E,UAAU,SAAS;IACjB,YAAY,EAAE,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,IAAI,CAAC;IACnE,YAAY,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACxD,cAAc,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1D,kBAAkB,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9D,gEAAgE;IAChE,YAAY,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CACzD;AAwLD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAInE;AAED,uFAAuF;AACvF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAI1E;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,SAAS,CAoKrG;AA8KD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,EAAE,QAAQ,SAAK,GAAG,IAAI,CAuBxG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,IAAI,CAwEjG"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/web/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAgD,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAqB1G,OAAO,EAAqC,KAAK,QAAQ,EAAmB,MAAM,gBAAgB,CAAC;AAInG,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;KACrB;CACF;AAGD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,8EAA8E;AAC9E,UAAU,SAAS;IACjB,YAAY,EAAE,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,IAAI,CAAC;IACnE,YAAY,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACxD,cAAc,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1D,kBAAkB,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9D,gEAAgE;IAChE,YAAY,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACxD,6EAA6E;IAC7E,cAAc,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC3D;AAwMD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAInE;AAED,uFAAuF;AACvF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAI1E;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,SAAS,CAyLrG;AAgQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,EAAE,QAAQ,SAAK,GAAG,IAAI,CAuBxG;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,IAAI,CAwEjG"}

package/dist/web/middleware/auth.js

@@ -7,10 +7,10 @@
  * - Security headers (CSP, X-Frame-Options, HSTS)
  * - CORS (localhost only)
  */
-import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { StaleExpirationMap } from '../../utils/index.js';
 import { isAllowedRequestHost, isAllowedRequestOrigin } from '../network-auth-policy.js';
-import { AUTH_SESSION_TTL_MS, MAX_AUTH_SESSIONS, AUTH_FAILURE_MAX, AUTH_FAILURE_WINDOW_MS, } from '../../config/auth-config.js';
+import { AUTH_SESSION_TTL_MS, MAX_AUTH_SESSIONS, AUTH_FAILURE_MAX, AUTH_IP_FAILURE_MAX, AUTH_FAILURE_WINDOW_MS, } from '../../config/auth-config.js';
 import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { findUser, setPassword, touchLastLogin, verifyPassword } from '../../user-store.js';
@@ -42,6 +42,18 @@ function parseBasicAuth(header) {
         return null;
     }
 }
+/**
+ * Key of the multi-user in-flight verify map: a SHA-256 digest of (client IP,
+ * normalized username, password), so the plaintext password is never held as a key.
+ * The JSON array keeps the three parts unambiguous for any strings (a NUL-joined
+ * string is not, since a username may carry a NUL). Never logged or persisted, and
+ * gone from the map once its verify settles.
+ */
+function verifyFlightKey(clientIp, normUser, password) {
+    return createHash('sha256')
+        .update(JSON.stringify([clientIp, normUser, password]))
+        .digest('hex');
+}
 /**
  * The `/api/hook-event` + `/api/status-telemetry` localhost bypass, shared by the
  * single-user and multi-user auth hooks so the security-critical logic has ONE
@@ -266,6 +278,7 @@ export function registerAuthMiddleware(app, https, basePath = '') {
         qrAuthFailures: null,
         hookSecretFailures: null,
         userFailures: null,
+        userIpFailures: null,
     };
     // Always declare req.authUser so downstream reads are safe (single-user leaves it
     // undefined; the ownership helpers then default to a synthetic admin).
@@ -306,13 +319,24 @@ export function registerAuthMiddleware(app, https, basePath = '') {
     const authFailures = state.authFailures;
     const hookSecretFailures = state.hookSecretFailures;
     if (multiUser) {
-        // Per-username failure bucket: a botnet can't brute-force one account across
-        // many IPs, and one user behind a NAT can't lock out everyone else.
+        // Per-username failure bucket: failed guesses against one account answer 429
+        // from any IP once it fills, and one user behind a NAT can't lock out everyone
+        // else. Checked after the verify, so it never denies a correct password.
         state.userFailures = new StaleExpirationMap({
             ttlMs: AUTH_FAILURE_WINDOW_MS,
             refreshOnGet: false,
         });
-        registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, state.userFailures, basePath);
+        // Per-(username, IP) failure bucket: checked BEFORE the verify, so it is what
+        // caps verified guesses against one account from one source. Keyed on the pair,
+        // so other IPs can't lock the account out and two users behind one shared IP
+        // don't lock each other out. Same decay as the other buckets: it holds one key
+        // per (IP, username) pair whose verify failed or is still in flight, swept by
+        // the same TTL, so like them it grows only with scrypt verifies.
+        state.userIpFailures = new StaleExpirationMap({
+            ttlMs: AUTH_FAILURE_WINDOW_MS,
+            refreshOnGet: false,
+        });
+        registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, state.userFailures, state.userIpFailures, basePath);
         return state;
     }
     // ── Single-user Basic Auth (unchanged behavior; CODEMAN_PASSWORD required) ──
@@ -408,10 +432,11 @@ export function registerAuthMiddleware(app, https, basePath = '') {
 /**
  * Multi-user auth hook (async, because password verification runs scrypt). Verifies
  * `username:password` against the user store, mints an identity-carrying cookie,
- * decorates `req.authUser`, enforces the per-IP + per-username rate limits, and the
- * `mustChangePassword` lockbox. The single-user hook above is left untouched.
+ * decorates `req.authUser`, enforces the per-IP, per-(username, IP) and per-username
+ * rate limits, and the `mustChangePassword` lockbox. Identical logins in flight at once
+ * share one verify. The single-user hook above is left untouched.
  */
-function registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, userFailures, basePath = '') {
+function registerMultiUserAuthHook(app, https, authSessions, authFailures, hookSecretFailures, userFailures, userIpFailures, basePath = '') {
     const setSessionCookie = (reply, token) => reply.setCookie(AUTH_COOKIE_NAME, token, {
         httpOnly: true,
         secure: https,
@@ -447,6 +472,63 @@ function registerMultiUserAuthHook(app, https, authSessions, authFailures, hookS
         }
         return false;
     };
+    // Basic verifies in flight, by verifyFlightKey(). A request whose identical
+    // credentials from the same IP are already being verified awaits that verify
+    // instead of starting its own. Each entry is removed when its verify settles, so the
+    // map never holds more than the distinct verifies in flight.
+    const verifiesInFlight = new Map();
+    // The verify plus its once-only side effects, run by the first request for a key.
+    // A success clears the three buckets and records the login; a failure is counted
+    // here once (the per-IP and pair buckets already hold it: the caller reserved them).
+    const verifyOnce = async (username, password, normUser, clientIp, pairKey) => {
+        const result = await verifyPassword(username, password);
+        if (result) {
+            const { user, needsRehash: rehash } = result;
+            if (rehash)
+                void setPassword(user.username, password).catch(() => { });
+            void touchLastLogin(user.username).catch(() => { });
+            authFailures.delete(clientIp);
+            userFailures.delete(normUser);
+            userIpFailures.delete(pairKey);
+            return { user };
+        }
+        // Failed guess: only the per-username bucket counts it here. Once that bucket
+        // reaches the cap, further FAILED attempts get 429 from any IP, but this path is
+        // only reached on a wrong password, so it can never deny a correct one. Its count
+        // is re-read after the await, so concurrent failures against one account each add one.
+        const uFail = (userFailures.get(normUser) ?? 0) + 1;
+        userFailures.set(normUser, uFail);
+        return { user: null, limited: uFail >= AUTH_FAILURE_MAX };
+    };
+    // Answer one request from a shared outcome. Every successful request, joiners
+    // included, gets its own cookie session under the usual capacity rules.
+    const sendBasicOutcome = (req, reply, outcome, normUser) => {
+        if (outcome.user) {
+            const { user } = outcome;
+            const token = randomBytes(32).toString('hex');
+            if (authSessions.size >= MAX_AUTH_SESSIONS)
+                evictForCapacity(user.username);
+            authSessions.set(token, {
+                ip: req.ip,
+                ua: req.headers['user-agent'] ?? '',
+                createdAt: Date.now(),
+                method: 'basic',
+                username: user.username,
+                role: user.role,
+                mustChangePassword: !!user.mustChangePassword,
+            });
+            req.authUser = { username: user.username, role: user.role };
+            setSessionCookie(reply, token);
+            enforcePasswordChange(req, reply, !!user.mustChangePassword);
+            return;
+        }
+        if (outcome.limited) {
+            sendAuthRateLimit(reply, userFailures, normUser);
+            return;
+        }
+        reply.header('WWW-Authenticate', 'Basic realm="Codeman"');
+        reply.code(401).send('Unauthorized');
+    };
     app.addHook('onRequest', async (req, reply) => {
         const bypass = checkHookSecretBypass(req, reply, hookSecretFailures);
         if (bypass === 'bypass' || bypass === 'rejected')
@@ -502,59 +584,70 @@ function registerMultiUserAuthHook(app, https, authSessions, authFailures, hookS
             enforcePasswordChange(req, reply, !!live.mustChangePassword);
             return;
         }
-        // 2. Basic Auth against the user store (scrypt verify).
-        // Per-IP pre-gate bounds scrypt CPU cost from one source (does NOT gate on the
-        // per-username bucket here; see below).
+        // 2. Basic Auth against the user store (scrypt verify). Three failure buckets:
+        //  - per IP (AUTH_IP_FAILURE_MAX), checked first: bounds scrypt CPU cost from one
+        //    source. It refuses even a correct password, so it is wider than
+        //    AUTH_FAILURE_MAX: behind a shared egress IP (NAT, a tunnel) a narrow cap
+        //    would let a few wrong guesses lock everyone out.
+        //  - per (username, IP) (AUTH_FAILURE_MAX), checked BEFORE the verify: caps
+        //    verified guesses against one account from one source. Only that IP is
+        //    refused for that account; the same account from another IP still logs in.
+        //  - per username (AUTH_FAILURE_MAX), checked AFTER the verify; see below.
+        // Neither pre-verify refusal is counted, since nothing was verified (and counting
+        // a locked pair's retries would fill the shared per-IP bucket for everyone).
+        // A request that passes both gates RESERVES its slot in both buckets before the
+        // scrypt await, as if it had already failed. Counting only after the verify let a
+        // concurrent burst pass the gates on the same stale read: 29 wrong guesses plus the
+        // right password, all in flight at once from one IP, logged in. A success deletes
+        // the reservation with the rest of the buckets; a failure is not counted again.
+        // A request whose IDENTICAL credentials from the same IP are already being verified
+        // joins that verify instead: it skips both gates, takes no slot, runs no scrypt and
+        // gets the same outcome, since it adds no guess and no CPU. Reserving for each of
+        // them refused a correct password with the slots that password itself had filled,
+        // which is every reload after a restart: cookie sessions live in memory, so the
+        // browser replays its cached Basic header on many parallel requests at once. A
+        // request with no verify in flight for its credentials is gated as normal.
+        const creds = parseBasicAuth(req.headers.authorization);
+        const normUser = creds ? creds.username.trim().toLowerCase() : '';
+        const flightKey = creds ? verifyFlightKey(clientIp, normUser, creds.password) : '';
+        const shared = creds ? verifiesInFlight.get(flightKey) : undefined;
+        if (shared) {
+            sendBasicOutcome(req, reply, await shared, normUser);
+            return;
+        }
         const ipFail = authFailures.get(clientIp) ?? 0;
-        if (ipFail >= AUTH_FAILURE_MAX) {
+        if (ipFail >= AUTH_IP_FAILURE_MAX) {
             sendAuthRateLimit(reply, authFailures, clientIp);
             return;
         }
-        const creds = parseBasicAuth(req.headers.authorization);
         if (creds) {
-            const normUser = creds.username.trim().toLowerCase();
-            // Security: VERIFY FIRST, then throttle only FAILED attempts. Consulting the
-            // per-username bucket before verifying let throwaway IPs lock out a known account
-            // (incl. admin) even with the correct password. A correct password must always
-            // win and self-heal both buckets, regardless of the username-failure count.
-            const result = await verifyPassword(creds.username, creds.password);
-            if (result) {
-                const { user, needsRehash: rehash } = result;
-                if (rehash)
-                    void setPassword(user.username, creds.password).catch(() => { });
-                void touchLastLogin(user.username).catch(() => { });
-                authFailures.delete(clientIp);
-                userFailures.delete(normUser);
-                const token = randomBytes(32).toString('hex');
-                if (authSessions.size >= MAX_AUTH_SESSIONS)
-                    evictForCapacity(user.username);
-                authSessions.set(token, {
-                    ip: clientIp,
-                    ua: req.headers['user-agent'] ?? '',
-                    createdAt: Date.now(),
-                    method: 'basic',
-                    username: user.username,
-                    role: user.role,
-                    mustChangePassword: !!user.mustChangePassword,
-                });
-                req.authUser = { username: user.username, role: user.role };
-                setSessionCookie(reply, token);
-                enforcePasswordChange(req, reply, !!user.mustChangePassword);
+            // IPs never contain a newline, so this key is unambiguous for any username.
+            const pairKey = `${clientIp}\n${normUser}`;
+            const pairFail = userIpFailures.get(pairKey) ?? 0;
+            if (pairFail >= AUTH_FAILURE_MAX) {
+                sendAuthRateLimit(reply, userIpFailures, pairKey);
                 return;
             }
-            // Failed guess: count it against BOTH buckets. Once the per-username bucket
-            // reaches the cap, further FAILED attempts get 429 (throttles distributed
-            // brute-force), but this path is only reached on a wrong password, so it can
-            // never deny a correct one.
-            const uFail = (userFailures.get(normUser) ?? 0) + 1;
-            userFailures.set(normUser, uFail);
+            // Reserve both slots and publish this verify for joiners, from the values the
+            // gates just read. Correct only while nothing between those reads and these
+            // writes awaits: keep it that way.
             authFailures.set(clientIp, ipFail + 1);
-            if (uFail >= AUTH_FAILURE_MAX) {
-                sendAuthRateLimit(reply, userFailures, normUser);
-                return;
+            userIpFailures.set(pairKey, pairFail + 1);
+            // Security: the per-username bucket is consulted only AFTER the verify, and only
+            // FAILED attempts are throttled by it. Consulting it before verifying let
+            // throwaway IPs lock out a known account (incl. admin) even with the correct
+            // password. A correct password that passes the two gates above always wins and
+            // self-heals the per-IP, per-username and this pair's buckets.
+            const verify = verifyOnce(creds.username, creds.password, normUser, clientIp, pairKey);
+            verifiesInFlight.set(flightKey, verify);
+            let outcome;
+            try {
+                outcome = await verify;
+            }
+            finally {
+                verifiesInFlight.delete(flightKey);
             }
-            reply.header('WWW-Authenticate', 'Basic realm="Codeman"');
-            reply.code(401).send('Unauthorized');
+            sendBasicOutcome(req, reply, outcome, normUser);
             return;
         }
         // No credentials presented: count against the per-IP bucket and challenge.