@serfab/cadre-core 1.16.0 → 1.18.0

package/src/ed25519-key.ts

@@ -1,171 +1,174 @@
-import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
-import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
-import { peerIdFromPublicKey, peerIdFromString } from '@libp2p/peer-id';
-import { publicKeyFromRaw } from '@libp2p/crypto/keys';
-import type { PrivateKey } from '@libp2p/interface';
-
-/**
- * An Ed25519 keypair expressed in the base64url form that
- * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
- * Generic bridge type — reused for owner keys, member keys, and any other
- * seed→public keypair the control/strand databases sign with.
- */
-export interface Ed25519KeyPair {
-  /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
-  privateKeyB64: string;
-  /** 32-byte Ed25519 public key, base64url-encoded. */
-  publicKeyB64: string;
-}
-
-/**
- * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
- * control- and strand-database signing constraints.
- *
- * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
- * seed (the actual scalar source), the last 32 are the public key — see
- * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
- * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
- * derives the public key from it with standard Ed25519. The two derivations
- * agree, so the node's peer identity and its signing key are one keypair:
- * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
- *
- * @param privateKey - The node's libp2p Ed25519 private key.
- * @returns The base64url seed/public-key pair for signing operations.
- * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
- */
-export function ed25519KeyPairFromLibp2p(privateKey: PrivateKey): Ed25519KeyPair {
-  if (privateKey.type !== 'Ed25519') {
-    throw new Error(`ed25519KeyPairFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
-  }
-
-  const raw = privateKey.raw;
-  if (raw.length !== 64) {
-    throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
-  }
-
-  const seed = raw.subarray(0, 32);
-  const publicKeyRaw = privateKey.publicKey.raw;
-  if (publicKeyRaw.length !== 32) {
-    throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
-  }
-
-  return {
-    privateKeyB64: uint8ArrayToString(seed, 'base64url'),
-    publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
-  };
-}
-
-/**
- * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
- * — the same derivation the seed-bootstrap signer uses internally
- * (`SeedBootstrapService` constructor). Use this to enroll a standalone
- * (non-libp2p) key into the control DB before minting an invite, when the
- * key is *not* the node's peer identity (so `ed25519KeyPairFromLibp2p`,
- * which needs a libp2p key object, does not apply).
- *
- * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
- * @returns The base64url-encoded Ed25519 public key.
- */
-export function ed25519PublicKeyFromPrivate(privateKeyB64: string): string {
-  return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url') as string;
-}
-
-/**
- * Derive the base64url ed25519 public key embedded in an Ed25519 libp2p PeerId.
- *
- * An Ed25519 PeerId is an identity multihash of the public key, so
- * `peerIdFromString(id).publicKey.raw` is the 32-byte ed25519 key whose
- * base64url form matches the `OwnerKey.Key` representation (and
- * `ed25519KeyPairFromLibp2p().publicKeyB64`). Returns null for a non-Ed25519
- * id, a missing embedded key, or any parse failure — callers treat null as
- * "not an owner" rather than throwing.
- *
- * Lives here, beside the other key bridges, so the lightweight verifiers in
- * `peer-authorization.ts` can check a stored `PeerKey` against a row's `PeerId`
- * without importing the seed-bootstrap runtime.
- */
-export function ed25519PublicKeyB64FromPeerId(peerId: string): string | null {
-  try {
-    const parsed = peerIdFromString(peerId);
-    if (parsed.type !== 'Ed25519' || !parsed.publicKey) {
-      return null;
-    }
-    return uint8ArrayToString(parsed.publicKey.raw, 'base64url');
-  } catch {
-    return null;
-  }
-}
-
-/**
- * The inverse of {@link ed25519PublicKeyB64FromPeerId}: the libp2p peer id whose identity
- * is this ed25519 public key (base64url), or null when the value does not decode to a
- * 32-byte key. How an `OwnerKey` row is matched to the machine it names
- * (`machine-removal.ts`), since a machine's owner key is the key behind its peer id.
- */
-export function peerIdFromEd25519PublicKeyB64(publicKeyB64: string): string | null {
-  try {
-    const raw = uint8ArrayFromString(publicKeyB64, 'base64url');
-    if (raw.length !== 32) {
-      return null;
-    }
-    return peerIdFromPublicKey(publicKeyFromRaw(raw)).toString();
-  } catch {
-    return null;
-  }
-}
-
-/** Longest rejected key value echoed back in an error — a real key is 43 base64url chars. */
-const REJECTED_VALUE_ECHO_LIMIT = 64;
-
-/**
- * Render a rejected value for an error message, capped: owner keys now reach this check
- * from remote-supplied fields (a cadre invitation's `ownerKeys`, a donation request's
- * `ownerKeys`), so an unbounded echo would let a peer turn one junk string into a
- * megabyte of log line.
- */
-function describeRejected(value: string): string {
-  return value.length <= REJECTED_VALUE_ECHO_LIMIT
-    ? value
-    : `${value.slice(0, REJECTED_VALUE_ECHO_LIMIT)}… (${value.length} chars)`;
-}
-
-/**
- * Reject a value that isn't shaped like a base64url-encoded 32-byte Ed25519 public key
- * before it reaches the control database, where a malformed key would otherwise sit
- * indistinguishable from a real one until some later, unrelated signature check fails.
- *
- * Trims first, reusing the blank-value message for an empty result so that case keeps its
- * existing wording instead of a confusing base64url error. Every rejection names the offending
- * value (capped, see {@link describeRejected}) — with several keys in one batch, the message is
- * the only thing that says WHICH one. Does not check the decoded bytes
- * are a valid point on the Ed25519 curve — a well-formed-but-off-curve key still fails
- * signature verification later exactly like any other wrong key.
- *
- * @param value - Candidate base64url-encoded Ed25519 public key.
- * @param label - Human-readable name of the field, used in error messages.
- * @returns The trimmed value, so callers write the same bytes they validated.
- */
-export function requireEd25519PublicKeyB64(value: string, label: string): string {
-  const trimmed = value.trim();
-  if (trimmed.length === 0) {
-    throw new Error(`A ${label} is required (received an empty or whitespace-only value)`);
-  }
-
-  let decoded: Uint8Array;
-  try {
-    decoded = uint8ArrayFromString(trimmed, 'base64url');
-  } catch (error) {
-    throw new Error(
-      `A ${label} must be a base64url-encoded Ed25519 public key (could not decode "${describeRejected(trimmed)}" as base64url)`,
-      { cause: error },
-    );
-  }
-
-  if (decoded.length !== 32) {
-    throw new Error(
-      `A ${label} must be a base64url-encoded 32-byte Ed25519 public key ("${describeRejected(trimmed)}" decoded to ${decoded.length} bytes)`,
-    );
-  }
-
-  return trimmed;
-}
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
+import { peerIdFromString } from '@libp2p/peer-id';
+import type { PrivateKey } from '@libp2p/interface';
+
+/**
+ * An Ed25519 keypair expressed in the base64url form that
+ * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
+ * Generic bridge type — reused for owner keys, member keys, and any other
+ * seed→public keypair the control/strand databases sign with.
+ */
+export interface Ed25519KeyPair {
+  /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
+  privateKeyB64: string;
+  /** 32-byte Ed25519 public key, base64url-encoded. */
+  publicKeyB64: string;
+}
+
+/**
+ * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
+ * control- and strand-database signing constraints.
+ *
+ * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
+ * seed (the actual scalar source), the last 32 are the public key — see
+ * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
+ * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
+ * derives the public key from it with standard Ed25519. The two derivations
+ * agree, so the node's peer identity and its signing key are one keypair:
+ * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns The base64url seed/public-key pair for signing operations.
+ * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
+ */
+export function ed25519KeyPairFromLibp2p(privateKey: PrivateKey): Ed25519KeyPair {
+  if (privateKey.type !== 'Ed25519') {
+    throw new Error(`ed25519KeyPairFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
+  }
+
+  const raw = privateKey.raw;
+  if (raw.length !== 64) {
+    throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
+  }
+
+  const seed = raw.subarray(0, 32);
+  const publicKeyRaw = privateKey.publicKey.raw;
+  if (publicKeyRaw.length !== 32) {
+    throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
+  }
+
+  return {
+    privateKeyB64: uint8ArrayToString(seed, 'base64url'),
+    publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
+  };
+}
+
+/**
+ * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
+ * — the same derivation the seed-bootstrap signer uses internally
+ * (`SeedBootstrapService` constructor). Use this to enroll a standalone
+ * (non-libp2p) key into the control DB before minting an invite, when the
+ * key is *not* the node's peer identity (so `ed25519KeyPairFromLibp2p`,
+ * which needs a libp2p key object, does not apply).
+ *
+ * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
+ * @returns The base64url-encoded Ed25519 public key.
+ */
+export function ed25519PublicKeyFromPrivate(privateKeyB64: string): string {
+  return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url') as string;
+}
+
+/**
+ * Reject a value that isn't a base64url-encoded 32-byte Ed25519 seed, the private-key form
+ * {@link ed25519PublicKeyFromPrivate} and the crypto plugin's `sign` take. Unlike
+ * {@link requireEd25519PublicKeyB64}, no message names the value: it is a private key.
+ *
+ * @param value - Candidate base64url-encoded Ed25519 seed; surrounding whitespace is ignored.
+ * @param label - Human-readable name of the field, used in error messages.
+ * @returns The seed re-encoded as canonical base64url, so two spellings of one key compare equal.
+ */
+export function requireEd25519PrivateKeyB64(value: string, label: string): string {
+  let decoded: Uint8Array;
+  try {
+    decoded = uint8ArrayFromString(value.trim(), 'base64url');
+  } catch (error) {
+    throw new Error(`The ${label} must be a base64url-encoded Ed25519 private key (it does not decode as base64url)`, { cause: error });
+  }
+  if (decoded.length !== 32) {
+    throw new Error(`The ${label} must be a base64url-encoded 32-byte Ed25519 private key (it decoded to ${decoded.length} bytes)`);
+  }
+  return uint8ArrayToString(decoded, 'base64url');
+}
+
+/**
+ * Derive the base64url ed25519 public key embedded in an Ed25519 libp2p PeerId.
+ *
+ * An Ed25519 PeerId is an identity multihash of the public key, so
+ * `peerIdFromString(id).publicKey.raw` is the 32-byte ed25519 key whose
+ * base64url form matches the `OwnerKey.Key` representation (and
+ * `ed25519KeyPairFromLibp2p().publicKeyB64`). Returns null for a non-Ed25519
+ * id, a missing embedded key, or any parse failure — callers treat null as
+ * "not an owner" rather than throwing.
+ *
+ * Lives here, beside the other key bridges, so the lightweight verifiers in
+ * `peer-authorization.ts` can check a stored `PeerKey` against a row's `PeerId`
+ * without importing the seed-bootstrap runtime.
+ */
+export function ed25519PublicKeyB64FromPeerId(peerId: string): string | null {
+  try {
+    const parsed = peerIdFromString(peerId);
+    if (parsed.type !== 'Ed25519' || !parsed.publicKey) {
+      return null;
+    }
+    return uint8ArrayToString(parsed.publicKey.raw, 'base64url');
+  } catch {
+    return null;
+  }
+}
+
+/** Longest rejected key value echoed back in an error — a real key is 43 base64url chars. */
+const REJECTED_VALUE_ECHO_LIMIT = 64;
+
+/**
+ * Render a rejected value for an error message, capped: owner keys now reach this check
+ * from remote-supplied fields (a cadre invitation's `ownerKeys`, a donation request's
+ * `ownerKeys`), so an unbounded echo would let a peer turn one junk string into a
+ * megabyte of log line.
+ */
+function describeRejected(value: string): string {
+  return value.length <= REJECTED_VALUE_ECHO_LIMIT
+    ? value
+    : `${value.slice(0, REJECTED_VALUE_ECHO_LIMIT)}… (${value.length} chars)`;
+}
+
+/**
+ * Reject a value that isn't shaped like a base64url-encoded 32-byte Ed25519 public key
+ * before it reaches the control database, where a malformed key would otherwise sit
+ * indistinguishable from a real one until some later, unrelated signature check fails.
+ *
+ * Trims first, reusing the blank-value message for an empty result so that case keeps its
+ * existing wording instead of a confusing base64url error. Every rejection names the offending
+ * value (capped, see {@link describeRejected}) — with several keys in one batch, the message is
+ * the only thing that says WHICH one. Does not check the decoded bytes
+ * are a valid point on the Ed25519 curve — a well-formed-but-off-curve key still fails
+ * signature verification later exactly like any other wrong key.
+ *
+ * @param value - Candidate base64url-encoded Ed25519 public key.
+ * @param label - Human-readable name of the field, used in error messages.
+ * @returns The trimmed value, so callers write the same bytes they validated.
+ */
+export function requireEd25519PublicKeyB64(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`A ${label} is required (received an empty or whitespace-only value)`);
+  }
+
+  let decoded: Uint8Array;
+  try {
+    decoded = uint8ArrayFromString(trimmed, 'base64url');
+  } catch (error) {
+    throw new Error(
+      `A ${label} must be a base64url-encoded Ed25519 public key (could not decode "${describeRejected(trimmed)}" as base64url)`,
+      { cause: error },
+    );
+  }
+
+  if (decoded.length !== 32) {
+    throw new Error(
+      `A ${label} must be a base64url-encoded 32-byte Ed25519 public key ("${describeRejected(trimmed)}" decoded to ${decoded.length} bytes)`,
+    );
+  }
+
+  return trimmed;
+}

package/src/edge-node/config.ts

@@ -0,0 +1,277 @@
+/**
+ * The edge node's `CadreNodeConfig` and how a start settles its owner key. Nothing here needs a
+ * node started, so a test can build the node shape an edge device runs.
+ */
+
+import { DEFAULT_IDENTITY_KEY_ID, type KeyStore } from '../key-store.js';
+import { createOwnerKey, loadOwnerSigner } from '../owner-key-store.js';
+import { OWNER_KEY_MAX_LABEL } from '../owner-key-export.js';
+import type { OwnerSigner } from '../owner-signer.js';
+import type { CadreNode } from '../cadre-node.js';
+import type { CadreNodeConfig } from '../types.js';
+import type { BootstrapPeerStore } from '../bootstrap-peer-store.js';
+import type { EnrolledMachineStore } from '../enrolled-machine-store.js';
+import type { StrandNetworkStateStore } from '../strand-network-state.js';
+import type { TrustedOwnerStore } from '../trusted-owner-store.js';
+import type { IRawStorage, Libp2pTransports, NoiseCryptoInterface } from '@optimystic/db-p2p';
+import type { EdgeNodeOptions } from './options.js';
+
+/** What {@link buildEdgeNodeConfig} takes: one start's options plus what the platform built. */
+export interface EdgeNodeConfigInputs extends EdgeNodeOptions {
+	/** `undefined` keeps libp2p-noise's own crypto. */
+	noiseCrypto?: NoiseCryptoInterface;
+	/**
+	 * Holds the node identity, which the node loads on start, generating it on first run, and the
+	 * owner key in its own slot (`DEFAULT_OWNER_KEY_ID`), which only {@link runOwnerGenesis} creates.
+	 */
+	keyStore: KeyStore;
+	/**
+	 * Raw block storage per cadre-core storage scope: `controlStorageScope(partyId)` for the
+	 * control network, the strand id for each strand. The key is already safe as a database-name
+	 * segment — use it verbatim, do not parse it.
+	 */
+	storageProvider: (scope: string) => IRawStorage;
+	/** libp2p transport factories: what the node dials with, and what listens on `listenAddrs`. */
+	transports: Libp2pTransports;
+	/**
+	 * Listen addresses besides the bare `/p2p-circuit` entry cadre-core adds for a named relay.
+	 * Default `[]`: an edge device accepts no inbound connection. See `EdgeNodePlatform.listenAddrs`.
+	 */
+	listenAddrs?: string[];
+	/** See `EdgeNodePlatform.allowPrivateDial`. */
+	allowPrivateDial: boolean;
+	trustedOwnerStore: TrustedOwnerStore;
+	bootstrapPeerStore: BootstrapPeerStore;
+	enrolledMachineStore: EnrolledMachineStore;
+	strandNetworkStateStore: StrandNetworkStateStore;
+}
+
+/**
+ * The edge node's config: transaction profile (Ring Zulu only, intermittent connectivity), no
+ * listen address unless the platform names one, reachability through the configured relays (if
+ * any) but never a hard requirement for one, every strand the control network lists, and no
+ * automatic hibernation (the app's lifecycle runner hibernates on background). Schema signing is
+ * left at cadre-core's fail-closed default; an app with unsigned schemas relaxes it in
+ * `EdgeNodePlatform.configure`.
+ */
+export function buildEdgeNodeConfig(inputs: EdgeNodeConfigInputs): CadreNodeConfig {
+	return {
+		// Identity comes from the key store (loaded when present, generated and persisted on first
+		// run). Mutually exclusive with `privateKey`, which would take it out of the key store.
+		keyStore: inputs.keyStore,
+		identityKeyId: DEFAULT_IDENTITY_KEY_ID,
+		controlNetwork: {
+			partyId: inputs.partyId,
+			bootstrapNodes: inputs.bootstrapAddrs,
+		},
+		profile: 'transaction',
+		storage: {
+			provider: inputs.storageProvider,
+		},
+		network: {
+			transports: inputs.transports,
+			// An edge device accepts no inbound connection, so by default it listens on nothing:
+			// the only address it ever has is the `/p2p-circuit` address a relay reservation earns
+			// it. An explicitly empty `listenAddrs` stays empty through cadre-core's derivation, and
+			// naming a relay adds the bare `/p2p-circuit` search entry to it
+			// (`cadre-core/src/relay-addrs.ts` → `resolveListenAddrs`). A browser adds `/webrtc`.
+			listenAddrs: inputs.listenAddrs ?? [],
+			// Through this config field rather than `CadreNode.reserveRelays()`, which reaches the
+			// control node only: formation has the invitee dial the control node and then the strand
+			// nodes, so both need a circuit address.
+			//
+			// NOTE: naming a relay starts a reservation supervisor that runs for as long as the
+			// control node does, including while backgrounded (hibernation stops strands, not the
+			// control node): a 5 s local check while the reservation holds, a dial every backoff
+			// interval (2 s → 60 s) while it does not. If background battery use becomes a complaint,
+			// raise `checkMs`/`maxBackoffMs` in cadre-core rather than stopping the supervisor here,
+			// which would leave a device that silently stopped being invitable.
+			relayAddrs: inputs.relayAddrs,
+			// An edge device must come up with its relay down — on a plane, on dead Wi-Fi, or with
+			// none configured. A first reservation attempt that lands nothing is logged and retried in
+			// the background instead of failing `start()`. A malformed entry still throws.
+			requireRelay: false,
+			// The platform's Noise primitives (native SHA-256 / ChaCha20-Poly1305, and X25519 in
+			// `full` mode, on a phone); only local primitives change, not the wire protocol.
+			noiseCrypto: inputs.noiseCrypto,
+			// libp2p's `connection-gater` points its `react-native` and `browser` fields at a build
+			// that refuses to dial plain `ws://`, loopback and private addresses. A cadre-host node
+			// claimed by its code on the same Wi-Fi, an emulator reaching `10.0.2.2` and a self-run
+			// relay without TLS are all of those. Only the dial is permitted: the connection is still
+			// Noise, the pinned `/p2p/<id>` decides which machine answers, and membership is still
+			// gated by `denyDialPeer` and the inbound hooks. cadre-core hands this gater to strand nodes too.
+			...(inputs.allowPrivateDial ? { connectionGater: { denyDialMultiaddr: () => false } } : {}),
+		},
+		strandFilter: { mode: 'all' },
+		hibernation: { enabled: false },
+		trustedOwners: { store: inputs.trustedOwnerStore },
+		bootstrapPeers: { store: inputs.bootstrapPeerStore },
+		enrolledMachines: { store: inputs.enrolledMachineStore },
+		strandNetworkState: { store: inputs.strandNetworkStateStore },
+	};
+}
+
+/**
+ * How the start settled this node's owner key: `EdgeNodeStatus.owner`. `'enrolled'`: a key is
+ * an owner and wired for signing. `'member'`: the party lists no key this app holds (a party it
+ * joined, or one it founded whose owner slot was lost). `'failed'` and `'timed-out'`: see
+ * {@link runOwnerGenesis}.
+ */
+export type OwnerGenesisResult = 'enrolled' | 'member' | 'failed' | 'timed-out';
+
+/**
+ * Default bound on {@link runOwnerGenesis} and {@link wireJoinedOwnerKey}: what a start can wait
+ * for its owner step, which runs control reads and one control write, before it goes on without
+ * it. Not derived from the link, since a start that waited out a stalled write (about 84 s, see
+ * `docs/cadre-consistency.md`) would be a start the user gave up on.
+ */
+// eslint-disable-next-line no-restricted-syntax -- cuts off by design: a start goes on without its owner step rather than wait out a stalled control write; see docs/cadre-consistency.md → "Deadlines Over Optimystic's Reads and Commits"
+export const DEFAULT_OWNER_GENESIS_TIMEOUT_MS = 60_000;
+
+/** Default `EdgeNodeOptions.ownerKeyLabel`: the founding owner key's name on its `OwnerKey` row. */
+export const DEFAULT_OWNER_KEY_LABEL = 'phone';
+
+/**
+ * Refuses an `ownerKeyLabel` the founding `OwnerKey` row would refuse, so a start naming one
+ * fails outright: fail-soft genesis would only log it, on that start and every later one.
+ */
+export function requireOwnerKeyLabel(label: string | undefined): void {
+	const length = label?.trim().length ?? 0;
+	if (length > OWNER_KEY_MAX_LABEL) {
+		throw new Error(`ownerKeyLabel must be at most ${OWNER_KEY_MAX_LABEL} characters (this one has ${length})`);
+	}
+}
+
+/** What {@link runOwnerGenesis} takes. */
+export interface OwnerGenesisOptions {
+	/** The key store whose owner slot holds this app's owner key: the one the identity is in. */
+	keyStore: KeyStore;
+	/** The founding row's label; default {@link DEFAULT_OWNER_KEY_LABEL}. */
+	label?: string;
+	/** Default {@link DEFAULT_OWNER_GENESIS_TIMEOUT_MS}. */
+	timeoutMs?: number;
+}
+
+/** What {@link wireJoinedOwnerKey} takes. */
+export interface JoinedOwnerKeyOptions {
+	/** The key store whose owner slot holds this app's owner key, if it holds one. */
+	keyStore: KeyStore;
+	/** Default {@link DEFAULT_OWNER_GENESIS_TIMEOUT_MS}. */
+	timeoutMs?: number;
+	/** An owner grant has just seated the slot's key: keep asking until the row arrives. */
+	granted?: boolean;
+}
+
+/** How often {@link wireJoinedOwnerKey} asks again for an owner key an owner grant just seated. */
+const GRANTED_OWNER_RECHECK_MS = 2_000;
+
+/**
+ * The owner step of a party this app founded. On a party with no `OwnerKey` row yet, the owner
+ * slot's key (created there now unless the slot already holds one) becomes the founding owner
+ * under `label` and is wired for signing, which also lets the node author its own `CadrePeer` row.
+ * On a party that has owners, the slot's key is wired only when it is a live owner, and no key is
+ * created: a new one could not be seated without another owner's signature. A node must be an
+ * enrolled owner to publish strands, and `CadreNode.requestJoin` works only on one. A joined
+ * party's start runs {@link wireJoinedOwnerKey} instead.
+ *
+ * Fail-soft and bounded: a failure or a genesis that has not settled within `timeoutMs` is logged
+ * and returned, and the start stands — the app can still join discovered strands and sync. A
+ * genesis that times out keeps running; its later failure is logged.
+ *
+ * NOTE: the bound is here, in cadre-core, so every edge node gets it; a Node host runs genesis
+ * through the CLI's own flow instead. Since v1.10 a control write against an unresponsive member
+ * can hold the write lock for about 84 s, so an unbounded wait here would be a real stall. A bound
+ * on that write itself, in `ControlDatabase`, would make this one redundant; drop `timeoutMs` then.
+ */
+export function runOwnerGenesis(node: CadreNode, options: OwnerGenesisOptions): Promise<OwnerGenesisResult> {
+	const label = options.label ?? DEFAULT_OWNER_KEY_LABEL;
+	return withinBound('owner self-genesis', enrollFoundedOwner(node, options.keyStore, label), options.timeoutMs ?? DEFAULT_OWNER_GENESIS_TIMEOUT_MS);
+}
+
+/**
+ * The owner step of a party this app joined: wire a key only when the party lists it as a live
+ * owner, never insert an `OwnerKey` row, so a joined app can neither seat itself as a founder nor
+ * anchor a key that is no owner's. Only the owner slot's key is tried: the key an owner grant
+ * seated, one imported here, or one an owner of the party added. The identity key is never
+ * tried, since a machine's network identity is never an owner key. Fail-soft and bounded as
+ * {@link runOwnerGenesis} is.
+ *
+ * `granted`: an owner grant has just made this app an owner, so a key not listed yet means the
+ * row has not reached this node, not that it is no owner. It is asked again every 2 s until it
+ * is wired or the bound passes; a start that timed out wires it on the next start.
+ */
+export function wireJoinedOwnerKey(node: CadreNode, options: JoinedOwnerKeyOptions): Promise<OwnerGenesisResult> {
+	let expired = false;
+	const wiring = async (): Promise<OwnerGenesisResult> => {
+		const held = await loadOwnerSigner(options.keyStore);
+		while (!(await wireJoinedOwner(node, held))) {
+			if (!options.granted) return 'member';
+			await new Promise((resolve) => setTimeout(resolve, GRANTED_OWNER_RECHECK_MS));
+			// Past the bound the start has gone on as `'timed-out'`, and may have stopped the node.
+			if (expired) return 'member';
+		}
+		return 'enrolled';
+	};
+	return withinBound('wiring the joined owner key', wiring(), options.timeoutMs ?? DEFAULT_OWNER_GENESIS_TIMEOUT_MS)
+		.finally(() => {
+			expired = true;
+		});
+}
+
+/** `settling`, or `'failed'` when it rejects (logged), or `'timed-out'` when it has not settled within `timeoutMs` (logged). */
+async function withinBound(
+	label: string,
+	settling: Promise<OwnerGenesisResult>,
+	timeoutMs: number,
+): Promise<OwnerGenesisResult> {
+	const settled = settling.catch((err: unknown): OwnerGenesisResult => {
+		console.warn(`[cadre-core/edge-node] ${label} failed:`, err);
+		return 'failed';
+	});
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<OwnerGenesisResult>((resolve) => {
+		timer = setTimeout(() => resolve('timed-out'), timeoutMs);
+	});
+	try {
+		const result = await Promise.race([settled, deadline]);
+		if (result === 'timed-out') {
+			console.warn(`[cadre-core/edge-node] ${label} has not settled after ${timeoutMs} ms; starting without it`);
+		}
+		return result;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function enrollFoundedOwner(node: CadreNode, keyStore: KeyStore, label: string): Promise<OwnerGenesisResult> {
+	const controlDb = node.getControlDatabase();
+	if (!controlDb) {
+		throw new Error('control database unavailable after start; cannot run owner genesis');
+	}
+	const held = await loadOwnerSigner(keyStore);
+	if (await controlDb.hasOwnerKey()) {
+		return held ? wiredIfOwner(node, held) : 'member';
+	}
+	// Loaded rather than created when the slot already holds a key: one imported before founding,
+	// or one an iOS reinstall kept in the Keychain while the app's data went.
+	const founding = held ?? (await createOwnerKey(keyStore));
+	if (!(await controlDb.ensureOwnerKey(founding.publicKey, label))) {
+		// A row arrived between the two reads: the party has an owner now, so judge the key as above.
+		return wiredIfOwner(node, founding);
+	}
+	await node.useOwnerSigner(founding);
+	return 'enrolled';
+}
+
+async function wiredIfOwner(node: CadreNode, signer: OwnerSigner): Promise<OwnerGenesisResult> {
+	return (await node.wireOwnKeyIfOwner(signer)) ? 'enrolled' : 'member';
+}
+
+/**
+ * Wire `held`, the owner slot's key, when the party lists it. A node takes one owner signer, so
+ * a signer already wired is asked about instead (is it still a live owner?) and never replaced.
+ */
+async function wireJoinedOwner(node: CadreNode, held: OwnerSigner | undefined): Promise<boolean> {
+	if (node.getOwnerSigner() !== null) return await node.wireOwnKeyIfOwner();
+	return held !== undefined && (await node.wireOwnKeyIfOwner(held));
+}