@serfab/cadre-core 0.7.1 → 0.9.0

package/dist/control-database.d.ts

@@ -1,7 +1,43 @@
 import { Database } from '@quereus/quereus';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
-import type { StrandRow } from './types.js';
+import type { StrandRow, PeerAddressRecord, DeviceTokenRecord } from './types.js';
+/**
+ * Generate a unique stamp ID for transaction authorization.
+ * Format: 32 bytes base64url encoded
+ * - First 16 bytes: SHA-256 hash of peer ID (for distributed uniqueness)
+ * - Last 16 bytes: Random bytes (for collision resistance)
+ */
+export declare function generateStampId(peerId: string): string;
+/**
+ * Build the canonical authorization message that owner signatures are bound to.
+ *
+ * The message is a SINGLE framed SHA-256 digest over the ordered tuple of fields (the
+ * crypto plugin's injective multi-field encoding), in a fixed field order, with the
+ * single-use StampId as the final field:
+ *
+ *   message = sha256(encodeFields([field_1, field_2, ..., StampId]))   // raw digest bytes
+ *
+ * ed25519 signs these raw digest bytes DIRECTLY (no second hash). The SQL constraints
+ * verify the identical bytes with one variadic call
+ * (`verify(digest(field_1, ..., StampId), context.Signature, A.Key, 'ed25519')`): SQL
+ * `digest(...)` returns the base64url string of the same digest, which `verify`'s default
+ * base64url input encoding decodes back to those raw bytes — so signer and verifier
+ * operate on the same bytes. Every field is TEXT on both sides (the SQL columns are
+ * `cast(... as text)` / `coalesce(...,'')`; the TS args are strings), so the per-field
+ * type tags agree. This binds the signature to the row contents (not a bare stamp),
+ * closing the captured-stamp replay / privilege-escalation hole. Single source of truth:
+ * every signed writer (and every test/harness signer) MUST build the message through this
+ * function in the schema's field order, or `verify` will reject the row.
+ */
+export declare function buildAuthorizationMessage(fields: string[]): Uint8Array;
+/**
+ * Names of the CadreControl tables that {@link ControlDatabase.countRows} can
+ * read. Constraining to this union keeps the dynamic `from` clause off the
+ * SQL-injection surface and hands callers (e.g. the integration harness's
+ * `waitForControlSync`) a typo-proof table argument.
+ */
+export type ControlTable = 'OwnerKey' | 'ValidationKey' | 'Strand' | 'CadrePeer' | 'DeviceToken' | 'FormationInvite' | 'FormationUsage';
 export interface ControlDatabaseConfig {
     /** Party ID for the control network */
     partyId: string;
@@ -35,25 +71,260 @@ export declare class ControlDatabase {
      * Query all strands from the control database
      */
     queryStrands(): Promise<StrandRow[]>;
+    /**
+     * Read a single strand row by id, or null when absent. Single-row sibling of
+     * {@link queryStrands}; the responder uses it to read a host strand's
+     * `MemberPrivateKey` (the closed-strand read-gating secret) for delivery to a
+     * validated invitee during provision-then-record formation.
+     */
+    queryStrand(strandId: string): Promise<StrandRow | null>;
+    /**
+     * Count rows in a CadreControl table as seen by THIS database instance.
+     *
+     * `table` is validated against {@link CONTROL_TABLES} before it is interpolated
+     * into the `from` clause: the names are not user input, but the check keeps the
+     * dynamic query off the injection surface and fails loudly on a typo instead of
+     * emitting a malformed statement. The count reflects only the rows this node's
+     * control DB has converged on — in the integration harness that is the owner
+     * node (one ControlDatabase per party), i.e. the authoritative control-network
+     * view, not a per-drone convergence guarantee.
+     */
+    countRows(table: ControlTable): Promise<number>;
     /**
      * Get the underlying database for advanced queries
      */
     getDatabase(): Database;
     /**
-     * Insert the initial authority key (bootstrap - no existing authorities required)
+     * Check whether any owner key exists in the control database.
+     * Used to decide whether a fresh-party genesis insert is required.
+     */
+    hasOwnerKey(): Promise<boolean>;
+    /**
+     * Idempotent genesis: insert `key` as the founding owner key only when
+     * the party has none yet. Returns true if it inserted, false if an owner
+     * key already existed (so a repeat `--owner` start is a no-op).
+     */
+    ensureOwnerKey(key: string): Promise<boolean>;
+    /**
+     * Collect every owner key (`CadreControl.OwnerKey.Key`) as a set.
+     *
+     * This is the steady-state trust anchor for seeds: a seed's signer key is
+     * trusted only if it is already enrolled here (see `SeedTrustPolicy`). It is
+     * also the owner-identity source for `queryPeers`, decoupling owner
+     * status from the libp2p transport peer ID.
+     */
+    getOwnerKeys(): Promise<Set<string>>;
+    /**
+     * Enumerate the CadrePeer rows (cadre membership) for admin/membership reads.
+     */
+    queryCadrePeers(): Promise<Array<{
+        peerId: string;
+        multiaddr: string | null;
+        stampId: string | null;
+        vouchOwner: string | null;
+        vouchSig: string | null;
+    }>>;
+    /**
+     * Read a single `CadrePeer` row's single-use `StampId` nonce (null when the row
+     * does not exist). Used by the owner delete / re-touch paths, which must bind
+     * their signature to the row's CURRENT nonce ({@link cadrePeerRemoveDigest} /
+     * {@link cadrePeerVoucherDigest}).
+     */
+    queryCadrePeerStampId(peerId: string): Promise<string | null>;
+    /**
+     * Read a single peer's address record (the full `CadrePeer` row) by PeerId.
+     *
+     * Returns null when no row exists. Missing/legacy column values are coalesced
+     * to their empty form (`''` key/sig, `[]` addrs, `0` stamp) so the caller's
+     * verify/freshness gates uniformly reject an unpublished or malformed row.
+     * The split `addrs` re-join to the exact stored `Multiaddr` (split-on-`,` is
+     * the inverse of join-on-`,`), so the resolver re-verifies over the same bytes
+     * the publisher signed.
+     */
+    queryPeerRecord(peerId: string): Promise<PeerAddressRecord | null>;
+    /**
+     * Apply a peer's own self-signed address-record update to an existing row.
+     *
+     * Authorization is carried entirely by the record: the `Sig` column (verified
+     * by the `AuthorizedUpdate` self-branch against the stored `PublicKey`) plus
+     * the strictly-increasing `UpdatedAt`. No owner key is involved, so this
+     * is the refresh path for any member — owner or drone — once its row
+     * exists. `PublicKey` is intentionally not in the SET list (it is immutable on
+     * self-update and the constraint enforces `new.PublicKey = old.PublicKey`).
+     */
+    updateSelfPeerRecord(record: PeerAddressRecord): Promise<void>;
+    /**
+     * Read a single peer's device push token (the full `DeviceToken` row) by PeerId.
+     *
+     * Returns null when no row exists. Missing/legacy column values are coalesced to
+     * their empty form (`''` token/sig, `0` stamp) so the caller's verify/freshness
+     * gates uniformly reject an unpublished or malformed row. `platform` is returned
+     * verbatim (the resolver validates it against {@link PushPlatform} and re-verifies
+     * the self-signature, which covers the platform field).
      */
-    insertAuthorityKey(key: string): Promise<void>;
+    queryDeviceToken(peerId: string): Promise<DeviceTokenRecord | null>;
     /**
-     * Insert a strand into the control database using authority signature.
-     * This starts a transaction, gets the StampId, signs it, and inserts the strand.
+     * Apply a peer's own self-signed device-token update to an existing row.
+     *
+     * Authorization is carried entirely by the record: the `Sig` column (verified by
+     * the `DeviceToken.AuthorizedUpdate` self-branch against the stored
+     * `CadrePeer.PublicKey`) plus the strictly-increasing `UpdatedAt`. No owner key
+     * is involved, so this is the refresh / rotation path for any member once both its
+     * `CadrePeer` row (for the PublicKey) and its `DeviceToken` row exist. `PeerId` is
+     * intentionally not in the SET list (immutable; the constraint enforces
+     * `new.PeerId = old.PeerId`). Mirrors {@link updateSelfPeerRecord}.
+     */
+    updateSelfDeviceToken(record: DeviceTokenRecord): Promise<void>;
+    /**
+     * Insert the initial owner key (bootstrap - no existing owners required)
+     */
+    insertOwnerKey(key: string): Promise<void>;
+    /**
+     * Insert a strand into the control database using an owner signature.
+     *
+     * The owner signs the canonical row-bound authorization message (see
+     * {@link buildAuthorizationMessage}) — NOT a bare stamp — so the signature is bound to
+     * this strand's contents and cannot be transplanted onto an attacker-chosen row. The
+     * StampId is persisted as a unique column for single-use anti-replay.
      *
      * @param strandId - Unique identifier for the strand
      * @param type - Strand type: 'o' for open, 'c' for closed
-     * @param authorityKey - Public key of the authorizing authority
-     * @param signStampId - Function to sign the stamp ID with the authority's private key
+     * @param ownerKey - Public key of the authorizing owner
+     * @param signMessage - Function that ed25519-signs the raw message bytes (no pre-hash)
+     *   with the owner's private key, returning a base64url signature
      * @param memberPrivateKey - Optional private key for membership in closed strands
      */
-    insertStrand(strandId: string, type: 'o' | 'c', authorityKey: string, signStampId: (stampId: string) => string, memberPrivateKey?: string): Promise<void>;
+    insertStrand(strandId: string, type: 'o' | 'c', ownerKey: string, signMessage: (message: Uint8Array) => string, memberPrivateKey?: string): Promise<void>;
+    /**
+     * Insert a validation key into the control database using an owner signature.
+     *
+     * Mirrors {@link insertStrand}: the owner signs the canonical row-bound
+     * authorization message over (Key, StampId), and the StampId is persisted as a unique
+     * column for single-use anti-replay. A `ValidationKey` authorizes verifying strand
+     * formation disclosures.
+     *
+     * @param key - The validation public key to enroll
+     * @param ownerKey - Public key of the authorizing owner
+     * @param signMessage - Function that ed25519-signs the raw message bytes (no pre-hash)
+     *   with the owner's private key, returning a base64url signature
+     */
+    insertValidationKey(key: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<void>;
+    /**
+     * Insert an owner-signed `FormationInvite` (open invitation token).
+     *
+     * The invite is the on-network record that later authorizes an
+     * owner-signature-FREE `Strand` creation: an invited cadre peer redeems it
+     * by inserting a matching `FormationUsage` row (see {@link redeemInvitation}),
+     * which satisfies the consent branch of `Strand.Authorized`.
+     *
+     * Like {@link insertStrand}/{@link insertValidationKey}, the owner signs the
+     * canonical row-bound authorization message (see {@link buildAuthorizationMessage})
+     * over (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId) — NOT a
+     * bare stamp — so the signature is bound to this invite's contents and cannot be
+     * transplanted onto an attacker-chosen row. The StampId is persisted as a unique
+     * column for single-use anti-replay. `FormationInvite.AuthorizedAddOrRemove` gates
+     * both insert and delete; its `coalesce(new, old)` verify binds the NEW row on
+     * insert and the OLD row on delete.
+     *
+     * `StrandId` binds the invite to a pre-existing host strand (provision-then-record):
+     * when set, a responder redeeming this token records a `FormationUsage` against that
+     * strand and returns it (see {@link ControlFormationUsageRecorder.resolveStrand}); a
+     * null `StrandId` (the default) leaves the legacy responder-provisions path in place.
+     * Like ValidationUrl it is a nullable bound field, signed as `''` when absent.
+     *
+     * The ExpiresAt and TotalUses message fields must byte-match what the (auto-deferred,
+     * because it has a subquery) CHECK sees AFTER column coercion: TotalUses becomes a
+     * decimal string (`String(totalUses)` ⇔ `cast(new.TotalUses as text)`) and ExpiresAt
+     * becomes the engine's canonical `PlainDateTime` string — sourced here from
+     * {@link canonicalDatetime} (a `select datetime(?)` round-trip) rather than a hand-rolled
+     * ISO formatter, so signer and verifier agree exactly. A null ExpiresAt / TotalUses /
+     * ValidationUrl signs as `''`, matching the schema's `coalesce(..., '')`.
+     *
+     * @param token - Invitation token (the `FormationInvite` primary key)
+     * @param sAppId - The sApp a redeemed strand will use
+     * @param ownerKey - Public key of the authorizing owner
+     * @param signMessage - ed25519-signs the raw message bytes (no pre-hash),
+     *   returning a base64url signature — the same callback shape {@link insertStrand} uses
+     * @param options - Optional `expiresAtMs` (epoch ms), `totalUses`, `validationUrl`,
+     *   `strandId` (bind to a pre-existing host strand for provision-then-record)
+     */
+    insertFormationInvite(token: string, sAppId: string, ownerKey: string, signMessage: (message: Uint8Array) => string, options?: {
+        expiresAtMs?: number;
+        totalUses?: number;
+        validationUrl?: string;
+        strandId?: string;
+    }): Promise<void>;
+    /**
+     * Redeem a `FormationInvite` by inserting the `Strand` row and a matching
+     * `FormationUsage` row **atomically, in one transaction**.
+     *
+     * The two CHECK constraints are mutually circular under immediate evaluation:
+     * `Strand.Authorized`'s consent branch requires the `FormationUsage` row, while
+     * `FormationUsage.StrandExists` requires the `Strand` row. Both CHECKs contain
+     * subqueries, so Quereus auto-defers them to transaction commit — wrapping both
+     * inserts in a single explicit `begin … commit` lets both deferred CHECKs see
+     * both rows at commit. The strand is authorised WITHOUT an owner signature
+     * (the `FormationUsage` branch of `Strand.Authorized`) but still gets a fresh,
+     * unique `StampId` column to satisfy the not-null/unique anti-replay column.
+     *
+     * `UseNumber` is computed as `max(UseNumber)+1` for the token (the `Monotonic`
+     * constraint); callers redeeming concurrently against the same token must
+     * serialise, since the next use number is read before the insert.
+     */
+    redeemInvitation(params: {
+        token: string;
+        strandId: string;
+        type?: 'o' | 'c';
+        memberPrivateKey?: string;
+        disclosure?: string;
+        peerId?: string;
+        peerSignature?: string;
+        nowMs?: number;
+        validationKey?: string;
+        validationSignature?: string;
+    }): Promise<void>;
+    /**
+     * Record a `FormationUsage` against an **already-existing** `Strand` (no strand
+     * insert). This is the redemption path when the strand was provisioned
+     * separately (e.g. owner-signed) and the consent record is added after the
+     * fact: the single insert auto-commits, and the deferred `StrandExists` CHECK
+     * is satisfied by the pre-existing committed strand row. Returns the assigned
+     * `UseNumber`.
+     *
+     * Use {@link redeemInvitation} instead when the strand must be created by
+     * consent atomically with the usage.
+     */
+    recordFormationUsage(params: {
+        token: string;
+        strandId: string;
+        disclosure?: string;
+        peerId?: string;
+        peerSignature?: string;
+        nowMs?: number;
+        validationKey?: string;
+        validationSignature?: string;
+    }): Promise<number>;
+    /** Parameterised `FormationUsage` insert shared by redeem + record paths. */
+    private execFormationUsageInsert;
+    /**
+     * Read a `FormationInvite` row by token, or null when absent. `expiresAtMs` is
+     * the parsed epoch-ms of the stored `datetime` (null when the invite never
+     * expires); the caller compares it against the wall clock for freshness.
+     */
+    queryFormationInvite(token: string): Promise<{
+        token: string;
+        sAppId: string;
+        expiresAtMs: number | null;
+        totalUses: number | null;
+        validationUrl: string | null;
+        strandId: string | null;
+    } | null>;
+    /**
+     * Count `FormationUsage` rows recorded against a token (uses consumed so far).
+     */
+    countFormationUsage(token: string): Promise<number>;
+    /** Next `UseNumber` for a token = max(existing)+1, per the `Monotonic` constraint. */
+    private nextUseNumber;
     /**
      * Close the database and cleanup resources
      */