wire-mesh-core 1.15.0 → 1.17.0

package/dist/adapters/frame-codec.d.cts

@@ -1,4 +1,4 @@
-import { E as Frame } from "../protocol-MnxTzpRP.cjs";
+import { D as Frame } from "../protocol-Dhswk7YD.cjs";
 //#region src/adapters/frame-codec.d.ts
 export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
 /** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting. */

package/dist/adapters/frame-codec.d.mts

@@ -1,4 +1,4 @@
-import { E as Frame } from "../protocol-MnxTzpRP.mjs";
+import { D as Frame } from "../protocol-Dhswk7YD.mjs";
 //#region src/adapters/frame-codec.d.ts
 export declare function messageFromFrame(frame: Frame): Uint8Array<ArrayBuffer>;
 /** A frame that fails schema validation, caught separately from a decode failure so it can be dropped without disconnecting. */

package/dist/adapters/node-identity.d.cts

@@ -1,5 +1,5 @@
-import { N as IdentityKey, b as DeviceId } from "../protocol-MnxTzpRP.cjs";
-import { t as IdentityPort } from "../identity-DkEe1465.cjs";
+import { P as IdentityKey, x as DeviceId } from "../protocol-Dhswk7YD.cjs";
+import { t as IdentityPort } from "../identity-BldV8xFj.cjs";
 import { webcrypto } from "node:crypto";
 //#region src/adapters/node-identity.d.ts
 export declare function deriveDeviceId(publicKey: Uint8Array): Promise<DeviceId>;

package/dist/adapters/node-identity.d.mts

@@ -1,5 +1,5 @@
-import { N as IdentityKey, b as DeviceId } from "../protocol-MnxTzpRP.mjs";
-import { t as IdentityPort } from "../identity-D8iJZRZZ.mjs";
+import { P as IdentityKey, x as DeviceId } from "../protocol-Dhswk7YD.mjs";
+import { t as IdentityPort } from "../identity-B1hBV3YA.mjs";
 import { webcrypto } from "node:crypto";
 //#region src/adapters/node-identity.d.ts
 export declare function deriveDeviceId(publicKey: Uint8Array): Promise<DeviceId>;

package/dist/adapters/tcp-transport.d.cts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-Da7GP9ya.cjs";
+import { r as Transport } from "../transport-hEUxrdhT.cjs";
 //#region src/adapters/tcp-transport.d.ts
 /** A Node net.Socket-based Transport: length-prefixed, CBOR-encoded frames over plain TCP -- matching Cascade's own transport shape, since interop with Cascade nodes is wire-mesh's stated goal. Framing (not TLS) is this adapter's own concern; a TLS-terminated variant is a separate adapter behind the same Transport contract. */
 export declare function createTcpTransport(): Transport;

package/dist/adapters/tcp-transport.d.mts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-ESMXRz3s.mjs";
+import { r as Transport } from "../transport-BNNdUBq-.mjs";
 //#region src/adapters/tcp-transport.d.ts
 /** A Node net.Socket-based Transport: length-prefixed, CBOR-encoded frames over plain TCP -- matching Cascade's own transport shape, since interop with Cascade nodes is wire-mesh's stated goal. Framing (not TLS) is this adapter's own concern; a TLS-terminated variant is a separate adapter behind the same Transport contract. */
 export declare function createTcpTransport(): Transport;

package/dist/adapters/tls-transport.d.cts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-Da7GP9ya.cjs";
+import { r as Transport } from "../transport-hEUxrdhT.cjs";
 //#region src/adapters/tls-transport.d.ts
 export interface TlsIdentity {
   certificatePem: string;

package/dist/adapters/tls-transport.d.mts

@@ -1,4 +1,4 @@
-import { r as Transport } from "../transport-ESMXRz3s.mjs";
+import { r as Transport } from "../transport-BNNdUBq-.mjs";
 //#region src/adapters/tls-transport.d.ts
 export interface TlsIdentity {
   certificatePem: string;

package/dist/domain/capability-grant.cjs

@@ -0,0 +1,90 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_generated_protocol = require("../generated/protocol.cjs");
+const require_domain_tokens = require("./tokens.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.
+*
+* Two responsibilities, split the same way capability-request.ts already splits them: sendCapabilityGrant is the pushing side (a thin wrapper over MeshSession.sendManageRequest), and createCapabilityGrantHandler is the receiving side (validates the pushed token against all four of management.cddl's own capability-grant obligations, then hands the verified grant to the domain). Unlike capability-request's handler, there is no decide()/timeout mechanism here: management.cddl deliberately specifies no protocol-level approval round trip for this primitive (a receiver's manage-response reports validation success or failure only, never a human decision), so onGrant is a plain notification callback, not an event carrying its own responder.
+*/
+/**
+* Builds a capability-grant command per management.cddl. The outer `manage-command.verb` is the capability string itself, the identical convention capability-request.ts's own buildCapabilityRequestCommand already establishes -- a receiver's per-capability handler is how it knows which grant this push is even for. `params.verb` is the fixed "capability.grant" marker. No scope or invitee field: manage-request-frame's own top-level scope already carries the former, and the request's own destination already carries the latter -- naming either a second time inside params could only ever disagree with the fact it duplicates.
+*/
+function buildCapabilityGrantCommand(capability, grantedToken) {
+	return {
+		verb: capability,
+		params: {
+			verb: "capability.grant",
+			"granted-token": grantedToken
+		}
+	};
+}
+/**
+* Pushes an already-minted grantedToken to whichever peer this request is addressed to -- the caller mints grantedToken itself beforehand (there is no minting step here, unlike capability-request's own accept path, since this primitive carries a token the sender already decided to hand over unprompted). Resolves with the raw manage-response outcome: `{result:"ok"}` on successful validation, an ordinary manage-error otherwise (per management.cddl's own capability-grant obligations, this is a validation-failure code only, never a human "no" -- an application wanting a human-decision gate applies it on the RECEIVING side's own onGrant callback instead, exactly as core/room's own room.invite→room_invite delivery event already does today in agent-comms).
+*
+* scope and targetDevice forward directly to MeshSession.sendManageRequest's own identically-named parameters (the request's own top-level scope obligation 4 checks the token against, and relay routing respectively).
+*/
+async function sendCapabilityGrant(session, capability, grantedToken, scope, targetDevice) {
+	return session.sendManageRequest(buildCapabilityGrantCommand(capability, grantedToken), scope, targetDevice);
+}
+/**
+* Builds a reusable handler for one capability's incoming capability-grants. The returned function checks, in order: the outer verb names this handler's own capability (otherwise `{result:"error", code:"malformed"}`, matching capability-request.ts's identical check); the params payload parses against capability-grant's own CDDL shape (otherwise "malformed"); the embedded token independently passes every ordinary verifyCapabilityToken obligation with `expectedBearer` set to this receiver's OWN identity -- obligations 1 and 3 together, since an unsolicited push must name its actual recipient as bearer and must otherwise be exactly as valid as any other token (a verification failure responds with verifyCapabilityToken's own specific TokenVerdictReason as the error code, e.g. "expired"/"revoked"/"bad_signature", rather than a single generic code, mirroring how capability-request.ts already distinguishes "expired" from "malformed"); the token's own capability claim equals this handler's capability (obligation 2, otherwise "capability_mismatch"); and the token's own scope equals or roots the enclosing request's own top-level scope (obligation 4, via tokens.ts's own scopeNarrows -- otherwise "scope_mismatch"). Only once every obligation passes does it respond `{result:"ok"}` and invoke onGrant -- there is no decide()/timeout mechanism the way createCapabilityRequestHandler has one, since management.cddl specifies no protocol-level approval round trip for this primitive at all.
+*/
+function createCapabilityGrantHandler(options) {
+	return async function handleCapabilityGrant(incoming) {
+		if (incoming.command.verb !== options.capability) {
+			await incoming.respond({
+				result: "error",
+				code: "malformed"
+			});
+			return;
+		}
+		const parsed = require_generated_protocol.capabilityGrantSchema.safeParse(incoming.command.params);
+		if (!parsed.success) {
+			await incoming.respond({
+				result: "error",
+				code: "malformed"
+			});
+			return;
+		}
+		const grantedToken = parsed.data["granted-token"];
+		const verdict = await require_domain_tokens.verifyCapabilityToken(grantedToken, {
+			identity: options.identity,
+			clock: options.clock,
+			revocation: options.revocation,
+			expectedBearer: options.identity.deviceId
+		});
+		if (!verdict.ok) {
+			await incoming.respond({
+				result: "error",
+				code: verdict.reason
+			});
+			return;
+		}
+		if (verdict.claims.capability !== options.capability) {
+			await incoming.respond({
+				result: "error",
+				code: "capability_mismatch"
+			});
+			return;
+		}
+		if (!require_domain_tokens.scopeNarrows(verdict.claims.scope, incoming.scope)) {
+			await incoming.respond({
+				result: "error",
+				code: "scope_mismatch"
+			});
+			return;
+		}
+		await incoming.respond({ result: "ok" });
+		options.onGrant({
+			capability: options.capability,
+			grantedToken,
+			scope: incoming.scope,
+			granterDevice: options.granterDevice
+		});
+	};
+}
+//#endregion
+exports.buildCapabilityGrantCommand = buildCapabilityGrantCommand;
+exports.createCapabilityGrantHandler = createCapabilityGrantHandler;
+exports.sendCapabilityGrant = sendCapabilityGrant;

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

@@ -0,0 +1,44 @@
+import { F as ManageCommand, o as CapabilityScope, s as CapabilityToken, x as DeviceId } from "../protocol-Dhswk7YD.cjs";
+import { t as IdentityPort } from "../identity-BldV8xFj.cjs";
+import { t as Clock } from "../clock-DiSx-WKM.cjs";
+import { IncomingManageRequest, ManageOutcome, MeshSession } from "./mesh-session.cjs";
+import { RevocationCheck } from "./tokens.cjs";
+//#region src/domain/capability-grant.d.ts
+/**
+ * Builds a capability-grant command per management.cddl. The outer `manage-command.verb` is the capability string itself, the identical convention capability-request.ts's own buildCapabilityRequestCommand already establishes -- a receiver's per-capability handler is how it knows which grant this push is even for. `params.verb` is the fixed "capability.grant" marker. No scope or invitee field: manage-request-frame's own top-level scope already carries the former, and the request's own destination already carries the latter -- naming either a second time inside params could only ever disagree with the fact it duplicates.
+ */
+export declare function buildCapabilityGrantCommand(capability: string, grantedToken: CapabilityToken): ManageCommand;
+/**
+ * Pushes an already-minted grantedToken to whichever peer this request is addressed to -- the caller mints grantedToken itself beforehand (there is no minting step here, unlike capability-request's own accept path, since this primitive carries a token the sender already decided to hand over unprompted). Resolves with the raw manage-response outcome: `{result:"ok"}` on successful validation, an ordinary manage-error otherwise (per management.cddl's own capability-grant obligations, this is a validation-failure code only, never a human "no" -- an application wanting a human-decision gate applies it on the RECEIVING side's own onGrant callback instead, exactly as core/room's own room.invite→room_invite delivery event already does today in agent-comms).
+ *
+ * scope and targetDevice forward directly to MeshSession.sendManageRequest's own identically-named parameters (the request's own top-level scope obligation 4 checks the token against, and relay routing respectively).
+ */
+export declare function sendCapabilityGrant(session: Readonly<MeshSession>, capability: string, grantedToken: CapabilityToken, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId): Promise<ManageOutcome>;
+/** One incoming, fully-verified capability-grant, surfaced for the domain to react to (store the token, notify a human, etc.) -- there is no decide() here because management.cddl specifies no protocol-level approval round trip for this primitive; by the time onGrant fires, the wire response has already been sent. */
+export interface CapabilityGrantEvent {
+  /** The capability granted -- equals both the outer manage-command.verb and the verified token's own capability claim (obligation 2 already enforced this before onGrant fires). */
+  capability: string;
+  /** The pushed token, already confirmed to independently pass every ordinary verifyCapabilityToken obligation, name this receiver as its own bearer, and scope-match the enclosing request (obligations 1, 2, 3, and 4 respectively). Ready to use exactly as capability-request.ts's own CapabilityGrantOk["granted-token"] is on the pull side. */
+  grantedToken: CapabilityToken;
+  /** The scope this grant's own manage-request-frame carried -- e.g. core/room's `{kind:"room", path: roomPath}` -- passed through unchanged so the domain can inspect it (a room handler reads `.path` back out) without this module needing to know its shape. */
+  scope: Readonly<CapabilityScope>;
+  /** The peer device-id authenticated on the connection this grant arrived on -- the granter, surfaced so the domain can attribute the push (e.g. core/room's own room_invite event names the inviter). Never itself checked against the token's bearer (obligation 1 checks the RECIPIENT's own identity instead -- an unsolicited push names its own recipient by where it was sent, not by who sent it). */
+  granterDevice: DeviceId;
+}
+export interface CreateCapabilityGrantHandlerOptions {
+  /** The capability this handler accepts pushed grants for. Checked against the incoming command's own outer verb (a mismatch is refused as malformed, mirroring capability-request.ts's identical capability check) and against the verified token's own capability claim (obligation 2); a caller wanting to accept grants for several distinct capabilities over one session constructs one handler per capability, the same way core/room constructs one handler for `room:member` and nothing else. */
+  capability: string;
+  /** This receiver's own identity -- both the verification primitives every pushed token is checked with, and (via `.deviceId`) the value obligation 1 requires the token's own bearer to equal. There is no separate bearerDevice option the way CreateCapabilityRequestHandlerOptions has one: capability-request's handler mints a NEW token for whichever peer asked, so it needs that peer's device-id as an input; capability-grant's handler verifies an ALREADY-minted token against this side's own identity, which identity.deviceId already provides. */
+  identity: IdentityPort;
+  clock: Clock;
+  revocation: RevocationCheck;
+  /** The peer device-id authenticated on this session's own connection -- the granter, surfaced on every CapabilityGrantEvent so the domain can attribute the push. Never used for verification itself (see CapabilityGrantEvent.granterDevice's own doc comment on why obligation 1 checks the recipient's identity instead). */
+  granterDevice: DeviceId;
+  /** Called once per incoming, fully-verified capability-grant. Fires after the wire response has already been sent (see createCapabilityGrantHandler's own doc comment) -- this is a notification, not a decision point. */
+  onGrant: (event: Readonly<CapabilityGrantEvent>) => void;
+}
+/**
+ * Builds a reusable handler for one capability's incoming capability-grants. The returned function checks, in order: the outer verb names this handler's own capability (otherwise `{result:"error", code:"malformed"}`, matching capability-request.ts's identical check); the params payload parses against capability-grant's own CDDL shape (otherwise "malformed"); the embedded token independently passes every ordinary verifyCapabilityToken obligation with `expectedBearer` set to this receiver's OWN identity -- obligations 1 and 3 together, since an unsolicited push must name its actual recipient as bearer and must otherwise be exactly as valid as any other token (a verification failure responds with verifyCapabilityToken's own specific TokenVerdictReason as the error code, e.g. "expired"/"revoked"/"bad_signature", rather than a single generic code, mirroring how capability-request.ts already distinguishes "expired" from "malformed"); the token's own capability claim equals this handler's capability (obligation 2, otherwise "capability_mismatch"); and the token's own scope equals or roots the enclosing request's own top-level scope (obligation 4, via tokens.ts's own scopeNarrows -- otherwise "scope_mismatch"). Only once every obligation passes does it respond `{result:"ok"}` and invoke onGrant -- there is no decide()/timeout mechanism the way createCapabilityRequestHandler has one, since management.cddl specifies no protocol-level approval round trip for this primitive at all.
+ */
+export declare function createCapabilityGrantHandler(options: Readonly<CreateCapabilityGrantHandlerOptions>): (incoming: Readonly<IncomingManageRequest>) => Promise<void>;
+//#endregion

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

@@ -0,0 +1,44 @@
+import { F as ManageCommand, o as CapabilityScope, s as CapabilityToken, x as DeviceId } from "../protocol-Dhswk7YD.mjs";
+import { t as IdentityPort } from "../identity-B1hBV3YA.mjs";
+import { t as Clock } from "../clock-DiSx-WKM.mjs";
+import { IncomingManageRequest, ManageOutcome, MeshSession } from "./mesh-session.mjs";
+import { RevocationCheck } from "./tokens.mjs";
+//#region src/domain/capability-grant.d.ts
+/**
+ * Builds a capability-grant command per management.cddl. The outer `manage-command.verb` is the capability string itself, the identical convention capability-request.ts's own buildCapabilityRequestCommand already establishes -- a receiver's per-capability handler is how it knows which grant this push is even for. `params.verb` is the fixed "capability.grant" marker. No scope or invitee field: manage-request-frame's own top-level scope already carries the former, and the request's own destination already carries the latter -- naming either a second time inside params could only ever disagree with the fact it duplicates.
+ */
+export declare function buildCapabilityGrantCommand(capability: string, grantedToken: CapabilityToken): ManageCommand;
+/**
+ * Pushes an already-minted grantedToken to whichever peer this request is addressed to -- the caller mints grantedToken itself beforehand (there is no minting step here, unlike capability-request's own accept path, since this primitive carries a token the sender already decided to hand over unprompted). Resolves with the raw manage-response outcome: `{result:"ok"}` on successful validation, an ordinary manage-error otherwise (per management.cddl's own capability-grant obligations, this is a validation-failure code only, never a human "no" -- an application wanting a human-decision gate applies it on the RECEIVING side's own onGrant callback instead, exactly as core/room's own room.invite→room_invite delivery event already does today in agent-comms).
+ *
+ * scope and targetDevice forward directly to MeshSession.sendManageRequest's own identically-named parameters (the request's own top-level scope obligation 4 checks the token against, and relay routing respectively).
+ */
+export declare function sendCapabilityGrant(session: Readonly<MeshSession>, capability: string, grantedToken: CapabilityToken, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId): Promise<ManageOutcome>;
+/** One incoming, fully-verified capability-grant, surfaced for the domain to react to (store the token, notify a human, etc.) -- there is no decide() here because management.cddl specifies no protocol-level approval round trip for this primitive; by the time onGrant fires, the wire response has already been sent. */
+export interface CapabilityGrantEvent {
+  /** The capability granted -- equals both the outer manage-command.verb and the verified token's own capability claim (obligation 2 already enforced this before onGrant fires). */
+  capability: string;
+  /** The pushed token, already confirmed to independently pass every ordinary verifyCapabilityToken obligation, name this receiver as its own bearer, and scope-match the enclosing request (obligations 1, 2, 3, and 4 respectively). Ready to use exactly as capability-request.ts's own CapabilityGrantOk["granted-token"] is on the pull side. */
+  grantedToken: CapabilityToken;
+  /** The scope this grant's own manage-request-frame carried -- e.g. core/room's `{kind:"room", path: roomPath}` -- passed through unchanged so the domain can inspect it (a room handler reads `.path` back out) without this module needing to know its shape. */
+  scope: Readonly<CapabilityScope>;
+  /** The peer device-id authenticated on the connection this grant arrived on -- the granter, surfaced so the domain can attribute the push (e.g. core/room's own room_invite event names the inviter). Never itself checked against the token's bearer (obligation 1 checks the RECIPIENT's own identity instead -- an unsolicited push names its own recipient by where it was sent, not by who sent it). */
+  granterDevice: DeviceId;
+}
+export interface CreateCapabilityGrantHandlerOptions {
+  /** The capability this handler accepts pushed grants for. Checked against the incoming command's own outer verb (a mismatch is refused as malformed, mirroring capability-request.ts's identical capability check) and against the verified token's own capability claim (obligation 2); a caller wanting to accept grants for several distinct capabilities over one session constructs one handler per capability, the same way core/room constructs one handler for `room:member` and nothing else. */
+  capability: string;
+  /** This receiver's own identity -- both the verification primitives every pushed token is checked with, and (via `.deviceId`) the value obligation 1 requires the token's own bearer to equal. There is no separate bearerDevice option the way CreateCapabilityRequestHandlerOptions has one: capability-request's handler mints a NEW token for whichever peer asked, so it needs that peer's device-id as an input; capability-grant's handler verifies an ALREADY-minted token against this side's own identity, which identity.deviceId already provides. */
+  identity: IdentityPort;
+  clock: Clock;
+  revocation: RevocationCheck;
+  /** The peer device-id authenticated on this session's own connection -- the granter, surfaced on every CapabilityGrantEvent so the domain can attribute the push. Never used for verification itself (see CapabilityGrantEvent.granterDevice's own doc comment on why obligation 1 checks the recipient's identity instead). */
+  granterDevice: DeviceId;
+  /** Called once per incoming, fully-verified capability-grant. Fires after the wire response has already been sent (see createCapabilityGrantHandler's own doc comment) -- this is a notification, not a decision point. */
+  onGrant: (event: Readonly<CapabilityGrantEvent>) => void;
+}
+/**
+ * Builds a reusable handler for one capability's incoming capability-grants. The returned function checks, in order: the outer verb names this handler's own capability (otherwise `{result:"error", code:"malformed"}`, matching capability-request.ts's identical check); the params payload parses against capability-grant's own CDDL shape (otherwise "malformed"); the embedded token independently passes every ordinary verifyCapabilityToken obligation with `expectedBearer` set to this receiver's OWN identity -- obligations 1 and 3 together, since an unsolicited push must name its actual recipient as bearer and must otherwise be exactly as valid as any other token (a verification failure responds with verifyCapabilityToken's own specific TokenVerdictReason as the error code, e.g. "expired"/"revoked"/"bad_signature", rather than a single generic code, mirroring how capability-request.ts already distinguishes "expired" from "malformed"); the token's own capability claim equals this handler's capability (obligation 2, otherwise "capability_mismatch"); and the token's own scope equals or roots the enclosing request's own top-level scope (obligation 4, via tokens.ts's own scopeNarrows -- otherwise "scope_mismatch"). Only once every obligation passes does it respond `{result:"ok"}` and invoke onGrant -- there is no decide()/timeout mechanism the way createCapabilityRequestHandler has one, since management.cddl specifies no protocol-level approval round trip for this primitive at all.
+ */
+export declare function createCapabilityGrantHandler(options: Readonly<CreateCapabilityGrantHandlerOptions>): (incoming: Readonly<IncomingManageRequest>) => Promise<void>;
+//#endregion

package/dist/domain/capability-grant.mjs

@@ -0,0 +1,87 @@
+import { capabilityGrantSchema } from "../generated/protocol.mjs";
+import { scopeNarrows, verifyCapabilityToken } from "./tokens.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.
+*
+* Two responsibilities, split the same way capability-request.ts already splits them: sendCapabilityGrant is the pushing side (a thin wrapper over MeshSession.sendManageRequest), and createCapabilityGrantHandler is the receiving side (validates the pushed token against all four of management.cddl's own capability-grant obligations, then hands the verified grant to the domain). Unlike capability-request's handler, there is no decide()/timeout mechanism here: management.cddl deliberately specifies no protocol-level approval round trip for this primitive (a receiver's manage-response reports validation success or failure only, never a human decision), so onGrant is a plain notification callback, not an event carrying its own responder.
+*/
+/**
+* Builds a capability-grant command per management.cddl. The outer `manage-command.verb` is the capability string itself, the identical convention capability-request.ts's own buildCapabilityRequestCommand already establishes -- a receiver's per-capability handler is how it knows which grant this push is even for. `params.verb` is the fixed "capability.grant" marker. No scope or invitee field: manage-request-frame's own top-level scope already carries the former, and the request's own destination already carries the latter -- naming either a second time inside params could only ever disagree with the fact it duplicates.
+*/
+function buildCapabilityGrantCommand(capability, grantedToken) {
+	return {
+		verb: capability,
+		params: {
+			verb: "capability.grant",
+			"granted-token": grantedToken
+		}
+	};
+}
+/**
+* Pushes an already-minted grantedToken to whichever peer this request is addressed to -- the caller mints grantedToken itself beforehand (there is no minting step here, unlike capability-request's own accept path, since this primitive carries a token the sender already decided to hand over unprompted). Resolves with the raw manage-response outcome: `{result:"ok"}` on successful validation, an ordinary manage-error otherwise (per management.cddl's own capability-grant obligations, this is a validation-failure code only, never a human "no" -- an application wanting a human-decision gate applies it on the RECEIVING side's own onGrant callback instead, exactly as core/room's own room.invite→room_invite delivery event already does today in agent-comms).
+*
+* scope and targetDevice forward directly to MeshSession.sendManageRequest's own identically-named parameters (the request's own top-level scope obligation 4 checks the token against, and relay routing respectively).
+*/
+async function sendCapabilityGrant(session, capability, grantedToken, scope, targetDevice) {
+	return session.sendManageRequest(buildCapabilityGrantCommand(capability, grantedToken), scope, targetDevice);
+}
+/**
+* Builds a reusable handler for one capability's incoming capability-grants. The returned function checks, in order: the outer verb names this handler's own capability (otherwise `{result:"error", code:"malformed"}`, matching capability-request.ts's identical check); the params payload parses against capability-grant's own CDDL shape (otherwise "malformed"); the embedded token independently passes every ordinary verifyCapabilityToken obligation with `expectedBearer` set to this receiver's OWN identity -- obligations 1 and 3 together, since an unsolicited push must name its actual recipient as bearer and must otherwise be exactly as valid as any other token (a verification failure responds with verifyCapabilityToken's own specific TokenVerdictReason as the error code, e.g. "expired"/"revoked"/"bad_signature", rather than a single generic code, mirroring how capability-request.ts already distinguishes "expired" from "malformed"); the token's own capability claim equals this handler's capability (obligation 2, otherwise "capability_mismatch"); and the token's own scope equals or roots the enclosing request's own top-level scope (obligation 4, via tokens.ts's own scopeNarrows -- otherwise "scope_mismatch"). Only once every obligation passes does it respond `{result:"ok"}` and invoke onGrant -- there is no decide()/timeout mechanism the way createCapabilityRequestHandler has one, since management.cddl specifies no protocol-level approval round trip for this primitive at all.
+*/
+function createCapabilityGrantHandler(options) {
+	return async function handleCapabilityGrant(incoming) {
+		if (incoming.command.verb !== options.capability) {
+			await incoming.respond({
+				result: "error",
+				code: "malformed"
+			});
+			return;
+		}
+		const parsed = capabilityGrantSchema.safeParse(incoming.command.params);
+		if (!parsed.success) {
+			await incoming.respond({
+				result: "error",
+				code: "malformed"
+			});
+			return;
+		}
+		const grantedToken = parsed.data["granted-token"];
+		const verdict = await verifyCapabilityToken(grantedToken, {
+			identity: options.identity,
+			clock: options.clock,
+			revocation: options.revocation,
+			expectedBearer: options.identity.deviceId
+		});
+		if (!verdict.ok) {
+			await incoming.respond({
+				result: "error",
+				code: verdict.reason
+			});
+			return;
+		}
+		if (verdict.claims.capability !== options.capability) {
+			await incoming.respond({
+				result: "error",
+				code: "capability_mismatch"
+			});
+			return;
+		}
+		if (!scopeNarrows(verdict.claims.scope, incoming.scope)) {
+			await incoming.respond({
+				result: "error",
+				code: "scope_mismatch"
+			});
+			return;
+		}
+		await incoming.respond({ result: "ok" });
+		options.onGrant({
+			capability: options.capability,
+			grantedToken,
+			scope: incoming.scope,
+			granterDevice: options.granterDevice
+		});
+	};
+}
+//#endregion
+export { buildCapabilityGrantCommand, createCapabilityGrantHandler, sendCapabilityGrant };

package/dist/domain/capability-request.d.cts

@@ -1,5 +1,5 @@
-import { P as ManageCommand, a as CapabilityScope, b as DeviceId, r as CapabilityGrantOk } from "../protocol-MnxTzpRP.cjs";
-import { t as IdentityPort } from "../identity-DkEe1465.cjs";
+import { F as ManageCommand, i as CapabilityGrantOk, o as CapabilityScope, x as DeviceId } from "../protocol-Dhswk7YD.cjs";
+import { t as IdentityPort } from "../identity-BldV8xFj.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.cjs";
 //#region src/domain/capability-request.d.ts

package/dist/domain/capability-request.d.mts

@@ -1,5 +1,5 @@
-import { P as ManageCommand, a as CapabilityScope, b as DeviceId, r as CapabilityGrantOk } from "../protocol-MnxTzpRP.mjs";
-import { t as IdentityPort } from "../identity-D8iJZRZZ.mjs";
+import { F as ManageCommand, i as CapabilityGrantOk, o as CapabilityScope, x as DeviceId } from "../protocol-Dhswk7YD.mjs";
+import { t as IdentityPort } from "../identity-B1hBV3YA.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
 import { IncomingManageRequest, MeshSession } from "./mesh-session.mjs";
 //#region src/domain/capability-request.d.ts

package/dist/domain/device-id.d.cts

@@ -1,4 +1,4 @@
-import { b as DeviceId } from "../protocol-MnxTzpRP.cjs";
+import { x as DeviceId } from "../protocol-Dhswk7YD.cjs";
 //#region src/domain/device-id.d.ts
 /** Lowercase, byte-exact hex for an arbitrary-length byte string -- the same encoding convention deviceIdToHex uses for the fixed-length device-id case, extracted so any other byte string needing a stable, displayable, map-keyable text form (e.g. a token-id, which tokens.cddl defines as an arbitrary-length bstr rather than a 32-byte device-id) can use the identical convention without going through a device-id-shaped function. */
 export declare function bytesToHex(bytes: Uint8Array): string;

package/dist/domain/device-id.d.mts

@@ -1,4 +1,4 @@
-import { b as DeviceId } from "../protocol-MnxTzpRP.mjs";
+import { x as DeviceId } from "../protocol-Dhswk7YD.mjs";
 //#region src/domain/device-id.d.ts
 /** Lowercase, byte-exact hex for an arbitrary-length byte string -- the same encoding convention deviceIdToHex uses for the fixed-length device-id case, extracted so any other byte string needing a stable, displayable, map-keyable text form (e.g. a token-id, which tokens.cddl defines as an arbitrary-length bstr rather than a 32-byte device-id) can use the identical convention without going through a device-id-shaped function. */
 export declare function bytesToHex(bytes: Uint8Array): string;

package/dist/domain/handshake.d.cts

@@ -1,4 +1,4 @@
-import { $ as ProtocolVersion, C as DomainId, j as HandshakeFrame } from "../protocol-MnxTzpRP.cjs";
+import { M as HandshakeFrame, et as ProtocolVersion, w as DomainId } from "../protocol-Dhswk7YD.cjs";
 //#region src/domain/handshake.d.ts
 /** The highest protocol version this build of core understands. */
 export declare const SUPPORTED_PROTOCOL_VERSION: ProtocolVersion;

package/dist/domain/handshake.d.mts

@@ -1,4 +1,4 @@
-import { $ as ProtocolVersion, C as DomainId, j as HandshakeFrame } from "../protocol-MnxTzpRP.mjs";
+import { M as HandshakeFrame, et as ProtocolVersion, w as DomainId } from "../protocol-Dhswk7YD.mjs";
 //#region src/domain/handshake.d.ts
 /** The highest protocol version this build of core understands. */
 export declare const SUPPORTED_PROTOCOL_VERSION: ProtocolVersion;

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

@@ -1,7 +1,7 @@
-import { $ as ProtocolVersion, E as Frame, G as PeerAdvert, I as ManageError, L as ManageOk, P as ManageCommand, a as CapabilityScope, b as DeviceId, o as CapabilityToken, ut as RevocationEntry } from "../protocol-MnxTzpRP.cjs";
-import { t as IdentityPort } from "../identity-DkEe1465.cjs";
+import { D as Frame, F as ManageCommand, K as PeerAdvert, L as ManageError, R as ManageOk, dt as RevocationEntry, et as ProtocolVersion, o as CapabilityScope, s as CapabilityToken, x as DeviceId } from "../protocol-Dhswk7YD.cjs";
+import { t as IdentityPort } from "../identity-BldV8xFj.cjs";
 import { t as Clock } from "../clock-DiSx-WKM.cjs";
-import { r as Transport, t as Connection } from "../transport-Da7GP9ya.cjs";
+import { r as Transport, t as Connection } from "../transport-hEUxrdhT.cjs";
 //#region src/domain/mesh-session.d.ts
 /** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
 export declare const HANDSHAKE_TIMEOUT_MS = 3000;

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

@@ -1,7 +1,7 @@
-import { $ as ProtocolVersion, E as Frame, G as PeerAdvert, I as ManageError, L as ManageOk, P as ManageCommand, a as CapabilityScope, b as DeviceId, o as CapabilityToken, ut as RevocationEntry } from "../protocol-MnxTzpRP.mjs";
-import { t as IdentityPort } from "../identity-D8iJZRZZ.mjs";
+import { D as Frame, F as ManageCommand, K as PeerAdvert, L as ManageError, R as ManageOk, dt as RevocationEntry, et as ProtocolVersion, o as CapabilityScope, s as CapabilityToken, x as DeviceId } from "../protocol-Dhswk7YD.mjs";
+import { t as IdentityPort } from "../identity-B1hBV3YA.mjs";
 import { t as Clock } from "../clock-DiSx-WKM.mjs";
-import { r as Transport, t as Connection } from "../transport-ESMXRz3s.mjs";
+import { r as Transport, t as Connection } from "../transport-BNNdUBq-.mjs";
 //#region src/domain/mesh-session.d.ts
 /** How long to wait for the node's handshake before calling it unanswered. A relay-only node never sends one; that is a state to display, not an error. */
 export declare const HANDSHAKE_TIMEOUT_MS = 3000;

package/dist/domain/relay-hub.cjs

@@ -8,6 +8,7 @@ function deviceKey(device) {
 	return key;
 }
 function createRelayHub() {
+	const connections = /* @__PURE__ */ new Set();
 	const devices = /* @__PURE__ */ new Map();
 	const connectionDevice = /* @__PURE__ */ new Map();
 	const pairings = /* @__PURE__ */ new Map();
@@ -26,6 +27,7 @@ function createRelayHub() {
 		mostRecentPairing.set(b, a);
 	}
 	function forgetConnection(connection) {
+		connections.delete(connection);
 		for (const [key, registration] of devices) if (registration.connection === connection) devices.delete(key);
 		const ownDevice = connectionDevice.get(connection);
 		connectionDevice.delete(connection);
@@ -44,12 +46,26 @@ function createRelayHub() {
 		if (frame.type === "gossip") {
 			for (const advert of frame.peers) devices.set(deviceKey(advert.device), {
 				connection,
-				device: advert.device
+				advert
 			});
 			for (const registration of devices.values()) if (registration.connection === connection) {
-				connectionDevice.set(connection, registration.device);
+				connectionDevice.set(connection, registration.advert.device);
 				break;
 			}
+			for (const other of connections) {
+				if (other === connection) continue;
+				try {
+					await other.send(frame);
+				} catch {}
+			}
+			const catchUp = [];
+			for (const registration of devices.values()) if (registration.connection !== connection) catchUp.push(registration.advert);
+			if (catchUp.length > 0) try {
+				await connection.send({
+					type: "gossip",
+					peers: catchUp
+				});
+			} catch {}
 			return;
 		}
 		if (frame.type === "relay-connect") {
@@ -57,7 +73,7 @@ function createRelayHub() {
 			if (!registration || registration.connection === connection) return;
 			const initiatorDevice = connectionDevice.get(connection);
 			if (initiatorDevice === void 0) return;
-			addPairing(connection, initiatorDevice, registration.connection, registration.device);
+			addPairing(connection, initiatorDevice, registration.connection, registration.advert.device);
 			await registration.connection.send({
 				type: "relay-inbound",
 				"source-device": initiatorDevice
@@ -81,6 +97,7 @@ function createRelayHub() {
 	}
 	return {
 		async handleConnection(connection) {
+			connections.add(connection);
 			try {
 				for await (const frame of connection.receive()) await handleFrame(connection, frame);
 			} catch {} finally {
@@ -88,6 +105,7 @@ function createRelayHub() {
 			}
 		},
 		stop() {
+			connections.clear();
 			devices.clear();
 			connectionDevice.clear();
 			pairings.clear();

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

@@ -1,7 +1,7 @@
-import { t as Connection } from "../transport-Da7GP9ya.cjs";
+import { t as Connection } from "../transport-hEUxrdhT.cjs";
 //#region src/domain/relay-hub.d.ts
 export interface RelayHub {
-  /** Drives one accepted connection until it closes: registers gossip-advertised devices, 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. */
   handleConnection: (connection: Readonly<Connection>) => Promise<void>;
   /** Drops all registry and pairing state -- used by tests and by transport teardown. */
   stop: () => void;

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

@@ -1,7 +1,7 @@
-import { t as Connection } from "../transport-ESMXRz3s.mjs";
+import { t as Connection } from "../transport-BNNdUBq-.mjs";
 //#region src/domain/relay-hub.d.ts
 export interface RelayHub {
-  /** Drives one accepted connection until it closes: registers gossip-advertised devices, 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. */
   handleConnection: (connection: Readonly<Connection>) => Promise<void>;
   /** Drops all registry and pairing state -- used by tests and by transport teardown. */
   stop: () => void;

package/dist/domain/relay-hub.mjs

@@ -7,6 +7,7 @@ function deviceKey(device) {
 	return key;
 }
 function createRelayHub() {
+	const connections = /* @__PURE__ */ new Set();
 	const devices = /* @__PURE__ */ new Map();
 	const connectionDevice = /* @__PURE__ */ new Map();
 	const pairings = /* @__PURE__ */ new Map();
@@ -25,6 +26,7 @@ function createRelayHub() {
 		mostRecentPairing.set(b, a);
 	}
 	function forgetConnection(connection) {
+		connections.delete(connection);
 		for (const [key, registration] of devices) if (registration.connection === connection) devices.delete(key);
 		const ownDevice = connectionDevice.get(connection);
 		connectionDevice.delete(connection);
@@ -43,12 +45,26 @@ function createRelayHub() {
 		if (frame.type === "gossip") {
 			for (const advert of frame.peers) devices.set(deviceKey(advert.device), {
 				connection,
-				device: advert.device
+				advert
 			});
 			for (const registration of devices.values()) if (registration.connection === connection) {
-				connectionDevice.set(connection, registration.device);
+				connectionDevice.set(connection, registration.advert.device);
 				break;
 			}
+			for (const other of connections) {
+				if (other === connection) continue;
+				try {
+					await other.send(frame);
+				} catch {}
+			}
+			const catchUp = [];
+			for (const registration of devices.values()) if (registration.connection !== connection) catchUp.push(registration.advert);
+			if (catchUp.length > 0) try {
+				await connection.send({
+					type: "gossip",
+					peers: catchUp
+				});
+			} catch {}
 			return;
 		}
 		if (frame.type === "relay-connect") {
@@ -56,7 +72,7 @@ function createRelayHub() {
 			if (!registration || registration.connection === connection) return;
 			const initiatorDevice = connectionDevice.get(connection);
 			if (initiatorDevice === void 0) return;
-			addPairing(connection, initiatorDevice, registration.connection, registration.device);
+			addPairing(connection, initiatorDevice, registration.connection, registration.advert.device);
 			await registration.connection.send({
 				type: "relay-inbound",
 				"source-device": initiatorDevice
@@ -80,6 +96,7 @@ function createRelayHub() {
 	}
 	return {
 		async handleConnection(connection) {
+			connections.add(connection);
 			try {
 				for await (const frame of connection.receive()) await handleFrame(connection, frame);
 			} catch {} finally {
@@ -87,6 +104,7 @@ function createRelayHub() {
 			}
 		},
 		stop() {
+			connections.clear();
 			devices.clear();
 			connectionDevice.clear();
 			pairings.clear();

package/dist/domain/revocation-view.d.cts

@@ -1,4 +1,4 @@
-import { ut as RevocationEntry } from "../protocol-MnxTzpRP.cjs";
+import { dt as RevocationEntry } from "../protocol-Dhswk7YD.cjs";
 import { RevocationCheck, RevocationEntryVerdict, VerifyRevocationEntryOptions } from "./tokens.cjs";
 //#region src/domain/revocation-view.d.ts
 /**

package/dist/domain/revocation-view.d.mts

@@ -1,4 +1,4 @@
-import { ut as RevocationEntry } from "../protocol-MnxTzpRP.mjs";
+import { dt as RevocationEntry } from "../protocol-Dhswk7YD.mjs";
 import { RevocationCheck, RevocationEntryVerdict, VerifyRevocationEntryOptions } from "./tokens.mjs";
 //#region src/domain/revocation-view.d.ts
 /**

package/dist/domain/room-token-verification.d.cts

@@ -1,4 +1,4 @@
-import { Ot as TokenClaims, b as DeviceId, o as CapabilityToken } from "../protocol-MnxTzpRP.cjs";
+import { kt as TokenClaims, s as CapabilityToken, x as DeviceId } from "../protocol-Dhswk7YD.cjs";
 import { TokenVerdictReason, VerifyCapabilityTokenOptions } from "./tokens.cjs";
 //#region src/domain/room-token-verification.d.ts
 /** The one capability every core/room verb (room.send/read/leave/members) is gated by, per spec/room.cddl -- room.join/room.invite are deliberately ungated instead and need no token check at all. */

package/dist/domain/room-token-verification.d.mts

@@ -1,4 +1,4 @@
-import { Ot as TokenClaims, b as DeviceId, o as CapabilityToken } from "../protocol-MnxTzpRP.mjs";
+import { kt as TokenClaims, s as CapabilityToken, x as DeviceId } from "../protocol-Dhswk7YD.mjs";
 import { TokenVerdictReason, VerifyCapabilityTokenOptions } from "./tokens.mjs";
 //#region src/domain/room-token-verification.d.ts
 /** The one capability every core/room verb (room.send/read/leave/members) is gated by, per spec/room.cddl -- room.join/room.invite are deliberately ungated instead and need no token check at all. */