@serfab/cadre-core 1.14.0 → 1.16.0

package/src/fs-atomic.ts

@@ -1,117 +1,92 @@
-/**
- * Node-only filesystem helpers: atomic file write, filename-safe encoding, and
- * the ENOENT check, shared by `key-store-file.ts` and `file-durable-slot.ts`.
- *
- * This module imports `node:fs/promises`, so — like its consumers — it is kept
- * OUT of the package's cross-platform default entry and is not itself an
- * exported subpath; it is only reachable through the Node-only store modules.
- */
-import debug from 'debug';
-import { mkdir, rm, rename, open } from 'node:fs/promises';
-import type { FileHandle } from 'node:fs/promises';
-
-const log = debug('sereus:cadre:fs-atomic');
-
-/** Best-effort POSIX permissions (ignored on Windows / unsupported FSes). */
-export const DIR_MODE = 0o700;
-export const FILE_MODE = 0o600;
-
-/**
- * Percent-encode a string into a filesystem-safe filename component. Beyond
- * `encodeURIComponent` (which already escapes `/`, spaces, and unicode), this
- * also escapes the unreserved characters `encodeURIComponent` leaves intact but
- * that are unsafe in filenames on some platforms (notably `*` on Windows) — and
- * `.`, so a file suffix appended by the caller is the only literal dot, making
- * suffix-stripping unambiguous — and every uppercase letter, because Windows
- * (NTFS) and macOS (APFS/HFS+ by default) ignore case in file names. Reversed by
- * `decodeURIComponent`.
- *
- * The result contains only `a-z0-9-_` and `%XX` escapes (uppercase hex). Since a
- * literal `%` is itself escaped, every `%` starts an escape, so ignoring case
- * can change only escape hex digits — which decode case-insensitively — and two
- * different inputs never yield names equal ignoring case. The escapes keep
- * `encodeURIComponent`'s uppercase hex so a name built from an id with no
- * capital letters (the identity slot `cadre%2Fidentity.key`, a lowercase party
- * id) is the same as before uppercase letters were escaped.
- */
-export function encodeFileSafeComponent(component: string): string {
-	// NOTE: a file left from before uppercase letters were escaped (`trusted-owners.Alice.json`) has, ignoring case, the new name of the all-lowercase id (`alice`), so on Windows/macOS a lookup for that id opens it; the per-party records' envelope party-id check rejects it (cold start), and `FileKeyStore` needs two parties in one key directory whose ids fold to the same lowercase string. The release note says to delete old files; if a store ever reads another id's old file in practice, rename or remove old-format files when the store opens.
-	return encodeURIComponent(component).replace(
-		/(%[0-9A-F]{2})|[!'()*~.A-Z]/g,
-		(c, escape: string | undefined) => escape ?? `%${c.charCodeAt(0).toString(16).toUpperCase()}`
-	);
-}
-
-/** Whether an unknown error is a Node "file/dir not found" (ENOENT). */
-export function isNotFound(error: unknown): boolean {
-	return typeof error === 'object' && error !== null
-		&& (error as { code?: unknown }).code === 'ENOENT';
-}
-
-/**
- * Crash-atomic file write: a concurrent reader sees either the complete
- * previous bytes or the complete new bytes, never a torn file. `dir` is created
- * (0700) if absent; the data is written to `tmpPath` (created exclusively,
- * 0600), fsync'd, then atomically renamed onto `finalPath`. A failure at any
- * point removes the temp file and leaves the previous file untouched.
- *
- * `tmpPath` must be a sibling of `finalPath` (same directory) so the rename
- * stays within one filesystem and is therefore atomic, and should carry a
- * random component so concurrent writers (and crash-orphaned leftovers) are
- * collide-free.
- *
- * Durability bar: the temp file is fsync'd before the rename so a power loss
- * cannot surface a file whose bytes never reached the platter, and `dir` is
- * fsync'd afterwards (best-effort — see {@link syncDirBestEffort}) so the
- * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
- * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
- * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
- * holds the destination open. That cross-process case is out of scope for the
- * single-flight in-process callers here; such a failure surfaces to the caller
- * with the previous file left intact.
- */
-export async function writeFileAtomically(
-	dir: string,
-	tmpPath: string,
-	finalPath: string,
-	data: Uint8Array
-): Promise<void> {
-	await mkdir(dir, { recursive: true, mode: DIR_MODE });
-	// 'wx' creates the temp file exclusively; a name collision (astronomically
-	// unlikely given the caller's random component) fails here before we own anything.
-	const handle = await open(tmpPath, 'wx', FILE_MODE);
-	try {
-		try {
-			await handle.writeFile(data);
-			await handle.sync(); // land bytes on disk before the rename exposes them
-		} finally {
-			await handle.close().catch(() => {});
-		}
-		await rename(tmpPath, finalPath);
-	} catch (error) {
-		// Any failure after creation (write, sync, or rename): drop the temp
-		// file so a retry leaves no `.tmp` debris. The destination is only ever
-		// swapped by the atomic rename, so the previous bytes stay intact.
-		await rm(tmpPath, { force: true }).catch(() => {});
-		throw error;
-	}
-	await syncDirBestEffort(dir);
-}
-
-/**
- * Best-effort fsync of a directory so a fresh file's directory entry is
- * durable across power loss. Opening a directory for fsync is not portable
- * (unsupported on Windows and some filesystems), and rename atomicity does not
- * depend on it — so a failure here is logged and swallowed, never surfaced.
- */
-async function syncDirBestEffort(dir: string): Promise<void> {
-	let dirHandle: FileHandle | undefined;
-	try {
-		dirHandle = await open(dir, 'r');
-		await dirHandle.sync();
-	} catch (error) {
-		log('directory fsync skipped for %s: %o', dir, error);
-	} finally {
-		await dirHandle?.close().catch(() => {});
-	}
-}
+/**
+ * Node-only filesystem helpers: atomic file write and the ENOENT check, shared
+ * by `key-store-file.ts` and `file-durable-slot.ts`. The filename-safe encoding
+ * they also use is cross-platform and lives in `file-safe-name.ts`.
+ *
+ * This module imports `node:fs/promises`, so — like its consumers — it is kept
+ * OUT of the package's cross-platform default entry and is not itself an
+ * exported subpath; it is only reachable through the Node-only store modules.
+ */
+import debug from 'debug';
+import { mkdir, rm, rename, open } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+
+const log = debug('sereus:cadre:fs-atomic');
+
+/** Best-effort POSIX permissions (ignored on Windows / unsupported FSes). */
+export const DIR_MODE = 0o700;
+export const FILE_MODE = 0o600;
+
+/** Whether an unknown error is a Node "file/dir not found" (ENOENT). */
+export function isNotFound(error: unknown): boolean {
+	return typeof error === 'object' && error !== null
+		&& (error as { code?: unknown }).code === 'ENOENT';
+}
+
+/**
+ * Crash-atomic file write: a concurrent reader sees either the complete
+ * previous bytes or the complete new bytes, never a torn file. `dir` is created
+ * (0700) if absent; the data is written to `tmpPath` (created exclusively,
+ * 0600), fsync'd, then atomically renamed onto `finalPath`. A failure at any
+ * point removes the temp file and leaves the previous file untouched.
+ *
+ * `tmpPath` must be a sibling of `finalPath` (same directory) so the rename
+ * stays within one filesystem and is therefore atomic, and should carry a
+ * random component so concurrent writers (and crash-orphaned leftovers) are
+ * collide-free.
+ *
+ * Durability bar: the temp file is fsync'd before the rename so a power loss
+ * cannot surface a file whose bytes never reached the platter, and `dir` is
+ * fsync'd afterwards (best-effort — see {@link syncDirBestEffort}) so the
+ * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
+ * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
+ * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
+ * holds the destination open. That cross-process case is out of scope for the
+ * single-flight in-process callers here; such a failure surfaces to the caller
+ * with the previous file left intact.
+ */
+export async function writeFileAtomically(
+	dir: string,
+	tmpPath: string,
+	finalPath: string,
+	data: Uint8Array
+): Promise<void> {
+	await mkdir(dir, { recursive: true, mode: DIR_MODE });
+	// 'wx' creates the temp file exclusively; a name collision (astronomically
+	// unlikely given the caller's random component) fails here before we own anything.
+	const handle = await open(tmpPath, 'wx', FILE_MODE);
+	try {
+		try {
+			await handle.writeFile(data);
+			await handle.sync(); // land bytes on disk before the rename exposes them
+		} finally {
+			await handle.close().catch(() => {});
+		}
+		await rename(tmpPath, finalPath);
+	} catch (error) {
+		// Any failure after creation (write, sync, or rename): drop the temp
+		// file so a retry leaves no `.tmp` debris. The destination is only ever
+		// swapped by the atomic rename, so the previous bytes stay intact.
+		await rm(tmpPath, { force: true }).catch(() => {});
+		throw error;
+	}
+	await syncDirBestEffort(dir);
+}
+
+/**
+ * Best-effort fsync of a directory so a fresh file's directory entry is
+ * durable across power loss. Opening a directory for fsync is not portable
+ * (unsupported on Windows and some filesystems), and rename atomicity does not
+ * depend on it — so a failure here is logged and swallowed, never surfaced.
+ */
+async function syncDirBestEffort(dir: string): Promise<void> {
+	let dirHandle: FileHandle | undefined;
+	try {
+		dirHandle = await open(dir, 'r');
+		await dirHandle.sync();
+	} catch (error) {
+		log('directory fsync skipped for %s: %o', dir, error);
+	} finally {
+		await dirHandle?.close().catch(() => {});
+	}
+}

package/src/index.ts

@@ -7,8 +7,12 @@ export { canonicalJson } from './canonical-json.js';
 // Main CadreNode class
 export { CadreNode, OWNER_INVITATION_DEFAULT_TTL_MS, CADRE_INVITATION_DEFAULT_TTL_MS } from './cadre-node.js';
 
+// Removing a machine from a cadre: the by-name refusal `CadreNode.removeMachine` throws
+// (the listing, plan and result types are in types.ts)
+export { MachineRemovalRefusedError } from './machine-removal.js';
+
 // Control database
-export { ControlDatabase, MissingHostStrandError, InvitationExhaustedError, CadreInviteIssuerUnknownError, buildAuthorizationMessage, registerPartyIdFunction, formationVouchMessage, formationConsentMessage, cadreInviteAddMessage, cadreInviteRedeemMessage, cadreInviteConsentMessage, projectSeedPeers, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef } from './control-database.js';
+export { ControlDatabase, parseNullableStoredDatetimeMs, MissingHostStrandError, InvitationExhaustedError, CadreInviteIssuerUnknownError, buildAuthorizationMessage, registerPartyIdFunction, formationVouchMessage, formationConsentMessage, cadreInviteAddMessage, cadreInviteRedeemMessage, cadreInviteConsentMessage, projectSeedPeers, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type FormationInviteRow, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef, type MachineRemovalWrites } from './control-database.js';
 
 // Bounded retry for transient control-write failures (classifier + loop behind
 // ControlDatabase.lockedWithRetry; exported so the integration package can drive the
@@ -63,6 +67,10 @@ export {
   type KeyId
 } from './key-store.js';
 
+// The filename-safe form of an id that every Node-only per-party file store names its file
+// with (`<name>.<encoded party>.json`), for an embedder keeping its own file beside theirs.
+export { encodeFileSafeComponent } from './file-safe-name.js';
+
 // The KeyStore-backed identity rule, shared with embedding apps that need the
 // node key BEFORE `CadreNode` exists.
 export { loadOrCreateIdentityKey } from './identity-key.js';
@@ -155,6 +163,7 @@ export {
 
 // Strand database
 export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
+export type { StrandCommitDurability, StrandCommitHeld } from './strand-commit-durability.js';
 
 // Strand management
 export {
@@ -428,7 +437,6 @@ export {
   isPeerRecordFresh,
   isSignalingAddr,
   orderSignalingFirst,
-  withTrailingPeerId,
   currentMemberTrustPolicy,
   DEFAULT_PEER_RECORD_MAX_AGE_MS,
   DEFAULT_PEER_RECORD_HEARTBEAT_MS
@@ -481,8 +489,12 @@ export {
 } from './control-cohort.js';
 
 // Dialing one peer from several candidate addresses, each under its own time
-// limit, so an address that never answers cannot starve the rest.
+// limit, so an address that never answers cannot starve the rest. Each address is
+// bound to the peer expected and dialed outside libp2p's dial queue (`dialAddr`),
+// so another dial of the same peer in flight cannot capture the attempt.
 export {
+  dialAddr,
+  withTrailingPeerId,
   dialPeerAddrs,
   SelfRelayOnlyError,
   PeerUnreachableError,
@@ -550,10 +562,56 @@ export {
 export {
   encodeNodeClaimPayload,
   decodeNodeClaimPayload,
+  selectNodeClaimAddresses,
+  withClaimDestination,
+  destinationPeerIdOf,
+  classifyDialAddress,
   NODE_CLAIM_PAYLOAD_PREFIX,
-  type NodeClaimPayload
+  type NodeClaimPayload,
+  type NodeClaimAddressOptions,
+  type DialAddressKind
 } from './node-claim-payload.js';
 
+// Moving a party's strands into another party of the same owner, so an app's strands follow
+// the app into the user's main cadre: the bundle one node exports from the party it leaves,
+// its adoption by a node of the party it joined, and the check that the party it left holds
+// nothing the joined one lacks before it is dissolved.
+export {
+  exportStrandBundle,
+  adoptStrandBundle,
+  readStrandHoldings,
+  unheldBundleContent,
+  StrandMoveNotOwnerError,
+  StrandMoveSamePartyError,
+  type StrandHoldings,
+  type StrandBundle,
+  type StrandBundleEntry,
+  type FormationInviteEntry,
+  type StrandMoveReport,
+  type StrandMoveFailure
+} from './strand-move.js';
+
+// The join request: what an app that wants to join a cadre copies to the app that manages it,
+// which mints an invitation targeted at the request's peer id. Both paste-text prefixes live here.
+export {
+  encodeCadreJoinRequest,
+  decodeCadreJoinRequest,
+  requireCadreJoinReply,
+  CADRE_JOIN_REQUEST_PREFIX,
+  CADRE_INVITATION_PREFIX,
+  CADRE_JOIN_REQUEST_MAX_APP_NAME,
+  type CadreJoinReply,
+  type CadreJoinRequest
+} from './cadre-join-request.js';
+
+// Renting a node from a hosting provider: the provider's descriptor, the app's side of the
+// OAuth 2 + PKCE sign-in, the typed client for its container API, and `rentNode` /
+// `finishRental`, which add the rented container to this node's cadre by invitation or by
+// claim. Global `fetch` and `crypto.getRandomValues` only, so the whole set loads on React
+// Native and in the browser (`docs/architecture.md` → "Renting a node from an app"). The
+// barrel is the curated list; it is not repeated here.
+export * from './provider/index.js';
+
 // Schema Verification
 export {
   signSchema,
@@ -599,6 +657,7 @@ export { formationDeadlines, type FormationDeadlines } from './strand-formation-
 export {
   CadreInviteHandler,
   redeemAtMembers,
+  redeemInPasses,
   signRedeemRequest,
   verifyRedeemReply,
   encodeCadreInvitation,
@@ -620,9 +679,17 @@ export {
   type CadreInviteHandlerOptions,
   type CadreInviteStore,
   type RedeemAtMembersOptions,
+  type RedeemInPassesOptions,
   type RedeemSigner,
   type CadreInviteRedemption
 } from './cadre-invite-protocol.js';
+// Which machines, and how many addresses of each, an invitation names; how far a cadre invitation reaches
+export {
+  selectCadreInvitationMembers,
+  cadreInvitationReach,
+  CADRE_INVITATION_MAX_ADDRS,
+  CADRE_INVITATION_ADDRS_PER_SIBLING
+} from './invitation-bootstrap.js';
 // The pending-join retry loop behind CadreNode.requestJoin (PendingJoinStatus is in types.ts)
 export { PENDING_JOIN_POLL_MS, PENDING_JOIN_MAX_BACKOFF_MS, MAX_PENDING_JOIN_MS } from './pending-join-runner.js';
 

package/src/invitation-bootstrap.ts

@@ -1,23 +1,43 @@
 /**
- * Which of the inviting party's other machines an open invitation names, so a joiner can still
- * form while the machine that minted it is offline. The minting machine's own addresses go
- * first and are not chosen here (`CadreNode.createOpenInvitation`).
+ * Which of the inviting party's machines an invitation names, so a joiner can still form or
+ * join while the machine that minted it is offline: an open strand invitation
+ * (`CadreNode.createOpenInvitation`, which puts the minting machine's own addresses first
+ * itself) and a cadre invitation ({@link selectCadreInvitationMembers}). Also how far a cadre
+ * invitation reaches once its minting machine is gone ({@link cadreInvitationReach}).
  */
 
+import { classifyDialAddress, destinationPeerIdOf, type DialAddressKind } from './node-claim-payload.js';
+import type { CadreInvitationReach } from './types.js';
+
 /**
  * At most this many of the party's other machines are named, each with at most
  * {@link INVITATION_ADDRS_PER_SIBLING} addresses: 12 extra addresses of roughly 100–200
  * characters, base64url-encoded into an invitation shared as text.
  *
- * NOTE: if invitations are ever carried in a QR code, lower these caps or name the machines by
- * peer id only.
- * NOTE: the per-machine cap keeps the record's order (relay first, then direct addresses as the
- * machine published them, loopback included). If a sibling with many interfaces is seen to have
- * its reachable address cut, rank loopback and private addresses last before slicing.
+ * NOTE: a cadre invitation, which may be carried in a QR code, is capped harder
+ * ({@link CADRE_INVITATION_MAX_ADDRS}); an open strand invitation keeps these caps. If open
+ * invitations are ever carried in a QR code too, cap them the same way.
+ * NOTE: for an open strand invitation the per-machine cap keeps the record's order (relay first,
+ * then direct addresses as the machine published them, loopback included); a cadre invitation
+ * ranks them first. If an open invitation's sibling is seen to have its reachable address cut,
+ * rank the same way.
  */
 export const INVITATION_SIBLING_MACHINES = 3;
 export const INVITATION_ADDRS_PER_SIBLING = 4;
 
+/**
+ * Most addresses a cadre invitation names in total, so its text fits one QR code. Measured
+ * with three owner keys: 2,206 characters encoded at 6 relayed addresses of about 155
+ * characters (the worst case, since ranking puts relayed addresses first), 1,972 with relayed
+ * and direct WebSocket addresses alternating, against 2,331 bytes in the largest QR code at
+ * error-correction level M (2,953 at L). Each further address costs about 170 characters, each
+ * further owner key about 60.
+ */
+export const CADRE_INVITATION_MAX_ADDRS = 6;
+
+/** Most addresses a cadre invitation names for each of the party's other machines. */
+export const CADRE_INVITATION_ADDRS_PER_SIBLING = 2;
+
 /** One other machine of the party whose signed address record resolved. */
 export interface InvitationSibling {
 	peerId: string;
@@ -28,13 +48,71 @@ export interface InvitationSibling {
 }
 
 /**
- * The addresses of the siblings an invitation names. Machines this node is connected to right
- * now come first, since a live connection is the best evidence that a machine is up; a record
- * shows only that it was up within the freshness window. Within each half, newest record first.
+ * The addresses of the siblings an invitation names, at most `perSibling` each. Machines this
+ * node is connected to right now come first, since a live connection is the best evidence that
+ * a machine is up; a record shows only that it was up within the freshness window. Within each
+ * half, newest record first.
  */
-export function selectInvitationSiblingAddrs(siblings: InvitationSibling[], connected: ReadonlySet<string>): string[] {
+export function selectInvitationSiblingAddrs(
+	siblings: InvitationSibling[],
+	connected: ReadonlySet<string>,
+	perSibling: number = INVITATION_ADDRS_PER_SIBLING
+): string[] {
 	return [...siblings]
 		.sort((a, b) => Number(connected.has(b.peerId)) - Number(connected.has(a.peerId)) || b.updatedAt - a.updatedAt)
 		.slice(0, INVITATION_SIBLING_MACHINES)
-		.flatMap((sibling) => sibling.addrs.slice(0, INVITATION_ADDRS_PER_SIBLING));
+		.flatMap((sibling) => sibling.addrs.slice(0, perSibling));
+}
+
+/**
+ * The `members` of a cadre invitation: the minting machine's own addresses first (at most
+ * {@link INVITATION_ADDRS_PER_SIBLING}), then the other machines' in
+ * {@link selectInvitationSiblingAddrs} order (at most {@link CADRE_INVITATION_ADDRS_PER_SIBLING}
+ * each), the whole list cut to {@link CADRE_INVITATION_MAX_ADDRS}. Each machine's addresses are
+ * ranked for a phone before they are cut ({@link rankForPhone}): libp2p reports a machine
+ * listening on every interface with its loopback and private addresses ahead of its relayed one.
+ *
+ * NOTE: accepted tradeoff — with two or more other machines, only the best two addresses of
+ * each survive, connected machines first, so a reachable address of a sibling can be cut. Size
+ * was weighed over completeness, so the text fits a QR code; revisit if redemptions are seen
+ * failing for want of a sibling address the record held.
+ */
+export function selectCadreInvitationMembers(
+	own: readonly string[],
+	siblings: InvitationSibling[],
+	connected: ReadonlySet<string>
+): string[] {
+	const ranked = siblings.map((sibling) => ({ ...sibling, addrs: rankForPhone(sibling.addrs) }));
+	return [
+		...rankForPhone(own).slice(0, INVITATION_ADDRS_PER_SIBLING),
+		...selectInvitationSiblingAddrs(ranked, connected, CADRE_INVITATION_ADDRS_PER_SIBLING),
+	].slice(0, CADRE_INVITATION_MAX_ADDRS);
+}
+
+/** Order in which a phone is likeliest to reach an address: from anywhere, on its network, on that machine, not at all. */
+const PHONE_DIAL_RANK: Record<DialAddressKind, number> = { relay: 0, name: 0, public: 0, private: 1, loopback: 2 };
+
+/** `addrs` best first for a phone dialing them ({@link PHONE_DIAL_RANK}), ties in their given order; one a phone cannot dial (plain TCP) last. */
+function rankForPhone(addrs: readonly string[]): string[] {
+	const rankOf = (addr: string): number => {
+		const kind = classifyDialAddress(addr);
+		return kind === undefined ? 3 : PHONE_DIAL_RANK[kind];
+	};
+	return addrs.map((addr) => ({ addr, rank: rankOf(addr) })).sort((a, b) => a.rank - b.rank).map(({ addr }) => addr);
+}
+
+/**
+ * Where a phone could redeem an invitation naming `members` from, judged on the machines other
+ * than `issuerPeerId`: in the app flows the minting app is the one closed or in the background
+ * when the other app redeems, and two apps on one phone cannot reach each other. An address
+ * names its machine by its last `/p2p/`.
+ */
+export function cadreInvitationReach(members: readonly string[], issuerPeerId: string): CadreInvitationReach {
+	const others = members.flatMap((addr) => {
+		const kind = classifyDialAddress(addr);
+		// Classified, so it parses and `destinationPeerIdOf` cannot throw.
+		return kind === undefined || destinationPeerIdOf(addr) === issuerPeerId ? [] : [kind];
+	});
+	if (others.some((kind) => kind === 'relay' || kind === 'name' || kind === 'public')) return 'anywhere';
+	return others.length > 0 ? 'local-network' : 'issuer-only';
 }