wire-mesh-core 3.5.1 → 3.6.1

package/dist/domain/mesh-session.d.cts

@@ -81,7 +81,17 @@ export interface MeshSession {
   readonly coordinatorFrames: AsyncIterable<CoordinatorFrame>;
   connect: (address: string, localDomains: readonly string[]) => Promise<void>;
   sendPing: () => Promise<void>;
-  /** Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives -- FIFO-paired against this call's own ping, since ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's own promise resolves against the Nth pong received after it, never matched by any other means. Rejects if the connection closes, or (when timeoutMs is given) if no pong arrives within timeoutMs, rather than resolving a sentinel value the way sendManageRequest's own timeout does -- there is no natural "no answer" value for a bare millisecond count to double as. Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong -- today, relay-hub's own frame handling (wire-mesh#181) -- so calling this against a connection to a plain peer that never sends pong hangs until timeoutMs (if given) or forever. Exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time this over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg. */
+  /**
+   * Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives.
+   *
+   * The pairing is FIFO because ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's promise resolves against the Nth pong received after it, never matched by any other means.
+   *
+   * Rejects with a plain Error if the connection closes, and with a PingTimeoutError (from ping-round-trips.ts) when `timeoutMs` is given and no pong arrives within it, so a caller can tell an unanswered ping from a dropped connection. It never resolves a sentinel the way sendManageRequest's own timeout does, because there is no natural "no answer" value for a bare millisecond count to double as.
+   *
+   * Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong, which today means relay-hub's own frame handling (wire-mesh#181). Called against a plain peer that never sends pong it hangs until `timeoutMs` if given, or forever.
+   *
+   * It exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time it over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg.
+   */
   sendPingMeasureRtt: (timeoutMs?: number) => Promise<number>;
   /** Attaches this token to every `manage-request` sent from now on. */
   setToken: (token: CapabilityToken) => void;

package/dist/domain/mesh-session.d.mts

@@ -81,7 +81,17 @@ export interface MeshSession {
   readonly coordinatorFrames: AsyncIterable<CoordinatorFrame>;
   connect: (address: string, localDomains: readonly string[]) => Promise<void>;
   sendPing: () => Promise<void>;
-  /** Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives -- FIFO-paired against this call's own ping, since ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's own promise resolves against the Nth pong received after it, never matched by any other means. Rejects if the connection closes, or (when timeoutMs is given) if no pong arrives within timeoutMs, rather than resolving a sentinel value the way sendManageRequest's own timeout does -- there is no natural "no answer" value for a bare millisecond count to double as. Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong -- today, relay-hub's own frame handling (wire-mesh#181) -- so calling this against a connection to a plain peer that never sends pong hangs until timeoutMs (if given) or forever. Exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time this over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg. */
+  /**
+   * Sends a ping-frame and resolves with the round-trip time in milliseconds once the correlated pong-frame arrives.
+   *
+   * The pairing is FIFO because ping-frame carries no correlation id of its own (spec/transport.cddl): the Nth call's promise resolves against the Nth pong received after it, never matched by any other means.
+   *
+   * Rejects with a plain Error if the connection closes, and with a PingTimeoutError (from ping-round-trips.ts) when `timeoutMs` is given and no pong arrives within it, so a caller can tell an unanswered ping from a dropped connection. It never resolves a sentinel the way sendManageRequest's own timeout does, because there is no natural "no answer" value for a bare millisecond count to double as.
+   *
+   * Unlike sendPing (fire-and-forget, answered by nothing on an ordinary peer connection), this is answered only by a peer that replies to ping with pong, which today means relay-hub's own frame handling (wire-mesh#181). Called against a plain peer that never sends pong it hangs until `timeoutMs` if given, or forever.
+   *
+   * It exists to isolate the sender-to-hub leg of a relayed path.trace round trip: time it over the same connection a relayed manage-request travelled, then subtract it from path.trace's own end-to-end RTT to recover the hub-to-target leg.
+   */
   sendPingMeasureRtt: (timeoutMs?: number) => Promise<number>;
   /** Attaches this token to every `manage-request` sent from now on. */
   setToken: (token: CapabilityToken) => void;

package/dist/domain/notice-board.d.cts

@@ -10,7 +10,8 @@ import { RoomNoticeVerdictReason } from "./room.cjs";
  */
 export interface RoomKeyStore {
   get: (room: string, epoch: number) => Promise<Uint8Array | undefined>;
-  set: (room: string, epoch: number, key: Uint8Array) => void;
+  /** May be asynchronous, as storing a key durably is; callers wait for it before relying on the key being held. */
+  set: (room: string, epoch: number, key: Uint8Array) => Promise<void> | void;
   /** The highest epoch held for a room -- what postEncryptedNotice stamps a new notice with. */
   currentEpoch: (room: string) => Promise<number | undefined>;
 }

package/dist/domain/notice-board.d.mts

@@ -10,7 +10,8 @@ import { RoomNoticeVerdictReason } from "./room.mjs";
  */
 export interface RoomKeyStore {
   get: (room: string, epoch: number) => Promise<Uint8Array | undefined>;
-  set: (room: string, epoch: number, key: Uint8Array) => void;
+  /** May be asynchronous, as storing a key durably is; callers wait for it before relying on the key being held. */
+  set: (room: string, epoch: number, key: Uint8Array) => Promise<void> | void;
   /** The highest epoch held for a room -- what postEncryptedNotice stamps a new notice with. */
   currentEpoch: (room: string) => Promise<number | undefined>;
 }

package/dist/domain/ping-round-trips.cjs

@@ -1,5 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/domain/ping-round-trips.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+var PingTimeoutError = class extends Error {
+	constructor() {
+		super("timed out waiting for pong");
+		this.name = "PingTimeoutError";
+	}
+};
 function createPingRoundTrips() {
 	const pending = [];
 	function cancel(sentAt) {
@@ -28,11 +35,12 @@ function createPingRoundTrips() {
 			if (timeoutMs === void 0) return rtt;
 			return Promise.race([rtt, new Promise((_resolve, reject) => {
 				setTimeout(() => {
-					if (cancel(sentAt)) reject(/* @__PURE__ */ new Error("timed out waiting for pong"));
+					if (cancel(sentAt)) reject(new PingTimeoutError());
 				}, timeoutMs);
 			})]);
 		}
 	};
 }
 //#endregion
+exports.PingTimeoutError = PingTimeoutError;
 exports.createPingRoundTrips = createPingRoundTrips;

package/dist/domain/ping-round-trips.d.cts

@@ -1,4 +1,8 @@
 //#region src/domain/ping-round-trips.d.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+export declare class PingTimeoutError extends Error {
+  constructor();
+}
 export interface PingRoundTrips {
   /** Resolves the oldest still-pending call with (nowMs - itsOwnSentAt) -- called once per pong-frame received. A no-op if nothing is pending (a stray pong with no outstanding call). */
   resolveOldest: (nowMs: number) => void;

package/dist/domain/ping-round-trips.d.mts

@@ -1,4 +1,8 @@
 //#region src/domain/ping-round-trips.d.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+export declare class PingTimeoutError extends Error {
+  constructor();
+}
 export interface PingRoundTrips {
   /** Resolves the oldest still-pending call with (nowMs - itsOwnSentAt) -- called once per pong-frame received. A no-op if nothing is pending (a stray pong with no outstanding call). */
   resolveOldest: (nowMs: number) => void;

package/dist/domain/ping-round-trips.mjs

@@ -1,4 +1,11 @@
 //#region src/domain/ping-round-trips.ts
+/** Why a ping was given up on: no pong arrived within the caller's `timeoutMs`. A call rejected for any other reason (the connection dropped or closed first) rejects with a plain Error, so a caller counting unanswered pings tells the two apart by this class rather than by message text. */
+var PingTimeoutError = class extends Error {
+	constructor() {
+		super("timed out waiting for pong");
+		this.name = "PingTimeoutError";
+	}
+};
 function createPingRoundTrips() {
 	const pending = [];
 	function cancel(sentAt) {
@@ -27,11 +34,11 @@ function createPingRoundTrips() {
 			if (timeoutMs === void 0) return rtt;
 			return Promise.race([rtt, new Promise((_resolve, reject) => {
 				setTimeout(() => {
-					if (cancel(sentAt)) reject(/* @__PURE__ */ new Error("timed out waiting for pong"));
+					if (cancel(sentAt)) reject(new PingTimeoutError());
 				}, timeoutMs);
 			})]);
 		}
 	};
 }
 //#endregion
-export { createPingRoundTrips };
+export { PingTimeoutError, createPingRoundTrips };

package/dist/domain/room-rekey.cjs

@@ -100,7 +100,7 @@ function createRoomRekeyHandler(options) {
 			return;
 		}
 		await incoming.respond({ result: "ok" });
-		options.onRekey({
+		await options.onRekey({
 			room: roomPath,
 			keyEpoch,
 			contentKeys

package/dist/domain/room-rekey.d.cts

@@ -25,8 +25,8 @@ export interface CreateRoomRekeyHandlerOptions {
   revocation: RevocationCheck;
   /** This recipient's own currently-held room:member token for the room being rekeyed, verified fresh on every incoming room.rekey (not cached) -- see this module's own doc comment for why its certified root issuer-key is what the ECDH derivation uses, rather than a separately-tracked live-sender identity. */
   ownRoomMemberToken: CapabilityToken;
-  /** Called once per successfully unwrapped room.rekey. */
-  onRekey: (event: Readonly<RoomRekeyEvent>) => void;
+  /** Called once per successfully unwrapped room.rekey, after the sender has been told it succeeded. May be asynchronous, as storing a key durably is; the handler waits for it, so a failure to store reaches whoever awaits the handler. */
+  onRekey: (event: Readonly<RoomRekeyEvent>) => Promise<void> | void;
 }
 /**
  * Builds a reusable handler for one room's incoming room.rekey messages. Checks, in order: the outer verb is room:member (otherwise "malformed"); the params payload parses against room.rekey's own CDDL shape (otherwise "malformed"); the request's own scope is a room scope (otherwise "scope_mismatch"); ownRoomMemberToken independently passes every one of core/room's six verifier obligations, scoped to the incoming request's own room path (a failure responds with verifyRoomToken's own specific reason, e.g. "wrong_chain_root"/"wrong_scope_path"/"expired"); this identity actually supports deriveSharedSecret (otherwise "ecdh_unsupported" -- an Ed25519-only identity genuinely cannot participate). Only then does it derive the shared secret against the verified chain's own rootIssuerKey, derive one wrapping key per granted epoch (per the array-ordering convention: entry i is epoch i+1, counting back from key-epoch), and unwrap each -- a failure at that final cryptographic step (a forged sender, or genuine corruption) responds "unwrap_failed" rather than surfacing a partially-decoded result.

package/dist/domain/room-rekey.d.mts

@@ -25,8 +25,8 @@ export interface CreateRoomRekeyHandlerOptions {
   revocation: RevocationCheck;
   /** This recipient's own currently-held room:member token for the room being rekeyed, verified fresh on every incoming room.rekey (not cached) -- see this module's own doc comment for why its certified root issuer-key is what the ECDH derivation uses, rather than a separately-tracked live-sender identity. */
   ownRoomMemberToken: CapabilityToken;
-  /** Called once per successfully unwrapped room.rekey. */
-  onRekey: (event: Readonly<RoomRekeyEvent>) => void;
+  /** Called once per successfully unwrapped room.rekey, after the sender has been told it succeeded. May be asynchronous, as storing a key durably is; the handler waits for it, so a failure to store reaches whoever awaits the handler. */
+  onRekey: (event: Readonly<RoomRekeyEvent>) => Promise<void> | void;
 }
 /**
  * Builds a reusable handler for one room's incoming room.rekey messages. Checks, in order: the outer verb is room:member (otherwise "malformed"); the params payload parses against room.rekey's own CDDL shape (otherwise "malformed"); the request's own scope is a room scope (otherwise "scope_mismatch"); ownRoomMemberToken independently passes every one of core/room's six verifier obligations, scoped to the incoming request's own room path (a failure responds with verifyRoomToken's own specific reason, e.g. "wrong_chain_root"/"wrong_scope_path"/"expired"); this identity actually supports deriveSharedSecret (otherwise "ecdh_unsupported" -- an Ed25519-only identity genuinely cannot participate). Only then does it derive the shared secret against the verified chain's own rootIssuerKey, derive one wrapping key per granted epoch (per the array-ordering convention: entry i is epoch i+1, counting back from key-epoch), and unwrap each -- a failure at that final cryptographic step (a forged sender, or genuine corruption) responds "unwrap_failed" rather than surfacing a partially-decoded result.

package/dist/domain/room-rekey.mjs

@@ -99,7 +99,7 @@ function createRoomRekeyHandler(options) {
 			return;
 		}
 		await incoming.respond({ result: "ok" });
-		options.onRekey({
+		await options.onRekey({
 			room: roomPath,
 			keyEpoch,
 			contentKeys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "3.5.1",
+  "version": "3.6.1",
   "dependencies": {
     "cbor2": "2.3.0",
     "cddl.js": "1.0.1",