@serfab/cadre-core 0.7.1 → 0.9.0

package/src/control-formation-recorder.ts

@@ -0,0 +1,151 @@
+import debug from 'debug';
+import { randomBytes } from '@optimystic/quereus-plugin-crypto';
+import type { ControlDatabase } from './control-database.js';
+import type { FormationUsageRecorder, ResolvedHostStrand } from './strand-solicitation.js';
+import type { OpenInvitation } from './types.js';
+
+const log = debug('sereus:cadre:formation-recorder');
+
+/** Far-future sentinel for an invitation that never expires (max valid JS Date). */
+const NEVER_EXPIRES = new Date(8640000000000000);
+
+/**
+ * {@link FormationUsageRecorder} backed by the real `CadreControl` tables.
+ *
+ * It reads `FormationInvite` / `FormationUsage` to answer token-validity and
+ * usage questions, and writes the consent row that records a redemption. Two
+ * provisioning shapes are supported, keyed on whether the invite binds a host strand:
+ *
+ * - **Bound (provision-then-record):** the host strand already exists (owner-signed
+ *   up front and named by the invite's `StrandId`), so {@link resolveStrand} reports it
+ *   and {@link recordUsage} writes the consent row against that pre-existing strand
+ *   (record-only) rather than inserting a new `Strand`.
+ * - **Unbound (responder-provisions):** the invite carries no `StrandId`, so
+ *   {@link provisionAndRecord} mints a fresh strand and records consent against it
+ *   ATOMICALLY (one `FormationUsage` row), closing the single-use hole the older
+ *   never-record fallback left open.
+ *
+ * This replaces the in-memory stubs used by the formation tests so the consent path
+ * is exercised against the persisted control network.
+ *
+ * Usage accounting follows the schema's `FormationUsage.Authorized` semantics:
+ * a null `TotalUses` means unlimited uses; otherwise the invite is "used up"
+ * once the recorded usage count reaches `TotalUses`.
+ */
+export class ControlFormationUsageRecorder implements FormationUsageRecorder {
+  constructor(private readonly controlDatabase: ControlDatabase) {}
+
+  /** A token is valid when a matching, unexpired `FormationInvite` exists. */
+  async isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }> {
+    const invite = await this.controlDatabase.queryFormationInvite(token);
+    if (!invite) {
+      return { valid: false };
+    }
+    if (invite.expiresAtMs !== null && invite.expiresAtMs <= Date.now()) {
+      log('Token expired: %s', token);
+      return { valid: false };
+    }
+    return {
+      valid: true,
+      invitation: {
+        token: invite.token,
+        sAppId: invite.sAppId,
+        expiration: invite.expiresAtMs !== null ? new Date(invite.expiresAtMs) : NEVER_EXPIRES,
+        bootstrap: [],
+      },
+    };
+  }
+
+  /**
+   * A token is "used" when its recorded usage count has reached the invite's
+   * `TotalUses`. A null `TotalUses` (unlimited) is never used up; an unknown
+   * token is reported not-used (validity is handled by {@link isTokenValid}).
+   */
+  async isTokenUsed(token: string): Promise<boolean> {
+    const invite = await this.controlDatabase.queryFormationInvite(token);
+    if (!invite || invite.totalUses === null) {
+      return false;
+    }
+    const uses = await this.controlDatabase.countFormationUsage(token);
+    return uses >= invite.totalUses;
+  }
+
+  /**
+   * Record consent against an **already-existing** host strand (record-only): the
+   * single `FormationUsage` insert auto-commits and the deferred `StrandExists`
+   * CHECK is satisfied by the pre-existing strand. This is the provision-then-record
+   * commitment — the strand was minted owner-signed up front, so we do NOT
+   * re-insert it (which would double-insert the same PK). `initiatorKey` is carried
+   * as the usage `PeerId` (advisory). Use {@link ControlDatabase.redeemInvitation}
+   * for the consent-creates-strand path instead.
+   */
+  async recordUsage(token: string, initiatorKey: string, strandId: string): Promise<void> {
+    await this.controlDatabase.recordFormationUsage({ token, strandId, peerId: initiatorKey });
+    log('Recorded formation usage: token=%s strand=%s', token, strandId);
+  }
+
+  /**
+   * Classify the host strand this invite binds to (see {@link ResolvedHostStrand}):
+   *
+   * - no invite / no `StrandId` → `unbound` (responder-provisions path).
+   * - `StrandId` set AND the strand row is present → `bound`, carrying its
+   *   `MemberPrivateKey` (the closed-strand read-gating secret) for delivery to a
+   *   validated invitee.
+   * - `StrandId` set but the strand row is absent → `missing` (the host strand has not
+   *   converged on this responder yet); the manager rejects cleanly instead of recording
+   *   usage against a non-existent strand, which would fail the deferred `StrandExists`
+   *   CHECK at commit and drop the result frame.
+   */
+  async resolveStrand(token: string): Promise<ResolvedHostStrand> {
+    const invite = await this.controlDatabase.queryFormationInvite(token);
+    if (!invite || !invite.strandId) {
+      return { kind: 'unbound' };
+    }
+    const strand = await this.controlDatabase.queryStrand(invite.strandId);
+    if (!strand) {
+      return { kind: 'missing', strandId: invite.strandId };
+    }
+    return {
+      kind: 'bound',
+      strandId: invite.strandId,
+      memberPrivateKey: strand.MemberPrivateKey ?? null,
+    };
+  }
+
+  /**
+   * Provision a NEW strand for an UNBOUND invite and record consent against it in ONE
+   * transaction (the responder-provisions fallback, now single-use-enforced).
+   *
+   * Mints a fresh, globally-unique strand id from {@link randomBytes} — the same
+   * cross-platform CSPRNG `control-database`'s `generateStampId` uses, NOT
+   * `crypto.randomUUID` / `Date.now` / `Math.random` (not uniformly available across
+   * node/browser/RN) — then delegates to {@link ControlDatabase.redeemInvitation}, whose
+   * single `begin … commit` inserts the consent-authorized `Strand` row AND the matching
+   * `FormationUsage` row together (both deferred CHECKs see both rows at commit). That one
+   * `FormationUsage` row makes the unbound redemption single-use exactly like the bound
+   * path: the next redemption of a `TotalUses:1` invite sees `count 1 >= 1` and is rejected.
+   *
+   * The strand is open (`'o'`) — an unbound responder-provisioned strand has no membership
+   * key — so the returned `memberPrivateKey` is null. `sAppId` is accepted for parity/future
+   * use; `redeemInvitation` does not currently thread it into the `Strand` row.
+   *
+   * A concurrent redemption of the same single-use invite collides on the
+   * `(Token, UseNumber)` PK and this call THROWS for the loser — the manager maps that to a
+   * clean protocol rejection (it never lets the dropped insert close the stream silently).
+   */
+  async provisionAndRecord(
+    token: string,
+    initiatorKey: string,
+    _sAppId: string
+  ): Promise<{ strandId: string; memberPrivateKey: string | null }> {
+    const strandId = `strand-${randomBytes(128, 'hex') as string}`;
+    await this.controlDatabase.redeemInvitation({
+      token,
+      strandId,
+      type: 'o',
+      peerId: initiatorKey,
+    });
+    log('Provisioned + recorded unbound strand: token=%s strand=%s', token, strandId);
+    return { strandId, memberPrivateKey: null };
+  }
+}

package/src/control-schema.ts

@@ -0,0 +1,222 @@
+/**
+ * Embedded control schema for cross-platform compatibility.
+ *
+ * This is the authoritative runtime copy of the CadreControl authorization
+ * schema. It is duplicated from `schemas/control.qsql` so that React Native and
+ * other filesystem-less environments get the schema without a runtime file read.
+ *
+ * The two copies MUST stay identical — `control-schema-drift.spec.ts` fails the
+ * build if they drift. Any edit here must be mirrored in `schemas/control.qsql`
+ * and vice versa.
+ */
+export const CONTROL_SCHEMA = `-- This manages a Sereus party's cadre, or set of nodes, and their participation in strands (networks)
+declare schema CadreControl {
+    -- A key that can authorize various control changes
+    table OwnerKey (
+        Key text primary key,
+        StampId text not null unique,   -- single-use authorization nonce (anti-replay)
+        constraint Authorized check (
+            -- Bootstrap: first owner key needs no existing authorization
+            (select count(1) from OwnerKey) <= 1
+
+                -- Old owner authorizes by signing over THIS row (Key, StampId); single-use via unique StampId
+                or (old.Key is not null and old.Key = context.OwnerKey and verify(digest(new.Key, new.StampId), context.Signature, old.Key, 'ed25519'))
+
+                -- or other owners authorize by signing over THIS row (Key, StampId); single-use via unique StampId
+                or exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(new.Key, new.StampId), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (OwnerKey text null, Signature text null);
+
+    -- A key that can validate a strand formation disclosure
+    table ValidationKey (
+        Key text primary key,
+        StampId text not null unique,   -- single-use authorization nonce (anti-replay)
+        constraint Authorized check (
+            -- Owners authorize by signing over THIS row (Key, StampId); single-use via unique StampId
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(new.Key, new.StampId), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (OwnerKey text, Signature text);
+
+    -- A network of members sharing an sApp database, each contributing peer nodes (their cadre) to the overall cohort
+    -- Cadre peers should participate in each of these strands
+    table Strand (
+        Id text primary key,    -- UUID
+        MemberPrivateKey text null unique,   -- Our private key as a member of this strand
+        Type text, -- Types: 'o' = Open, 'c' = Closed -- Open can still control writes in the sApp, but only Closed controls reads
+        StampId text not null unique,   -- single-use authorization nonce (anti-replay)
+        constraint Authorized check (
+            -- Authorized by an owner signing over THIS row (Id, Type, MemberPrivateKey, StampId); single-use via unique StampId
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
+
+                -- or authorized by a cadre peer who has received a valid formation invitation.
+                -- That path has no signed writer yet; when one is built it must still supply a
+                -- fresh, unique StampId to satisfy the not-null/unique anti-replay column.
+                or exists (select 1 from FormationUsage FU where FU.StrandId = new.Id)
+        ),
+        constraint MemberKeyClosedOnly check (
+            -- An open strand ('o') has no membership gate, so it must not carry a
+            -- member key. A non-null MemberPrivateKey requires a closed strand ('c').
+            new.MemberPrivateKey is null or new.Type = 'c'
+        )
+    ) with context (OwnerKey text, Signature text);
+
+    -- A peer (node) that is part of the cadre, carrying a self-published,
+    -- freshness-stamped, self-signed address record (see PeerAddressRecord in cadre-core).
+    -- The row IS the peer-address record: a resolver reads it, re-verifies Sig against
+    -- PublicKey, checks freshness (UpdatedAt) and trust, then dials the addrs.
+    table CadrePeer (
+        PeerId text primary key,
+        PublicKey text null,            -- ed25519 (base64url) whose libp2p identity == PeerId (null if non-Ed25519)
+        Multiaddr text,                 -- comma-joined current addrs (signaling / p2p-circuit first)
+        UpdatedAt int null,             -- epoch ms; strictly increases per self-update (replay/rollback guard)
+        Sig text null,                  -- ed25519 self-signature over the signed payload (base64url); null until self-published
+        StampId text not null unique,    -- single-use authorization nonce (anti-replay), bound into the voucher/remove digests; rotates on (re)insert
+        VouchOwner text null,        -- ed25519 (base64url) owner key that vouched this membership (== insert context.OwnerKey)
+        VouchSig text null,              -- that owner's signature over digest(PeerId, StampId) (== insert context.Signature). A reader checks VouchOwner against its NODE-LOCAL trusted-owner anchor (not this replicated table, which a self-owner can pollute) to decide authorized membership.
+        constraint AuthorizedInsert check on insert (
+            -- Authorized by an owner key, which vouches both membership and the
+            -- PublicKey<->PeerId binding (cadre-core derives PublicKey from PeerId before insert).
+            -- The digest binds PeerId + the single-use StampId nonce (two TEXT fields),
+            -- matching cadre-core peer-authorization.ts:cadrePeerVoucherDigest.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(new.PeerId, new.StampId), context.Signature, A.Key, 'ed25519'))
+            -- Persist the vouching (owner, signature) onto the row so a reader can later
+            -- re-check VouchOwner against its node-local anchor. The stored pair MUST equal
+            -- the pair the verify above validated, so a writer cannot store a voucher it did
+            -- not actually receive a signature for.
+            and new.VouchOwner = context.OwnerKey
+            and new.VouchSig = context.Signature
+        ),
+        constraint AuthorizedDelete check on delete (
+            -- Delete is authorized by a signature over a DISTINCT 'remove'-scoped digest bound
+            -- to the row's StampId (cadre-core peer-authorization.ts:cadrePeerRemoveDigest), so
+            -- the stored voucher (a signature over digest(PeerId, StampId)) can NEVER be replayed
+            -- to authorize a delete. The remove signature rides in context and is never stored.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(old.PeerId, old.StampId, 'remove'), context.Signature, A.Key, 'ed25519'))
+        ),
+        constraint AuthorizedUpdate check on update (
+            -- Peer self-updates its own addrs + freshness, signing with its OWN ed25519 key
+            -- (the key behind PeerId). PeerId/PublicKey/StampId/voucher are immutable on
+            -- self-update, UpdatedAt must strictly increase (replay guard), and Sig is verified
+            -- against the stored PublicKey over the same payload the publish path signs
+            -- (cadre-core peer-record.ts:peerRecordSignedPayload).
+            (
+                new.PeerId = old.PeerId
+                and new.PublicKey = old.PublicKey
+                and new.StampId = old.StampId
+                and new.VouchOwner = old.VouchOwner
+                and new.VouchSig = old.VouchSig
+                and new.UpdatedAt > coalesce(old.UpdatedAt, 0)
+                and verify(
+                        digest(new.PeerId || '|' || new.Multiaddr || '|' || cast(new.UpdatedAt as text)),
+                        new.Sig, new.PublicKey, 'ed25519')
+            )
+                -- or an owner re-authorizes (rotation / correction): re-vouches the row over
+                -- its current StampId, so the stored voucher is re-bound to the re-authorizing owner.
+                or (
+                    exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(new.PeerId, new.StampId), context.Signature, A.Key, 'ed25519'))
+                    and new.VouchOwner = context.OwnerKey
+                    and new.VouchSig = context.Signature
+                )
+        )
+    ) with context (OwnerKey text null, Signature text);
+
+    -- A mobile cadre peer's platform push token (FCM/APNs), self-published so a
+    -- server peer can deliver a push-wake to a suspended app over the platform push
+    -- channel (a control-network dial cannot reach an OS-suspended process). The row
+    -- mirrors CadrePeer: a resolver re-verifies Sig against the CadrePeer.PublicKey for
+    -- this PeerId (see device-token.ts:deviceTokenSignedPayload), checks freshness, then
+    -- hands the token to the push sender.
+    table DeviceToken (
+        PeerId text primary key,        -- the CadrePeer this token belongs to
+        Platform text not null,         -- 'fcm' | 'apns'
+        Token text not null,            -- opaque platform device/registration token
+        UpdatedAt int null,             -- epoch ms; strictly increases per self-update (replay guard)
+        Sig text null,                  -- ed25519 self-sig over (PeerId|Platform|Token|UpdatedAt)
+        constraint AuthorizedInsert check on insert, delete (
+            -- Authorized by an owner key (membership vouch), exactly like CadrePeer.
+            -- The single-field digest frames the base58btc PeerId as TEXT.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(coalesce(new.PeerId, old.PeerId)), context.Signature, A.Key, 'ed25519'))
+        ),
+        constraint AuthorizedUpdate check on update (
+            -- Peer self-updates its own token, signing with its OWN ed25519 key (the key
+            -- behind PeerId). PeerId is immutable, UpdatedAt must strictly increase (replay
+            -- guard), and Sig is verified against the stored CadrePeer.PublicKey over the
+            -- signed payload (cadre-core device-token.ts:deviceTokenSignedPayload). Platform
+            -- and Token may change on self-update (platform switch / reinstall / rotation).
+            (
+                new.PeerId = old.PeerId
+                and new.UpdatedAt > coalesce(old.UpdatedAt, 0)
+                and exists (select 1 from CadrePeer P where P.PeerId = new.PeerId and verify(
+                        digest(new.PeerId || '|' || new.Platform || '|' || new.Token || '|' || cast(new.UpdatedAt as text)),
+                        new.Sig, P.PublicKey, 'ed25519'))
+            )
+                -- or an owner re-authorizes (rotation / correction)
+                or exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest(new.PeerId), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (OwnerKey text null, Signature text);
+
+    -- An open invitation to form a strand with this party
+    table FormationInvite (
+        Token text primary key, -- Just a random string
+        sAppId text, -- The app for the strand that will be formed
+        ExpiresAt datetime null,
+        TotalUses int null check (TotalUses >= 0),
+        ValidationUrl text null,   -- Web hook - send disclosure, IP address...
+        StrandId text null,   -- Host strand this invite binds to (provision-then-record). Non-null => the responder records consent against this pre-existing strand; null => legacy responder-provisions path.
+        StampId text not null unique,   -- single-use authorization nonce (anti-replay)
+        constraint AuthorizedAddOrRemove check on insert, delete (
+            -- Authorized by an owner signing over THIS row
+            -- (Token, sAppId, ExpiresAt, TotalUses, ValidationUrl, StrandId, StampId); single-use via unique StampId.
+            -- coalesce(new.F, old.F) binds the NEW row on insert and the OLD row on delete (cf. CadrePeer).
+            -- StrandId is a nullable bound field: it signs as '' when absent (cf. ValidationUrl).
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(
+                digest(
+                    coalesce(new.Token, old.Token),
+                    coalesce(new.sAppId, old.sAppId),
+                    coalesce(cast(coalesce(new.ExpiresAt, old.ExpiresAt) as text), ''),
+                    coalesce(cast(coalesce(new.TotalUses, old.TotalUses) as text), ''),
+                    coalesce(coalesce(new.ValidationUrl, old.ValidationUrl), ''),
+                    coalesce(coalesce(new.StrandId, old.StrandId), ''),
+                    coalesce(new.StampId, old.StampId)
+                ),
+                context.Signature, A.Key, 'ed25519'))
+        ),
+        -- Invites are insert/delete only: forbid in-place mutation so the row-bound
+        -- AuthorizedAddOrRemove signature cannot be sidestepped by updating consent
+        -- parameters (TotalUses/ExpiresAt/...) after a legitimate insert. A bare check
+        -- defaults to insert+update; the check on insert, delete above excludes update,
+        -- so this guard is required. Mirrors FormationUsage.InsertOnly.
+        constraint Immutable check on update (false)
+    ) with context (OwnerKey text, Signature text);
+
+    table FormationUsage (
+        Token text,
+        UseNumber int,
+        Disclosure text,
+        StrandId text,
+        primary key (Token, UseNumber),
+        constraint InsertOnly check on update, delete (false),
+        constraint Monotonic check (
+            -- Read the PRE-transaction snapshot (committed.*): this CHECK auto-defers
+            -- to commit (it has a subquery), by which point the row being inserted is
+            -- live, so a plain from-FormationUsage would count this row itself and make
+            -- UseNumber = max+1 unsatisfiable. committed.* excludes the in-flight row,
+            -- giving sequential 1,2,3... per token (cross-transaction; concurrent
+            -- redemptions of the same token collide on the (Token, UseNumber) PK).
+            new.UseNumber = coalesce((select max(UseNumber) from committed.FormationUsage U where U.Token = new.Token), 0) + 1
+        ),
+        constraint Authorized check on insert (
+            -- Satisfies an invitation
+            exists (
+                select 1 from FormationInvite FI
+                    where FI.Token = new.Token
+                        and (FI.TotalUses is null or FI.TotalUses >= new.UseNumber)
+                        and (FI.ExpiresAt is null or FI.ExpiresAt > context.Now)
+                        and (FI.ValidationUrl is null or verify(digest(new.Token || new.Disclosure), context.ValidationSignature, context.ValidationKey, 'ed25519'))
+            )
+        ),
+        constraint StrandExists check (exists (select 1 from Strand S where S.Id = new.StrandId)),
+    ) with context (PeerId text, PeerSignature text, Now datetime, ValidationKey text null, ValidationSignature text null);
+}
+
+apply schema CadreControl;`;

package/src/control-stream.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared control-network stream primitives.
+ *
+ * The cadre control protocols — seed delivery (`seed-bootstrap.ts`), push-wake
+ * (`strand-wake-protocol.ts`), and strand formation (`strand-formation-protocol.ts`)
+ * — all speak 4-byte big-endian length-prefixed JSON frames over a libp2p 3.x
+ * stream. This module lifts the previously-triplicated stream shape, frame
+ * writer, and `withTimeout` wrapper into one place, and adds a timeout-bounded,
+ * abort-on-timeout read-to-EOF helper so a misbehaving peer that opens a stream
+ * and never half-closes its write end cannot pin a receiver forever.
+ *
+ * Dependency-free by design: it imports nothing from the protocol modules, so
+ * the import graph stays acyclic (`control-stream` ← `seed-bootstrap` ←
+ * `strand-wake-protocol`). In particular it returns RAW bytes from
+ * {@link readStreamToEnd} rather than decoding a frame — callers own the
+ * `decodeLengthPrefixedFrame` guard.
+ */
+
+/**
+ * Minimal libp2p 3.x stream surface: AsyncIterable for reads, `send()` for
+ * writes, `close()` to half-close the write end (EOF), `abort()` to reset.
+ */
+export interface ControlStream extends AsyncIterable<Uint8Array> {
+  send(data: Uint8Array): boolean;
+  close(): Promise<void>;
+  abort(err: Error): void;
+}
+
+/** Write a JSON object as a single 4-byte big-endian length-prefixed frame. */
+export function writeFrame(stream: ControlStream, obj: unknown): void {
+  const body = new TextEncoder().encode(JSON.stringify(obj));
+  const prefix = new Uint8Array(4);
+  new DataView(prefix.buffer).setUint32(0, body.length, false);
+  stream.send(prefix);
+  stream.send(body);
+}
+
+/**
+ * Reject if `op` does not settle within `ms`. On timeout, invoke `onTimeout`
+ * (used by the sender to abort the in-flight dial/stream so it does not leak)
+ * before rejecting. A throwing `onTimeout` is swallowed so it cannot mask the
+ * timeout rejection. The rejection message is exactly `<label> timed out after
+ * <ms>ms`, so callers fold any domain prefix into `label`.
+ */
+export function withTimeout<T>(
+  ms: number,
+  label: string,
+  op: () => Promise<T>,
+  onTimeout?: () => void,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      try {
+        onTimeout?.();
+      } catch {
+        // Best-effort: a throwing onTimeout must not replace the timeout error.
+      }
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    op().then(resolve, reject).finally(() => clearTimeout(timer));
+  });
+}
+
+/** Normalize a libp2p chunk (Uint8Array or Uint8ArrayList) to a flat Uint8Array. */
+function toBytes(chunk: Uint8Array | { subarray(): Uint8Array }): Uint8Array {
+  return chunk instanceof Uint8Array ? chunk : chunk.subarray();
+}
+
+/**
+ * Read a stream to EOF, capped at `maxBytes`, bounded by `timeoutMs`, returning
+ * the assembled bytes (the caller decodes via `decodeLengthPrefixedFrame`).
+ *
+ * Implemented as `Promise.race([readLoop, timeout])`:
+ * - The size cap throws synchronously inside `readLoop` (a well-behaved peer may
+ *   have sent a real-but-too-large frame and could still be reading for the ack,
+ *   so this path does NOT abort the stream — it just rejects).
+ * - The timeout path is the true hang: it ALSO calls `stream.abort(err)` to
+ *   release the stuck read. The race guarantees the helper settles at the
+ *   deadline even if `abort()` does not immediately unblock the iterator (e.g. a
+ *   test double whose `abort()` is a no-op).
+ */
+export function readStreamToEnd(
+  stream: ControlStream,
+  opts: { maxBytes: number; timeoutMs: number; label: string },
+): Promise<Uint8Array> {
+  const { maxBytes, timeoutMs, label } = opts;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const err = new Error(`${label} read timed out after ${timeoutMs}ms`);
+      // Release the hung read; the race below settles on `err` regardless of
+      // whether abort() promptly unblocks the iterator.
+      try {
+        stream.abort(err);
+      } catch {
+        // Best-effort: a broken/closed stream may reject abort.
+      }
+      reject(err);
+    }, timeoutMs);
+  });
+
+  const readLoop = collect(stream, maxBytes, label);
+
+  return Promise.race([readLoop, timeout]).finally(() => clearTimeout(timer));
+}
+
+/** Accumulate every chunk to EOF, rejecting once the running total exceeds `maxBytes`. */
+async function collect(stream: ControlStream, maxBytes: number, label: string): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of stream) {
+    const bytes = toBytes(chunk);
+    chunks.push(bytes);
+    total += bytes.length;
+    if (total > maxBytes) {
+      throw new Error(`${label} message too large: ${total} bytes exceeds max ${maxBytes}`);
+    }
+  }
+
+  const data = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    data.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return data;
+}

package/src/device-token.ts

@@ -0,0 +1,89 @@
+/**
+ * Device-token record helpers: the single source of truth for the bytes a node
+ * signs when publishing its own `DeviceToken` row and re-verifies when resolving
+ * another peer's row.
+ *
+ * Modeled directly on {@link peerRecordSignedPayload} (peer-record.ts): the signed
+ * payload is a single SHA-256 digest of a delimited string of the authenticated
+ * fields. It is intentionally NOT JSON-canonicalized — a delimited digest is
+ * trivially deterministic across node/browser/RN (plain string concat + sha256, no
+ * key ordering) and is reconstructable inside the `DeviceToken.AuthorizedUpdate` SQL
+ * constraint from the row's own columns:
+ *
+ *   digest(new.PeerId || '|' || new.Platform || '|' || new.Token || '|'
+ *          || cast(new.UpdatedAt as text))
+ *
+ * Keep {@link deviceTokenSignedPayload} and that constraint byte-for-byte in sync.
+ * The `'|'` delimiter is safe: a base58btc PeerId, a fixed `'fcm'`/`'apns'` platform
+ * string, and a base-10 integer never contain it. The opaque platform token is the
+ * last variable-length field before the integer stamp, so even a token containing a
+ * `'|'` cannot create a collision with a different field split.
+ *
+ * Unlike a peer-address record, a device-token record carries NO public key: the
+ * signature is verified against the `CadrePeer.PublicKey` bound to the same PeerId
+ * (the resolver supplies it), so the key binding is checked exactly once, where the
+ * membership row already lives.
+ */
+
+import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
+import type { DeviceTokenRecord, PushPlatform } from './types.js';
+
+/**
+ * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
+ * `DeviceToken.AuthorizedUpdate` constraint exactly; both sides take the default
+ * base64url output of a single `digest(...)`, which round-trips cleanly.
+ */
+export function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>): string {
+  const joined = `${record.peerId}|${record.platform}|${record.token}|${record.updatedAt}`;
+  return digest([joined], 'sha256', 'base64url') as string;
+}
+
+/**
+ * Sign a device-token record with the ed25519 private key behind its `peerId`.
+ * Returns a fully-populated {@link DeviceTokenRecord}.
+ *
+ * @param fields - the record fields to sign
+ * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
+ */
+export function signDeviceTokenRecord(
+  fields: Omit<DeviceTokenRecord, 'sig'>,
+  privateKeyB64: string
+): DeviceTokenRecord {
+  const payloadDigest = deviceTokenSignedPayload(fields);
+  const sig = sign(
+    payloadDigest,
+    privateKeyB64,
+    'ed25519',
+    'base64url',
+    'base64url',
+    'base64url'
+  ) as string;
+  return { peerId: fields.peerId, platform: fields.platform, token: fields.token, updatedAt: fields.updatedAt, sig };
+}
+
+/**
+ * Verify a record's self-signature against the `CadrePeer.PublicKey` (base64url)
+ * bound to its `peerId`. Reconstructs the signed bytes from the record exactly as
+ * {@link signDeviceTokenRecord} produced them. Returns false on a missing key/sig or
+ * any verification failure.
+ */
+export function verifyDeviceTokenSignature(record: DeviceTokenRecord, publicKeyB64: string): boolean {
+  if (!publicKeyB64 || !record.sig) {
+    return false;
+  }
+  const payloadDigest = deviceTokenSignedPayload(record);
+  return verify(
+    payloadDigest,
+    record.sig,
+    publicKeyB64,
+    'ed25519',
+    'base64url',
+    'base64url',
+    'base64url'
+  );
+}
+
+/** Narrow an arbitrary stored string to a known {@link PushPlatform}. */
+export function isPushPlatform(value: string): value is PushPlatform {
+  return value === 'fcm' || value === 'apns';
+}