@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/auth/guard.ts

@@ -0,0 +1,285 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The UI-auth gate: one `onBeforeHandle` in front of every route.
+ *
+ * Registered on the root Elysia instance BEFORE `routes/index.ts` is mounted,
+ * which is what makes it cover the whole surface at once — REST handlers, the
+ * SSE streams, and the `.ws()` routes a domain plugin registers internally.
+ * (Verified against Elysia 1.4.30: a hook added after `.use()` never runs, and a
+ * hook added before it runs for the child's own `ws` `beforeHandle` too.)
+ *
+ * Two paths cannot be covered from here and are handled elsewhere:
+ *
+ * - `/_shell` lives in `Bun.serve`'s own routing table rather than Elysia's, so
+ *   no hook sees it. It is left reachable deliberately: it serves the page
+ *   skeleton and, measured, carries no bootstrap payload — the settings map is
+ *   injected by the SSR route, which is gated.
+ * - Static assets are exempt by necessity: the login page is the app shell, so
+ *   its bundle, stylesheet and fonts must load before any credential exists.
+ *
+ * The config is read once and cached. A password change goes through
+ * `POST /api/auth/password`, which invalidates the cache — so a change takes
+ * effect on the next request without a restart.
+ */
+
+import { hashPassword, deriveCredentialKey, readSessionSecret, writeSessionSecret, type ActiveAuthConfig } from '@/server/lib/auth/config';
+import { readSessionCookie, verifySessionToken } from '@/server/lib/auth/token';
+import { rememberClientAddress } from '@/server/lib/auth/client-address';
+import type { CredentialHandover } from '@/shared/lib/auth/handover';
+
+/**
+ * The login screen's path. One constant because three places depend on the same
+ * string agreeing: it is public (the way in), it is where an unauthenticated
+ * document request is sent, and it is where a signed-in visitor must NOT stay.
+ */
+const LOGIN_PATH = '/login';
+
+/** Paths that never require a session, because they ARE the way in. */
+const PUBLIC_EXACT = new Set([
+  '/api/health',
+  '/api/auth/state',
+  '/api/auth/login',
+  '/api/auth/logout',
+  LOGIN_PATH,
+  '/robots.txt',
+  '/sw.js',
+  '/manifest.webmanifest',
+  '/favicon.ico',
+  '/fonts.css',
+  '/_shell',
+]);
+
+/**
+ * Prefixes whose contents are the app itself: bundle, styles, fonts, icons.
+ *
+ * Each ends at a real separator — `/fonts/`, `/icon.` — rather than at a word
+ * stem. A bare `/icon` would also exempt `/icons-secret`, and a public prefix
+ * that matches more than it names is an open door that nothing reports.
+ */
+const PUBLIC_PREFIXES = [
+  '/_bun/',
+  '/_dev-assets/',
+  '/fonts/',
+  '/static/',
+  '/.well-known/',
+  // The icons are served both by their stable names (`/icon.svg`, referenced
+  // absolutely from the manifest, which Bun does not rewrite) and by the hashed
+  // names the HTML loader emits for the ones `index.html` links.
+  '/icon.',
+  '/icon-',
+  '/apple-touch-icon.',
+  '/apple-touch-icon-',
+];
+
+/** True when `pathname` is reachable without a session. */
+export function isPublicPath(pathname: string): boolean {
+  if (PUBLIC_EXACT.has(pathname)) return true;
+  for (const prefix of PUBLIC_PREFIXES) {
+    if (pathname.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * The auth state of this process, or null when authentication is off.
+ *
+ * A module-level slot, populated ONCE by `initAuth()` before the listener opens.
+ * There is nothing to re-read per request, and nothing on disk that could turn
+ * authentication on behind the operator's back — which is the whole point of the
+ * design. `initAuth` is the only writer.
+ */
+let active: ActiveAuthConfig | null = null;
+
+/**
+ * arm authentication for this process from a password supplied on the command
+ * line or in the environment. Call once, before the listener opens.
+ *
+ * Returns a description of the outcome for the boot banner. The hash is computed
+ * here and never leaves the process; only the session secret is persisted, so a
+ * restart keeps its sessions without keeping the password.
+ */
+export async function initAuth(password: string | null | undefined): Promise<string> {
+  const candidate = typeof password === 'string' ? password.trim() : '';
+  if (candidate.length === 0) {
+    active = null;
+    return 'disabled (no --ui-password or KABMO_UI_PASSWORD given)';
+  }
+
+  const existingSecret = await readSessionSecret();
+  const sessionSecret = existingSecret ?? crypto.randomUUID();
+  // Written only when it is new, so a normal restart does not touch the file.
+  if (!existingSecret) await writeSessionSecret(sessionSecret);
+
+  active = {
+    passwordHash: await hashPassword(candidate),
+    // Derived, not hashed: this is the half that has to come out the SAME on
+    // the next boot, which is what makes a restart keep its sessions.
+    credentialKey: deriveCredentialKey(candidate, sessionSecret),
+    sessionSecret,
+  };
+  return existingSecret
+    ? 'enabled (password from this run)'
+    : 'enabled (password from this run; new session secret generated)';
+}
+
+/**
+ * Arm authentication from a credential a PREVIOUS process already hashed.
+ *
+ * This is the self-restart path. The replacement is spawned by
+ * `kabmo restart`, which never had the plaintext — the server that armed
+ * the restart did, and it has already hashed it. Handing the hash over instead
+ * of the password is what keeps the plaintext from being respawned at all: a
+ * `--ui-password` given to the original run never has to exist again, and the
+ * sessions it signed stay valid because the credential key and the secret it
+ * was derived from travel together.
+ *
+ * The secret is used as given rather than re-read from disk: if the file were
+ * unreadable, reading it would mint a new secret, compute a different key, and
+ * sign every session out on a restart the user did not ask for.
+ */
+export async function initAuthFromHandover(handover: CredentialHandover): Promise<string> {
+  if (!handover.passwordHash || !handover.credentialKey || !handover.sessionSecret) {
+    return initAuth(handover.password);
+  }
+  const existingSecret = await readSessionSecret();
+  if (existingSecret !== handover.sessionSecret) await writeSessionSecret(handover.sessionSecret);
+  active = {
+    passwordHash: handover.passwordHash,
+    credentialKey: handover.credentialKey,
+    sessionSecret: handover.sessionSecret,
+  };
+  return 'enabled (credential handed over by the restarting instance)';
+}
+
+/**
+ * Replace the active password at runtime — the `POST /api/auth/password` path.
+ *
+ * The session secret is deliberately REUSED, so a password change does not sign
+ * the user out of this browser. It does revoke every OTHER session, because a
+ * token carries a fingerprint of the credential key and that just changed.
+ */
+export async function replaceActivePassword(password: string): Promise<void> {
+  const sessionSecret = active?.sessionSecret ?? (await readSessionSecret()) ?? crypto.randomUUID();
+  if (!active) await writeSessionSecret(sessionSecret);
+  active = {
+    passwordHash: await hashPassword(password),
+    credentialKey: deriveCredentialKey(password, sessionSecret),
+    sessionSecret,
+  };
+}
+
+/**
+ * Revoke every session everywhere, by rotating the signing secret.
+ *
+ * A session token is stateless — an HMAC over its expiry and a fingerprint of
+ * the password hash — so there is no list of issued tokens to walk and mark
+ * dead. Rotating the secret is what makes every existing token fail
+ * verification at once, which is the only revocation a stateless design has, and
+ * it is the stronger form: a copied cookie dies with the rest.
+ *
+ * The new secret is persisted, so the revocation survives a restart. If the
+ * write fails the rotation still applies to this process, which is the useful
+ * half — the caller is told so it can say the revocation is temporary.
+ */
+export async function revokeAllSessions(): Promise<{ revoked: boolean; persisted: boolean }> {
+  const nextSecret = crypto.randomUUID();
+  const persisted = await writeSessionSecret(nextSecret);
+  // Keep the current password hash: the user asked to end sessions, not to
+  // change their password.
+  if (active) active = { ...active, sessionSecret: nextSecret };
+  return { revoked: true, persisted };
+}
+
+/**
+ * The active config, or null when authentication is off.
+ *
+ * Synchronous by design: the value is settled before the first request, so a
+ * handler cannot observe a half-initialised state, and there is no per-request
+ * I/O to fail.
+ */
+export function loadAuthConfig(): ActiveAuthConfig | null {
+  return active;
+}
+
+/**
+ * Whether UI auth is active for this run. Read by the health endpoint and the CLI.
+ */
+export function isAuthEnabled(): boolean {
+  return active !== null;
+}
+
+/**
+ * Whether this request carries a valid session.
+ *
+ * A request with no active config is authenticated by definition — there is
+ * nothing to check it against — so callers that need to distinguish "no
+ * password required" from "valid session" must consult `isAuthEnabled()` first.
+ */
+export function isAuthenticatedRequest(request: Request): boolean {
+  if (!active) return true;
+  return verifySessionToken(readSessionCookie(request), {
+    sessionSecret: active.sessionSecret,
+    credentialKey: active.credentialKey,
+  });
+}
+
+/** JSON body for a rejected API call, or a redirect for a document request. */
+function rejectionResponse(pathname: string, wantsHtml: boolean): Response {
+  if (wantsHtml || !pathname.startsWith('/api/')) {
+    // The login screen is the shell itself, so a document request is sent there
+    // rather than answered with a body it could not render.
+    return new Response(null, { status: 302, headers: { location: LOGIN_PATH, 'cache-control': 'no-store' } });
+  }
+  return new Response(JSON.stringify({ error: 'UI authentication required', locked: true }), {
+    status: 401,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  });
+}
+
+/**
+ * The gate itself. Returns a `Response` to reject, or `undefined` to continue.
+ *
+ * `clientAddress` comes from the socket (Elysia's `server.requestIP`) and is
+ * recorded for the login route, which throttles by it. It is optional so a test
+ * can exercise the gate without a listener.
+ *
+ * Preflight is passed through: an `OPTIONS` carries no credentials by design and
+ * the routes that matter are same-origin, so rejecting it would only break
+ * browsers that probe.
+ */
+export function authGate(request: Request, clientAddress?: string): Response | undefined {
+  if (request.method === 'OPTIONS') return undefined;
+
+  rememberClientAddress(request, clientAddress);
+
+  const pathname = new URL(request.url).pathname;
+
+  // The login screen is for someone who has no session. A visitor who already
+  // has one — a bookmarked `/login`, a stale tab, a hand-typed address, or the
+  // back button after signing in — is sent to the app instead of being shown a
+  // form that would only re-authenticate what it already is.
+  //
+  // Checked BEFORE the public-path shortcut, because that shortcut is what used
+  // to let `/login` render the workspace at a URL that says otherwise. It also
+  // covers the case where authentication is off entirely, where there is
+  // nothing to log into at all.
+  if (pathname === LOGIN_PATH && isAuthenticatedRequest(request)) {
+    return new Response(null, { status: 302, headers: { location: '/', 'cache-control': 'no-store' } });
+  }
+
+  if (isPublicPath(pathname)) return undefined;
+
+  if (!active) return undefined;
+
+  const token = readSessionCookie(request);
+  if (verifySessionToken(token, { sessionSecret: active.sessionSecret, credentialKey: active.credentialKey })) {
+    return undefined;
+  }
+
+  const wantsHtml = (request.headers.get('accept') ?? '').includes('text/html');
+  return rejectionResponse(pathname, wantsHtml);
+}

package/src/server/lib/auth/handover-guard.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Arming authentication from a credential a PREVIOUS process computed.
+ *
+ * This is the self-restart path. The replacement is spawned by `kabmo
+ * restart`, which never had the plaintext — the instance being replaced did,
+ * and it has already hashed it. The property under test is that the pair
+ * `credentialKey` + `sessionSecret` travels together: without the secret the
+ * key means nothing, and a replacement that generated a fresh one would sign
+ * every session out on a restart the user did not ask for.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { authGate, initAuth, initAuthFromHandover, isAuthEnabled, loadAuthConfig } from '@/server/lib/auth/guard';
+import { issueSessionToken, SESSION_TTL_MS } from '@/server/lib/auth/token';
+
+let tempDir: string | null = null;
+
+afterEach(async () => {
+  // `initAuth(null)` is the reset: the module slot is process-wide, so a test
+  // that armed a password would otherwise leak it into the next one.
+  await initAuth(null);
+  if (tempDir) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+  delete Bun.env.KABMO_DATA_DIR;
+});
+
+function useTempDataDir(): void {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-handover-test-'));
+  Bun.env.KABMO_DATA_DIR = tempDir;
+}
+
+describe('initAuthFromHandover', () => {
+  test('a hashed credential arms auth without the plaintext', async () => {
+    useTempDataDir();
+    await initAuth('correct-horse');
+    const original = loadAuthConfig();
+    expect(original).not.toBeNull();
+
+    const notice = await initAuthFromHandover({
+      passwordHash: original!.passwordHash,
+      credentialKey: original!.credentialKey,
+      sessionSecret: original!.sessionSecret,
+    });
+    expect(notice).toContain('handed over');
+    const restored = loadAuthConfig();
+    expect(restored?.credentialKey).toBe(original!.credentialKey);
+    expect(restored?.sessionSecret).toBe(original!.sessionSecret);
+  });
+
+  test('a session issued before the handover still verifies after it', async () => {
+    useTempDataDir();
+    await initAuth('correct-horse');
+    const original = loadAuthConfig()!;
+    const token = issueSessionToken({
+      sessionSecret: original.sessionSecret,
+      credentialKey: original.credentialKey,
+      ttlMs: SESSION_TTL_MS,
+    });
+
+    await initAuthFromHandover({
+      passwordHash: original.passwordHash,
+      credentialKey: original.credentialKey,
+      sessionSecret: original.sessionSecret,
+    });
+
+    // A restart must not sign the user out: this is the property the key +
+    // secret pair exists to preserve.
+    const response = authGate(new Request('http://localhost/api/folders', {
+      headers: { cookie: `omp_session=${token}` },
+    }));
+    expect(response).toBeUndefined();
+  });
+
+  test('a payload carrying only a plaintext falls back to the normal path', async () => {
+    useTempDataDir();
+    const notice = await initAuthFromHandover({ password: 'correct-horse' });
+    expect(notice).toContain('password from this run');
+    expect(loadAuthConfig()).not.toBeNull();
+  });
+
+  test('an incomplete payload leaves authentication off rather than half-armed', async () => {
+    useTempDataDir();
+    // A hash with no key is not a credential; installing it would make every
+    // request fail in a way nothing on screen explains.
+    await initAuthFromHandover({ passwordHash: 'hash-only' });
+    expect(loadAuthConfig()).toBeNull();
+    expect(isAuthEnabled()).toBe(false);
+  });
+});

package/src/server/lib/auth/rate-limit.test.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The login attempt budget.
+ *
+ * The behaviours worth pinning are the ones a refactor would plausibly invert:
+ * a lockout that does not lift, a window that never resets, and an
+ * unidentifiable caller getting a fresh budget per request instead of sharing
+ * the small one.
+ */
+
+import { beforeEach, describe, expect, test } from 'bun:test';
+
+import { authGate } from '@/server/lib/auth/guard';
+import { clientAddressFor } from '@/server/lib/auth/client-address';
+import {
+  checkLoginRateLimit,
+  clearLoginRateLimit,
+  RATE_LIMIT_LOCKOUT_MS,
+  RATE_LIMIT_MAX_ATTEMPTS,
+  RATE_LIMIT_UNKNOWN_MAX_ATTEMPTS,
+  RATE_LIMIT_WINDOW_MS,
+  recordLoginFailure,
+  resetLoginRateLimits,
+  UNKNOWN_CLIENT_KEY,
+} from '@/server/lib/auth/rate-limit';
+
+const NOW = 1_700_000_000_000;
+
+beforeEach(() => resetLoginRateLimits());
+
+describe('login rate limit', () => {
+  test('allows attempts up to the budget, then locks the address out', () => {
+    for (let attempt = 1; attempt < RATE_LIMIT_MAX_ATTEMPTS; attempt += 1) {
+      expect(recordLoginFailure('1.2.3.4', NOW).allowed).toBe(true);
+    }
+    // The attempt that spends the budget trips the lockout and is itself refused.
+    const tripped = recordLoginFailure('1.2.3.4', NOW);
+    expect(tripped.allowed).toBe(false);
+    expect(tripped.retryAfterSec).toBe(RATE_LIMIT_LOCKOUT_MS / 1000);
+
+    const checked = checkLoginRateLimit('1.2.3.4', NOW + 1);
+    expect(checked.allowed).toBe(false);
+    expect(checked.remaining).toBe(0);
+  });
+
+  test('a locked address is refused before any verification could run', () => {
+    for (let attempt = 0; attempt < RATE_LIMIT_MAX_ATTEMPTS; attempt += 1) recordLoginFailure('1.2.3.4', NOW);
+    const status = checkLoginRateLimit('1.2.3.4', NOW + 60_000);
+    expect(status.allowed).toBe(false);
+    expect(status.retryAfterSec).toBeGreaterThan(0);
+  });
+
+  test('the lockout lifts when it expires', () => {
+    for (let attempt = 0; attempt < RATE_LIMIT_MAX_ATTEMPTS; attempt += 1) recordLoginFailure('1.2.3.4', NOW);
+    expect(checkLoginRateLimit('1.2.3.4', NOW + RATE_LIMIT_LOCKOUT_MS).allowed).toBe(true);
+    expect(checkLoginRateLimit('1.2.3.4', NOW + RATE_LIMIT_LOCKOUT_MS).remaining).toBe(RATE_LIMIT_MAX_ATTEMPTS);
+  });
+
+  test('failures spread beyond the window do not accumulate', () => {
+    for (let attempt = 0; attempt < RATE_LIMIT_MAX_ATTEMPTS - 1; attempt += 1) {
+      recordLoginFailure('1.2.3.4', NOW + attempt * (RATE_LIMIT_WINDOW_MS + 1));
+    }
+    // Each failure started a fresh window, so the address is nowhere near locked.
+    expect(checkLoginRateLimit('1.2.3.4', NOW + RATE_LIMIT_MAX_ATTEMPTS * (RATE_LIMIT_WINDOW_MS + 1)).allowed).toBe(true);
+  });
+
+  test('a successful login clears the budget', () => {
+    for (let attempt = 1; attempt < RATE_LIMIT_MAX_ATTEMPTS; attempt += 1) recordLoginFailure('1.2.3.4', NOW);
+    clearLoginRateLimit('1.2.3.4');
+    expect(checkLoginRateLimit('1.2.3.4', NOW).remaining).toBe(RATE_LIMIT_MAX_ATTEMPTS);
+  });
+
+  test('budgets are per address', () => {
+    for (let attempt = 0; attempt < RATE_LIMIT_MAX_ATTEMPTS; attempt += 1) recordLoginFailure('1.2.3.4', NOW);
+    expect(checkLoginRateLimit('1.2.3.4', NOW).allowed).toBe(false);
+    expect(checkLoginRateLimit('5.6.7.8', NOW).allowed).toBe(true);
+  });
+
+  test('an unidentifiable caller draws from the small shared budget', () => {
+    for (let attempt = 1; attempt < RATE_LIMIT_UNKNOWN_MAX_ATTEMPTS; attempt += 1) {
+      expect(recordLoginFailure(UNKNOWN_CLIENT_KEY, NOW).allowed).toBe(true);
+    }
+    expect(recordLoginFailure(UNKNOWN_CLIENT_KEY, NOW).allowed).toBe(false);
+  });
+});
+
+describe('the rate limit cannot be evaded by a forged forwarding header', () => {
+  // Verified against a live server: 8 attempts with rotating `x-forwarded-for`
+  // and `x-real-ip` values all answered 429. This pins the REASON, against the
+  // real gate rather than a stand-in: the key is the socket address the gate
+  // records, and a caller-supplied header is never consulted. If that ever
+  // changed, a caller could present a fresh identity per attempt and walk
+  // straight through the budget — invisible until exploited.
+  const loginRequest = (forwardedFor: string) => new Request('http://127.0.0.1/api/auth/login', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-forwarded-for': forwardedFor, 'x-real-ip': forwardedFor },
+  });
+
+  test('a forged forwarding header does not become the rate-limit key', async () => {
+    const request = loginRequest('10.0.0.1');
+    // The gate records the socket address it was handed…
+    await authGate(request, '127.0.0.1');
+    // …and that is what the login route throttles on, not the header.
+    expect(clientAddressFor(request)).toBe('127.0.0.1');
+    expect(clientAddressFor(request)).not.toBe('10.0.0.1');
+  });
+
+  test('rotating the header changes nothing about the key', async () => {
+    const keys = new Set<string>();
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const request = loginRequest(`10.0.0.${attempt}`);
+      await authGate(request, '127.0.0.1');
+      keys.add(clientAddressFor(request));
+    }
+    // Five different forged identities, one key.
+    expect(keys.size).toBe(1);
+    expect([...keys][0]).toBe('127.0.0.1');
+  });
+
+  test('an unidentifiable caller falls back to the shared key, not a fresh one', async () => {
+    // No address from the socket (a non-Bun adapter, a test harness). The
+    // fallback must be ONE shared key: per-request randomness would hand every
+    // attempt a new budget.
+    const first = loginRequest('10.0.0.1');
+    const second = loginRequest('10.0.0.2');
+    await authGate(first, undefined);
+    await authGate(second, undefined);
+    expect(clientAddressFor(first)).toBe(UNKNOWN_CLIENT_KEY);
+    expect(clientAddressFor(second)).toBe(UNKNOWN_CLIENT_KEY);
+  });
+});

package/src/server/lib/auth/rate-limit.ts

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Login throttling: a per-IP attempt budget in front of the password check.
+ *
+ * argon2id already makes one guess cost ~70 ms, but that only bounds the RATE of
+ * guesses — it does not stop a script from running them for a week. This bounds
+ * the NUMBER of failures instead: past the budget the address is locked out
+ * outright, and no verification runs at all.
+ *
+ * State is in-memory and therefore resets when the process restarts. That is the
+ * right trade for a single-user console: a persisted lockout would have to be
+ * cleared by hand after a restart, and the process is only reachable at all
+ * because someone chose to expose it.
+ *
+ * The key is the SOCKET address (`requestIP`), never `x-forwarded-for`: that
+ * header is caller-supplied, so trusting it would let one client present a fresh
+ * identity per attempt and walk straight through the budget. Behind a reverse
+ * proxy every client shares the proxy's socket address, which throttles them
+ * together — the conservative direction for a limit whose job is to fail closed.
+ */
+
+/** Sliding window an attempt count is measured over. */
+export const RATE_LIMIT_WINDOW_MS = 5 * 60 * 1000;
+
+/** Failures allowed within the window before the lockout. */
+export const RATE_LIMIT_MAX_ATTEMPTS = 10;
+
+/** How long a tripped lockout lasts. */
+export const RATE_LIMIT_LOCKOUT_MS = 15 * 60 * 1000;
+
+/**
+ * Budget for a request whose address could not be determined. Lower than the
+ * per-IP budget on purpose: an unidentifiable caller cannot be distinguished
+ * from any other, so the budget they share must be small.
+ */
+export const RATE_LIMIT_UNKNOWN_MAX_ATTEMPTS = 3;
+
+/** Key used when the socket address is unavailable. */
+export const UNKNOWN_CLIENT_KEY = 'unknown-client';
+
+interface AttemptRecord {
+  count: number;
+  lastAttempt: number;
+  lockedUntil: number;
+}
+
+const attempts = new Map<string, AttemptRecord>();
+
+/** Entries older than this are dropped opportunistically; see `prune`. */
+const STALE_AFTER_MS = 60 * 60 * 1000;
+
+const MAX_TRACKED_CLIENTS = 4096;
+
+function maxAttemptsFor(key: string): number {
+  return key === UNKNOWN_CLIENT_KEY ? RATE_LIMIT_UNKNOWN_MAX_ATTEMPTS : RATE_LIMIT_MAX_ATTEMPTS;
+}
+
+/**
+ * Drop records that are neither locked nor recently touched.
+ *
+ * Runs on write rather than on a timer: a module-level interval would have to be
+ * unref'd and torn down, and this map is written exactly when a login fails —
+ * which is also the only moment it can grow.
+ */
+function prune(now: number): void {
+  if (attempts.size < MAX_TRACKED_CLIENTS) return;
+  for (const [key, record] of attempts) {
+    const locked = record.lockedUntil > now;
+    if (!locked && now - record.lastAttempt > STALE_AFTER_MS) attempts.delete(key);
+  }
+}
+
+export interface RateLimitStatus {
+  allowed: boolean;
+  /** Seconds until the lockout lifts; only present when `allowed` is false. */
+  retryAfterSec?: number;
+  limit: number;
+  remaining: number;
+}
+
+/** Whether this key may attempt a login right now. Does not consume the budget. */
+export function checkLoginRateLimit(key: string, now = Date.now()): RateLimitStatus {
+  const limit = maxAttemptsFor(key);
+  const record = attempts.get(key);
+
+  if (!record) return { allowed: true, limit, remaining: limit };
+
+  if (record.lockedUntil > now) {
+    return {
+      allowed: false,
+      retryAfterSec: Math.ceil((record.lockedUntil - now) / 1000),
+      limit,
+      remaining: 0,
+    };
+  }
+
+  // A lockout that has run out, or a window that has gone quiet, both start over.
+  if (record.lockedUntil > 0 || now - record.lastAttempt > RATE_LIMIT_WINDOW_MS) {
+    attempts.delete(key);
+    return { allowed: true, limit, remaining: limit };
+  }
+
+  return { allowed: true, limit, remaining: Math.max(0, limit - record.count) };
+}
+
+/**
+ * Record a failed attempt, tripping the lockout once the budget is spent.
+ * Returns the status AFTER the failure, so the caller can answer 429 immediately.
+ */
+export function recordLoginFailure(key: string, now = Date.now()): RateLimitStatus {
+  const limit = maxAttemptsFor(key);
+  const record = attempts.get(key);
+
+  if (!record || now - record.lastAttempt > RATE_LIMIT_WINDOW_MS) {
+    attempts.set(key, { count: 1, lastAttempt: now, lockedUntil: 0 });
+    prune(now);
+    return { allowed: true, limit, remaining: limit - 1 };
+  }
+
+  const count = record.count + 1;
+  const lockedUntil = count >= limit ? now + RATE_LIMIT_LOCKOUT_MS : 0;
+  attempts.set(key, { count, lastAttempt: now, lockedUntil });
+  prune(now);
+
+  if (lockedUntil > 0) {
+    return { allowed: false, retryAfterSec: Math.ceil(RATE_LIMIT_LOCKOUT_MS / 1000), limit, remaining: 0 };
+  }
+  return { allowed: true, limit, remaining: Math.max(0, limit - count) };
+}
+
+/** Forget a key's failures — called after a successful login. */
+export function clearLoginRateLimit(key: string): void {
+  attempts.delete(key);
+}
+
+/** Drop every record. Test seam; the process otherwise keeps them for its life. */
+export function resetLoginRateLimits(): void {
+  attempts.clear();
+}