@serfab/cadre-core 0.7.1 → 0.9.0

package/src/strand-instance-manager.ts

@@ -1,7 +1,6 @@
 import debug from 'debug';
-import type { Libp2p, PrivateKey } from '@libp2p/interface';
+import type { PrivateKey } from '@libp2p/interface';
 import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
-import type { IRepo } from '@optimystic/db-core';
 import { StrandDatabase } from './strand-database.js';
 import { assertSchemaSignature } from './schema-verification.js';
 import type {
@@ -14,17 +13,10 @@ import type {
   SAppConfig,
   SAppInfo,
   RawStorageProvider,
-  StrandMode
+  StrandMode,
+  Libp2pNodeWithRepo
 } from './types.js';
 
-/**
- * Extended Libp2p node with coordinatedRepo attached by createLibp2pNode.
- * The db-p2p createLibp2pNode function attaches these properties after node creation.
- */
-interface Libp2pNodeWithRepo extends Libp2p {
-  coordinatedRepo: IRepo;
-}
-
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
 
@@ -40,19 +32,48 @@ export interface StartStrandConfig {
   profile: NodeProfile;
   defaultLatencyHint: LatencyHint;
   privateKey?: PrivateKey;
+  /** Cohort-derived discovery seed (multiaddr strings). Defaults to [] when omitted. */
+  bootstrapNodes?: string[];
   /**
    * Lifecycle mode for this strand; selects the default transactor used by the
-   * StrandDatabase. Defaults to `'networked'` when omitted.
+   * StrandDatabase. When omitted, the StrandDatabase falls back to `'networked'`;
+   * callers (CadreNode) infer it from cohort membership before reaching here.
+   */
+  mode?: StrandMode;
+  /**
+   * Require a valid author signature on the sApp schema before bring-up.
+   * Defaults to true (fail closed) when omitted; set false only for dev/test
+   * with unsigned demo schemas. Mirrors {@link CadreNodeConfig.requireSignedSchemas}.
    */
+  requireSignedSchemas?: boolean;
+  /**
+   * Whether this node founds the strand (vs. joins it). Forwarded to the
+   * StrandDatabase so the founder bootstrap (Header, founding Member/Manager)
+   * runs once at bring-up. Joiners leave this unset and write nothing. See
+   * {@link StrandConfig.founder}.
+   */
+  founder?: boolean;
+}
+
+/**
+ * Volatile inputs re-resolved when resuming a quiesced strand. These may have
+ * changed since the strand first launched — the cohort discovery seed grows as
+ * peers are learned, and cohort membership can push a strand `bootstrap → networked`.
+ */
+export interface ResumeStrandOverrides {
+  /** Freshly-resolved cohort discovery seed (multiaddr strings). */
+  bootstrapNodes?: string[];
+  /** Freshly-resolved lifecycle mode. */
   mode?: StrandMode;
 }
 
 /**
  * Get the isolated storage path for a specific strand.
  *
- * @deprecated This function uses Node.js path module which is not available in React Native.
- * Use a storage provider factory function instead, which receives the strandId and can
- * create strand-specific storage paths using platform-appropriate methods.
+ * @deprecated This helper is Node-only and throws in React Native (it assumes a
+ * filesystem layout). Use a storage provider factory function instead, which
+ * receives the strandId and can create strand-specific storage paths using
+ * platform-appropriate methods.
  *
  * @example
  * // Instead of using getStrandStoragePath, use a storage provider factory:
@@ -69,13 +90,16 @@ export function getStrandStoragePath(basePath: string, strandId: string): string
     );
   }
 
-  // Dynamically require path only in Node.js
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const path = require('path');
-
   // Sanitize strandId for filesystem safety (UUIDs should be safe, but just in case)
   const safeId = strandId.replace(/[^a-zA-Z0-9-]/g, '_');
-  return path.join(basePath, 'strands', safeId);
+
+  // Build the path with plain string joins rather than the Node `path` module.
+  // A static `require('path')` forces RN bundlers (e.g. Metro) to *resolve* the
+  // module at bundle time even though this Node-only helper throws above before
+  // ever reaching here — joining by hand keeps the module free of any Node
+  // built-in reference, so RN bundles need no `path` shim.
+  const trimmedBase = basePath.replace(/[\\/]+$/, '');
+  return `${trimmedBase}/strands/${safeId}`;
 }
 
 /**
@@ -102,6 +126,12 @@ function resolveStrandStorage(
  */
 export class StrandInstanceManager {
   private instances: Map<string, StrandInstance> = new Map();
+  /**
+   * Retained launch config per strand, captured in `startStrand` and cleared in
+   * `stopStrand`. `resumeStrand` reuses it to rebuild a quiesced strand's runtime
+   * without the caller re-threading storage/network/profile/key/sApp config.
+   */
+  private launchConfigs: Map<string, StartStrandConfig> = new Map();
   private stopping = false;
 
   constructor() {
@@ -148,8 +178,9 @@ export class StrandInstanceManager {
     log('Starting strand instance: %s (sApp: %s v%s)', strandId, sAppConfig.id, sAppConfig.version);
     const tTotal = performance.now();
 
-    // Verify schema signature before proceeding
-    assertSchemaSignature(sAppConfig);
+    // Verify schema signature before proceeding (fail-closed by default)
+    const requireSignature = config.requireSignedSchemas ?? true;
+    assertSchemaSignature(sAppConfig, { requireSignature });
     log('Strand %s sApp schema signature verified (author: %s)', strandId, sAppConfig.id);
 
     // Convert SAppConfig to SAppInfo for the instance
@@ -174,29 +205,54 @@ export class StrandInstanceManager {
     };
 
     this.instances.set(strandId, instance);
+    this.launchConfigs.set(strandId, config);
 
     try {
-      // Resolve storage for this strand
-      // If a factory function is provided, it will be called with the strandId
-      // to create strand-specific storage (e.g., strand-isolated directories)
-      const strandStorage = resolveStrandStorage(config.storage?.provider, strandId);
-      if (strandStorage) {
-        log('Strand %s using provided storage provider', strandId);
-      }
-
-      // Create isolated libp2p node for this strand
-      // Note: protocolPrefix would be used by libp2p services, but createLibp2pNode
-      // may not support it yet - tracked for future implementation
-      const _protocolPrefix = `/sereus/strand/${strandId}`;
-
-      // Determine relay mode: if explicitly set in config, use that;
-      // otherwise default to true for storage profile nodes
-      const enableRelay = config.network?.enableRelay ?? (config.profile === 'storage');
+      await this.buildStrandRuntime(instance, config);
+      timing('[startStrand:%s] total: %dms', strandId, Math.round(performance.now() - tTotal));
+      log('Strand %s started successfully with sApp %s', strandId, sAppConfig.id);
+      return instance;
+    } catch (error) {
+      instance.status = 'error';
+      instance.error = error instanceof Error ? error.message : String(error);
+      log('Failed to start strand %s: %s', strandId, instance.error);
+      throw error;
+    }
+  }
 
+  /**
+   * Build (or rebuild) the libp2p node + StrandDatabase for an instance and
+   * attach them, transitioning it to `active`. Shared by `startStrand` (fresh
+   * launch) and `resumeStrand` (rehydrating a quiesced instance). Reads all
+   * volatile inputs (bootstrapNodes, mode, storage, network, profile,
+   * privateKey, sApp config) from `config`, so the caller controls the
+   * cohort-derived values.
+   */
+  private async buildStrandRuntime(instance: StrandInstance, config: StartStrandConfig): Promise<void> {
+    const strandId = instance.strandId;
+    const { sAppConfig } = config;
+
+    // Resolve storage for this strand. If a factory function is provided, it is
+    // called with the strandId to create strand-specific storage (e.g.,
+    // strand-isolated directories).
+    const strandStorage = resolveStrandStorage(config.storage?.provider, strandId);
+    if (strandStorage) {
+      log('Strand %s using provided storage provider', strandId);
+    }
+
+    // Note: protocolPrefix would be used by libp2p services, but createLibp2pNode
+    // may not support it yet - tracked for future implementation.
+    const _protocolPrefix = `/sereus/strand/${strandId}`;
+
+    // Determine relay mode: if explicitly set in config, use that;
+    // otherwise default to true for storage profile nodes.
+    const enableRelay = config.network?.enableRelay ?? (config.profile === 'storage');
+
+    try {
       let t0 = performance.now();
       const node = await createLibp2pNode({
         port: 0, // Random port
-        bootstrapNodes: [], // Will be populated from strand cohort
+        bootstrapNodes: config.bootstrapNodes ?? [],
         networkName: `strand-${strandId}`,
         storage: strandStorage,
         fretProfile: config.profile === 'storage' ? 'core' : 'edge',
@@ -211,9 +267,10 @@ export class StrandInstanceManager {
         },
         ...(config.privateKey && { privateKey: config.privateKey }),
         ...(config.network?.transports && { transports: config.network.transports }),
-        ...(config.network?.listenAddrs && { listenAddrs: config.network.listenAddrs })
+        ...(config.network?.listenAddrs && { listenAddrs: config.network.listenAddrs }),
+        ...(config.network?.connectionGater && { connectionGater: config.network.connectionGater })
       }) as Libp2pNodeWithRepo;
-      timing('[startStrand:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
+      timing('[buildStrandRuntime:%s] createLibp2pNode: %dms', strandId, Math.round(performance.now() - t0));
 
       instance.libp2pNode = node;
 
@@ -222,6 +279,9 @@ export class StrandInstanceManager {
       // DML lands on the host's persistent storage (e.g. MMKV on RN). Sharing
       // the instance — not creating a second one over the same id+prefix —
       // avoids cache divergence between the libp2p and database paths.
+      //
+      // Attach before initialize so a failed init is cleaned up by
+      // releaseRuntime below (close() is safe on a partially-initialized db).
       t0 = performance.now();
       const strandDb = new StrandDatabase({
         strandId,
@@ -229,23 +289,121 @@ export class StrandInstanceManager {
         libp2pNode: node,
         coordinatedRepo: node.coordinatedRepo,
         mode: config.mode ?? 'networked',
-        rawStorage: strandStorage
+        rawStorage: strandStorage,
+        // Founder bootstrap inputs: the strand's type drives which membership rows
+        // are written, and the closed-strand MemberPrivateKey derives the founding
+        // Member/Manager key. Both come off the control-network strand row.
+        strandType: config.strandRow.Type,
+        memberPrivateKey: config.strandRow.MemberPrivateKey ?? undefined,
+        founder: config.founder
       });
-      await strandDb.initialize();
-      timing('[startStrand:%s] strandDatabase.initialize: %dms', strandId, Math.round(performance.now() - t0));
       instance.database = strandDb;
+      await strandDb.initialize();
+      timing('[buildStrandRuntime:%s] strandDatabase.initialize: %dms', strandId, Math.round(performance.now() - t0));
 
       instance.status = 'active';
       instance.lastActivity = new Date();
+    } catch (error) {
+      // Roll back any partially-attached runtime so the instance is left with
+      // NEITHER handle. Otherwise the `libp2pNode || database` "already live"
+      // guard in resumeStrand/handleStrandWake would treat a half-built strand
+      // as healthy — leaking the libp2p node and never retrying the rebuild.
+      await this.releaseRuntime(instance).catch((cleanupErr) => {
+        log('buildStrandRuntime cleanup for strand %s also failed: %o', strandId, cleanupErr);
+      });
+      throw error;
+    }
+  }
 
-      timing('[startStrand:%s] total: %dms', strandId, Math.round(performance.now() - tTotal));
-      log('Strand %s started successfully with sApp %s', strandId, sAppConfig.id);
+  /**
+   * Release an instance's strand-network runtime: close the StrandDatabase, then
+   * stop the libp2p node (construction order in reverse), clearing both fields
+   * and zeroing connectedPeers. Tolerant of partially-built state — either handle
+   * may be absent — so it doubles as rollback for a failed `buildStrandRuntime`.
+   * Shared by `quiesceStrand`, `stopStrand`, and that rollback path.
+   */
+  private async releaseRuntime(instance: StrandInstance): Promise<void> {
+    if (instance.database) {
+      await instance.database.close();
+      instance.database = undefined;
+    }
+    if (instance.libp2pNode) {
+      await instance.libp2pNode.stop();
+      instance.libp2pNode = undefined;
+    }
+    instance.connectedPeers = 0;
+  }
+
+  /**
+   * Quiesce a strand: release its strand-network resources (stop the libp2p node,
+   * close the StrandDatabase) while RETAINING the instance record — identity,
+   * sAppInfo, keys, latency hint, metadata — and its launch config so it can be
+   * resumed later. Mechanically this is `stopStrand` minus the instance/config
+   * deletion. The caller sets the post-quiesce status (e.g. `hibernating`).
+   * No-ops when the strand is missing or already quiesced.
+   */
+  async quiesceStrand(strandId: string): Promise<void> {
+    const instance = this.instances.get(strandId);
+    if (!instance) {
+      log('quiesceStrand: strand %s not found', strandId);
+      return;
+    }
+    if (!instance.libp2pNode && !instance.database) {
+      log('quiesceStrand: strand %s already quiesced', strandId);
+      return;
+    }
+
+    log('Quiescing strand instance: %s', strandId);
+    await this.releaseRuntime(instance);
+    log('Strand %s quiesced (resources released, instance retained)', strandId);
+  }
+
+  /**
+   * Resume a previously-quiesced strand: rebuild its libp2p node + StrandDatabase
+   * from the retained launch config and re-attach them, transitioning it back to
+   * `active`. `overrides` re-applies volatile inputs that may have changed since
+   * launch (cohort `bootstrapNodes`, lifecycle `mode`) and updates the retained
+   * config so a later resume reuses the latest values. Returns the live instance
+   * unchanged if it is already running.
+   */
+  async resumeStrand(strandId: string, overrides?: ResumeStrandOverrides): Promise<StrandInstance> {
+    if (this.stopping) {
+      throw new Error('StrandInstanceManager is stopping');
+    }
+    const instance = this.instances.get(strandId);
+    if (!instance) {
+      throw new Error(`Cannot resume strand ${strandId}: not tracked`);
+    }
+    const launchConfig = this.launchConfigs.get(strandId);
+    if (!launchConfig) {
+      throw new Error(`Cannot resume strand ${strandId}: no retained launch config`);
+    }
+    if (instance.libp2pNode || instance.database) {
+      log('resumeStrand: strand %s already live', strandId);
       return instance;
+    }
 
+    log('Resuming strand instance: %s', strandId);
+    const tTotal = performance.now();
+
+    // Re-apply volatile inputs and persist them so a subsequent resume reuses them.
+    const resumeConfig: StartStrandConfig = {
+      ...launchConfig,
+      bootstrapNodes: overrides?.bootstrapNodes ?? launchConfig.bootstrapNodes,
+      mode: overrides?.mode ?? launchConfig.mode
+    };
+    this.launchConfigs.set(strandId, resumeConfig);
+
+    instance.status = 'starting';
+    try {
+      await this.buildStrandRuntime(instance, resumeConfig);
+      timing('[resumeStrand:%s] total: %dms', strandId, Math.round(performance.now() - tTotal));
+      log('Strand %s resumed successfully', strandId);
+      return instance;
     } catch (error) {
       instance.status = 'error';
       instance.error = error instanceof Error ? error.message : String(error);
-      log('Failed to start strand %s: %s', strandId, instance.error);
+      log('Failed to resume strand %s: %s', strandId, instance.error);
       throw error;
     }
   }
@@ -264,17 +422,10 @@ export class StrandInstanceManager {
     instance.status = 'stopping';
 
     try {
-      // Close the database before stopping libp2p
-      if (instance.database) {
-        await instance.database.close();
-        instance.database = undefined;
-      }
-      if (instance.libp2pNode) {
-        await instance.libp2pNode.stop();
-        instance.libp2pNode = undefined;
-      }
+      await this.releaseRuntime(instance);
       instance.status = 'stopped';
       this.instances.delete(strandId);
+      this.launchConfigs.delete(strandId);
       log('Strand %s stopped successfully', strandId);
     } catch (error) {
       instance.status = 'error';

package/src/strand-member-key.ts

@@ -0,0 +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);
+}

package/src/strand-member-registry.ts

@@ -0,0 +1,177 @@
+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,
+} from './strand-membership-writer.js';
+import { canonicalDatetime } from './canonical-datetime.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.
+   *
+   * Expired invites are filtered out so this pre-flight matches the on-engine
+   * `ConsumedInvite.NotExpired` gate — `Now` is canonicalised the same way the
+   * writer canonicalises it, so `Expiration > ?` compares like-for-like canonical
+   * strings. A member that already holds a `ConsumedInvite` short-circuits above,
+   * regardless of any invite's expiry.
+   */
+  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) {
+      return true;
+    }
+    const nowCanonical = await canonicalDatetime(this.db, Date.now());
+    const invites = await scalarCount(
+      this.db,
+      'select count(1) as c from Strand.Invite where Expiration is null or Expiration > ?',
+      [nowCanonical],
+    );
+    return invites > 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;
+}