@forgezero/runtime 0.1.0 → 0.1.2

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/custody-crypto.d.ts

@@ -0,0 +1,53 @@
+/** The wire shape, identical to the server's `CipherBox`. */
+export interface CipherBox {
+    alg: 'aes-256-gcm';
+    nonce: string;
+    ciphertext: string;
+}
+/** HKDF-SHA256, the same construction and parameter order as `hkdfSync`. */
+export declare function deriveKey(secret: Uint8Array, salt: Uint8Array, info: string, length?: number): Uint8Array;
+/**
+ * Seal under a key, with AAD bound but not encrypted.
+ *
+ * `randomBytes` comes from the platform: `crypto.getRandomValues` exists in
+ * every browser and in Bun, and a nonce from anywhere else is not a nonce.
+ */
+export declare function sealWithKey(key: Uint8Array, plaintext: Uint8Array, aad: string): CipherBox;
+/** Open a box. Throws on a wrong key, a wrong AAD, or any modification. */
+export declare function openWithKey(key: Uint8Array, box: CipherBox, aad: string): Uint8Array;
+/**
+ * Sealing to a PUBLIC key, so the holder of the private half is the only reader.
+ *
+ * This exists because the server was handing custodians their raw Shamir share
+ * and trusting them to report that both envelopes opened. Capturing one
+ * enrolment response therefore bypassed both recovery factors permanently, and
+ * the two factor "tests" were attestations by the client rather than evidence.
+ *
+ * With this, the client derives a wrapping key pair from each factor and sends
+ * only the public halves. The server seals the share to those and never emits
+ * plaintext — so a captured response is ciphertext, and opening it requires the
+ * factor itself.
+ *
+ * X25519 + HKDF-SHA256 + AES-256-GCM, with the ephemeral public key carried in
+ * the box. Nothing bespoke: the ephemeral-static shape is what every sealed-box
+ * construction uses, and doing it by hand is how people lose the AAD.
+ */
+export interface SealedToKey extends CipherBox {
+    /** base64 — the ephemeral public key this box was sealed with. */
+    ephemeral: string;
+}
+/** Seal to a recipient's public key. */
+export declare function sealToKey(recipientPublicKey: Uint8Array, plaintext: Uint8Array, aad: string): SealedToKey;
+/** Open a box sealed to this private key. */
+export declare function openFromKey(recipientSecretKey: Uint8Array, box: SealedToKey, aad: string): Uint8Array;
+/**
+ * A wrapping key pair derived from factor material.
+ *
+ * Deterministic, because a custodian must reproduce the same private key on a
+ * different machine months later from the same passkey or the same words. The
+ * factor never leaves the caller — only the public half is ever sent.
+ */
+export declare function wrappingKeyPair(factorMaterial: Uint8Array, info: string): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};

package/dist/custody-crypto.js

@@ -0,0 +1,89 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/custody-crypto.ts
+import { gcm } from "@noble/ciphers/aes.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+var KEY_BYTES = 32;
+var NONCE_BYTES = 12;
+var toBase64 = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+var fromBase64 = (value) => {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1)
+    bytes[index] = binary.charCodeAt(index);
+  return bytes;
+};
+var utf8 = (value) => new TextEncoder().encode(value);
+function deriveKey(secret, salt, info, length = KEY_BYTES) {
+  return hkdf(sha256, secret, salt, utf8(info), length);
+}
+function sealWithKey(key, plaintext, aad) {
+  if (key.length !== KEY_BYTES)
+    throw new Error("custody: key must be 32 bytes");
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const sealed = gcm(key, nonce, utf8(aad)).encrypt(plaintext);
+  return { alg: "aes-256-gcm", nonce: toBase64(nonce), ciphertext: toBase64(sealed) };
+}
+function openWithKey(key, box, aad) {
+  if (key.length !== KEY_BYTES)
+    throw new Error("custody: key must be 32 bytes");
+  if (box.alg !== "aes-256-gcm")
+    throw new Error(`custody: unknown algorithm ${box.alg}`);
+  return gcm(key, fromBase64(box.nonce), utf8(aad)).decrypt(fromBase64(box.ciphertext));
+}
+var WRAP_INFO = "forgezero:custody:wrap:v1";
+var wrapKey = (shared, ephemeral, recipient) => hkdf(sha256, shared, concatBytes(ephemeral, recipient), utf8(WRAP_INFO), 32);
+function concatBytes(left, right) {
+  const out = new Uint8Array(left.length + right.length);
+  out.set(left, 0);
+  out.set(right, left.length);
+  return out;
+}
+function sealToKey(recipientPublicKey, plaintext, aad) {
+  const ephemeralSecret = x25519.utils.randomSecretKey();
+  const ephemeralPublic = x25519.getPublicKey(ephemeralSecret);
+  const shared = x25519.getSharedSecret(ephemeralSecret, recipientPublicKey);
+  const key = wrapKey(shared, ephemeralPublic, recipientPublicKey);
+  try {
+    return { ...sealWithKey(key, plaintext, aad), ephemeral: toBase64(ephemeralPublic) };
+  } finally {
+    key.fill(0);
+    ephemeralSecret.fill(0);
+  }
+}
+function openFromKey(recipientSecretKey, box, aad) {
+  const ephemeralPublic = fromBase64(box.ephemeral);
+  const recipientPublic = x25519.getPublicKey(recipientSecretKey);
+  const shared = x25519.getSharedSecret(recipientSecretKey, ephemeralPublic);
+  const key = wrapKey(shared, ephemeralPublic, recipientPublic);
+  try {
+    return openWithKey(key, box, aad);
+  } finally {
+    key.fill(0);
+  }
+}
+function wrappingKeyPair(factorMaterial, info) {
+  const secretKey = hkdf(sha256, factorMaterial, utf8("forgezero:custody:wrapkey:v1"), utf8(info), 32);
+  return { secretKey, publicKey: x25519.getPublicKey(secretKey) };
+}
+export {
+  wrappingKeyPair,
+  sealWithKey,
+  sealToKey,
+  openWithKey,
+  openFromKey,
+  deriveKey
+};

package/dist/custody-share.d.ts

@@ -0,0 +1,117 @@
+import { type CipherBox, type SealedToKey } from './custody-crypto';
+export interface SealedShare {
+    shareIndex: number;
+    passkeyEnvelope: CipherBox;
+    phraseEnvelope: CipherBox;
+    /** base64 — the HKDF salt for the phrase key and the verifier. */
+    phraseSalt: string;
+    /** hex — proves the right phrase without being able to rebuild it. */
+    phraseVerifier: string;
+}
+type EnvelopeKind = 'passkey' | 'phrase';
+/** The x-coordinate a share was cut at — its custodian-facing share number. */
+export declare function shareIndexOf(share: Uint8Array): number;
+/**
+ * Seal one share under BOTH factors.
+ *
+ * The two `sealWithKey` calls are siblings: the same `share` goes into each and
+ * neither output is an input to the other. That is what makes recovery an OR —
+ * lose the passkey, open with the phrase.
+ */
+export declare function sealShare(args: {
+    share: Uint8Array;
+    custodianKey: string;
+    passkeyPrfOutput: Uint8Array;
+    phraseWords: string[];
+}): SealedShare;
+/** Open the share with the passkey alone. The phrase is not consulted. */
+export declare function openShareWithPasskey(sealed: SealedShare, custodianKey: string, passkeyPrfOutput: Uint8Array): Uint8Array;
+/** Open the share with the phrase alone. The passkey is not consulted. */
+export declare function openShareWithPhrase(sealed: SealedShare, custodianKey: string, phraseWords: string[]): Uint8Array;
+/**
+ * The public halves a custodian offers so the server can seal to them.
+ *
+ * The server used to hand over the raw Shamir share and trust the client to
+ * report that both envelopes opened. Capturing one enrolment response therefore
+ * bypassed both recovery factors permanently, and the factor "tests" were
+ * attestations rather than evidence.
+ *
+ * These are derived from the factors themselves and are deterministic, so a
+ * custodian reproduces the same private halves months later on a different
+ * machine from the same passkey or the same words. Only the public halves are
+ * ever sent.
+ */
+export interface WrappingKeys {
+    passkeyPublicKey: string;
+    phrasePublicKey: string;
+    phraseSalt: string;
+    phraseVerifier: string;
+}
+/** The private half for one factor. Never leaves the machine that made it. */
+export declare function passkeyWrappingKey(custodianKey: string, passkeyPrfOutput: Uint8Array): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+/** The same for the phrase, over the salt that will be stored beside it. */
+export declare function phraseWrappingKey(custodianKey: string, phraseWords: string[], salt: Uint8Array): {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+/** Everything the server needs, and nothing it must not have. */
+export declare function wrappingKeysFor(args: {
+    custodianKey: string;
+    passkeyPrfOutput: Uint8Array;
+    phraseWords: string[];
+}): WrappingKeys;
+/** Open something the server sealed to one of those public keys. */
+export declare function openSealedToFactor(args: {
+    custodianKey: string;
+    factor: EnvelopeKind;
+    box: SealedToKey;
+    passkeyPrfOutput?: Uint8Array;
+    phraseWords?: string[];
+    phraseSalt?: string;
+}): Uint8Array;
+/** The aad the server must use when sealing to a custodian's factor key. */
+export declare const factorWrapAad: (custodianKey: string, factor: EnvelopeKind) => string;
+/**
+ * A share plus a probe, sealed together.
+ *
+ * The probe is DIFFERENT in each envelope, and that difference is what makes
+ * the two factor tests independent. Sealing only the share would let a client
+ * that opened the passkey envelope answer the phrase test with the same bytes —
+ * proving one factor and being credited with both, which is the attestation
+ * problem this whole change exists to remove.
+ *
+ * Fixed 32-byte probe at the front, so splitting needs no length prefix and a
+ * truncated envelope fails the GCM tag rather than being parsed.
+ */
+export declare const PROBE_BYTES = 32;
+export declare function joinProbeAndShare(probe: Uint8Array, share: Uint8Array): Uint8Array;
+export declare function splitProbeAndShare(opened: Uint8Array): {
+    probe: Uint8Array;
+    share: Uint8Array;
+};
+/**
+ * Open one factor's envelope from the sealed record.
+ *
+ * Takes the whole record rather than a single box, because the phrase salt
+ * lives IN that record and is public — asking every caller to carry it
+ * separately meant each one had somewhere to lose it, and losing it surfaces as
+ * `atob` complaining about invalid characters rather than as anything about
+ * custody.
+ */
+export declare function openFactorEnvelope(args: {
+    sealed: SealedShare & {
+        passkeyEnvelope: SealedToKey;
+        phraseEnvelope: SealedToKey;
+    };
+    custodianKey: string;
+    factor: EnvelopeKind;
+    passkeyPrfOutput?: Uint8Array;
+    phraseWords?: string[];
+}): {
+    probe: Uint8Array;
+    share: Uint8Array;
+};
+export {};