wire-mesh-core 3.8.0 → 3.10.0

package/dist/tokens-BMWCnQEF.d.cts

@@ -1,158 +0,0 @@
-import { B as IdentityKey, D as DeviceId, bt as RevocationEntry, en as TokenClaims, p as CapabilityToken, yt as RevocationClaims } from "./protocol-BgR1e_NI.cjs";
-import { t as IdentityPort } from "./identity-DJbr96J3.cjs";
-import { t as Clock } from "./clock-DiSx-WKM.cjs";
-import { z } from "zod";
-import { JsonValue, PredicateNode, Resolution } from "trilean";
-//#region src/domain/token-predicates.d.ts
-/** Everything needed to check candidate against parent, restated from tokens.ts's own NarrowingCandidate/checkNarrowing shape rather than requiring a full TokenClaims for the not-yet-minted child -- the same reasoning mintCapabilityToken's own checkNarrowing already applies (a delegation candidate has no token-id/issuer-key/bearer of its own yet). camelCase field names, matching NarrowingCandidate's own convention, deliberately distinct from TokenClaims' hyphenated wire field names. */
-interface NarrowingCandidate {
-  capability: TokenClaims["capability"];
-  scope: TokenClaims["scope"];
-  expires: number;
-  delegationsRemaining?: number;
-}
-/** A `conditions` entry's own generic evaluation context: no parent/candidate distinction, since a domain-specific condition (a message TTL, a future revoke-authorization check) reasons about the presented token's own claims directly, not a not-yet-minted delegation candidate. */
-interface ConditionsContext {
-  readonly clock: Clock;
-  readonly claims: Readonly<TokenClaims>;
-  /** The minted child a grant-capability's conditions are being evaluated against (wire-mesh#323 subject mode): present only inside an authorised-by verification walk or a mint-time authorisation check, never when a token's conditions are evaluated against its own claims. */
-  readonly subject?: Readonly<GrantSubject>;
-}
-/** The child half of a subject-mode conditions evaluation: the claims of the token a grant-capability authorises, structurally what NarrowingCandidate already is plus the bearer the mint named. Satisfied by a full TokenClaims, so the verifier passes the child's decoded claims directly. */
-interface GrantSubject {
-  capability: TokenClaims["capability"];
-  scope: TokenClaims["scope"];
-  bearer: DeviceId;
-  expires: number;
-  delegationsRemaining?: number;
-}
-/** One delegate system's own handler: given the delegate node's payload and the concrete context it was invoked with, resolves to a boolean-valued Resolution. Handlers never throw for a data-quality problem -- an op that cannot make sense of its own payload/context returns `{found: false}`, which the evaluator turns into a fail-closed `indeterminate`. */
-type TokenDelegateHandler<TContext> = (payload: JsonValue, context: TContext) => Resolution | Promise<Resolution>;
-//#endregion
-//#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. */
-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.
- */
-interface RevocationCheck {
-  entriesFor: (tokenId: Uint8Array) => Promise<readonly RevocationClaims[]>;
-}
-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";
-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;
-};
-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. */
-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.
- */
-declare function verifyCapabilityToken(token: CapabilityToken, options: VerifyCapabilityTokenOptions): Promise<TokenVerdict>;
-type RevocationEntryVerdictReason = "malformed" | "bad_signature" | "wrong_issuer";
-type RevocationEntryVerdict = {
-  ok: true;
-  claims: RevocationClaims;
-} | {
-  ok: false;
-  reason: RevocationEntryVerdictReason;
-};
-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.
- */
-declare function verifyRevocationEntry(entry: RevocationEntry, options: VerifyRevocationEntryOptions): Promise<RevocationEntryVerdict>;
-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";
-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.
- */
-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). */
-declare function canGrantVia(heldGrantCapability: CapabilityToken, deviceId: DeviceId, candidate: Readonly<GrantSubject>, now: number): Promise<boolean>;
-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.
- */
-declare function mintCapabilityToken(options: MintCapabilityTokenOptions): Promise<MintVerdict>;
-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. */
-declare function mintRevocationEntry(options: MintRevocationEntryOptions): Promise<RevocationEntry>;
-//#endregion
-export { sig1ToBeSigned as _, MintVerdict as a, ConditionsContext as b, RevocationEntryVerdictReason as c, VerifyCapabilityTokenOptions as d, VerifyRevocationEntryOptions as f, mintRevocationEntry as g, mintCapabilityToken as h, MintRevocationEntryOptions as i, TokenVerdict as l, canGrantVia as m, MintCapabilityTokenOptions as n, RevocationCheck as o, canGrant as p, MintRefusalReason as r, RevocationEntryVerdict as s, MANAGE_GRANT_CAPABILITY as t, TokenVerdictReason as u, verifyCapabilityToken as v, TokenDelegateHandler as x, verifyRevocationEntry as y };