@cotal-ai/core 0.12.0 → 0.13.0

package/dist/endpoint-handle.js

@@ -0,0 +1,608 @@
+/**
+ * The CAPABILITY HANDLE (SPEC §13.6): the one passable reference type — a signed JSON grant,
+ * RFC 8785 canonical, Ed25519-signed by a key in the trust-anchor registry (§13.10).
+ *
+ * This module owns the transport-thin CORE of the handle: the artifact shape + closed-tuple
+ * validation, the NORMATIVE COMPILER (a grant entry → exactly the subjects the equivalent
+ * minted capability would receive, never wider — reads and instance rails included, every
+ * present signed component consumed), the ATTENUATION CONTAINMENT ORDER (a child handle MUST
+ * be ⊆ its parent), and CHAIN VERIFICATION (walk every parentDigest link to a registered
+ * anchor, fail closed on widening / unknown / revoked / expiry). Conferral — REDEMPTION
+ * through the trusted auth path, which fresh-checks the target triple against the current
+ * mapping and mints a ledgered short-lived credential — is the §9/§10 exchange's job (the D14
+ * auth-path slice); a handle grants NO broker reach here, only narrows.
+ *
+ * Verification discipline (§13.10 D28): the signature and the parentDigest identity are
+ * checked over the EXACT RAW presented artifacts, never a reconstructed projection — the
+ * parsed projection is for SEMANTICS only. Issuer authority is the anchor's STRUCTURED
+ * `handles` scope (ceiling entries in the handle-grant shape itself); coverage is the SAME
+ * §13.6 containment order (`handle.grants ⊆ anchor.scope`). A child link's issuer key must be
+ * lifecycle-bound to the parent's holder (owner text alone would let a recycled alias issue
+ * off its predecessor's handles). Every link — not only the leaf — is currency-checked
+ * (window, TTL ceilings clock-anchored at `now`, live-epoch), sturdy revocation is
+ * strict-`false`-only (an unreadable status is REVOKED), and the whole walk is bounded
+ * (chain length + ONE total await budget across the walk).
+ *
+ * Two uses, both fail-closed: ATTENUATION (presented in the `auth` slot — the handler enforces
+ * effective = presenter-cred ∩ handle.grants ∩ issuer-authority, never conferring reach) and
+ * CONFERRAL (redemption). Both rest on the same containment + chain verification here.
+ */
+import { contractDigest, isContractDigest, canonicalJson } from "./canonical.js";
+import { EpEnvelopeError } from "./endpoint-envelope.js";
+import { assertBoundedOwner, assertLifecycleToken, assertCommandToken, endpointToken, EP_AUTHZ_MODES } from "./endpoint-subjects.js";
+import { verifyArtifactSignature, resolveAnchorForUse, assertArtifactCurrency } from "./endpoint-signing.js";
+const isRec = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+function invalid(what) { throw new EpEnvelopeError("contract-invalid", `${what} (SPEC 13.6 capability handle)`); }
+/** The §13.6 default validity ceilings (space-configurable): live ≤ 24h, sturdy default 30d. */
+export const HANDLE_MAX_LIVE_TTL_MS = 24 * 60 * 60 * 1000;
+export const HANDLE_MAX_STURDY_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** Verification bounds (fail loud past each; a bound reached is a refusal, never a truncation). */
+export const HANDLE_MAX_CHAIN_LENGTH = 16;
+export const HANDLE_MAX_BYTES = 64 * 1024;
+export const HANDLE_MAX_GRANTS = 64;
+export const HANDLE_MAX_COMMANDS_PER_GRANT = 64;
+export const HANDLE_MAX_READS_PER_GRANT = 64;
+/** Bounded canonical token grammars (§13.6 consuming boundary): id/space/keyId are bounded
+ *  opaque tokens; the holder principal id is `owner` or `owner.actor` reverse-form. A garbled
+ *  token is a CATALOG error (`contract-invalid`), never a raw validator throw. */
+const HANDLE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function assertHandleToken(v, what) {
+    if (typeof v !== "string" || !HANDLE_TOKEN.test(v))
+        invalid(`${what} is not a bounded canonical token (1..128 of [A-Za-z0-9._:-], leading alnum)`);
+    return v;
+}
+function parseGrantCommand(raw) {
+    if (!isRec(raw))
+        invalid("a grant command is not an object");
+    const o = raw;
+    const allowed = new Set(["name", "authz", "targetOwner", "targetActor", "targetLifecycleUid"]);
+    for (const k of Object.keys(o))
+        if (!allowed.has(k))
+            invalid(`a grant command carries the unknown field "${k}" (closed schema)`);
+    if (typeof o.name !== "string")
+        invalid("a grant command has no string name");
+    assertCommandToken(o.name);
+    const hasOwner = o.targetOwner !== undefined, hasActor = o.targetActor !== undefined, hasUid = o.targetLifecycleUid !== undefined;
+    const hasAuthz = o.authz !== undefined;
+    // The closed set of three target shapes (§13.6). The parsed projection stays BYTE-FAITHFUL
+    // to the signed form (no default injection — `authz ?? "owner"` applies at USE time), so the
+    // projection can never diverge from the D28 signature input.
+    if (!hasOwner && !hasActor && !hasUid) {
+        // NO-TARGET: an `authz` field is schema-invalid.
+        if (hasAuthz)
+            invalid(`command "${o.name}" is a no-target entry but carries authz (schema-invalid: a no-target entry compiles to the untargeted/self form)`);
+        return { name: o.name };
+    }
+    if (hasOwner && !hasActor && !hasUid) {
+        // OWNER-DOMAIN: authz names owner|child|ledger (default owner); `any` is schema-invalid.
+        if (typeof o.targetOwner !== "string")
+            invalid(`command "${o.name}" targetOwner is not a string`);
+        assertBoundedOwner(o.targetOwner, `command "${o.name}" targetOwner`);
+        if (hasAuthz && o.authz !== "owner" && o.authz !== "child" && o.authz !== "ledger")
+            invalid(`command "${o.name}" authz "${String(o.authz)}" is not owner|child|ledger ("any" is operator-ceiling authority, never conferred through a handle)`);
+        return { name: o.name, ...(hasAuthz ? { authz: o.authz } : {}), targetOwner: o.targetOwner };
+    }
+    if (hasOwner && hasActor && hasUid) {
+        // ACTOR-PINNED FULL TRIPLE: `authz` is schema-invalid (the triple IS the mode).
+        if (hasAuthz)
+            invalid(`command "${o.name}" pins the full target triple but also carries authz (schema-invalid: the triple IS the handle mode)`);
+        if (typeof o.targetOwner !== "string" || typeof o.targetActor !== "string" || typeof o.targetLifecycleUid !== "string")
+            invalid(`command "${o.name}" target triple components must all be strings`);
+        assertBoundedOwner(o.targetOwner, `command "${o.name}" targetOwner`);
+        assertBoundedOwner(o.targetActor, `command "${o.name}" targetActor`);
+        assertLifecycleToken(o.targetLifecycleUid, `command "${o.name}" targetLifecycleUid`);
+        return { name: o.name, targetOwner: o.targetOwner, targetActor: o.targetActor, targetLifecycleUid: o.targetLifecycleUid };
+    }
+    // Every other combination is schema-invalid — in particular a partial tuple never weakens
+    // into a broader one (§13.6): targetActor without targetLifecycleUid, or targetLifecycleUid
+    // without targetActor, or owner+actor without uid.
+    invalid(`command "${o.name}" has a partial target tuple (${[hasOwner && "owner", hasActor && "actor", hasUid && "uid"].filter(Boolean).join("+")}); the legal shapes are no components, targetOwner alone, or the full triple; a partial tuple never weakens into a broader grant`);
+}
+/** A read scope names an exact record-key or event-topic SUBTREE (§13.6): dot-separated
+ *  literal tokens in the ONE token grammar record keys are built from (the §3 subject charset,
+ *  which the §13.7 key qualifiers use: [A-Za-z0-9_-], 1..64 per token), never a wildcard — the
+ *  subtree semantics live in the containment order (dot-prefix), not in the entry. The grammar
+ *  is exactly the key grammar on purpose: a wider charset would mint inert grants naming keys
+ *  that can never exist (and that a conforming implementation refuses — a divergence in a
+ *  normative compiler), while a narrower one would make legal keys (a `_`-leading goalId)
+ *  unreachable by any grant. */
+const READ_TOKEN = /^[A-Za-z0-9_-]{1,64}$/;
+function assertReadSubtree(r, endpoint) {
+    if (typeof r !== "string" || r.length === 0 || r.length > 256)
+        invalid(`grant entry for "${endpoint}" read scope is not a bounded string (1..256)`);
+    const tokens = r.split(".");
+    if (tokens.length > 16 || tokens.some((t) => !READ_TOKEN.test(t)))
+        invalid(`grant entry for "${endpoint}" read scope "${r}" is not a bounded literal dot-token subtree (at most 16 tokens of 1..64 [A-Za-z0-9_-]; no wildcards)`);
+    return r;
+}
+function parseGrant(raw) {
+    if (!isRec(raw))
+        invalid("a grant entry is not an object");
+    const o = raw;
+    for (const k of Object.keys(o))
+        if (!["endpoint", "instanceId", "commands", "reads"].includes(k))
+            invalid(`a grant entry carries the unknown field "${k}"`);
+    if (typeof o.endpoint !== "string")
+        invalid("a grant entry has no string endpoint");
+    endpointToken(o.endpoint);
+    if (o.instanceId !== undefined) {
+        try {
+            assertLifecycleToken(o.instanceId, "grant instanceId");
+        }
+        catch (e) {
+            invalid(e.message);
+        }
+    }
+    if (!Array.isArray(o.commands) || o.commands.length === 0)
+        invalid(`grant entry for "${o.endpoint}" has no commands`);
+    if (o.commands.length > HANDLE_MAX_COMMANDS_PER_GRANT)
+        invalid(`grant entry for "${o.endpoint}" exceeds ${HANDLE_MAX_COMMANDS_PER_GRANT} commands (bounded, never truncated)`);
+    const commands = o.commands.map(parseGrantCommand);
+    let reads;
+    if (o.reads !== undefined) {
+        if (!Array.isArray(o.reads))
+            invalid(`grant entry for "${o.endpoint}" has a non-array reads`);
+        if (o.reads.length > HANDLE_MAX_READS_PER_GRANT)
+            invalid(`grant entry for "${o.endpoint}" exceeds ${HANDLE_MAX_READS_PER_GRANT} read subtrees (bounded)`);
+        reads = o.reads.map((r) => assertReadSubtree(r, o.endpoint));
+    }
+    return { endpoint: o.endpoint, ...(o.instanceId !== undefined ? { instanceId: o.instanceId } : {}), commands, ...(reads !== undefined ? { reads } : {}) };
+}
+/** Validate a handle artifact's SHAPE (the closed-tuple rules + envelope), returning the typed
+ *  frozen handle. This is the schema step; signature + chain + currency are the verify step
+ *  ({@link verifyHandleChain}) — and those verify the RAW presented artifact, never this
+ *  projection. A `sturdy: false` handle MUST carry `epoch`; a `sturdy: true` handle MUST NOT
+ *  (§13.6: live binds the process epoch, sturdy binds the lifecycle UID). */
+export function parseHandle(raw) {
+    if (!isRec(raw))
+        invalid("the handle is not an object");
+    const o = raw;
+    const allowed = new Set(["v", "id", "space", "issuer", "holder", "grants", "iat", "nbf", "exp", "parentDigest", "sturdy", "epoch", "sig"]);
+    for (const k of Object.keys(o))
+        if (!allowed.has(k))
+            invalid(`the handle carries the unknown field "${k}" (closed envelope)`);
+    if (o.v !== 1)
+        invalid("the handle version is not 1");
+    assertHandleToken(o.id, "the handle id");
+    assertHandleToken(o.space, "the handle space");
+    if (!isRec(o.issuer))
+        invalid("the handle issuer is not an object");
+    for (const k of Object.keys(o.issuer))
+        if (k !== "keyId")
+            invalid(`the handle issuer carries the unknown field "${k}" (closed schema)`);
+    assertHandleToken(o.issuer.keyId, "the handle issuer keyId");
+    if (!isRec(o.holder))
+        invalid("the handle holder is not an object");
+    for (const k of Object.keys(o.holder))
+        if (k !== "id" && k !== "lifecycleUid")
+            invalid(`the handle holder carries the unknown field "${k}" (closed schema)`);
+    assertHandleToken(o.holder.id, "the handle holder id");
+    {
+        const uid = o.holder.lifecycleUid;
+        if (typeof uid !== "string")
+            invalid("the handle holder lifecycleUid is not a string");
+        try {
+            assertLifecycleToken(uid, "the handle holder lifecycleUid");
+        }
+        catch (e) {
+            invalid(e.message);
+        }
+    }
+    if (!Array.isArray(o.grants) || o.grants.length === 0)
+        invalid("the handle has no grants");
+    if (o.grants.length > HANDLE_MAX_GRANTS)
+        invalid(`the handle exceeds ${HANDLE_MAX_GRANTS} grant entries (bounded, never truncated)`);
+    // Any token-validator throw inside a grant becomes a CATALOG contract-invalid error (§13.6:
+    // the consuming boundary never surfaces a raw validator throw).
+    let grants;
+    try {
+        grants = o.grants.map(parseGrant);
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError)
+            throw e;
+        invalid(`a grant entry has an invalid token: ${e.message}`);
+    }
+    for (const f of ["iat", "exp"])
+        if (typeof o[f] !== "number" || !Number.isSafeInteger(o[f]) || o[f] < 0)
+            invalid(`the handle ${f} is not a non-negative safe integer`);
+    if (o.nbf !== undefined && (typeof o.nbf !== "number" || !Number.isSafeInteger(o.nbf) || o.nbf < 0))
+        invalid("the handle nbf is not a non-negative safe integer");
+    if (o.exp <= o.iat)
+        invalid("the handle exp is not after iat");
+    if (o.nbf !== undefined && o.nbf > o.exp)
+        invalid("the handle nbf is after exp (an empty validity window is garbled, not a short one)");
+    if (o.parentDigest !== undefined && (typeof o.parentDigest !== "string" || !isContractDigest(o.parentDigest)))
+        invalid("the handle parentDigest is not a sha256 digest");
+    if (typeof o.sturdy !== "boolean")
+        invalid("the handle sturdy flag is not a boolean");
+    if (o.sturdy === false && (typeof o.epoch !== "number" || !Number.isSafeInteger(o.epoch) || o.epoch < 0))
+        invalid("a LIVE handle (sturdy:false) MUST carry a non-negative integer epoch (it binds the process epoch)");
+    if (o.sturdy === true && o.epoch !== undefined)
+        invalid("a STURDY handle MUST NOT carry epoch (it binds the lifecycle UID, not a process epoch)");
+    if (typeof o.sig !== "string")
+        invalid("the handle has no sig");
+    return Object.freeze({
+        v: 1, id: o.id, space: o.space, issuer: { keyId: o.issuer.keyId },
+        holder: { id: o.holder.id, lifecycleUid: o.holder.lifecycleUid },
+        grants, iat: o.iat, ...(o.nbf !== undefined ? { nbf: o.nbf } : {}), exp: o.exp,
+        ...(o.parentDigest !== undefined ? { parentDigest: o.parentDigest } : {}), sturdy: o.sturdy,
+        ...(o.epoch !== undefined ? { epoch: o.epoch } : {}), sig: o.sig,
+    });
+}
+/** The handle's content address (`sha256:<hex>` over the full artifact incl. `sig`) — the
+ *  identity a child's `parentDigest` references. Chain verification computes this over the
+ *  RAW presented artifact ({@link verifyHandleChain}); this export is for issuance (building
+ *  a child's `parentDigest` from the parent artifact you hold). */
+export function handleDigest(handle) {
+    return contractDigest(handle);
+}
+/** Compile ONE grant command to the {@link EpTarget} the equivalent minted capability carries
+ *  (never wider): a no-target command → the untargeted form or `.self` PER ITS CONTRACT; an
+ *  owner-domain command → its authz mode pinning `targetOwner`; an actor-pinned command →
+ *  `handle`-mode with the verified triple. Every present signed component is consumed. */
+function compileTarget(cmd, contract) {
+    if (cmd.targetOwner === undefined)
+        return contract.noTargetForm === "self" ? { mode: "self" } : undefined;
+    if (cmd.targetActor !== undefined && cmd.targetLifecycleUid !== undefined)
+        return { mode: "handle", tOwner: cmd.targetOwner, tActor: cmd.targetActor, tUid: cmd.targetLifecycleUid };
+    return { mode: (cmd.authz ?? "owner"), tOwner: cmd.targetOwner };
+}
+/** Compile a handle's grants to the EpCapability set + read subtrees the equivalent minted
+ *  capability would receive (§13.6). This is what a redemption mints and what attenuation
+ *  intersects against; it NEVER widens and consumes EVERY signed component:
+ *   - `routes` is set EXPLICITLY: an instance entry compiles to the exact `ep.inst` rails
+ *     ONLY (`routes: []` — an instance pin never also grants the class rail); a class entry
+ *     compiles to `routes: ["one"]` (scatter `all` is not expressible in a handle);
+ *   - a NO-TARGET command's untargeted-vs-`.self` form and the `journal` rail come from the
+ *     REQUIRED command-contract seam (the compiler never guesses either);
+ *   - a JOURNAL-class command compiles to a journal-EXCLUSIVE capability (`routes: []`, no
+ *     request rails): journal submissions ride ONLY `epj` (§13.9), so emitting a request row
+ *     alongside would be equivalent-mint WIDENING. The frozen `epj` grammar has no instance
+ *     coordinate, so an instance-pinned journal command is UNREPRESENTABLE and refuses — the
+ *     signed instance pin is never silently dropped onto a class-wide journal row;
+ *   - `reads` are returned alongside, endpoint-bound, never dropped. */
+export function compileHandleGrants(handle, opts) {
+    if (typeof opts?.commandContract !== "function")
+        throw new EpEnvelopeError("failed-precondition", "compiling handle grants requires the command-contract seam; the compiler never guesses a command's no-target form or journal class (SPEC 13.6/13.9)");
+    const caps = [];
+    const reads = [];
+    for (const g of handle.grants) {
+        for (const cmd of g.commands) {
+            const contract = opts.commandContract(g.endpoint, cmd.name);
+            if (!contract || (contract.noTargetForm !== "untargeted" && contract.noTargetForm !== "self") || typeof contract.journal !== "boolean")
+                throw new EpEnvelopeError("internal", `the command-contract seam returned a malformed contract for ${g.endpoint}.${cmd.name}; a garbled contract never compiles (SPEC 13.6)`);
+            const target = compileTarget(cmd, contract);
+            if (contract.journal) {
+                if (g.instanceId !== undefined)
+                    throw new EpEnvelopeError("permission-denied", `grant entry for "${g.endpoint}" pins instance "${g.instanceId}" but command "${cmd.name}" is journal-class; the frozen epj grammar has no instance coordinate, so the signed instance pin cannot be honored - unrepresentable, refused rather than widened (SPEC 13.6/13.9)`);
+                caps.push({
+                    endpoint: g.endpoint, command: cmd.name,
+                    routes: [],
+                    ...(target !== undefined ? { target } : {}),
+                    journal: true,
+                });
+                continue;
+            }
+            caps.push({
+                endpoint: g.endpoint, command: cmd.name,
+                routes: g.instanceId !== undefined ? [] : ["one"],
+                ...(g.instanceId !== undefined ? { instanceId: g.instanceId } : {}),
+                ...(target !== undefined ? { target } : {}),
+            });
+        }
+        for (const r of g.reads ?? [])
+            if (!reads.some((x) => x.endpoint === g.endpoint && x.subtree === r))
+                reads.push({ endpoint: g.endpoint, subtree: r });
+    }
+    return { caps, reads };
+}
+// ---- the attenuation containment order (§13.6: a child MUST be ⊆ its parent) ------------------
+/** The command-mode lattice `self < owner < any`; `child`/`ledger`/`handle` are grantable in a
+ *  child ONLY where the parent names the SAME mode (they are distinct validator-primary rails,
+ *  never a widening of `owner`). */
+const MODE_RANK = { self: 0, owner: 1, child: 1, ledger: 1, handle: 1, any: 2 };
+function modeOf(cmd) {
+    if (cmd.targetOwner === undefined)
+        return "self"; // no-target ~ self/untargeted floor
+    if (cmd.targetActor !== undefined)
+        return "handle";
+    return (cmd.authz ?? "owner");
+}
+/** True iff a child command mode is ⊆ a parent command mode under the §13.6 order: never higher
+ *  in `self < owner < any`, and `child`/`ledger`/`handle` only where the parent names the SAME
+ *  mode. */
+function modeContained(childMode, parentMode) {
+    if (childMode === parentMode)
+        return true;
+    if (childMode === "child" || childMode === "ledger" || childMode === "handle")
+        return false; // distinct rails: only same-mode
+    if (parentMode === "child" || parentMode === "ledger" || parentMode === "handle")
+        return false; // a distinct-rail parent confers only itself
+    return MODE_RANK[childMode] <= MODE_RANK[parentMode];
+}
+function targetComponentsContained(child, parent) {
+    // Each present PARENT component must be equal in the child; the child may NEWLY PIN a
+    // component the parent left open, never widen a pinned one to absent.
+    for (const f of ["targetOwner", "targetActor", "targetLifecycleUid"])
+        if (parent[f] !== undefined && parent[f] !== child[f])
+            return false;
+    return true;
+}
+function readsContained(childReads, parentReads) {
+    if (childReads === undefined || childReads.length === 0)
+        return true;
+    const parents = parentReads ?? [];
+    // Every child subtree must be subject-prefix-contained in some parent subtree (equal, or a
+    // strict `.`-delimited descendant — never a token-boundary-crossing string prefix).
+    return childReads.every((cr) => parents.some((pr) => cr === pr || cr.startsWith(pr + ".")));
+}
+/** The per-grant-entry half of the §13.6 containment order, shared by attenuation (child ⊆
+ *  parent) and issuer-scope coverage (handle.grants ⊆ anchor.scope). Returns the FIRST
+ *  widening as a why-string, or undefined when contained. */
+function grantWidens(cg, ceiling) {
+    const pg = ceiling.find((p) => p.endpoint === cg.endpoint);
+    if (pg === undefined)
+        return `endpoint "${cg.endpoint}" is not granted`;
+    if (pg.instanceId !== undefined && pg.instanceId !== cg.instanceId)
+        return `endpoint "${cg.endpoint}" instance ${cg.instanceId ?? "(absent)"} != the pinned ${pg.instanceId}`;
+    if (!readsContained(cg.reads, pg.reads))
+        return `endpoint "${cg.endpoint}" reads are not subtree-contained`;
+    for (const cc of cg.commands) {
+        const pc = pg.commands.find((p) => p.name === cc.name);
+        if (pc === undefined)
+            return `command "${cg.endpoint}.${cc.name}" is not granted`;
+        if (!modeContained(modeOf(cc), modeOf(pc)))
+            return `command "${cg.endpoint}.${cc.name}" mode ${modeOf(cc)} is not ⊆ ${modeOf(pc)}`;
+        if (!targetComponentsContained(cc, pc))
+            return `command "${cg.endpoint}.${cc.name}" target components widen the granted ones`;
+    }
+    return undefined;
+}
+/** Assert a CHILD handle is ⊆ its PARENT under the §13.6 normative containment order. Per grant
+ *  entry: endpoint equal (domain patterns are a future extension; this revision pins exact
+ *  endpoints); `instanceId` equal or newly pinned (never widened to absent); commands a
+ *  name-subset with per-command mode contained and target components equal-or-newly-pinned;
+ *  reads subject-prefix-contained. Per envelope: same space; validity window within the
+ *  parent's; `sturdy` only if the parent is sturdy. Throws `permission-denied` on any widening. */
+export function assertHandleContainedIn(child, parent) {
+    const deny = (why) => { throw new EpEnvelopeError("permission-denied", `handle "${child.id}" widens its parent "${parent.id}": ${why} (SPEC 13.6 containment: a child MUST be ⊆ its parent)`); };
+    if (child.space !== parent.space)
+        deny(`space ${child.space} != ${parent.space}`);
+    if (child.exp > parent.exp)
+        deny(`exp ${child.exp} exceeds the parent's ${parent.exp}`);
+    const childNbf = child.nbf ?? child.iat, parentNbf = parent.nbf ?? parent.iat;
+    if (childNbf < parentNbf)
+        deny(`validity starts (${childNbf}) before the parent's (${parentNbf})`);
+    if (child.sturdy && !parent.sturdy)
+        deny("a sturdy child cannot descend from a live parent");
+    for (const cg of child.grants) {
+        const widens = grantWidens(cg, parent.grants);
+        if (widens !== undefined)
+            deny(widens);
+    }
+}
+// ---- issuer authority: the anchor's STRUCTURED handles scope (§13.10) -------------------------
+/** Parse an anchor's `handles`-role scope: each entry is a canonical-JSON-encoded
+ *  {@link HandleGrant} ceiling — "the full grant dimensions, in the handle-grant shape itself"
+ *  (§13.10). An absent/empty dimension is CLOSED; a garbled entry never widens into an open
+ *  ceiling. */
+function parseAnchorHandleScope(anchor) {
+    const entries = anchor.scope?.handles;
+    if (entries === undefined || entries.length === 0)
+        throw new EpEnvelopeError("permission-denied", `signing key ${anchor.keyId} carries the "handles" role with no scope ceiling; an absent dimension is closed, not open (SPEC 13.10)`);
+    return entries.map((e) => {
+        let raw;
+        try {
+            raw = JSON.parse(e);
+        }
+        catch {
+            throw new EpEnvelopeError("permission-denied", `signing key ${anchor.keyId} has a garbled handles-scope entry (not JSON); an unreadable ceiling never authorizes (SPEC 13.10)`);
+        }
+        try {
+            return parseGrant(raw);
+        }
+        catch (err) {
+            throw new EpEnvelopeError("permission-denied", `signing key ${anchor.keyId} has a garbled handles-scope entry (${err.message}); an unreadable ceiling never authorizes (SPEC 13.10)`);
+        }
+    });
+}
+/** Enforce §13.10 issuer authority for one handle: `handle.grants ⊆ anchor.scope` under the
+ *  SAME §13.6 containment order — endpoints, per-command modes, target components, instance
+ *  pins, and read subtrees are all ceiling dimensions; a flat endpoint/command list cannot
+ *  express them and is exactly the laundering this refuses. */
+export function assertIssuerScopeCoversHandle(anchor, handle) {
+    const ceiling = parseAnchorHandleScope(anchor);
+    for (const g of handle.grants) {
+        const widens = grantWidens(g, ceiling);
+        if (widens !== undefined)
+            throw new EpEnvelopeError("permission-denied", `signing key ${anchor.keyId}'s handles scope does not cover handle "${handle.id}": ${widens} (SPEC 13.10/13.6: handle.grants ⊆ anchor.scope, containment never widening)`);
+    }
+}
+/** Race an authority read against the REMAINING verification budget: a stuck registry/revocation
+ *  authority is a bounded `unavailable` refusal, never a hung verification. The caller passes the
+ *  remaining milliseconds of ONE total walk budget (never a per-await reset: sixteen links each
+ *  burning a full fresh budget would multiply the ceiling); an exhausted budget refuses
+ *  IMMEDIATELY, WITHOUT invoking the authority seam (the work is a THUNK, checked against the
+ *  budget before it is started). Races `Promise.resolve(p)` unconditionally (a non-native
+ *  thenable must not bypass the deadline), and NORMALIZES any lookup failure (a raw seam
+ *  rejection) to a catalog `unavailable`, so retry classification is deterministic.
+ *
+ *  Deferred (a shared-seam API change, tracked separately): on timeout the underlying in-flight
+ *  read is not aborted (the {@link AnchorResolver} seam shared with signing/receipt/guard takes
+ *  no AbortSignal). The verification still fails closed and bounds the CALLER; the residual is
+ *  orphaned backend work, a resource concern, not an authorization one. */
+async function withVerifyBudget(work, remainingMs, what) {
+    if (remainingMs <= 0)
+        throw new EpEnvelopeError("unavailable", `${what} found the verification budget already exhausted; the whole chain walk is ONE bounded operation and fails closed WITHOUT starting the read (SPEC 13.10)`);
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new EpEnvelopeError("unavailable", `${what} did not answer within the remaining ${remainingMs}ms verification budget; verification is bounded and fails closed (SPEC 13.10)`)), remainingMs);
+    });
+    try {
+        return await Promise.race([Promise.resolve(work()), deadline]); // work() invoked ONLY after the budget check
+    }
+    catch (e) {
+        if (e instanceof EpEnvelopeError)
+            throw e;
+        throw new EpEnvelopeError("unavailable", `${what} failed: ${e?.message ?? String(e)}; a lookup failure is a bounded unavailable, never a raw error (SPEC 13.10)`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Verify a presented handle CHAIN inline (§13.6): the leaf plus every `parentDigest`-linked
+ *  ancestor, presented together (no ambient fetch). Signature and digest identity are checked
+ *  over the EXACT RAW presented artifacts (D28), never the parsed projection. For each link,
+ *  leaf to root:
+ *   - its `parentDigest` (if any) equals the digest of the NEXT presented RAW artifact (the
+ *     chain is the one presented, not a forgeable claim);
+ *   - each child is ⊆ its parent ({@link assertHandleContainedIn});
+ *   - the ISSUER of a child is the PARENT's holder — anchor-registered with a `handles` role
+ *     whose STRUCTURED scope covers the link ({@link assertIssuerScopeCoversHandle}) AND
+ *     lifecycle-bound to the parent's holder (`ownerLifecycleUid`; owner text alone would let
+ *     a recycled alias issue off its predecessor's handles — absent binding fails closed);
+ *   - the signature verifies against the resolved anchor, within the anchor's window;
+ *   - EVERY link is currency-checked: window (`nbf ≤ now ≤ exp`), no future `iat`, TTL span
+ *     within the live/sturdy ceiling AND `exp ≤ now + ceiling` (clock-anchored: a backdated
+ *     `nbf`/forward-dated `iat` cannot manufacture validity beyond the ceiling), space match;
+ *   - EVERY sturdy link's revocation status is strict-`false`-checked (unreadable = revoked);
+ *   - a LIVE leaf binds `presenterEpoch`; a LIVE ANCESTOR requires `resolveHolderEpoch` to
+ *     fresh-check ITS holder's current epoch (a restarted intermediate kills the chain).
+ *  The walk is bounded: chain length ≤ {@link HANDLE_MAX_CHAIN_LENGTH}, every await within
+ *  `verifyBudgetMs` (default 5000). A ROOT handle (no parentDigest) is issued by an anchor
+ *  whose owner is the handle's issuer principal. Returns the leaf and its compiled
+ *  equivalent-mint bundle (never wider than any ancestor). */
+export async function verifyHandleChain(chain, opts) {
+    if (!Array.isArray(chain) || chain.length === 0)
+        throw new EpEnvelopeError("permission-denied", "a handle chain is empty (SPEC 13.6: present the leaf plus every ancestor inline)");
+    if (chain.length > HANDLE_MAX_CHAIN_LENGTH)
+        throw new EpEnvelopeError("permission-denied", `the presented chain has ${chain.length} links; verification is bounded at ${HANDLE_MAX_CHAIN_LENGTH} (SPEC 13.6)`);
+    if (!Number.isSafeInteger(opts.now) || opts.now < 0)
+        throw new EpEnvelopeError("failed-precondition", `now must be a non-negative safe integer; got ${JSON.stringify(opts.now)}`);
+    const budget = opts.verifyBudgetMs ?? 5_000;
+    if (!Number.isSafeInteger(budget) || budget <= 0)
+        throw new EpEnvelopeError("failed-precondition", `verifyBudgetMs must be a positive integer; got ${JSON.stringify(opts.verifyBudgetMs)}`);
+    // Snapshot the FULL authority context into detached, frozen locals at entry, BEFORE the first
+    // await: a caller mutating opts.readRevocation / resolveAnchor / resolveHolderEpoch (or any
+    // scalar/presenter field) between links would otherwise swap the authority a single
+    // verification decides against. Every consuming read below uses ONLY these locals.
+    if (!isRec(opts.presenter) || typeof opts.presenter.id !== "string" || typeof opts.presenter.lifecycleUid !== "string")
+        throw new EpEnvelopeError("failed-precondition", "the presenter must carry a string id and lifecycleUid");
+    const A = Object.freeze({
+        now: opts.now,
+        space: opts.space,
+        presenter: Object.freeze({ id: opts.presenter.id, lifecycleUid: opts.presenter.lifecycleUid, epoch: opts.presenter.epoch }),
+        maxSturdyTtlMs: opts.maxSturdyTtlMs ?? HANDLE_MAX_STURDY_TTL_MS,
+        maxLiveTtlMs: opts.maxLiveTtlMs ?? HANDLE_MAX_LIVE_TTL_MS,
+        resolveHolderEpoch: opts.resolveHolderEpoch,
+        resolveAnchor: opts.resolveAnchor,
+        readRevocation: opts.readRevocation,
+        commandContract: opts.commandContract,
+    });
+    // ONE total walk budget on a MONOTONIC clock: every read races the REMAINING time, so sixteen
+    // links cannot each burn a fresh full budget (bounded as one operation, SPEC 13.10), and a
+    // wall-clock adjustment cannot extend the budget backward or exhaust it forward.
+    const startedAt = performance.now();
+    const remainingBudget = () => budget - (performance.now() - startedAt);
+    // Snapshot each RAW artifact to a detached, byte-bounded, deep-frozen copy at entry (D28: the
+    // signature and digest identity are checked over EXACTLY this snapshot; the parsed projection
+    // derives from the same bytes, so a projection/default can never be the signed value, and a
+    // mid-flight mutation of the caller's object cannot split verification from projection).
+    const raws = chain.map((r) => {
+        if (!isRec(r))
+            invalid("a chain element is not an object");
+        const bytes = new TextEncoder().encode(canonicalJson(r)); // throws on non-interchangeable I-JSON
+        if (bytes.length > HANDLE_MAX_BYTES)
+            invalid(`a chain artifact is ${bytes.length} bytes, over the ${HANDLE_MAX_BYTES} bound (bounded verification)`);
+        return Object.freeze(JSON.parse(new TextDecoder().decode(bytes)));
+    });
+    const handles = raws.map(parseHandle);
+    const leaf = handles[0];
+    // The presented chain must be leaf → … → root by parentDigest identity over the RAW
+    // artifacts (no ambient fetch, no forgeable parent claim, no reconstructed projection).
+    for (let i = 0; i < handles.length; i++) {
+        const h = handles[i];
+        const rawParent = raws[i + 1];
+        if (h.parentDigest === undefined) {
+            if (rawParent !== undefined)
+                throw new EpEnvelopeError("permission-denied", `handle "${h.id}" is a root (no parentDigest) but the chain presents further ancestors; a chain must terminate at its root (SPEC 13.6)`);
+        }
+        else {
+            if (rawParent === undefined)
+                throw new EpEnvelopeError("permission-denied", `handle "${h.id}" names a parentDigest but no parent is presented; chains are presented inline in full (SPEC 13.6)`);
+            if (contractDigest(rawParent) !== h.parentDigest)
+                throw new EpEnvelopeError("permission-denied", `handle "${h.id}" parentDigest does not match the presented parent "${handles[i + 1].id}" (SPEC 13.6: the chain is the one presented, not a claim)`);
+        }
+    }
+    // Leaf holder binding (the presenter IS the leaf's holder).
+    if (leaf.holder.id !== A.presenter.id || leaf.holder.lifecycleUid !== A.presenter.lifecycleUid)
+        throw new EpEnvelopeError("permission-denied", `handle "${leaf.id}" is holder-bound to ${leaf.holder.id}/${leaf.holder.lifecycleUid}; the presenter ${A.presenter.id}/${A.presenter.lifecycleUid} is not the holder; a recycled alias cannot present its predecessor's handles (SPEC 13.6)`);
+    // Walk every link: currency, containment, issuer authority, signature, revocation.
+    for (let i = 0; i < handles.length; i++) {
+        const h = handles[i];
+        const parent = handles[i + 1];
+        // Per-link currency (§13.6: expiry/ceilings fail closed on EVERY link, not only the leaf).
+        if (h.space !== A.space)
+            throw new EpEnvelopeError("permission-denied", `handle "${h.id}" is bound to space ${h.space}, not ${A.space} (SPEC 13.6)`);
+        // The shared §13.6/§13.10 window rules (assertArtifactCurrency); "opaque" because this runs
+        // BEFORE the link's signature check, so every refusal stays permission-denied.
+        assertArtifactCurrency({ iat: h.iat, ...(h.nbf !== undefined ? { nbf: h.nbf } : {}), exp: h.exp }, { now: A.now, ceilingMs: h.sturdy ? A.maxSturdyTtlMs : A.maxLiveTtlMs, what: `handle "${h.id}"`, ceilingName: h.sturdy ? "sturdy" : "live", refusals: "opaque" });
+        if (!h.sturdy) {
+            if (i === 0) {
+                if (h.epoch !== A.presenter.epoch)
+                    throw new EpEnvelopeError("permission-denied", `live handle "${h.id}" binds process epoch ${h.epoch}; the presenter epoch is ${A.presenter.epoch} (live authority dies on restart, SPEC 13.1/13.6)`);
+            }
+            else {
+                // A LIVE ANCESTOR binds ITS holder's process epoch: fresh-check it (a restarted
+                // intermediate kills every descendant, exactly like a revoked sturdy ancestor).
+                if (typeof A.resolveHolderEpoch !== "function")
+                    throw new EpEnvelopeError("failed-precondition", `the chain contains a LIVE ancestor ("${h.id}") but no resolveHolderEpoch seam was supplied; a live link's epoch currency is never assumed (SPEC 13.6)`);
+                const resolveHolderEpoch = A.resolveHolderEpoch;
+                const current = await withVerifyBudget(() => resolveHolderEpoch(h.holder), remainingBudget(), `the holder-epoch resolver for "${h.id}"`);
+                if (current !== null && (typeof current !== "number" || !Number.isSafeInteger(current) || current < 0))
+                    throw new EpEnvelopeError("internal", `the holder-epoch resolver returned ${JSON.stringify(current)}; a non-integer epoch never authorizes (SPEC 13.6)`);
+                if (current === null || current !== h.epoch)
+                    throw new EpEnvelopeError("permission-denied", `live ancestor "${h.id}" binds its holder's process epoch ${h.epoch} but the current epoch is ${current === null ? "retired/unknown" : current}; live authority dies on restart, on every link (SPEC 13.6)`);
+            }
+        }
+        if (parent !== undefined)
+            assertHandleContainedIn(h, parent);
+        const anchor = await withVerifyBudget(() => resolveAnchorForUse(A.resolveAnchor, { keyId: h.issuer.keyId, role: "handles", at: A.now }), remainingBudget(), `the anchor-registry read for ${h.issuer.keyId}`);
+        // The issuer of a CHILD is the PARENT's holder — bound by LIFECYCLE, not owner text: a
+        // recycled alias (same id, new lifecycleUid) re-registering a key must never issue off its
+        // predecessor's handles. An anchor without the lifecycle binding fails closed here.
+        if (parent !== undefined) {
+            if (anchor.owner !== parent.holder.id)
+                throw new EpEnvelopeError("permission-denied", `handle "${h.id}" issuer key ${h.issuer.keyId} belongs to ${anchor.owner}, not the parent's holder ${parent.holder.id} (SPEC 13.6/13.10)`);
+            if (anchor.ownerLifecycleUid === undefined)
+                throw new EpEnvelopeError("permission-denied", `handle "${h.id}" issuer key ${h.issuer.keyId} is not lifecycle-bound in the anchor registry; child issuance requires the key's owning lifecycle so a recycled alias cannot issue off its predecessor's handles (SPEC 13.6/13.10: fail closed)`);
+            if (anchor.ownerLifecycleUid !== parent.holder.lifecycleUid)
+                throw new EpEnvelopeError("permission-denied", `handle "${h.id}" issuer key ${h.issuer.keyId} belongs to lifecycle ${anchor.ownerLifecycleUid}, not the parent holder's ${parent.holder.lifecycleUid}; a recycled alias cannot issue off its predecessor's handles (SPEC 13.6/13.10)`);
+        }
+        // A ROOT's issuer is the anchor's own owner (the root of trust): the handle carries no
+        // separate issuer-principal claim, so the root binding IS the resolved key — handles-roled,
+        // in-window, scope-covering; registry ownership semantics live in D18.
+        // The issuer key's STRUCTURED handles scope must cover this link's full grant dimensions.
+        assertIssuerScopeCoversHandle(anchor, h);
+        // D28: the signature verifies over the EXACT RAW presented artifact, never a projection.
+        verifyArtifactSignature(raws[i], anchor);
+        if (h.sturdy) {
+            const readRevocation = A.readRevocation;
+            const revoked = await withVerifyBudget(() => readRevocation(h.issuer.keyId, h.id), remainingBudget(), `the revocation read for "${h.id}"`);
+            if (revoked !== false)
+                throw new EpEnvelopeError("permission-denied", `a sturdy link in the chain is not provably unrevoked (handle "${h.id}", issuer ${h.issuer.keyId}, status ${JSON.stringify(revoked)}); ONLY a literal false is "not revoked"; an unreadable/undefined status fails closed, and every sturdy link is checked, not only the leaf (SPEC 13.6)`);
+        }
+    }
+    return { leaf, compiled: compileHandleGrants(leaf, { commandContract: A.commandContract }) };
+}
+/** Serialize a handle to its canonical bytes (the wire/store form). Throws if the artifact is
+ *  not interchangeable I-JSON (the strict canonical path), so a non-canonicalizable handle can
+ *  never be persisted or presented. The parsed projection is byte-faithful to the signed form
+ *  (parse injects nothing and drops nothing), so these bytes re-verify. */
+export function serializeHandle(handle) {
+    return new TextEncoder().encode(canonicalJson(handle));
+}
+// re-export so a caller can spell the modes without reaching into subjects
+export { EP_AUTHZ_MODES };
+//# sourceMappingURL=endpoint-handle.js.map