@serfab/cadre-core 0.9.0 → 0.11.0

package/src/identity-key.ts

@@ -0,0 +1,109 @@
+/**
+ * identity-key — the load-or-create rule for a {@link KeyStore}-backed node
+ * identity, plus the "prove you hold this node key" signer built on top of it.
+ *
+ * Both live here because both are needed *outside* `CadreNode`: an embedding app
+ * (the React Native reference app) has to resolve its identity key before the node
+ * is constructed, so it can sign an out-of-band HTTP request with the same key the
+ * node will then load. Keeping one copy of the load-or-create rule is load-bearing
+ * — a second copy that drifted could generate a fresh key and orphan the real
+ * identity.
+ *
+ * Dependency-free beyond `@libp2p/crypto` + `uint8arrays` (both already core
+ * dependencies), so this module is safe in every (RN / browser / Node) entry graph.
+ */
+import debug from 'debug';
+import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf, publicKeyToProtobuf } from '@libp2p/crypto/keys';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import type { PrivateKey } from '@libp2p/interface';
+import { DEFAULT_IDENTITY_KEY_ID, type KeyId, type KeyStore } from './key-store.js';
+
+const log = debug('sereus:cadre:identity-key');
+
+/**
+ * Load the node identity key from `keyStore`, generating and persisting a fresh
+ * Ed25519 key when the slot is empty.
+ *
+ * A rejected `get` (e.g. {@link KeyStoreAccessError} from a cancelled biometric
+ * prompt) **propagates** — we never fall through to generation on a read error,
+ * because that would silently orphan an existing but momentarily unreadable
+ * identity. Corrupt bytes in the slot likewise throw rather than regenerate.
+ *
+ * Idempotent in effect: a second call on a populated store loads the stored key
+ * and writes nothing.
+ *
+ * @param keyStore - Backend the identity is read from / persisted to.
+ * @param keyId - Slot id; defaults to {@link DEFAULT_IDENTITY_KEY_ID}.
+ * @returns The resolved libp2p private key.
+ */
+export async function loadOrCreateIdentityKey(
+  keyStore: KeyStore,
+  keyId: KeyId = DEFAULT_IDENTITY_KEY_ID
+): Promise<PrivateKey> {
+  // A rejection here (e.g. KeyStoreAccessError) must propagate — do NOT fall
+  // through to generation, which would orphan an existing but unreadable key.
+  const bytes = await keyStore.get(keyId);
+  if (bytes) {
+    // Corrupt/garbage bytes throw here; surface loudly rather than
+    // regenerating (which would orphan the real identity).
+    const loaded = privateKeyFromProtobuf(bytes);
+    log('Identity key loaded from key store (slot present)');
+    return loaded;
+  }
+
+  const generated = await generateKeyPair('Ed25519');
+  await keyStore.set(keyId, privateKeyToProtobuf(generated));
+  log('Identity key generated and persisted to key store (first run)');
+  return generated;
+}
+
+/**
+ * Proof-of-possession signer for a node key, for out-of-band HTTP services that
+ * want to attribute a request to a peer id.
+ *
+ * Deliberately generic — it carries no ICE/TURN vocabulary, and the message it
+ * signs is the caller's business. The one consumer today is the reference apps'
+ * `loadIceConfig`, which signs the TURN credential issuer's peer assertion; those
+ * files mirror this interface structurally rather than importing it, so they stay
+ * dependency-free.
+ */
+export interface PeerKeySigner {
+  /** base58btc peer id — the same string libp2p reports for this node. */
+  readonly peerId: string;
+  /** base64url of the libp2p protobuf-encoded public key. */
+  readonly publicKeyB64: string;
+  /** Sign the UTF-8 bytes of `message`; resolves to a base64url signature. */
+  sign(message: string): Promise<string>;
+}
+
+/**
+ * Wrap a libp2p private key as a {@link PeerKeySigner}.
+ *
+ * Ed25519 only: the peer id is derived as an identity multihash (so
+ * `publicKey.toString()` already *is* the base58btc peer id — no `@libp2p/peer-id`
+ * round trip needed), and verifiers of this proof accept nothing else.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns A signer exposing the peer id, the encoded public key, and `sign`.
+ * @throws If the key is not Ed25519.
+ */
+export function peerKeySigner(privateKey: PrivateKey): PeerKeySigner {
+  if (privateKey.type !== 'Ed25519') {
+    throw new Error(`peerKeySigner requires an Ed25519 key, got ${privateKey.type}`);
+  }
+
+  const publicKey = privateKey.publicKey;
+  // For Ed25519 the public key's digest is an identity multihash, so its string
+  // form is the peer id itself — the same value `peerIdFromPrivateKey` produces.
+  const peerId = publicKey.toString();
+  const publicKeyB64 = uint8ArrayToString(publicKeyToProtobuf(publicKey), 'base64url');
+
+  return {
+    peerId,
+    publicKeyB64,
+    async sign(message: string): Promise<string> {
+      const signature = await privateKey.sign(new TextEncoder().encode(message));
+      return uint8ArrayToString(signature, 'base64url');
+    }
+  };
+}

package/src/index.ts

@@ -8,10 +8,27 @@ export { canonicalJson } from './canonical-json.js';
 export { CadreNode } from './cadre-node.js';
 
 // Control database
-export { ControlDatabase, buildAuthorizationMessage, type ControlDatabaseConfig, type ControlTable } from './control-database.js';
+export { ControlDatabase, MissingHostStrandError, buildAuthorizationMessage, formationVouchMessage, formationConsentMessage, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type MembershipChangeListener, type GuardedDeleteListener, type RevokedRowRef } from './control-database.js';
+
+// Bounded retry for transient control-write failures (classifier + loop behind
+// ControlDatabase.lockedWithRetry; exported so the integration package can drive the
+// classifier against real engine errors)
+export {
+  CONTROL_WRITE_ATTEMPTS,
+  CONTROL_WRITE_RETRY_BUDGET_MS,
+  SCHEMA_INIT_ATTEMPTS,
+  SCHEMA_INIT_RETRY_POLICY,
+  isRetriableControlWriteFailure,
+  isRetriableSchemaInitFailure,
+  retryControlWrite,
+  type ControlWriteRetryOptions
+} from './control-write-retry.js';
+
+// Control-plane authorization field vector (the domain/action tagging every signer shares)
+export { controlAuthorizationFields, type ControlDomain, type ControlAction } from './control-authorization.js';
 
 // Ed25519 key bridge (libp2p Ed25519 -> base64url keypair)
-export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, type Ed25519KeyPair } from './ed25519-key.js';
+export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, requireEd25519PublicKeyB64, type Ed25519KeyPair } from './ed25519-key.js';
 
 // Pluggable key store (backend-agnostic identity/owner key material seam).
 // Dependency-free: the interface, error, default slot id, and in-memory backend
@@ -26,6 +43,46 @@ export {
   type KeyId
 } from './key-store.js';
 
+// The KeyStore-backed identity rule, shared with embedding apps that need the
+// node key BEFORE `CadreNode` exists (RN resolves it to sign its ICE-manifest
+// request), plus the generic "prove you hold this node key" signer built on it.
+export {
+  loadOrCreateIdentityKey,
+  peerKeySigner,
+  type PeerKeySigner
+} from './identity-key.js';
+
+// Node-local trusted-owner anchor: the NON-replicated, per-party record of
+// out-of-band-established owner keys (the trust anchor the replicated OwnerKey
+// table cannot be). Cross-platform: interface + in-memory store only — the
+// file-backed store is the Node-only subpath
+// '@serfab/cadre-core/trusted-owner-store-file' (same isolation as
+// key-store-file) so node:fs never lands in this graph.
+export {
+  MemoryTrustedOwnerStore,
+  PersistentTrustedOwnerStore,
+  type TrustedOwnerStore,
+  type TrustSource
+} from './trusted-owner-store.js';
+
+// The one platform-specific piece of a persistent node-local store: a single
+// durable text slot the embedding app supplies (IndexedDB / SecureStore /
+// SQLite / a file). Everything else — envelope, load policy, snapshot write
+// chain — is cross-platform in node-local-snapshot.ts.
+export type { DurableSlot } from './node-local-snapshot.js';
+
+// Node-local cold-start bootstrap-peer store: the dial targets retained from an
+// applied seed so a node that could not connect on its first try keeps retrying
+// across restarts. Same cross-platform split as the trusted-owner anchor above —
+// interface + in-memory store here, Node-only file backend behind the subpath
+// '@serfab/cadre-core/bootstrap-peer-store-file'.
+export {
+  MemoryBootstrapPeerStore,
+  PersistentBootstrapPeerStore,
+  type BootstrapPeerStore,
+  type BootstrapPeerEntry
+} from './bootstrap-peer-store.js';
+
 // Strand database
 export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
 
@@ -44,6 +101,18 @@ export {
   getStrandStoragePath
 } from './strand-instance-manager.js';
 
+// Strand peer-join block catch-up (push this strand's own blocks to each newly
+// connected strand peer, so a late joiner physically holds pre-join blocks).
+export {
+  StrandBackfill,
+  DEFAULT_STRAND_BACKFILL,
+  MAX_BLOCK_MESSAGE_BYTES,
+  type StrandBackfillConfig,
+  type StrandBackfillDeps,
+  type StrandBackfillResult,
+  type StrandBackfillPushClient
+} from './strand-backfill.js';
+
 // Hibernation
 export {
   HibernationManager,
@@ -72,11 +141,24 @@ export {
   type FormationUsageRecorder,
   type ResolvedHostStrand,
   type StrandProvisioner,
-  type FormationSigner,
   type FormationResponseValidator,
   type StrandSolicitationServiceOptions
 } from './strand-solicitation.js';
 
+// Formation approval client: asks an invite's ValidationUrl hook whether ONE redemption
+// may proceed, and checks the answer against the bytes the control database will verify.
+export {
+  createHttpFormationApprover,
+  signFormationApproval,
+  verifyFormationApproval,
+  FormationApprovalError,
+  type FormationApprovalRequest,
+  type FormationVouchFields,
+  type FormationApproval,
+  type FormationApprover,
+  type FormationApprovalFailure
+} from './formation-approval.js';
+
 // DB-backed FormationUsageRecorder (reads/writes the real CadreControl tables)
 export { ControlFormationUsageRecorder } from './control-formation-recorder.js';
 
@@ -90,12 +172,21 @@ export { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-ke
 export {
   signStrandPayload,
   verifyStrandPayload,
+  signStrandApproval,
+  generateStrandStampId,
   bootstrapFounderMembership,
   issueInvite,
   consumeInvite,
+  cancelInvite,
+  listOutstandingInvites,
   addMemberByManager,
+  revokeMember,
+  leaveStrand,
   registerMemberPeer,
+  listMemberPeers,
+  removeMemberPeer,
   addManager,
+  admitManager,
   removeManager,
   STRAND_ENGINE,
   STRAND_ENGINE_VERSION,
@@ -103,9 +194,17 @@ export {
   type IssueInviteParams,
   type IssuedInvite,
   type ConsumeInviteParams,
+  type CancelInviteParams,
+  type OutstandingInvite,
   type AddMemberByManagerParams,
+  type RevokeMemberParams,
+  type LeaveStrandParams,
   type RegisterMemberPeerParams,
+  type RemoveOwnPeerParams,
+  type RemoveMemberPeerByManagerParams,
+  type RemoveMemberPeerParams,
   type AddManagerParams,
+  type AdmitManagerParams,
   type RemoveManagerParams
 } from './strand-membership-writer.js';
 
@@ -136,7 +235,13 @@ export {
   peerAuthorizationDigest,
   cadrePeerVoucherDigest,
   cadrePeerRemoveDigest,
-  verifyPeerAuthorization
+  deviceTokenAddDigest,
+  deviceTokenRemoveDigest,
+  formationConsentDigest,
+  verifyPeerAuthorization,
+  verifyCadrePeerVoucher,
+  verifyFormationConsent,
+  type DeviceTokenAuthorizedRow
 } from './peer-authorization.js';
 
 // Strand Wake (control-network push-wake protocol)
@@ -212,6 +317,7 @@ export {
 // the cadence/degree defaults the proactive reconcile routine reads.
 export {
   selectControlCohortDials,
+  DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS,
   DEFAULT_CONTROL_COHORT_RECONCILE_MS,
   DEFAULT_CONTROL_COHORT_TARGET_DEGREE,
   type ControlCohortSelection
@@ -219,7 +325,7 @@ export {
 
 // Seed trust policy (trust anchor for incoming seeds)
 export {
-  dbAnchoredTrustPolicy,
+  anchoredTrustPolicy,
   pinnedKeyTrustPolicy,
   tofuTrustPolicy,
   type SeedTrustPolicy,
@@ -260,6 +366,32 @@ export {
   type StrandFormationManagerOptions
 } from './strand-formation-manager.js';
 
+// Control-network inbound connection gate (membership defense-in-depth)
+export {
+  createMembershipConnectionGater,
+  STRANGER_OPEN_PROTOCOLS,
+  DEFAULT_ENROLLMENT_WINDOW_MS,
+  ADMISSION_DECISION_TIMEOUT_MS,
+  type InboundAdmissionPolicy
+} from './membership-connection-gater.js';
+
+// Relay reservation via the bare `/p2p-circuit` search listener (fail-soft;
+// the fail-fast alternative is `network.relayAddrs`, see relay-reservation.ts)
+export {
+  circuitMultiaddrs,
+  superviseRelayReservation,
+  DEFAULT_RELAY_RESERVE_TIMEOUT_MS,
+  DEFAULT_RELAY_RESERVE_POLL_MS,
+  DEFAULT_RELAY_CHECK_MS,
+  DEFAULT_RELAY_MIN_BACKOFF_MS,
+  DEFAULT_RELAY_MAX_BACKOFF_MS,
+  type RelayReservationStatus,
+  type RelayReservationState,
+  type RelayReserveOptions,
+  type RelayReservationSupervisor,
+  type RelayReservationSupervisorOptions
+} from './relay-reservation.js';
+
 // Connection-path diagnostics (relayed vs direct classification + summary)
 export {
   classifyTransport,