@substrat-run/kernel 0.162.0 → 0.164.0

package/dist/wire-nonce.d.ts

@@ -0,0 +1,80 @@
+import type { SwitchSql } from './system-switch.js';
+/**
+ * The wire-signing nonce store (RFC wire-signing §4, Q4 as amended): where a scope records the
+ * nonce of each signed call it accepted that changes state, so the same envelope is accepted once.
+ *
+ * The verifier in the platform's entry claims a nonce here only after every other check of the
+ * envelope has passed, and only in the scope the verified envelope names, through the scope host's
+ * `claimWireNonceLocal`. Both adapters build these tables from this one definition and claim
+ * through `claimWireNonceIn`, so the self-hosted store and the hosted one answer alike.
+ *
+ * Kernel-written spine, never a module migration. **Store-local**: the tables describe calls this
+ * store accepted, not the scope's data, so a dump never carries them and no load takes them from
+ * one (`isWireNonceTable`), and a write to them advances no write revision a carry fences on
+ * (`isWireNonceWrite`). A load, restore, wipe or delete replaces the store, and the nonces recorded
+ * before it go with it, as a rewind drops those recorded after its bookmark, for the rest of their
+ * window. That window is short by design: an envelope lives at most two minutes.
+ */
+/**
+ * The live nonces, one row each, and the count of them. `until_s` is the integer Unix second after
+ * which a nonce may be forgotten (the envelope's `exp` plus the skew), and departs from the spine's
+ * ISO-text rule on purpose: the envelope states its times in Unix seconds and every comparison
+ * here is numeric, so text would add a conversion at both ends and change nothing.
+ *
+ * The count is a row of its own so that the cap costs one row read, not a scan: a claim keeps it in
+ * step with the rows it inserts and purges, in the same transaction.
+ */
+export declare const WIRE_NONCE_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_wire_nonces (\n    -- The envelope's nonce: 16 random bytes in canonical base64url, 22 characters.\n    nonce TEXT PRIMARY KEY,\n    -- Integer Unix seconds, not ISO text: the envelope's own unit, compared numerically.\n    until_s INTEGER NOT NULL\n  ) WITHOUT ROWID;\n  CREATE INDEX IF NOT EXISTS _substrat_wire_nonces_until\n    ON _substrat_wire_nonces (until_s);\n  -- One row, slot 'live': how many rows _substrat_wire_nonces holds. Absent until the first claim.\n  CREATE TABLE IF NOT EXISTS _substrat_wire_nonce_count (\n    slot TEXT PRIMARY KEY,\n    live INTEGER NOT NULL\n  ) WITHOUT ROWID;\n";
+/** The tables `WIRE_NONCE_DDL` builds: store-local, so no dump carries them. */
+export declare const WIRE_NONCE_TABLE_NAMES: readonly ['_substrat_wire_nonces', '_substrat_wire_nonce_count'];
+/** Whether a table is one of the nonce store's, which a dump leaves out. Case-insensitive, as SQLite names are. */
+export declare const isWireNonceTable: (name: string) => boolean;
+/**
+ * The most live nonces one scope holds. Past it a claim throws, which the entry answers as the
+ * store's failure (fail closed, and counted), never as acceptance.
+ *
+ * Sized from what one scope can be asked, not from a guess:
+ * - **How long a row lives.** A nonce is kept until `exp + 30` and can be claimed no earlier than
+ *   `iat - 30`, and an envelope lives at most 120 s, so a row lives at most 120 + 30 + 30 = 180 s.
+ * - **The platform's peak.** The control plane's calls that spend a nonce in a scope are made one
+ *   at a time per scope (each awaits the last), and the busy paths that move many calls (a restore's
+ *   pages, the drain, an event import) name the scope alone, so they spend none here. A sequential
+ *   loop at a 10 ms round trip makes at most 100 calls a second: 100 × 180 = 18 000 rows. Ten times
+ *   that is 180 000.
+ * - **The object's own ceiling.** A claim is itself one request to the scope's object, which serves
+ *   about 1 000 requests a second (`docs/master-plan.md`): 1 000 × 180 = 180 000 rows. No scope can
+ *   reach the cap without first exceeding what its object can serve.
+ *
+ * At about 50 bytes a row, a full store is about 9 MB of a scope's 10 GB.
+ */
+export declare const WIRE_NONCE_CAP = 180000;
+/**
+ * At most this many expired rows go per claim. A claim inserts at most one, so the purge outpaces
+ * the inserts, and a claim's write stays bounded however many rows expired at once.
+ */
+export declare const WIRE_NONCE_PURGE_BATCH = 64;
+/**
+ * Whether a statement is one of the claim's own writes, whitespace aside. The scope DO lets these,
+ * and only these, through the bookkeeping path that advances no write revision: a nonce describes
+ * a call this store accepted, not the scope's data, and a carried copy is another deployment, whose
+ * audience check refuses an envelope meant for this one anyway.
+ */
+export declare const isWireNonceWrite: (sql: string) => boolean;
+/** What a claim answers: the nonce was unspent (`true`), spent or too late (`false`), or the store is at its cap. */
+export type WireNonceClaim = true | false | 'full';
+/**
+ * Claim `nonce` until `until` (Unix seconds) in one scope's store, at `nowSeconds` by the store's
+ * own clock. Run it inside one transaction: it purges up to `WIRE_NONCE_PURGE_BATCH` expired rows,
+ * then answers `false` for a claim after `until` (the nonce may already be forgotten) or a nonce
+ * already held (at the cap too), `'full'` when the store holds `cap` live rows, and `true` once it
+ * has recorded the nonce. A claim the store's own clock places after `until` answers `false` like a
+ * replay; the verifier counts it as one, which only its last second can see. `'full'` is answered rather than thrown so that the purge before it still commits: the
+ * caller throws after the transaction, and a store that filled up drains as its rows expire.
+ *
+ * A nonce that is not 22 characters of base64url, or an `until` or a clock that is not a
+ * non-negative safe integer, is the caller's fault and throws before anything is written.
+ */
+export declare function claimWireNonceIn(sql: SwitchSql, nonce: string, until: number, nowSeconds: number, cap?: number): WireNonceClaim;
+/** What a claim at the cap throws, after its purge committed: the entry answers it as the store's failure. */
+export declare const WIRE_NONCE_FULL = "the wire nonce store holds as many live nonces as it may; a claim is refused until some expire";
+//# sourceMappingURL=wire-nonce.d.ts.map

package/dist/wire-nonce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-nonce.d.ts","sourceRoot":"","sources":["../src/wire-nonce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,0oBAc1B,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,YAAI,uBAAuB,EAAE,4BAA4B,CAAU,CAAC;AAIvG,mHAAmH;AACnH,eAAO,MAAM,gBAAgB,SAAU,MAAM,KAAG,OAA+C,CAAC;AAEhG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAQzC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAS,MAAM,KAAG,OAAsD,CAAC;AAKtG,qHAAqH;AACrH,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAuB,GAC3B,cAAc,CAoBhB;AAED,8GAA8G;AAC9G,eAAO,MAAM,eAAe,mGAAmG,CAAC"}

package/dist/wire-nonce.js

@@ -0,0 +1,126 @@
+/**
+ * The wire-signing nonce store (RFC wire-signing §4, Q4 as amended): where a scope records the
+ * nonce of each signed call it accepted that changes state, so the same envelope is accepted once.
+ *
+ * The verifier in the platform's entry claims a nonce here only after every other check of the
+ * envelope has passed, and only in the scope the verified envelope names, through the scope host's
+ * `claimWireNonceLocal`. Both adapters build these tables from this one definition and claim
+ * through `claimWireNonceIn`, so the self-hosted store and the hosted one answer alike.
+ *
+ * Kernel-written spine, never a module migration. **Store-local**: the tables describe calls this
+ * store accepted, not the scope's data, so a dump never carries them and no load takes them from
+ * one (`isWireNonceTable`), and a write to them advances no write revision a carry fences on
+ * (`isWireNonceWrite`). A load, restore, wipe or delete replaces the store, and the nonces recorded
+ * before it go with it, as a rewind drops those recorded after its bookmark, for the rest of their
+ * window. That window is short by design: an envelope lives at most two minutes.
+ */
+/**
+ * The live nonces, one row each, and the count of them. `until_s` is the integer Unix second after
+ * which a nonce may be forgotten (the envelope's `exp` plus the skew), and departs from the spine's
+ * ISO-text rule on purpose: the envelope states its times in Unix seconds and every comparison
+ * here is numeric, so text would add a conversion at both ends and change nothing.
+ *
+ * The count is a row of its own so that the cap costs one row read, not a scan: a claim keeps it in
+ * step with the rows it inserts and purges, in the same transaction.
+ */
+export const WIRE_NONCE_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_wire_nonces (
+    -- The envelope's nonce: 16 random bytes in canonical base64url, 22 characters.
+    nonce TEXT PRIMARY KEY,
+    -- Integer Unix seconds, not ISO text: the envelope's own unit, compared numerically.
+    until_s INTEGER NOT NULL
+  ) WITHOUT ROWID;
+  CREATE INDEX IF NOT EXISTS _substrat_wire_nonces_until
+    ON _substrat_wire_nonces (until_s);
+  -- One row, slot 'live': how many rows _substrat_wire_nonces holds. Absent until the first claim.
+  CREATE TABLE IF NOT EXISTS _substrat_wire_nonce_count (
+    slot TEXT PRIMARY KEY,
+    live INTEGER NOT NULL
+  ) WITHOUT ROWID;
+`;
+/** The tables `WIRE_NONCE_DDL` builds: store-local, so no dump carries them. */
+export const WIRE_NONCE_TABLE_NAMES = ['_substrat_wire_nonces', '_substrat_wire_nonce_count'];
+const NONCE_TABLES = new Set(WIRE_NONCE_TABLE_NAMES);
+/** Whether a table is one of the nonce store's, which a dump leaves out. Case-insensitive, as SQLite names are. */
+export const isWireNonceTable = (name) => NONCE_TABLES.has(name.toLowerCase());
+/**
+ * The most live nonces one scope holds. Past it a claim throws, which the entry answers as the
+ * store's failure (fail closed, and counted), never as acceptance.
+ *
+ * Sized from what one scope can be asked, not from a guess:
+ * - **How long a row lives.** A nonce is kept until `exp + 30` and can be claimed no earlier than
+ *   `iat - 30`, and an envelope lives at most 120 s, so a row lives at most 120 + 30 + 30 = 180 s.
+ * - **The platform's peak.** The control plane's calls that spend a nonce in a scope are made one
+ *   at a time per scope (each awaits the last), and the busy paths that move many calls (a restore's
+ *   pages, the drain, an event import) name the scope alone, so they spend none here. A sequential
+ *   loop at a 10 ms round trip makes at most 100 calls a second: 100 × 180 = 18 000 rows. Ten times
+ *   that is 180 000.
+ * - **The object's own ceiling.** A claim is itself one request to the scope's object, which serves
+ *   about 1 000 requests a second (`docs/master-plan.md`): 1 000 × 180 = 180 000 rows. No scope can
+ *   reach the cap without first exceeding what its object can serve.
+ *
+ * At about 50 bytes a row, a full store is about 9 MB of a scope's 10 GB.
+ */
+export const WIRE_NONCE_CAP = 180_000;
+/**
+ * At most this many expired rows go per claim. A claim inserts at most one, so the purge outpaces
+ * the inserts, and a claim's write stays bounded however many rows expired at once.
+ */
+export const WIRE_NONCE_PURGE_BATCH = 64;
+/** The statements a claim writes with, whitespace aside: the only writes `isWireNonceWrite` admits. */
+const PURGE_SQL = `DELETE FROM _substrat_wire_nonces WHERE nonce IN (SELECT nonce FROM _substrat_wire_nonces WHERE until_s < ? ORDER BY until_s LIMIT ${WIRE_NONCE_PURGE_BATCH}) RETURNING nonce`;
+const INSERT_SQL = `INSERT INTO _substrat_wire_nonces (nonce, until_s) VALUES (?, ?) ON CONFLICT (nonce) DO NOTHING RETURNING nonce`;
+const COUNT_WRITE_SQL = `INSERT INTO _substrat_wire_nonce_count (slot, live) VALUES ('live', ?) ON CONFLICT (slot) DO UPDATE SET live = excluded.live`;
+const WRITES = new Set([PURGE_SQL, INSERT_SQL, COUNT_WRITE_SQL]);
+/**
+ * Whether a statement is one of the claim's own writes, whitespace aside. The scope DO lets these,
+ * and only these, through the bookkeeping path that advances no write revision: a nonce describes
+ * a call this store accepted, not the scope's data, and a carried copy is another deployment, whose
+ * audience check refuses an envelope meant for this one anyway.
+ */
+export const isWireNonceWrite = (sql) => WRITES.has(sql.trim().replace(/\s+/g, ' '));
+/** 16 bytes in canonical base64url: 22 characters, the last one's unused trailing bits zero. */
+const NONCE = /^[A-Za-z0-9_-]{21}[AQgw]$/;
+/**
+ * Claim `nonce` until `until` (Unix seconds) in one scope's store, at `nowSeconds` by the store's
+ * own clock. Run it inside one transaction: it purges up to `WIRE_NONCE_PURGE_BATCH` expired rows,
+ * then answers `false` for a claim after `until` (the nonce may already be forgotten) or a nonce
+ * already held (at the cap too), `'full'` when the store holds `cap` live rows, and `true` once it
+ * has recorded the nonce. A claim the store's own clock places after `until` answers `false` like a
+ * replay; the verifier counts it as one, which only its last second can see. `'full'` is answered rather than thrown so that the purge before it still commits: the
+ * caller throws after the transaction, and a store that filled up drains as its rows expire.
+ *
+ * A nonce that is not 22 characters of base64url, or an `until` or a clock that is not a
+ * non-negative safe integer, is the caller's fault and throws before anything is written.
+ */
+export function claimWireNonceIn(sql, nonce, until, nowSeconds, cap = WIRE_NONCE_CAP) {
+    if (typeof nonce !== 'string' || !NONCE.test(nonce))
+        throw new TypeError('a wire nonce is 22 characters of canonical base64url');
+    for (const [name, value] of [['until', until], ['nowSeconds', nowSeconds]]) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new TypeError(`${name} is a non-negative whole number of seconds`);
+    }
+    // No count row yet means no nonce yet: the row is written with the first one. Never below zero,
+    // so a count that ever fell behind its rows cannot lift the cap.
+    let live = Math.max(0, Number(sql.all(`SELECT live FROM _substrat_wire_nonce_count WHERE slot = 'live'`)[0]?.live ?? 0));
+    const before = live;
+    live = Math.max(0, live - sql.all(PURGE_SQL, nowSeconds).length);
+    let answer;
+    if (nowSeconds > until)
+        answer = false;
+    // At the cap a nonce already held is still a replay: the one extra read is paid only there.
+    else if (live >= cap)
+        answer = sql.all('SELECT 1 FROM _substrat_wire_nonces WHERE nonce = ?', nonce).length ? false : 'full';
+    else if (sql.all(INSERT_SQL, nonce, until).length === 1) {
+        live += 1;
+        answer = true;
+    }
+    else
+        answer = false;
+    if (live !== before)
+        sql.run(COUNT_WRITE_SQL, live);
+    return answer;
+}
+/** What a claim at the cap throws, after its purge committed: the entry answers it as the store's failure. */
+export const WIRE_NONCE_FULL = 'the wire nonce store holds as many live nonces as it may; a claim is refused until some expire';
+//# sourceMappingURL=wire-nonce.js.map

package/dist/wire-nonce.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/kernel",
-  "version": "0.162.0",
+  "version": "0.164.0",
   "description": "Substrat kernel contracts and services — pure TypeScript, no platform imports (D-14)",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -34,7 +34,7 @@
     "dist"
   ],
   "dependencies": {
-    "@substrat-run/contracts": "^0.162.0"
+    "@substrat-run/contracts": "^0.164.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",