wire-mesh-core 1.18.0 → 1.19.0

package/dist/domain/tokens.cjs

@@ -1,316 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_generated_protocol = require("../generated/protocol.cjs");
-let cbor2 = require("cbor2");
-//#region src/domain/tokens.ts
-function bytesEqual(a, b) {
-	if (a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
-	return true;
-}
-/** True when the path contains a "." or ".." segment. Purely lexical prefix comparison would let "/work/../org" pass under "/work" -- a path that normalises outside the parent -- so any relative segment fails the narrowing comparison wholesale: fail-closed rather than reimplementing path normalisation, consistent with how empty, case-different, and non-boundary-prefixed paths already behave. */
-function hasRelativeSegment(path) {
-	return path.split("/").some((segment) => segment === "." || segment === "..");
-}
-/** True when childPath is parentPath or a descendant of it, compared on "/"-segment boundaries: "/work/sub" narrows "/work", but "/workbook" does NOT narrow "/work" despite the string prefix, because "book" continues the same segment. Paths containing "." or ".." segments never narrow anything (see hasRelativeSegment). */
-function pathNarrows(childPath, parentPath) {
-	if (hasRelativeSegment(childPath) || hasRelativeSegment(parentPath)) return false;
-	if (childPath === parentPath) return true;
-	if (!childPath.startsWith(parentPath)) return false;
-	if (parentPath.endsWith("/")) return true;
-	return childPath.charAt(parentPath.length) === "/";
-}
-/**
-* True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain.
-*/
-function scopeNarrows(parent, child) {
-	if (parent.kind !== child.kind) return false;
-	if (parent.path === void 0) return true;
-	if (child.path === void 0) return false;
-	return pathNarrows(child.path, parent.path);
-}
-/** RFC 9052 §4.4 Sig_structure for a COSE_Sign1 with no external AAD: ["Signature1", protected, external_aad, payload]. */
-function sig1ToBeSigned(protectedHeader, payload) {
-	return (0, cbor2.encode)([
-		"Signature1",
-		protectedHeader,
-		/* @__PURE__ */ new Uint8Array(0),
-		payload
-	], cbor2.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((0, cbor2.encode)(value, cbor2.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 = (0, cbor2.decode)(payload, cbor2.cdeDecodeOptions);
-	} catch {
-		return;
-	}
-	const result = require_generated_protocol.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
-	});
-	if (!verdict.ok) return verdict;
-	if (options.expectedBearer !== void 0 && !bytesEqual(verdict.claims.bearer, options.expectedBearer)) return {
-		ok: false,
-		reason: "bearer_mismatch"
-	};
-	return verdict;
-}
-async function verifyTokenChain(token, options) {
-	const [protectedHeader, , payload, signature] = token;
-	if (payload === null) return {
-		ok: false,
-		reason: "malformed"
-	};
-	let decodedClaims;
-	try {
-		decodedClaims = (0, cbor2.decode)(payload, cbor2.cdeDecodeOptions);
-	} catch {
-		return {
-			ok: false,
-			reason: "malformed"
-		};
-	}
-	const claimsResult = require_generated_protocol.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"
-	};
-	if (!bytesEqual(await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]), 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"
-	};
-	if (await options.revocation.isRevoked(claims["token-id"], claims.issuer)) return {
-		ok: false,
-		reason: "revoked"
-	};
-	if (claims.parent !== void 0) {
-		let decodedParent;
-		try {
-			decodedParent = (0, cbor2.decode)(claims.parent, cbor2.cdeDecodeOptions);
-		} catch {
-			return {
-				ok: false,
-				reason: "parent_invalid"
-			};
-		}
-		const parentResult = require_generated_protocol.capabilityTokenSchema.safeParse(decodedParent);
-		if (!parentResult.success) return {
-			ok: false,
-			reason: "parent_invalid"
-		};
-		const parentVerdict = await verifyTokenChain(parentResult.data, options);
-		if (!parentVerdict.ok) return {
-			ok: false,
-			reason: "parent_invalid"
-		};
-		if (!bytesEqual(parentVerdict.claims.bearer, claims.issuer)) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
-		};
-		if (claims.expires > parentVerdict.claims.expires) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
-		};
-		if (!scopeNarrows(parentVerdict.claims.scope, claims.scope)) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
-		};
-		if (parentVerdict.claims.capability !== claims.capability) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
-		};
-		const parentRemaining = parentVerdict.claims["delegations-remaining"];
-		if (parentRemaining !== void 0 && (claims["delegations-remaining"] === void 0 || claims["delegations-remaining"] >= parentRemaining)) return {
-			ok: false,
-			reason: "delegation_exceeds_parent"
-		};
-		return {
-			ok: true,
-			claims,
-			rootIssuer: parentVerdict.rootIssuer,
-			depth: parentVerdict.depth + 1
-		};
-	}
-	return {
-		ok: true,
-		claims,
-		rootIssuer: claims.issuer,
-		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 = (0, cbor2.decode)(payload, cbor2.cdeDecodeOptions);
-	} catch {
-		return {
-			ok: false,
-			reason: "malformed"
-		};
-	}
-	const claimsResult = require_generated_protocol.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"
-	};
-	if (!bytesEqual(await options.identity.deriveDeviceId(claims["issuer-key"]["public-key"]), claims.issuer)) return {
-		ok: false,
-		reason: "wrong_issuer"
-	};
-	return {
-		ok: true,
-		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).
-*
-* 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"
-	};
-	let parentBytes;
-	if (options.parent !== void 0) {
-		const parentClaims = decodeTokenClaims(options.parent);
-		if (parentClaims === void 0) return {
-			ok: false,
-			reason: "parent_malformed"
-		};
-		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: refusal
-		};
-		parentBytes = encodeBuf(options.parent);
-	}
-	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 } : {}
-	});
-	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
-exports.canGrant = canGrant;
-exports.mintCapabilityToken = mintCapabilityToken;
-exports.mintRevocationEntry = mintRevocationEntry;
-exports.scopeNarrows = scopeNarrows;
-exports.verifyCapabilityToken = verifyCapabilityToken;
-exports.verifyRevocationEntry = verifyRevocationEntry;
+const require_tokens = require("../tokens-BxTxBmXt.cjs");
+exports.canGrant = require_tokens.canGrant;
+exports.mintCapabilityToken = require_tokens.mintCapabilityToken;
+exports.mintRevocationEntry = require_tokens.mintRevocationEntry;
+exports.verifyCapabilityToken = require_tokens.verifyCapabilityToken;
+exports.verifyRevocationEntry = require_tokens.verifyRevocationEntry;

package/dist/domain/tokens.d.cts

@@ -1,104 +1,2 @@
-import { dt as RevocationEntry, kt as TokenClaims, s as CapabilityToken, ut as RevocationClaims, x as DeviceId } from "../protocol-Dhswk7YD.cjs";
-import { t as IdentityPort } from "../identity-BldV8xFj.cjs";
-import { t as Clock } from "../clock-DiSx-WKM.cjs";
-//#region src/domain/tokens.d.ts
-/**
- * The revocation view a verifier consults. Contract per management.cddl: an entry counts against a token only when BOTH its token-id and its issuer match the token's own -- only a token's own issuer may revoke it, so a third party's entry for someone else's token-id must be ignored. 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 + issuer.
- */
-export interface RevocationCheck {
-  isRevoked: (tokenId: Uint8Array, issuer: DeviceId) => Promise<boolean>;
-}
-export type TokenVerdictReason = "malformed" | "bad_signature" | "wrong_issuer" | "bearer_mismatch" | "expired" | "not_yet_valid" | "content_expired" | "revoked" | "delegation_exceeds_parent" | "parent_invalid";
-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;
-  /** 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;
-}
-/**
- * True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain.
- */
-export declare function scopeNarrows(parent: TokenClaims["scope"], child: TokenClaims["scope"]): boolean;
-/**
- * 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";
-export type MintVerdict = {
-  ok: true;
-  token: CapabilityToken;
-} | {
-  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;
-  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;
-}
-/**
- * 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
+import { a as RevocationCheck, c as TokenVerdict, d as VerifyRevocationEntryOptions, f as canGrant, g as verifyRevocationEntry, h as verifyCapabilityToken, i as MintVerdict, l as TokenVerdictReason, m as mintRevocationEntry, n as MintRefusalReason, o as RevocationEntryVerdict, p as mintCapabilityToken, r as MintRevocationEntryOptions, s as RevocationEntryVerdictReason, t as MintCapabilityTokenOptions, u as VerifyCapabilityTokenOptions } from "../tokens-D2aFwPcZ.cjs";
+export { MintCapabilityTokenOptions, MintRefusalReason, MintRevocationEntryOptions, MintVerdict, RevocationCheck, RevocationEntryVerdict, RevocationEntryVerdictReason, TokenVerdict, TokenVerdictReason, VerifyCapabilityTokenOptions, VerifyRevocationEntryOptions, canGrant, mintCapabilityToken, mintRevocationEntry, verifyCapabilityToken, verifyRevocationEntry };

package/dist/domain/tokens.d.mts

@@ -1,104 +1,2 @@
-import { dt as RevocationEntry, kt as TokenClaims, s as CapabilityToken, ut as RevocationClaims, x as DeviceId } from "../protocol-Dhswk7YD.mjs";
-import { t as IdentityPort } from "../identity-B1hBV3YA.mjs";
-import { t as Clock } from "../clock-DiSx-WKM.mjs";
-//#region src/domain/tokens.d.ts
-/**
- * The revocation view a verifier consults. Contract per management.cddl: an entry counts against a token only when BOTH its token-id and its issuer match the token's own -- only a token's own issuer may revoke it, so a third party's entry for someone else's token-id must be ignored. 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 + issuer.
- */
-export interface RevocationCheck {
-  isRevoked: (tokenId: Uint8Array, issuer: DeviceId) => Promise<boolean>;
-}
-export type TokenVerdictReason = "malformed" | "bad_signature" | "wrong_issuer" | "bearer_mismatch" | "expired" | "not_yet_valid" | "content_expired" | "revoked" | "delegation_exceeds_parent" | "parent_invalid";
-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;
-  /** 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;
-}
-/**
- * True when childScope narrows parentScope per tokens.cddl ("each hop can only narrow authority, never widen it"): the kind must be identical (a different kind is a different kind of authority, not a narrower one), and a parent with a path requires the child to carry an equal-or-descendant path -- an absent child path means the kind's whole-scope root, which is wider than any path-narrowed parent. A parent with no path (whole-scope root) lets any child path under the same kind through. Exported for capability-grant.ts's own obligation 4 (an unsolicited push's embedded token must equal-or-root the enclosing request's own scope), which is exactly this same narrowing relation applied outside a delegation chain.
- */
-export declare function scopeNarrows(parent: TokenClaims["scope"], child: TokenClaims["scope"]): boolean;
-/**
- * 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";
-export type MintVerdict = {
-  ok: true;
-  token: CapabilityToken;
-} | {
-  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;
-  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;
-}
-/**
- * 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
+import { a as RevocationCheck, c as TokenVerdict, d as VerifyRevocationEntryOptions, f as canGrant, g as verifyRevocationEntry, h as verifyCapabilityToken, i as MintVerdict, l as TokenVerdictReason, m as mintRevocationEntry, n as MintRefusalReason, o as RevocationEntryVerdict, p as mintCapabilityToken, r as MintRevocationEntryOptions, s as RevocationEntryVerdictReason, t as MintCapabilityTokenOptions, u as VerifyCapabilityTokenOptions } from "../tokens-DSwixfDl.mjs";
+export { MintCapabilityTokenOptions, MintRefusalReason, MintRevocationEntryOptions, MintVerdict, RevocationCheck, RevocationEntryVerdict, RevocationEntryVerdictReason, TokenVerdict, TokenVerdictReason, VerifyCapabilityTokenOptions, VerifyRevocationEntryOptions, canGrant, mintCapabilityToken, mintRevocationEntry, verifyCapabilityToken, verifyRevocationEntry };