@serfab/cadre-core 1.13.0 → 1.15.0

package/src/control-stream.ts

@@ -35,6 +35,10 @@ export interface ControlStream extends AsyncIterable<Uint8Array> {
   send(data: Uint8Array): boolean;
   close(): Promise<void>;
   abort(err: Error): void;
+  /** Whether the remote has half-closed its write end (`'closed'`); absent on test doubles. */
+  readonly remoteWriteStatus?: string;
+  /** Bytes received and not yet read; absent on test doubles. */
+  readonly readBufferLength?: number;
 }
 
 /** Write a JSON object as a single 4-byte big-endian length-prefixed frame. */
@@ -206,16 +210,31 @@ export function readStreamToEnd(
   return Promise.race([readLoop, timeout]).finally(() => clearTimeout(timer));
 }
 
-/** Accumulate every chunk to EOF, rejecting once the running total exceeds `maxBytes`. */
+/**
+ * Accumulate every chunk to EOF, rejecting once the running total exceeds `maxBytes`.
+ *
+ * A remote that half-closed before this read began has already sent everything it will,
+ * so the read ends once those buffered bytes are in. Its own end-of-stream cannot be
+ * waited for: libp2p 3.3.11's stream iterator ends on the one-shot `remoteCloseWrite`
+ * event, and an iterator attached after it fired never ends. That happens to any handler
+ * that awaits before reading, as the control-protocol guard's live membership check makes
+ * the wake and strand-addr handlers do.
+ */
 async function collect(stream: ControlStream, maxBytes: number, label: string): Promise<Uint8Array> {
   const chunks: Uint8Array[] = [];
   let total = 0;
-  for await (const chunk of stream) {
-    const bytes = toBytes(chunk);
-    chunks.push(bytes);
-    total += bytes.length;
-    if (total > maxBytes) {
-      throw new Error(`${label} message too large: ${total} bytes exceeds max ${maxBytes}`);
+  const alreadySent = stream.remoteWriteStatus === 'closed' ? (stream.readBufferLength ?? 0) : undefined;
+  if (alreadySent !== 0) {
+    for await (const chunk of stream) {
+      const bytes = toBytes(chunk);
+      chunks.push(bytes);
+      total += bytes.length;
+      if (total > maxBytes) {
+        throw new Error(`${label} message too large: ${total} bytes exceeds max ${maxBytes}`);
+      }
+      if (alreadySent !== undefined && total >= alreadySent) {
+        break;
+      }
     }
   }
 

package/src/delegate-admission.ts

@@ -21,7 +21,7 @@
  * granted delegate is admitted outright, never drawing on the small
  * unauthorized-reservation budget that unplaced peers share
  * (`membership-connection-gater.ts` → "The relay-reservation seam") and never
- * racing its not-reserving connection deadline. The fail-closed per-stream gate
+ * put on the provisional connection deadline. The fail-closed per-stream gate
  * (`authorizeInboundControlStream`) never honors a grant, so a delegate gets
  * the connection and its reservation (all a circuit-relay `hop` needs) and
  * nothing more.

package/src/device-token.ts

@@ -9,15 +9,16 @@
  * encoding, so no field split is ambiguous even with an opaque platform token. It
  * is intentionally NOT JSON-canonicalized (deterministic across node/browser/RN,
  * no key ordering) and is reconstructable inside the `DeviceToken.AuthorizedUpdate`
- * SQL constraint from the row's own columns:
+ * SQL constraint from the row's own columns and the node-local `party_id()`:
  *
- *   digest('CadreControl.DeviceToken', 'publish',
+ *   digest('CadreControl.DeviceToken', 'publish', party_id(),
  *          new.PeerId, new.Platform, new.Token, cast(new.UpdatedAt as text))
  *
  * Keep {@link deviceTokenSignedPayload} and that constraint byte-for-byte in sync.
  * The `'publish'` action tag marks this as a peer's SELF-signed record (signed with
  * the peer's own key, not an owner key) and keeps it disjoint from every
- * owner-signed digest.
+ * owner-signed digest; the party id keeps a record published into one party's table
+ * from verifying in another's (peer-record.ts says why a node uses its own party).
  *
  * Unlike a peer-address record, a device-token record carries NO public key: the
  * signature is verified against the `CadrePeer.PublicKey` bound to the same PeerId
@@ -34,10 +35,11 @@ import type { DeviceTokenRecord, PushPlatform } from './types.js';
  * `DeviceToken.AuthorizedUpdate` constraint exactly; both sides take the default
  * base64url output of a single `digest(...)`, which round-trips cleanly.
  */
-export function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>): string {
+export function deviceTokenSignedPayload(partyId: string, record: Omit<DeviceTokenRecord, 'sig'>): string {
   const fields = controlAuthorizationFields(
     'CadreControl.DeviceToken',
     'publish',
+    partyId,
     [record.peerId, record.platform, record.token, String(record.updatedAt)]
   );
   return digest(fields, 'sha256', 'base64url') as string;
@@ -47,14 +49,16 @@ export function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>)
  * Sign a device-token record with the ed25519 private key behind its `peerId`.
  * Returns a fully-populated {@link DeviceTokenRecord}.
  *
+ * @param partyId - the party whose `DeviceToken` table the record is published into
  * @param fields - the record fields to sign
  * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
  */
 export function signDeviceTokenRecord(
+  partyId: string,
   fields: Omit<DeviceTokenRecord, 'sig'>,
   privateKeyB64: string
 ): DeviceTokenRecord {
-  const payloadDigest = deviceTokenSignedPayload(fields);
+  const payloadDigest = deviceTokenSignedPayload(partyId, fields);
   const sig = sign(
     payloadDigest,
     privateKeyB64,
@@ -68,15 +72,15 @@ export function signDeviceTokenRecord(
 
 /**
  * Verify a record's self-signature against the `CadrePeer.PublicKey` (base64url)
- * bound to its `peerId`. Reconstructs the signed bytes from the record exactly as
- * {@link signDeviceTokenRecord} produced them. Returns false on a missing key/sig or
- * any verification failure.
+ * bound to its `peerId`, for `partyId`. Reconstructs the signed bytes from the record
+ * exactly as {@link signDeviceTokenRecord} produced them. Returns false on a missing
+ * key/sig or any verification failure.
  */
-export function verifyDeviceTokenSignature(record: DeviceTokenRecord, publicKeyB64: string): boolean {
+export function verifyDeviceTokenSignature(partyId: string, record: DeviceTokenRecord, publicKeyB64: string): boolean {
   if (!publicKeyB64 || !record.sig) {
     return false;
   }
-  const payloadDigest = deviceTokenSignedPayload(record);
+  const payloadDigest = deviceTokenSignedPayload(partyId, record);
   return verify(
     payloadDigest,
     record.sig,

package/src/ed25519-key.ts

@@ -1,5 +1,7 @@
 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';
 
 /**
@@ -68,12 +70,56 @@ 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 `CadreInvite`'s `ownerKeys`, a donation request's
+ * 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.
  */
@@ -95,15 +141,6 @@ function describeRejected(value: string): string {
  * 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.
  *
- * **This rule is restated once outside this package**, in `validateOwnerKey`
- * (`packages/cadre-provider/src/server/owner-key-validation.ts`): cadre-provider declares no
- * `workspace:` dependencies and validates `POST /containers` pins over `uint8arrays`
- * directly. Change the rule here and change it there — the copies are kept in step by
- * hand, since neither package can import the other's. Each side pins its own copy to the
- * same accept/reject table (`test/ed25519-key.spec.ts` here,
- * `create-container-owner-keys.test.ts` there), so a change fails the suite of the
- * package it was made in and lands the editor on this pointer.
- *
  * @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.

package/src/fetch-impl.ts

@@ -0,0 +1,23 @@
+/**
+ * The `fetch` a cross-platform HTTP caller in this package uses: the one injected for tests
+ * and embedders, else the runtime's global. Shared by the formation-approval client and the
+ * provider client, so both resolve it the same way.
+ *
+ * Bound to `globalThis` because an unbound global `fetch` is an illegal invocation in browsers
+ * (and in any runtime whose `fetch` is a branded method rather than a plain function).
+ */
+
+/** The injected `fetch`, else the bound global; undefined when the runtime has none. */
+export function resolveFetch(fetchImpl?: typeof fetch): typeof fetch | undefined {
+	if (fetchImpl) return fetchImpl;
+	return typeof globalThis.fetch === 'function' ? globalThis.fetch.bind(globalThis) : undefined;
+}
+
+/** {@link resolveFetch}, throwing when the runtime has no `fetch` and none was injected. */
+export function requireFetch(fetchImpl?: typeof fetch): typeof fetch {
+	const resolved = resolveFetch(fetchImpl);
+	if (!resolved) {
+		throw new Error('No fetch implementation: globalThis.fetch is missing and none was supplied');
+	}
+	return resolved;
+}

package/src/file-durable-slot.ts

@@ -1,63 +1,64 @@
-/**
- * Node-only {@link DurableSlot} backend: one JSON file per party under `dir`,
- * at `<dir>/<name>.<encoded partyId>.json` (0600, atomically replaced on every
- * save), so one directory can hold the same node-local record for several
- * parties without cross-party leakage.
- *
- * This is the whole platform-specific part of the file-backed node-local
- * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`,
- * `enrolled-machine-store-file.ts`); the load policy, envelope and write chain
- * are cross-platform — in `node-local-snapshot.ts` for the first two, and in
- * `enrolled-machine-store.ts` for the third, which deliberately does not share
- * that machinery. Like its three importers, this module imports
- * `node:fs/promises`, so it is kept OUT of the package's cross-platform
- * default entry and is not itself an exported subpath.
- */
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import { encodeFileSafeComponent, isNotFound, writeFileAtomically } from './fs-atomic.js';
-import type { DurableSlot } from './node-local-snapshot.js';
-
-export class FileDurableSlot implements DurableSlot {
-	/** Filename-safe form of the party id, shared by the record and temp paths. */
-	private readonly encodedParty: string;
-
-	constructor(
-		private readonly dir: string,
-		private readonly name: string,
-		partyId: string
-	) {
-		this.encodedParty = encodeFileSafeComponent(partyId);
-	}
-
-	/**
-	 * The record's bytes as text. An absent file (ENOENT — including an absent
-	 * directory) is `undefined`, a cold start. Every other read failure
-	 * (EACCES, EISDIR, EIO, …) THROWS, per {@link DurableSlot.load}: the caller
-	 * must not mistake an unreadable file for an empty one and snapshot-write
-	 * over it.
-	 */
-	async load(): Promise<string | undefined> {
-		try {
-			return (await readFile(this.filePath())).toString('utf8');
-		} catch (error) {
-			if (isNotFound(error)) return undefined;
-			throw new Error(`FileDurableSlot: ${this.filePath()} is present but unreadable`, { cause: error });
-		}
-	}
-
-	async save(text: string): Promise<void> {
-		await writeFileAtomically(this.dir, this.tempPath(), this.filePath(), new TextEncoder().encode(text));
-	}
-
-	private filePath(): string {
-		return join(this.dir, `${this.name}.${this.encodedParty}.json`);
-	}
-
-	/** Sibling temp path for the atomic replace (random component: collide-free). */
-	private tempPath(): string {
-		const unique = randomBytes(6).toString('hex');
-		return join(this.dir, `${this.name}.${this.encodedParty}.${unique}.tmp`);
-	}
-}
+/**
+ * Node-only {@link DurableSlot} backend: one JSON file per party under `dir`,
+ * at `<dir>/<name>.<encoded partyId>.json` (0600, atomically replaced on every
+ * save), so one directory can hold the same node-local record for several
+ * parties without cross-party leakage.
+ *
+ * This is the whole platform-specific part of the file-backed node-local
+ * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`,
+ * `enrolled-machine-store-file.ts`); the load policy, envelope and write chain
+ * are cross-platform — in `node-local-snapshot.ts` for the first two, and in
+ * `enrolled-machine-store.ts` for the third, which deliberately does not share
+ * that machinery. Like its three importers, this module imports
+ * `node:fs/promises`, so it is kept OUT of the package's cross-platform
+ * default entry and is not itself an exported subpath.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { isNotFound, writeFileAtomically } from './fs-atomic.js';
+import { encodeFileSafeComponent } from './file-safe-name.js';
+import type { DurableSlot } from './node-local-snapshot.js';
+
+export class FileDurableSlot implements DurableSlot {
+	/** Filename-safe form of the party id, shared by the record and temp paths. */
+	private readonly encodedParty: string;
+
+	constructor(
+		private readonly dir: string,
+		private readonly name: string,
+		partyId: string
+	) {
+		this.encodedParty = encodeFileSafeComponent(partyId);
+	}
+
+	/**
+	 * The record's bytes as text. An absent file (ENOENT — including an absent
+	 * directory) is `undefined`, a cold start. Every other read failure
+	 * (EACCES, EISDIR, EIO, …) THROWS, per {@link DurableSlot.load}: the caller
+	 * must not mistake an unreadable file for an empty one and snapshot-write
+	 * over it.
+	 */
+	async load(): Promise<string | undefined> {
+		try {
+			return (await readFile(this.filePath())).toString('utf8');
+		} catch (error) {
+			if (isNotFound(error)) return undefined;
+			throw new Error(`FileDurableSlot: ${this.filePath()} is present but unreadable`, { cause: error });
+		}
+	}
+
+	async save(text: string): Promise<void> {
+		await writeFileAtomically(this.dir, this.tempPath(), this.filePath(), new TextEncoder().encode(text));
+	}
+
+	private filePath(): string {
+		return join(this.dir, `${this.name}.${this.encodedParty}.json`);
+	}
+
+	/** Sibling temp path for the atomic replace (random component: collide-free). */
+	private tempPath(): string {
+		const unique = randomBytes(6).toString('hex');
+		return join(this.dir, `${this.name}.${this.encodedParty}.${unique}.tmp`);
+	}
+}

package/src/file-safe-name.ts

@@ -0,0 +1,32 @@
+/**
+ * The filename-safe encoding of an id, shared by every Node-only file store that keys a file on
+ * a party or key id (`<name>.<encoded id>.json`). A pure string function, so it lives outside
+ * `fs-atomic.ts` and is exported from the cross-platform entry: an embedder that keeps its own
+ * per-party file beside cadre-core's (cadre-cli's removal marker) names it the same way.
+ */
+
+/**
+ * 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()}`
+	);
+}