wire-mesh-core 1.8.0 → 1.10.0

package/dist/domain/mesh-session.cjs

@@ -357,12 +357,13 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			setToken(token) {
 				currentToken = token;
 			},
-			async sendManageRequest(command, scope, targetDevice, token) {
+			async sendManageRequest(command, scope, targetDevice, token, timeoutMs) {
 				if (connection === null || state.status !== "connected") throw new Error("not connected");
 				if (targetDevice !== void 0) await ensureRelayPairing(targetDevice);
 				const frame = buildManageRequest(command, scope, token);
+				const requestId = frame["request-id"];
 				const outcome = new Promise((resolve, reject) => {
-					pendingManageRequests.set(frame["request-id"], {
+					pendingManageRequests.set(requestId, {
 						resolve,
 						reject
 					});
@@ -373,7 +374,15 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				});
 				await transmit(frame, targetDevice !== void 0);
 				emit();
-				return outcome;
+				if (timeoutMs === void 0) return outcome;
+				return Promise.race([outcome, new Promise((resolve) => {
+					setTimeout(() => {
+						if (pendingManageRequests.delete(requestId)) resolve({
+							result: "error",
+							code: "timeout"
+						});
+					}, timeoutMs);
+				})]);
 			},
 			async sendRevocationAnnounce(entries) {
 				if (connection === null || state.status !== "connected") throw new Error("not connected");

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

@@ -81,8 +81,8 @@ export interface MeshSession {
   setToken: (token: CapabilityToken) => void;
   /** Announces one or more already-minted revocation-entries to the peer. Sent directly over the connection, never relay-wrapped -- revocation-announce is a gossiped broadcast, not a request addressed to a specific peer, so it has no targetDevice/token parameters the way sendManageRequest does. */
   sendRevocationAnnounce: (entries: readonly RevocationEntry[]) => Promise<void>;
-  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. */
-  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken) => Promise<ManageOutcome>;
+  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. When timeoutMs is given, the returned promise resolves with `{ result: "error", code: "timeout" }` rather than hanging forever if no manage-response arrives in time -- a held-open request (a human approval, a not-yet-online peer) otherwise has no way for the caller to give up on it. Absent, this request waits exactly as before, with no time limit of its own. */
+  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken, timeoutMs?: number) => Promise<ManageOutcome>;
   close: () => Promise<void>;
 }
 export declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null,

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

@@ -81,8 +81,8 @@ export interface MeshSession {
   setToken: (token: CapabilityToken) => void;
   /** Announces one or more already-minted revocation-entries to the peer. Sent directly over the connection, never relay-wrapped -- revocation-announce is a gossiped broadcast, not a request addressed to a specific peer, so it has no targetDevice/token parameters the way sendManageRequest does. */
   sendRevocationAnnounce: (entries: readonly RevocationEntry[]) => Promise<void>;
-  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. */
-  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken) => Promise<ManageOutcome>;
+  /** Sends a manage-request and resolves with the matching manage-response's outcome, correlated by request-id. When targetDevice is given, the request is routed to that specific peer via an established relay-connect pairing (wrapped as relay-data) rather than sent directly over this session's own Connection -- relay-hub deliberately drops manage-request/manage-response frames sent to it directly, since routing between two connected peers is not the relay role's business, so a specific peer reachable only through a relay hub can only be addressed this way. Absent, this sends directly over the Connection exactly as before. When token is given, it is attached to this one request instead of whatever setToken last set -- a single session routinely needs a different token per request when its peer shares more than one scope with this side (e.g. several core/room memberships over one connection), and a session-global token can only ever be correct for one of them. Absent, this request carries setToken's own session-global token exactly as before. When timeoutMs is given, the returned promise resolves with `{ result: "error", code: "timeout" }` rather than hanging forever if no manage-response arrives in time -- a held-open request (a human approval, a not-yet-online peer) otherwise has no way for the caller to give up on it. Absent, this request waits exactly as before, with no time limit of its own. */
+  sendManageRequest: (command: ManageCommand, scope: Readonly<CapabilityScope>, targetDevice?: DeviceId, token?: CapabilityToken, timeoutMs?: number) => Promise<ManageOutcome>;
   close: () => Promise<void>;
 }
 export declare function createMeshSession(transport: Readonly<Transport>, identity: Readonly<IdentityPort>, clock?: Readonly<Clock>, reconnect?: ReconnectPolicy | null,

package/dist/domain/mesh-session.mjs

@@ -356,12 +356,13 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 			setToken(token) {
 				currentToken = token;
 			},
-			async sendManageRequest(command, scope, targetDevice, token) {
+			async sendManageRequest(command, scope, targetDevice, token, timeoutMs) {
 				if (connection === null || state.status !== "connected") throw new Error("not connected");
 				if (targetDevice !== void 0) await ensureRelayPairing(targetDevice);
 				const frame = buildManageRequest(command, scope, token);
+				const requestId = frame["request-id"];
 				const outcome = new Promise((resolve, reject) => {
-					pendingManageRequests.set(frame["request-id"], {
+					pendingManageRequests.set(requestId, {
 						resolve,
 						reject
 					});
@@ -372,7 +373,15 @@ function createSessionCore(identity, clock, reconnect, dial, onPeerAdvert, addre
 				});
 				await transmit(frame, targetDevice !== void 0);
 				emit();
-				return outcome;
+				if (timeoutMs === void 0) return outcome;
+				return Promise.race([outcome, new Promise((resolve) => {
+					setTimeout(() => {
+						if (pendingManageRequests.delete(requestId)) resolve({
+							result: "error",
+							code: "timeout"
+						});
+					}, timeoutMs);
+				})]);
 			},
 			async sendRevocationAnnounce(entries) {
 				if (connection === null || state.status !== "connected") throw new Error("not connected");

package/dist/domain/tokens.cjs

@@ -214,6 +214,26 @@ async function verifyRevocationEntry(entry, options) {
 		claims
 	};
 }
+/** The narrowing arithmetic tokens.cddl's own delegation obligations require (bearer match, expiry within the parent's, scope narrows, same capability, delegations-remaining strictly less than the parent's) -- shared between mintCapabilityToken (which additionally builds and signs the resulting token) and canGrant (a pure query with no minting side effect at all), so the two can never silently drift into two different ideas of what "narrows" means. Returns the specific refusal reason, or undefined when every rule is satisfied. */
+function checkNarrowing(parentClaims, granterDeviceId, candidate) {
+	if (!bytesEqual(parentClaims.bearer, granterDeviceId)) return "parent_bearer_mismatch";
+	if (candidate.expires > parentClaims.expires) return "expires_exceeds_parent";
+	if (!scopeNarrows(parentClaims.scope, candidate.scope)) return "scope_does_not_narrow";
+	if (parentClaims.capability !== candidate.capability) return "capability_mismatch";
+	const parentRemaining = parentClaims["delegations-remaining"];
+	if (parentRemaining !== void 0 && (candidate.delegationsRemaining === void 0 || candidate.delegationsRemaining >= parentRemaining)) return "delegation_exceeds_parent";
+}
+/**
+* A pure query: could deviceId, presenting heldToken as its own delegation authority, successfully mint a delegation matching candidate right now -- without attempting (and potentially failing) a real mint just to find out. Reuses mintCapabilityToken's own narrowing arithmetic via checkNarrowing, so the two can never silently drift into different ideas of what "narrows" means.
+*
+* Deliberately narrower than a full mint attempt in one respect: this checks only the narrowing rules tokens.cddl's own delegation obligations require (bearer match, expiry, scope, capability, delegations-remaining), the same scope mintCapabilityToken itself checks a *parent* against -- it does not verify heldToken's own signature or revocation status, exactly as mintCapabilityToken never re-verifies its own parent's signature either. A caller that also needs heldToken's cryptographic validity confirmed calls verifyCapabilityToken separately.
+*/
+function canGrant(heldToken, deviceId, candidate, now) {
+	if (candidate.expires <= now) return false;
+	const heldClaims = decodeTokenClaims(heldToken);
+	if (heldClaims === void 0) return false;
+	return checkNarrowing(heldClaims, deviceId, candidate) === void 0;
+}
 /**
 * Mints one capability token: builds token-claims from the given fields, signs it as a COSE_Sign1 under `identity`'s own key, with a protected header matching what the frozen conformance vectors actually encode (`{1: alg, 4: issuer device-id}`, not the empty header a token merely needs to verify against itself).
 *
@@ -231,26 +251,15 @@ async function mintCapabilityToken(options) {
 			ok: false,
 			reason: "parent_malformed"
 		};
-		if (!bytesEqual(parentClaims.bearer, options.identity.deviceId)) return {
-			ok: false,
-			reason: "parent_bearer_mismatch"
-		};
-		if (options.expires > parentClaims.expires) return {
+		const refusal = checkNarrowing(parentClaims, options.identity.deviceId, {
+			capability: options.capability,
+			scope: options.scope,
+			expires: options.expires,
+			...options.delegationsRemaining !== void 0 ? { delegationsRemaining: options.delegationsRemaining } : {}
+		});
+		if (refusal !== void 0) return {
 			ok: false,
-			reason: "expires_exceeds_parent"
-		};
-		if (!scopeNarrows(parentClaims.scope, options.scope)) return {
-			ok: false,
-			reason: "scope_does_not_narrow"
-		};
-		if (parentClaims.capability !== options.capability) return {
-			ok: false,
-			reason: "capability_mismatch"
-		};
-		const parentRemaining = parentClaims["delegations-remaining"];
-		if (parentRemaining !== void 0 && (options.delegationsRemaining === void 0 || options.delegationsRemaining >= parentRemaining)) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
+			reason: refusal
 		};
 		parentBytes = encodeBuf(options.parent);
 	}
@@ -294,6 +303,7 @@ async function mintRevocationEntry(options) {
 	];
 }
 //#endregion
+exports.canGrant = canGrant;
 exports.mintCapabilityToken = mintCapabilityToken;
 exports.mintRevocationEntry = mintRevocationEntry;
 exports.verifyCapabilityToken = verifyCapabilityToken;

package/dist/domain/tokens.d.cts

@@ -55,6 +55,19 @@ export type MintVerdict = {
   ok: false;
   reason: MintRefusalReason;
 };
+/** What a would-be delegation needs, to check it narrows a specific parent -- everything mintCapabilityToken itself checks a delegation against, independent of the tokenId/bearer/notBefore/signing concerns unique to actually minting one. */
+interface NarrowingCandidate {
+  capability: TokenClaims["capability"];
+  scope: TokenClaims["scope"];
+  expires: number;
+  delegationsRemaining?: number;
+}
+/**
+ * A pure query: could deviceId, presenting heldToken as its own delegation authority, successfully mint a delegation matching candidate right now -- without attempting (and potentially failing) a real mint just to find out. Reuses mintCapabilityToken's own narrowing arithmetic via checkNarrowing, so the two can never silently drift into different ideas of what "narrows" means.
+ *
+ * Deliberately narrower than a full mint attempt in one respect: this checks only the narrowing rules tokens.cddl's own delegation obligations require (bearer match, expiry, scope, capability, delegations-remaining), the same scope mintCapabilityToken itself checks a *parent* against -- it does not verify heldToken's own signature or revocation status, exactly as mintCapabilityToken never re-verifies its own parent's signature either. A caller that also needs heldToken's cryptographic validity confirmed calls verifyCapabilityToken separately.
+ */
+export declare function canGrant(heldToken: CapabilityToken, deviceId: DeviceId, candidate: Readonly<NarrowingCandidate>, now: number): boolean;
 export interface MintCapabilityTokenOptions {
   /** The issuer -- signs the token, and supplies the self-certifying issuer/issuer-key claims. */
   identity: IdentityPort;

package/dist/domain/tokens.d.mts

@@ -55,6 +55,19 @@ export type MintVerdict = {
   ok: false;
   reason: MintRefusalReason;
 };
+/** What a would-be delegation needs, to check it narrows a specific parent -- everything mintCapabilityToken itself checks a delegation against, independent of the tokenId/bearer/notBefore/signing concerns unique to actually minting one. */
+interface NarrowingCandidate {
+  capability: TokenClaims["capability"];
+  scope: TokenClaims["scope"];
+  expires: number;
+  delegationsRemaining?: number;
+}
+/**
+ * A pure query: could deviceId, presenting heldToken as its own delegation authority, successfully mint a delegation matching candidate right now -- without attempting (and potentially failing) a real mint just to find out. Reuses mintCapabilityToken's own narrowing arithmetic via checkNarrowing, so the two can never silently drift into different ideas of what "narrows" means.
+ *
+ * Deliberately narrower than a full mint attempt in one respect: this checks only the narrowing rules tokens.cddl's own delegation obligations require (bearer match, expiry, scope, capability, delegations-remaining), the same scope mintCapabilityToken itself checks a *parent* against -- it does not verify heldToken's own signature or revocation status, exactly as mintCapabilityToken never re-verifies its own parent's signature either. A caller that also needs heldToken's cryptographic validity confirmed calls verifyCapabilityToken separately.
+ */
+export declare function canGrant(heldToken: CapabilityToken, deviceId: DeviceId, candidate: Readonly<NarrowingCandidate>, now: number): boolean;
 export interface MintCapabilityTokenOptions {
   /** The issuer -- signs the token, and supplies the self-certifying issuer/issuer-key claims. */
   identity: IdentityPort;

package/dist/domain/tokens.mjs

@@ -213,6 +213,26 @@ async function verifyRevocationEntry(entry, options) {
 		claims
 	};
 }
+/** The narrowing arithmetic tokens.cddl's own delegation obligations require (bearer match, expiry within the parent's, scope narrows, same capability, delegations-remaining strictly less than the parent's) -- shared between mintCapabilityToken (which additionally builds and signs the resulting token) and canGrant (a pure query with no minting side effect at all), so the two can never silently drift into two different ideas of what "narrows" means. Returns the specific refusal reason, or undefined when every rule is satisfied. */
+function checkNarrowing(parentClaims, granterDeviceId, candidate) {
+	if (!bytesEqual(parentClaims.bearer, granterDeviceId)) return "parent_bearer_mismatch";
+	if (candidate.expires > parentClaims.expires) return "expires_exceeds_parent";
+	if (!scopeNarrows(parentClaims.scope, candidate.scope)) return "scope_does_not_narrow";
+	if (parentClaims.capability !== candidate.capability) return "capability_mismatch";
+	const parentRemaining = parentClaims["delegations-remaining"];
+	if (parentRemaining !== void 0 && (candidate.delegationsRemaining === void 0 || candidate.delegationsRemaining >= parentRemaining)) return "delegation_exceeds_parent";
+}
+/**
+* A pure query: could deviceId, presenting heldToken as its own delegation authority, successfully mint a delegation matching candidate right now -- without attempting (and potentially failing) a real mint just to find out. Reuses mintCapabilityToken's own narrowing arithmetic via checkNarrowing, so the two can never silently drift into different ideas of what "narrows" means.
+*
+* Deliberately narrower than a full mint attempt in one respect: this checks only the narrowing rules tokens.cddl's own delegation obligations require (bearer match, expiry, scope, capability, delegations-remaining), the same scope mintCapabilityToken itself checks a *parent* against -- it does not verify heldToken's own signature or revocation status, exactly as mintCapabilityToken never re-verifies its own parent's signature either. A caller that also needs heldToken's cryptographic validity confirmed calls verifyCapabilityToken separately.
+*/
+function canGrant(heldToken, deviceId, candidate, now) {
+	if (candidate.expires <= now) return false;
+	const heldClaims = decodeTokenClaims(heldToken);
+	if (heldClaims === void 0) return false;
+	return checkNarrowing(heldClaims, deviceId, candidate) === void 0;
+}
 /**
 * Mints one capability token: builds token-claims from the given fields, signs it as a COSE_Sign1 under `identity`'s own key, with a protected header matching what the frozen conformance vectors actually encode (`{1: alg, 4: issuer device-id}`, not the empty header a token merely needs to verify against itself).
 *
@@ -230,26 +250,15 @@ async function mintCapabilityToken(options) {
 			ok: false,
 			reason: "parent_malformed"
 		};
-		if (!bytesEqual(parentClaims.bearer, options.identity.deviceId)) return {
-			ok: false,
-			reason: "parent_bearer_mismatch"
-		};
-		if (options.expires > parentClaims.expires) return {
+		const refusal = checkNarrowing(parentClaims, options.identity.deviceId, {
+			capability: options.capability,
+			scope: options.scope,
+			expires: options.expires,
+			...options.delegationsRemaining !== void 0 ? { delegationsRemaining: options.delegationsRemaining } : {}
+		});
+		if (refusal !== void 0) return {
 			ok: false,
-			reason: "expires_exceeds_parent"
-		};
-		if (!scopeNarrows(parentClaims.scope, options.scope)) return {
-			ok: false,
-			reason: "scope_does_not_narrow"
-		};
-		if (parentClaims.capability !== options.capability) return {
-			ok: false,
-			reason: "capability_mismatch"
-		};
-		const parentRemaining = parentClaims["delegations-remaining"];
-		if (parentRemaining !== void 0 && (options.delegationsRemaining === void 0 || options.delegationsRemaining >= parentRemaining)) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
+			reason: refusal
 		};
 		parentBytes = encodeBuf(options.parent);
 	}
@@ -293,4 +302,4 @@ async function mintRevocationEntry(options) {
 	];
 }
 //#endregion
-export { mintCapabilityToken, mintRevocationEntry, verifyCapabilityToken, verifyRevocationEntry };
+export { canGrant, mintCapabilityToken, mintRevocationEntry, verifyCapabilityToken, verifyRevocationEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "repository": {