@serfab/cadre-core 0.9.0 → 0.11.0

package/src/canonical-json.ts

@@ -1,30 +1,30 @@
-/**
- * Canonical JSON serialization for signed payloads.
- *
- * Recursively sorts object keys, drops `undefined` values, emits no whitespace
- * and no trailing newline. Arrays preserve their order. This is a tiny RFC 8785
- * subset, sufficient for the fixed-shape payloads we sign (update manifests in
- * cadre-host, control-network seeds here).
- *
- * Lives in cadre-core because cadre-host depends on cadre-core (not the
- * reverse); cadre-host re-imports this rather than keeping its own copy.
- */
-export function canonicalJson(value: unknown): string {
-  if (value === null) return 'null';
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value)) throw new Error('cannot serialize non-finite number');
-    return JSON.stringify(value);
-  }
-  if (typeof value === 'string' || typeof value === 'boolean') {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
-  }
-  if (typeof value === 'object') {
-    const obj = value as Record<string, unknown>;
-    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
-    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(obj[k])).join(',') + '}';
-  }
-  throw new Error(`cannot serialize value of type ${typeof value}`);
-}
+/**
+ * Canonical JSON serialization for signed payloads.
+ *
+ * Recursively sorts object keys, drops `undefined` values, emits no whitespace
+ * and no trailing newline. Arrays preserve their order. This is a tiny RFC 8785
+ * subset, sufficient for the fixed-shape payloads we sign (update manifests in
+ * cadre-host, control-network seeds here).
+ *
+ * Lives in cadre-core because cadre-host depends on cadre-core (not the
+ * reverse); cadre-host re-imports this rather than keeping its own copy.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return 'null';
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('cannot serialize non-finite number');
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
+  }
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(obj[k])).join(',') + '}';
+  }
+  throw new Error(`cannot serialize value of type ${typeof value}`);
+}

package/src/control-authorization.ts

@@ -0,0 +1,114 @@
+/**
+ * The single definition of the field vector every signed control-plane message
+ * covers. Both producers of signed bytes — `control-database.ts`'s
+ * `buildAuthorizationMessage` (raw digest bytes) and `peer-authorization.ts`'s
+ * digest helpers (base64url digest strings) — build their vector here, so the
+ * byte layout cannot drift between them or away from the SQL constraints in
+ * `schemas/control.qsql`.
+ *
+ * Every vector leads with two fixed literals:
+ *
+ *   digest(<domain>, <action>, <row field 1>, ..., <row field n>)
+ *
+ * so a signature verifies ONLY against the one rule it was minted for. Without
+ * the tags, several rules built byte-identical tuples (e.g. `ValidationKey`
+ * insert and `OwnerKey` insert both signed `digest(Key, StampId)`), so an
+ * approval for a narrow grant doubled as an approval for full ownership.
+ *
+ * This module deliberately has no Quereus / Optimystic / libp2p imports so the
+ * lightweight verifiers (`peer-authorization.ts`, consumed by the offline
+ * `cadre enroll register` check) can use it without pulling in the runtime.
+ */
+
+/**
+ * Names of the CadreControl tables, in schema order. The single list: the
+ * {@link ControlTable} union is derived from it and `ControlDatabase.countRows`
+ * guards its dynamic `from` clause against it (keeping the table name off the
+ * SQL-injection surface), so a new table cannot be added to one and missed in
+ * the other.
+ *
+ * `Revocation` is here for the same two reasons as every other entry: it
+ * derives a `'CadreControl.Revocation'` domain tag — its `Authorized` CHECK
+ * verifies an owner signature over the `'remove'`-tagged digest that
+ * `peer-authorization.ts`'s `revocationDigest` mints, and its `AuthorizedReissue`
+ * CHECK the `'reissue'`-tagged digest `ControlDatabase.reissueRevocations`
+ * signs — and `countRows` counts it.
+ */
+export const CONTROL_TABLES = [
+  'OwnerKey',
+  'ValidationKey',
+  'Strand',
+  'CadrePeer',
+  'DeviceToken',
+  'FormationInvite',
+  'FormationUsage',
+  'Revocation',
+] as const;
+
+/**
+ * Name of a CadreControl table. Doubles as the table half of a
+ * {@link ControlDomain} tag.
+ */
+export type ControlTable = typeof CONTROL_TABLES[number];
+
+/**
+ * The control tables whose rows carry a single-use `StampId` retired into
+ * `CadreControl.Revocation` on delete — i.e. the ones the schema's
+ * `NotRevoked` / `RevocationRecorded` CHECK pair guards, and the only values
+ * `Revocation.RowIsGone` accepts in `TableName`. `Extract` from
+ * {@link ControlTable} rather than a fresh literal list, so a renamed table is a
+ * compile error here instead of a silently dead branch.
+ *
+ * Lives in this import-free module rather than beside its main consumer
+ * (`control-database.ts`) so the lightweight signers — `peer-authorization.ts`'s
+ * `revocationDigest` — can type against it without pulling in the runtime.
+ */
+export type RevocableTable = Extract<ControlTable, 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'DeviceToken'>;
+
+/**
+ * What a signature authorizes, scoped to one table rule — or, for
+ * `'Cadre.Enrollment'`, the offline peer vouch that `cadre enroll register`
+ * verifies (no table checks it, so it needs its own domain to stay disjoint
+ * from every table rule).
+ */
+export type ControlDomain = `CadreControl.${ControlTable}` | 'Cadre.Enrollment';
+
+/**
+ * The action half of the tag:
+ *  - `'add'` / `'remove'` — insert / delete of the named row.
+ *  - `'vouch'` — an owner (or validation key) vouches the row's semantics
+ *    without adding or removing it: the `CadrePeer` membership vouch (shared,
+ *    deliberately, by its insert and its owner-update branch), the
+ *    `FormationUsage` disclosure validation, and the offline enrollment vouch.
+ *    `DeviceToken` has no `'vouch'` digest — its owner re-touch branch was
+ *    removed (it rewrote the row outside the monotonicity guard), so an owner
+ *    correcting a token deletes and re-inserts it.
+ *  - `'publish'` — a peer self-signs its OWN record (the `CadrePeer` /
+ *    `DeviceToken` self-update branches), with its own key rather than an
+ *    owner key.
+ *  - `'consent'` — a peer self-signs its OWN `FormationUsage` redemption (the
+ *    joiner proving it agreed to join), with its own key. Distinct from the
+ *    approver's `'vouch'` over the same table so the two stored signatures are
+ *    never interchangeable.
+ *  - `'reissue'` — an owner re-writes an existing `Revocation` tombstone,
+ *    bumping its `ReissuedAt` counter so a tombstone committed while the node
+ *    was alone can be re-broadcast. Distinct from `'remove'` so a tombstone
+ *    append approval can never be replayed as a re-issue and vice versa.
+ */
+export type ControlAction = 'add' | 'remove' | 'vouch' | 'publish' | 'consent' | 'reissue';
+
+/**
+ * The full ordered field vector a control-plane signature covers. Digest this
+ * with the crypto plugin's injective multi-field encoding (every field TEXT);
+ * the SQL mirror passes the same literals as leading `digest(...)` arguments:
+ *
+ *   TS:  digest(controlAuthorizationFields('CadreControl.X', 'add', [a, b]), 'sha256', ...)
+ *   SQL: digest('CadreControl.X', 'add', new.A, new.B)
+ */
+export function controlAuthorizationFields(
+  domain: ControlDomain,
+  action: ControlAction,
+  rowFields: string[],
+): string[] {
+  return [domain, action, ...rowFields];
+}

package/src/control-cohort.ts

@@ -1,103 +1,130 @@
-/**
- * Control-cohort dial selection: the pure policy behind
- * {@link CadreNode.reconcileControlCohort}. Decides WHICH known cadre siblings a
- * node proactively dials each pass to keep the `CadreControl` collections' cohort
- * connected (and thus replicating), without devolving into an N² mesh.
- *
- * FRET only needs a *connected* graph with the block clusters reachable, not a
- * full mesh. Storage/owner nodes are the stable, publicly-dialable backbone
- * that hold the control blocks, so the policy is **backbone-preferential with a
- * bounded out-degree**:
- *
- * - **Always dial every backbone (owner) member** — the owner set is
- *   small by design, and routing cohort formation through publicly-dialable
- *   owner nodes keeps the cohort ≥2 where owner-signed writes originate.
- * - **Fill the remainder** up to `targetDegree` with non-owner members,
- *   ordered deterministically (peerId sort) so every node makes the same stable
- *   choice across passes and load spreads predictably.
- *
- * For a small party (members ≤ degree) this degenerates to a full mesh, which is
- * correct, cheap, and matches what the convergence tests do by hand; for a large
- * party it bounds out-degree to `backbone + targetDegree`.
- */
-
-import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
-import type { CohortPeerRow } from './strand-cohort.js';
-
-/**
- * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
- * In the same spirit as the 5s strand-watch poll but lighter, since a control
- * cohort changes far less often than strand activity.
- */
-export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15_000;
-
-/**
- * Default cap on the number of **non-owner** members a single reconcile pass
- * proactively dials. Backbone (owner) members are always dialed and do NOT
- * count against this cap.
- */
-export const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
-
-/** Outcome of {@link selectControlCohortDials}: who to dial + what the cap dropped. */
-export interface ControlCohortSelection {
-  /**
-   * Siblings to dial this pass, backbone first then the bounded non-owner
-   * fill. Already self-excluded (the caller must pass self-excluded `siblings`).
-   * Still includes peers that may turn out to be already-connected — the caller
-   * diffs against live connections separately.
-   */
-  dials: CohortPeerRow[];
-  /** Non-owner members dropped by the `targetDegree` cap (0 when none). */
-  cappedNonOwner: number;
-}
-
-/** Stable peerId ordering so the bounded fill is identical across passes/nodes. */
-function byPeerId(a: CohortPeerRow, b: CohortPeerRow): number {
-  if (a.peerId < b.peerId) return -1;
-  if (a.peerId > b.peerId) return 1;
-  return 0;
-}
-
-/**
- * Backbone-preferential, bounded-out-degree selection of control-cohort siblings
- * to dial.
- *
- * A member is **backbone** iff the ed25519 key derived from its peerId
- * (see {@link ed25519PublicKeyB64FromPeerId}) is in `ownerKeys`. All backbone
- * members are selected; non-owner members fill up to `targetDegree` in
- * deterministic peerId order.
- *
- * @param siblings - cadre members EXCLUDING self (the caller filters self out).
- * @param ownerKeys - the converged `OwnerKey` set; may be empty/partial
- *   before owner convergence, in which case no member classifies as backbone
- *   yet and the bounded fill still makes progress (preference sharpens later).
- * @param targetDegree - cap on non-owner dials (negative is treated as 0).
- */
-export function selectControlCohortDials(
-  siblings: CohortPeerRow[],
-  ownerKeys: ReadonlySet<string>,
-  targetDegree: number,
-): ControlCohortSelection {
-  const backbone: CohortPeerRow[] = [];
-  const rest: CohortPeerRow[] = [];
-
-  for (const peer of siblings) {
-    const pubKey = ed25519PublicKeyB64FromPeerId(peer.peerId);
-    if (pubKey !== null && ownerKeys.has(pubKey)) {
-      backbone.push(peer);
-    } else {
-      rest.push(peer);
-    }
-  }
-
-  backbone.sort(byPeerId);
-  rest.sort(byPeerId);
-
-  const cap = Math.max(0, targetDegree);
-  const fill = rest.slice(0, cap);
-
-  return {
-    dials: [...backbone, ...fill],
-    cappedNonOwner: rest.length - fill.length,
-  };
-}
+/**
+ * Control-cohort dial selection: the pure policy behind
+ * {@link CadreNode.reconcileControlCohort}. Decides WHICH known cadre siblings a
+ * node proactively dials each pass to keep the `CadreControl` collections' cohort
+ * connected (and thus replicating), without devolving into an N² mesh.
+ *
+ * FRET only needs a *connected* graph with the block clusters reachable, not a
+ * full mesh. Storage/owner nodes are the stable, publicly-dialable backbone
+ * that hold the control blocks, so the policy is **backbone-preferential with a
+ * bounded out-degree**:
+ *
+ * - **Always dial every backbone (owner) member** — the owner set is
+ *   small by design, and routing cohort formation through publicly-dialable
+ *   owner nodes keeps the cohort ≥2 where owner-signed writes originate.
+ * - **Fill the remainder** up to `targetDegree` with non-owner members,
+ *   ordered deterministically (peerId sort) so every node makes the same stable
+ *   choice across passes and load spreads predictably.
+ *
+ * For a small party (members ≤ degree) this degenerates to a full mesh, which is
+ * correct, cheap, and matches what the convergence tests do by hand; for a large
+ * party it bounds out-degree to `backbone + targetDegree`.
+ */
+
+import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+import type { CohortPeerRow } from './strand-cohort.js';
+
+/**
+ * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
+ * In the same spirit as the 5s strand-watch poll but lighter, since a control
+ * cohort changes far less often than strand activity.
+ */
+export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15_000;
+
+/**
+ * Default cap on the number of **non-owner** members a single reconcile pass
+ * proactively dials. Backbone (owner) members are always dialed and do NOT
+ * count against this cap.
+ */
+export const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
+
+/**
+ * Default per-sibling budget for one proactive control-cohort dial, in ms.
+ *
+ * `libp2p.dial(addrs)` is handed EVERY address a sibling resolved to, and each
+ * one carries its own attempt timeout (js-libp2p's default is ~10 s, and
+ * `@optimystic/db-p2p` does not override it). Some addresses cost more than one
+ * attempt on their own: a `…/p2p-circuit/webrtc/…` address makes
+ * `@libp2p/webrtc` dial the signalling leg to the relay hop FIRST and only then
+ * the peer, so a two-address WebRTC sibling can block the sequential dial loop
+ * for four attempt timeouts. Against unroutable addresses none of those attempts
+ * ever answers, so an offline sibling's cost is address fan-out × relay hops ×
+ * ~10 s — a number nothing in this package chose or bounds.
+ *
+ * This budget makes the SIBLING the unit instead of the address: one pass costs
+ * at most (dialed siblings) × this, whatever each sibling's addresses look like.
+ * Deliberately wider than one attempt timeout so a reachable sibling whose first
+ * address is stale still gets a genuine try at its later ones; a sibling that
+ * needs longer than this is simply retried next pass (every
+ * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}), which is what the dial loop's
+ * best-effort contract already does with any other dial failure.
+ *
+ * Override per node with `network.controlCohort.dialTimeoutMs` — tests that
+ * drive dead addresses on purpose set it low so a pass's duration is a chosen
+ * number rather than a transitive libp2p default stretched by machine load.
+ */
+export const DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS = 20_000;
+
+/** Outcome of {@link selectControlCohortDials}: who to dial + what the cap dropped. */
+export interface ControlCohortSelection {
+  /**
+   * Siblings to dial this pass, backbone first then the bounded non-owner
+   * fill. Already self-excluded (the caller must pass self-excluded `siblings`).
+   * Still includes peers that may turn out to be already-connected — the caller
+   * diffs against live connections separately.
+   */
+  dials: CohortPeerRow[];
+  /** Non-owner members dropped by the `targetDegree` cap (0 when none). */
+  cappedNonOwner: number;
+}
+
+/** Stable peerId ordering so the bounded fill is identical across passes/nodes. */
+function byPeerId(a: CohortPeerRow, b: CohortPeerRow): number {
+  if (a.peerId < b.peerId) return -1;
+  if (a.peerId > b.peerId) return 1;
+  return 0;
+}
+
+/**
+ * Backbone-preferential, bounded-out-degree selection of control-cohort siblings
+ * to dial.
+ *
+ * A member is **backbone** iff the ed25519 key derived from its peerId
+ * (see {@link ed25519PublicKeyB64FromPeerId}) is in `ownerKeys`. All backbone
+ * members are selected; non-owner members fill up to `targetDegree` in
+ * deterministic peerId order.
+ *
+ * @param siblings - cadre members EXCLUDING self (the caller filters self out).
+ * @param ownerKeys - the converged `OwnerKey` set; may be empty/partial
+ *   before owner convergence, in which case no member classifies as backbone
+ *   yet and the bounded fill still makes progress (preference sharpens later).
+ * @param targetDegree - cap on non-owner dials (negative is treated as 0).
+ */
+export function selectControlCohortDials(
+  siblings: CohortPeerRow[],
+  ownerKeys: ReadonlySet<string>,
+  targetDegree: number,
+): ControlCohortSelection {
+  const backbone: CohortPeerRow[] = [];
+  const rest: CohortPeerRow[] = [];
+
+  for (const peer of siblings) {
+    const pubKey = ed25519PublicKeyB64FromPeerId(peer.peerId);
+    if (pubKey !== null && ownerKeys.has(pubKey)) {
+      backbone.push(peer);
+    } else {
+      rest.push(peer);
+    }
+  }
+
+  backbone.sort(byPeerId);
+  rest.sort(byPeerId);
+
+  const cap = Math.max(0, targetDegree);
+  const fill = rest.slice(0, cap);
+
+  return {
+    dials: [...backbone, ...fill],
+    cappedNonOwner: rest.length - fill.length,
+  };
+}