@serfab/cadre-core 0.10.0 → 0.12.0

package/src/strand-member-key.ts

@@ -1,39 +1,39 @@
-import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf } from '@libp2p/crypto/keys';
-import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
-import { ed25519KeyPairFromLibp2p, type Ed25519KeyPair } from './ed25519-key.js';
-
-/**
- * Mint a fresh ed25519 strand member private key, encoded as base64 protobuf.
- *
- * Closed strands (`Type:'c'`) gate membership on a `MemberPrivateKey` column
- * (see the `Strand` control-schema table). This produces one in the SAME
- * encoding {@link StrandSolicitationService.formStrand} uses for its
- * `invitePrivateKey`, so a host-minted key and a formation-issued key are
- * interchangeable when attaching a closed strand.
- */
-export async function generateStrandMemberKey(): Promise<string> {
-  const privateKey = await generateKeyPair('Ed25519');
-  return uint8ArrayToString(privateKeyToProtobuf(privateKey), 'base64');
-}
-
-/**
- * Bridge a strand's `MemberPrivateKey` (base64 protobuf libp2p ed25519 key, as
- * minted by {@link generateStrandMemberKey} or issued by formation) into the
- * base64url keypair the strand RBAC constraints consume.
- *
- * The `Strand` control-layer `MemberPrivateKey` is the closed-strand read-gating
- * secret; the founding `Member.Key`/`Manager.MemberKey` (the strand RBAC layer)
- * are *derived from it* — they are the `publicKeyB64` of the keypair this returns.
- * Decode the protobuf to a libp2p private key, then reuse
- * {@link ed25519KeyPairFromLibp2p} so the same seed→public derivation used for node
- * owner keys yields a stable `{ privateKeyB64, publicKeyB64 }` whose public
- * key a later strand signature verifies against.
- *
- * @param memberPrivateKey - The strand's `MemberPrivateKey` (base64 protobuf).
- * @returns The base64url seed/public-key pair for founding membership/manager.
- * @throws If the decoded key is not Ed25519 or the raw bytes are malformed.
- */
-export function strandMemberKeyPair(memberPrivateKey: string): Ed25519KeyPair {
-  const privateKey = privateKeyFromProtobuf(uint8ArrayFromString(memberPrivateKey, 'base64'));
-  return ed25519KeyPairFromLibp2p(privateKey);
-}
+import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf } from '@libp2p/crypto/keys';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { ed25519KeyPairFromLibp2p, type Ed25519KeyPair } from './ed25519-key.js';
+
+/**
+ * Mint a fresh ed25519 strand member private key, encoded as base64 protobuf.
+ *
+ * Closed strands (`Type:'c'`) gate membership on a `MemberPrivateKey` column
+ * (see the `Strand` control-schema table). This produces one in the SAME
+ * encoding {@link StrandSolicitationService.formStrand} uses for its
+ * `invitePrivateKey`, so a host-minted key and a formation-issued key are
+ * interchangeable when attaching a closed strand.
+ */
+export async function generateStrandMemberKey(): Promise<string> {
+  const privateKey = await generateKeyPair('Ed25519');
+  return uint8ArrayToString(privateKeyToProtobuf(privateKey), 'base64');
+}
+
+/**
+ * Bridge a strand's `MemberPrivateKey` (base64 protobuf libp2p ed25519 key, as
+ * minted by {@link generateStrandMemberKey} or issued by formation) into the
+ * base64url keypair the strand RBAC constraints consume.
+ *
+ * The `Strand` control-layer `MemberPrivateKey` is the closed-strand read-gating
+ * secret; the founding `Member.Key`/`Manager.MemberKey` (the strand RBAC layer)
+ * are *derived from it* — they are the `publicKeyB64` of the keypair this returns.
+ * Decode the protobuf to a libp2p private key, then reuse
+ * {@link ed25519KeyPairFromLibp2p} so the same seed→public derivation used for node
+ * owner keys yields a stable `{ privateKeyB64, publicKeyB64 }` whose public
+ * key a later strand signature verifies against.
+ *
+ * @param memberPrivateKey - The strand's `MemberPrivateKey` (base64 protobuf).
+ * @returns The base64url seed/public-key pair for founding membership/manager.
+ * @throws If the decoded key is not Ed25519 or the raw bytes are malformed.
+ */
+export function strandMemberKeyPair(memberPrivateKey: string): Ed25519KeyPair {
+  const privateKey = privateKeyFromProtobuf(uint8ArrayFromString(memberPrivateKey, 'base64'));
+  return ed25519KeyPairFromLibp2p(privateKey);
+}

package/src/strand-member-registry.ts

@@ -1,182 +1,182 @@
-import debug from 'debug';
-import type { Database, SqlValue } from '@quereus/quereus';
-import type { MemberRegistration } from './types.js';
-import type { MemberRegistry, MemberVerifier } from './enrollment.js';
-import type { Ed25519KeyPair } from './ed25519-key.js';
-import {
-  verifyStrandPayload,
-  consumeInvite,
-  addMemberByManager,
-  listOutstandingInvites,
-} from './strand-membership-writer.js';
-
-const log = debug('sereus:cadre:strand-member-registry');
-
-/**
- * The canonical payload a joining member signs to prove ownership of its strand
- * member key, verified by {@link StrandMemberVerifier.verifyMember}.
- *
- * Binds the member key to the strand id so a registration signature cannot be
- * replayed against a different strand. Peer-id binding is intentionally NOT part
- * of this payload — `MemberPeer` rows carry their OWN per-peer self-proofs
- * (`MemberKey || '|' || PeerId`, signed by the member) and are written by the
- * dedicated `registerMemberPeer` writer; see {@link StrandMemberRegistry}.
- */
-export function memberRegistrationPayload(registration: MemberRegistration): string {
-  return `${registration.strandId}|${registration.key}`;
-}
-
-/** How a {@link StrandMemberRegistry} admits a member into the strand. */
-export type StrandAdmission =
-  | {
-      /** Redeem a specific single-use invite (the invitee-side join). */
-      readonly mode: 'invite';
-      /** The `Invite.Key` (invite public key, base64url) to redeem. */
-      readonly inviteKey: string;
-      /** The matching invite private seed (base64url), received out-of-band. */
-      readonly invitePrivateKey: string;
-    }
-  | {
-      /** Admit directly by manager signature (the manager-side join). */
-      readonly mode: 'manager';
-      /** The admitting manager's strand keypair. */
-      readonly managerKeyPair: Ed25519KeyPair;
-    };
-
-/**
- * Strand-`Database`-backed {@link MemberVerifier} — the reconciliation that lets
- * {@link EnrollmentService} make real authorization decisions against a strand's
- * `Invite`/`ConsumedInvite`/`Member` tables instead of a placeholder.
- *
- * Each instance is scoped to ONE strand's database (the `Strand.*` tables live
- * inside the connected strand DB), so the `strandId` arguments on the interface
- * are accepted for signature compatibility but the queries run against this db.
- */
-export class StrandMemberVerifier implements MemberVerifier {
-  constructor(private readonly db: Database) {}
-
-  /**
-   * Verify the member's self-proof over {@link memberRegistrationPayload} against
-   * the registration's own `key` (the member's ed25519 public key). This is the
-   * off-engine counterpart to the on-engine signature checks — a pre-flight gate
-   * before the constraint-enforced write.
-   */
-  async verifyMember(registration: MemberRegistration, signature: string): Promise<boolean> {
-    const ok = verifyStrandPayload(memberRegistrationPayload(registration), signature, registration.key);
-    if (!ok) {
-      log('verifyMember: bad self-proof for member %s on strand %s', registration.key, registration.strandId);
-    }
-    return ok;
-  }
-
-  /**
-   * A member is authorized to join when either it has already consumed an invite
-   * (a `ConsumedInvite` row bears its key) OR the strand has at least one
-   * outstanding `Invite` it could redeem.
-   *
-   * Strand invites are anonymous — `Invite.Key` is an invite public key, not a
-   * member key, so an un-consumed invite cannot be bound to a specific member
-   * here. This check is therefore a "door is open" pre-flight; the binding,
-   * single-use, and cryptographic gates are all enforced by the deferred
-   * `Strand.*` constraints when the member is actually written.
-   *
-   * "Outstanding" is {@link listOutstandingInvites}: an `Invite` that is neither
-   * already consumed, nor cancelled by a manager, nor expired. All three exclusions
-   * mirror gates the actual write would hit (`ConsumedInvite`'s primary key,
-   * `NotCancelled`, `NotExpired`), so this pre-flight does not report a door the
-   * constraints will slam. A raw `Invite` count would over-report on all three.
-   */
-  async isAuthorizedToJoin(_strandId: string, memberKey: string): Promise<boolean> {
-    const consumed = await scalarCount(
-      this.db,
-      'select count(1) as c from Strand.ConsumedInvite where MemberKey = ?',
-      [memberKey],
-    );
-    if (consumed > 0) {
-      // NOTE: a REVOKED member still bears its stale ConsumedInvite row (the table is
-      // insert-only, and revocation does not delete it), so this short-circuit says
-      // "authorized" for a party that can no longer actually join. Harmless because the
-      // on-engine constraints are the real gate — Member.Authorized's invite branch
-      // requires a FRESH consumption row, which a stale one is not — and this pre-flight
-      // only decides whether attempting the write is worthwhile.
-      return true;
-    }
-    // NOTE: materialises the whole outstanding set to answer a non-empty question (the
-    // former code was a single `select count(1)`). Deliberate — sharing one definition of
-    // "outstanding" with the manager-facing enumeration beats a second, drifting copy of
-    // the three exclusions. If this pre-flight ever runs hot on a strand with many
-    // invitations, add a short-circuiting variant rather than re-inlining the rules.
-    return (await listOutstandingInvites(this.db)).length > 0;
-  }
-}
-
-/**
- * Strand-`Database`-backed {@link MemberRegistry} — writes real `Strand.Member`
- * (and, in invite mode, `Strand.ConsumedInvite`) rows through the signed writer
- * primitives, so {@link EnrollmentService.registerMember} performs the actual
- * per-strand join handshake rather than returning "MemberRegistry not configured".
- *
- * The {@link StrandAdmission} chosen at construction selects which branch of
- * `Member.Authorized` is taken:
- * - `invite`  → {@link consumeInvite} (atomic `Member` + `ConsumedInvite`), the
- *   invitee-side flow that redeems a single-use invite.
- * - `manager` → {@link addMemberByManager}, the manager-side flow that
- *   seats a member already trusted by a manager.
- *
- * Scoped to one strand's db; the `strandId` argument is accepted for interface
- * compatibility but writes target this db's `Strand.*` tables.
- *
- * NOTE: `peerIds` are NOT written as `MemberPeer` rows here. The signed peer path
- * now exists as the standalone `registerMemberPeer` writer (each peer self-proof is
- * signed by the member's own key), but wiring the enrollment `peerIds` through it is
- * a deliberate follow-on — the member self-proof available here does not carry the
- * per-peer signatures `MemberPeer.Authorized` requires. A non-empty `peerIds` is
- * logged and otherwise ignored so the member still lands; peer rows are reconciled
- * separately via `registerMemberPeer`.
- */
-export class StrandMemberRegistry implements MemberRegistry {
-  constructor(
-    private readonly db: Database,
-    private readonly admission: StrandAdmission,
-  ) {}
-
-  async registerMember(strandId: string, memberKey: string, peerIds: string[]): Promise<void> {
-    if (peerIds.length > 0) {
-      log(
-        'registerMember: %d peerId(s) for member %s on strand %s deferred to the registerMemberPeer path (needs per-peer self-proofs); registering member only',
-        peerIds.length, memberKey, strandId,
-      );
-    }
-
-    if (this.admission.mode === 'invite') {
-      await consumeInvite(this.db, {
-        inviteKey: this.admission.inviteKey,
-        invitePrivateKey: this.admission.invitePrivateKey,
-        memberKey,
-      });
-      return;
-    }
-
-    await addMemberByManager(this.db, {
-      managerKeyPair: this.admission.managerKeyPair,
-      memberKey,
-    });
-  }
-
-  async isMemberRegistered(_strandId: string, memberKey: string): Promise<boolean> {
-    const count = await scalarCount(
-      this.db,
-      'select count(1) as c from Strand.Member where Key = ?',
-      [memberKey],
-    );
-    return count > 0;
-  }
-}
-
-/** Run a `select count(1) as c ...` and return the scalar (0 if no row). */
-async function scalarCount(db: Database, sql: string, params: SqlValue[]): Promise<number> {
-  for await (const row of db.eval(sql, params)) {
-    return (row.c as number) ?? 0;
-  }
-  return 0;
-}
+import debug from 'debug';
+import type { Database, SqlValue } from '@quereus/quereus';
+import type { MemberRegistration } from './types.js';
+import type { MemberRegistry, MemberVerifier } from './enrollment.js';
+import type { Ed25519KeyPair } from './ed25519-key.js';
+import {
+  verifyStrandPayload,
+  consumeInvite,
+  addMemberByManager,
+  listOutstandingInvites,
+} from './strand-membership-writer.js';
+
+const log = debug('sereus:cadre:strand-member-registry');
+
+/**
+ * The canonical payload a joining member signs to prove ownership of its strand
+ * member key, verified by {@link StrandMemberVerifier.verifyMember}.
+ *
+ * Binds the member key to the strand id so a registration signature cannot be
+ * replayed against a different strand. Peer-id binding is intentionally NOT part
+ * of this payload — `MemberPeer` rows carry their OWN per-peer self-proofs
+ * (`MemberKey || '|' || PeerId`, signed by the member) and are written by the
+ * dedicated `registerMemberPeer` writer; see {@link StrandMemberRegistry}.
+ */
+export function memberRegistrationPayload(registration: MemberRegistration): string {
+  return `${registration.strandId}|${registration.key}`;
+}
+
+/** How a {@link StrandMemberRegistry} admits a member into the strand. */
+export type StrandAdmission =
+  | {
+      /** Redeem a specific single-use invite (the invitee-side join). */
+      readonly mode: 'invite';
+      /** The `Invite.Key` (invite public key, base64url) to redeem. */
+      readonly inviteKey: string;
+      /** The matching invite private seed (base64url), received out-of-band. */
+      readonly invitePrivateKey: string;
+    }
+  | {
+      /** Admit directly by manager signature (the manager-side join). */
+      readonly mode: 'manager';
+      /** The admitting manager's strand keypair. */
+      readonly managerKeyPair: Ed25519KeyPair;
+    };
+
+/**
+ * Strand-`Database`-backed {@link MemberVerifier} — the reconciliation that lets
+ * {@link EnrollmentService} make real authorization decisions against a strand's
+ * `Invite`/`ConsumedInvite`/`Member` tables instead of a placeholder.
+ *
+ * Each instance is scoped to ONE strand's database (the `Strand.*` tables live
+ * inside the connected strand DB), so the `strandId` arguments on the interface
+ * are accepted for signature compatibility but the queries run against this db.
+ */
+export class StrandMemberVerifier implements MemberVerifier {
+  constructor(private readonly db: Database) {}
+
+  /**
+   * Verify the member's self-proof over {@link memberRegistrationPayload} against
+   * the registration's own `key` (the member's ed25519 public key). This is the
+   * off-engine counterpart to the on-engine signature checks — a pre-flight gate
+   * before the constraint-enforced write.
+   */
+  async verifyMember(registration: MemberRegistration, signature: string): Promise<boolean> {
+    const ok = verifyStrandPayload(memberRegistrationPayload(registration), signature, registration.key);
+    if (!ok) {
+      log('verifyMember: bad self-proof for member %s on strand %s', registration.key, registration.strandId);
+    }
+    return ok;
+  }
+
+  /**
+   * A member is authorized to join when either it has already consumed an invite
+   * (a `ConsumedInvite` row bears its key) OR the strand has at least one
+   * outstanding `Invite` it could redeem.
+   *
+   * Strand invites are anonymous — `Invite.Key` is an invite public key, not a
+   * member key, so an un-consumed invite cannot be bound to a specific member
+   * here. This check is therefore a "door is open" pre-flight; the binding,
+   * single-use, and cryptographic gates are all enforced by the deferred
+   * `Strand.*` constraints when the member is actually written.
+   *
+   * "Outstanding" is {@link listOutstandingInvites}: an `Invite` that is neither
+   * already consumed, nor cancelled by a manager, nor expired. All three exclusions
+   * mirror gates the actual write would hit (`ConsumedInvite`'s primary key,
+   * `NotCancelled`, `NotExpired`), so this pre-flight does not report a door the
+   * constraints will slam. A raw `Invite` count would over-report on all three.
+   */
+  async isAuthorizedToJoin(_strandId: string, memberKey: string): Promise<boolean> {
+    const consumed = await scalarCount(
+      this.db,
+      'select count(1) as c from Strand.ConsumedInvite where MemberKey = ?',
+      [memberKey],
+    );
+    if (consumed > 0) {
+      // NOTE: a REVOKED member still bears its stale ConsumedInvite row (the table is
+      // insert-only, and revocation does not delete it), so this short-circuit says
+      // "authorized" for a party that can no longer actually join. Harmless because the
+      // on-engine constraints are the real gate — Member.Authorized's invite branch
+      // requires a FRESH consumption row, which a stale one is not — and this pre-flight
+      // only decides whether attempting the write is worthwhile.
+      return true;
+    }
+    // NOTE: materialises the whole outstanding set to answer a non-empty question (the
+    // former code was a single `select count(1)`). Deliberate — sharing one definition of
+    // "outstanding" with the manager-facing enumeration beats a second, drifting copy of
+    // the three exclusions. If this pre-flight ever runs hot on a strand with many
+    // invitations, add a short-circuiting variant rather than re-inlining the rules.
+    return (await listOutstandingInvites(this.db)).length > 0;
+  }
+}
+
+/**
+ * Strand-`Database`-backed {@link MemberRegistry} — writes real `Strand.Member`
+ * (and, in invite mode, `Strand.ConsumedInvite`) rows through the signed writer
+ * primitives, so {@link EnrollmentService.registerMember} performs the actual
+ * per-strand join handshake rather than returning "MemberRegistry not configured".
+ *
+ * The {@link StrandAdmission} chosen at construction selects which branch of
+ * `Member.Authorized` is taken:
+ * - `invite`  → {@link consumeInvite} (atomic `Member` + `ConsumedInvite`), the
+ *   invitee-side flow that redeems a single-use invite.
+ * - `manager` → {@link addMemberByManager}, the manager-side flow that
+ *   seats a member already trusted by a manager.
+ *
+ * Scoped to one strand's db; the `strandId` argument is accepted for interface
+ * compatibility but writes target this db's `Strand.*` tables.
+ *
+ * NOTE: `peerIds` are NOT written as `MemberPeer` rows here. The signed peer path
+ * now exists as the standalone `registerMemberPeer` writer (each peer self-proof is
+ * signed by the member's own key), but wiring the enrollment `peerIds` through it is
+ * a deliberate follow-on — the member self-proof available here does not carry the
+ * per-peer signatures `MemberPeer.Authorized` requires. A non-empty `peerIds` is
+ * logged and otherwise ignored so the member still lands; peer rows are reconciled
+ * separately via `registerMemberPeer`.
+ */
+export class StrandMemberRegistry implements MemberRegistry {
+  constructor(
+    private readonly db: Database,
+    private readonly admission: StrandAdmission,
+  ) {}
+
+  async registerMember(strandId: string, memberKey: string, peerIds: string[]): Promise<void> {
+    if (peerIds.length > 0) {
+      log(
+        'registerMember: %d peerId(s) for member %s on strand %s deferred to the registerMemberPeer path (needs per-peer self-proofs); registering member only',
+        peerIds.length, memberKey, strandId,
+      );
+    }
+
+    if (this.admission.mode === 'invite') {
+      await consumeInvite(this.db, {
+        inviteKey: this.admission.inviteKey,
+        invitePrivateKey: this.admission.invitePrivateKey,
+        memberKey,
+      });
+      return;
+    }
+
+    await addMemberByManager(this.db, {
+      managerKeyPair: this.admission.managerKeyPair,
+      memberKey,
+    });
+  }
+
+  async isMemberRegistered(_strandId: string, memberKey: string): Promise<boolean> {
+    const count = await scalarCount(
+      this.db,
+      'select count(1) as c from Strand.Member where Key = ?',
+      [memberKey],
+    );
+    return count > 0;
+  }
+}
+
+/** Run a `select count(1) as c ...` and return the scalar (0 if no row). */
+async function scalarCount(db: Database, sql: string, params: SqlValue[]): Promise<number> {
+  for await (const row of db.eval(sql, params)) {
+    return (row.c as number) ?? 0;
+  }
+  return 0;
+}