wire-mesh-core 3.8.0 → 3.10.0

package/dist/domain/tokens.d.mts

@@ -1,2 +1,131 @@
-import { _ as sig1ToBeSigned, a as MintVerdict, c as RevocationEntryVerdictReason, d as VerifyCapabilityTokenOptions, f as VerifyRevocationEntryOptions, g as mintRevocationEntry, h as mintCapabilityToken, i as MintRevocationEntryOptions, l as TokenVerdict, m as canGrantVia, n as MintCapabilityTokenOptions, o as RevocationCheck, p as canGrant, r as MintRefusalReason, s as RevocationEntryVerdict, t as MANAGE_GRANT_CAPABILITY, u as TokenVerdictReason, v as verifyCapabilityToken, y as verifyRevocationEntry } from "../tokens-DRkm_QOR.mjs";
-export { MANAGE_GRANT_CAPABILITY, MintCapabilityTokenOptions, MintRefusalReason, MintRevocationEntryOptions, MintVerdict, RevocationCheck, RevocationEntryVerdict, RevocationEntryVerdictReason, TokenVerdict, TokenVerdictReason, VerifyCapabilityTokenOptions, VerifyRevocationEntryOptions, canGrant, canGrantVia, mintCapabilityToken, mintRevocationEntry, sig1ToBeSigned, verifyCapabilityToken, verifyRevocationEntry };
+import { B as IdentityKey, D as DeviceId, bt as RevocationEntry, en as TokenClaims, p as CapabilityToken, yt as RevocationClaims } from "../protocol-DzmpxxUr.mjs";
+import { t as IdentityPort } from "../identity-EV-HHv_D.mjs";
+import { t as Clock } from "../clock-DiSx-WKM.mjs";
+import { l as GrantSubject, m as TokenDelegateHandler, r as ConditionsContext, u as NarrowingCandidate } from "../token-predicates-DqpG8VZZ.mjs";
+import { PredicateNode } from "trilean";
+//#region src/domain/tokens.d.ts
+/** The capability verb of a grant-capability (wire-mesh#323): authority to mint other capability tokens, the same register manage:revoke already established for authority over tokens. */
+export declare const MANAGE_GRANT_CAPABILITY = "manage:grant";
+/**
+ * The revocation view a verifier consults. Returns every recorded, already-signature-verified revocation-claims for tokenId, across every issuer that has ever submitted one -- unfiltered by the store itself. The actual verifier obligation (an entry counts against a token when its own issuer matches the token's own issuer, OR its optional `authorization` grants delegated revoke authority -- management.cddl) is checked by the caller (verifyTokenChain), not here, since that check needs the target token's own scope plus identity/clock to verify a nested authorization token, none of which a store constructed ahead of time has access to. Implementations ingest gossiped revocation-announce frames via verifyRevocationEntry (which enforces each entry's own signature and self-certification) and key the resulting claims by token-id alone -- a token-id can legitimately carry multiple recorded entries from different issuers.
+ */
+export interface RevocationCheck {
+  entriesFor: (tokenId: Uint8Array) => Promise<readonly RevocationClaims[]>;
+}
+export type TokenVerdictReason = "malformed" | "bad_signature" | "wrong_issuer" | "bearer_mismatch" | "expired" | "not_yet_valid" | "content_expired" | "revoked" | "delegation_exceeds_parent" | "parent_invalid" |
+/** The authorised-by link's own obligations failed: the cited grant-capability did not decode or fully verify, its bearer is not this token's issuer, its capability is not manage:grant, its grants-capability does not match, the scope or expiry widened, the depth bound was exceeded, or its conditions (evaluated against THIS token's claims) did not hold. Collapsed to one reason the same way every narrowing failure already collapses to delegation_exceeds_parent. */
+"authorisation_invalid" |
+/** The parent/authorised-by walk exceeded MAX_CHAIN_DEPTH. */
+"chain_too_deep" |
+/** The walk revisited a payload already on the current path: a cycle two colluding issuers constructed. */
+"chain_cycle" |
+/** claims.conditions is present but its bstr fails CBOR decode, or decodes to something that is not a JSON array of valid trilean PredicateNodes -- fail-closed per CONVENTIONS.md's verifier-obligations glossary, the same treatment "malformed" already gives an undecodable payload. */
+"conditions_invalid" |
+/** claims.conditions decoded and validated, but at least one entry did not evaluate to a definite `true` (indeterminate or false) -- the issuer's own additional restriction was not met. */
+"conditions_not_satisfied";
+export type TokenVerdict = {
+  ok: true;
+  claims: TokenClaims;
+  /** The device-id at the root of this token's delegation chain: its own issuer when it carries no parent, otherwise the root of its parent's chain. Lets a caller (e.g. core/room's obligation that a chain must terminate at the path's own owner, or the verifier itself for a DM) check the chain's root with one equality comparison instead of re-walking the parent chain a second time. */
+  rootIssuer: DeviceId;
+  /** The root ancestor's own self-certifying issuer-key -- already decoded during the walk (every TokenClaims carries its own issuer-key), just threaded up rather than re-derived. Lets a caller compute an ECDH shared secret against the chain's root (e.g. room.rekey's own sender, for a named room whose token chain terminates at the owner) without a separate, out-of-band way to learn that issuer's public key. */
+  rootIssuerKey: IdentityKey;
+  /** How many delegation hops this token is from its own root -- 0 for a root grant. Costs nothing extra once rootIssuer is being tracked, and makes the delegation bound observable for diagnostics. */
+  depth: number;
+} | {
+  ok: false;
+  reason: TokenVerdictReason;
+};
+export interface VerifyCapabilityTokenOptions {
+  identity: IdentityPort;
+  clock: Clock;
+  revocation: RevocationCheck;
+  /** When given, the token must bear this device -- the caller presenting a token to authorise itself, not someone else. */
+  expectedBearer?: DeviceId;
+  /** Registers domain-specific delegate systems a presented token's own `conditions` entries may name, beyond the five mandatory narrowing ops (which are never reachable from `conditions` -- see evaluateConditions's own doc comment). None are registered by wire-mesh-core itself; a domain (a message TTL, #84's future revoke-authorization check) supplies its own here. A `conditions` entry naming a system absent from this map is indeterminate, and therefore fails the whole token -- fail-closed, not a silent no-op. */
+  extraPredicateResolvers?: Readonly<Record<string, TokenDelegateHandler<ConditionsContext>>>;
+}
+/** RFC 9052 §4.4 Sig_structure for a COSE_Sign1 with no external AAD: ["Signature1", protected, external_aad, payload]. Exported (not just used internally by verifyTokenChain) so any other self-certifying COSE_Sign1 construction in this codebase -- e.g. threshold-subject.ts's own to-be-signed bytes for a FROST-signed capability-token/revocation-entry/handle-record/room-notice -- reuses this single construction rather than a second hand-rolled one. */
+export declare function sig1ToBeSigned(protectedHeader: Uint8Array, payload: Uint8Array): Uint8Array;
+/**
+ * Verifies one capability token per tokens.cddl's own documented rules: the token is a well-formed COSE_Sign1 whose signature actually verifies against its own embedded issuer-key, that issuer-key is self-certifying (sha256(issuer-key.public-key) equals the claimed issuer device-id -- no shared secret needed to check this), the token is currently valid (not expired, not before not-before, not revoked by its own issuer), and -- recursively -- any parent delegation narrows rather than widens across all three axes of authority: the parent's bearer must be this token's issuer (the delegation chain is unbroken), this token's expiry must not exceed its parent's, and this token's scope must narrow its parent's (same kind; equal-or-descendant path when the parent carries one) with an identical capability verb (the capability-verb grammar has no sub-verb relation, so a different verb is a different authority, not a narrower one). Undecodable payload bytes return "malformed" and undecodable parent bytes return "parent_invalid" -- hostile input produces a verdict, never a throw.
+ */
+export declare function verifyCapabilityToken(token: CapabilityToken, options: VerifyCapabilityTokenOptions): Promise<TokenVerdict>;
+export type RevocationEntryVerdictReason = "malformed" | "bad_signature" | "wrong_issuer";
+export type RevocationEntryVerdict = {
+  ok: true;
+  claims: RevocationClaims;
+} | {
+  ok: false;
+  reason: RevocationEntryVerdictReason;
+};
+export interface VerifyRevocationEntryOptions {
+  /** Crypto primitives only -- any IdentityPort instance can verify any entry, since everything needed to check one travels inside the entry itself. */
+  identity: IdentityPort;
+}
+/**
+ * Verifies one gossiped revocation-entry (management.cddl): a well-formed COSE_Sign1 whose signature verifies against its own embedded issuer-key, where that issuer-key is self-certifying (sha256(issuer-key.public-key) equals the claimed issuer device-id). A verifier that ingests a revocation-announce frame runs each entry through this before recording it in its revocation view; entries failing here are dropped, not stored. The issuer-match against a specific token's own issuer (only a token's own issuer may revoke it) is deliberately NOT checked here -- it happens at lookup time in RevocationCheck, against whichever token is being verified.
+ */
+export declare function verifyRevocationEntry(entry: RevocationEntry, options: VerifyRevocationEntryOptions): Promise<RevocationEntryVerdict>;
+export type MintRefusalReason = "already_expired" | "parent_malformed" | "parent_bearer_mismatch" | "expires_exceeds_parent" | "scope_does_not_narrow" | "capability_mismatch" | "delegation_exceeds_parent" |
+/** parent and authorised-by are mutually exclusive link kinds; a manage:grant capability must be minted through authorised-by only. */
+"links_exclusive" |
+/** The cited grant-capability did not decode, or its own conditions bytes did not. */
+"authorisation_malformed" | "authorisation_parent_forbidden" | "authorisation_bearer_mismatch" | "authorisation_capability_mismatch" | "authorisation_scope_does_not_narrow" | "authorisation_exceeds_authoriser" | "authorisation_delegation_exceeds" |
+/** The authoriser's conditions, evaluated against the candidate being minted, did not all hold (wire-mesh#323 subject mode). */
+"authorisation_conditions_not_satisfied";
+export type MintVerdict = {
+  ok: true;
+  token: CapabilityToken;
+} | {
+  ok: false;
+  reason: MintRefusalReason;
+};
+/**
+ * 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.
+ *
+ * Async as of the predicate-list evaluator (issue #85): checkNarrowing now routes through trilean's own evaluatePredicate, which is asynchronous throughout -- there is no synchronous path through a real evaluator call, so this is a genuine, deliberate breaking change to what was previously a synchronous pure function. No existing consumer of wire-mesh-core calls canGrant (confirmed against agent-comms, the only other repo depending on this package), so there is nothing to migrate.
+ */
+export declare function canGrant(heldToken: CapabilityToken, deviceId: DeviceId, candidate: Readonly<NarrowingCandidate>, now: number): Promise<boolean>;
+/** A pure query: could deviceId, presenting heldGrantCapability as its minting authority, mint a token matching candidate right now (wire-mesh#323) -- canGrant's authorised-by analogue, with the same deliberately-narrower-than-verify caveat canGrant's own doc comment states: the held token's signature and revocation status are not checked here; a caller needing those confirmed calls verifyCapabilityToken separately. The candidate carries a bearer because the authoriser's subject-mode conditions read it (the no-self-grant bar). */
+export declare function canGrantVia(heldGrantCapability: CapabilityToken, deviceId: DeviceId, candidate: Readonly<GrantSubject>, now: number): Promise<boolean>;
+export interface MintCapabilityTokenOptions {
+  /** The issuer -- signs the token, and supplies the self-certifying issuer/issuer-key claims. */
+  identity: IdentityPort;
+  clock: Clock;
+  tokenId: Uint8Array<ArrayBuffer>;
+  bearer: DeviceId;
+  capability: TokenClaims["capability"];
+  scope: TokenClaims["scope"];
+  expires: number;
+  notBefore?: number;
+  /** How many further delegation hops the *resulting* token itself permits below it -- unrelated to, and never a bound on, whether `identity` may mint further tokens of its own at the root level for other bearers. Those are two different facts: a token minted with `delegationsRemaining: 0` genuinely cannot itself be re-delegated (correct -- e.g. a room owner's own self-signed root grant, which should never be handed onward), but that same `0` says nothing about the issuer's own separate, ordinary authority to mint additional independent root-level grants (naming no `parent` at all) for other bearers. Root-level minting for a second bearer is never blocked by any existing token's own `delegationsRemaining`, because it uses no `parent` in the first place -- there is no narrowing check to run. Confirmed live in agent-comms' own room-membership implementation (`ExaDev/agent-comms` PR #72): each member's own join/invite grant is minted as its own independent, parent-less, root-level token precisely because the room owner's `delegationsRemaining: 0` self-grant cannot parent anything -- correct by this same reasoning, not a workaround. */
+  delegationsRemaining?: number;
+  /** The issuer's own token, when this is a delegation rather than a root grant. Its claims are checked against every narrowing rule below -- mint refuses rather than producing a token verifyCapabilityToken would reject anyway. Omit entirely for a root-level grant (including a second, independent root-level grant for a different bearer under the same capability/scope this issuer already grants elsewhere) -- there is no bound on how many such root grants an issuer may mint, since none of them narrows any other. */
+  parent?: CapabilityToken;
+  /** Additional, issuer-chosen restrictions beyond the five mandatory narrowing checks (issue #85) -- CBOR-encoded into claims.conditions verbatim, evaluated by every verifier via evaluateConditions. Strictly additive: has no bearing on narrowing, which mint enforces separately above regardless of what's given here. Not re-validated against trilean's own schema before encoding -- the TS type already guarantees a well-formed PredicateNode[] at this call site, unlike the bytes a verifier decodes from an untrusted wire token, which always are. */
+  conditions?: PredicateNode[];
+  /** The grant-capability authorising this mint (wire-mesh#323): the resulting token carries it as authorised-by, and every link obligation (bearer match, manage:grant verb, grants-capability match, scope and expiry narrowing, depth consumption, and the authoriser's subject-mode conditions against this very candidate) is enforced here, at issuance, rather than left for the far end as a bare authorisation_invalid. Mutually exclusive with parent. */
+  authorisedBy?: CapabilityToken;
+  /** On a manage:grant token: the single verb it authorises minting. Absent means any verb within scope. */
+  grantsCapability?: TokenClaims["capability"];
+  /** On a manage:request token (wire-mesh#324): the single verb it authorises requesting. Absent means any verb within scope. */
+  requestsCapability?: TokenClaims["capability"];
+}
+/**
+ * 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).
+ *
+ * When `parent` is given, every one of `tokens.cddl`'s own narrowing obligations is enforced here, at issuance, rather than left for the far end to discover minutes or hours later as a bare `delegation_exceeds_parent` from `verifyCapabilityToken` -- the same "fail loudly, fail early" reasoning that governs every other boundary in this codebase. An issuer minting an invalid delegation is a bug in the caller; this function refuses rather than producing a token indistinguishable from a valid one until someone else verifies it.
+ */
+export declare function mintCapabilityToken(options: MintCapabilityTokenOptions): Promise<MintVerdict>;
+export interface MintRevocationEntryOptions {
+  /** The token's own issuer -- only a token's own issuer may revoke it (management.cddl), so this must be the same identity that minted the token being revoked. */
+  identity: IdentityPort;
+  tokenId: Uint8Array<ArrayBuffer>;
+  revokedAt: number;
+}
+/** Mints one revocation-entry (management.cddl): a COSE_Sign1 over revocation-claims, signed the same way mintCapabilityToken signs a token. No narrowing chain to check -- a revocation entry has no parent and cannot fail to be issuable the way a delegated token can, so this returns the entry directly rather than a verdict. */
+export declare function mintRevocationEntry(options: MintRevocationEntryOptions): Promise<RevocationEntry>;
+//#endregion

package/dist/domain/tokens.mjs

@@ -1,2 +1,459 @@
-import { a as mintRevocationEntry, c as verifyRevocationEntry, i as mintCapabilityToken, n as canGrant, o as sig1ToBeSigned, r as canGrantVia, s as verifyCapabilityToken, t as MANAGE_GRANT_CAPABILITY } from "../tokens-D8JlTJNA.mjs";
+import { capabilityTokenSchema, revocationClaimsSchema, tokenClaimsSchema } from "../generated/protocol.mjs";
+import { bytesToHex } from "./device-id.mjs";
+import { bytesEqual, scopeNarrows } from "./token-scope.mjs";
+import { conditionsListSchema, evaluateConditions, evaluateNarrowing } from "./token-predicates.mjs";
+import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
+//#region src/domain/tokens.ts
+/** The capability verb of a grant-capability (wire-mesh#323): authority to mint other capability tokens, the same register manage:revoke already established for authority over tokens. */
+const MANAGE_GRANT_CAPABILITY = "manage:grant";
+/** Both link kinds walk at most this many hops before the verifier gives up, mirroring Rust's own MAX_CHAIN_DEPTH. Two colluding issuers can construct a mutually-bearing parent cycle that would otherwise recurse forever, and the authorised-by link makes the attack cheaper to mount, so TS gains the bound rather than relying on JS recursion limits. */
+const MAX_CHAIN_DEPTH = 64;
+/** RFC 9052 §4.4 Sig_structure for a COSE_Sign1 with no external AAD: ["Signature1", protected, external_aad, payload]. Exported (not just used internally by verifyTokenChain) so any other self-certifying COSE_Sign1 construction in this codebase -- e.g. threshold-subject.ts's own to-be-signed bytes for a FROST-signed capability-token/revocation-entry/handle-record/room-notice -- reuses this single construction rather than a second hand-rolled one. */
+function sig1ToBeSigned(protectedHeader, payload) {
+	return encode([
+		"Signature1",
+		protectedHeader,
+		/* @__PURE__ */ new Uint8Array(0),
+		payload
+	], cdeEncodeOptions);
+}
+/** Normalises cbor2's encode() (and any other Uint8Array<ArrayBufferLike>-typed construction) to a fresh, non-shared, whole-buffer Uint8Array<ArrayBuffer> -- what the generated schemas' concrete-typed fields require. */
+function buf(bytes) {
+	return Uint8Array.from(bytes);
+}
+function encodeBuf(value) {
+	return buf(encode(value, cdeEncodeOptions));
+}
+/** The COSE protected header every capability-token/revocation-entry envelope in this codebase actually signs over: label 1 (alg) and label 4 (kid, the issuer's own device-id) -- matching the frozen conformance vectors, not the empty header a token merely needs to verify against itself. */
+function protectedHeaderFor(identity) {
+	return encodeBuf({
+		1: identity.identityKey.alg,
+		4: identity.deviceId
+	});
+}
+/** Decodes and validates a parent token's own claims from its raw CapabilityToken tuple -- the same decode `verifyTokenChain` performs on `claims.parent`, extracted here so mint can check narrowing against a parent's real claims without duplicating the CBOR/schema plumbing. Returns undefined for anything that doesn't parse; the caller turns that into its own refusal reason since "malformed" means something different at mint time than at verify time. */
+function decodeTokenClaims(token) {
+	const [, , payload] = token;
+	if (payload === null) return void 0;
+	let decoded;
+	try {
+		decoded = decode(payload, cdeDecodeOptions);
+	} catch {
+		return;
+	}
+	const result = tokenClaimsSchema.safeParse(decoded);
+	return result.success ? result.data : void 0;
+}
+/**
+* Verifies one capability token per tokens.cddl's own documented rules: the token is a well-formed COSE_Sign1 whose signature actually verifies against its own embedded issuer-key, that issuer-key is self-certifying (sha256(issuer-key.public-key) equals the claimed issuer device-id -- no shared secret needed to check this), the token is currently valid (not expired, not before not-before, not revoked by its own issuer), and -- recursively -- any parent delegation narrows rather than widens across all three axes of authority: the parent's bearer must be this token's issuer (the delegation chain is unbroken), this token's expiry must not exceed its parent's, and this token's scope must narrow its parent's (same kind; equal-or-descendant path when the parent carries one) with an identical capability verb (the capability-verb grammar has no sub-verb relation, so a different verb is a different authority, not a narrower one). Undecodable payload bytes return "malformed" and undecodable parent bytes return "parent_invalid" -- hostile input produces a verdict, never a throw.
+*/
+async function verifyCapabilityToken(token, options) {
+	const verdict = await verifyTokenChain(token, {
+		identity: options.identity,
+		clock: options.clock,
+		revocation: options.revocation,
+		...options.extraPredicateResolvers !== void 0 ? { extraPredicateResolvers: options.extraPredicateResolvers } : {}
+	});
+	if (!verdict.ok) return verdict;
+	if (options.expectedBearer !== void 0 && !bytesEqual(verdict.claims.bearer, options.expectedBearer)) return {
+		ok: false,
+		reason: "bearer_mismatch"
+	};
+	return verdict;
+}
+/**
+* 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 (entry.authorization === void 0) return false;
+	let decodedAuthorization;
+	try {
+		decodedAuthorization = decode(entry.authorization, cdeDecodeOptions);
+	} catch {
+		return false;
+	}
+	const authorizationResult = capabilityTokenSchema.safeParse(decodedAuthorization);
+	if (!authorizationResult.success) return false;
+	const authorizationVerdict = await verifyCapabilityToken(authorizationResult.data, {
+		...options,
+		expectedBearer: entry.issuer
+	});
+	return authorizationVerdict.ok && authorizationVerdict.claims.capability === "manage:revoke" && scopeNarrows(authorizationVerdict.claims.scope, targetClaims.scope);
+}
+async function verifyTokenChain(token, options, subjectClaims, depth = 0, seen = /* @__PURE__ */ new Set()) {
+	const [protectedHeader, , payload, signature] = token;
+	if (payload === null) return {
+		ok: false,
+		reason: "malformed"
+	};
+	if (depth >= MAX_CHAIN_DEPTH) return {
+		ok: false,
+		reason: "chain_too_deep"
+	};
+	const payloadHex = bytesToHex(payload);
+	if (seen.has(payloadHex)) return {
+		ok: false,
+		reason: "chain_cycle"
+	};
+	const deeperSeen = new Set(seen).add(payloadHex);
+	let decodedClaims;
+	try {
+		decodedClaims = decode(payload, cdeDecodeOptions);
+	} catch {
+		return {
+			ok: false,
+			reason: "malformed"
+		};
+	}
+	const claimsResult = tokenClaimsSchema.safeParse(decodedClaims);
+	if (!claimsResult.success) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const claims = claimsResult.data;
+	if (!await options.identity.verify(claims["issuer-key"], sig1ToBeSigned(protectedHeader, payload), signature)) return {
+		ok: false,
+		reason: "bad_signature"
+	};
+	const derivedIssuerId = await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]);
+	if (!bytesEqual(derivedIssuerId, claims.issuer)) return {
+		ok: false,
+		reason: "wrong_issuer"
+	};
+	const now = options.clock.now();
+	if (claims.expires <= now) return {
+		ok: false,
+		reason: "expired"
+	};
+	if (claims["not-before"] !== void 0 && claims["not-before"] > now) return {
+		ok: false,
+		reason: "not_yet_valid"
+	};
+	const validUntil = claims["valid-until"];
+	if (validUntil !== void 0 && validUntil <= now) return {
+		ok: false,
+		reason: "content_expired"
+	};
+	const revocationEntries = await options.revocation.entriesFor(claims["token-id"]);
+	for (const entry of revocationEntries) if (await revocationEntryGrantsRevoke(entry, claims, options)) return {
+		ok: false,
+		reason: "revoked"
+	};
+	if (claims.conditions !== void 0) {
+		let decodedConditions;
+		try {
+			decodedConditions = decode(claims.conditions, cdeDecodeOptions);
+		} catch {
+			return {
+				ok: false,
+				reason: "conditions_invalid"
+			};
+		}
+		const conditionsResult = conditionsListSchema.safeParse(decodedConditions);
+		if (!conditionsResult.success) return {
+			ok: false,
+			reason: "conditions_invalid"
+		};
+		if (!(await evaluateConditions(conditionsResult.data, claims, options.clock, options.extraPredicateResolvers, subjectClaims)).ok) return {
+			ok: false,
+			reason: "conditions_not_satisfied"
+		};
+	}
+	const parentBytes = claims.parent;
+	const authorisationBytes = claims["authorised-by"];
+	if (claims.capability === "manage:grant" && parentBytes !== void 0) return {
+		ok: false,
+		reason: "authorisation_invalid"
+	};
+	if (parentBytes !== void 0 && authorisationBytes !== void 0) return {
+		ok: false,
+		reason: "malformed"
+	};
+	if (parentBytes !== void 0) {
+		let decodedParent;
+		try {
+			decodedParent = decode(parentBytes, cdeDecodeOptions);
+		} catch {
+			return {
+				ok: false,
+				reason: "parent_invalid"
+			};
+		}
+		const parentResult = capabilityTokenSchema.safeParse(decodedParent);
+		if (!parentResult.success) return {
+			ok: false,
+			reason: "parent_invalid"
+		};
+		const parentVerdict = await verifyTokenChain(parentResult.data, options, void 0, depth + 1, deeperSeen);
+		if (!parentVerdict.ok) {
+			if (parentVerdict.reason === "chain_too_deep" || parentVerdict.reason === "chain_cycle") return {
+				ok: false,
+				reason: parentVerdict.reason
+			};
+			return {
+				ok: false,
+				reason: "parent_invalid"
+			};
+		}
+		const candidate = {
+			capability: claims.capability,
+			scope: claims.scope,
+			expires: claims.expires,
+			...claims["delegations-remaining"] !== void 0 ? { delegationsRemaining: claims["delegations-remaining"] } : {}
+		};
+		if (await evaluateNarrowing(parentVerdict.claims, claims.issuer, candidate) !== void 0) return {
+			ok: false,
+			reason: "delegation_exceeds_parent"
+		};
+		return {
+			ok: true,
+			claims,
+			rootIssuer: parentVerdict.rootIssuer,
+			rootIssuerKey: parentVerdict.rootIssuerKey,
+			depth: parentVerdict.depth + 1
+		};
+	}
+	if (authorisationBytes !== void 0) {
+		let decodedAuthoriser;
+		try {
+			decodedAuthoriser = decode(authorisationBytes, cdeDecodeOptions);
+		} catch {
+			return {
+				ok: false,
+				reason: "authorisation_invalid"
+			};
+		}
+		const authoriserResult = capabilityTokenSchema.safeParse(decodedAuthoriser);
+		if (!authoriserResult.success) return {
+			ok: false,
+			reason: "authorisation_invalid"
+		};
+		const authoriserVerdict = await verifyTokenChain(authoriserResult.data, options, claims, depth + 1, deeperSeen);
+		if (!authoriserVerdict.ok) {
+			if (authoriserVerdict.reason === "chain_too_deep" || authoriserVerdict.reason === "chain_cycle") return {
+				ok: false,
+				reason: authoriserVerdict.reason
+			};
+			return {
+				ok: false,
+				reason: "authorisation_invalid"
+			};
+		}
+		const authoriser = authoriserVerdict.claims;
+		const grantsCapability = authoriser["grants-capability"];
+		if (!(bytesEqual(authoriser.bearer, claims.issuer) && authoriser.capability === "manage:grant" && (grantsCapability === void 0 || grantsCapability === claims.capability) && scopeNarrows(authoriser.scope, claims.scope) && claims.expires <= authoriser.expires && (authoriser["delegations-remaining"] === void 0 || claims["delegations-remaining"] !== void 0 && claims["delegations-remaining"] < authoriser["delegations-remaining"]))) return {
+			ok: false,
+			reason: "authorisation_invalid"
+		};
+		return {
+			ok: true,
+			claims,
+			rootIssuer: authoriserVerdict.rootIssuer,
+			rootIssuerKey: authoriserVerdict.rootIssuerKey,
+			depth: authoriserVerdict.depth + 1
+		};
+	}
+	return {
+		ok: true,
+		claims,
+		rootIssuer: claims.issuer,
+		rootIssuerKey: claims["issuer-key"],
+		depth: 0
+	};
+}
+/**
+* Verifies one gossiped revocation-entry (management.cddl): a well-formed COSE_Sign1 whose signature verifies against its own embedded issuer-key, where that issuer-key is self-certifying (sha256(issuer-key.public-key) equals the claimed issuer device-id). A verifier that ingests a revocation-announce frame runs each entry through this before recording it in its revocation view; entries failing here are dropped, not stored. The issuer-match against a specific token's own issuer (only a token's own issuer may revoke it) is deliberately NOT checked here -- it happens at lookup time in RevocationCheck, against whichever token is being verified.
+*/
+async function verifyRevocationEntry(entry, options) {
+	const [protectedHeader, , payload, signature] = entry;
+	if (payload === null) return {
+		ok: false,
+		reason: "malformed"
+	};
+	let decodedClaims;
+	try {
+		decodedClaims = decode(payload, cdeDecodeOptions);
+	} catch {
+		return {
+			ok: false,
+			reason: "malformed"
+		};
+	}
+	const claimsResult = revocationClaimsSchema.safeParse(decodedClaims);
+	if (!claimsResult.success) return {
+		ok: false,
+		reason: "malformed"
+	};
+	const claims = claimsResult.data;
+	if (!await options.identity.verify(claims["issuer-key"], sig1ToBeSigned(protectedHeader, payload), signature)) return {
+		ok: false,
+		reason: "bad_signature"
+	};
+	const derivedIssuerId = await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]);
+	if (!bytesEqual(derivedIssuerId, claims.issuer)) return {
+		ok: false,
+		reason: "wrong_issuer"
+	};
+	return {
+		ok: true,
+		claims
+	};
+}
+/** Maps evaluateNarrowing's own NarrowingSystem (the first predicate op that did not hold) to mintCapabilityToken's five distinct refusal reasons -- verifyTokenChain collapses every narrowing failure to a single "delegation_exceeds_parent", but mint has always reported which specific rule was violated, since a caller building the candidate itself benefits from knowing exactly what to fix. */
+const NARROWING_SYSTEM_TO_MINT_REFUSAL = {
+	"bearer-is": "parent_bearer_mismatch",
+	"expires-at": "expires_exceeds_parent",
+	"scope-narrows": "scope_does_not_narrow",
+	"capability-is": "capability_mismatch",
+	"depth-remaining": "delegation_exceeds_parent"
+};
+/** 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. Delegates the actual check to evaluateNarrowing (token-predicates.ts), the same generic evaluator verifyTokenChain's own delegation-chain walk uses, so mint and verify share one implementation of each of the five checks rather than two hardcoded copies. Returns the specific refusal reason, or undefined when every rule is satisfied. */
+async function checkNarrowing(parentClaims, granterDeviceId, candidate) {
+	const failedSystem = await evaluateNarrowing(parentClaims, granterDeviceId, candidate);
+	return failedSystem === void 0 ? void 0 : NARROWING_SYSTEM_TO_MINT_REFUSAL[failedSystem];
+}
+/** The authorised-by link's own arithmetic (wire-mesh#323), the analogue checkNarrowing already is for the parent link: everything tokens.cddl's authorised-by obligations require, checked against a not-yet-minted candidate, shared between mintCapabilityToken and canGrantVia so the two can never drift. The authoriser's conditions are evaluated in subject mode against the candidate, the same evaluation the verifier performs against the minted child. Returns the specific refusal reason, or undefined when the authorisation holds. */
+async function checkAuthorisation(authorisingClaims, minterDeviceId, candidate) {
+	if (authorisingClaims.parent !== void 0) return "authorisation_parent_forbidden";
+	if (!bytesEqual(authorisingClaims.bearer, minterDeviceId)) return "authorisation_bearer_mismatch";
+	const grantsCapability = authorisingClaims["grants-capability"];
+	if (authorisingClaims.capability !== "manage:grant" || grantsCapability !== void 0 && grantsCapability !== candidate.capability) return "authorisation_capability_mismatch";
+	if (!scopeNarrows(authorisingClaims.scope, candidate.scope)) return "authorisation_scope_does_not_narrow";
+	if (candidate.expires > authorisingClaims.expires) return "authorisation_exceeds_authoriser";
+	const remaining = authorisingClaims["delegations-remaining"];
+	if (remaining !== void 0 && (candidate.delegationsRemaining === void 0 || candidate.delegationsRemaining >= remaining)) return "authorisation_delegation_exceeds";
+	if (authorisingClaims.conditions !== void 0) {
+		let decodedConditions;
+		try {
+			decodedConditions = decode(authorisingClaims.conditions, cdeDecodeOptions);
+		} catch {
+			return "authorisation_malformed";
+		}
+		const conditionsResult = conditionsListSchema.safeParse(decodedConditions);
+		if (!conditionsResult.success) return "authorisation_malformed";
+		if (!(await evaluateConditions(conditionsResult.data, authorisingClaims, { now: () => 0 }, {}, candidate)).ok) return "authorisation_conditions_not_satisfied";
+	}
+}
+/**
+* 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.
+*
+* Async as of the predicate-list evaluator (issue #85): checkNarrowing now routes through trilean's own evaluatePredicate, which is asynchronous throughout -- there is no synchronous path through a real evaluator call, so this is a genuine, deliberate breaking change to what was previously a synchronous pure function. No existing consumer of wire-mesh-core calls canGrant (confirmed against agent-comms, the only other repo depending on this package), so there is nothing to migrate.
+*/
+async function canGrant(heldToken, deviceId, candidate, now) {
+	if (candidate.expires <= now) return false;
+	const heldClaims = decodeTokenClaims(heldToken);
+	if (heldClaims === void 0) return false;
+	return await checkNarrowing(heldClaims, deviceId, candidate) === void 0;
+}
+/** A pure query: could deviceId, presenting heldGrantCapability as its minting authority, mint a token matching candidate right now (wire-mesh#323) -- canGrant's authorised-by analogue, with the same deliberately-narrower-than-verify caveat canGrant's own doc comment states: the held token's signature and revocation status are not checked here; a caller needing those confirmed calls verifyCapabilityToken separately. The candidate carries a bearer because the authoriser's subject-mode conditions read it (the no-self-grant bar). */
+async function canGrantVia(heldGrantCapability, deviceId, candidate, now) {
+	if (candidate.expires <= now) return false;
+	const heldClaims = decodeTokenClaims(heldGrantCapability);
+	if (heldClaims === void 0) return false;
+	return await checkAuthorisation(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).
+*
+* When `parent` is given, every one of `tokens.cddl`'s own narrowing obligations is enforced here, at issuance, rather than left for the far end to discover minutes or hours later as a bare `delegation_exceeds_parent` from `verifyCapabilityToken` -- the same "fail loudly, fail early" reasoning that governs every other boundary in this codebase. An issuer minting an invalid delegation is a bug in the caller; this function refuses rather than producing a token indistinguishable from a valid one until someone else verifies it.
+*/
+async function mintCapabilityToken(options) {
+	if (options.expires <= options.clock.now()) return {
+		ok: false,
+		reason: "already_expired"
+	};
+	if (options.parent !== void 0 && options.authorisedBy !== void 0) return {
+		ok: false,
+		reason: "links_exclusive"
+	};
+	if (options.capability === "manage:grant" && options.parent !== void 0) return {
+		ok: false,
+		reason: "authorisation_parent_forbidden"
+	};
+	let parentBytes;
+	if (options.parent !== void 0) {
+		const parentClaims = decodeTokenClaims(options.parent);
+		if (parentClaims === void 0) return {
+			ok: false,
+			reason: "parent_malformed"
+		};
+		const refusal = await 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: refusal
+		};
+		parentBytes = encodeBuf(options.parent);
+	}
+	let authorisationBytes;
+	if (options.authorisedBy !== void 0) {
+		const authorisingClaims = decodeTokenClaims(options.authorisedBy);
+		if (authorisingClaims === void 0) return {
+			ok: false,
+			reason: "authorisation_malformed"
+		};
+		const refusal = await checkAuthorisation(authorisingClaims, options.identity.deviceId, {
+			capability: options.capability,
+			scope: options.scope,
+			bearer: options.bearer,
+			expires: options.expires,
+			...options.delegationsRemaining !== void 0 ? { delegationsRemaining: options.delegationsRemaining } : {}
+		});
+		if (refusal !== void 0) return {
+			ok: false,
+			reason: refusal
+		};
+		authorisationBytes = encodeBuf(options.authorisedBy);
+	}
+	const payload = encodeBuf({
+		"token-id": options.tokenId,
+		issuer: options.identity.deviceId,
+		"issuer-key": options.identity.identityKey,
+		bearer: options.bearer,
+		capability: options.capability,
+		scope: options.scope,
+		expires: options.expires,
+		...options.notBefore !== void 0 ? { "not-before": options.notBefore } : {},
+		...parentBytes !== void 0 ? { parent: parentBytes } : {},
+		...options.delegationsRemaining !== void 0 ? { "delegations-remaining": options.delegationsRemaining } : {},
+		...options.conditions !== void 0 ? { conditions: encodeBuf(options.conditions) } : {},
+		...authorisationBytes !== void 0 ? { "authorised-by": authorisationBytes } : {},
+		...options.grantsCapability !== void 0 ? { "grants-capability": options.grantsCapability } : {},
+		...options.requestsCapability !== void 0 ? { "requests-capability": options.requestsCapability } : {}
+	});
+	const protectedHeader = protectedHeaderFor(options.identity);
+	return {
+		ok: true,
+		token: [
+			protectedHeader,
+			{},
+			payload,
+			await options.identity.sign(sig1ToBeSigned(protectedHeader, payload))
+		]
+	};
+}
+/** Mints one revocation-entry (management.cddl): a COSE_Sign1 over revocation-claims, signed the same way mintCapabilityToken signs a token. No narrowing chain to check -- a revocation entry has no parent and cannot fail to be issuable the way a delegated token can, so this returns the entry directly rather than a verdict. */
+async function mintRevocationEntry(options) {
+	const payload = encodeBuf({
+		"token-id": options.tokenId,
+		issuer: options.identity.deviceId,
+		"issuer-key": options.identity.identityKey,
+		"revoked-at": options.revokedAt
+	});
+	const protectedHeader = protectedHeaderFor(options.identity);
+	return [
+		protectedHeader,
+		{},
+		payload,
+		await options.identity.sign(sig1ToBeSigned(protectedHeader, payload))
+	];
+}
+//#endregion
 export { MANAGE_GRANT_CAPABILITY, canGrant, canGrantVia, mintCapabilityToken, mintRevocationEntry, sig1ToBeSigned, verifyCapabilityToken, verifyRevocationEntry };

package/dist/domain/topology-snapshot.d.cts

@@ -1,4 +1,4 @@
-import { D as DeviceId, nn as TopologyPeers } from "../protocol-BgR1e_NI.cjs";
+import { D as DeviceId, nn as TopologyPeers } from "../protocol-DzmpxxUr.cjs";
 //#region src/domain/topology-snapshot.d.ts
 export interface TopologyPeersInputs {
   /** connection?.peerDeviceId -- the transport-authenticated direct peer, when the adapter gives one. Takes priority over firstAdvertisedPeer below. */

package/dist/domain/topology-snapshot.d.mts

@@ -1,4 +1,4 @@
-import { D as DeviceId, nn as TopologyPeers } from "../protocol-BgR1e_NI.mjs";
+import { D as DeviceId, nn as TopologyPeers } from "../protocol-DzmpxxUr.mjs";
 //#region src/domain/topology-snapshot.d.ts
 export interface TopologyPeersInputs {
   /** connection?.peerDeviceId -- the transport-authenticated direct peer, when the adapter gives one. Takes priority over firstAdvertisedPeer below. */

package/dist/domain/topology.d.cts

@@ -1,4 +1,4 @@
-import { D as DeviceId, V as ManageCommand, et as PeerAdvert, nn as TopologyPeers } from "../protocol-BgR1e_NI.cjs";
+import { D as DeviceId, V as ManageCommand, et as PeerAdvert, nn as TopologyPeers } from "../protocol-DzmpxxUr.cjs";
 import { DirectoryEntry, IncomingManageRequest, MeshSession } from "./mesh-session.cjs";
 //#region src/domain/topology.d.ts
 export declare const TOPOLOGY_GET_CAPABILITY = "topology:get";

package/dist/domain/topology.d.mts

@@ -1,4 +1,4 @@
-import { D as DeviceId, V as ManageCommand, et as PeerAdvert, nn as TopologyPeers } from "../protocol-BgR1e_NI.mjs";
+import { D as DeviceId, V as ManageCommand, et as PeerAdvert, nn as TopologyPeers } from "../protocol-DzmpxxUr.mjs";
 import { DirectoryEntry, IncomingManageRequest, MeshSession } from "./mesh-session.mjs";
 //#region src/domain/topology.d.ts
 export declare const TOPOLOGY_GET_CAPABILITY = "topology:get";