@serfab/cadre-core 0.10.0 → 0.11.0

package/src/strand-transport-key.ts

@@ -1,58 +1,58 @@
-import { generateKeyPairFromSeed } from '@libp2p/crypto/keys';
-import type { PrivateKey } from '@libp2p/interface';
-import { digest } from '@optimystic/quereus-plugin-crypto';
-import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
-
-/**
- * Domain-separation tag for the strand-transport-key derivation. Versioned so a
- * future change to the derivation (different KDF, different inputs) can bump to
- * `.v2` and be recognized as a deliberate identity migration rather than silent
- * peerId churn — a strand node's transport peerId must stay stable across
- * process restarts, or any peer-store entry or `MemberPeer` row that names it
- * goes stale on every boot.
- */
-const STRAND_TRANSPORT_KEY_DOMAIN = 'sereus.strand-transport-key.v1';
-
-/**
- * Derive a strand node's libp2p transport key from the cadre identity key and
- * the strand id.
- *
- * A `CadreNode` runs its control node and each strand node as separate libp2p
- * instances. Handing them all the same private key gives them all the same
- * peerId, and `@libp2p/circuit-relay-v2` keys reservations and hop-connects by
- * peerId — so a control node and a strand node reserving through one shared
- * relay collide, and relayed streams for one land on the other
- * (https://github.com/gotchoices/sereus/issues/1). Each strand node therefore
- * gets its own transport identity. Cadre *authority* is untouched: the control
- * node keeps the identity key, and every peerId→authority derivation
- * (`ed25519PublicKeyB64FromPeerId`) is a control-network path.
- *
- * The derivation is deterministic — `sha256(domain, identity seed, strandId)`
- * as an Ed25519 seed — rather than a fresh random key per launch, so the
- * strand's transport peerId survives restarts. The identity *private* seed is
- * an input (not the public key) so that no third party can enumerate a member's
- * strand peerIds from public data; only the key holder can compute them.
- *
- * NOTE: the derived peerId *is* attested at runtime: before a strand node
- * starts, its control node announces it over the strand-addr RPC, and a
- * membership-gated relay (a party control node running the relay server) holds
- * a short-lived delegate admission grant for it (`delegate-admission.ts`) —
- * without that grant the relay denies the strand node's reservation and
- * `libp2p.start()` fails. The strand *mesh* itself still does not gate
- * admission by peerId (strand peers are legitimately cross-party); if
- * strand-mesh admission control is ever added, the durable binding it needs is
- * a `MemberPeer(MemberKey, PeerId)` row: the table and its self-signed
- * `Authorized` constraint already exist in `schemas/strand.qsql`; production
- * code simply never writes one.
- *
- * @param identityKey - The cadre's Ed25519 identity key (the control node's key).
- * @param strandId - The strand whose transport key to derive.
- * @returns A stable, per-strand Ed25519 libp2p private key, distinct from the
- *   identity key and from every other strand's.
- * @throws If the identity key is not Ed25519.
- */
-export async function strandTransportKey(identityKey: PrivateKey, strandId: string): Promise<PrivateKey> {
-  const { privateKeyB64 } = ed25519KeyPairFromLibp2p(identityKey);
-  const seed = digest([STRAND_TRANSPORT_KEY_DOMAIN, privateKeyB64, strandId], 'sha256', 'bytes') as Uint8Array;
-  return generateKeyPairFromSeed('Ed25519', seed);
-}
+import { generateKeyPairFromSeed } from '@libp2p/crypto/keys';
+import type { PrivateKey } from '@libp2p/interface';
+import { digest } from '@optimystic/quereus-plugin-crypto';
+import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
+
+/**
+ * Domain-separation tag for the strand-transport-key derivation. Versioned so a
+ * future change to the derivation (different KDF, different inputs) can bump to
+ * `.v2` and be recognized as a deliberate identity migration rather than silent
+ * peerId churn — a strand node's transport peerId must stay stable across
+ * process restarts, or any peer-store entry or `MemberPeer` row that names it
+ * goes stale on every boot.
+ */
+const STRAND_TRANSPORT_KEY_DOMAIN = 'sereus.strand-transport-key.v1';
+
+/**
+ * Derive a strand node's libp2p transport key from the cadre identity key and
+ * the strand id.
+ *
+ * A `CadreNode` runs its control node and each strand node as separate libp2p
+ * instances. Handing them all the same private key gives them all the same
+ * peerId, and `@libp2p/circuit-relay-v2` keys reservations and hop-connects by
+ * peerId — so a control node and a strand node reserving through one shared
+ * relay collide, and relayed streams for one land on the other
+ * (https://github.com/gotchoices/sereus/issues/1). Each strand node therefore
+ * gets its own transport identity. Cadre *authority* is untouched: the control
+ * node keeps the identity key, and every peerId→authority derivation
+ * (`ed25519PublicKeyB64FromPeerId`) is a control-network path.
+ *
+ * The derivation is deterministic — `sha256(domain, identity seed, strandId)`
+ * as an Ed25519 seed — rather than a fresh random key per launch, so the
+ * strand's transport peerId survives restarts. The identity *private* seed is
+ * an input (not the public key) so that no third party can enumerate a member's
+ * strand peerIds from public data; only the key holder can compute them.
+ *
+ * NOTE: the derived peerId *is* attested at runtime: before a strand node
+ * starts, its control node announces it over the strand-addr RPC, and a
+ * membership-gated relay (a party control node running the relay server) holds
+ * a short-lived delegate admission grant for it (`delegate-admission.ts`) —
+ * without that grant the relay denies the strand node's reservation and
+ * `libp2p.start()` fails. The strand *mesh* itself still does not gate
+ * admission by peerId (strand peers are legitimately cross-party); if
+ * strand-mesh admission control is ever added, the durable binding it needs is
+ * a `MemberPeer(MemberKey, PeerId)` row: the table and its self-signed
+ * `Authorized` constraint already exist in `schemas/strand.qsql`; production
+ * code simply never writes one.
+ *
+ * @param identityKey - The cadre's Ed25519 identity key (the control node's key).
+ * @param strandId - The strand whose transport key to derive.
+ * @returns A stable, per-strand Ed25519 libp2p private key, distinct from the
+ *   identity key and from every other strand's.
+ * @throws If the identity key is not Ed25519.
+ */
+export async function strandTransportKey(identityKey: PrivateKey, strandId: string): Promise<PrivateKey> {
+  const { privateKeyB64 } = ed25519KeyPairFromLibp2p(identityKey);
+  const seed = digest([STRAND_TRANSPORT_KEY_DOMAIN, privateKeyB64, strandId], 'sha256', 'bytes') as Uint8Array;
+  return generateKeyPairFromSeed('Ed25519', seed);
+}

package/src/strand-wake-payload.ts

@@ -1,32 +1,32 @@
-/**
- * strand-wake-payload.ts — the canonical wire contract for a strand-wake data
- * message, shared by the server-side sender (`PushNotifier`, this package) and
- * the mobile receiver (`@serfab/reference-app-rn`'s `push-wake.ts`).
- *
- * A strand-wake is a data-only push delivered to an OS-suspended phone over its
- * platform channel (FCM/APNs) when a control-network dial cannot reach the
- * hibernating process. It names the strand that has pending activity so the phone
- * can run one `serviceWake` cycle and re-hibernate.
- *
- * This module is intentionally dependency-free (no node/RN/browser-specific
- * imports) so it sits cleanly on the cross-platform `cadre-core` entry and can be
- * re-exported by the RN receive module without dragging any platform code across
- * the send/receive boundary. The defensive `parseStrandWakePayload` parser stays
- * on the receive side (it guards untrusted wire input); the sender constructs
- * payloads from typed fields and never parses.
- */
-
-/** Discriminator value carried by a strand-wake data message. */
-export const STRAND_WAKE_TYPE = 'strand-wake';
-
-/**
- * A data-only push payload telling a suspended phone that `strandId` has pending
- * activity. Delivered addressed to the phone's resolved `DeviceToken`.
- */
-export interface StrandWakePayload {
-  type: typeof STRAND_WAKE_TYPE;
-  /** The strand the wake is for. */
-  strandId: string;
-  /** Why the wake was sent (e.g. `'activity'`). Free-form, for diagnostics. */
-  reason: string;
-}
+/**
+ * strand-wake-payload.ts — the canonical wire contract for a strand-wake data
+ * message, shared by the server-side sender (`PushNotifier`, this package) and
+ * the mobile receiver (`@serfab/reference-app-rn`'s `push-wake.ts`).
+ *
+ * A strand-wake is a data-only push delivered to an OS-suspended phone over its
+ * platform channel (FCM/APNs) when a control-network dial cannot reach the
+ * hibernating process. It names the strand that has pending activity so the phone
+ * can run one `serviceWake` cycle and re-hibernate.
+ *
+ * This module is intentionally dependency-free (no node/RN/browser-specific
+ * imports) so it sits cleanly on the cross-platform `cadre-core` entry and can be
+ * re-exported by the RN receive module without dragging any platform code across
+ * the send/receive boundary. The defensive `parseStrandWakePayload` parser stays
+ * on the receive side (it guards untrusted wire input); the sender constructs
+ * payloads from typed fields and never parses.
+ */
+
+/** Discriminator value carried by a strand-wake data message. */
+export const STRAND_WAKE_TYPE = 'strand-wake';
+
+/**
+ * A data-only push payload telling a suspended phone that `strandId` has pending
+ * activity. Delivered addressed to the phone's resolved `DeviceToken`.
+ */
+export interface StrandWakePayload {
+  type: typeof STRAND_WAKE_TYPE;
+  /** The strand the wake is for. */
+  strandId: string;
+  /** Why the wake was sent (e.g. `'activity'`). Free-form, for diagnostics. */
+  reason: string;
+}