@serfab/cadre-core 0.12.0 → 1.0.0

package/src/strand-member-key.ts

@@ -5,11 +5,16 @@ 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.
+ * Used for BOTH closed-strand key roles, which share this encoding but are
+ * deliberately different keys:
+ *  - the strand-wide read secret (`Strand.MemberPrivateKey`), which formation
+ *    hands to every joining party — 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;
+ *  - a single party's own membership identity (the control-layer `StrandPartyKey`
+ *    row, minted by `CadreNode.ensureStrandPartyKey`), never shared outside the
+ *    party.
  */
 export async function generateStrandMemberKey(): Promise<string> {
   const privateKey = await generateKeyPair('Ed25519');
@@ -17,20 +22,23 @@ export async function generateStrandMemberKey(): Promise<string> {
 }
 
 /**
- * Bridge a strand's `MemberPrivateKey` (base64 protobuf libp2p ed25519 key, as
+ * Bridge a strand membership private key (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
+ * The founding `Member.Key`/`Manager.MemberKey` (the strand RBAC layer) are the
+ * `publicKeyB64` of the keypair this returns, derived from the PARTY's own
+ * `StrandPartyKey.PrivateKey` — deliberately NOT from the strand row's
+ * `MemberPrivateKey`, which is the strand-wide read secret every joining party
+ * receives (an identity derived from it is one every joiner can forge —
+ * gotchoices/sereus#4). Both keys share this encoding, so this decoder serves
+ * either. 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.
+ * @param memberPrivateKey - A strand membership private key (base64 protobuf).
+ * @returns The base64url seed/public-key pair for strand membership signing.
  * @throws If the decoded key is not Ed25519 or the raw bytes are malformed.
  */
 export function strandMemberKeyPair(memberPrivateKey: string): Ed25519KeyPair {

package/src/strand-member-registry.ts

@@ -148,6 +148,9 @@ export class StrandMemberRegistry implements MemberRegistry {
       );
     }
 
+    // NOTE: both writers run in default (joining) mode. Nothing in cadre-core wires this
+    // registry to a live strand today; if a network handler ever drives it on a database
+    // the app also holds, pass `{ joinOpenTransaction: false }` as the reconciler does.
     if (this.admission.mode === 'invite') {
       await consumeInvite(this.db, {
         inviteKey: this.admission.inviteKey,