@withbuddi/buddi 0.1.0-pre.27 → 0.1.0-pre.29

package/node_modules/@buddi/gateway/dist/web/sessions.d.ts

@@ -38,14 +38,27 @@ export type SessionScope = 'local' | 'remote';
  * `local` is a request that arrived on loopback with no proxy metadata on it —
  * the open mint, or a ticket exchanged from this machine. `ticket` is a ticket
  * exchanged from anywhere else. `tailscale` is an identity the local daemon
- * confirmed. This lives on the session rather than in a second map beside it,
+ * confirmed. `token` is an owner API token (`api-tokens.ts`); such a session is
+ * never stored. This lives on the session rather than in a second map beside it,
  * so provenance cannot drift out of step with the session it describes, and so
  * a route that must refuse everything but "this machine" can simply say so.
  */
-export type SessionVia = 'local' | 'ticket' | 'tailscale';
+export type SessionVia = 'local' | 'ticket' | 'tailscale' | 'token';
+/**
+ * Who holds the session: a person's browser, or one of buddi's own
+ * command-line clients (`buddi mcp`, `buddi connections`), which say so with
+ * the `x-buddi-client: mcp` header on the ticket exchange that mints the
+ * session (the header alone, on the open binding, earns nothing), or a program
+ * holding an API token (`api`). The lock screen covers browsers only (docs/dashboard.md, "Lock screen").
+ */
+export type SessionClient = 'browser' | 'mcp' | 'api';
+/** Why a session is locked: Lock now, nobody used it for the delay, or it began while a PIN was set. */
+export type LockReason = 'owner' | 'idle' | 'start';
 /** What established a session, as `create` is told it. */
 export interface SessionProvenance {
     via: SessionVia;
+    /** Who holds it; a browser unless buddi's own client said otherwise. */
+    client?: SessionClient;
     /** The daemon-confirmed login, when `via` is `tailscale`. */
     tailscaleLogin?: string;
     /** The tailnet address it was confirmed at. */
@@ -89,24 +102,91 @@ export interface Session {
     absoluteExpiresAt?: Date;
     /** When the browser was last handed this cookie. Drives the refresh rule. */
     cookieIssuedAt: Date;
+    /** A browser, or buddi's own command-line client. */
+    client: SessionClient;
+    /** When the owner last used it, as the page reports. Polls and streams do not count. */
+    activeAt: Date;
+    /** When it locked; absent while it is open. */
+    lockedAt?: Date;
+    lockReason?: LockReason;
+}
+/**
+ * What the table stores in place of a session id: sha256, hex.
+ *
+ * A plain hash is enough because the id is 256 random bits — there is nothing
+ * to guess, so nothing a slow hash would slow down.
+ */
+export declare function sessionIdHash(sessionId: string): string;
+/**
+ * The CSRF value for a session, derived from its id.
+ *
+ * Derived rather than random so it never has to be stored: after a restart the
+ * request presents the session id, and the CSRF value it must also echo is
+ * recomputed from it. HMAC keyed by the id is one-way — the page can read the
+ * CSRF cookie, and that reveals nothing about the HttpOnly id — and another
+ * site still cannot read either cookie, which is all double-submit asks of it.
+ */
+export declare function csrfFor(sessionId: string): string;
+/** Just enough of `pg.Pool` for the session table. */
+export interface SessionDb {
+    query: (sql: string, params?: unknown[]) => Promise<{
+        rows: unknown[];
+    }>;
 }
+/**
+ * A session as `forget` offers it: the stored fields, and the id only when this
+ * process has seen the cookie (a row read back from the table has no id to give).
+ */
+export type SessionRecord = Omit<Session, 'id' | 'csrf'> & {
+    id?: string;
+};
+export interface SessionStoreOptions {
+    /** The database the sessions are kept in. Without one they live in memory only. */
+    db?: SessionDb | undefined;
+    log?: ((line: string) => void) | undefined;
+}
+/**
+ * The longest the stored idle edge may lag the live one.
+ *
+ * Sliding the in-memory expiry is free and happens on every request; writing
+ * it back is a database round trip, so it is done at most this often per
+ * session (or a tenth of the idle lifetime, when that is shorter). A restart
+ * can therefore cost a session at most this much of its idle lifetime, never
+ * extend it.
+ */
+export declare const SESSION_WRITE_EVERY_MS: number;
+/** How often expired rows are swept from the table. */
+export declare const SESSION_SWEEP_EVERY_MS: number;
+/** How often a session's `active_at` is written back, at most. */
+export declare const ACTIVE_WRITE_EVERY_MS = 60000;
 export declare class SessionStore {
     #private;
-    constructor(ttlMs?: Partial<Record<SessionScope, number>>, tailscaleMaxMs?: number);
+    constructor(ttlMs?: Partial<Record<SessionScope, number>>, tailscaleMaxMs?: number, options?: SessionStoreOptions);
     /** The idle lifetime a session established from `scope` gets. */
     ttlFor(scope: SessionScope): number;
-    create(scope: SessionScope, now?: Date, provenance?: SessionProvenance): Session;
     /**
-     * Forget every session matching this, and say how many went.
+     * A new session. Stored unless `persist` is false — which is how the open
+     * loopback gate mints its silent sessions: one is minted again for free on
+     * the next request, so there is nothing to keep across a restart, and a
+     * cookie-less local poller must not add a row per request.
+     */
+    create(scope: SessionScope, now?: Date, provenance?: SessionProvenance, options?: {
+        persist?: boolean;
+        locked?: LockReason;
+    }): Session;
+    /**
+     * Forget every session matching this — in memory and in the table — and say
+     * how many went.
      *
      * What the setting page uses to revoke the sessions an identity earned the
      * moment that identity stops being allowed one: turning the switch off, or
      * naming a different login, empties the tailnet's access immediately rather
-     * than at the next request that happens to be made.
+     * than at the next request that happens to be made. Rows this process never
+     * saw a cookie for are offered without an `id`.
      */
-    forget(matches: (session: Session) => boolean): number;
+    forget(matches: (session: SessionRecord) => boolean): Promise<number>;
     /**
-     * The live session for this cookie, sliding its expiry.
+     * The live session for this cookie, from memory only, sliding its expiry.
      *
      * `scope` is where *this request* came from, and it must match where the
      * session was established. A cookie minted on loopback is not honoured when
@@ -114,8 +194,19 @@ export declare class SessionStore {
      * this machine rather than a credential that got a longer life by accident.
      * (A browser will not send it across hosts in the first place; this is the
      * belt to that suspenders.)
+     *
+     * The server asks `resolve`, which reads through to the table on a miss.
      */
     get(sessionId: string | undefined, scope: SessionScope, now?: Date): Session | undefined;
+    /**
+     * `get`, reading through to the table when this process has not seen the
+     * cookie yet — after a restart, every session starts here.
+     *
+     * A row is honoured on exactly the terms a cached session is: past its idle
+     * edge or its absolute one it is deleted and refused, and its scope must
+     * match. A database that cannot be read is a miss, never an error page.
+     */
+    resolve(sessionId: string | undefined, scope: SessionScope, now?: Date): Promise<Session | undefined>;
     /**
      * Should this response carry a fresh cookie? Mutating: a `true` answer marks
      * the cookie as issued now, so the caller must actually send it.
@@ -125,7 +216,29 @@ export declare class SessionStore {
     static maxAgeSeconds(session: Session): number;
     /** Constant-time double-submit check. */
     static csrfMatches(session: Session, presented: string | undefined): boolean;
-    destroy(sessionId: string | undefined): void;
+    /**
+     * End this session, in memory at once and in the table before the returned
+     * promise settles. Callers that revoke for a reason await it.
+     */
+    destroy(sessionId: string | undefined): Promise<void>;
+    /**
+     * Lock this session (or open it, with `null`): in memory at once, and on
+     * its row when it has one. The lock screen's own state, nothing more — the
+     * gate in `lock.ts` is what answers a locked session 423.
+     */
+    setLock(session: Session, lock: {
+        at: Date;
+        reason: LockReason;
+    } | null): void;
+    /**
+     * The owner used this session now. Written back at most once a minute: a
+     * restart can cost the lock at most that much of its delay, never add to it.
+     */
+    touch(session: Session, now: Date): void;
+    /** Open every cached session: the PIN is gone. The table is cleared by whoever removed it. */
+    unlockCached(): void;
+    /** Every table operation queued so far has settled. A test seam. */
+    flush(): Promise<void>;
     get size(): number;
 }
 /**
@@ -138,6 +251,8 @@ export declare class RateLimiter {
     constructor(max?: number, windowMs?: number);
     /** True when this address is over its budget and should be answered 429. */
     blocked(key: string, now?: Date): boolean;
+    /** How long until this address may try again, in ms; 0 when it is not blocked. */
+    retryAfterMs(key: string, now?: Date): number;
     /** Record one failed attempt. Successes never count against the budget. */
     fail(key: string, now?: Date): void;
     reset(key: string): void;

package/node_modules/@buddi/gateway/dist/web/sessions.d.ts.map

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

package/node_modules/@buddi/gateway/dist/web/sessions.js

@@ -1,12 +1,14 @@
 /**
  * Sessions, CSRF tokens, spent tickets and the auth rate limit.
  *
- * All four are in-process and deliberately so: a dashboard session is not a
- * durable fact about the installation, and a restart logging the owner out is
- * the correct behaviour for a page that can approve an effect. Nothing here
- * reaches the database, and nothing here is ever written to a log.
+ * Sessions are kept in `core.dashboard_sessions` with a small cache in front,
+ * so a restart or an upgrade no longer signs the owner out (docs/web.md,
+ * "Sessions"). What is stored is a hash of the session id, never the id: a
+ * copy of the table cannot be replayed as a cookie. The CSRF value is derived
+ * from the id rather than stored at all. The rate limit stays in memory.
+ * Nothing here is ever written to a log.
  */
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 /**
  * How long a session is honoured **without any activity**, by where it was
  * established. Both are idle lifetimes, not absolute ones: a session in use
@@ -66,24 +68,90 @@ function equal(a, b) {
     const bb = Buffer.from(b ?? '', 'utf8');
     return ab.length > 0 && ab.length === bb.length && timingSafeEqual(ab, bb);
 }
+/**
+ * What the table stores in place of a session id: sha256, hex.
+ *
+ * A plain hash is enough because the id is 256 random bits — there is nothing
+ * to guess, so nothing a slow hash would slow down.
+ */
+export function sessionIdHash(sessionId) {
+    return createHash('sha256').update(sessionId, 'utf8').digest('hex');
+}
+/**
+ * The CSRF value for a session, derived from its id.
+ *
+ * Derived rather than random so it never has to be stored: after a restart the
+ * request presents the session id, and the CSRF value it must also echo is
+ * recomputed from it. HMAC keyed by the id is one-way — the page can read the
+ * CSRF cookie, and that reveals nothing about the HttpOnly id — and another
+ * site still cannot read either cookie, which is all double-submit asks of it.
+ */
+export function csrfFor(sessionId) {
+    return createHmac('sha256', sessionId).update('buddi-csrf-v1').digest('base64url').slice(0, 32);
+}
+/**
+ * The longest the stored idle edge may lag the live one.
+ *
+ * Sliding the in-memory expiry is free and happens on every request; writing
+ * it back is a database round trip, so it is done at most this often per
+ * session (or a tenth of the idle lifetime, when that is shorter). A restart
+ * can therefore cost a session at most this much of its idle lifetime, never
+ * extend it.
+ */
+export const SESSION_WRITE_EVERY_MS = 5 * 60_000;
+/** How often expired rows are swept from the table. */
+export const SESSION_SWEEP_EVERY_MS = 10 * 60_000;
+const COLUMNS = `id_hash, scope, via, tailscale_login, tailscale_address, tailscale_name, ttl_ms,
+  created_at, expires_at, absolute_expires_at, locked_at, lock_reason, active_at, client`;
+/** How often a session's `active_at` is written back, at most. */
+export const ACTIVE_WRITE_EVERY_MS = 60_000;
+/** Is this a row the table could have produced? Anything else is a miss. */
+function isRow(value) {
+    const row = value;
+    return !!row && typeof row.id_hash === 'string'
+        && (row.scope === 'local' || row.scope === 'remote')
+        && (row.via === 'local' || row.via === 'ticket' || row.via === 'tailscale')
+        && row.created_at !== undefined && row.expires_at !== undefined && row.ttl_ms !== undefined;
+}
 export class SessionStore {
+    /** Keyed by the id's hash, so the cache and the table speak the same key. */
     #sessions = new Map();
+    /** When each cached session's idle edge was last written back. */
+    #persistedAt = new Map();
+    /** When each cached session's `active_at` was last written back. */
+    #activeWrittenAt = new Map();
+    /** Destroyed while a read of the table may still be in flight. */
+    #revoked = new Set();
     #ttl;
     #tailscaleMaxMs;
-    constructor(ttlMs = {}, tailscaleMaxMs = TAILSCALE_SESSION_MAX_MS) {
+    #db;
+    #log;
+    /** Every table operation, in order: a revoke can never be overtaken by a read. */
+    #chain = Promise.resolve();
+    #sweptAt = Number.NEGATIVE_INFINITY;
+    constructor(ttlMs = {}, tailscaleMaxMs = TAILSCALE_SESSION_MAX_MS, options = {}) {
         this.#ttl = { ...SESSION_TTL_MS, ...ttlMs };
         this.#tailscaleMaxMs = tailscaleMaxMs;
+        this.#db = options.db;
+        this.#log = options.log ?? ((line) => console.error(line));
     }
     /** The idle lifetime a session established from `scope` gets. */
     ttlFor(scope) {
         return this.#ttl[scope];
     }
-    create(scope, now = new Date(), provenance = { via: scope === 'local' ? 'local' : 'ticket' }) {
+    /**
+     * A new session. Stored unless `persist` is false — which is how the open
+     * loopback gate mints its silent sessions: one is minted again for free on
+     * the next request, so there is nothing to keep across a restart, and a
+     * cookie-less local poller must not add a row per request.
+     */
+    create(scope, now = new Date(), provenance = { via: scope === 'local' ? 'local' : 'ticket' }, options = {}) {
         this.#prune(now);
         const ttlMs = this.#ttl[scope];
+        const sessionId = id();
         const session = {
-            id: id(),
-            csrf: id(24),
+            id: sessionId,
+            csrf: csrfFor(sessionId),
             scope,
             via: provenance.via,
             ...(provenance.tailscaleLogin !== undefined ? { tailscaleLogin: provenance.tailscaleLogin } : {}),
@@ -94,30 +162,67 @@ export class SessionStore {
             expiresAt: new Date(now.getTime() + ttlMs),
             ...(provenance.via === 'tailscale' ? { absoluteExpiresAt: new Date(now.getTime() + this.#tailscaleMaxMs) } : {}),
             cookieIssuedAt: now,
+            client: provenance.client ?? 'browser',
+            activeAt: now,
+            ...(options.locked ? { lockedAt: now, lockReason: options.locked } : {}),
         };
-        this.#sessions.set(session.id, session);
+        const key = sessionIdHash(sessionId);
+        this.#sessions.set(key, session);
+        if (options.persist !== false && this.#db) {
+            this.#persistedAt.set(key, now.getTime());
+            const db = this.#db;
+            void this.#enqueue('storing a session', () => db.query(`insert into core.dashboard_sessions (${COLUMNS}, last_seen_at)
+         values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $8)
+         on conflict (id_hash) do nothing`, [key, session.scope, session.via, session.tailscaleLogin ?? null, session.tailscaleAddress ?? null,
+                session.tailscaleName ?? null, ttlMs, session.createdAt, session.expiresAt, session.absoluteExpiresAt ?? null,
+                session.lockedAt ?? null, session.lockReason ?? null, session.activeAt, session.client]));
+            this.#maybeSweep(now);
+        }
         return session;
     }
     /**
-     * Forget every session matching this, and say how many went.
+     * Forget every session matching this — in memory and in the table — and say
+     * how many went.
      *
      * What the setting page uses to revoke the sessions an identity earned the
      * moment that identity stops being allowed one: turning the switch off, or
      * naming a different login, empties the tailnet's access immediately rather
-     * than at the next request that happens to be made.
+     * than at the next request that happens to be made. Rows this process never
+     * saw a cookie for are offered without an `id`.
      */
-    forget(matches) {
-        let gone = 0;
+    async forget(matches) {
+        const gone = new Set();
         for (const [key, session] of this.#sessions) {
             if (matches(session)) {
-                this.#sessions.delete(key);
-                gone += 1;
+                this.#drop(key);
+                gone.add(key);
             }
         }
-        return gone;
+        const db = this.#db;
+        if (db) {
+            await this.#enqueue('revoking sessions', async () => {
+                const { rows } = await db.query(`select ${COLUMNS} from core.dashboard_sessions`);
+                const drop = [...gone];
+                for (const row of rows) {
+                    if (!isRow(row) || gone.has(row.id_hash))
+                        continue;
+                    const { id: _id, csrf: _csrf, ...record } = this.#fromRow(row, undefined);
+                    if (matches(record)) {
+                        drop.push(row.id_hash);
+                        gone.add(row.id_hash);
+                    }
+                }
+                // A read queued before this one may have cached a row it is dropping.
+                for (const key of drop)
+                    this.#drop(key);
+                if (drop.length > 0)
+                    await db.query(`delete from core.dashboard_sessions where id_hash = any($1)`, [drop]);
+            }, true);
+        }
+        return gone.size;
     }
     /**
-     * The live session for this cookie, sliding its expiry.
+     * The live session for this cookie, from memory only, sliding its expiry.
      *
      * `scope` is where *this request* came from, and it must match where the
      * session was established. A cookie minted on loopback is not honoured when
@@ -125,22 +230,57 @@ export class SessionStore {
      * this machine rather than a credential that got a longer life by accident.
      * (A browser will not send it across hosts in the first place; this is the
      * belt to that suspenders.)
+     *
+     * The server asks `resolve`, which reads through to the table on a miss.
      */
     get(sessionId, scope, now = new Date()) {
         if (!sessionId)
             return undefined;
-        const session = this.#sessions.get(sessionId);
+        const key = sessionIdHash(sessionId);
+        const session = this.#sessions.get(key);
         if (!session)
             return undefined;
         if (this.#dead(session, now)) {
-            this.#sessions.delete(sessionId);
+            this.#drop(key);
+            if (this.#db)
+                void this.#deleteRows([key]);
             return undefined;
         }
         if (session.scope !== scope)
             return undefined;
         session.expiresAt = new Date(now.getTime() + session.ttlMs);
+        this.#writeBack(key, session, now);
         return session;
     }
+    /**
+     * `get`, reading through to the table when this process has not seen the
+     * cookie yet — after a restart, every session starts here.
+     *
+     * A row is honoured on exactly the terms a cached session is: past its idle
+     * edge or its absolute one it is deleted and refused, and its scope must
+     * match. A database that cannot be read is a miss, never an error page.
+     */
+    async resolve(sessionId, scope, now = new Date()) {
+        if (!sessionId)
+            return undefined;
+        const key = sessionIdHash(sessionId);
+        if (!this.#sessions.has(key) && this.#db && !this.#revoked.has(key)) {
+            const db = this.#db;
+            await this.#enqueue('reading a session', async () => {
+                // Another request with the same cookie may have loaded it meanwhile.
+                if (this.#sessions.has(key) || this.#revoked.has(key))
+                    return;
+                const { rows } = await db.query(`select ${COLUMNS} from core.dashboard_sessions where id_hash = $1`, [key]);
+                const row = rows[0];
+                if (!isRow(row) || row.id_hash !== key || this.#revoked.has(key))
+                    return;
+                this.#sessions.set(key, this.#fromRow(row, sessionId));
+                this.#persistedAt.set(key, now.getTime());
+            });
+            this.#maybeSweep(now);
+        }
+        return this.get(sessionId, scope, now);
+    }
     /**
      * Should this response carry a fresh cookie? Mutating: a `true` answer marks
      * the cookie as issued now, so the caller must actually send it.
@@ -160,17 +300,153 @@ export class SessionStore {
     static csrfMatches(session, presented) {
         return presented !== undefined && equal(session.csrf, presented);
     }
-    destroy(sessionId) {
-        if (sessionId)
-            this.#sessions.delete(sessionId);
+    /**
+     * End this session, in memory at once and in the table before the returned
+     * promise settles. Callers that revoke for a reason await it.
+     */
+    async destroy(sessionId) {
+        if (!sessionId)
+            return;
+        const key = sessionIdHash(sessionId);
+        this.#drop(key);
+        if (this.#db) {
+            this.#revoked.add(key);
+            try {
+                await this.#deleteRows([key], true);
+            }
+            finally {
+                this.#revoked.delete(key);
+            }
+        }
+    }
+    /**
+     * Lock this session (or open it, with `null`): in memory at once, and on
+     * its row when it has one. The lock screen's own state, nothing more — the
+     * gate in `lock.ts` is what answers a locked session 423.
+     */
+    setLock(session, lock) {
+        if (lock) {
+            session.lockedAt = lock.at;
+            session.lockReason = lock.reason;
+        }
+        else {
+            delete session.lockedAt;
+            delete session.lockReason;
+        }
+        const key = session.id ? sessionIdHash(session.id) : undefined;
+        const db = this.#db;
+        if (!db || !key || !this.#persistedAt.has(key))
+            return;
+        void this.#enqueue(lock ? 'locking a session' : 'unlocking a session', () => db.query(`update core.dashboard_sessions set locked_at = $2, lock_reason = $3 where id_hash = $1`, [key, lock?.at ?? null, lock?.reason ?? null]));
+    }
+    /**
+     * The owner used this session now. Written back at most once a minute: a
+     * restart can cost the lock at most that much of its delay, never add to it.
+     */
+    touch(session, now) {
+        const before = session.activeAt.getTime();
+        session.activeAt = now;
+        const key = session.id ? sessionIdHash(session.id) : undefined;
+        const db = this.#db;
+        if (!db || !key || !this.#persistedAt.has(key))
+            return;
+        const written = this.#activeWrittenAt.get(key) ?? before;
+        if (now.getTime() - written < ACTIVE_WRITE_EVERY_MS)
+            return;
+        this.#activeWrittenAt.set(key, now.getTime());
+        void this.#enqueue('noting a session in use', () => db.query(`update core.dashboard_sessions set active_at = greatest(coalesce(active_at, $2), $2) where id_hash = $1`, [key, now]));
+    }
+    /** Open every cached session: the PIN is gone. The table is cleared by whoever removed it. */
+    unlockCached() {
+        for (const session of this.#sessions.values()) {
+            delete session.lockedAt;
+            delete session.lockReason;
+        }
+    }
+    /** Every table operation queued so far has settled. A test seam. */
+    async flush() {
+        await this.#chain;
     }
     get size() {
         return this.#sessions.size;
     }
+    #drop(key) {
+        this.#sessions.delete(key);
+        this.#persistedAt.delete(key);
+        this.#activeWrittenAt.delete(key);
+    }
+    #deleteRows(keys, rethrow = false) {
+        const db = this.#db;
+        if (!db)
+            return Promise.resolve();
+        return this.#enqueue('revoking a session', () => db.query(`delete from core.dashboard_sessions where id_hash = any($1)`, [keys]), rethrow);
+    }
+    /**
+     * Write the sliding edge back, sparingly: at most once per
+     * `SESSION_WRITE_EVERY_MS` (or a tenth of the idle lifetime) per session.
+     */
+    #writeBack(key, session, now) {
+        const db = this.#db;
+        const last = this.#persistedAt.get(key);
+        if (!db || last === undefined)
+            return;
+        const every = Math.min(SESSION_WRITE_EVERY_MS, session.ttlMs / 10);
+        if (now.getTime() - last < every)
+            return;
+        this.#persistedAt.set(key, now.getTime());
+        const expiresAt = session.expiresAt;
+        void this.#enqueue('renewing a session', () => db.query(`update core.dashboard_sessions set expires_at = greatest(expires_at, $2), last_seen_at = $3 where id_hash = $1`, [key, expiresAt, now]));
+    }
+    #maybeSweep(now) {
+        const db = this.#db;
+        if (!db || now.getTime() - this.#sweptAt < SESSION_SWEEP_EVERY_MS)
+            return;
+        this.#sweptAt = now.getTime();
+        void this.#enqueue('sweeping expired sessions', () => db.query(`delete from core.dashboard_sessions where expires_at <= $1 or absolute_expires_at <= $1`, [now]));
+    }
+    /** A stored row as a session. Its cookie is re-issued on the first response. */
+    #fromRow(row, sessionId) {
+        const createdAt = new Date(row.created_at);
+        return {
+            id: sessionId ?? '',
+            csrf: sessionId ? csrfFor(sessionId) : '',
+            scope: row.scope,
+            via: row.via,
+            ...(row.tailscale_login !== null ? { tailscaleLogin: row.tailscale_login } : {}),
+            ...(row.tailscale_address !== null ? { tailscaleAddress: row.tailscale_address } : {}),
+            ...(row.tailscale_name !== null ? { tailscaleName: row.tailscale_name } : {}),
+            ttlMs: Number(row.ttl_ms),
+            createdAt,
+            expiresAt: new Date(row.expires_at),
+            ...(row.absolute_expires_at !== null ? { absoluteExpiresAt: new Date(row.absolute_expires_at) } : {}),
+            // Unknown after a restart, so treated as old: the browser's copy is
+            // refreshed on the first response rather than trusted to outlive it.
+            cookieIssuedAt: createdAt,
+            client: row.client === 'mcp' ? 'mcp' : 'browser',
+            // A row from before the lock screen has no use on record: its last
+            // renewal (the idle edge less the lifetime) is the best there is.
+            activeAt: row.active_at ? new Date(row.active_at) : new Date(new Date(row.expires_at).getTime() - Number(row.ttl_ms)),
+            ...(row.locked_at ? { lockedAt: new Date(row.locked_at), lockReason: row.lock_reason ?? 'owner' } : {}),
+        };
+    }
+    /**
+     * Run one table operation after every earlier one. A failure is logged by a
+     * fixed sentence (never a value) and, unless `rethrow`, swallowed: the
+     * dashboard keeps working from memory when the database hiccups.
+     */
+    #enqueue(what, op, rethrow = false) {
+        const run = this.#chain.then(async () => { await op(); });
+        this.#chain = run.catch(() => { });
+        return run.catch((err) => {
+            this.#log(`web: ${what} failed: ${err instanceof Error ? err.message : String(err)}`);
+            if (rethrow)
+                throw err;
+        });
+    }
     #prune(now) {
         for (const [key, session] of this.#sessions) {
             if (this.#dead(session, now))
-                this.#sessions.delete(key);
+                this.#drop(key);
         }
     }
     /** Idle too long, or past the absolute edge no use extends. */
@@ -200,6 +476,12 @@ export class RateLimiter {
             return false;
         return entry.count >= this.#max;
     }
+    /** How long until this address may try again, in ms; 0 when it is not blocked. */
+    retryAfterMs(key, now = new Date()) {
+        if (!this.blocked(key, now))
+            return 0;
+        return Math.max(0, (this.#hits.get(key)?.resetAt ?? now.getTime()) - now.getTime());
+    }
     /** Record one failed attempt. Successes never count against the budget. */
     fail(key, now = new Date()) {
         const entry = this.#hits.get(key);