cursedbelt-server 1.0.0

package/dist/server/auth/jwt.d.ts

@@ -0,0 +1,18 @@
+import { type JWTPayload } from 'jose';
+import type { AppJwtPayload } from './types';
+/**
+ * Sign an HS256 token. `expiresIn` is a jose duration string (`'15m'`, `'24h'`) or a
+ * number of seconds-from-now. `iat`/`exp` are set automatically — pass everything
+ * else (`userId`, `sessionId`, `roles`, `getOnly`, optional `purpose`).
+ */
+export declare function signToken(payload: Omit<AppJwtPayload, 'iat' | 'exp'>, secret: string, expiresIn: string | number): Promise<string>;
+/** Verify signature + claims and return the decoded payload (throws on bad
+ * signature / expiry / malformed). */
+export declare function verifyToken<T extends JWTPayload = AppJwtPayload>(token: string, secret: string): Promise<T>;
+/**
+ * Verify a single-purpose token (vault/private-media/files/yt-oauth) AND assert its
+ * `purpose` claim matches — so an access token (or a token for a *different*
+ * feature) can never be replayed as, say, a vault-unlock token. Throws on a bad
+ * signature, expiry, or a purpose mismatch.
+ */
+export declare function verifyPurposeToken<T extends AppJwtPayload = AppJwtPayload>(token: string, secret: string, purpose: string): Promise<T>;

package/dist/server/auth/jwt.js

@@ -0,0 +1,56 @@
+import { jwtVerify, SignJWT } from 'jose';
+/**
+ * JWT sign/verify on `jose` (Web Crypto HMAC — native on Bun + Node, no native
+ * deps; replaces `jsonwebtoken`). Every token system in the apps — the access
+ * token plus the short-lived vault/private-media/files/yt-oauth unlock tokens —
+ * goes through these, so there is exactly ONE jose integration to reason about.
+ *
+ * jose verifies any standard HS256 JWT regardless of which library signed it, so a
+ * token previously minted by `jsonwebtoken` validates here unchanged — that is the
+ * whole cutover guarantee (no dual-verify shim or `jsonwebtoken` dependency is
+ * carried into this from-scratch toolkit). A pre-`getOnly` token simply has no
+ * `getOnly` claim; the auth middleware reads it as `false`.
+ *
+ * NOTE: Web Crypto HMAC is async, so these are async (jsonwebtoken was sync — every
+ * caller becomes async/await).
+ */
+const keyOf = (secret) => new TextEncoder().encode(secret);
+/**
+ * Normalize jose's expiration input. jose treats a bare **number** as an absolute
+ * UNIX timestamp (seconds) — so `3600` would mean "1970" and expire instantly. We
+ * treat a number as RELATIVE seconds-from-now (the obviously-intended meaning) by
+ * handing jose a `"<n>s"` duration; a string (`'15m'`, `'24h'`) passes through as a
+ * jose duration unchanged.
+ */
+const asDuration = (expiresIn) => typeof expiresIn === 'number' ? `${expiresIn}s` : expiresIn;
+/**
+ * Sign an HS256 token. `expiresIn` is a jose duration string (`'15m'`, `'24h'`) or a
+ * number of seconds-from-now. `iat`/`exp` are set automatically — pass everything
+ * else (`userId`, `sessionId`, `roles`, `getOnly`, optional `purpose`).
+ */
+export async function signToken(payload, secret, expiresIn) {
+    return new SignJWT(payload)
+        .setProtectedHeader({ alg: 'HS256' })
+        .setIssuedAt()
+        .setExpirationTime(asDuration(expiresIn))
+        .sign(keyOf(secret));
+}
+/** Verify signature + claims and return the decoded payload (throws on bad
+ * signature / expiry / malformed). */
+export async function verifyToken(token, secret) {
+    const { payload } = await jwtVerify(token, keyOf(secret));
+    return payload;
+}
+/**
+ * Verify a single-purpose token (vault/private-media/files/yt-oauth) AND assert its
+ * `purpose` claim matches — so an access token (or a token for a *different*
+ * feature) can never be replayed as, say, a vault-unlock token. Throws on a bad
+ * signature, expiry, or a purpose mismatch.
+ */
+export async function verifyPurposeToken(token, secret, purpose) {
+    const payload = await verifyToken(token, secret);
+    if (payload.purpose !== purpose) {
+        throw new Error(`token purpose mismatch: expected '${purpose}', got '${payload.purpose}'`);
+    }
+    return payload;
+}

package/dist/server/auth/loginThrottle.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Failed-login backoff for every password door in the fleet — cc's `guard` mixin and
+ * the satellites' own auth stacks alike.
+ *
+ * ── Why this shape (consolidated 2026-08-02) ────────────────────────────────
+ * There were two of these. This file used to hold a fixed-window lockout (N failures
+ * in a window → locked for M minutes); `cursed-satellites` grew a second, better one
+ * in `satellite-kit` because at the time `cursed-core` was treated as read-only from
+ * there. That precedent is repealed, so the EVOLVED implementation lands here and the
+ * satellites import it back. Everything below that reads like over-engineering is a
+ * lesson the fixed-window version had already lost.
+ *
+ * ── The trust model, which is the whole design ───────────────────────────────
+ * A client-supplied `X-Forwarded-For` is forgeable, so per-IP limiting alone is
+ * defeated by rotating the header. Two things follow, and both are deliberate:
+ *
+ * 1. **The IP is read from the LAST hop, not the first.** Behind nginx,
+ *    `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for` APPENDS the socket
+ *    peer to whatever the client sent. The final entry is therefore the address our
+ *    own proxy observed; the first is whatever the client typed. Reading the first is
+ *    the classic version of this bug.
+ * 2. **The GLOBAL counter is the actual defense.** For a single-principal door
+ *    ("somebody is failing a lot" is enough to slow everybody down) it cannot be
+ *    evaded by rotating a header at all. Per-IP limiting is the courtesy layer that
+ *    keeps one noisy client from being the reason the legitimate user waits.
+ *
+ * ── The lockout-vs-DoS trade, stated plainly ─────────────────────────────────
+ * A global lock means an attacker can make a legitimate user wait. That is why the
+ * global ceiling is 60s while the per-IP ceiling is 15 minutes: a minute of delay per
+ * attempt reduces a distributed brute force to a rounding error against argon2id, and
+ * never locks someone out of their own dashboard for a quarter of an hour. A
+ * successful sign-in clears both counters.
+ *
+ * ── Exponential, not fixed-window ───────────────────────────────────────────
+ * Delay is `base·2^(n-1)` past the threshold rather than a flat lockout, so an honest
+ * typo costs a second and a scripted run costs progressively everything. A quiet
+ * window forgives: someone who mistyped twice last week starts fresh.
+ *
+ * ── Why in-memory, and why bounded ──────────────────────────────────────────
+ * The state is per-process and does not survive a restart. That is acceptable: an
+ * attacker cannot cause a restart, and the only thing that does — a deploy — is
+ * operator-initiated and rare. What is NOT acceptable is an unbounded map keyed by
+ * attacker-controlled input, so the table has a hard key cap and evicts the
+ * least-recently-seen entry when full. The cap is a real limit, not a comment: the
+ * global counter keeps working after eviction, which is precisely the case where it
+ * matters most.
+ *
+ * Pair with the coarse per-IP `createRateLimiter` (`../middleware/rateLimit`); this is
+ * the strict per-identity layer.
+ */
+export interface LoginThrottleOptions {
+    /** Injected clock, so backoff is testable without waiting. */
+    now?: () => number;
+    /**
+     * Failures that incur NO delay. Default 5.
+     *
+     * Read it precisely: with `threshold: 5`, failures 1–5 are answered 401 with no
+     * lock, failure 6 is ALSO answered 401 and is the one that arms the first delay, so
+     * attempt 7 is the first refusal. The extra attempt is deliberate — the alternative
+     * (lock on the Nth failure itself) means a 429 whose cause the user cannot
+     * distinguish from a wrong password.
+     */
+    threshold?: number;
+    /** First delay after the threshold, doubling per further failure. Default 1s. */
+    baseDelayMs?: number;
+    /** Ceiling on the per-key delay. Default 15 minutes. */
+    maxDelayMs?: number;
+    /** Free failures, across ALL clients, before everyone is delayed. Default 20. */
+    globalThreshold?: number;
+    /** Ceiling on the global delay — deliberately lower; see the header. Default 60s. */
+    globalMaxDelayMs?: number;
+    /** A key with no failures for this long is forgotten. Default 1 hour. */
+    windowMs?: number;
+    /** Hard cap on tracked keys, so the table cannot be a memory vector. Default 4096. */
+    maxKeys?: number;
+}
+export type ThrottleVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterSeconds: number;
+    scope: 'ip' | 'global';
+};
+export interface LoginThrottle {
+    /** May this key attempt a login right now? */
+    check(key: string): ThrottleVerdict;
+    /** Record a failed attempt. Returns the verdict the NEXT attempt would get. */
+    recordFailure(key: string): ThrottleVerdict;
+    /** Record a success — clears this key and the global counter. */
+    recordSuccess(key: string): void;
+    /** Clear one key without touching the global counter (admin unlock, verified reset). */
+    reset(key: string): void;
+    /** Tracked-key count, for the bounded-growth test. */
+    readonly size: number;
+}
+/**
+ * The client address to key on — the LAST `X-Forwarded-For` entry (what our proxy
+ * saw), falling back to `X-Real-IP`, the socket peer, and finally a shared constant.
+ *
+ * The fallback deliberately collapses to ONE key rather than inventing a unique one
+ * per request. A per-request key would make every attempt look like a first attempt
+ * from a new client, i.e. it would silently disable the per-IP layer. Collapsing means
+ * an unidentifiable client shares a budget with every other unidentifiable client,
+ * which is the conservative direction.
+ */
+export declare function clientKeyOf(req: Request, socketAddress?: string | null): string;
+/**
+ * The same, from inside a Hono handler.
+ *
+ * Under Bun, Hono's `env` IS the `Server` (the second argument to `app.fetch`), and
+ * `Server.requestIP(req)` is the only source of the real socket peer. Every step is
+ * defensive because that plumbing is the least stable thing here: `env` is `undefined`
+ * under `app.request()` in tests, and a future adapter could pass something else
+ * entirely. A missing address is not an error — `clientKeyOf` falls back to the
+ * headers, which is what production actually uses behind nginx.
+ */
+export declare function clientKeyOfContext(req: Request, env: unknown): string;
+export declare function createLoginThrottle(options?: LoginThrottleOptions): LoginThrottle;

package/dist/server/auth/loginThrottle.js

@@ -0,0 +1,204 @@
+/**
+ * Failed-login backoff for every password door in the fleet — cc's `guard` mixin and
+ * the satellites' own auth stacks alike.
+ *
+ * ── Why this shape (consolidated 2026-08-02) ────────────────────────────────
+ * There were two of these. This file used to hold a fixed-window lockout (N failures
+ * in a window → locked for M minutes); `cursed-satellites` grew a second, better one
+ * in `satellite-kit` because at the time `cursed-core` was treated as read-only from
+ * there. That precedent is repealed, so the EVOLVED implementation lands here and the
+ * satellites import it back. Everything below that reads like over-engineering is a
+ * lesson the fixed-window version had already lost.
+ *
+ * ── The trust model, which is the whole design ───────────────────────────────
+ * A client-supplied `X-Forwarded-For` is forgeable, so per-IP limiting alone is
+ * defeated by rotating the header. Two things follow, and both are deliberate:
+ *
+ * 1. **The IP is read from the LAST hop, not the first.** Behind nginx,
+ *    `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for` APPENDS the socket
+ *    peer to whatever the client sent. The final entry is therefore the address our
+ *    own proxy observed; the first is whatever the client typed. Reading the first is
+ *    the classic version of this bug.
+ * 2. **The GLOBAL counter is the actual defense.** For a single-principal door
+ *    ("somebody is failing a lot" is enough to slow everybody down) it cannot be
+ *    evaded by rotating a header at all. Per-IP limiting is the courtesy layer that
+ *    keeps one noisy client from being the reason the legitimate user waits.
+ *
+ * ── The lockout-vs-DoS trade, stated plainly ─────────────────────────────────
+ * A global lock means an attacker can make a legitimate user wait. That is why the
+ * global ceiling is 60s while the per-IP ceiling is 15 minutes: a minute of delay per
+ * attempt reduces a distributed brute force to a rounding error against argon2id, and
+ * never locks someone out of their own dashboard for a quarter of an hour. A
+ * successful sign-in clears both counters.
+ *
+ * ── Exponential, not fixed-window ───────────────────────────────────────────
+ * Delay is `base·2^(n-1)` past the threshold rather than a flat lockout, so an honest
+ * typo costs a second and a scripted run costs progressively everything. A quiet
+ * window forgives: someone who mistyped twice last week starts fresh.
+ *
+ * ── Why in-memory, and why bounded ──────────────────────────────────────────
+ * The state is per-process and does not survive a restart. That is acceptable: an
+ * attacker cannot cause a restart, and the only thing that does — a deploy — is
+ * operator-initiated and rare. What is NOT acceptable is an unbounded map keyed by
+ * attacker-controlled input, so the table has a hard key cap and evicts the
+ * least-recently-seen entry when full. The cap is a real limit, not a comment: the
+ * global counter keeps working after eviction, which is precisely the case where it
+ * matters most.
+ *
+ * Pair with the coarse per-IP `createRateLimiter` (`../middleware/rateLimit`); this is
+ * the strict per-identity layer.
+ */
+/**
+ * The client address to key on — the LAST `X-Forwarded-For` entry (what our proxy
+ * saw), falling back to `X-Real-IP`, the socket peer, and finally a shared constant.
+ *
+ * The fallback deliberately collapses to ONE key rather than inventing a unique one
+ * per request. A per-request key would make every attempt look like a first attempt
+ * from a new client, i.e. it would silently disable the per-IP layer. Collapsing means
+ * an unidentifiable client shares a budget with every other unidentifiable client,
+ * which is the conservative direction.
+ */
+export function clientKeyOf(req, socketAddress) {
+    const forwarded = req.headers.get('x-forwarded-for');
+    if (forwarded) {
+        const hops = forwarded
+            .split(',')
+            .map((h) => h.trim())
+            .filter((h) => h.length > 0);
+        // LAST, not first — see the header.
+        const observed = hops[hops.length - 1];
+        if (observed)
+            return observed;
+    }
+    const real = req.headers.get('x-real-ip')?.trim();
+    if (real)
+        return real;
+    return socketAddress?.trim() || 'unknown';
+}
+/**
+ * The same, from inside a Hono handler.
+ *
+ * Under Bun, Hono's `env` IS the `Server` (the second argument to `app.fetch`), and
+ * `Server.requestIP(req)` is the only source of the real socket peer. Every step is
+ * defensive because that plumbing is the least stable thing here: `env` is `undefined`
+ * under `app.request()` in tests, and a future adapter could pass something else
+ * entirely. A missing address is not an error — `clientKeyOf` falls back to the
+ * headers, which is what production actually uses behind nginx.
+ */
+export function clientKeyOfContext(req, env) {
+    let address = null;
+    const requestIP = env?.requestIP;
+    if (typeof requestIP === 'function') {
+        try {
+            address = requestIP.call(env, req)?.address ?? null;
+        }
+        catch {
+            address = null;
+        }
+    }
+    return clientKeyOf(req, address);
+}
+/**
+ * Keys are compared case- and whitespace-insensitively.
+ *
+ * This is NOT cosmetic, and it is the one behavior the satellites' version had lost:
+ * the recommended key is `"<email>:<ip>"`, and an email address is case-insensitive,
+ * so without this `Victim@example.com` and `victim@example.com` are separate budgets
+ * and an attacker evades the per-account layer by varying the case of a letter. The
+ * global counter still caught that, but only after 20 free guesses per attacker.
+ */
+const normalizeKey = (key) => key.trim().toLowerCase();
+export function createLoginThrottle(options = {}) {
+    const now = options.now ?? Date.now;
+    const threshold = options.threshold ?? 5;
+    const baseDelayMs = options.baseDelayMs ?? 1_000;
+    const maxDelayMs = options.maxDelayMs ?? 15 * 60_000;
+    const globalThreshold = options.globalThreshold ?? 20;
+    const globalMaxDelayMs = options.globalMaxDelayMs ?? 60_000;
+    const windowMs = options.windowMs ?? 60 * 60_000;
+    const maxKeys = options.maxKeys ?? 4096;
+    const attempts = new Map();
+    const global = { failures: 0, lockedUntil: 0, lastSeen: 0 };
+    /** Delay for the nth failure past a threshold: base·2^(n-1), capped. */
+    const delayFor = (failures, limit, cap) => {
+        const past = failures - limit;
+        if (past <= 0)
+            return 0;
+        // `Math.min` before the shift would still overflow for large `past`; clamp the
+        // exponent instead so a client that keeps hammering cannot reach Infinity.
+        const exponent = Math.min(past - 1, 32);
+        return Math.min(baseDelayMs * 2 ** exponent, cap);
+    };
+    /** Drop stale entries; then, if still over the cap, evict least-recently-seen. */
+    const prune = (nowMs) => {
+        for (const [key, entry] of attempts) {
+            if (nowMs - entry.lastSeen > windowMs && entry.lockedUntil <= nowMs)
+                attempts.delete(key);
+        }
+        if (attempts.size <= maxKeys)
+            return;
+        const byAge = [...attempts.entries()].sort((a, b) => a[1].lastSeen - b[1].lastSeen);
+        for (const [key] of byAge.slice(0, attempts.size - maxKeys))
+            attempts.delete(key);
+    };
+    const verdict = (rawKey, nowMs) => {
+        const key = normalizeKey(rawKey);
+        // Global first: it is the layer that cannot be evaded by rotating a header, so it
+        // should also be the one that decides.
+        if (global.lockedUntil > nowMs) {
+            return {
+                allowed: false,
+                scope: 'global',
+                retryAfterSeconds: Math.ceil((global.lockedUntil - nowMs) / 1000),
+            };
+        }
+        const entry = attempts.get(key);
+        if (entry && entry.lockedUntil > nowMs) {
+            return {
+                allowed: false,
+                scope: 'ip',
+                retryAfterSeconds: Math.ceil((entry.lockedUntil - nowMs) / 1000),
+            };
+        }
+        return { allowed: true };
+    };
+    return {
+        check(key) {
+            return verdict(key, now());
+        },
+        recordFailure(rawKey) {
+            const key = normalizeKey(rawKey);
+            const nowMs = now();
+            const entry = attempts.get(key) ?? { failures: 0, lockedUntil: 0, lastSeen: nowMs };
+            // A quiet window forgives: someone who mistyped twice last week starts fresh,
+            // while a run of failures keeps compounding.
+            if (nowMs - entry.lastSeen > windowMs)
+                entry.failures = 0;
+            entry.failures += 1;
+            entry.lastSeen = nowMs;
+            entry.lockedUntil = nowMs + delayFor(entry.failures, threshold, maxDelayMs);
+            attempts.set(key, entry);
+            if (nowMs - global.lastSeen > windowMs)
+                global.failures = 0;
+            global.failures += 1;
+            global.lastSeen = nowMs;
+            global.lockedUntil = nowMs + delayFor(global.failures, globalThreshold, globalMaxDelayMs);
+            prune(nowMs);
+            return verdict(key, nowMs);
+        },
+        recordSuccess(rawKey) {
+            attempts.delete(normalizeKey(rawKey));
+            // The user got in, so whatever the global counter was reacting to is over.
+            // Leaving it armed would punish the legitimate user for the attack.
+            global.failures = 0;
+            global.lockedUntil = 0;
+            global.lastSeen = now();
+        },
+        reset(rawKey) {
+            attempts.delete(normalizeKey(rawKey));
+        },
+        get size() {
+            return attempts.size;
+        },
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { MiddlewareHandler } from 'hono';
+import type { AuthEnv, SessionStore } from './types';
+/**
+ * The composed auth middleware. Reads the httpOnly `access_token` cookie, verifies
+ * the JWT, checks the session is live (present, not revoked, inside its sliding
+ * window), and sets the normalized {@link AuthUser} on `c.get('user')` (plus
+ * `userId` for request-log attribution). Every failure maps to a 401 in the
+ * canonical error envelope.
+ *
+ * Deliberately minimal: it does NOT slide/re-issue the token — that (and the
+ * `/f`-vs-`/login` policy) is app business (task 32). Mount {@link
+ * ./getOnly.getOnlyEnforcement} AFTER this to add the GET-only gate.
+ */
+export declare function createAuthMiddleware(sessionStore: SessionStore, jwtSecret: string): MiddlewareHandler<AuthEnv>;

package/dist/server/auth/middleware.js

@@ -0,0 +1,47 @@
+import { ApiError, toErrorEnvelope } from '../errors';
+import { readAuthCookie } from './cookie';
+import { verifyToken } from './jwt';
+/**
+ * The composed auth middleware. Reads the httpOnly `access_token` cookie, verifies
+ * the JWT, checks the session is live (present, not revoked, inside its sliding
+ * window), and sets the normalized {@link AuthUser} on `c.get('user')` (plus
+ * `userId` for request-log attribution). Every failure maps to a 401 in the
+ * canonical error envelope.
+ *
+ * Deliberately minimal: it does NOT slide/re-issue the token — that (and the
+ * `/f`-vs-`/login` policy) is app business (task 32). Mount {@link
+ * ./getOnly.getOnlyEnforcement} AFTER this to add the GET-only gate.
+ */
+export function createAuthMiddleware(sessionStore, jwtSecret) {
+    return async (c, next) => {
+        const token = readAuthCookie(c);
+        if (!token) {
+            return c.json(toErrorEnvelope(new ApiError(401, 'Unauthorized')), 401);
+        }
+        let payload;
+        try {
+            payload = await verifyToken(token, jwtSecret);
+        }
+        catch {
+            return c.json(toErrorEnvelope(new ApiError(401, 'Invalid token')), 401);
+        }
+        const session = sessionStore.get(payload.sessionId);
+        if (!session || session.disabled) {
+            return c.json(toErrorEnvelope(new ApiError(401, 'Session revoked')), 401);
+        }
+        if (new Date(session.refreshExpiresAt) < new Date()) {
+            return c.json(toErrorEnvelope(new ApiError(401, 'Session expired')), 401);
+        }
+        const user = {
+            id: payload.userId,
+            roles: payload.roles ?? [],
+            // A token minted before the claim existed has no `getOnly` → treat as false,
+            // preserving access for pre-existing cookies.
+            getOnly: payload.getOnly ?? false,
+            sessionId: payload.sessionId,
+        };
+        c.set('user', user);
+        c.set('userId', user.id);
+        await next();
+    };
+}

package/dist/server/auth/password.d.ts

@@ -0,0 +1,14 @@
+/** Mint an argon2id password hash. Returns the self-describing PHC string. */
+export declare function hashPassword(plain: string): Promise<string>;
+/**
+ * Verify a candidate against a stored hash, handling BOTH formats: an argon2id PHC
+ * string (new) via `Bun.password.verify`; a legacy `"<salt>:<pbkdf2-hex>"` digest by
+ * re-deriving PBKDF2-SHA512 with the stored salt and comparing in constant time.
+ */
+export declare function verifyPassword(plain: string, stored: string): Promise<boolean>;
+/**
+ * True when a stored hash is a legacy (non-argon2id) digest and should be upgraded.
+ * Call AFTER a successful {@link verifyPassword} to opportunistically re-hash with
+ * argon2id — never block auth on the upgrade.
+ */
+export declare function needsRehash(stored: string): boolean;

package/dist/server/auth/password.js

@@ -0,0 +1,65 @@
+import { pbkdf2 as pbkdf2Cb, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+/**
+ * Password hashing on `Bun.password` (argon2id — memory-hard, thread-pooled, zero
+ * deps, the current OWASP default). The argon2id hash is self-describing
+ * (`$argon2id$v=19$m=…$<salt>$<hash>`) so there is NO separate salt column — the new
+ * schema stores just the hash string.
+ *
+ * Legacy upgrade path: the old app used PBKDF2-SHA512 @ 1000 iterations with a
+ * separate salt; the ETL (task 43) brings those forward as a combined `"<salt>:<hex>"`
+ * string in the password column (it can't re-hash — it lacks the plaintext).
+ * {@link verifyPassword} transparently verifies BOTH shapes; on a legacy match the
+ * caller re-hashes with argon2id ({@link needsRehash}) — a silent per-login upgrade,
+ * no forced reset.
+ */
+// Legacy PBKDF2-SHA512 parameters — used ONLY to verify pre-argon2id hashes; never
+// to mint new ones. (1000 iterations is far below modern guidance — exactly why we
+// moved off it.)
+const LEGACY_ITERATIONS = 1000;
+const LEGACY_KEYLEN = 64;
+const LEGACY_DIGEST = 'sha512';
+const pbkdf2 = promisify(pbkdf2Cb);
+const isArgon2 = (hash) => hash.startsWith('$argon2');
+/** Mint an argon2id password hash. Returns the self-describing PHC string. */
+export function hashPassword(plain) {
+    return Bun.password.hash(plain, { algorithm: 'argon2id' });
+}
+/**
+ * Verify a candidate against a stored hash, handling BOTH formats: an argon2id PHC
+ * string (new) via `Bun.password.verify`; a legacy `"<salt>:<pbkdf2-hex>"` digest by
+ * re-deriving PBKDF2-SHA512 with the stored salt and comparing in constant time.
+ */
+export async function verifyPassword(plain, stored) {
+    if (isArgon2(stored)) {
+        try {
+            return await Bun.password.verify(plain, stored);
+        }
+        catch {
+            return false;
+        }
+    }
+    // Legacy: split on the FIRST colon — salt (hex) : derived (hex). A malformed value
+    // (no colon) is simply a non-match.
+    const sep = stored.indexOf(':');
+    if (sep === -1)
+        return false;
+    const salt = stored.slice(0, sep);
+    const expectedHex = stored.slice(sep + 1);
+    if (!salt || !expectedHex)
+        return false;
+    const derived = (await pbkdf2(plain, salt, LEGACY_ITERATIONS, LEGACY_KEYLEN, LEGACY_DIGEST)).toString('hex');
+    // timingSafeEqual throws on length mismatch; a length diff is already a non-match
+    // and short-circuiting leaks nothing a compare wouldn't.
+    if (derived.length !== expectedHex.length)
+        return false;
+    return timingSafeEqual(Buffer.from(derived), Buffer.from(expectedHex));
+}
+/**
+ * True when a stored hash is a legacy (non-argon2id) digest and should be upgraded.
+ * Call AFTER a successful {@link verifyPassword} to opportunistically re-hash with
+ * argon2id — never block auth on the upgrade.
+ */
+export function needsRehash(stored) {
+    return !isArgon2(stored);
+}

package/dist/server/auth/sessionStore.d.ts

@@ -0,0 +1,19 @@
+import type { PlumbingDb } from '../db/kysely';
+import type { SessionStore } from './types';
+export interface SessionStoreOptions {
+    /** Sliding refresh window — how long after the last activity a session stays
+     * valid. Default 7 days. */
+    refreshWindowMs?: number;
+    /** Retention before a stale (lapsed) row is pruned from memory + DB. Default 30
+     * days. Must be ≥ refreshWindowMs to keep recently-expired rows for the audit view. */
+    retentionMs?: number;
+    /** Throttle window for sliding-`touch` DB writes. Memory is always current; the
+     * row is flushed at most this often (unless a token re-issue forces it). Default 60s. */
+    flushIntervalMs?: number;
+    /** Start a background prune timer. Default false — wire pruning through the job
+     * runner (task 29), or call {@link SessionStore.prune} yourself. */
+    autoPrune?: boolean;
+    /** Auto-prune cadence when {@link autoPrune} is on. Default 1 hour. */
+    pruneIntervalMs?: number;
+}
+export declare function createSessionStore(ky: PlumbingDb, opts?: SessionStoreOptions): SessionStore;