wire-mesh-core 1.20.0 → 1.22.0

package/dist/domain/capability-grant.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_generated_protocol = require("../generated/protocol.cjs");
-const require_tokens = require("../tokens-Dp9BnUTZ.cjs");
+const require_token_scope = require("../token-scope-CxHXTT3u.cjs");
+const require_tokens = require("../tokens-CiNXdKJ8.cjs");
 //#region src/domain/capability-grant.ts
 /**
 * The generic, capability-agnostic capability-grant primitive (wire-mesh#117, spec/management.cddl) -- the unsolicited push counterpart to capability-request.ts's own ask/response primitive. Where capability-request lifts core/room's room.join shape (a pull: the requester asks, the owner mints and returns a grant on the same response) out of that one domain, capability-grant lifts room.invite's own shape (a push: the owner mints unprompted and delivers the grant in the request itself, since there is no approval round-trip to carry it back) the same way. core/room's own room-client.ts is the reference consumer: it builds sendRoomInvite as a thin wrapper over sendCapabilityGrant below, and wires createRoomRouter's dispatch onto createCapabilityGrantHandler for the receiving side.
@@ -68,7 +69,7 @@ function createCapabilityGrantHandler(options) {
 			});
 			return;
 		}
-		if (!require_tokens.scopeNarrows(verdict.claims.scope, incoming.scope)) {
+		if (!require_token_scope.scopeNarrows(verdict.claims.scope, incoming.scope)) {
 			await incoming.respond({
 				result: "error",
 				code: "scope_mismatch"

package/dist/domain/capability-grant.mjs

@@ -1,5 +1,6 @@
 import { capabilityGrantSchema } from "../generated/protocol.mjs";
-import { i as verifyCapabilityToken, o as scopeNarrows } from "../tokens-B5BUgkba.mjs";
+import { n as scopeNarrows } from "../token-scope-Z4bmci4M.mjs";
+import { i as verifyCapabilityToken } from "../tokens-VicRWTj1.mjs";
 //#region src/domain/capability-grant.ts
 /**
 * The generic, capability-agnostic capability-grant primitive (wire-mesh#117, spec/management.cddl) -- the unsolicited push counterpart to capability-request.ts's own ask/response primitive. Where capability-request lifts core/room's room.join shape (a pull: the requester asks, the owner mints and returns a grant on the same response) out of that one domain, capability-grant lifts room.invite's own shape (a push: the owner mints unprompted and delivers the grant in the request itself, since there is no approval round-trip to carry it back) the same way. core/room's own room-client.ts is the reference consumer: it builds sendRoomInvite as a thin wrapper over sendCapabilityGrant below, and wires createRoomRouter's dispatch onto createCapabilityGrantHandler for the receiving side.

package/dist/domain/capability-request.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_generated_protocol = require("../generated/protocol.cjs");
-const require_tokens = require("../tokens-Dp9BnUTZ.cjs");
+const require_tokens = require("../tokens-CiNXdKJ8.cjs");
 //#region src/domain/capability-request.ts
 /**
 * The generic, capability-agnostic capability-request / capability-grant-ok primitive (wire-mesh#78, spec/management.cddl). Lifts core/room's own room.join shape -- an ungated ask, held open, a human (or any other domain-supplied decision) accepts or refuses, acceptance mints and returns a token on the same response -- out of that one domain so any capability can reuse it, not just room:member. core/room's own room-client.ts is the reference consumer: it rewires requestToJoin/createRoomRouter's room.join handling onto requestCapability/createCapabilityRequestHandler below, supplying room-specific extension fields (its member list) through this module's own extensions mechanism rather than this module knowing anything about rooms.

package/dist/domain/capability-request.mjs

@@ -1,5 +1,5 @@
 import { capabilityGrantOkSchema, capabilityRequestSchema } from "../generated/protocol.mjs";
-import { n as mintCapabilityToken } from "../tokens-B5BUgkba.mjs";
+import { n as mintCapabilityToken } from "../tokens-VicRWTj1.mjs";
 //#region src/domain/capability-request.ts
 /**
 * The generic, capability-agnostic capability-request / capability-grant-ok primitive (wire-mesh#78, spec/management.cddl). Lifts core/room's own room.join shape -- an ungated ask, held open, a human (or any other domain-supplied decision) accepts or refuses, acceptance mints and returns a token on the same response -- out of that one domain so any capability can reuse it, not just room:member. core/room's own room-client.ts is the reference consumer: it rewires requestToJoin/createRoomRouter's room.join handling onto requestCapability/createCapabilityRequestHandler below, supplying room-specific extension fields (its member list) through this module's own extensions mechanism rather than this module knowing anything about rooms.

package/dist/domain/grant-candidates.cjs

@@ -0,0 +1,47 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_generated_protocol = require("../generated/protocol.cjs");
+const require_token_scope = require("../token-scope-CxHXTT3u.cjs");
+let zod = require("zod");
+//#region src/domain/grant-candidates.ts
+/**
+* Gossip-advertised delegable-grant candidates (wire-mesh#87): lets a bearer of a still-delegable held token advertise its own willingness to field a capability-request for a narrower grant, and lets a requester discover the best candidate it can currently see before falling back to a capability's own structural root (that fallback -- e.g. a room's owner device-id -- is the caller's own concern, entirely outside this module; findGrantCandidate only ever returns a nearer-than-root candidate or undefined). Rides peer-advert's existing open extension tail (spec/transport.cddl, wire-mesh#91) under the domain-qualified key "capability-request/candidates" -- no new CDDL, no new wire mechanism, just a structured value on an already-shipped extension point.
+*
+* Honest limit, not closed here: this is only ever as complete as gossip propagation allows. A request can go unanswered by a nearer delegate not because none exists, but because it hasn't been gossiped yet -- the same "detection with propagation delay" honesty this spec already accepts for kick propagation and revocation timing.
+*/
+const GOSSIP_CANDIDATES_KEY = "capability-request/candidates";
+const grantCandidateSchema = zod.z.object({
+	capability: zod.z.string(),
+	scope: require_generated_protocol.capabilityScopeSchema,
+	"delegations-remaining": zod.z.number().int().nonnegative().optional()
+});
+const grantCandidateListSchema = zod.z.array(grantCandidateSchema);
+/**
+* Advertises this session's own willingness to field a capability-request for each of candidates, via sendGossipUpdate's own re-advertisement mechanism. Callers own their own re-advertisement cadence (there is no timer here, matching sendGossipUpdate's own design) -- calling this again with a fresh list replaces what was previously advertised under this key, exactly as sendGossipUpdate's own peer-advert re-send already does for any other extension field.
+*/
+async function advertiseGrantCandidates(session, candidates) {
+	await session.sendGossipUpdate({ [GOSSIP_CANDIDATES_KEY]: candidates });
+}
+/**
+* Scans directory for the best currently-gossiped delegate that could field a capability-request for capability over scope, returning its device-id -- or undefined when nothing closer than the capability's own structural root has been gossiped. A candidate qualifies when its own advertised capability matches exactly and its own advertised scope narrows into the requested scope (scopeNarrows' existing narrowing relation: the candidate's scope is the same as or a broader ancestor of scope), and its own delegations-remaining is either absent (unbounded) or still greater than zero.
+*
+* Selection policy, deliberately simple and explicitly stated rather than left implicit: the first qualifying candidate in directory's own order wins. Gossip carries no distance, latency, or load signal a requester could meaningfully rank candidates by, so no ordering directory provides is more defensible than any other -- "first seen" is exactly as reasonable a tie-break as "highest delegations-remaining" and simplest to implement and reason about.
+*
+* A malformed or non-conforming candidates value (from a misbehaving or out-of-date peer) is silently skipped, not treated as an error: this is a discovery hint over self-asserted, unsigned gossip, not a security check -- the token minted from any candidate this function returns still goes through mintCapabilityToken's own full narrowing checks regardless.
+*/
+function findGrantCandidate(directory, capability, scope) {
+	for (const entry of directory) {
+		const raw = entry.advert[GOSSIP_CANDIDATES_KEY];
+		if (raw === void 0) continue;
+		const parsed = grantCandidateListSchema.safeParse(raw);
+		if (!parsed.success) continue;
+		for (const candidate of parsed.data) {
+			if (candidate.capability !== capability) continue;
+			const remaining = candidate["delegations-remaining"];
+			if (remaining !== void 0 && remaining <= 0) continue;
+			if (require_token_scope.scopeNarrows(candidate.scope, scope)) return entry.device;
+		}
+	}
+}
+//#endregion
+exports.advertiseGrantCandidates = advertiseGrantCandidates;
+exports.findGrantCandidate = findGrantCandidate;

package/dist/domain/grant-candidates.d.cts

@@ -0,0 +1,26 @@
+import { o as CapabilityScope, x as DeviceId } from "../protocol-l9RMR3s5.cjs";
+import { DirectoryEntry, MeshSession } from "./mesh-session.cjs";
+import { z } from "zod";
+//#region src/domain/grant-candidates.d.ts
+declare const grantCandidateSchema: z.ZodObject<{
+  capability: z.ZodString;
+  scope: z.ZodLazy<z.ZodObject<{
+    kind: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  "delegations-remaining": z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type GrantCandidate = z.infer<typeof grantCandidateSchema>;
+/**
+ * Advertises this session's own willingness to field a capability-request for each of candidates, via sendGossipUpdate's own re-advertisement mechanism. Callers own their own re-advertisement cadence (there is no timer here, matching sendGossipUpdate's own design) -- calling this again with a fresh list replaces what was previously advertised under this key, exactly as sendGossipUpdate's own peer-advert re-send already does for any other extension field.
+ */
+export declare function advertiseGrantCandidates(session: Readonly<MeshSession>, candidates: readonly GrantCandidate[]): Promise<void>;
+/**
+ * Scans directory for the best currently-gossiped delegate that could field a capability-request for capability over scope, returning its device-id -- or undefined when nothing closer than the capability's own structural root has been gossiped. A candidate qualifies when its own advertised capability matches exactly and its own advertised scope narrows into the requested scope (scopeNarrows' existing narrowing relation: the candidate's scope is the same as or a broader ancestor of scope), and its own delegations-remaining is either absent (unbounded) or still greater than zero.
+ *
+ * Selection policy, deliberately simple and explicitly stated rather than left implicit: the first qualifying candidate in directory's own order wins. Gossip carries no distance, latency, or load signal a requester could meaningfully rank candidates by, so no ordering directory provides is more defensible than any other -- "first seen" is exactly as reasonable a tie-break as "highest delegations-remaining" and simplest to implement and reason about.
+ *
+ * A malformed or non-conforming candidates value (from a misbehaving or out-of-date peer) is silently skipped, not treated as an error: this is a discovery hint over self-asserted, unsigned gossip, not a security check -- the token minted from any candidate this function returns still goes through mintCapabilityToken's own full narrowing checks regardless.
+ */
+export declare function findGrantCandidate(directory: readonly DirectoryEntry[], capability: string, scope: Readonly<CapabilityScope>): DeviceId | undefined;
+//#endregion

package/dist/domain/grant-candidates.d.mts

@@ -0,0 +1,26 @@
+import { o as CapabilityScope, x as DeviceId } from "../protocol-l9RMR3s5.mjs";
+import { DirectoryEntry, MeshSession } from "./mesh-session.mjs";
+import { z } from "zod";
+//#region src/domain/grant-candidates.d.ts
+declare const grantCandidateSchema: z.ZodObject<{
+  capability: z.ZodString;
+  scope: z.ZodLazy<z.ZodObject<{
+    kind: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  "delegations-remaining": z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type GrantCandidate = z.infer<typeof grantCandidateSchema>;
+/**
+ * Advertises this session's own willingness to field a capability-request for each of candidates, via sendGossipUpdate's own re-advertisement mechanism. Callers own their own re-advertisement cadence (there is no timer here, matching sendGossipUpdate's own design) -- calling this again with a fresh list replaces what was previously advertised under this key, exactly as sendGossipUpdate's own peer-advert re-send already does for any other extension field.
+ */
+export declare function advertiseGrantCandidates(session: Readonly<MeshSession>, candidates: readonly GrantCandidate[]): Promise<void>;
+/**
+ * Scans directory for the best currently-gossiped delegate that could field a capability-request for capability over scope, returning its device-id -- or undefined when nothing closer than the capability's own structural root has been gossiped. A candidate qualifies when its own advertised capability matches exactly and its own advertised scope narrows into the requested scope (scopeNarrows' existing narrowing relation: the candidate's scope is the same as or a broader ancestor of scope), and its own delegations-remaining is either absent (unbounded) or still greater than zero.
+ *
+ * Selection policy, deliberately simple and explicitly stated rather than left implicit: the first qualifying candidate in directory's own order wins. Gossip carries no distance, latency, or load signal a requester could meaningfully rank candidates by, so no ordering directory provides is more defensible than any other -- "first seen" is exactly as reasonable a tie-break as "highest delegations-remaining" and simplest to implement and reason about.
+ *
+ * A malformed or non-conforming candidates value (from a misbehaving or out-of-date peer) is silently skipped, not treated as an error: this is a discovery hint over self-asserted, unsigned gossip, not a security check -- the token minted from any candidate this function returns still goes through mintCapabilityToken's own full narrowing checks regardless.
+ */
+export declare function findGrantCandidate(directory: readonly DirectoryEntry[], capability: string, scope: Readonly<CapabilityScope>): DeviceId | undefined;
+//#endregion

package/dist/domain/grant-candidates.mjs

@@ -0,0 +1,45 @@
+import { capabilityScopeSchema } from "../generated/protocol.mjs";
+import { n as scopeNarrows } from "../token-scope-Z4bmci4M.mjs";
+import { z } from "zod";
+//#region src/domain/grant-candidates.ts
+/**
+* Gossip-advertised delegable-grant candidates (wire-mesh#87): lets a bearer of a still-delegable held token advertise its own willingness to field a capability-request for a narrower grant, and lets a requester discover the best candidate it can currently see before falling back to a capability's own structural root (that fallback -- e.g. a room's owner device-id -- is the caller's own concern, entirely outside this module; findGrantCandidate only ever returns a nearer-than-root candidate or undefined). Rides peer-advert's existing open extension tail (spec/transport.cddl, wire-mesh#91) under the domain-qualified key "capability-request/candidates" -- no new CDDL, no new wire mechanism, just a structured value on an already-shipped extension point.
+*
+* Honest limit, not closed here: this is only ever as complete as gossip propagation allows. A request can go unanswered by a nearer delegate not because none exists, but because it hasn't been gossiped yet -- the same "detection with propagation delay" honesty this spec already accepts for kick propagation and revocation timing.
+*/
+const GOSSIP_CANDIDATES_KEY = "capability-request/candidates";
+const grantCandidateSchema = z.object({
+	capability: z.string(),
+	scope: capabilityScopeSchema,
+	"delegations-remaining": z.number().int().nonnegative().optional()
+});
+const grantCandidateListSchema = z.array(grantCandidateSchema);
+/**
+* Advertises this session's own willingness to field a capability-request for each of candidates, via sendGossipUpdate's own re-advertisement mechanism. Callers own their own re-advertisement cadence (there is no timer here, matching sendGossipUpdate's own design) -- calling this again with a fresh list replaces what was previously advertised under this key, exactly as sendGossipUpdate's own peer-advert re-send already does for any other extension field.
+*/
+async function advertiseGrantCandidates(session, candidates) {
+	await session.sendGossipUpdate({ [GOSSIP_CANDIDATES_KEY]: candidates });
+}
+/**
+* Scans directory for the best currently-gossiped delegate that could field a capability-request for capability over scope, returning its device-id -- or undefined when nothing closer than the capability's own structural root has been gossiped. A candidate qualifies when its own advertised capability matches exactly and its own advertised scope narrows into the requested scope (scopeNarrows' existing narrowing relation: the candidate's scope is the same as or a broader ancestor of scope), and its own delegations-remaining is either absent (unbounded) or still greater than zero.
+*
+* Selection policy, deliberately simple and explicitly stated rather than left implicit: the first qualifying candidate in directory's own order wins. Gossip carries no distance, latency, or load signal a requester could meaningfully rank candidates by, so no ordering directory provides is more defensible than any other -- "first seen" is exactly as reasonable a tie-break as "highest delegations-remaining" and simplest to implement and reason about.
+*
+* A malformed or non-conforming candidates value (from a misbehaving or out-of-date peer) is silently skipped, not treated as an error: this is a discovery hint over self-asserted, unsigned gossip, not a security check -- the token minted from any candidate this function returns still goes through mintCapabilityToken's own full narrowing checks regardless.
+*/
+function findGrantCandidate(directory, capability, scope) {
+	for (const entry of directory) {
+		const raw = entry.advert[GOSSIP_CANDIDATES_KEY];
+		if (raw === void 0) continue;
+		const parsed = grantCandidateListSchema.safeParse(raw);
+		if (!parsed.success) continue;
+		for (const candidate of parsed.data) {
+			if (candidate.capability !== capability) continue;
+			const remaining = candidate["delegations-remaining"];
+			if (remaining !== void 0 && remaining <= 0) continue;
+			if (scopeNarrows(candidate.scope, scope)) return entry.device;
+		}
+	}
+}
+//#endregion
+export { advertiseGrantCandidates, findGrantCandidate };

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/revocation-view.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_tokens = require("../tokens-Dp9BnUTZ.cjs");
+const require_tokens = require("../tokens-CiNXdKJ8.cjs");
 const require_domain_device_id = require("./device-id.cjs");
 //#region src/domain/revocation-view.ts
 function revocationKey(tokenId) {

package/dist/domain/revocation-view.mjs

@@ -1,4 +1,4 @@
-import { a as verifyRevocationEntry } from "../tokens-B5BUgkba.mjs";
+import { a as verifyRevocationEntry } from "../tokens-VicRWTj1.mjs";
 import { bytesToHex } from "./device-id.mjs";
 //#region src/domain/revocation-view.ts
 function revocationKey(tokenId) {

package/dist/domain/room-token-verification.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_tokens = require("../tokens-Dp9BnUTZ.cjs");
+const require_tokens = require("../tokens-CiNXdKJ8.cjs");
 const require_domain_device_id = require("./device-id.cjs");
 const require_domain_room_path = require("./room-path.cjs");
 //#region src/domain/room-token-verification.ts

package/dist/domain/room-token-verification.mjs

@@ -1,4 +1,4 @@
-import { i as verifyCapabilityToken } from "../tokens-B5BUgkba.mjs";
+import { i as verifyCapabilityToken } from "../tokens-VicRWTj1.mjs";
 import { deviceIdToHex } from "./device-id.mjs";
 import { parseRoomPath } from "./room-path.mjs";
 //#region src/domain/room-token-verification.ts

package/dist/domain/tokens.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_tokens = require("../tokens-Dp9BnUTZ.cjs");
+const require_tokens = require("../tokens-CiNXdKJ8.cjs");
 exports.canGrant = require_tokens.canGrant;
 exports.mintCapabilityToken = require_tokens.mintCapabilityToken;
 exports.mintRevocationEntry = require_tokens.mintRevocationEntry;

package/dist/domain/tokens.mjs

@@ -1,2 +1,2 @@
-import { a as verifyRevocationEntry, i as verifyCapabilityToken, n as mintCapabilityToken, r as mintRevocationEntry, t as canGrant } from "../tokens-B5BUgkba.mjs";
+import { a as verifyRevocationEntry, i as verifyCapabilityToken, n as mintCapabilityToken, r as mintRevocationEntry, t as canGrant } from "../tokens-VicRWTj1.mjs";
 export { canGrant, mintCapabilityToken, mintRevocationEntry, verifyCapabilityToken, verifyRevocationEntry };

package/dist/token-scope-CxHXTT3u.cjs

@@ -0,0 +1,43 @@
+//#region src/domain/token-scope.ts
+/**
+* Extracted out of tokens.ts specifically so token-predicates.ts (the generic evaluator's own delegate handlers) and tokens.ts (the chain walk, and its re-export for capability-grant.ts) can both depend on this pure, no-domain-imports module without creating an import cycle between the two -- tokens.ts imports evaluateNarrowing from token-predicates.ts, and token-predicates.ts's own scope-narrows/bearer-is handlers need these exact comparisons, so neither of those two files may import the other.
+*/
+function bytesEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+	return true;
+}
+/** True when the path contains a "." or ".." segment. Purely lexical prefix comparison would let "/work/../org" pass under "/work" -- a path that normalises outside the parent -- so any relative segment fails the narrowing comparison wholesale: fail-closed rather than reimplementing path normalisation, consistent with how empty, case-different, and non-boundary-prefixed paths already behave. */
+function hasRelativeSegment(path) {
+	return path.split("/").some((segment) => segment === "." || segment === "..");
+}
+/** True when childPath is parentPath or a descendant of it, compared on "/"-segment boundaries: "/work/sub" narrows "/work", but "/workbook" does NOT narrow "/work" despite the string prefix, because "book" continues the same segment. Paths containing "." or ".." segments never narrow anything (see hasRelativeSegment). */
+function pathNarrows(childPath, parentPath) {
+	if (hasRelativeSegment(childPath) || hasRelativeSegment(parentPath)) return false;
+	if (childPath === parentPath) return true;
+	if (!childPath.startsWith(parentPath)) return false;
+	if (parentPath.endsWith("/")) return true;
+	return childPath.charAt(parentPath.length) === "/";
+}
+/**
+* True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain, and for token-predicates.ts's own `scope-narrows` delegate handler.
+*/
+function scopeNarrows(parent, child) {
+	if (parent.kind !== child.kind) return false;
+	if (parent.path === void 0) return true;
+	if (child.path === void 0) return false;
+	return pathNarrows(child.path, parent.path);
+}
+//#endregion
+Object.defineProperty(exports, "bytesEqual", {
+	enumerable: true,
+	get: function() {
+		return bytesEqual;
+	}
+});
+Object.defineProperty(exports, "scopeNarrows", {
+	enumerable: true,
+	get: function() {
+		return scopeNarrows;
+	}
+});

package/dist/token-scope-Z4bmci4M.mjs

@@ -0,0 +1,32 @@
+//#region src/domain/token-scope.ts
+/**
+* Extracted out of tokens.ts specifically so token-predicates.ts (the generic evaluator's own delegate handlers) and tokens.ts (the chain walk, and its re-export for capability-grant.ts) can both depend on this pure, no-domain-imports module without creating an import cycle between the two -- tokens.ts imports evaluateNarrowing from token-predicates.ts, and token-predicates.ts's own scope-narrows/bearer-is handlers need these exact comparisons, so neither of those two files may import the other.
+*/
+function bytesEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+	return true;
+}
+/** True when the path contains a "." or ".." segment. Purely lexical prefix comparison would let "/work/../org" pass under "/work" -- a path that normalises outside the parent -- so any relative segment fails the narrowing comparison wholesale: fail-closed rather than reimplementing path normalisation, consistent with how empty, case-different, and non-boundary-prefixed paths already behave. */
+function hasRelativeSegment(path) {
+	return path.split("/").some((segment) => segment === "." || segment === "..");
+}
+/** True when childPath is parentPath or a descendant of it, compared on "/"-segment boundaries: "/work/sub" narrows "/work", but "/workbook" does NOT narrow "/work" despite the string prefix, because "book" continues the same segment. Paths containing "." or ".." segments never narrow anything (see hasRelativeSegment). */
+function pathNarrows(childPath, parentPath) {
+	if (hasRelativeSegment(childPath) || hasRelativeSegment(parentPath)) return false;
+	if (childPath === parentPath) return true;
+	if (!childPath.startsWith(parentPath)) return false;
+	if (parentPath.endsWith("/")) return true;
+	return childPath.charAt(parentPath.length) === "/";
+}
+/**
+* True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain, and for token-predicates.ts's own `scope-narrows` delegate handler.
+*/
+function scopeNarrows(parent, child) {
+	if (parent.kind !== child.kind) return false;
+	if (parent.path === void 0) return true;
+	if (child.path === void 0) return false;
+	return pathNarrows(child.path, parent.path);
+}
+//#endregion
+export { scopeNarrows as n, bytesEqual as t };

package/dist/{tokens-Dp9BnUTZ.cjs → tokens-CiNXdKJ8.cjs}

@@ -1,38 +1,8 @@
 const require_generated_protocol = require("./generated/protocol.cjs");
+const require_token_scope = require("./token-scope-CxHXTT3u.cjs");
 let zod = require("zod");
 let cbor2 = require("cbor2");
 let trilean = require("trilean");
-//#region src/domain/token-scope.ts
-/**
-* Extracted out of tokens.ts specifically so token-predicates.ts (the generic evaluator's own delegate handlers) and tokens.ts (the chain walk, and its re-export for capability-grant.ts) can both depend on this pure, no-domain-imports module without creating an import cycle between the two -- tokens.ts imports evaluateNarrowing from token-predicates.ts, and token-predicates.ts's own scope-narrows/bearer-is handlers need these exact comparisons, so neither of those two files may import the other.
-*/
-function bytesEqual(a, b) {
-	if (a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
-	return true;
-}
-/** True when the path contains a "." or ".." segment. Purely lexical prefix comparison would let "/work/../org" pass under "/work" -- a path that normalises outside the parent -- so any relative segment fails the narrowing comparison wholesale: fail-closed rather than reimplementing path normalisation, consistent with how empty, case-different, and non-boundary-prefixed paths already behave. */
-function hasRelativeSegment(path) {
-	return path.split("/").some((segment) => segment === "." || segment === "..");
-}
-/** True when childPath is parentPath or a descendant of it, compared on "/"-segment boundaries: "/work/sub" narrows "/work", but "/workbook" does NOT narrow "/work" despite the string prefix, because "book" continues the same segment. Paths containing "." or ".." segments never narrow anything (see hasRelativeSegment). */
-function pathNarrows(childPath, parentPath) {
-	if (hasRelativeSegment(childPath) || hasRelativeSegment(parentPath)) return false;
-	if (childPath === parentPath) return true;
-	if (!childPath.startsWith(parentPath)) return false;
-	if (parentPath.endsWith("/")) return true;
-	return childPath.charAt(parentPath.length) === "/";
-}
-/**
-* True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain, and for token-predicates.ts's own `scope-narrows` delegate handler.
-*/
-function scopeNarrows(parent, child) {
-	if (parent.kind !== child.kind) return false;
-	if (parent.path === void 0) return true;
-	if (child.path === void 0) return false;
-	return pathNarrows(child.path, parent.path);
-}
-//#endregion
 //#region src/domain/token-predicates.ts
 /** The wire shape of `token-claims.conditions` once CBOR-decoded: trilean's own PredicateNodeSchema is the single source of truth for what a condition entry may contain, re-validated here rather than trusted from a CDDL-generated shadow schema (see tokens.cddl's own comment on why `conditions` is an opaque bstr, not a native CDDL type) -- a token from an untrusted peer must pass trilean's real schema before any of its conditions are evaluated. Explicitly annotated: trilean's PredicateNodeSchema is a deeply recursive z.lazy() type whose inferred shape is too large for tsdown's declaration-file generator to serialise (TS7056) without this. */
 const conditionsListSchema = zod.z.array(trilean.PredicateNodeSchema);
@@ -67,7 +37,7 @@ function booleanFound(value) {
 const narrowingHandlers = {
 	[BEARER_IS]: (_payload, context) => {
 		if (context.parentClaims === void 0) return booleanFound(false);
-		return booleanFound(bytesEqual(context.parentClaims.bearer, context.childIssuer));
+		return booleanFound(require_token_scope.bytesEqual(context.parentClaims.bearer, context.childIssuer));
 	},
 	[EXPIRES_AT]: (_payload, context) => {
 		if (context.parentClaims === void 0) return booleanFound(false);
@@ -75,7 +45,7 @@ const narrowingHandlers = {
 	},
 	[SCOPE_NARROWS]: (_payload, context) => {
 		if (context.parentClaims === void 0) return booleanFound(false);
-		return booleanFound(scopeNarrows(context.parentClaims.scope, context.candidate.scope));
+		return booleanFound(require_token_scope.scopeNarrows(context.parentClaims.scope, context.candidate.scope));
 	},
 	[CAPABILITY_IS]: (_payload, context) => {
 		if (context.parentClaims === void 0) return booleanFound(false);
@@ -211,7 +181,7 @@ async function verifyCapabilityToken(token, options) {
 		...options.extraPredicateResolvers !== void 0 ? { extraPredicateResolvers: options.extraPredicateResolvers } : {}
 	});
 	if (!verdict.ok) return verdict;
-	if (options.expectedBearer !== void 0 && !bytesEqual(verdict.claims.bearer, options.expectedBearer)) return {
+	if (options.expectedBearer !== void 0 && !require_token_scope.bytesEqual(verdict.claims.bearer, options.expectedBearer)) return {
 		ok: false,
 		reason: "bearer_mismatch"
 	};
@@ -221,7 +191,7 @@ async function verifyCapabilityToken(token, options) {
 * Does one recorded revocation-claims entry actually revoke targetClaims, per management.cddl's own additive obligation? Valid when EITHER the entry's own issuer equals the target token's own issuer (the original, unconditional rule -- only a token's own issuer may revoke it), OR the entry carries an `authorization` that independently verifies as an ordinary capability-token -- with `expectedBearer` set to THIS entry's own `issuer`, proving the authorization was actually granted to the party submitting this revocation, not merely referenced from someone else's -- whose own `capability` is `manage:revoke` (spec/registry/core-capabilities.md) and whose own `scope` narrows targetClaims' scope. An authorization that fails any part of this (wrong capability, scope doesn't narrow, fails ordinary verification -- expired, revoked, bad signature, bearer mismatch) makes the entry no more valid than if `authorization` were absent; it never falls back to weakening the issuer-match rule.
 */
 async function revocationEntryGrantsRevoke(entry, targetClaims, options) {
-	if (bytesEqual(entry.issuer, targetClaims.issuer)) return true;
+	if (require_token_scope.bytesEqual(entry.issuer, targetClaims.issuer)) return true;
 	if (entry.authorization === void 0) return false;
 	let decodedAuthorization;
 	try {
@@ -235,7 +205,7 @@ async function revocationEntryGrantsRevoke(entry, targetClaims, options) {
 		...options,
 		expectedBearer: entry.issuer
 	});
-	return authorizationVerdict.ok && authorizationVerdict.claims.capability === "manage:revoke" && scopeNarrows(authorizationVerdict.claims.scope, targetClaims.scope);
+	return authorizationVerdict.ok && authorizationVerdict.claims.capability === "manage:revoke" && require_token_scope.scopeNarrows(authorizationVerdict.claims.scope, targetClaims.scope);
 }
 async function verifyTokenChain(token, options) {
 	const [protectedHeader, , payload, signature] = token;
@@ -262,7 +232,8 @@ async function verifyTokenChain(token, options) {
 		ok: false,
 		reason: "bad_signature"
 	};
-	if (!bytesEqual(await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]), claims.issuer)) return {
+	const derivedIssuerId = await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]);
+	if (!require_token_scope.bytesEqual(derivedIssuerId, claims.issuer)) return {
 		ok: false,
 		reason: "wrong_issuer"
 	};
@@ -377,7 +348,8 @@ async function verifyRevocationEntry(entry, options) {
 		ok: false,
 		reason: "bad_signature"
 	};
-	if (!bytesEqual(await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]), claims.issuer)) return {
+	const derivedIssuerId = await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]);
+	if (!require_token_scope.bytesEqual(derivedIssuerId, claims.issuer)) return {
 		ok: false,
 		reason: "wrong_issuer"
 	};
@@ -500,12 +472,6 @@ Object.defineProperty(exports, "mintRevocationEntry", {
 		return mintRevocationEntry;
 	}
 });
-Object.defineProperty(exports, "scopeNarrows", {
-	enumerable: true,
-	get: function() {
-		return scopeNarrows;
-	}
-});
 Object.defineProperty(exports, "verifyCapabilityToken", {
 	enumerable: true,
 	get: function() {

package/dist/{tokens-B5BUgkba.mjs → tokens-VicRWTj1.mjs}

@@ -1,38 +1,8 @@
 import { capabilityTokenSchema, revocationClaimsSchema, tokenClaimsSchema } from "./generated/protocol.mjs";
+import { n as scopeNarrows, t as bytesEqual } from "./token-scope-Z4bmci4M.mjs";
 import { z } from "zod";
 import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
 import { PredicateNodeSchema, evaluatePredicate } from "trilean";
-//#region src/domain/token-scope.ts
-/**
-* Extracted out of tokens.ts specifically so token-predicates.ts (the generic evaluator's own delegate handlers) and tokens.ts (the chain walk, and its re-export for capability-grant.ts) can both depend on this pure, no-domain-imports module without creating an import cycle between the two -- tokens.ts imports evaluateNarrowing from token-predicates.ts, and token-predicates.ts's own scope-narrows/bearer-is handlers need these exact comparisons, so neither of those two files may import the other.
-*/
-function bytesEqual(a, b) {
-	if (a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
-	return true;
-}
-/** True when the path contains a "." or ".." segment. Purely lexical prefix comparison would let "/work/../org" pass under "/work" -- a path that normalises outside the parent -- so any relative segment fails the narrowing comparison wholesale: fail-closed rather than reimplementing path normalisation, consistent with how empty, case-different, and non-boundary-prefixed paths already behave. */
-function hasRelativeSegment(path) {
-	return path.split("/").some((segment) => segment === "." || segment === "..");
-}
-/** True when childPath is parentPath or a descendant of it, compared on "/"-segment boundaries: "/work/sub" narrows "/work", but "/workbook" does NOT narrow "/work" despite the string prefix, because "book" continues the same segment. Paths containing "." or ".." segments never narrow anything (see hasRelativeSegment). */
-function pathNarrows(childPath, parentPath) {
-	if (hasRelativeSegment(childPath) || hasRelativeSegment(parentPath)) return false;
-	if (childPath === parentPath) return true;
-	if (!childPath.startsWith(parentPath)) return false;
-	if (parentPath.endsWith("/")) return true;
-	return childPath.charAt(parentPath.length) === "/";
-}
-/**
-* True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain, and for token-predicates.ts's own `scope-narrows` delegate handler.
-*/
-function scopeNarrows(parent, child) {
-	if (parent.kind !== child.kind) return false;
-	if (parent.path === void 0) return true;
-	if (child.path === void 0) return false;
-	return pathNarrows(child.path, parent.path);
-}
-//#endregion
 //#region src/domain/token-predicates.ts
 /** The wire shape of `token-claims.conditions` once CBOR-decoded: trilean's own PredicateNodeSchema is the single source of truth for what a condition entry may contain, re-validated here rather than trusted from a CDDL-generated shadow schema (see tokens.cddl's own comment on why `conditions` is an opaque bstr, not a native CDDL type) -- a token from an untrusted peer must pass trilean's real schema before any of its conditions are evaluated. Explicitly annotated: trilean's PredicateNodeSchema is a deeply recursive z.lazy() type whose inferred shape is too large for tsdown's declaration-file generator to serialise (TS7056) without this. */
 const conditionsListSchema = z.array(PredicateNodeSchema);
@@ -262,7 +232,8 @@ async function verifyTokenChain(token, options) {
 		ok: false,
 		reason: "bad_signature"
 	};
-	if (!bytesEqual(await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]), claims.issuer)) return {
+	const derivedIssuerId = await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]);
+	if (!bytesEqual(derivedIssuerId, claims.issuer)) return {
 		ok: false,
 		reason: "wrong_issuer"
 	};
@@ -377,7 +348,8 @@ async function verifyRevocationEntry(entry, options) {
 		ok: false,
 		reason: "bad_signature"
 	};
-	if (!bytesEqual(await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]), claims.issuer)) return {
+	const derivedIssuerId = await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]);
+	if (!bytesEqual(derivedIssuerId, claims.issuer)) return {
 		ok: false,
 		reason: "wrong_issuer"
 	};
@@ -482,4 +454,4 @@ async function mintRevocationEntry(options) {
 	];
 }
 //#endregion
-export { verifyRevocationEntry as a, verifyCapabilityToken as i, mintCapabilityToken as n, scopeNarrows as o, mintRevocationEntry as r, canGrant as t };
+export { verifyRevocationEntry as a, verifyCapabilityToken as i, mintCapabilityToken as n, mintRevocationEntry as r, canGrant as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "type": "module",
   "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "repository": {
@@ -98,6 +98,10 @@
       "import": "./dist/domain/device-id.mjs",
       "require": "./dist/domain/device-id.cjs"
     },
+    "./domain/grant-candidates": {
+      "import": "./dist/domain/grant-candidates.mjs",
+      "require": "./dist/domain/grant-candidates.cjs"
+    },
     "./domain/handshake": {
       "import": "./dist/domain/handshake.mjs",
       "require": "./dist/domain/handshake.cjs"