@serfab/cadre-core 1.13.0 → 1.14.0

package/src/claim-proof.ts

@@ -0,0 +1,147 @@
+/**
+ * Claim proof: how the first seed delivered to a brand-new node proves that its sender
+ * holds the node's one-time claim secret.
+ *
+ * A node that belongs to nobody yet (a cadre-host child before its owner scans the QR
+ * code) has an empty trusted-owner anchor, so every seed trust policy refuses its first
+ * seed. The claim secret is the out-of-band channel that breaks the deadlock: the host
+ * mints 32 random bytes, shows them beside the node's addresses, and the owner's phone
+ * proves possession by sending, next to the seed, an HMAC keyed by those bytes.
+ *
+ * The proof is `base64url(HMAC-SHA256(secret, utf8(canonicalJson(payload))))` where
+ * `payload` is `{ purpose: 'sereus-node-claim', v: 1, nodePeerId, signerKey, seedDigest }`:
+ *
+ *  - `nodePeerId` binds the proof to one node, so a captured proof cannot claim another
+ *    node minted with the same secret;
+ *  - `signerKey` binds it to one owner, so it cannot anchor a different key;
+ *  - `seedDigest` (the same digest the seed signature covers, `seedDigest()` in
+ *    `seed-bootstrap.ts`) binds it to one seed, so it cannot be reattached to another.
+ *
+ * A passive observer of one delivery therefore learns a proof that is useless anywhere
+ * else, and useless on this node once it is claimed. A keyed MAC is the standard way to
+ * prove possession of a secret without revealing it; the crypto plugin's framed
+ * `digest([...])` helper is not specified as one, so the secret is never fed to it.
+ *
+ * Verified by `claimSecretTrustPolicy` (`seed-trust-policy.ts`). Imports only
+ * `@noble/hashes`, `uint8arrays` and `canonical-json.ts`: this module loads on React
+ * Native and in the browser as well as Node.
+ */
+import debug from 'debug';
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+import type { SeedRefusalCode } from './types.js';
+
+const log = debug('sereus:cadre:claim-proof');
+
+/** Length of a claim secret: 256 bits, so guessing one is infeasible. */
+export const CLAIM_SECRET_BYTES = 32;
+
+/**
+ * Thrown by `CadreNode.claimNode` when the node answered the claim seed with a refusal.
+ * Distinct from `PeerUnreachableError` (no connection to the node formed) and from a
+ * failure after the node was reached (thrown by `deliverSeed` as is): here the node was
+ * reached and said no. `code` is the node's machine-readable cause
+ * when its policy supplied one (`already-claimed`, `claim-proof-invalid`, ...), so a
+ * phone can tell "someone else owns it" from "wrong secret" without parsing `reason`.
+ */
+export class ClaimRefusedError extends Error {
+	constructor(
+		readonly nodePeerId: string,
+		readonly reason: string,
+		readonly code?: SeedRefusalCode,
+	) {
+		super(`Node ${nodePeerId} refused the claim${code ? ` (${code})` : ''}: ${reason}`);
+		this.name = 'ClaimRefusedError';
+	}
+}
+
+/**
+ * Decode a claim secret from the base64url text the host shows and the phone scans.
+ *
+ * Refuses anything that is not base64url of exactly {@link CLAIM_SECRET_BYTES} bytes,
+ * naming the problem. The rejected value is never echoed: unlike a public key, a
+ * mistyped secret may still be a secret.
+ *
+ * @returns The 32 secret bytes.
+ */
+export function parseClaimSecret(text: string): Uint8Array {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) {
+		throw new Error('A claim secret is required (received an empty or whitespace-only value)');
+	}
+
+	let decoded: Uint8Array;
+	try {
+		decoded = uint8ArrayFromString(trimmed, 'base64url');
+	} catch (error) {
+		throw new Error('A claim secret must be base64url text (the value could not be decoded as base64url)', { cause: error });
+	}
+
+	if (decoded.length !== CLAIM_SECRET_BYTES) {
+		throw new Error(`A claim secret must decode to exactly ${CLAIM_SECRET_BYTES} bytes (the value decoded to ${decoded.length})`);
+	}
+	return decoded;
+}
+
+/** The HMAC tag bytes over the canonical claim payload (see the module doc). */
+function claimProofBytes(secret: Uint8Array, nodePeerId: string, signerKey: string, seedDigest: string): Uint8Array {
+	const payload = canonicalJson({ purpose: 'sereus-node-claim', v: 1, nodePeerId, signerKey, seedDigest });
+	return hmac(sha256, secret, new TextEncoder().encode(payload));
+}
+
+/**
+ * Compute the claim proof the owner side sends beside its seed.
+ *
+ * @param secret - The parsed 32-byte claim secret ({@link parseClaimSecret}).
+ * @param nodePeerId - The peer id of the node being claimed.
+ * @param signerKey - The owner key that signed the seed (base64url).
+ * @param seedDigest - The seed's signature digest (`seedDigest()` in `seed-bootstrap.ts`).
+ * @returns The proof, base64url.
+ */
+export function claimProof(secret: Uint8Array, nodePeerId: string, signerKey: string, seedDigest: string): string {
+	return uint8ArrayToString(claimProofBytes(secret, nodePeerId, signerKey, seedDigest), 'base64url');
+}
+
+/**
+ * Check a presented proof against the receiver's own view of the three bound fields.
+ *
+ * Recomputes the tag and compares in constant time. A proof that does not decode as
+ * base64url is simply invalid. `nodePeerId` must be the RECEIVER's own peer id, never
+ * one the sender supplied; that is what makes a captured proof useless elsewhere.
+ */
+export function verifyClaimProof(
+	secret: Uint8Array,
+	nodePeerId: string,
+	signerKey: string,
+	seedDigest: string,
+	proof: string,
+): boolean {
+	let presented: Uint8Array;
+	try {
+		presented = uint8ArrayFromString(proof, 'base64url');
+	} catch (error) {
+		log('claim proof is not base64url: %o', error);
+		return false;
+	}
+	return constantTimeEqual(presented, claimProofBytes(secret, nodePeerId, signerKey, seedDigest));
+}
+
+/**
+ * Byte equality whose running time does not depend on WHERE the arrays differ, so a
+ * remote cannot learn a valid proof prefix from response timing. The length check
+ * short-circuits, which leaks nothing: a valid proof's length is public. A plain loop
+ * rather than `node:crypto`'s `timingSafeEqual` because this module must load on React
+ * Native and in the browser.
+ */
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+	if (a.length !== b.length) {
+		return false;
+	}
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) {
+		diff |= a[i]! ^ b[i]!;
+	}
+	return diff === 0;
+}

package/src/control-authorization.ts

@@ -1,117 +1,203 @@
-/**
- * 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',
-  'StrandPartyKey',
-  'JoinedStrand',
-  'PendingJoin',
-  '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' | 'StrandPartyKey' | 'JoinedStrand' | 'PendingJoin' | '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];
-}
+/**
+ * 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 and the party id:
+ *
+ *   digest(<domain>, <action>, <party id>, <row field 1>, ..., <row field n>)
+ *
+ * so a signature verifies ONLY against the one rule, in the one party, 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.
+ * Without the party, two parties sharing an owner key (one node key owning two
+ * cadres, a hardware owner key) would accept each other's approvals. The SQL side
+ * reads the party from the node-local `party_id()` function `ControlDatabase`
+ * registers (never from a context value or a replicated table), and every
+ * TypeScript signer and verifier passes the party it is configured for.
+ *
+ * Two digests carry NO party ({@link UnboundControlDomain}): the `FormationUsage`
+ * `'consent'` and `'vouch'` digests, whose signers do not know the party (see the
+ * schema's `FormationUsage.Authorized` comment), and the offline `'Cadre.Enrollment'`
+ * vouch, which no table checks.
+ *
+ * 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',
+  'StrandPartyKey',
+  'JoinedStrand',
+  'JoinRequest',
+  'JoinSuccess',
+  'JoinFailure',
+  'CadrePeer',
+  'DeviceToken',
+  'FormationInvite',
+  'FormationUsage',
+  'CadreInvite',
+  'CadreInviteUsage',
+  '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.
+ *
+ * `CadreInvite` is the one member whose rows are never deleted: its tombstone is a
+ * withdrawal over a row that stays (`NotRevoked` refuses re-seating the withdrawn
+ * row; there is no `RevocationRecorded`, since nothing is ever removed), so it is
+ * revocable without being removable — `control-database.ts`'s `RemovableTable`
+ * excludes it.
+ *
+ * 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' | 'StrandPartyKey' | 'JoinedStrand' | 'JoinRequest' | 'DeviceToken' | 'CadreInvite'>;
+
+/**
+ * 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 domains whose digests bind no party id — the only two
+ * {@link unboundAuthorizationFields} accepts. `FormationUsage`: neither signer knows
+ * the party, and the invitation token scopes the digest instead (the reason is at the
+ * schema's `FormationUsage.Authorized` comment). `Cadre.Enrollment`: no table checks it.
+ */
+export type UnboundControlDomain = 'CadreControl.FormationUsage' | 'Cadre.Enrollment';
+
+/** Every domain whose digests bind the party id — the only ones {@link controlAuthorizationFields} accepts. */
+export type BoundControlDomain = Exclude<ControlDomain, UnboundControlDomain>;
+
+/**
+ * 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` or
+ *    `CadreInviteUsage` 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.
+ *  - `'redeem'` — the holder of a `CadreInvite`'s private key proves possession
+ *    on a `CadreInviteUsage` row. Distinct from the device's `'consent'` over the
+ *    same fields: the two signatures are by different keys and neither may stand
+ *    in for the other.
+ *  - `'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' | 'redeem' | 'reissue';
+
+/**
+ * The `CadreInvite` columns its `'add'` signature binds, in the schema's order and
+ * with the row's stored forms: `expiresAt` is the engine-canonical `datetime` string
+ * (`canonicalDatetime`), never epoch ms, because the SQL side digests
+ * `cast(new.ExpiresAt as text)` after coercion. Structurally satisfied by a
+ * `CadreInviteRow` (`types.ts`), which adds the issuer pair the signature does not cover.
+ */
+export interface CadreInviteSignedFields {
+  key: string;
+  peerId: string | null;
+  grantsOwner: boolean;
+  expiresAt: string | null;
+  totalUses: number | null;
+  stampId: string;
+}
+
+/**
+ * The row-field half of a `CadreInvite` `'add'` digest, shared by the signer
+ * (`control-database.ts`'s `cadreInviteAddMessage`, raw bytes) and the verifier
+ * (`peer-authorization.ts`'s `cadreInviteAddDigest`, base64url) so the two cannot
+ * drift. SQL mirror, in `CadreInvite.AuthorizedInsert`:
+ * `new.Key, coalesce(new.PeerId, ''), cast(new.GrantsOwner as text),
+ * coalesce(cast(new.ExpiresAt as text), ''), coalesce(cast(new.TotalUses as text), ''), new.StampId`.
+ */
+export function cadreInviteRowFields(row: CadreInviteSignedFields): string[] {
+  return [
+    row.key,
+    row.peerId ?? '',
+    row.grantsOwner ? '1' : '0',
+    row.expiresAt ?? '',
+    row.totalUses === null ? '' : String(row.totalUses),
+    row.stampId,
+  ];
+}
+
+/**
+ * The full ordered field vector a party-bound 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 and
+ * reads the party from its node-local `party_id()`:
+ *
+ *   TS:  digest(controlAuthorizationFields('CadreControl.X', 'add', partyId, [a, b]), 'sha256', ...)
+ *   SQL: digest('CadreControl.X', 'add', party_id(), new.A, new.B)
+ */
+export function controlAuthorizationFields(
+  domain: BoundControlDomain,
+  action: ControlAction,
+  partyId: string,
+  rowFields: string[],
+): string[] {
+  return [domain, action, partyId, ...rowFields];
+}
+
+/**
+ * The field vector of the two party-free digests ({@link UnboundControlDomain}):
+ *
+ *   TS:  digest(unboundAuthorizationFields('CadreControl.FormationUsage', 'consent', [a, b]), 'sha256', ...)
+ *   SQL: digest('CadreControl.FormationUsage', 'consent', new.A, new.B)
+ */
+export function unboundAuthorizationFields(
+  domain: UnboundControlDomain,
+  action: ControlAction,
+  rowFields: string[],
+): string[] {
+  return [domain, action, ...rowFields];
+}

package/src/control-cohort.ts

@@ -21,7 +21,7 @@
  * party it bounds out-degree to `backbone + targetDegree`.
  */
 
-import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
 import type { CohortPeerRow } from './strand-cohort.js';
 
 /**