wire-mesh-core 1.21.0 → 1.23.0

package/dist/domain/mesh-session.cjs

@@ -31,7 +31,7 @@ function localHandshake(domains) {
 /**
 * Builds the connection-agnostic session state machine and its public MeshSession surface. dial is null for a session that can never (re)connect on its own -- acceptMeshSession's case, where the one connection it will ever have already exists by construction and reconnect therefore cannot apply (only the remote redialing, and being accepted again, produces a fresh connection). createMeshSession supplies dial as transport.connect so its own connect()/reconnect behaviour is unchanged from before this was factored out.
 */
-function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addresses = []) {
+function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addresses = [], onFrame, onSessionEnd) {
 	let connection = null;
 	let state = { status: "idle" };
 	let handshake = { status: "pending" };
@@ -239,8 +239,10 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		for await (const frame of link.receive()) {
 			if (feedCancelled) return;
 			applyFrame(frame);
+			await onFrame?.(link, frame);
 			emit();
 		}
+		onSessionEnd?.(link);
 		if (state.status === "connected") handleDisconnect("node closed the connection", address, localDomains);
 	}
 	/** Builds this side's own self-advert: this node's own directly-reachable addresses (wire-mesh#38), or none for a caller with nothing to offer (a browser client, which cannot accept inbound connections) -- either is an honest advert, not a stopgap. extensions merge onto peer-advert's own open `* tstr => any` tail -- the mechanism sendGossipUpdate uses to keep a gossiped fact (presence status, an accept/refuse policy, or any future domain's own) live over the connection's lifetime. Extensions are spread before the three mandatory fields (never after) so a caller-supplied key of the same name can never shadow them on the wire -- validateGossipExtensions already rejects that case loudly, but the field order is kept safe in its own right rather than relying solely on the guard staying in sync. */
@@ -466,7 +468,7 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 		if (peerDeviceIdResolved) return;
 		peerDeviceIdResolved = true;
 		resolvePeerDeviceId?.(advert.device);
-	}, options.addresses);
+	}, options.addresses, options.onFrame, options.onSessionEnd);
 	await wireUpConnection(connection, options.label ?? "accepted", localDomains);
 	return {
 		...session,

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

@@ -101,6 +101,10 @@ export interface AcceptedMeshSessionOptions {
   clock?: Readonly<Clock>;
   /** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert. Omit (or pass none) for a caller with nothing to offer. */
   addresses?: readonly string[];
+  /** Observes every frame this session receives, alongside (never instead of) its own manage-request/gossip/handshake handling (wire-mesh#102) -- the integration point an "ordinary opted-in node relays for peers it's already talking to" uses: pass a shared RelayHub instance's own handleFrame, bound to this connection, and it sees the identical frame stream this session's own applyFrame already consumes, with no second for-await loop racing over the same connection.receive(). A dedicated wire-mesh-node/cloudflare-hub deployment, which never runs a MeshSession at all, is unaffected -- this is additive, opt-in, and irrelevant to that case. */
+  onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>;
+  /** Fired once this session's own connection.receive() stream ends -- the counterpart a RelayHub's own forgetConnection needs, since its registry is keyed by this exact Connection and must be cleaned up when it specifically ends. */
+  onSessionEnd?: (connection: Readonly<Connection>) => void;
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
 export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;

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

@@ -101,6 +101,10 @@ export interface AcceptedMeshSessionOptions {
   clock?: Readonly<Clock>;
   /** This node's own directly-reachable "host:port" candidates (wire-mesh#38), advertised in this session's self-advert. Omit (or pass none) for a caller with nothing to offer. */
   addresses?: readonly string[];
+  /** Observes every frame this session receives, alongside (never instead of) its own manage-request/gossip/handshake handling (wire-mesh#102) -- the integration point an "ordinary opted-in node relays for peers it's already talking to" uses: pass a shared RelayHub instance's own handleFrame, bound to this connection, and it sees the identical frame stream this session's own applyFrame already consumes, with no second for-await loop racing over the same connection.receive(). A dedicated wire-mesh-node/cloudflare-hub deployment, which never runs a MeshSession at all, is unaffected -- this is additive, opt-in, and irrelevant to that case. */
+  onFrame?: (connection: Readonly<Connection>, frame: Frame) => void | Promise<void>;
+  /** Fired once this session's own connection.receive() stream ends -- the counterpart a RelayHub's own forgetConnection needs, since its registry is keyed by this exact Connection and must be cleaned up when it specifically ends. */
+  onSessionEnd?: (connection: Readonly<Connection>) => void;
 }
 /** Wires an already-accepted Connection up as a full MeshSession, mirroring exactly what createMeshSession's own dial path does once a connection exists (send handshake, send self-advert, negotiate, consume frames) -- the wire-mesh#45 prerequisite agent-comms needs, since its peers both listen and dial rather than only ever dialing the way web-console's own console UI does. Reconnect does not apply here: if this connection drops, only the remote redialing and being accepted again produces a new connection, and therefore a new session -- there is nothing on this side to retry. */
 export declare function acceptMeshSession(connection: Readonly<Connection>, identity: Readonly<IdentityPort>, localDomains: readonly string[], options?: Readonly<AcceptedMeshSessionOptions>): Promise<AcceptedMeshSession>;

package/dist/domain/mesh-session.mjs

@@ -30,7 +30,7 @@ function localHandshake(domains) {
 /**
 * Builds the connection-agnostic session state machine and its public MeshSession surface. dial is null for a session that can never (re)connect on its own -- acceptMeshSession's case, where the one connection it will ever have already exists by construction and reconnect therefore cannot apply (only the remote redialing, and being accepted again, produces a fresh connection). createMeshSession supplies dial as transport.connect so its own connect()/reconnect behaviour is unchanged from before this was factored out.
 */
-function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addresses = []) {
+function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addresses = [], onFrame, onSessionEnd) {
 	let connection = null;
 	let state = { status: "idle" };
 	let handshake = { status: "pending" };
@@ -238,8 +238,10 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 		for await (const frame of link.receive()) {
 			if (feedCancelled) return;
 			applyFrame(frame);
+			await onFrame?.(link, frame);
 			emit();
 		}
+		onSessionEnd?.(link);
 		if (state.status === "connected") handleDisconnect("node closed the connection", address, localDomains);
 	}
 	/** Builds this side's own self-advert: this node's own directly-reachable addresses (wire-mesh#38), or none for a caller with nothing to offer (a browser client, which cannot accept inbound connections) -- either is an honest advert, not a stopgap. extensions merge onto peer-advert's own open `* tstr => any` tail -- the mechanism sendGossipUpdate uses to keep a gossiped fact (presence status, an accept/refuse policy, or any future domain's own) live over the connection's lifetime. Extensions are spread before the three mandatory fields (never after) so a caller-supplied key of the same name can never shadow them on the wire -- validateGossipExtensions already rejects that case loudly, but the field order is kept safe in its own right rather than relying solely on the guard staying in sync. */
@@ -465,7 +467,7 @@ async function acceptMeshSession(connection, identity, localDomains, options = {
 		if (peerDeviceIdResolved) return;
 		peerDeviceIdResolved = true;
 		resolvePeerDeviceId?.(advert.device);
-	}, options.addresses);
+	}, options.addresses, options.onFrame, options.onSessionEnd);
 	await wireUpConnection(connection, options.label ?? "accepted", localDomains);
 	return {
 		...session,

package/dist/domain/relay-hub.cjs

@@ -104,6 +104,11 @@ function createRelayHub() {
 				forgetConnection(connection);
 			}
 		},
+		registerConnection(connection) {
+			connections.add(connection);
+		},
+		onFrame: handleFrame,
+		onDisconnect: forgetConnection,
 		stop() {
 			connections.clear();
 			devices.clear();

package/dist/domain/relay-hub.d.cts

@@ -1,8 +1,15 @@
+import { D as Frame } from "../protocol-l9RMR3s5.cjs";
 import { t as Connection } from "../transport-Baipikk7.cjs";
 //#region src/domain/relay-hub.d.ts
 export interface RelayHub {
-  /** Drives one accepted connection until it closes: registers gossip-advertised devices, re-broadcasts each gossip frame to every other connected client and replies to the gossiping connection with a catch-up frame of every other already-known device, answers relay-connect by pairing and notifying the target, and forwards relay-data within established pairings. Resolves when the connection's frame stream ends. */
+  /** Drives one accepted connection until it closes: registers gossip-advertised devices, re-broadcasts each gossip frame to every other connected client and replies to the gossiping connection with a catch-up frame of every other already-known device, answers relay-connect by pairing and notifying the target, and forwards relay-data within established pairings. Resolves when the connection's frame stream ends. Internally just registerConnection followed by a loop of onFrame calls and a final onDisconnect -- kept as its own method since a dedicated hub deployment (wire-mesh-node/cloudflare-hub) has nothing else driving the connection and wants the whole lifecycle in one call. */
   handleConnection: (connection: Readonly<Connection>) => Promise<void>;
+  /** Registers a connection with this hub without taking over its own frame-consumption loop (wire-mesh#102) -- the entry point an "ordinary opted-in node relays for peers it's already talking to" uses, alongside onFrame/onDisconnect below, to let a MeshSession's own single connection.receive() loop drive this hub rather than running a second, competing one. Must be called once, before the first onFrame call for this connection, so gossip fan-out (which forwards to every OTHER registered connection) already sees it. */
+  registerConnection: (connection: Readonly<Connection>) => void;
+  /** Observes one frame on an already-registered connection -- the same per-frame logic handleConnection's own loop calls internally, exposed directly so a caller with its own frame-consumption loop can drive it without a second for-await over the same connection.receive(). */
+  onFrame: (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
+  /** Cleans up all registry and pairing state for one connection once its own frame stream has ended -- the onSessionEnd counterpart registerConnection/onFrame needs for the shared-consumption case, since this hub's registry is keyed by Connection and has no other way to learn a connection is gone. */
+  onDisconnect: (connection: Readonly<Connection>) => void;
   /** Drops all registry and pairing state -- used by tests and by transport teardown. */
   stop: () => void;
 }

package/dist/domain/relay-hub.d.mts

@@ -1,8 +1,15 @@
+import { D as Frame } from "../protocol-l9RMR3s5.mjs";
 import { t as Connection } from "../transport-DWbvUc3L.mjs";
 //#region src/domain/relay-hub.d.ts
 export interface RelayHub {
-  /** Drives one accepted connection until it closes: registers gossip-advertised devices, re-broadcasts each gossip frame to every other connected client and replies to the gossiping connection with a catch-up frame of every other already-known device, answers relay-connect by pairing and notifying the target, and forwards relay-data within established pairings. Resolves when the connection's frame stream ends. */
+  /** Drives one accepted connection until it closes: registers gossip-advertised devices, re-broadcasts each gossip frame to every other connected client and replies to the gossiping connection with a catch-up frame of every other already-known device, answers relay-connect by pairing and notifying the target, and forwards relay-data within established pairings. Resolves when the connection's frame stream ends. Internally just registerConnection followed by a loop of onFrame calls and a final onDisconnect -- kept as its own method since a dedicated hub deployment (wire-mesh-node/cloudflare-hub) has nothing else driving the connection and wants the whole lifecycle in one call. */
   handleConnection: (connection: Readonly<Connection>) => Promise<void>;
+  /** Registers a connection with this hub without taking over its own frame-consumption loop (wire-mesh#102) -- the entry point an "ordinary opted-in node relays for peers it's already talking to" uses, alongside onFrame/onDisconnect below, to let a MeshSession's own single connection.receive() loop drive this hub rather than running a second, competing one. Must be called once, before the first onFrame call for this connection, so gossip fan-out (which forwards to every OTHER registered connection) already sees it. */
+  registerConnection: (connection: Readonly<Connection>) => void;
+  /** Observes one frame on an already-registered connection -- the same per-frame logic handleConnection's own loop calls internally, exposed directly so a caller with its own frame-consumption loop can drive it without a second for-await over the same connection.receive(). */
+  onFrame: (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
+  /** Cleans up all registry and pairing state for one connection once its own frame stream has ended -- the onSessionEnd counterpart registerConnection/onFrame needs for the shared-consumption case, since this hub's registry is keyed by Connection and has no other way to learn a connection is gone. */
+  onDisconnect: (connection: Readonly<Connection>) => void;
   /** Drops all registry and pairing state -- used by tests and by transport teardown. */
   stop: () => void;
 }

package/dist/domain/relay-hub.mjs

@@ -103,6 +103,11 @@ function createRelayHub() {
 				forgetConnection(connection);
 			}
 		},
+		registerConnection(connection) {
+			connections.add(connection);
+		},
+		onFrame: handleFrame,
+		onDisconnect: forgetConnection,
 		stop() {
 			connections.clear();
 			devices.clear();

package/dist/domain/relay-use-gate.cjs

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/domain/relay-use-gate.ts
+/** An in-memory, per-connection authorization set. Keyed by Connection identity (reference equality), matching RelayHub's own registry -- a connection that reconnects is a new object and starts unauthorized again, exactly as a fresh relay-hub registration would. */
+function createRelayUseAuthorizationTracker() {
+	const authorized = /* @__PURE__ */ new Set();
+	return {
+		isAuthorized: (connection) => authorized.has(connection),
+		authorize: (connection) => {
+			authorized.add(connection);
+		},
+		revoke: (connection) => {
+			authorized.delete(connection);
+		}
+	};
+}
+/**
+* Wraps a RelayHub's own onFrame with the relay:use check: a relay-connect from an unauthorized connection is silently dropped before ever reaching the hub, matching relay-connect-frame's own existing "no error frame defined for this" precedent for an unresolvable request (spec/transport.cddl, relay-hub.ts's own handleFrame comment for an unknown target-device). Every other frame type passes through unconditionally -- gossip needs no gate (it carries no relay effect on its own), and relay-data needs none either, since it can only ever act within a pairing that itself required an authorized relay-connect to establish in the first place; gating it again would be redundant, not additionally safe.
+*/
+function createGatedRelayFrameHandler(options) {
+	return async function gatedOnFrame(connection, frame) {
+		if (frame.type === "relay-connect" && !options.isAuthorized(connection)) return;
+		await options.onFrame(connection, frame);
+	};
+}
+//#endregion
+exports.createGatedRelayFrameHandler = createGatedRelayFrameHandler;
+exports.createRelayUseAuthorizationTracker = createRelayUseAuthorizationTracker;

package/dist/domain/relay-use-gate.d.cts

@@ -0,0 +1,23 @@
+import { D as Frame } from "../protocol-l9RMR3s5.cjs";
+import { t as Connection } from "../transport-Baipikk7.cjs";
+//#region src/domain/relay-use-gate.d.ts
+export interface RelayUseAuthorizationTracker {
+  /** True once authorize() has been called for this exact connection and revoke() has not been called since. */
+  isAuthorized: (connection: Readonly<Connection>) => boolean;
+  /** Marks a connection as holding a currently-valid relay:use grant -- called from the accepting side of a capability-request/capability-grant-ok exchange once it decides to grant. */
+  authorize: (connection: Readonly<Connection>) => void;
+  /** Withdraws a connection's own authorization, e.g. once its granted token's own expiry has passed or it was revoked. Tracking here is a live boolean, not the token itself -- a caller enforcing expiry calls this when it decides the grant is no longer current. */
+  revoke: (connection: Readonly<Connection>) => void;
+}
+/** An in-memory, per-connection authorization set. Keyed by Connection identity (reference equality), matching RelayHub's own registry -- a connection that reconnects is a new object and starts unauthorized again, exactly as a fresh relay-hub registration would. */
+export declare function createRelayUseAuthorizationTracker(): RelayUseAuthorizationTracker;
+export interface CreateGatedRelayFrameHandlerOptions {
+  /** The RelayHub method this gate wraps -- typically a real RelayHub's own onFrame (wire-mesh#102), but accepting just the one method it needs keeps this module decoupled from RelayHub's full interface. */
+  onFrame: (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
+  isAuthorized: (connection: Readonly<Connection>) => boolean;
+}
+/**
+ * Wraps a RelayHub's own onFrame with the relay:use check: a relay-connect from an unauthorized connection is silently dropped before ever reaching the hub, matching relay-connect-frame's own existing "no error frame defined for this" precedent for an unresolvable request (spec/transport.cddl, relay-hub.ts's own handleFrame comment for an unknown target-device). Every other frame type passes through unconditionally -- gossip needs no gate (it carries no relay effect on its own), and relay-data needs none either, since it can only ever act within a pairing that itself required an authorized relay-connect to establish in the first place; gating it again would be redundant, not additionally safe.
+ */
+export declare function createGatedRelayFrameHandler(options: Readonly<CreateGatedRelayFrameHandlerOptions>): (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
+//#endregion

package/dist/domain/relay-use-gate.d.mts

@@ -0,0 +1,23 @@
+import { D as Frame } from "../protocol-l9RMR3s5.mjs";
+import { t as Connection } from "../transport-DWbvUc3L.mjs";
+//#region src/domain/relay-use-gate.d.ts
+export interface RelayUseAuthorizationTracker {
+  /** True once authorize() has been called for this exact connection and revoke() has not been called since. */
+  isAuthorized: (connection: Readonly<Connection>) => boolean;
+  /** Marks a connection as holding a currently-valid relay:use grant -- called from the accepting side of a capability-request/capability-grant-ok exchange once it decides to grant. */
+  authorize: (connection: Readonly<Connection>) => void;
+  /** Withdraws a connection's own authorization, e.g. once its granted token's own expiry has passed or it was revoked. Tracking here is a live boolean, not the token itself -- a caller enforcing expiry calls this when it decides the grant is no longer current. */
+  revoke: (connection: Readonly<Connection>) => void;
+}
+/** An in-memory, per-connection authorization set. Keyed by Connection identity (reference equality), matching RelayHub's own registry -- a connection that reconnects is a new object and starts unauthorized again, exactly as a fresh relay-hub registration would. */
+export declare function createRelayUseAuthorizationTracker(): RelayUseAuthorizationTracker;
+export interface CreateGatedRelayFrameHandlerOptions {
+  /** The RelayHub method this gate wraps -- typically a real RelayHub's own onFrame (wire-mesh#102), but accepting just the one method it needs keeps this module decoupled from RelayHub's full interface. */
+  onFrame: (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
+  isAuthorized: (connection: Readonly<Connection>) => boolean;
+}
+/**
+ * Wraps a RelayHub's own onFrame with the relay:use check: a relay-connect from an unauthorized connection is silently dropped before ever reaching the hub, matching relay-connect-frame's own existing "no error frame defined for this" precedent for an unresolvable request (spec/transport.cddl, relay-hub.ts's own handleFrame comment for an unknown target-device). Every other frame type passes through unconditionally -- gossip needs no gate (it carries no relay effect on its own), and relay-data needs none either, since it can only ever act within a pairing that itself required an authorized relay-connect to establish in the first place; gating it again would be redundant, not additionally safe.
+ */
+export declare function createGatedRelayFrameHandler(options: Readonly<CreateGatedRelayFrameHandlerOptions>): (connection: Readonly<Connection>, frame: Frame) => Promise<void>;
+//#endregion

package/dist/domain/relay-use-gate.mjs

@@ -0,0 +1,25 @@
+//#region src/domain/relay-use-gate.ts
+/** An in-memory, per-connection authorization set. Keyed by Connection identity (reference equality), matching RelayHub's own registry -- a connection that reconnects is a new object and starts unauthorized again, exactly as a fresh relay-hub registration would. */
+function createRelayUseAuthorizationTracker() {
+	const authorized = /* @__PURE__ */ new Set();
+	return {
+		isAuthorized: (connection) => authorized.has(connection),
+		authorize: (connection) => {
+			authorized.add(connection);
+		},
+		revoke: (connection) => {
+			authorized.delete(connection);
+		}
+	};
+}
+/**
+* Wraps a RelayHub's own onFrame with the relay:use check: a relay-connect from an unauthorized connection is silently dropped before ever reaching the hub, matching relay-connect-frame's own existing "no error frame defined for this" precedent for an unresolvable request (spec/transport.cddl, relay-hub.ts's own handleFrame comment for an unknown target-device). Every other frame type passes through unconditionally -- gossip needs no gate (it carries no relay effect on its own), and relay-data needs none either, since it can only ever act within a pairing that itself required an authorized relay-connect to establish in the first place; gating it again would be redundant, not additionally safe.
+*/
+function createGatedRelayFrameHandler(options) {
+	return async function gatedOnFrame(connection, frame) {
+		if (frame.type === "relay-connect" && !options.isAuthorized(connection)) return;
+		await options.onFrame(connection, frame);
+	};
+}
+//#endregion
+export { createGatedRelayFrameHandler, createRelayUseAuthorizationTracker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "type": "module",
   "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "repository": {
@@ -114,6 +114,10 @@
       "import": "./dist/domain/relay-hub.mjs",
       "require": "./dist/domain/relay-hub.cjs"
     },
+    "./domain/relay-use-gate": {
+      "import": "./dist/domain/relay-use-gate.mjs",
+      "require": "./dist/domain/relay-use-gate.cjs"
+    },
     "./domain/revocation-view": {
       "import": "./dist/domain/revocation-view.mjs",
       "require": "./dist/domain/revocation-view.cjs"