cursedbelt-server 4.28.0 → 4.30.0

package/README.md

@@ -73,6 +73,12 @@ against one stale count (task 2137). Pass `attempts: createD1MasterLockAttempts(
 (one conditional UPSERT … RETURNING on the `meta` row `master_lock:attempts`).
 `src/server/master-lock/attempts.ts` has the why.
 
+Its open unlocks go in rows of their own too: `sessions: createD1MasterLockSessions(db, writes,
+{ rows })`, one `meta` row per token digest under `master_lock:session:` (read them in the same
+snapshot query with `masterLockSessionRange()`). In the one-blob `state` two devices' overlapping
+requests each wrote back the map they read, and the owner was asked for the password again right
+after typing it (task 2138). `src/server/master-lock/sessions.ts` has the why.
+
 ## Standards
 
 `docs/retention.md`, `docs/activity.md`, `docs/notifications.md`, `docs/engagement.md` — the

package/dist/server/master-lock/index.d.ts

@@ -25,6 +25,7 @@ export { MASTER_LOCK_CSP, type MasterLockGuard, type MasterLockGuardOptions, cre
 export { LOCK_SCRIPT, LOCK_STYLE, MASTER_LOCK_DERIVE_SOURCE, type LockPageOptions, lockPageHtml, } from "./lockPage.js";
 export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, type MasterLockDirectoryOptions, masterLockPrincipalKey, } from "./principals.js";
 export { MASTER_LOCK_ATTEMPTS_KEY, type MasterLockAttempts, createD1MasterLockAttempts, } from "./attempts.js";
-export { FIRST_ACCOUNT_ID, MasterLock, type MasterLockAccount, type MasterLockAddAccountResult, type MasterLockEnrollResult, type MasterLockOptions, type MasterLockRecord, type MasterLockStore, type MasterLockUnlockResult, readRecord, } from "./masterLock.js";
+export { FIRST_ACCOUNT_ID, MasterLock, type MasterLockAccount, type MasterLockAddAccountResult, type MasterLockEnrollResult, type MasterLockOptions, type MasterLockRecord, type MasterLockStateStore, type MasterLockStore, type MasterLockUnlockResult, readRecord, } from "./masterLock.js";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, type MintMasterLockSeedOptions, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed.js";
+export { MASTER_LOCK_SESSION_KEY_PREFIX, type MasterLockSession, type MasterLockSessionStore, createD1MasterLockSessions, masterLockSessionRange, } from "./sessions.js";
 export { MASTER_LOCK_SETTING_KEY, MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store.js";

package/dist/server/master-lock/index.js

@@ -27,4 +27,5 @@ export { MASTER_LOCK_PRINCIPAL_KEY_PREFIX, MasterLockDirectory, masterLockPrinci
 export { MASTER_LOCK_ATTEMPTS_KEY, createD1MasterLockAttempts, } from "./attempts.js";
 export { FIRST_ACCOUNT_ID, MasterLock, readRecord, } from "./masterLock.js";
 export { DEFAULT_SEED_IDLE_MS, generateStagePassword, mintMasterLockSeed, serializeMasterLockSeed, } from "./seed.js";
+export { MASTER_LOCK_SESSION_KEY_PREFIX, createD1MasterLockSessions, masterLockSessionRange, } from "./sessions.js";
 export { MASTER_LOCK_SETTING_KEY, MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore, } from "./store.js";

package/dist/server/master-lock/masterLock.d.ts

@@ -1,5 +1,6 @@
 import { type MasterLockAccountSummary, type MasterLockKdfParams, type MasterLockStatus } from "cursedbelt-core/master-lock";
 import type { MasterLockAttempts } from "./attempts.js";
+import type { MasterLockSessionStore } from "./sessions.js";
 /**
  * ONE master password, and therefore one TENANT of the app behind it.
  *
@@ -102,6 +103,14 @@ export interface MasterLockOptions {
     store: MasterLockStore;
     /** See {@link MasterLockStateStore}. Required wherever the instance does not outlive a request. */
     state?: MasterLockStateStore;
+    /**
+     * Where the open unlocks live, ONE ROW EACH — see `./sessions.ts`. Given, the sessions leave
+     * the {@link state} blob (which keeps only the throttle's own count, if anything), so two
+     * devices' overlapping requests touch different rows instead of each writing back the whole
+     * map it read (task 2138). A Worker passes `createD1MasterLockSessions`; omitted, nothing
+     * changes.
+     */
+    sessions?: MasterLockSessionStore;
     /**
      * The BOOTSTRAP record, as JSON, used only when the store is empty — the same shape as
      * {@link MasterLockRecord} with `idleMs` optional.
@@ -206,6 +215,8 @@ export declare class MasterLock {
      */
     private sessions;
     private readonly stateStore;
+    /** See {@link MasterLockOptions.sessions}. */
+    private readonly sessionStore;
     private expiryTimer;
     private failures;
     private lastFailureAt;

package/dist/server/master-lock/masterLock.js

@@ -90,6 +90,8 @@ export class MasterLock {
      */
     sessions = new Map();
     stateStore = null;
+    /** See {@link MasterLockOptions.sessions}. */
+    sessionStore = null;
     expiryTimer = null;
     failures = 0;
     lastFailureAt = 0;
@@ -98,6 +100,7 @@ export class MasterLock {
     constructor(options) {
         this.store = options.store;
         this.stateStore = options.state ?? null;
+        this.sessionStore = options.sessions ?? null;
         this.attempts = options.attempts ?? this.ownAttempts();
         this.loadState();
         this.now = options.now ?? Date.now;
@@ -365,14 +368,24 @@ export class MasterLock {
      * created, so `unlock` and `enroll` cannot disagree about what an unlock is.
      */
     open(accountId, now) {
+        const hadFailures = this.failures !== 0 || this.lastFailureAt !== 0;
         this.failures = 0;
         this.lastFailureAt = 0;
         const token = randomToken();
         const wasLocked = this.sessions.size === 0;
         // ADDED, never replacing: the desk and the phone are the same person and both stay
         // open. See the `sessions` note.
-        this.sessions.set(tokenDigest(token), { accountId, lastActivityAt: now });
-        this.saveState();
+        const digest = tokenDigest(token);
+        const session = { accountId, lastActivityAt: now };
+        this.sessions.set(digest, session);
+        if (this.sessionStore) {
+            this.sessionStore.open(digest, session);
+            if (hadFailures)
+                this.saveState();
+        }
+        else {
+            this.saveState();
+        }
         this.scheduleExpiry();
         if (wasLocked)
             this.onLockedChange?.(false);
@@ -537,13 +550,16 @@ export class MasterLock {
                 // No early `return`, for the reason `accountFor` gives: the loop's duration
                 // must not say which of the jar's cookies was this app's.
                 if (constantTimeEqual(presented, live)) {
-                    this.sessions.set(live, { ...session, lastActivityAt: this.now() });
+                    const lastActivityAt = this.now();
+                    this.sessions.set(live, { ...session, lastActivityAt });
+                    this.sessionStore?.touch(live, lastActivityAt);
                     slid = true;
                 }
             }
         }
         if (slid) {
-            this.saveState();
+            if (!this.sessionStore)
+                this.saveState();
             this.scheduleExpiry();
         }
         return slid;
@@ -551,13 +567,18 @@ export class MasterLock {
     /** The manual lock — the owner's *"I want a lock option to turn the site back to needing
      *  the master password"*. Also what a change of password does to every open page. */
     lock() {
+        // 🔴 With a session store the rows are deleted even when THIS snapshot holds none: a
+        // device that unlocked after this request read its snapshot is still a device, and
+        // "every device" is the requirement below.
+        this.sessionStore?.closeAll();
         if (this.sessions.size === 0)
             return;
         // EVERY device this person has open, not the one that pressed the button. The
         // owner's requirement is "no one can see anything until the master password is
         // entered again", and a lock that left the phone open would not be that.
         this.sessions.clear();
-        this.saveState();
+        if (!this.sessionStore)
+            this.saveState();
         this.clearExpiry();
         this.onLockedChange?.(true);
     }
@@ -644,6 +665,9 @@ export class MasterLock {
     }
     /** Adopt the persisted live state, if there is a store and it holds a readable one. */
     loadState() {
+        for (const [digest, session] of this.sessionStore?.read() ?? []) {
+            this.sessions.set(digest, { accountId: session.accountId, lastActivityAt: session.lastActivityAt });
+        }
         if (!this.stateStore)
             return;
         const raw = this.stateStore.read();
@@ -653,7 +677,10 @@ export class MasterLock {
             const parsed = JSON.parse(raw);
             if (parsed.v !== 1)
                 return;
-            for (const [digest, session] of parsed.sessions ?? []) {
+            // With a session store the blob's sessions are not the truth — its rows are (task 2138).
+            // An unlock left in the blob by an older release is dropped, not adopted: adopting it
+            // would re-write a row a concurrent `lock()` may already have closed. Fails LOCKED, once.
+            for (const [digest, session] of this.sessionStore ? [] : (parsed.sessions ?? [])) {
                 if (typeof digest === "string" && typeof session?.accountId === "string" && Number.isFinite(session.lastActivityAt)) {
                     this.sessions.set(digest, { accountId: session.accountId, lastActivityAt: session.lastActivityAt });
                 }
@@ -667,7 +694,13 @@ export class MasterLock {
     }
     /** Persist the live state — every mutation of it calls this, or a Worker forgets it. */
     saveState() {
-        this.stateStore?.write(JSON.stringify({ v: 1, sessions: [...this.sessions], failures: this.failures, lastFailureAt: this.lastFailureAt }));
+        this.stateStore?.write(JSON.stringify({
+            v: 1,
+            // Not here when they have rows of their own — see {@link MasterLockOptions.sessions}.
+            sessions: this.sessionStore ? [] : [...this.sessions],
+            failures: this.failures,
+            lastFailureAt: this.lastFailureAt,
+        }));
     }
     /** Retire a session whose idle window has passed. Called on every read of the state, so
      *  correctness never depends on the timer having fired. */
@@ -680,10 +713,12 @@ export class MasterLock {
         const before = this.sessions.size;
         for (const [token, session] of this.sessions) {
             // Each device expires on its OWN clock, so one going idle never shortens another.
-            if (now - session.lastActivityAt > record.idleMs)
+            if (now - session.lastActivityAt > record.idleMs) {
                 this.sessions.delete(token);
+                this.sessionStore?.expire(token, session.lastActivityAt);
+            }
         }
-        if (this.sessions.size !== before)
+        if (this.sessions.size !== before && !this.sessionStore)
             this.saveState();
         if (wasOpen && this.sessions.size === 0) {
             this.clearExpiry();

package/dist/server/master-lock/sessions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The master lock's open unlocks, ONE ROW EACH — so two devices' requests never overwrite each
+ * other's sessions.
+ *
+ * ── 🔴 Why this file exists (task 2138, 2026-09-24) ─────────────────────────
+ * A Worker rebuilds `MasterLock` on every request over a snapshot, and until 4.30.0 the open
+ * unlocks rode in ONE JSON blob (`MasterLockStateStore`, `master_lock:state`). Every mutation
+ * wrote the whole map back, so two requests that overlapped each wrote the map THEY read: the
+ * owner unlocks on the phone while the desk's `POST /__lock/ping` is in flight, the ping's write
+ * lands last, and the phone's brand-new session is gone — asked for the master password again
+ * right after typing it. A request that swept an expired session dropped any unlock that opened
+ * during it the same way. It failed LOCKED, so it was never a hole; it was a trust bug.
+ *
+ * With a {@link MasterLockSessionStore}, every mutation touches only the row it means:
+ *  · `open`     — insert this token's row. Nothing else is read or written.
+ *  · `touch`    — slide this row's clock, and ONLY if the row still exists and only forwards.
+ *                 🔴 Never an upsert: a touch landing after a concurrent `lock()` must not
+ *                 resurrect the session the owner just closed on every device.
+ *  · `expire`   — delete this row, and only if it is still as idle as the sweep saw it, so a
+ *                 sweep racing a touch from another device cannot drop a session that was just used.
+ *  · `closeAll` — delete every row under the prefix. The manual lock, and a password change.
+ *
+ * Omitted, the sessions stay where they were — in memory, or in the state blob — so the Mac's
+ * one-process daemons are unchanged.
+ */
+import type { WriteCollector } from "../d1/invocation.js";
+import type { D1LikeDatabase } from "../d1/types.js";
+/** One live unlock: the token's account, and when it last saw real interaction. */
+export interface MasterLockSession {
+    accountId: string;
+    lastActivityAt: number;
+}
+/**
+ * Where the open unlocks live when the lock does not outlive a request — one entry per token
+ * DIGEST (never the token). Synchronous by the same contract as `MasterLockStore`: `read` answers
+ * from the request's snapshot, and the mutations are queued for the entry point to settle.
+ */
+export interface MasterLockSessionStore {
+    /** Every open unlock, as this request's snapshot read them. */
+    read(): Iterable<readonly [digest: string, session: MasterLockSession]>;
+    open(digest: string, session: MasterLockSession): void;
+    /** Slide an EXISTING session's clock forwards. Never creates one. */
+    touch(digest: string, lastActivityAt: number): void;
+    /** Retire a lapsed session — only if it has not been touched since `seenLastActivityAt`. */
+    expire(digest: string, seenLastActivityAt: number): void;
+    /** Every session, on every device. */
+    closeAll(): void;
+}
+/** The key prefix a D1 store keeps one session per row under, beside the lock's record. */
+export declare const MASTER_LOCK_SESSION_KEY_PREFIX = "master_lock:session:";
+/**
+ * The half-open key range `[low, high)` that holds exactly the keys under `prefix` — for a
+ * snapshot query that reads them with the lock's other rows. A range, not `LIKE`: `_` is a
+ * `LIKE` wildcard and this prefix is full of them.
+ */
+export declare function masterLockSessionRange(prefix?: string): {
+    low: string;
+    high: string;
+};
+/**
+ * The store over a D1 key/value table (`key TEXT PRIMARY KEY, value TEXT`) — `meta` by default,
+ * the table a Worker port already keeps the lock's record in, so it needs no migration.
+ *
+ * `rows` is the request's snapshot, read by the caller in the same query as the lock's other keys
+ * (`masterLockSessionRange` is the range to add); rows outside the prefix are ignored, so the
+ * whole snapshot may be passed. Mutations go to `writes`, CHAINED so they land in the order they
+ * were made — a password change is `closeAll` then nothing, but a lock-then-open in one request
+ * must not race its own DELETE past its INSERT (`createPendingWrites` runs what it collects
+ * concurrently, and says so).
+ */
+export declare function createD1MasterLockSessions(db: D1LikeDatabase, writes: WriteCollector, options: {
+    rows: Iterable<{
+        key: string;
+        value: string;
+    }>;
+    table?: string;
+    prefix?: string;
+}): MasterLockSessionStore;

package/dist/server/master-lock/sessions.js

@@ -0,0 +1,67 @@
+/** The key prefix a D1 store keeps one session per row under, beside the lock's record. */
+export const MASTER_LOCK_SESSION_KEY_PREFIX = "master_lock:session:";
+/**
+ * The half-open key range `[low, high)` that holds exactly the keys under `prefix` — for a
+ * snapshot query that reads them with the lock's other rows. A range, not `LIKE`: `_` is a
+ * `LIKE` wildcard and this prefix is full of them.
+ */
+export function masterLockSessionRange(prefix = MASTER_LOCK_SESSION_KEY_PREFIX) {
+    const last = prefix.charCodeAt(prefix.length - 1);
+    return { low: prefix, high: prefix.slice(0, -1) + String.fromCharCode(last + 1) };
+}
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function parseSession(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.accountId !== "string" || !Number.isFinite(parsed.lastActivityAt))
+            return null;
+        return { accountId: parsed.accountId, lastActivityAt: Number(parsed.lastActivityAt) };
+    }
+    catch {
+        // An unreadable row is no session: LOCKED, the safe reading.
+        return null;
+    }
+}
+/**
+ * The store over a D1 key/value table (`key TEXT PRIMARY KEY, value TEXT`) — `meta` by default,
+ * the table a Worker port already keeps the lock's record in, so it needs no migration.
+ *
+ * `rows` is the request's snapshot, read by the caller in the same query as the lock's other keys
+ * (`masterLockSessionRange` is the range to add); rows outside the prefix are ignored, so the
+ * whole snapshot may be passed. Mutations go to `writes`, CHAINED so they land in the order they
+ * were made — a password change is `closeAll` then nothing, but a lock-then-open in one request
+ * must not race its own DELETE past its INSERT (`createPendingWrites` runs what it collects
+ * concurrently, and says so).
+ */
+export function createD1MasterLockSessions(db, writes, options) {
+    const table = options.table ?? "meta";
+    if (!IDENTIFIER.test(table))
+        throw new Error(`master lock sessions: "${table}" is not a table name`);
+    const prefix = options.prefix ?? MASTER_LOCK_SESSION_KEY_PREFIX;
+    const { low, high } = masterLockSessionRange(prefix);
+    const snapshot = [];
+    for (const row of options.rows) {
+        if (!row.key.startsWith(prefix))
+            continue;
+        const session = parseSession(row.value);
+        if (session)
+            snapshot.push([row.key.slice(prefix.length), session]);
+    }
+    let chain = Promise.resolve();
+    const queue = (sql, ...params) => {
+        chain = chain.then(() => db
+            .prepare(sql)
+            .bind(...params)
+            .run());
+        writes.add(chain);
+    };
+    const lastActivity = `json_extract(value, '$.lastActivityAt')`;
+    return {
+        read: () => snapshot,
+        open: (digest, session) => queue(`INSERT OR REPLACE INTO ${table} (key, value) VALUES (?, ?)`, prefix + digest, JSON.stringify({ accountId: session.accountId, lastActivityAt: session.lastActivityAt })),
+        touch: (digest, lastActivityAt) => queue(`UPDATE ${table} SET value = json_set(value, '$.lastActivityAt', ?2)
+				 WHERE key = ?1 AND json_valid(value) AND ${lastActivity} < ?2`, prefix + digest, lastActivityAt),
+        expire: (digest, seenLastActivityAt) => queue(`DELETE FROM ${table} WHERE key = ?1 AND (NOT json_valid(value) OR ${lastActivity} <= ?2)`, prefix + digest, seenLastActivityAt),
+        closeAll: () => queue(`DELETE FROM ${table} WHERE key >= ? AND key < ?`, low, high),
+    };
+}

package/dist/server/metrics/metricsBuffer.d.ts

@@ -27,8 +27,6 @@ export interface MetricRow {
     region?: string | null;
     city?: string | null;
 }
-/** The optional place columns, in insert order. Each is written only when the table HAS it. */
-export declare const PLACE_COLUMNS: readonly ["country", "region", "city"];
 export interface MetricsBufferOptions {
     db: Database;
     /** Flush cadence in ms. Default: 1500. */

package/dist/server/metrics/metricsBuffer.js

@@ -1,5 +1,8 @@
-/** The optional place columns, in insert order. Each is written only when the table HAS it. */
-export const PLACE_COLUMNS = ['country', 'region', 'city'];
+import { PLACE_COLUMNS } from './requestPlace.js';
+// Every place column is a `MetricRow` field — a column declared in `requestPlace.ts` that this
+// row cannot carry fails to compile here rather than inserting `undefined` for ever.
+const _placeColumnsAreRowFields = PLACE_COLUMNS;
+void _placeColumnsAreRowFields;
 export function createMetricsBuffer(opts) {
     const { db, flushIntervalMs = 1500, maxSize = 5000 } = opts;
     let buffer = [];

package/dist/server/metrics/requestPlace.d.ts

@@ -30,6 +30,14 @@ export interface RequestPlace {
 }
 /** Place one request, or `null` when it cannot. Must not throw — but a throw is caught and read as `null`. */
 export type RequestLocator = (request: Request) => RequestPlace | null;
+/**
+ * The place columns, in insert order — the ONE declaration every reader and migration uses
+ * (`metricsBuffer` writes them, an app's reader allows them, an app's migration adds them).
+ * Exported through `cursedbelt-server/telemetry` since 4.29.0 (task 2141): until then it was
+ * private to `metricsBuffer.ts`, so flix, station and desk each declared their own copy, and a
+ * fourth column added here would have been written by the buffer and dropped by all three.
+ */
+export declare const PLACE_COLUMNS: readonly ["country", "region", "city"];
 /** Each place field is capped so three of them can never crowd the 5120-byte Analytics Engine blob budget. */
 export declare const PLACE_FIELD_MAX_CHARS = 96;
 /**

package/dist/server/metrics/requestPlace.js

@@ -22,6 +22,14 @@
  *
  * Worker-safe: no `bun:` import (`telemetryIsWorkerSafe.spec.ts` walks this graph).
  */
+/**
+ * The place columns, in insert order — the ONE declaration every reader and migration uses
+ * (`metricsBuffer` writes them, an app's reader allows them, an app's migration adds them).
+ * Exported through `cursedbelt-server/telemetry` since 4.29.0 (task 2141): until then it was
+ * private to `metricsBuffer.ts`, so flix, station and desk each declared their own copy, and a
+ * fourth column added here would have been written by the buffer and dropped by all three.
+ */
+export const PLACE_COLUMNS = ['country', 'region', 'city'];
 /** Each place field is capped so three of them can never crowd the 5120-byte Analytics Engine blob budget. */
 export const PLACE_FIELD_MAX_CHARS = 96;
 /** Cloudflare's "no country could be determined" code — an unknown, not a place. */

package/dist/server/requestLog/requestMetrics.js

@@ -62,7 +62,7 @@ import { Database } from "bun:sqlite";
 import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { applyCcPragmas } from "cwip/sqlite";
-import { PLACE_COLUMNS } from "../metrics/metricsBuffer.js";
+import { PLACE_COLUMNS } from "../metrics/requestPlace.js";
 import { createTelemetrySink } from "../metrics/telemetrySink.js";
 import { requestLogger } from "../middleware/requestLogger.js";
 import { runMigrations } from "../migration/runner.js";

package/dist/server/telemetry.d.ts

@@ -17,4 +17,4 @@
  */
 export { type RequestLoggerOpts, requestLogger } from './middleware/requestLogger.js';
 export { type AnalyticsEngineDataset, createTelemetrySink, TELEMETRY_POINT_VERSION, type TelemetryEvent, type TelemetrySink, type TelemetrySinkOptions, toDataPoint, } from './metrics/telemetrySink.js';
-export { locateFromCloudflare, type RequestLocator, type RequestPlace, } from './metrics/requestPlace.js';
+export { locateFromCloudflare, PLACE_COLUMNS, type RequestLocator, type RequestPlace, } from './metrics/requestPlace.js';

package/dist/server/telemetry.js

@@ -17,4 +17,4 @@
  */
 export { requestLogger } from './middleware/requestLogger.js';
 export { createTelemetrySink, TELEMETRY_POINT_VERSION, toDataPoint, } from './metrics/telemetrySink.js';
-export { locateFromCloudflare, } from './metrics/requestPlace.js';
+export { locateFromCloudflare, PLACE_COLUMNS, } from './metrics/requestPlace.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.28.0",
+	"version": "4.30.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -340,7 +340,7 @@
 	"dependencies": {
 		"argon2id": "1.0.1",
 		"cursedbelt-core": "^2.1.1",
-		"cursedops": "^0.6.0",
+		"cursedops": "^0.8.1",
 		"cwip": "^4.6.0",
 		"jose": "^6.2.3"
 	},
@@ -380,7 +380,7 @@
 		"@node-rs/argon2": "^2.0.2",
 		"@types/bun": "^1.3.14",
 		"@types/node": "^24",
-		"cursedbelt": "^4.5.0",
+		"cursedbelt": "^5.7.2",
 		"hono": "4.12.28",
 		"kysely": "^0.28.17",
 		"kysely-bun-sqlite": "^0.4.0",

package/src/server/master-lock/index.ts

@@ -59,6 +59,7 @@ export {
 	type MasterLockEnrollResult,
 	type MasterLockOptions,
 	type MasterLockRecord,
+	type MasterLockStateStore,
 	type MasterLockStore,
 	type MasterLockUnlockResult,
 	readRecord,
@@ -70,6 +71,13 @@ export {
 	mintMasterLockSeed,
 	serializeMasterLockSeed,
 } from "./seed.js";
+export {
+	MASTER_LOCK_SESSION_KEY_PREFIX,
+	type MasterLockSession,
+	type MasterLockSessionStore,
+	createD1MasterLockSessions,
+	masterLockSessionRange,
+} from "./sessions.js";
 export {
 	MASTER_LOCK_SETTING_KEY,
 	MASTER_LOCK_STATE_KEY,

package/src/server/master-lock/masterLock.ts

@@ -58,6 +58,7 @@ import {
 	windowRemaining,
 } from "cursedbelt-core/master-lock";
 import type { MasterLockAttempts, MasterLockCharge } from "./attempts.js";
+import type { MasterLockSession, MasterLockSessionStore } from "./sessions.js";
 
 /**
  * ONE master password, and therefore one TENANT of the app behind it.
@@ -166,6 +167,14 @@ export interface MasterLockOptions {
 	store: MasterLockStore;
 	/** See {@link MasterLockStateStore}. Required wherever the instance does not outlive a request. */
 	state?: MasterLockStateStore;
+	/**
+	 * Where the open unlocks live, ONE ROW EACH — see `./sessions.ts`. Given, the sessions leave
+	 * the {@link state} blob (which keeps only the throttle's own count, if anything), so two
+	 * devices' overlapping requests touch different rows instead of each writing back the whole
+	 * map it read (task 2138). A Worker passes `createD1MasterLockSessions`; omitted, nothing
+	 * changes.
+	 */
+	sessions?: MasterLockSessionStore;
 	/**
 	 * The BOOTSTRAP record, as JSON, used only when the store is empty — the same shape as
 	 * {@link MasterLockRecord} with `idleMs` optional.
@@ -225,12 +234,6 @@ export type MasterLockAddAccountResult =
 	| { ok: true; account: MasterLockAccountSummary }
 	| { ok: false; reason: "wrong" | "invalid" | "duplicate" | "unconfigured" | "locked" };
 
-/** One live unlock: the token's account, and when it last saw real interaction. */
-interface MasterLockSession {
-	accountId: string;
-	lastActivityAt: number;
-}
-
 const TOKEN_BYTES = 24;
 
 /**
@@ -269,6 +272,8 @@ export class MasterLock {
 	 */
 	private sessions = new Map<string, MasterLockSession>();
 	private readonly stateStore: MasterLockStateStore | null = null;
+	/** See {@link MasterLockOptions.sessions}. */
+	private readonly sessionStore: MasterLockSessionStore | null = null;
 	private expiryTimer: ReturnType<typeof setTimeout> | null = null;
 
 	private failures = 0;
@@ -279,6 +284,7 @@ export class MasterLock {
 	constructor(options: MasterLockOptions) {
 		this.store = options.store;
 		this.stateStore = options.state ?? null;
+		this.sessionStore = options.sessions ?? null;
 		this.attempts = options.attempts ?? this.ownAttempts();
 		this.loadState();
 		this.now = options.now ?? Date.now;
@@ -555,14 +561,22 @@ export class MasterLock {
 	 * created, so `unlock` and `enroll` cannot disagree about what an unlock is.
 	 */
 	private open(accountId: string, now: number): { token: string; accountId: string } {
+		const hadFailures = this.failures !== 0 || this.lastFailureAt !== 0;
 		this.failures = 0;
 		this.lastFailureAt = 0;
 		const token = randomToken();
 		const wasLocked = this.sessions.size === 0;
 		// ADDED, never replacing: the desk and the phone are the same person and both stay
 		// open. See the `sessions` note.
-		this.sessions.set(tokenDigest(token), { accountId, lastActivityAt: now });
-		this.saveState();
+		const digest = tokenDigest(token);
+		const session = { accountId, lastActivityAt: now };
+		this.sessions.set(digest, session);
+		if (this.sessionStore) {
+			this.sessionStore.open(digest, session);
+			if (hadFailures) this.saveState();
+		} else {
+			this.saveState();
+		}
 		this.scheduleExpiry();
 		if (wasLocked) this.onLockedChange?.(false);
 		return { token, accountId };
@@ -737,13 +751,15 @@ export class MasterLock {
 				// No early `return`, for the reason `accountFor` gives: the loop's duration
 				// must not say which of the jar's cookies was this app's.
 				if (constantTimeEqual(presented, live)) {
-					this.sessions.set(live, { ...session, lastActivityAt: this.now() });
+					const lastActivityAt = this.now();
+					this.sessions.set(live, { ...session, lastActivityAt });
+					this.sessionStore?.touch(live, lastActivityAt);
 					slid = true;
 				}
 			}
 		}
 		if (slid) {
-			this.saveState();
+			if (!this.sessionStore) this.saveState();
 			this.scheduleExpiry();
 		}
 		return slid;
@@ -752,12 +768,16 @@ export class MasterLock {
 	/** The manual lock — the owner's *"I want a lock option to turn the site back to needing
 	 *  the master password"*. Also what a change of password does to every open page. */
 	lock(): void {
+		// 🔴 With a session store the rows are deleted even when THIS snapshot holds none: a
+		// device that unlocked after this request read its snapshot is still a device, and
+		// "every device" is the requirement below.
+		this.sessionStore?.closeAll();
 		if (this.sessions.size === 0) return;
 		// EVERY device this person has open, not the one that pressed the button. The
 		// owner's requirement is "no one can see anything until the master password is
 		// entered again", and a lock that left the phone open would not be that.
 		this.sessions.clear();
-		this.saveState();
+		if (!this.sessionStore) this.saveState();
 		this.clearExpiry();
 		this.onLockedChange?.(true);
 	}
@@ -849,6 +869,9 @@ export class MasterLock {
 
 	/** Adopt the persisted live state, if there is a store and it holds a readable one. */
 	private loadState(): void {
+		for (const [digest, session] of this.sessionStore?.read() ?? []) {
+			this.sessions.set(digest, { accountId: session.accountId, lastActivityAt: session.lastActivityAt });
+		}
 		if (!this.stateStore) return;
 		const raw = this.stateStore.read();
 		if (!raw) return;
@@ -860,7 +883,10 @@ export class MasterLock {
 				lastFailureAt?: number;
 			};
 			if (parsed.v !== 1) return;
-			for (const [digest, session] of parsed.sessions ?? []) {
+			// With a session store the blob's sessions are not the truth — its rows are (task 2138).
+			// An unlock left in the blob by an older release is dropped, not adopted: adopting it
+			// would re-write a row a concurrent `lock()` may already have closed. Fails LOCKED, once.
+			for (const [digest, session] of this.sessionStore ? [] : (parsed.sessions ?? [])) {
 				if (typeof digest === "string" && typeof session?.accountId === "string" && Number.isFinite(session.lastActivityAt)) {
 					this.sessions.set(digest, { accountId: session.accountId, lastActivityAt: session.lastActivityAt });
 				}
@@ -875,7 +901,13 @@ export class MasterLock {
 	/** Persist the live state — every mutation of it calls this, or a Worker forgets it. */
 	private saveState(): void {
 		this.stateStore?.write(
-			JSON.stringify({ v: 1, sessions: [...this.sessions], failures: this.failures, lastFailureAt: this.lastFailureAt }),
+			JSON.stringify({
+				v: 1,
+				// Not here when they have rows of their own — see {@link MasterLockOptions.sessions}.
+				sessions: this.sessionStore ? [] : [...this.sessions],
+				failures: this.failures,
+				lastFailureAt: this.lastFailureAt,
+			}),
 		);
 	}
 
@@ -889,9 +921,12 @@ export class MasterLock {
 		const before = this.sessions.size;
 		for (const [token, session] of this.sessions) {
 			// Each device expires on its OWN clock, so one going idle never shortens another.
-			if (now - session.lastActivityAt > record.idleMs) this.sessions.delete(token);
+			if (now - session.lastActivityAt > record.idleMs) {
+				this.sessions.delete(token);
+				this.sessionStore?.expire(token, session.lastActivityAt);
+			}
 		}
-		if (this.sessions.size !== before) this.saveState();
+		if (this.sessions.size !== before && !this.sessionStore) this.saveState();
 		if (wasOpen && this.sessions.size === 0) {
 			this.clearExpiry();
 			this.onLockedChange?.(true);

package/src/server/master-lock/sessions.spec.ts

@@ -0,0 +1,247 @@
+/**
+ * 🔴 The open unlocks are ONE ROW EACH (task 2138) — two devices' overlapping requests never
+ * overwrite each other's sessions.
+ *
+ * Every test builds the lock the way a Worker does: per REQUEST, over a snapshot read from D1
+ * before the request runs, with its writes collected and settled at the end. "In flight
+ * together" therefore means: both requests snapshot, then both act, then both settle — the
+ * interleaving that made the blob lose an unlock. The first test runs that interleaving over the
+ * blob and shows the loss, so the rest are not passing vacuously.
+ */
+import { Database } from "bun:sqlite";
+import { beforeAll, describe, expect, test } from "bun:test";
+import { type MasterLockKdfParams, deriveMasterLockVerifier } from "cursedbelt-core/master-lock";
+import { createFakeD1Binding } from "../d1/fakeD1.js";
+import { createPendingWrites } from "../d1/invocation.js";
+import { createRemoteD1 } from "../d1/remote.js";
+import type { D1LikeDatabase, D1LikeStatement } from "../d1/types.js";
+import { MasterLock } from "./masterLock.js";
+import { MASTER_LOCK_SESSION_KEY_PREFIX, createD1MasterLockSessions, masterLockSessionRange } from "./sessions.js";
+import { MASTER_LOCK_STATE_KEY, createKvMasterLockStore, createMemoryMasterLockStore } from "./store.js";
+
+const KDF: MasterLockKdfParams = { v: 1, alg: "PBKDF2-SHA256", iter: 1, salt: "AAECAwQFBgcICQoLDA0ODw" };
+const IDLE_MS = 10 * 60_000;
+
+let VERIFIER = "";
+let SEED = "";
+beforeAll(async () => {
+	VERIFIER = await deriveMasterLockVerifier("the owner's master password", KDF);
+	const verifierHash = await Bun.password.hash(VERIFIER, { algorithm: "argon2id", memoryCost: 4096, timeCost: 1 });
+	SEED = JSON.stringify({ kdf: KDF, verifierHash, idleMs: IDLE_MS });
+});
+
+const req = (token: string): Request => new Request("http://x/", { headers: { cookie: `master_lock=${token}` } });
+
+/**
+ * Real D1 is a network round trip per statement, so two statements in flight land in whatever
+ * order the network picks. The fake runs them in call order; this makes every DELETE slow, so a
+ * store that does not order its own writes is caught doing it.
+ */
+function slowDeletes(db: D1LikeDatabase): D1LikeDatabase {
+	const wrap = (sql: string, statement: D1LikeStatement): D1LikeStatement => ({
+		bind: (...values) => wrap(sql, statement.bind(...values)),
+		first: ((column?: string) => (column === undefined ? statement.first() : statement.first(column))) as D1LikeStatement["first"],
+		all: () => statement.all(),
+		raw: () => statement.raw(),
+		run: async () => {
+			if (/^\s*DELETE/i.test(sql)) await new Promise((resolve) => setTimeout(resolve, 20));
+			return statement.run();
+		},
+	});
+	return Object.assign(Object.create(db) as D1LikeDatabase, { prepare: (sql: string) => wrap(sql, db.prepare(sql)) });
+}
+
+function world() {
+	const sqlite = new Database(":memory:");
+	sqlite.exec("CREATE TABLE meta ( key TEXT PRIMARY KEY, value TEXT NOT NULL )");
+	const db: D1LikeDatabase = slowDeletes(createRemoteD1(createFakeD1Binding(sqlite)));
+	const record = createMemoryMasterLockStore(null);
+	let clock = 1_000_000;
+	const rows = () => sqlite.query("SELECT key FROM meta WHERE key >= ? ORDER BY key").all(MASTER_LOCK_SESSION_KEY_PREFIX) as { key: string }[];
+
+	/** One Worker request: snapshot, then a lock over it. `settle` is the entry point's await. */
+	async function request() {
+		const { low, high } = masterLockSessionRange();
+		const snapshot = (await db.prepare("SELECT key, value FROM meta WHERE key >= ? AND key < ?").bind(low, high).all<{ key: string; value: string }>())
+			.results;
+		const writes = createPendingWrites();
+		const lock = new MasterLock({
+			store: record,
+			sessions: createD1MasterLockSessions(db, writes, { rows: snapshot }),
+			seedJson: SEED,
+			now: () => clock,
+		});
+		return { lock, settle: () => writes.settle() };
+	}
+
+	/** Does a brand-new request, after everything settled, honour this token? */
+	async function opens(token: string): Promise<boolean> {
+		const { lock } = await request();
+		return lock.presents(req(token));
+	}
+
+	async function unlocked(): Promise<string> {
+		const r = await request();
+		const result = await r.lock.unlock(VERIFIER);
+		if (!result.ok) throw new Error("expected an unlock");
+		await r.settle();
+		return result.token;
+	}
+
+	return { sqlite, db, request, opens, unlocked, rows, tick: (ms: number) => (clock += ms) };
+}
+
+describe("🔴 two devices in flight together (task 2138)", () => {
+	test("the defect: over the ONE-blob state, the ping's write lands last and the phone's unlock is gone", async () => {
+		// The pre-4.30.0 shape — `state` is one `meta` row holding every session.
+		const sqlite = new Database(":memory:");
+		sqlite.exec("CREATE TABLE meta ( key TEXT PRIMARY KEY, value TEXT NOT NULL )");
+		const kv = {
+			get: (key: string) => (sqlite.query("SELECT value FROM meta WHERE key = ?").get(key) as { value: string } | null)?.value ?? null,
+			set: (key: string, value: string) => void sqlite.query("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run(key, value),
+		};
+		const record = createMemoryMasterLockStore(null);
+		/** A request whose state reads are a SNAPSHOT taken now, and whose writes land when it settles. */
+		const request = () => {
+			const seen = kv.get(MASTER_LOCK_STATE_KEY);
+			let pending: string | null = null;
+			const lock = new MasterLock({
+				store: record,
+				state: { read: () => seen, write: (json) => void (pending = json) },
+				seedJson: SEED,
+			});
+			return { lock, settle: () => pending !== null && createKvMasterLockStore(kv, MASTER_LOCK_STATE_KEY).write(pending) };
+		};
+		const desk = request();
+		const deskUnlock = await desk.lock.unlock(VERIFIER);
+		desk.settle();
+		if (!deskUnlock.ok) throw new Error("expected an unlock");
+
+		const phone = request();
+		const ping = request();
+		const phoneUnlock = await phone.lock.unlock(VERIFIER);
+		if (!phoneUnlock.ok) throw new Error("expected an unlock");
+		expect(ping.lock.touch(req(deskUnlock.token))).toBe(true);
+		phone.settle();
+		ping.settle(); // lands last
+
+		expect(request().lock.presents(req(phoneUnlock.token))).toBe(false);
+	});
+
+	test("an unlock on the phone and a ping from the desk, together: BOTH tokens still open the site", async () => {
+		const w = world();
+		const deskToken = await w.unlocked();
+
+		const phone = await w.request();
+		const ping = await w.request();
+		const phoneUnlock = await phone.lock.unlock(VERIFIER);
+		if (!phoneUnlock.ok) throw new Error("expected an unlock");
+		expect(ping.lock.touch(req(deskToken))).toBe(true);
+		await phone.settle();
+		await ping.settle();
+
+		expect(await w.opens(phoneUnlock.token)).toBe(true);
+		expect(await w.opens(deskToken)).toBe(true);
+		expect(w.rows()).toHaveLength(2);
+	});
+
+	test("a sweep of one lapsed device does not drop an unlock that opened during it", async () => {
+		const w = world();
+		const stale = await w.unlocked();
+		w.tick(IDLE_MS + 1);
+
+		const sweeper = await w.request();
+		const phone = await w.request();
+		const phoneUnlock = await phone.lock.unlock(VERIFIER);
+		if (!phoneUnlock.ok) throw new Error("expected an unlock");
+		expect(sweeper.lock.unlocked).toBe(false); // sweeps `stale`
+		await phone.settle();
+		await sweeper.settle();
+
+		expect(await w.opens(phoneUnlock.token)).toBe(true);
+		expect(await w.opens(stale)).toBe(false);
+		expect(w.rows()).toHaveLength(1);
+	});
+
+	test("🔴 a touch landing after a concurrent lock does NOT resurrect the session", async () => {
+		const w = world();
+		const token = await w.unlocked();
+
+		const locker = await w.request();
+		const ping = await w.request();
+		locker.lock.lock();
+		expect(ping.lock.touch(req(token))).toBe(true); // its snapshot still had the session
+		await locker.settle();
+		await ping.settle(); // lands last
+
+		expect(await w.opens(token)).toBe(false);
+		expect(w.rows()).toHaveLength(0);
+	});
+
+	test("🔴 a lock whose snapshot is EMPTY still closes a device that unlocked after that snapshot", async () => {
+		const w = world();
+		const locker = await w.request(); // read nothing
+		const phoneToken = await w.unlocked();
+		locker.lock.lock();
+		await locker.settle();
+		expect(await w.opens(phoneToken)).toBe(false);
+	});
+
+	test("a sweep racing a touch from another device keeps the session that was just used", async () => {
+		const w = world();
+		const token = await w.unlocked();
+		const late = await w.request(); // snapshot taken BEFORE the touch below
+		w.tick(IDLE_MS - 1);
+		const toucher = await w.request();
+		expect(toucher.lock.touch(req(token))).toBe(true);
+		await toucher.settle();
+		w.tick(2); // `late` now judges its (stale) view of the session lapsed
+		expect(late.lock.presents(req(token))).toBe(false);
+		await late.settle();
+		expect(await w.opens(token)).toBe(true);
+	});
+
+	test("a password change in one request — lock, then nothing else — closes every device, in order", async () => {
+		const w = world();
+		await w.unlocked();
+		await w.unlocked();
+		const r = await w.request();
+		r.lock.lock();
+		const reopened = await r.lock.unlock(VERIFIER); // same request: its INSERT must follow its DELETE
+		if (!reopened.ok) throw new Error("expected an unlock");
+		await r.settle();
+		expect(w.rows()).toHaveLength(1);
+		expect(await w.opens(reopened.token)).toBe(true);
+	});
+
+	test("🔴 the store lands its own writes in the order they were made — a closeAll then an open keeps the open", async () => {
+		const w = world();
+		const writes = createPendingWrites();
+		const store = createD1MasterLockSessions(w.db, writes, { rows: [] });
+		store.closeAll(); // slow, like a real round trip can be
+		store.open("fresh", { accountId: "acct-1", lastActivityAt: 1 });
+		await writes.settle();
+		expect(w.rows().map((row) => row.key)).toEqual([`${MASTER_LOCK_SESSION_KEY_PREFIX}fresh`]);
+	});
+
+	test("the rows hold a digest, never the token — a leaked row opens nothing", async () => {
+		const w = world();
+		const token = await w.unlocked();
+		const dump = JSON.stringify(w.sqlite.query("SELECT key, value FROM meta").all());
+		expect(dump).not.toContain(token);
+	});
+
+	test("an unreadable row is no session", async () => {
+		const w = world();
+		w.sqlite.query("INSERT INTO meta (key, value) VALUES (?, ?)").run(`${MASTER_LOCK_SESSION_KEY_PREFIX}abc`, "{not json");
+		const { lock } = await w.request();
+		expect(lock.unlocked).toBe(false);
+	});
+
+	test("the range is exactly the prefix — `_` is not a wildcard here", () => {
+		const { low, high } = masterLockSessionRange();
+		expect(`${MASTER_LOCK_SESSION_KEY_PREFIX}zzz` >= low && `${MASTER_LOCK_SESSION_KEY_PREFIX}zzz` < high).toBe(true);
+		expect("master_lock:state" >= low && "master_lock:state" < high).toBe(false);
+		expect("masterXlock:session:a" >= low && "masterXlock:session:a" < high).toBe(false);
+	});
+});

package/src/server/master-lock/sessions.ts

@@ -0,0 +1,141 @@
+/**
+ * The master lock's open unlocks, ONE ROW EACH — so two devices' requests never overwrite each
+ * other's sessions.
+ *
+ * ── 🔴 Why this file exists (task 2138, 2026-09-24) ─────────────────────────
+ * A Worker rebuilds `MasterLock` on every request over a snapshot, and until 4.30.0 the open
+ * unlocks rode in ONE JSON blob (`MasterLockStateStore`, `master_lock:state`). Every mutation
+ * wrote the whole map back, so two requests that overlapped each wrote the map THEY read: the
+ * owner unlocks on the phone while the desk's `POST /__lock/ping` is in flight, the ping's write
+ * lands last, and the phone's brand-new session is gone — asked for the master password again
+ * right after typing it. A request that swept an expired session dropped any unlock that opened
+ * during it the same way. It failed LOCKED, so it was never a hole; it was a trust bug.
+ *
+ * With a {@link MasterLockSessionStore}, every mutation touches only the row it means:
+ *  · `open`     — insert this token's row. Nothing else is read or written.
+ *  · `touch`    — slide this row's clock, and ONLY if the row still exists and only forwards.
+ *                 🔴 Never an upsert: a touch landing after a concurrent `lock()` must not
+ *                 resurrect the session the owner just closed on every device.
+ *  · `expire`   — delete this row, and only if it is still as idle as the sweep saw it, so a
+ *                 sweep racing a touch from another device cannot drop a session that was just used.
+ *  · `closeAll` — delete every row under the prefix. The manual lock, and a password change.
+ *
+ * Omitted, the sessions stay where they were — in memory, or in the state blob — so the Mac's
+ * one-process daemons are unchanged.
+ */
+import type { WriteCollector } from "../d1/invocation.js";
+import type { D1LikeBindable, D1LikeDatabase } from "../d1/types.js";
+
+/** One live unlock: the token's account, and when it last saw real interaction. */
+export interface MasterLockSession {
+	accountId: string;
+	lastActivityAt: number;
+}
+
+/**
+ * Where the open unlocks live when the lock does not outlive a request — one entry per token
+ * DIGEST (never the token). Synchronous by the same contract as `MasterLockStore`: `read` answers
+ * from the request's snapshot, and the mutations are queued for the entry point to settle.
+ */
+export interface MasterLockSessionStore {
+	/** Every open unlock, as this request's snapshot read them. */
+	read(): Iterable<readonly [digest: string, session: MasterLockSession]>;
+	open(digest: string, session: MasterLockSession): void;
+	/** Slide an EXISTING session's clock forwards. Never creates one. */
+	touch(digest: string, lastActivityAt: number): void;
+	/** Retire a lapsed session — only if it has not been touched since `seenLastActivityAt`. */
+	expire(digest: string, seenLastActivityAt: number): void;
+	/** Every session, on every device. */
+	closeAll(): void;
+}
+
+/** The key prefix a D1 store keeps one session per row under, beside the lock's record. */
+export const MASTER_LOCK_SESSION_KEY_PREFIX = "master_lock:session:";
+
+/**
+ * The half-open key range `[low, high)` that holds exactly the keys under `prefix` — for a
+ * snapshot query that reads them with the lock's other rows. A range, not `LIKE`: `_` is a
+ * `LIKE` wildcard and this prefix is full of them.
+ */
+export function masterLockSessionRange(prefix: string = MASTER_LOCK_SESSION_KEY_PREFIX): { low: string; high: string } {
+	const last = prefix.charCodeAt(prefix.length - 1);
+	return { low: prefix, high: prefix.slice(0, -1) + String.fromCharCode(last + 1) };
+}
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function parseSession(raw: string): MasterLockSession | null {
+	try {
+		const parsed = JSON.parse(raw) as Partial<MasterLockSession>;
+		if (typeof parsed.accountId !== "string" || !Number.isFinite(parsed.lastActivityAt)) return null;
+		return { accountId: parsed.accountId, lastActivityAt: Number(parsed.lastActivityAt) };
+	} catch {
+		// An unreadable row is no session: LOCKED, the safe reading.
+		return null;
+	}
+}
+
+/**
+ * The store over a D1 key/value table (`key TEXT PRIMARY KEY, value TEXT`) — `meta` by default,
+ * the table a Worker port already keeps the lock's record in, so it needs no migration.
+ *
+ * `rows` is the request's snapshot, read by the caller in the same query as the lock's other keys
+ * (`masterLockSessionRange` is the range to add); rows outside the prefix are ignored, so the
+ * whole snapshot may be passed. Mutations go to `writes`, CHAINED so they land in the order they
+ * were made — a password change is `closeAll` then nothing, but a lock-then-open in one request
+ * must not race its own DELETE past its INSERT (`createPendingWrites` runs what it collects
+ * concurrently, and says so).
+ */
+export function createD1MasterLockSessions(
+	db: D1LikeDatabase,
+	writes: WriteCollector,
+	options: { rows: Iterable<{ key: string; value: string }>; table?: string; prefix?: string },
+): MasterLockSessionStore {
+	const table = options.table ?? "meta";
+	if (!IDENTIFIER.test(table)) throw new Error(`master lock sessions: "${table}" is not a table name`);
+	const prefix = options.prefix ?? MASTER_LOCK_SESSION_KEY_PREFIX;
+	const { low, high } = masterLockSessionRange(prefix);
+
+	const snapshot: Array<readonly [string, MasterLockSession]> = [];
+	for (const row of options.rows) {
+		if (!row.key.startsWith(prefix)) continue;
+		const session = parseSession(row.value);
+		if (session) snapshot.push([row.key.slice(prefix.length), session]);
+	}
+
+	let chain: Promise<unknown> = Promise.resolve();
+	const queue = (sql: string, ...params: D1LikeBindable[]) => {
+		chain = chain.then(() =>
+			db
+				.prepare(sql)
+				.bind(...params)
+				.run(),
+		);
+		writes.add(chain);
+	};
+	const lastActivity = `json_extract(value, '$.lastActivityAt')`;
+
+	return {
+		read: () => snapshot,
+		open: (digest, session) =>
+			queue(
+				`INSERT OR REPLACE INTO ${table} (key, value) VALUES (?, ?)`,
+				prefix + digest,
+				JSON.stringify({ accountId: session.accountId, lastActivityAt: session.lastActivityAt }),
+			),
+		touch: (digest, lastActivityAt) =>
+			queue(
+				`UPDATE ${table} SET value = json_set(value, '$.lastActivityAt', ?2)
+				 WHERE key = ?1 AND json_valid(value) AND ${lastActivity} < ?2`,
+				prefix + digest,
+				lastActivityAt,
+			),
+		expire: (digest, seenLastActivityAt) =>
+			queue(
+				`DELETE FROM ${table} WHERE key = ?1 AND (NOT json_valid(value) OR ${lastActivity} <= ?2)`,
+				prefix + digest,
+				seenLastActivityAt,
+			),
+		closeAll: () => queue(`DELETE FROM ${table} WHERE key >= ? AND key < ?`, low, high),
+	};
+}

package/src/server/metrics/metricsBuffer.ts

@@ -1,4 +1,5 @@
 import type { Database } from 'bun:sqlite';
+import { PLACE_COLUMNS } from './requestPlace.js';
 
 /**
  * In-memory, batched writer for `request_metrics`. To keep request latency
@@ -30,8 +31,10 @@ export interface MetricRow {
   city?: string | null;
 }
 
-/** The optional place columns, in insert order. Each is written only when the table HAS it. */
-export const PLACE_COLUMNS = ['country', 'region', 'city'] as const;
+// Every place column is a `MetricRow` field — a column declared in `requestPlace.ts` that this
+// row cannot carry fails to compile here rather than inserting `undefined` for ever.
+const _placeColumnsAreRowFields: readonly (keyof MetricRow)[] = PLACE_COLUMNS;
+void _placeColumnsAreRowFields;
 
 export interface MetricsBufferOptions {
   db: Database;

package/src/server/metrics/requestPlace.ts

@@ -33,6 +33,15 @@ export interface RequestPlace {
 /** Place one request, or `null` when it cannot. Must not throw — but a throw is caught and read as `null`. */
 export type RequestLocator = (request: Request) => RequestPlace | null;
 
+/**
+ * The place columns, in insert order — the ONE declaration every reader and migration uses
+ * (`metricsBuffer` writes them, an app's reader allows them, an app's migration adds them).
+ * Exported through `cursedbelt-server/telemetry` since 4.29.0 (task 2141): until then it was
+ * private to `metricsBuffer.ts`, so flix, station and desk each declared their own copy, and a
+ * fourth column added here would have been written by the buffer and dropped by all three.
+ */
+export const PLACE_COLUMNS = ['country', 'region', 'city'] as const;
+
 /** Each place field is capped so three of them can never crowd the 5120-byte Analytics Engine blob budget. */
 export const PLACE_FIELD_MAX_CHARS = 96;
 

package/src/server/requestLog/requestMetrics.ts

@@ -63,7 +63,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statS
 import { join } from "node:path";
 import { applyCcPragmas } from "cwip/sqlite";
 import type { MiddlewareHandler } from "hono";
-import { PLACE_COLUMNS } from "../metrics/metricsBuffer.js";
+import { PLACE_COLUMNS } from "../metrics/requestPlace.js";
 import type { RequestLocator } from "../metrics/requestPlace.js";
 import { createTelemetrySink, type TelemetrySink } from "../metrics/telemetrySink.js";
 import { requestLogger } from "../middleware/requestLogger.js";

package/src/server/telemetry.ts

@@ -27,6 +27,7 @@ export {
 } from './metrics/telemetrySink.js';
 export {
 	locateFromCloudflare,
+	PLACE_COLUMNS,
 	type RequestLocator,
 	type RequestPlace,
 } from './metrics/requestPlace.js';

package/src/server/telemetryIsWorkerSafe.spec.ts

@@ -88,6 +88,14 @@ describe('cursedbelt-server/telemetry', () => {
 		const found = [..."import { Database } from 'bun:sqlite';\nimport type { X } from 'bun:sqlite';".matchAll(regex)].map((m) => m[1]);
 		expect(found).toEqual(['bun:sqlite']);
 	});
+
+	test('publishes PLACE_COLUMNS — the one declaration the buffer writes and every app reads (task 2141)', async () => {
+		const telemetry = await import('./telemetry.ts');
+		expect(telemetry.PLACE_COLUMNS).toEqual(['country', 'region', 'city']);
+		// The same array the Bun buffer inserts from, not a second copy of it.
+		const { PLACE_COLUMNS } = await import('./metrics/requestPlace.ts');
+		expect(telemetry.PLACE_COLUMNS).toBe(PLACE_COLUMNS);
+	});
 });
 
 describe('🔴 cursedbelt-server/engagement/d1 — a Worker mounts it (task 2096)', () => {