@forgezero/runtime 0.1.1 → 0.1.3

package/README.md

@@ -5,7 +5,7 @@ themselves, keyed queues, a transactional outbox, a hash-chained audit trail,
 templated mail, encrypted backups, schema validation, and money that is never a
 floating-point number.
 
-Twenty-six modules. Each is its own entry point, so you install one package and
+Thirty-three public modules. Each is its own entry point, so you install one package and
 your bundler includes only what you imported.
 
 ```bash
@@ -24,7 +24,7 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 
 | | |
 |---|---|
-| **Spine** | `jobs` `queue` `serial` `outbox` |
+| **Spine** | `jobs` `queue` `outbox` |
 | **Record** | `audit` `backup` `compliance` `calendar` |
 | **Identity** | `identity` `totp` `notify` `notify/templates` `schema` `schema/typebox` |
 | **Finance** | `finance/money` `finance/storage` `finance/ledger` `finance/commission` `finance/rates` `finance/transfers` `finance/tax` `finance/chain` `finance/custody` `finance/derive` `finance/venues` `finance/binance` |
@@ -32,6 +32,29 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 None of it knows what your product does. You bind your own rules to these; you
 do not fork them.
 
+## One reusable async queue
+
+`queue` is deliberately memory-only: it accepts a function, returns that
+function's value through a Promise, runs one key sequentially, and runs
+different keys in parallel. Persistence and cluster ownership remain in the
+business layer that knows what a pending request means; ForgeZero uses an
+ArangoDB unique claim, while another caller may use any database or no database.
+
+```ts
+import { createQueue } from '@forgezero/runtime/queue';
+
+const queue = createQueue({ width: 8 });
+const task = queue.run('tenant-a:wallet-7', transfer, amount, destination);
+const receipt = await task.result;
+
+queue.pauseKey('tenant-a:wallet-7');
+queue.resumeKey('tenant-a:wallet-7');
+queue.stopKey('tenant-a:wallet-7'); // running finishes; pending is rejected
+queue.startKey('tenant-a:wallet-7');
+queue.cancel(task.id);               // pending task only
+await queue.stop(30_000);            // close intake and drain all work
+```
+
 ## Three things worth knowing before you use it
 
 **Money is never a number.** An amount is minor units as a `bigint` with its
@@ -81,9 +104,9 @@ node_modules/@forgezero/runtime/contracts/src/
   ColdVault.sol        M-of-N EIP-712, signatures ordered by ascending signer
 ```
 
-Full documentation: **https://forgezero.net/docs/runtime**
+Full documentation: **https://www.forgezero.net/docs/runtime**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys — and usable entirely on its own, with no ForgeZero account.

package/dist/audit.js

@@ -6,32 +6,271 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
-// src/serial.ts
-function createKeyedSerial(options = {}) {
-  const maxKeys = options.maxKeys ?? 1e4;
-  const chains = new Map;
-  return {
-    run(key, work) {
-      const previous = chains.get(key) ?? Promise.resolve();
-      const next = previous.then(work, work);
-      const settled = next.then(() => {
+// src/queue.ts
+class QueueStoppedError extends Error {
+  constructor() {
+    super("queue: stopped before this task could run");
+    this.name = "QueueStoppedError";
+  }
+}
+
+class QueueKeyStoppedError extends Error {
+  key;
+  constructor(key) {
+    super(`queue: key ${key} is stopped`);
+    this.key = key;
+    this.name = "QueueKeyStoppedError";
+  }
+}
+
+class TaskCancelledError extends Error {
+  constructor() {
+    super("queue: task cancelled");
+    this.name = "TaskCancelledError";
+  }
+}
+var DEFAULT_RETRY = {
+  attempts: 1,
+  backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
+};
+function createQueue(options = {}) {
+  const width = options.width ?? 8;
+  const retry = { ...DEFAULT_RETRY, ...options.retry };
+  if (!Number.isSafeInteger(width) || width < 1) {
+    throw new RangeError("queue: width must be a positive integer");
+  }
+  if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
+    throw new RangeError("queue: retry attempts must be a positive integer");
+  }
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const lanes = new Map;
+  const running = new Set;
+  const paused = new Set;
+  const stoppedKeys = new Set;
+  let sequence = 0;
+  let globallyPaused = false;
+  let accepting = true;
+  let aborted = false;
+  let completed = 0;
+  let failed = 0;
+  const idle = [];
+  const announceIdle = () => {
+    if (running.size > 0)
+      return;
+    for (const lane of lanes.values())
+      if (lane.length > 0)
         return;
-      }, () => {
+    while (idle.length > 0)
+      idle.shift()();
+  };
+  function pump() {
+    if (globallyPaused || aborted) {
+      announceIdle();
+      return;
+    }
+    for (const [key, lane] of lanes) {
+      if (running.size >= width)
+        break;
+      if (running.has(key) || paused.has(key) || lane.length === 0)
+        continue;
+      execute(key);
+    }
+    announceIdle();
+  }
+  async function execute(key) {
+    running.add(key);
+    try {
+      const lane = lanes.get(key);
+      const entry = lane?.[0];
+      if (entry && !globallyPaused && !paused.has(key) && !aborted) {
+        lane.shift();
+        await attempt(entry);
+      }
+    } finally {
+      running.delete(key);
+      const remaining = lanes.get(key);
+      if (remaining?.length === 0)
+        lanes.delete(key);
+      else if (remaining) {
+        lanes.delete(key);
+        lanes.set(key, remaining);
+      }
+      pump();
+    }
+  }
+  async function attempt(entry) {
+    if (entry.cancelled) {
+      entry.reject(new TaskCancelledError);
+      return;
+    }
+    for (;; ) {
+      entry.attempt += 1;
+      try {
+        const value = await entry.run();
+        completed += 1;
+        entry.resolve(value);
         return;
+      } catch (cause) {
+        if (entry.attempt >= retry.attempts || entry.cancelled || aborted) {
+          failed += 1;
+          entry.reject(cause);
+          return;
+        }
+        const delay = retry.backoffMs(entry.attempt);
+        if (!Number.isFinite(delay) || delay < 0) {
+          failed += 1;
+          entry.reject(new RangeError("queue: retry backoff must be a non-negative finite number"));
+          return;
+        }
+        await sleep(delay);
+      }
+    }
+  }
+  return {
+    run(key, handler, ...args) {
+      const id = `q_${++sequence}`;
+      if (!accepting || stoppedKeys.has(key)) {
+        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+        refused.catch(() => {
+          return;
+        });
+        return { id, key, result: refused };
+      }
+      let resolve;
+      let reject;
+      const result = new Promise((ok, no) => {
+        resolve = ok;
+        reject = no;
       });
-      chains.set(key, settled);
-      settled.then(() => {
-        if (chains.get(key) === settled)
-          chains.delete(key);
-      });
-      if (chains.size > maxKeys) {
-        console.warn(`[serial] ${chains.size} keys in flight, above the ${maxKeys} guideline.`);
+      const entry = {
+        id,
+        key,
+        run: async () => handler(...args),
+        resolve,
+        reject,
+        attempt: 0,
+        cancelled: false
+      };
+      const lane = lanes.get(key);
+      if (lane)
+        lane.push(entry);
+      else
+        lanes.set(key, [entry]);
+      pump();
+      return { id, key, result };
+    },
+    cancel(id) {
+      for (const [key, lane] of lanes) {
+        const index = lane.findIndex((entry2) => entry2.id === id);
+        if (index === -1)
+          continue;
+        const [entry] = lane.splice(index, 1);
+        entry.cancelled = true;
+        entry.reject(new TaskCancelledError);
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+        announceIdle();
+        return true;
+      }
+      return false;
+    },
+    pauseKey(key) {
+      paused.add(key);
+    },
+    resumeKey(key) {
+      paused.delete(key);
+      pump();
+    },
+    stopKey(key) {
+      stoppedKeys.add(key);
+      paused.delete(key);
+      const lane = lanes.get(key);
+      if (!lane)
+        return 0;
+      let removed = 0;
+      for (const entry of lane.splice(0)) {
+        removed += 1;
+        entry.cancelled = true;
+        entry.reject(new QueueKeyStoppedError(key));
+      }
+      if (!running.has(key))
+        lanes.delete(key);
+      announceIdle();
+      return removed;
+    },
+    startKey(key) {
+      const changed = stoppedKeys.delete(key);
+      pump();
+      return changed;
+    },
+    pause() {
+      globallyPaused = true;
+    },
+    resume() {
+      globallyPaused = false;
+      pump();
+    },
+    snapshot() {
+      let queued = 0;
+      for (const lane of lanes.values())
+        queued += lane.length;
+      return {
+        running: running.size,
+        queued,
+        keys: lanes.size,
+        paused: globallyPaused,
+        pausedKeys: [...paused],
+        stoppedKeys: [...stoppedKeys],
+        completed,
+        failed
+      };
+    },
+    whenIdle() {
+      if (running.size === 0 && [...lanes.values()].every((lane) => lane.length === 0)) {
+        return Promise.resolve();
       }
-      return next;
+      return new Promise((resolve) => idle.push(resolve));
     },
-    size: () => chains.size,
-    drain: async () => {
-      await Promise.allSettled([...chains.values()]);
+    async stop(deadlineMs = 30000) {
+      if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 0) {
+        throw new RangeError("queue: stop deadline must be a non-negative integer");
+      }
+      accepting = false;
+      const before = { completed, failed };
+      globallyPaused = false;
+      paused.clear();
+      pump();
+      let timedOut = false;
+      let deadlineHandle;
+      const deadline = new Promise((resolve) => {
+        deadlineHandle = setTimeout(() => {
+          timedOut = true;
+          resolve();
+        }, deadlineMs);
+      });
+      await Promise.race([this.whenIdle(), deadline]);
+      if (!timedOut && deadlineHandle !== undefined)
+        clearTimeout(deadlineHandle);
+      if (timedOut)
+        aborted = true;
+      let abandoned = 0;
+      for (const lane of lanes.values()) {
+        abandoned += lane.length;
+        for (const entry of lane.splice(0))
+          entry.reject(new QueueStoppedError);
+      }
+      abandoned += running.size;
+      for (const [key, lane] of lanes) {
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+      }
+      announceIdle();
+      return {
+        completed: completed - before.completed,
+        failed: failed - before.failed,
+        abandoned,
+        timedOut
+      };
     }
   };
 }
@@ -201,8 +440,8 @@ async function verifyExport(slice, options = {}) {
 }
 function createAuditChain(options) {
   const digester = options.digester ?? hashDigester;
-  const serial = createKeyedSerial();
-  const enqueue = (realm, run) => serial.run(realm ?? "\x00platform", run);
+  const queue = createQueue();
+  const enqueue = (realm, run) => queue.run(realm ?? "\x00platform", run).result;
   return {
     append: (entry) => enqueue(entry.realm, () => appendRecord(options.store, entry, { ...options, digester })),
     verify: async (realm, fromSequence = 1, toSequence = Number.MAX_SAFE_INTEGER) => {

package/dist/identity.d.ts

@@ -64,6 +64,28 @@ export interface SignedEnvelope {
     edSignature: string;
     mlDsaSignature: string;
 }
+export interface ResponseRecipient {
+    publicKey: string;
+    secretKey: string;
+}
+export interface SealedResponse {
+    version: 1;
+    kemCiphertext: string;
+    nonce: string;
+    ciphertext: string;
+}
+export declare const RESPONSE_KEY_HEADER = "x-fz-response-key";
+export declare function validResponsePublicKey(value: string): boolean;
+/** One ephemeral hybrid ML-KEM-768 + X25519 recipient per request. */
+export declare function generateResponseRecipient(): ResponseRecipient;
+/** Seal one JSON response so TLS termination never sees the secret payload. */
+export declare function sealResponse<T>(recipientPublicKey: string, requestBinding: string, payload: T): Promise<SealedResponse>;
+/** Open a response only with the request's ephemeral private half and exact signature binding. */
+export declare function openResponse<T>(recipientSecretKey: string, requestBinding: string, envelope: SealedResponse): Promise<T>;
+/** One wire encoding for Agent and external API-key hybrid signatures. */
+export declare function encodeSignatureHeader(envelope: SignedEnvelope): string;
+/** Parse the common wire encoding and bind its public key id from the companion header. */
+export declare function decodeSignatureHeader(raw: string, nodeKey: string): SignedEnvelope | null;
 /**
  * The bytes that get signed.
  *
@@ -79,12 +101,14 @@ export declare function canonicalString(args: {
     timestamp: number;
     nonce: string;
     body: string | Uint8Array;
+    responseKey?: string;
 }): string;
 export declare function signRequest(keys: NodeKeyPair, nodeKey: string, args: {
     method: string;
     path: string;
     query?: string;
     body: string | Uint8Array;
+    responseKey?: string;
 }): SignedEnvelope;
 export type VerifyFailure = 'timestamp_out_of_window' | 'ed25519_invalid' | 'ml_dsa_invalid' | 'malformed';
 /** Requests older or newer than this are refused before any signature work. */
@@ -106,6 +130,7 @@ export declare function verifyRequest(args: {
     path: string;
     query?: string;
     body: string | Uint8Array;
+    responseKey?: string;
     nowSeconds?: number;
 }): {
     verified: true;

package/dist/identity.js

@@ -10,6 +10,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 import { toBase64Url, fromBase64Url } from "@forgezero/access/security";
 import { ed25519 } from "@noble/curves/ed25519.js";
 import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { ml_kem768_x25519 } from "@noble/post-quantum/hybrid.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
 var ENCODER = new TextEncoder;
@@ -41,17 +42,104 @@ function generateNodeKeys() {
     mlDsa: { publicKey: b64(mlKeys.publicKey), secretKey: b64(mlKeys.secretKey) }
   };
 }
+var RESPONSE_KEY_HEADER = "x-fz-response-key";
+function validResponsePublicKey(value) {
+  try {
+    return un64(value).length === ml_kem768_x25519.lengths.publicKey;
+  } catch {
+    return false;
+  }
+}
+function generateResponseRecipient() {
+  const pair = ml_kem768_x25519.keygen();
+  return { publicKey: b64(pair.publicKey), secretKey: b64(pair.secretKey) };
+}
+var responseKey = (sharedSecret) => hkdf(sha256, sharedSecret, undefined, ENCODER.encode("forgezero/response/ml-kem-768+x25519/v1"), 32);
+async function sealResponse(recipientPublicKey, requestBinding, payload) {
+  const { cipherText, sharedSecret } = ml_kem768_x25519.encapsulate(un64(recipientPublicKey));
+  const rawKey = responseKey(sharedSecret);
+  sharedSecret.fill(0);
+  const key = await crypto.subtle.importKey("raw", new Uint8Array(rawKey), "AES-GCM", false, ["encrypt"]);
+  rawKey.fill(0);
+  const nonce = randomBytes(12);
+  const serialized = JSON.stringify(payload);
+  if (serialized === undefined)
+    throw new Error("response: payload is not JSON serializable");
+  const plaintext = ENCODER.encode(serialized);
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv: new Uint8Array(nonce),
+    additionalData: new Uint8Array(ENCODER.encode(requestBinding)),
+    tagLength: 128
+  }, key, new Uint8Array(plaintext));
+  plaintext.fill(0);
+  return {
+    version: 1,
+    kemCiphertext: b64(cipherText),
+    nonce: b64(nonce),
+    ciphertext: b64(new Uint8Array(ciphertext))
+  };
+}
+async function openResponse(recipientSecretKey, requestBinding, envelope) {
+  if (envelope?.version !== 1)
+    throw new Error("response: unsupported sealed response");
+  const sharedSecret = ml_kem768_x25519.decapsulate(un64(envelope.kemCiphertext), un64(recipientSecretKey));
+  const rawKey = responseKey(sharedSecret);
+  sharedSecret.fill(0);
+  const key = await crypto.subtle.importKey("raw", new Uint8Array(rawKey), "AES-GCM", false, ["decrypt"]);
+  rawKey.fill(0);
+  const decrypted = new Uint8Array(await crypto.subtle.decrypt({
+    name: "AES-GCM",
+    iv: new Uint8Array(un64(envelope.nonce)),
+    additionalData: new Uint8Array(ENCODER.encode(requestBinding)),
+    tagLength: 128
+  }, key, new Uint8Array(un64(envelope.ciphertext))));
+  try {
+    return JSON.parse(new TextDecoder().decode(decrypted));
+  } finally {
+    decrypted.fill(0);
+  }
+}
+var SIGNATURE_FIELDS = (envelope) => ({
+  timestamp: envelope.timestamp,
+  nonce: envelope.nonce,
+  edSignature: envelope.edSignature,
+  mlDsaSignature: envelope.mlDsaSignature
+});
+function encodeSignatureHeader(envelope) {
+  return b64(ENCODER.encode(JSON.stringify(SIGNATURE_FIELDS(envelope))));
+}
+function decodeSignatureHeader(raw, nodeKey) {
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(un64(raw)));
+  } catch {
+    return null;
+  }
+  if (typeof parsed.timestamp !== "number" || !Number.isSafeInteger(parsed.timestamp) || typeof parsed.nonce !== "string" || typeof parsed.edSignature !== "string" || typeof parsed.mlDsaSignature !== "string")
+    return null;
+  return {
+    nodeKey,
+    timestamp: parsed.timestamp,
+    nonce: parsed.nonce,
+    edSignature: parsed.edSignature,
+    mlDsaSignature: parsed.mlDsaSignature
+  };
+}
 function canonicalString(args) {
   const body = typeof args.body === "string" ? ENCODER.encode(args.body) : args.body;
   const digest = Array.from(sha256(body), (byte) => byte.toString(16).padStart(2, "0")).join("");
-  return [
+  const fields = [
     args.method.toUpperCase(),
     args.path,
     args.query ?? "",
     String(args.timestamp),
     args.nonce,
     digest
-  ].join(`
+  ];
+  if (args.responseKey)
+    fields.push(args.responseKey);
+  return fields.join(`
 `);
 }
 function signRequest(keys, nodeKey, args) {
@@ -80,7 +168,8 @@ function verifyRequest(args) {
       query: args.query ?? "",
       timestamp: args.envelope.timestamp,
       nonce: args.envelope.nonce,
-      body: args.body
+      body: args.body,
+      responseKey: args.responseKey
     }));
   } catch {
     return { verified: false, reason: "malformed" };
@@ -103,9 +192,16 @@ function verifyRequest(args) {
 }
 export {
   verifyRequest,
+  validResponsePublicKey,
   signRequest,
+  sealResponse,
+  openResponse,
+  generateResponseRecipient,
   generateNodeKeys,
+  encodeSignatureHeader,
   deriveKeysFromSeed,
+  decodeSignatureHeader,
   canonicalString,
+  RESPONSE_KEY_HEADER,
   CLOCK_SKEW_SECONDS
 };

package/dist/jobs.d.ts

@@ -15,11 +15,12 @@
  *
  * Each has a specific answer here: reschedule after completion rather than on
  * an interval, advance only on a fully successful batch, take a fenced lock,
- * and await in-flight work on stop.
+ * and submit every run through the common awaited queue, which drains on stop.
  *
  * Zero dependencies. The lock and the cursor store are interfaces, so this runs
  * against a database, Redis, or nothing at all in a test.
  */
+import { type DrainReport } from './queue';
 /** Injected so a test does not sleep and a resumed run is reproducible. */
 export interface Clock {
     now(): number;
@@ -122,7 +123,7 @@ export declare function createScheduler(options: SchedulerOptions): {
      * leaves a record half-written — the process exits mid-transaction and the
      * next boot finds state nothing can explain.
      */
-    stop(): Promise<void>;
+    stop(deadlineMs?: number): Promise<DrainReport>;
     /** Timers stop firing; in-flight work is left to finish. */
     pause(): void;
     resume(): void;