@agenticprimitives/delegation 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/mandate-handlers.js

@@ -0,0 +1,173 @@
+// The first subset handlers — spec 350 §2.1. Each `type` owns its own "narrower-than", because RFC 9396
+// says no universal one exists. Two ship here: a GENERIC capability handler that covers every
+// non-financial action (membership, naming, registry), and the PAYMENT handler that reuses the
+// spec-272 `PaymentEnforcer` caveats so a treasury mandate is bounded on chain by the same terms the
+// off-chain verifier reads.
+import { decodeAbiParameters } from 'viem';
+import { buildCaveat, encodeTimestampTerms, decodeTimestampTerms, encodeAllowedMethodsTerms, decodeAllowedMethodsTerms, encodeAllowedTargetsTerms, decodeAllowedTargetsTerms, encodeValueTerms, encodePaymentTerms, PAYMENT_TRANSFER_SELECTOR, } from './caveats.js';
+import { methodSelector } from './method-authorization.js';
+import { baseIsSubset, registerSubsetHandler } from './mandate.js';
+const lc = (s) => s.toLowerCase();
+const findCaveat = (caveats, enforcer) => enforcer ? caveats.find((c) => lc(c.enforcer) === lc(enforcer)) : undefined;
+// ─── Generic capability handler ────────────────────────────────────────────────────────────────────
+//
+// type: `urn:ap:rar:capability`. actions = capability ids (ADR-0051), each becoming an allowedMethods
+// selector; locations = the agent SAs this authority may be exercised AGAINST (allowedTargets); a window;
+// value pinned to 0. No type-specific limits — a membership add either is or is not in scope.
+export const CAPABILITY_RAR_TYPE = 'urn:ap:rar:capability';
+export const capabilityHandler = {
+    type: CAPABILITY_RAR_TYPE,
+    isSubset: baseIsSubset,
+    toCaveats(req, e) {
+        if (!req.actions.length)
+            throw new Error('capability mandate: at least one action (capability id) is required');
+        const caveats = [
+            buildCaveat(e.timestamp, encodeTimestampTerms(req.validAfter ?? 0, req.validUntil)),
+            // Capability selectors (what the off-chain verifier compares) AND the real EVM selectors this
+            // authority actually calls (what the enforcer sees). Both are "methods allowed"; omitting the
+            // second made every on-chain capability call revert MethodNotAllowed.
+            buildCaveat(e.allowedMethods, encodeAllowedMethodsTerms([...req.actions.map(methodSelector), ...(req.methods ?? [])])),
+            buildCaveat(e.value, encodeValueTerms(0n)),
+        ];
+        if (req.locations?.length)
+            caveats.push(buildCaveat(e.allowedTargets, encodeAllowedTargetsTerms(req.locations.map(asAddress))));
+        return caveats;
+    },
+    fromCaveats(caveats, e) {
+        const ts = findCaveat(caveats, e.timestamp);
+        const methods = findCaveat(caveats, e.allowedMethods);
+        if (!ts || !methods)
+            return null;
+        const { validAfter, validUntil } = decodeTimestampTerms(ts.terms);
+        const selectors = decodeAllowedMethodsTerms(methods.terms);
+        // Selectors are one-way; the reader keeps them as `sel:<hex>` unless it can name them. A verifier
+        // compares by selector (methodSelector(step.capability)), so this is lossless for its purpose.
+        const targets = findCaveat(caveats, e.allowedTargets);
+        return {
+            type: CAPABILITY_RAR_TYPE,
+            actions: selectors.map((s) => `sel:${s}`),
+            ...(targets ? { locations: [...decodeAllowedTargetsTerms(targets.terms)] } : {}),
+            validAfter: Number(validAfter),
+            validUntil: Number(validUntil),
+        };
+    },
+};
+/** A capability mandate grants capability IDS: a step exercising `organization.team.create` with the verb
+ *  `create` is judged on the id (the verb is the capability's own facet, not a separate grant). */
+capabilityHandler.stepActions = (step) => [step.capability];
+/** `isSubset` for the capability type must compare ACTIONS BY SELECTOR, because a read-back mandate
+ *  carries `sel:<hex>` while a step or a fresh requirement carries the capability id. */
+capabilityHandler.isSubset = (child, parent) => {
+    const norm = (a) => (a.startsWith('sel:') ? a.slice(4).toLowerCase() : methodSelector(a).toLowerCase());
+    return baseIsSubset({ ...child, actions: child.actions.map(norm) }, { ...parent, actions: parent.actions.map(norm) });
+};
+// ─── Payment handler ───────────────────────────────────────────────────────────────────────────────
+//
+// type: `urn:ap:rar:treasury.payment.execute`. limits = { payee, asset, maxAmount, maxAggregate,
+// maxRedemptionsPerWindow, windowSeconds }; the on-chain terms are the spec-272 PaymentEnforcer's.
+// "Pay Ligonier $250 but not Bob $250" is `payee` + `maxAmount`, not a different method.
+export const PAYMENT_RAR_TYPE = 'urn:ap:rar:treasury.payment.execute';
+function paymentLimits(req) {
+    const l = req.limits ?? {};
+    const need = (k) => { const v = l[k]; if (v === undefined)
+        throw new Error(`payment mandate: limits.${k} is required`); return String(v); };
+    return {
+        payee: asAddress(need('payee')), asset: asAddress(need('asset')),
+        maxAmount: BigInt(need('maxAmount')), maxAggregate: BigInt(l.maxAggregate ?? need('maxAmount')),
+        maxRedemptionsPerWindow: Number(l.maxRedemptionsPerWindow ?? 1), windowSeconds: Number(l.windowSeconds ?? 86_400),
+    };
+}
+export const paymentHandler = {
+    type: PAYMENT_RAR_TYPE,
+    // The narrowest grant that covers this payment: THIS payee, THIS asset, THIS amount, once, within the
+    // hour. A person asked to authorize a payment is being asked for an amount — a requirement that omits
+    // it either cannot be minted (the enforcer needs the ceiling) or would have to invent one, and an
+    // invented ceiling is a bigger grant than anybody agreed to.
+    stepLimits(step) {
+        const a = step.args ?? {};
+        const amount = a.amount !== undefined ? String(a.amount).trim() : undefined;
+        if (amount === undefined || amount === '')
+            throw new Error('payment step: args.amount is required to bound the authority it needs');
+        // AND IT MUST BE A NUMBER. A planner asked for a payment with no figure filled the amount with the
+        // literal string "<UNKNOWN>", which is present, non-empty, and would have been encoded as the
+        // ceiling of a real mandate. A limit that cannot be read as a quantity does not bound anything, and
+        // the one thing a payment caveat exists to do is bound the quantity.
+        if (!/^\d+$/.test(amount)) {
+            throw new Error(`payment step: args.amount must be a whole number of the token's smallest units, got "${amount}"`);
+        }
+        return {
+            payee: String(a.payee ?? ''), asset: String(a.asset ?? step.resource ?? ''),
+            maxAmount: amount, maxAggregate: amount, maxRedemptionsPerWindow: 1, windowSeconds: 3600,
+        };
+    },
+    isSubset(child, parent) {
+        if (!baseIsSubset(child, parent))
+            return false;
+        // A STEP arrives with `amount` + `payee` (+ maybe `asset`); a REQUIREMENT with the full limit set.
+        // Compare what is present; anything the child leaves unstated inherits the parent's bound.
+        const p = paymentLimits(parent);
+        const cl = child.limits ?? {};
+        const amount = cl.amount !== undefined ? BigInt(String(cl.amount)) : cl.maxAmount !== undefined ? BigInt(String(cl.maxAmount)) : null;
+        if (amount !== null && amount > p.maxAmount)
+            return false;
+        if (cl.maxAggregate !== undefined && BigInt(String(cl.maxAggregate)) > p.maxAggregate)
+            return false;
+        if (cl.payee !== undefined && lc(String(cl.payee)) !== lc(p.payee))
+            return false;
+        if (cl.asset !== undefined && lc(String(cl.asset)) !== lc(p.asset))
+            return false;
+        if (cl.maxRedemptionsPerWindow !== undefined && Number(cl.maxRedemptionsPerWindow) > p.maxRedemptionsPerWindow)
+            return false;
+        return true;
+    },
+    toCaveats(req, e) {
+        if (!e.payment)
+            throw new Error('payment mandate: enforcers.payment (PaymentEnforcer) is required');
+        const p = paymentLimits(req);
+        return [
+            buildCaveat(e.payment, encodePaymentTerms({ payee: p.payee, asset: p.asset, maxAmountPerCharge: p.maxAmount, maxAggregate: p.maxAggregate, maxRedemptionsPerWindow: p.maxRedemptionsPerWindow, windowSeconds: p.windowSeconds })),
+            buildCaveat(e.timestamp, encodeTimestampTerms(req.validAfter ?? 0, req.validUntil)),
+            buildCaveat(e.allowedTargets, encodeAllowedTargetsTerms([p.asset])),
+            buildCaveat(e.allowedMethods, encodeAllowedMethodsTerms([PAYMENT_TRANSFER_SELECTOR, methodSelector('treasury.payment.execute')])),
+        ];
+    },
+    fromCaveats(caveats, e) {
+        const pay = findCaveat(caveats, e.payment);
+        const ts = findCaveat(caveats, e.timestamp);
+        if (!pay || !ts)
+            return null;
+        const [payee, asset, maxAmount, maxAggregate, perWindow, windowSeconds] = decodeAbiParameters([{ type: 'address' }, { type: 'address' }, { type: 'uint256' }, { type: 'uint256' }, { type: 'uint32' }, { type: 'uint32' }], pay.terms);
+        const { validAfter, validUntil } = decodeTimestampTerms(ts.terms);
+        return {
+            type: PAYMENT_RAR_TYPE,
+            actions: ['execute'],
+            locations: [asset],
+            limits: { payee, asset, maxAmount: maxAmount.toString(), maxAggregate: maxAggregate.toString(), maxRedemptionsPerWindow: perWindow, windowSeconds },
+            validAfter: Number(validAfter), validUntil: Number(validUntil),
+        };
+    },
+};
+function asAddress(s) {
+    const m = /0x[0-9a-fA-F]{40}$/.exec(s); // accepts a bare address or a CAIP-10 `eip155:<chain>:0x…`
+    if (!m)
+        throw new Error(`not an address or CAIP-10 account: ${s}`);
+    return m[0];
+}
+/** The defaults as an explicit set — pass this to `verifyMandateForStep({ handlers })` rather than relying
+ *  on ambient registration, which does not survive a bundle that duplicates the module. */
+export const DEFAULT_SUBSET_HANDLERS = new Map([
+    [capabilityHandler.type, capabilityHandler],
+    [paymentHandler.type, paymentHandler],
+]);
+/** Register both into the ambient registry. Idempotent per process; a second call is a no-op. */
+let registered = false;
+export function registerDefaultSubsetHandlers() {
+    if (registered)
+        return;
+    registerSubsetHandler(capabilityHandler);
+    registerSubsetHandler(paymentHandler);
+    registered = true;
+}
+/** Test seam — pairs with `_resetSubsetHandlers`. */
+export function _resetDefaultRegistration() { registered = false; }
+//# sourceMappingURL=mandate-handlers.js.map

package/dist/mandate-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mandate-handlers.js","sourceRoot":"","sources":["../src/mandate-handlers.ts"],"names":[],"mappings":"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"}

package/dist/mandate.d.ts

@@ -0,0 +1,213 @@
+import { type Hex } from 'viem';
+import type { Address, Caveat, Delegation, EnforcerAddressMap } from './types.js';
+import { type MethodAuthorizationChecks } from './method-authorization.js';
+import { type DigestBindingKind } from './caveats.js';
+import { ROOT_AUTHORITY } from './types.js';
+/**
+ * What authority a step NEEDS, in RFC 9396 `authorization_details` shape. A proposal: it grants nothing.
+ * `type` is collision-resistant and owns its own subset semantics via a registered handler.
+ */
+export interface MandateRequirementV1 {
+    /** e.g. `urn:ap:rar:treasury.payment.execute`. Chooses the subset handler. */
+    type: string;
+    /** Capability-level actions, e.g. `['execute']`, `['add','remove']`. */
+    actions: string[];
+    /** Resources, as URNs / CAIP-10 — the treasury, the org, the team. */
+    locations?: string[];
+    /** Type-specific ceilings: `{ maxAmount: '500', currency: 'USDC' }`. Interpreted by the handler. */
+    limits?: Record<string, string | number>;
+    /** THE REASON. Digest of the canonical intent (§ intentDigest). Required — without it this is a capability. */
+    intentDigest: Hex;
+    /** What was disclosed to the grantee (spec 336 §4), when the mandate followed a projection. */
+    projectionDigest?: Hex;
+    /** The accepted offer (spec 336 §5), when the mandate followed an engagement. */
+    offerDigest?: Hex;
+    /** Unix seconds. */
+    validAfter?: number;
+    validUntil: number;
+    /**
+     * THE ON-CHAIN CALLS THIS AUTHORITY MAKES — real 4-byte EVM selectors, when the capability is exercised
+     * by redeeming this mandate against a contract.
+     *
+     * `actions` are CAPABILITY ids, and `methodSelector` turns each into a synthetic selector the OFF-CHAIN
+     * verifier compares. The `AllowedMethodsEnforcer` sees the actual transaction, so a mandate carrying
+     * only capability selectors reverts every real call with `MethodNotAllowed` — which is exactly what
+     * happened to `treasury.fund` through the Ask: the mandate verified, the person signed, and the chain
+     * refused a call the caveat had never been told to expect.
+     *
+     * WHO SAYS WHICH SELECTORS: the app that owns the call, never a planner and never the person — the
+     * bytes are a deployment fact. Listing them NARROWS nothing on its own (`allowedTargets` still bounds
+     * WHERE) but it is what makes the authority honest about WHAT it does, and the card can name it.
+     */
+    methods?: Hex[];
+}
+/** RFC 8785 JCS → keccak256. The ONE way an intent digest is computed, so grantor, verifier and receipt
+ *  cannot disagree about which bytes were bound. */
+export declare function intentDigest(intent: unknown): Hex;
+/** The enforcer addresses a handler may encode caveats against. */
+export type EnforcerAddresses = EnforcerAddressMap & {
+    digestBinding: Address;
+};
+/**
+ * One per `type`. RFC 9396: "there is no universal way to determine whether one authorization_details
+ * object is a subset of another" — so every type says for itself.
+ */
+export interface MandateSubsetHandler {
+    type: string;
+    /** Is `child` ⊆ `parent`? Pure; deterministic. Must be conservative: unsure ⇒ false. */
+    isSubset(child: MandateRequirementV1, parent: MandateRequirementV1): boolean;
+    /** The caveats that ENFORCE the requirement on chain (not counting the digest bindings, added generically). */
+    toCaveats(req: MandateRequirementV1, enforcers: EnforcerAddresses): Caveat[];
+    /** Read the requirement back out of a delegation's caveats — for verification and for display. */
+    fromCaveats(caveats: readonly Caveat[], enforcers: EnforcerAddresses): Omit<MandateRequirementV1, 'intentDigest' | 'projectionDigest' | 'offerDigest'> | null;
+    /** The LIMITS a mandate would need to carry for this step to be within it — the type's own quantities,
+     *  read off the step. Payment turns `{payee, asset, amount}` into a ceiling; the generic capability type
+     *  bounds nothing beyond its actions and locations. Used when ASKING for authority (§3.6): a person
+     *  granting a payment is granting an amount, and a requirement that omits it cannot be minted. */
+    stepLimits?(step: MandateStep): Record<string, string | number>;
+    /** What a step's ACTIONS are, in this type's vocabulary. A step carries both a capability id
+     *  (`organization.team.create`) and a verb (`create`); which of them a mandate's `actions` name is the
+     *  type's convention — the generic capability type grants capability IDS, the payment type grants the
+     *  verb `execute`. Default: the verb. A type that grants ids overrides. */
+    stepActions?(step: MandateStep): string[];
+}
+/** The handlers a verification consults. Passed EXPLICITLY (`SubsetHandlers`) wherever possible: the
+ *  ambient registry below is module-level state, and a bundle that ends up with two copies of this
+ *  module has two registries — one that was registered into and one that is consulted. That is how a
+ *  live verifier once answered "no handler" for a type its process had registered. */
+export type SubsetHandlers = ReadonlyMap<string, MandateSubsetHandler>;
+export declare function registerSubsetHandler(h: MandateSubsetHandler): void;
+export declare function subsetHandlerFor(type: string, from?: SubsetHandlers): MandateSubsetHandler | null;
+/** Test seam. */
+export declare function _resetSubsetHandlers(): void;
+/**
+ * The base rule every handler can build on: actions ⊆, locations ⊆ (when the parent names any),
+ * window ⊆, and the intent must be the SAME — a mandate for one intent never derives one for another.
+ */
+export declare function baseIsSubset(child: MandateRequirementV1, parent: MandateRequirementV1): boolean;
+export interface DeriveMandateInput {
+    /** The standing authority. Its hash becomes the child's `authority`, which is what makes it a CHAIN. */
+    parent: Delegation;
+    /** What the parent allows, as read by its handler. Supplied by the caller who resolved it (or read
+     *  it with `readMandate`). */
+    parentRequirement: MandateRequirementV1;
+    /** What the child asks for. Must be ⊆ parent, per the handler, or this refuses. */
+    requirement: MandateRequirementV1;
+    grantee: Address;
+    enforcers: EnforcerAddresses;
+    chainId: number;
+    delegationManager: Address;
+    /** Random 128-bit salt; injected so a test can be deterministic. */
+    salt: bigint;
+    /** The handler set to consult. Defaults to the ambient registry. */
+    handlers?: SubsetHandlers;
+}
+export type DeriveMandateResult = {
+    ok: true;
+    delegation: Delegation;
+    digest: Hex;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * A child mandate from a standing delegation. Unsigned: the caller signs `digest` with the parent's
+ * DELEGATE's credential (the party attenuating its own authority onward).
+ */
+export declare function deriveMandate(input: DeriveMandateInput): DeriveMandateResult;
+/** Read a mandate's requirement back out of a delegation, or null when it carries no intent binding —
+ *  in which case it is a standing capability, not a mandate. */
+export declare function readMandate(d: Delegation, type: string, enforcers: EnforcerAddresses, from?: SubsetHandlers): MandateRequirementV1 | null;
+/** The step, as the verifier sees it. */
+export interface MandateStep {
+    /** ADR-0051 capability id the step exercises, e.g. `treasury.payment.execute`. Its selector is what
+     *  `allowedMethods` is checked against. */
+    capability: string;
+    action: string;
+    resource?: string;
+    /** The intent THIS RUN is acting under. Compared to the mandate's binding — this is the reason check. */
+    intent: unknown;
+    /** Optional: the projection / offer digests when the run followed an engagement. */
+    projectionDigest?: Hex;
+    offerDigest?: Hex;
+    /** Type-specific arguments the handler may bound (amount, payee…). */
+    args?: Record<string, unknown>;
+    /** For the `value` caveat. */
+    value?: bigint;
+}
+export interface VerifyMandateInput {
+    /** The wire the caller presented. */
+    presented: Delegation;
+    /** The RAR type the step requires — selects the handler that judges type-specific limits. */
+    requirementType: string;
+    /** The party acting. MUST be the delegate. */
+    actor: Address;
+    step: MandateStep;
+    enforcers: EnforcerAddresses;
+    checks: MethodAuthorizationChecks;
+    /** Unix seconds; injected. */
+    now: number;
+    /** The handler set to consult. Defaults to the ambient registry — pass it explicitly in a bundle. */
+    handlers?: SubsetHandlers;
+}
+export interface DecisionReason {
+    code: string;
+    message: string;
+}
+/** An UNSATISFIED condition attached to the authority. Not a UI prompt: a fact the mandate carries. */
+export interface Obligation {
+    kind: 'second-party-approval' | 'quorum' | 'fresh-authorization' | 'disclosure' | (string & {});
+    dischargeableBy: {
+        role?: string;
+        agents?: Address[];
+        threshold?: number;
+    };
+    /** The policy or caveat that imposed it, by reference — so the record of discharge can name it. */
+    imposedBy: string;
+}
+export interface DecisionEvidence {
+    mandateRef: Hex;
+    intentDigest: Hex;
+    evaluatedAt: number;
+    /** Every caveat verdict, so a denial names the caveat and a permit is inspectable. */
+    verdicts: Array<{
+        enforcer: Address;
+        allowed: boolean;
+        reason?: string;
+    }>;
+    /** Spec 383 — THE CHAIN the leaf descends from, verified whole: every link by digest, the accountability
+     *  root (the root delegator) and the acting agent (the leaf delegate). A root mandate is a chain of one. */
+    chain?: import('./authority-chain.js').AuthorityChainV1;
+}
+export type MandateDecision = {
+    decision: 'allow';
+    obligations: Obligation[];
+    evidence: DecisionEvidence;
+} | {
+    decision: 'approval-required';
+    obligations: Obligation[];
+    evidence: DecisionEvidence;
+} | {
+    decision: 'deny';
+    reasons: DecisionReason[];
+    evidence: DecisionEvidence;
+};
+/**
+ * Is THIS step covered by the presented mandate, RIGHT NOW?
+ *
+ * Order — and every stage fails closed:
+ *   1. the actor is the delegate;
+ *   2. the delegation is live: signed by its delegator, unrevoked, in window (verifyLiveDelegation);
+ *   3. it IS a mandate: it carries an intent binding, and that binding equals the digest computed from
+ *      the step's intent — the reason check (evaluateCaveats with `digests`, strict);
+ *   4. the step's capability selector satisfies allowedMethods, and its value the value cap;
+ *   5. the handler's type-specific limits admit the step's args.
+ *
+ * Obligations are NOT decided here — they come from policy (spec 350 §3.4) and are attached by the
+ * `MandateVerifier` port implementation that composes this with a `PolicyEvaluator`. This function
+ * answers one question: is the authority present and does it cover the step.
+ */
+export declare function verifyMandateForStep(input: VerifyMandateInput): Promise<MandateDecision>;
+export { ROOT_AUTHORITY };
+export type { DigestBindingKind };
+//# sourceMappingURL=mandate.d.ts.map

package/dist/mandate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mandate.d.ts","sourceRoot":"","sources":["../src/mandate.ts"],"names":[],"mappings":"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"}

package/dist/mandate.js

@@ -0,0 +1,222 @@
+// Mandates — spec 350 §2 / spec 336 §8.3 + E4.
+//
+// A MANDATE IS A DELEGATION WITH A REASON. Not a new authority mechanism, not a token format, not a
+// package of its own: a standing `Delegation` (EIP-712, ERC-1271-verified, on-chain revocable) whose
+// caveats ALSO bind it to the digest of the intent it serves. `allowedMethods` + a window says WHAT the
+// delegate may call; the intent binding says WHY, and a step whose intent differs is refused even though
+// the method is identical. That is the whole difference between a standing capability and a mandate.
+//
+// This module is the missing half of spec 336 wave E4:
+//   • `MandateRequirementV1` — the RAR-shaped (RFC 9396) PROPOSAL a mandate is derived from. It grants
+//     nothing; it is what an offer can state openly and what a grantor approves.
+//   • the subset-handler registry — RFC 9396 is explicit that NO universal "narrower-than" exists across
+//     authorization-detail types, so each `type` registers its own `isSubset` / `toCaveats` / `fromCaveats`.
+//   • `deriveMandate` — a child delegation from a standing one. It refuses EARLY (via the handler) so a
+//     doomed child is never signed; the chain would refuse it anyway, because the child's `authority` is
+//     the parent's hash and DelegationManager evaluates the whole chain at redemption. Attenuation is a
+//     property of the representation, not a policy this file remembers to enforce.
+//   • `verifyMandateForStep` — THE per-step check. Called before every consequential step of a run, never
+//     once at admission, so a revocation between step 2 and step 3 stops step 3. Returns a decision with
+//     reasons; it never falls back to a weaker check (ADR-0013).
+import { keccak256, stringToBytes } from 'viem';
+import { jcsCanonicalize } from '@agenticprimitives/types';
+import { hashDelegation } from './hash.js';
+import { verifyLiveDelegation, methodSelector } from './method-authorization.js';
+import { evaluateCaveats } from './evaluator.js';
+import { buildDigestBindingCaveat, readDigestBindings } from './caveats.js';
+import { ROOT_AUTHORITY } from './types.js';
+/** RFC 8785 JCS → keccak256. The ONE way an intent digest is computed, so grantor, verifier and receipt
+ *  cannot disagree about which bytes were bound. */
+export function intentDigest(intent) {
+    return keccak256(stringToBytes(jcsCanonicalize(intent)));
+}
+const handlers = new Map();
+export function registerSubsetHandler(h) {
+    if (handlers.has(h.type))
+        throw new Error(`registerSubsetHandler: a handler for ${h.type} is already registered`);
+    handlers.set(h.type, h);
+}
+export function subsetHandlerFor(type, from = handlers) {
+    return from.get(type) ?? null;
+}
+/** Test seam. */
+export function _resetSubsetHandlers() { handlers.clear(); }
+/**
+ * The base rule every handler can build on: actions ⊆, locations ⊆ (when the parent names any),
+ * window ⊆, and the intent must be the SAME — a mandate for one intent never derives one for another.
+ */
+export function baseIsSubset(child, parent) {
+    if (child.type !== parent.type)
+        return false;
+    if (child.intentDigest.toLowerCase() !== parent.intentDigest.toLowerCase())
+        return false;
+    if (!child.actions.every((a) => parent.actions.includes(a)))
+        return false;
+    if (parent.locations?.length) {
+        // Locations are addresses / CAIP-10 accounts; viem checksums on decode, callers pass lowercase.
+        // Case is not identity.
+        const p = parent.locations.map((l) => l.toLowerCase());
+        if (!child.locations?.length)
+            return false;
+        if (!child.locations.every((l) => p.includes(l.toLowerCase())))
+            return false;
+    }
+    if ((child.validAfter ?? 0) < (parent.validAfter ?? 0))
+        return false;
+    if (child.validUntil > parent.validUntil)
+        return false;
+    return true;
+}
+/**
+ * A child mandate from a standing delegation. Unsigned: the caller signs `digest` with the parent's
+ * DELEGATE's credential (the party attenuating its own authority onward).
+ */
+export function deriveMandate(input) {
+    const h = subsetHandlerFor(input.requirement.type, input.handlers);
+    if (!h)
+        return { ok: false, reason: `no subset handler registered for ${input.requirement.type} — refusing to derive an authority nobody can bound` };
+    if (input.requirement.type !== input.parentRequirement.type)
+        return { ok: false, reason: 'child and parent requirement types differ' };
+    if (!h.isSubset(input.requirement, input.parentRequirement)) {
+        return { ok: false, reason: `requested authority is not a subset of the parent's (${h.type})` };
+    }
+    const caveats = [
+        ...h.toCaveats(input.requirement, input.enforcers),
+        buildDigestBindingCaveat(input.enforcers.digestBinding, 'intent', input.requirement.intentDigest, input.requirement.intentDigest),
+        ...(input.requirement.projectionDigest ? [buildDigestBindingCaveat(input.enforcers.digestBinding, 'projection', input.requirement.projectionDigest, input.requirement.projectionDigest)] : []),
+        ...(input.requirement.offerDigest ? [buildDigestBindingCaveat(input.enforcers.digestBinding, 'offer', input.requirement.offerDigest, input.requirement.offerDigest)] : []),
+    ];
+    const delegation = {
+        delegator: input.parent.delegate, // the party attenuating ITS authority onward
+        delegate: input.grantee,
+        authority: hashDelegation(input.parent, input.chainId, input.delegationManager), // the chain link
+        caveats,
+        salt: input.salt,
+        signature: '0x',
+    };
+    return { ok: true, delegation, digest: hashDelegation(delegation, input.chainId, input.delegationManager) };
+}
+/** Read a mandate's requirement back out of a delegation, or null when it carries no intent binding —
+ *  in which case it is a standing capability, not a mandate. */
+export function readMandate(d, type, enforcers, from) {
+    const h = subsetHandlerFor(type, from);
+    if (!h)
+        return null;
+    const bindings = readDigestBindings(d.caveats, enforcers.digestBinding);
+    if (!bindings.intent)
+        return null;
+    const base = h.fromCaveats(d.caveats, enforcers);
+    if (!base)
+        return null;
+    return { ...base, intentDigest: bindings.intent, ...(bindings.projection ? { projectionDigest: bindings.projection } : {}), ...(bindings.offer ? { offerDigest: bindings.offer } : {}) };
+}
+const lc = (s) => s.toLowerCase();
+/**
+ * Is THIS step covered by the presented mandate, RIGHT NOW?
+ *
+ * Order — and every stage fails closed:
+ *   1. the actor is the delegate;
+ *   2. the delegation is live: signed by its delegator, unrevoked, in window (verifyLiveDelegation);
+ *   3. it IS a mandate: it carries an intent binding, and that binding equals the digest computed from
+ *      the step's intent — the reason check (evaluateCaveats with `digests`, strict);
+ *   4. the step's capability selector satisfies allowedMethods, and its value the value cap;
+ *   5. the handler's type-specific limits admit the step's args.
+ *
+ * Obligations are NOT decided here — they come from policy (spec 350 §3.4) and are attached by the
+ * `MandateVerifier` port implementation that composes this with a `PolicyEvaluator`. This function
+ * answers one question: is the authority present and does it cover the step.
+ */
+export async function verifyMandateForStep(input) {
+    const d = input.presented;
+    const digestOfIntent = intentDigest(input.step.intent);
+    const evidence = {
+        mandateRef: input.checks.delegationDigest(d),
+        intentDigest: digestOfIntent,
+        evaluatedAt: input.now,
+        verdicts: [],
+    };
+    const deny = (code, message) => ({ decision: 'deny', reasons: [{ code, message }], evidence });
+    // 1. actor
+    if (lc(d.delegate) !== lc(input.actor))
+        return deny('actor-not-delegate', 'the acting party is not the mandate\'s delegate');
+    // 2. live
+    const live = await verifyLiveDelegation({ delegation: d, expectedDelegate: input.actor, enforcers: input.enforcers, checks: input.checks, now: input.now });
+    if (!live.ok)
+        return deny('not-live', live.reason);
+    // 3. it is a mandate, and the reason matches
+    const bindings = readDigestBindings(d.caveats, input.enforcers.digestBinding);
+    if (!bindings.intent)
+        return deny('not-a-mandate', 'the presented delegation carries no intent binding — it is a standing capability, and a step needs a mandate');
+    // Spec 384 (336 §3.8) — A STEP THAT FULFILS AN ACCEPTED OFFER runs only under a mandate that NAMES that offer.
+    // The digest-binding caveat compares an `offer` binding when the mandate carries one; a mandate that
+    // carries none would pass the comparison by default, and that is exactly how an offer would become a
+    // commitment without the signature that accepted it. Required here, before the caveats are read.
+    if (input.step.offerDigest && !bindings.offer)
+        return deny('offer-not-bound', 'this step fulfils an accepted offer, and the presented mandate names no offer — an offer becomes a commitment only under the mandate that binds it');
+    if (input.step.projectionDigest && bindings.projection && lc(bindings.projection) !== lc(input.step.projectionDigest))
+        return deny('projection-mismatch', 'the mandate was granted over another projection of the intent');
+    const selector = methodSelector(input.step.capability);
+    const verdicts = evaluateCaveats(d.caveats, {
+        timestamp: input.now,
+        // The call TARGET is the step's resource: the agent being acted for (a membership add on an org),
+        // or the asset contract (a payment). Both are what `allowedTargets` was encoded against.
+        target: (input.step.resource ?? d.delegator),
+        selector,
+        ...(input.step.value !== undefined ? { value: input.step.value } : {}),
+        digests: {
+            intent: digestOfIntent,
+            ...(input.step.projectionDigest ? { projection: input.step.projectionDigest } : {}),
+            ...(input.step.offerDigest ? { offer: input.step.offerDigest } : {}),
+        },
+    }, input.enforcers, { enforceOnChain: true });
+    evidence.verdicts = verdicts.map((v) => ({ enforcer: v.enforcer, allowed: v.allowed, ...(v.reason ? { reason: v.reason } : {}) }));
+    const denied = verdicts.find((v) => !v.allowed);
+    if (denied) {
+        const isReason = /digest mismatch|binding present/.test(denied.reason ?? '');
+        return deny(isReason ? 'intent-mismatch' : 'caveat-denied', denied.reason ?? 'caveat denied');
+    }
+    // 5. type-specific limits
+    const h = subsetHandlerFor(input.requirementType, input.handlers);
+    if (!h)
+        return deny('no-handler', `no subset handler for ${input.requirementType} — an authority nobody can bound is not verified`);
+    const req = readMandate(d, input.requirementType, input.enforcers, input.handlers);
+    if (!req)
+        return deny('not-a-mandate', `the presented delegation does not decode as a ${input.requirementType} mandate`);
+    // Actions, resources and limits are ALL the handler's to judge — a read-back capability mandate
+    // carries `sel:<hex>` actions while a step carries the id, and only the handler knows they are the
+    // same. Asking it "would a requirement shaped like this step be a subset?" gives every type-specific
+    // comparison exactly one definition. The reason names what failed so a denial is actionable.
+    const shaped = stepAsRequirement(req, input.step, h);
+    if (!h.isSubset(shaped, req)) {
+        if (!h.isSubset({ ...shaped, locations: req.locations, limits: req.limits }, req)) {
+            return deny('action-not-granted', `${shaped.actions.map((a) => `"${a}"`).join(', ')} is not among the mandate's actions`);
+        }
+        if (input.step.resource && !h.isSubset({ ...shaped, limits: req.limits }, req)) {
+            return deny('resource-not-granted', `resource ${input.step.resource} is not among the mandate's locations`);
+        }
+        return deny('limit-exceeded', `step exceeds the mandate's ${h.type} limits`);
+    }
+    return { decision: 'allow', obligations: [], evidence };
+}
+/** The step, re-expressed as a requirement, so the handler can compare like with like. */
+function stepAsRequirement(req, step, h) {
+    return {
+        ...req,
+        actions: h.stepActions ? h.stepActions(step) : [step.action],
+        ...(step.resource ? { locations: [step.resource] } : {}),
+        limits: stepLimits(step),
+    };
+}
+/** The step's bounded quantities as `limits`, so the handler compares like with like. */
+function stepLimits(step) {
+    const out = {};
+    for (const [k, v] of Object.entries(step.args ?? {})) {
+        if (typeof v === 'string' || typeof v === 'number')
+            out[k] = v;
+        else if (typeof v === 'bigint')
+            out[k] = v.toString();
+    }
+    return out;
+}
+export { ROOT_AUTHORITY };
+//# sourceMappingURL=mandate.js.map