@kya-brasil/core 0.10.0 → 0.12.0

package/README.md

@@ -43,6 +43,51 @@ const verdict = checkAction(credential.mandate, {
 // verdict.allowed, verdict.checks (every rule evaluated, with its reason), verdict.not_evaluated (extensions)
 ```
 
+## Delegation chains (sub-agents)
+
+A mandate with `delegation: { max_depth, max_ttl_seconds }` lets the agent hand a narrower mandate to another key
+(SPEC section 17). Verify a chain received in `KYA-Delegation`, offline, then evaluate the action on every level:
+
+```ts
+import { checkDelegatedAction, decodeDelegationHeader, verifyDelegationChain } from "@kya-brasil/core";
+const r = await verifyDelegationChain({ credential, chain: decodeDelegationHeader(header) });
+if (!r.ok) reject(r.error);                         // r.delegate is the key that must sign the request
+const verdict = checkDelegatedAction(r.mandates, { action: "quote", amount: 80, currency: "BRL" });
+```
+
+To delegate, `prepareDelegation({ credential, chain, delegate, mandate, ttlSeconds })` returns the delegation and
+the text the delegator signs with its agent key; `mandateSubsetProblems(parent, child)` says why a mandate is broader.
+
+## Status freshness proportional to the amount (offline)
+
+Offline, a verifier only has status evidence of some age: an answer the issuer signed (the credential's status) or a
+CRL (the certificate's). How old is acceptable is the verifier's call, because the verifier runs the risk (SPEC
+section 18). Declare the expected loss you accept per action (`L`) and the revocation rate you assume (`λ`, per hour);
+the maximum age is `L / (amount × λ)`, capped (one day by default):
+
+```ts
+import { freshnessPolicy, checkFreshAction, evidenceFromSignedStatus, evidenceFromRevocation } from "@kya-brasil/core";
+
+const policy = freshnessPolicy({
+  max_expected_loss: { amount: 1, currency: "BRL" },               // L: your tolerance, per action
+  revocation_rate_per_hour: { credential: lambda, certificate: mu }, // λ: what you assume; no default
+  require: ["credential"],                                          // add "certificate" to also require a CRL
+  // max_age_seconds: 86_400, max_clock_skew_seconds: 300, or max_age: ({ amount, kind }) => seconds
+});
+
+// The agent may staple a recent signed verdict to its request: then no network is needed.
+const evidence = [await evidenceFromSignedStatus(stapledVerdict, issuerPublicJwk, credential.credential_id)];
+// evidence.push(evidenceFromRevocation(await checkRevocation({ crlDer, serial, issuerCertificate })));
+
+const r = checkFreshAction(credential.mandate, { action: "buy", amount: 4200, currency: "BRL" }, { policy, evidence });
+// r.allowed; r.freshness.refresh = kinds to fetch again (or ask the agent for); r.freshness.applied = policy and
+// clock used, keep it with the verdict as the risk you accepted
+```
+
+It fails closed: no evidence, another currency, an invalid amount or clock, evidence dated in the future beyond the
+skew, or a CRL past its `nextUpdate`. The freshest statement wins, so a later revocation beats an earlier "active".
+`checkFreshness` and `maxStatusAgeSeconds` are available on their own.
+
 ## Payment instruments (card networks, acquirers, issuers)
 
 A mandate can list the instruments the agent may pay with. Each one is a network and the SHA-256 of a reference

package/dist/delegation.d.ts

@@ -0,0 +1,92 @@
+import { type ActionQuery, type ActionVerdict } from "./mandate.js";
+import { type AgentKey, type Mandate } from "./types.js";
+/** A delegated mandate travels in a header on every request: keep it small. */
+export declare const DELEGATED_MANDATE_MAX_BYTES = 2048;
+export interface Delegation {
+    version: 1;
+    credential_id: string;
+    /** `signature_sha256` of the delegation this one extends; null at depth 1 (signed by the credential's agent). */
+    parent: string | null;
+    /** The key that receives the mandate (evm or web-bot-auth). */
+    delegate: AgentKey;
+    depth: number;
+    issued_at: string;
+    expires_at: string;
+    mandate: Mandate;
+    /** Signature by the delegator: the credential's agent at depth 1, the previous delegate after that. */
+    signature: string;
+}
+/** The credential fields a chain is checked against (a Credential, or the `credential` of a verification). */
+export interface DelegationAnchor {
+    credential_id: string;
+    agent: AgentKey;
+    mandate: Mandate;
+    expires_at: string;
+}
+/**
+ * Why `child` is not contained in `parent` (empty array = contained). Every reserved field the parent restricts
+ * must be at least as restricted in the child; a child may restrict what the parent leaves open. Extensions
+ * (non-reserved fields) are not compared: they are never evaluated.
+ */
+export declare function mandateSubsetProblems(parent: Mandate, child: Mandate): string[];
+export declare function isMandateSubset(parent: Mandate, child: Mandate): boolean;
+/** Validates a mandate to delegate: the usual schema plus the size limit of delegated mandates. */
+export declare function validateDelegatedMandate(input: unknown): Mandate;
+/** The exact text the delegator signs. */
+export declare function delegationText(d: Omit<Delegation, "signature" | "version">): Promise<string>;
+/** Identifier of a signed delegation, used as `parent` by the next one. */
+export declare function delegationRef(d: Pick<Delegation, "signature">): Promise<string>;
+/**
+ * Builds the unsigned delegation that extends `chain` (empty = delegate from the credential itself) and the text
+ * to sign. The delegator signs `text` with its key and sets `signature`. Throws INVALID_INPUT when the policy
+ * does not allow it (depth, lifetime, mandate not contained in the delegator's).
+ */
+export declare function prepareDelegation(p: {
+    credential: DelegationAnchor;
+    chain?: Delegation[];
+    delegate: {
+        kind?: unknown;
+        id?: unknown;
+    };
+    mandate: unknown;
+    ttlSeconds: number;
+    now?: Date;
+}): Promise<{
+    delegation: Omit<Delegation, "signature">;
+    text: string;
+}>;
+export type DelegationChainResult = {
+    ok: true;
+    delegate: AgentKey;
+    depth: number;
+    expires_at: string;
+    mandates: Mandate[];
+    ref: string;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+/**
+ * Verifies a delegation chain against its credential, offline: every link signed by the key above it, depth and
+ * lifetime within each policy, each mandate contained in the one above, nothing expired. On success `delegate` is
+ * the key that must sign the request and `mandates` is every mandate an action must satisfy (credential first).
+ * The credential's own status (active, not revoked) is the caller's to check, as for any request.
+ */
+export declare function verifyDelegationChain(p: {
+    credential: DelegationAnchor;
+    chain: unknown;
+    now?: Date;
+}): Promise<DelegationChainResult>;
+/**
+ * Evaluates an action against every mandate of a verified chain (credential first). Allowed only when all allow
+ * it; `levels[0]` is the credential's mandate, `levels[n]` the mandate of delegation n.
+ */
+export declare function checkDelegatedAction(mandates: Mandate[], q: ActionQuery): {
+    allowed: boolean;
+    levels: ActionVerdict[];
+};
+/** Encodes a chain for the `KYA-Delegation` header (base64url of its JSON). */
+export declare function encodeDelegationHeader(chain: Delegation[]): string;
+/** Decodes a `KYA-Delegation` header; throws INVALID_INPUT when it is not base64url JSON. */
+export declare function decodeDelegationHeader(value: string): unknown;

package/dist/delegation.js

@@ -0,0 +1,268 @@
+/**
+ * Delegation to sub-agents (D-30, docs/SPEC.md section 17).
+ *
+ * The principal allows it once, in the mandate it signs with its certificate (`delegation: { max_depth,
+ * max_ttl_seconds }`). The credential's agent then signs, with its own key, a short-lived delegation that hands a
+ * NARROWER mandate to another key; that key may delegate again while the depth allows. Nothing is stored by the
+ * issuer: the chain travels with the request (`KYA-Delegation`) and any verifier checks it offline against the
+ * credential. An action is allowed only when every mandate in the chain allows it.
+ *
+ * Delegation text (what the delegator signs; EIP-191 for evm/erc8004, raw Ed25519 for web-bot-auth):
+ *   KYA Brasil: delegation
+ *   credential: <credential_id>
+ *   parent: <signature_sha256 of the previous delegation | ->
+ *   delegate: <kind>:<id>
+ *   depth: <1..3>
+ *   issued: <ISO 8601>
+ *   expires: <ISO 8601>
+ *   mandate-sha256: <hex SHA-256 of the canonical JSON of the delegated mandate>
+ */
+import { canonicalize } from "./attestation.js";
+import { normalizeAgentKey, verifyAgentSignature } from "./challenge.js";
+import { DELEGATION_MAX_DEPTH, DELEGATION_MIN_TTL_SECONDS, checkAction, counterpartyMatches, normalizeCounterparty, validateMandate } from "./mandate.js";
+import { KyaError } from "./types.js";
+/** A delegated mandate travels in a header on every request: keep it small. */
+export const DELEGATED_MANDATE_MAX_BYTES = 2048;
+/** Clock difference tolerated on `issued_at`. */
+const SKEW_MS = 300_000;
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+const sha256Hex = async (text) => hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+/**
+ * Why `child` is not contained in `parent` (empty array = contained). Every reserved field the parent restricts
+ * must be at least as restricted in the child; a child may restrict what the parent leaves open. Extensions
+ * (non-reserved fields) are not compared: they are never evaluated.
+ */
+export function mandateSubsetProblems(parent, child) {
+    const p = [];
+    if (parent.actions) {
+        if (!child.actions)
+            p.push("actions: parent restricts actions, delegated mandate must list them");
+        else
+            for (const a of child.actions)
+                if (!parent.actions.includes(a))
+                    p.push(`actions: "${a}" is not in the parent mandate`);
+    }
+    for (const k of ["max_per_operation", "max_per_day"]) {
+        const pm = parent[k];
+        const cm = child[k];
+        if (!pm)
+            continue;
+        if (!cm)
+            p.push(`${k}: parent sets a ceiling, delegated mandate must too`);
+        else if (cm.currency !== pm.currency)
+            p.push(`${k}: currency ${cm.currency} differs from the parent's ${pm.currency}`);
+        else if (cm.amount > pm.amount)
+            p.push(`${k}: ${cm.amount} is above the parent's ${pm.amount}`);
+    }
+    if (parent.currencies) {
+        if (!child.currencies)
+            p.push("currencies: parent restricts currencies, delegated mandate must list them");
+        else
+            for (const c of child.currencies)
+                if (!parent.currencies.includes(c))
+                    p.push(`currencies: ${c} is not in the parent mandate`);
+    }
+    if (parent.counterparties && parent.counterparties.length) {
+        if (!child.counterparties || !child.counterparties.length)
+            p.push("counterparties: parent restricts counterparties, delegated mandate must list them");
+        else
+            for (const c of child.counterparties)
+                if (!parent.counterparties.some((pc) => counterpartyMatches(pc, normalizeCounterparty(c))))
+                    p.push(`counterparties: ${c} is not covered by the parent mandate`);
+    }
+    if (parent.payment_instruments && parent.payment_instruments.length) {
+        if (!child.payment_instruments || !child.payment_instruments.length)
+            p.push("payment_instruments: parent restricts instruments, delegated mandate must list them");
+        else
+            for (const i of child.payment_instruments)
+                if (!parent.payment_instruments.some((pi) => pi.network === i.network && pi.ref_sha256 === i.ref_sha256))
+                    p.push(`payment_instruments: ${i.network} ${i.ref_sha256.slice(0, 12)}… is not in the parent mandate`);
+    }
+    if (parent.valid_from && (!child.valid_from || Date.parse(child.valid_from) < Date.parse(parent.valid_from)))
+        p.push("valid_from: delegated mandate starts before the parent's");
+    if (parent.valid_until && (!child.valid_until || Date.parse(child.valid_until) > Date.parse(parent.valid_until)))
+        p.push("valid_until: delegated mandate ends after the parent's");
+    if (child.delegation) {
+        if (!parent.delegation)
+            p.push("delegation: parent does not allow further delegation");
+        else {
+            if (child.delegation.max_depth > parent.delegation.max_depth - 1)
+                p.push(`delegation.max_depth: at most ${parent.delegation.max_depth - 1} below this level`);
+            if (child.delegation.max_ttl_seconds > parent.delegation.max_ttl_seconds)
+                p.push(`delegation.max_ttl_seconds: above the parent's ${parent.delegation.max_ttl_seconds}`);
+        }
+    }
+    return p;
+}
+export function isMandateSubset(parent, child) {
+    return mandateSubsetProblems(parent, child).length === 0;
+}
+/** Validates a mandate to delegate: the usual schema plus the size limit of delegated mandates. */
+export function validateDelegatedMandate(input) {
+    const m = validateMandate(input);
+    if (JSON.stringify(m).length > DELEGATED_MANDATE_MAX_BYTES)
+        throw new KyaError("INVALID_INPUT", `delegated mandate larger than ${DELEGATED_MANDATE_MAX_BYTES} bytes`);
+    return m;
+}
+/** The exact text the delegator signs. */
+export async function delegationText(d) {
+    return [
+        "KYA Brasil: delegation",
+        `credential: ${d.credential_id}`,
+        `parent: ${d.parent ?? "-"}`,
+        `delegate: ${d.delegate.kind}:${d.delegate.id}`,
+        `depth: ${d.depth}`,
+        `issued: ${d.issued_at}`,
+        `expires: ${d.expires_at}`,
+        `mandate-sha256: ${await sha256Hex(canonicalize(d.mandate))}`
+    ].join("\n");
+}
+/** Identifier of a signed delegation, used as `parent` by the next one. */
+export function delegationRef(d) {
+    return sha256Hex(d.signature);
+}
+/**
+ * Builds the unsigned delegation that extends `chain` (empty = delegate from the credential itself) and the text
+ * to sign. The delegator signs `text` with its key and sets `signature`. Throws INVALID_INPUT when the policy
+ * does not allow it (depth, lifetime, mandate not contained in the delegator's).
+ */
+export async function prepareDelegation(p) {
+    const chain = p.chain ?? [];
+    const now = p.now ?? new Date();
+    const delegate = normalizeAgentKey(p.delegate);
+    if (delegate.kind === "erc8004")
+        throw new KyaError("INVALID_INPUT", "delegate must be an evm or web-bot-auth key");
+    const mandate = validateDelegatedMandate(p.mandate);
+    const last = chain[chain.length - 1];
+    const parentMandate = last ? last.mandate : p.credential.mandate;
+    const policy = parentMandate.delegation;
+    const depth = chain.length + 1;
+    if (!policy)
+        throw new KyaError("INVALID_INPUT", depth === 1 ? "the credential's mandate does not allow delegation" : "the delegator's mandate does not allow further delegation");
+    if (depth > DELEGATION_MAX_DEPTH)
+        throw new KyaError("INVALID_INPUT", `delegation deeper than ${DELEGATION_MAX_DEPTH}`);
+    if (!Number.isInteger(p.ttlSeconds) || p.ttlSeconds < DELEGATION_MIN_TTL_SECONDS || p.ttlSeconds > policy.max_ttl_seconds)
+        throw new KyaError("INVALID_INPUT", `ttlSeconds must be from ${DELEGATION_MIN_TTL_SECONDS} to ${policy.max_ttl_seconds}`);
+    const problems = mandateSubsetProblems(parentMandate, mandate);
+    if (problems.length)
+        throw new KyaError("INVALID_INPUT", `delegated mandate is broader than the delegator's: ${problems.join("; ")}`);
+    let expires = now.getTime() + p.ttlSeconds * 1000;
+    for (const bound of [p.credential.expires_at, last?.expires_at])
+        if (bound)
+            expires = Math.min(expires, Date.parse(bound));
+    const delegation = {
+        version: 1,
+        credential_id: p.credential.credential_id,
+        parent: last ? await delegationRef(last) : null,
+        delegate,
+        depth,
+        issued_at: now.toISOString(),
+        expires_at: new Date(expires).toISOString(),
+        mandate
+    };
+    return { delegation, text: await delegationText(delegation) };
+}
+/**
+ * Verifies a delegation chain against its credential, offline: every link signed by the key above it, depth and
+ * lifetime within each policy, each mandate contained in the one above, nothing expired. On success `delegate` is
+ * the key that must sign the request and `mandates` is every mandate an action must satisfy (credential first).
+ * The credential's own status (active, not revoked) is the caller's to check, as for any request.
+ */
+export async function verifyDelegationChain(p) {
+    const fail = (error, message) => ({ ok: false, error, message });
+    const now = (p.now ?? new Date()).getTime();
+    if (!Array.isArray(p.chain) || p.chain.length === 0)
+        return fail("KYA_DELEGATION_MALFORMED", "delegation chain must be a non-empty array");
+    if (p.chain.length > DELEGATION_MAX_DEPTH)
+        return fail("KYA_DELEGATION_TOO_DEEP", `delegation deeper than ${DELEGATION_MAX_DEPTH}`);
+    let signer = p.credential.agent;
+    let parentMandate = p.credential.mandate;
+    let parentRef = null;
+    let notAfter = Date.parse(p.credential.expires_at);
+    if (!Number.isFinite(notAfter))
+        return fail("KYA_DELEGATION_MALFORMED", "the credential has no valid expires_at");
+    const mandates = [p.credential.mandate];
+    for (let i = 0; i < p.chain.length; i++) {
+        const at = `delegation ${i + 1}`;
+        const raw = p.chain[i];
+        if (!raw || typeof raw !== "object" || raw.version !== 1 || typeof raw.signature !== "string" || typeof raw.issued_at !== "string" || typeof raw.expires_at !== "string")
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: not a v1 delegation`);
+        if (raw.credential_id !== p.credential.credential_id)
+            return fail("KYA_DELEGATION_MISMATCH", `${at}: issued under another credential`);
+        if (raw.depth !== i + 1)
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: depth must be ${i + 1}`);
+        if ((raw.parent ?? null) !== parentRef)
+            return fail("KYA_DELEGATION_MISMATCH", `${at}: does not extend the previous link`);
+        let delegate;
+        let mandate;
+        try {
+            delegate = normalizeAgentKey(raw.delegate ?? {});
+            if (delegate.kind === "erc8004")
+                throw new KyaError("INVALID_INPUT", "erc8004 delegate");
+            mandate = validateDelegatedMandate(raw.mandate);
+        }
+        catch (e) {
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: ${e.message}`);
+        }
+        if (delegate.id !== raw.delegate?.id || canonicalize(mandate) !== canonicalize(raw.mandate))
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: delegate or mandate not in normalized form`);
+        const policy = parentMandate.delegation;
+        if (!policy)
+            return fail("KYA_DELEGATION_NOT_ALLOWED", i === 0 ? "the credential's mandate does not allow delegation" : `${at}: the delegator's mandate does not allow further delegation`);
+        const issued = Date.parse(raw.issued_at);
+        const expires = Date.parse(raw.expires_at);
+        if (!Number.isFinite(issued) || !Number.isFinite(expires) || expires <= issued)
+            return fail("KYA_DELEGATION_MALFORMED", `${at}: bad issued_at / expires_at`);
+        if (expires - issued > policy.max_ttl_seconds * 1000)
+            return fail("KYA_DELEGATION_TTL", `${at}: lives longer than ${policy.max_ttl_seconds}s`);
+        if (expires > notAfter)
+            return fail("KYA_DELEGATION_TTL", `${at}: outlives the link above it`);
+        if (issued > now + SKEW_MS)
+            return fail("KYA_DELEGATION_NOT_YET_VALID", `${at}: issued in the future`);
+        if (expires < now)
+            return fail("KYA_DELEGATION_EXPIRED", `${at}: expired at ${raw.expires_at}`);
+        const problems = mandateSubsetProblems(parentMandate, mandate);
+        if (problems.length)
+            return fail("KYA_DELEGATION_BROADER", `${at}: ${problems.join("; ")}`);
+        const text = await delegationText({ credential_id: raw.credential_id, parent: parentRef, delegate, depth: i + 1, issued_at: raw.issued_at, expires_at: raw.expires_at, mandate });
+        if (!(await verifyAgentSignature(signer, text, raw.signature)))
+            return fail("KYA_DELEGATION_BAD_SIGNATURE", `${at}: not signed by the key above it`);
+        signer = delegate;
+        parentMandate = mandate;
+        parentRef = await delegationRef({ signature: raw.signature });
+        notAfter = expires;
+        mandates.push(mandate);
+    }
+    return { ok: true, delegate: signer, depth: p.chain.length, expires_at: new Date(notAfter).toISOString(), mandates, ref: parentRef };
+}
+/**
+ * Evaluates an action against every mandate of a verified chain (credential first). Allowed only when all allow
+ * it; `levels[0]` is the credential's mandate, `levels[n]` the mandate of delegation n.
+ */
+export function checkDelegatedAction(mandates, q) {
+    const levels = mandates.map((m) => checkAction(m, q));
+    return { allowed: levels.length > 0 && levels.every((l) => l.allowed), levels };
+}
+/** Encodes a chain for the `KYA-Delegation` header (base64url of its JSON). */
+export function encodeDelegationHeader(chain) {
+    const bytes = new TextEncoder().encode(JSON.stringify(chain));
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCodePoint(b);
+    const b64 = btoa(s).replaceAll("+", "-").replaceAll("/", "_");
+    let end = b64.length;
+    while (end > 0 && b64[end - 1] === "=")
+        end--;
+    return b64.slice(0, end);
+}
+/** Decodes a `KYA-Delegation` header; throws INVALID_INPUT when it is not base64url JSON. */
+export function decodeDelegationHeader(value) {
+    try {
+        const b64 = value.trim().replaceAll("-", "+").replaceAll("_", "/");
+        const bin = atob(b64.padEnd(Math.ceil(b64.length / 4) * 4, "="));
+        return JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, (c) => c.codePointAt(0) ?? 0)));
+    }
+    catch {
+        throw new KyaError("INVALID_INPUT", "KYA-Delegation is not base64url JSON");
+    }
+}

package/dist/freshness.d.ts

@@ -0,0 +1,119 @@
+import { type ActionQuery, type ActionVerdict } from "./mandate.js";
+import { type Mandate } from "./types.js";
+import type { RevocationStatus } from "./revocation.js";
+/** What a piece of evidence is about: the KYA credential (issuer status) or the ICP-Brasil certificate (CRL). */
+export type EvidenceKind = "credential" | "certificate";
+export interface StatusEvidence {
+    kind: EvidenceKind;
+    /** True when the evidence says the subject is in force: credential `active`, certificate not on the CRL. */
+    in_force: boolean;
+    /** Instant at which the status was true: the issuer's `attestation.signed_at`, or the CRL's thisUpdate. */
+    as_of: string;
+    /** Instant after which the evidence must not be used at all (a CRL's nextUpdate). */
+    valid_until?: string | null;
+    /** Free text for the verdict, e.g. "issuer verdict" or "CRL of AC X". */
+    source?: string;
+    /** Status as stated by the evidence, for the verdict ("active", "revoked", "certificateHold", ...). */
+    status?: string;
+}
+export declare const FRESHNESS_DEFAULT_MAX_AGE_SECONDS = 86400;
+export declare const FRESHNESS_LIMIT_MAX_AGE_SECONDS: number;
+export declare const FRESHNESS_DEFAULT_CLOCK_SKEW_SECONDS = 300;
+export interface FreshnessPolicyInput {
+    /** L: the expected loss the verifier accepts per action, in the currency of the amounts it checks. */
+    max_expected_loss: {
+        amount: number;
+        currency: string;
+    };
+    /** λ: probability per hour that a subject in force stops being so, per kind of evidence. */
+    revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
+    /** Kinds of evidence an action needs. Default ["credential"]. */
+    require?: EvidenceKind[];
+    /** Ceiling on the evidence age, whatever the amount. Default 86400 (one day), at most 90 days. */
+    max_age_seconds?: number;
+    /** Tolerance for evidence dated after the verifier's clock. Default 300, at most 3600. */
+    max_clock_skew_seconds?: number;
+    /**
+     * Replaces the default formula. Receives the amount (undefined when the action has none) and the kind;
+     * returns seconds. The result is clamped to [0, max_age_seconds]; anything not finite counts as 0.
+     */
+    max_age?: (p: {
+        amount: number | undefined;
+        currency: string;
+        kind: EvidenceKind;
+    }) => number;
+}
+export interface FreshnessPolicy {
+    max_expected_loss: {
+        amount: number;
+        currency: string;
+    };
+    revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
+    require: EvidenceKind[];
+    max_age_seconds: number;
+    max_clock_skew_seconds: number;
+    max_age?: FreshnessPolicyInput["max_age"];
+}
+/** Validates and normalizes a policy. Throws INVALID_INPUT on anything that would make it fail open. */
+export declare function freshnessPolicy(input: FreshnessPolicyInput): FreshnessPolicy;
+/** Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency). */
+export declare function maxStatusAgeSeconds(policy: FreshnessPolicy, kind: EvidenceKind, amount?: number): number;
+export interface FreshnessCheck {
+    rule: "freshness";
+    kind: EvidenceKind;
+    ok: boolean;
+    detail: string;
+    age_seconds: number | null;
+    max_age_seconds: number;
+}
+export interface FreshnessVerdict {
+    ok: boolean;
+    checks: FreshnessCheck[];
+    /** Kinds for which fresher (or any) evidence would change the answer: fetch it, or ask the agent for it. */
+    refresh: EvidenceKind[];
+    /** The policy and clock actually applied, to keep with the verdict as proof of the risk accepted. */
+    applied: {
+        now: string;
+        amount: number | null;
+        currency: string;
+        max_expected_loss: {
+            amount: number;
+            currency: string;
+        };
+        revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
+        max_age_seconds: number;
+        max_clock_skew_seconds: number;
+        custom_max_age: boolean;
+    };
+}
+/**
+ * Checks that, for every kind the policy requires, the freshest evidence given says "in force", is not
+ * past its own validity, is not dated in the future beyond the clock skew, and is younger than the maximum
+ * age for this amount. Fails closed: missing, malformed or foreign-currency input never passes.
+ */
+export declare function checkFreshness(policy: FreshnessPolicy, evidence: StatusEvidence[], q?: {
+    amount?: number;
+    currency?: string;
+    now?: Date;
+}): FreshnessVerdict;
+/**
+ * The mandate (checkAction) and the freshness of the status, in one answer: allowed only when both pass.
+ * The freshness check uses the action's amount and currency and the same clock.
+ */
+export declare function checkFreshAction(mandate: Mandate, q: ActionQuery, p: {
+    policy: FreshnessPolicy;
+    evidence: StatusEvidence[];
+}): {
+    allowed: boolean;
+    mandate: ActionVerdict;
+    freshness: FreshnessVerdict;
+};
+/** Evidence about the certificate from a CRL lookup (checkRevocation / verifyCrl().lookup). */
+export declare function evidenceFromRevocation(r: RevocationStatus, source?: string): StatusEvidence;
+/**
+ * Evidence about the credential from an answer the issuer signed (a verdict from /allowed, a paid
+ * verification receipt): any answer carrying `credential_id`, `status` and an Ed25519 `attestation`. The
+ * agent can staple such an answer to its request so the verifier needs no network. The answer must be
+ * about `credentialId` and verify with the issuer's key; the status instant is the signature's.
+ */
+export declare function evidenceFromSignedStatus(answer: Record<string, unknown>, issuerPublicJwk: JsonWebKey, credentialId: string): Promise<StatusEvidence>;

package/dist/freshness.js

@@ -0,0 +1,206 @@
+/**
+ * Status freshness proportional to what is at stake (D-32, SPEC section 18).
+ *
+ * A verifier working offline holds evidence of status that is some time old: an issuer answer signed at a
+ * given instant (the credential's status), or a CRL issued at a given instant (the e-CNPJ / e-CPF
+ * certificate's status). Following Rivest (1998), the recency requirement is set by whoever accepts the
+ * action and runs the risk, not by the issuer: this module turns the verifier's loss tolerance into a
+ * maximum evidence age that shrinks as the amount grows, and refuses older evidence.
+ *
+ * Expected loss of accepting an action of value v on evidence of age t, when status changes at a rate of
+ * λ per hour: v × λ × t. Keeping it under the tolerance L gives the default maximum age
+ *
+ *     max_age(v) = L / (v × λ)   hours, capped by max_age_seconds.
+ *
+ * Pure functions, no network: the caller obtains the evidence (cache, CRL download, an issuer answer the
+ * agent staples to its request) and passes the clock it trusts.
+ */
+import { verifyAttestation } from "./attestation.js";
+import { checkAction } from "./mandate.js";
+import { KyaError } from "./types.js";
+export const FRESHNESS_DEFAULT_MAX_AGE_SECONDS = 86_400;
+export const FRESHNESS_LIMIT_MAX_AGE_SECONDS = 90 * 86_400;
+export const FRESHNESS_DEFAULT_CLOCK_SKEW_SECONDS = 300;
+const KINDS = ["credential", "certificate"];
+const CURRENCY = /^[A-Z0-9]{2,10}$/;
+function bad(message) {
+    throw new KyaError("INVALID_INPUT", `freshness policy: ${message}`);
+}
+/** Validates and normalizes a policy. Throws INVALID_INPUT on anything that would make it fail open. */
+export function freshnessPolicy(input) {
+    if (!input || typeof input !== "object")
+        bad("expected an object");
+    const loss = input.max_expected_loss;
+    if (!loss || typeof loss.amount !== "number" || !Number.isFinite(loss.amount) || loss.amount < 0)
+        bad("max_expected_loss.amount must be a finite number >= 0");
+    const currency = typeof loss.currency === "string" ? loss.currency.trim().toUpperCase() : "";
+    if (!CURRENCY.test(currency))
+        bad("max_expected_loss.currency must match ^[A-Z0-9]{2,10}$");
+    const require = input.require ?? ["credential"];
+    if (!Array.isArray(require) || !require.length || require.some((k) => !KINDS.includes(k)))
+        bad(`require must list one or more of ${KINDS.join(", ")}`);
+    const rates = {};
+    for (const [k, v] of Object.entries(input.revocation_rate_per_hour ?? {})) {
+        if (!KINDS.includes(k))
+            bad(`unknown evidence kind "${k}" in revocation_rate_per_hour`);
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+            bad(`revocation_rate_per_hour.${k} must be a finite number >= 0`);
+        rates[k] = v;
+    }
+    if (!input.max_age)
+        for (const k of require)
+            if (rates[k] === undefined)
+                bad(`revocation_rate_per_hour.${k} is required (or give max_age)`);
+    const ceiling = input.max_age_seconds ?? FRESHNESS_DEFAULT_MAX_AGE_SECONDS;
+    if (!Number.isInteger(ceiling) || ceiling < 0 || ceiling > FRESHNESS_LIMIT_MAX_AGE_SECONDS)
+        bad(`max_age_seconds must be an integer in 0..${FRESHNESS_LIMIT_MAX_AGE_SECONDS}`);
+    const skew = input.max_clock_skew_seconds ?? FRESHNESS_DEFAULT_CLOCK_SKEW_SECONDS;
+    if (!Number.isInteger(skew) || skew < 0 || skew > 3600)
+        bad("max_clock_skew_seconds must be an integer in 0..3600");
+    if (input.max_age !== undefined && typeof input.max_age !== "function")
+        bad("max_age must be a function");
+    return { max_expected_loss: { amount: loss.amount, currency }, revocation_rate_per_hour: rates, require: [...new Set(require)], max_age_seconds: ceiling, max_clock_skew_seconds: skew, max_age: input.max_age };
+}
+/** Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency). */
+export function maxStatusAgeSeconds(policy, kind, amount) {
+    const ceiling = policy.max_age_seconds;
+    let seconds;
+    if (policy.max_age) {
+        seconds = policy.max_age({ amount, currency: policy.max_expected_loss.currency, kind });
+    }
+    else {
+        const rate = policy.revocation_rate_per_hour[kind] ?? 0;
+        if (amount === undefined || amount <= 0 || rate === 0)
+            return ceiling;
+        seconds = (policy.max_expected_loss.amount / (amount * rate)) * 3600;
+    }
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return seconds === Infinity ? ceiling : 0;
+    // The epsilon keeps binary rounding (1 / (10000 × 1e-4) × 3600 = 3599.999…) from costing a whole second.
+    return Math.min(ceiling, Math.floor(seconds + 1e-6));
+}
+function human(seconds) {
+    if (seconds < 120)
+        return `${seconds} s`;
+    if (seconds < 7200)
+        return `${Math.floor(seconds / 60)} min`;
+    if (seconds < 172_800)
+        return `${Math.floor(seconds / 3600)} h`;
+    return `${Math.floor(seconds / 86_400)} d`;
+}
+/**
+ * Checks that, for every kind the policy requires, the freshest evidence given says "in force", is not
+ * past its own validity, is not dated in the future beyond the clock skew, and is younger than the maximum
+ * age for this amount. Fails closed: missing, malformed or foreign-currency input never passes.
+ */
+export function checkFreshness(policy, evidence, q = {}) {
+    const now = q.now ?? new Date();
+    const nowMs = now.getTime();
+    const currency = policy.max_expected_loss.currency;
+    const qCurrency = q.currency?.trim().toUpperCase();
+    const amount = q.amount;
+    const applied = {
+        now: Number.isNaN(nowMs) ? "invalid" : now.toISOString(),
+        amount: amount ?? null,
+        currency,
+        max_expected_loss: policy.max_expected_loss,
+        revocation_rate_per_hour: policy.revocation_rate_per_hour,
+        max_age_seconds: policy.max_age_seconds,
+        max_clock_skew_seconds: policy.max_clock_skew_seconds,
+        custom_max_age: !!policy.max_age
+    };
+    const checks = [];
+    const refresh = [];
+    if (Number.isNaN(nowMs)) {
+        for (const kind of policy.require)
+            checks.push({ rule: "freshness", kind, ok: false, detail: "the verifier's clock is not a valid date", age_seconds: null, max_age_seconds: 0 });
+        return { ok: false, checks, refresh, applied };
+    }
+    const amountOk = amount === undefined || (typeof amount === "number" && Number.isFinite(amount) && amount >= 0);
+    if (!amountOk || (qCurrency && qCurrency !== currency)) {
+        const detail = !amountOk ? "amount is not a finite number >= 0" : `loss tolerance is in ${currency}, operation in ${qCurrency}`;
+        for (const kind of policy.require)
+            checks.push({ rule: "freshness", kind, ok: false, detail, age_seconds: null, max_age_seconds: 0 });
+        return { ok: false, checks, refresh, applied };
+    }
+    for (const kind of policy.require) {
+        const max = maxStatusAgeSeconds(policy, kind, amount);
+        const limit = `${amount === undefined ? "no amount given, ceiling applies" : `for ${amount} ${currency}`}: at most ${human(max)}`;
+        const usable = evidence.filter((e) => e && e.kind === kind && !Number.isNaN(Date.parse(e.as_of)));
+        if (!usable.length) {
+            checks.push({ rule: "freshness", kind, ok: false, detail: `no ${kind} status evidence; ${limit}`, age_seconds: null, max_age_seconds: max });
+            refresh.push(kind);
+            continue;
+        }
+        // Freshest first: a newer statement supersedes an older one, whatever it says.
+        let e = usable[0];
+        let asOf = Date.parse(e.as_of);
+        for (const candidate of usable) {
+            const t = Date.parse(candidate.as_of);
+            if (t > asOf) {
+                e = candidate;
+                asOf = t;
+            }
+        }
+        const age = Math.floor((nowMs - asOf) / 1000);
+        const from = e.source ? ` (${e.source})` : "";
+        if (asOf - nowMs > policy.max_clock_skew_seconds * 1000) {
+            checks.push({ rule: "freshness", kind, ok: false, detail: `${kind} evidence${from} is dated ${e.as_of}, after the verifier's clock ${applied.now} beyond the ${policy.max_clock_skew_seconds} s tolerance`, age_seconds: age, max_age_seconds: max });
+            continue;
+        }
+        if (e.valid_until && !Number.isNaN(Date.parse(e.valid_until)) && Date.parse(e.valid_until) < nowMs) {
+            checks.push({ rule: "freshness", kind, ok: false, detail: `${kind} evidence${from} expired at ${e.valid_until}`, age_seconds: Math.max(0, age), max_age_seconds: max });
+            refresh.push(kind);
+            continue;
+        }
+        if (!e.in_force) {
+            checks.push({ rule: "freshness", kind, ok: false, detail: `${kind} is not in force${e.status ? ` (${e.status})` : ""} as of ${e.as_of}${from}`, age_seconds: Math.max(0, age), max_age_seconds: max });
+            continue;
+        }
+        const ageShown = Math.max(0, age);
+        const fresh = ageShown <= max;
+        checks.push({ rule: "freshness", kind, ok: fresh, detail: `${kind} status${from} is ${human(ageShown)} old; ${limit}`, age_seconds: ageShown, max_age_seconds: max });
+        if (!fresh)
+            refresh.push(kind);
+    }
+    return { ok: checks.length > 0 && checks.every((c) => c.ok), checks, refresh, applied };
+}
+/**
+ * The mandate (checkAction) and the freshness of the status, in one answer: allowed only when both pass.
+ * The freshness check uses the action's amount and currency and the same clock.
+ */
+export function checkFreshAction(mandate, q, p) {
+    const now = q.now ?? new Date();
+    const m = checkAction(mandate, { ...q, now });
+    const f = checkFreshness(p.policy, p.evidence, { amount: q.amount, currency: q.currency, now });
+    return { allowed: m.allowed && f.ok, mandate: m, freshness: f };
+}
+/** Evidence about the certificate from a CRL lookup (checkRevocation / verifyCrl().lookup). */
+export function evidenceFromRevocation(r, source) {
+    return {
+        kind: "certificate",
+        in_force: !r.revoked,
+        as_of: r.crl_this_update,
+        valid_until: r.crl_next_update,
+        source: source ?? "CRL",
+        status: r.revoked ? (r.reason ?? "revoked") : "not revoked"
+    };
+}
+/**
+ * Evidence about the credential from an answer the issuer signed (a verdict from /allowed, a paid
+ * verification receipt): any answer carrying `credential_id`, `status` and an Ed25519 `attestation`. The
+ * agent can staple such an answer to its request so the verifier needs no network. The answer must be
+ * about `credentialId` and verify with the issuer's key; the status instant is the signature's.
+ */
+export async function evidenceFromSignedStatus(answer, issuerPublicJwk, credentialId) {
+    if (!answer || typeof answer !== "object")
+        throw new KyaError("INVALID_INPUT", "signed status: expected an object");
+    if (answer.credential_id !== credentialId)
+        throw new KyaError("INVALID_INPUT", `signed status is about ${String(answer.credential_id)}, not ${credentialId}`);
+    if (typeof answer.status !== "string")
+        throw new KyaError("INVALID_INPUT", "signed status has no status");
+    const sig = await verifyAttestation(answer, issuerPublicJwk);
+    if (!sig.valid || !sig.signed_at)
+        throw new KyaError("INVALID_INPUT", `signed status does not verify: ${sig.reason ?? "no signature time"}`);
+    return { kind: "credential", in_force: answer.status === "active", as_of: sig.signed_at, source: "issuer signed status", status: answer.status };
+}

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export * from "./erc8004.js";
 export * from "./ecnpj-sign.js";
 export * from "./cloud-sign.js";
 export * from "./person.js";
+export * from "./delegation.js";
+export * from "./freshness.js";

package/dist/index.js

@@ -10,3 +10,5 @@ export * from "./erc8004.js";
 export * from "./ecnpj-sign.js";
 export * from "./cloud-sign.js";
 export * from "./person.js";
+export * from "./delegation.js";
+export * from "./freshness.js";

package/dist/mandate.d.ts

@@ -4,7 +4,11 @@
  * `checkAction`; extensions are carried in the credential untouched and never evaluated.
  * Validation is hand-written (no Ajv: `new Function` is blocked on Workers).
  */
-import { type Mandate, type MandateCore } from "./types.js";
+import { type DelegationPolicy, type Mandate, type MandateCore } from "./types.js";
+/** Delegation bounds (D-30): how deep a chain may go and how long one link may live. */
+export declare const DELEGATION_MAX_DEPTH = 3;
+export declare const DELEGATION_MIN_TTL_SECONDS = 60;
+export declare const DELEGATION_MAX_TTL_SECONDS = 86400;
 export declare const MANDATE_SCHEMA: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly $id: "https://kya.example/.well-known/kya-mandate.schema.json";
@@ -72,6 +76,26 @@ export declare const MANDATE_SCHEMA: {
                 readonly additionalProperties: false;
             };
         };
+        readonly delegation: {
+            readonly type: "object";
+            readonly description: "Allows the agent to hand a narrower mandate to other keys (sub-agents), without a new certificate signature. Absent = no delegation.";
+            readonly properties: {
+                readonly max_depth: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 3;
+                    readonly description: "How many levels of sub-agents below this agent.";
+                };
+                readonly max_ttl_seconds: {
+                    readonly type: "integer";
+                    readonly minimum: 60;
+                    readonly maximum: 86400;
+                    readonly description: "Longest lifetime of one delegation.";
+                };
+            };
+            readonly required: readonly ["max_depth", "max_ttl_seconds"];
+            readonly additionalProperties: false;
+        };
         readonly valid_from: {
             readonly type: "string";
             readonly format: "date-time";
@@ -102,12 +126,19 @@ export declare const MANDATE_SCHEMA: {
 };
 /** Throws KyaError INVALID_INPUT with the first problem found; returns the mandate with reserved fields normalized. */
 export declare function validateMandate(input: unknown): Mandate;
+/** Validates a `delegation` field of a mandate (used by validateMandate). */
+export declare function validateDelegationPolicy(v: unknown): DelegationPolicy;
 /**
  * SHA-256 (lowercase hex) of a payment reference as a mandate stores it (D-25): UTF-8, whitespace removed,
  * case kept. Use it on the network's token reference or PAR, never on a card number.
  */
 export declare function hashPaymentRef(ref: string): Promise<string>;
 export declare function normalizeCounterparty(c: string): string;
+/**
+ * Whether a mandate entry matches a normalized counterparty: exactly, or for a `*.domain` entry the domain itself
+ * and any subdomain (SPEC section 5).
+ */
+export declare function counterpartyMatches(entry: string, counterparty: string): boolean;
 export interface ActionQuery {
     action?: string;
     amount?: number;

package/dist/mandate.js

@@ -5,6 +5,10 @@
  * Validation is hand-written (no Ajv: `new Function` is blocked on Workers).
  */
 import { KyaError } from "./types.js";
+/** Delegation bounds (D-30): how deep a chain may go and how long one link may live. */
+export const DELEGATION_MAX_DEPTH = 3;
+export const DELEGATION_MIN_TTL_SECONDS = 60;
+export const DELEGATION_MAX_TTL_SECONDS = 86_400;
 export const MANDATE_SCHEMA = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://kya.example/.well-known/kya-mandate.schema.json",
@@ -32,6 +36,16 @@ export const MANDATE_SCHEMA = {
                 additionalProperties: false
             }
         },
+        delegation: {
+            type: "object",
+            description: "Allows the agent to hand a narrower mandate to other keys (sub-agents), without a new certificate signature. Absent = no delegation.",
+            properties: {
+                max_depth: { type: "integer", minimum: 1, maximum: 3, description: "How many levels of sub-agents below this agent." },
+                max_ttl_seconds: { type: "integer", minimum: 60, maximum: 86400, description: "Longest lifetime of one delegation." }
+            },
+            required: ["max_depth", "max_ttl_seconds"],
+            additionalProperties: false
+        },
         valid_from: { type: "string", format: "date-time" },
         valid_until: { type: "string", format: "date-time" }
     },
@@ -68,6 +82,8 @@ export function validateMandate(input) {
     }
     if (m.payment_instruments !== undefined)
         m.payment_instruments = validatePaymentInstruments(m.payment_instruments, bad);
+    if (m.delegation !== undefined)
+        m.delegation = validateDelegationPolicy(m.delegation);
     for (const k of ["valid_from", "valid_until"])
         if (m[k] !== undefined && !isoDate(m[k]))
             throw bad(k, "ISO 8601 date-time");
@@ -75,6 +91,20 @@ export function validateMandate(input) {
         throw bad("valid_until", "must be after valid_from");
     return m;
 }
+/** Validates a `delegation` field of a mandate (used by validateMandate). */
+export function validateDelegationPolicy(v) {
+    const bad = (why) => new KyaError("INVALID_INPUT", `mandate.delegation: ${why}`);
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw bad(`object { max_depth: 1..${DELEGATION_MAX_DEPTH}, max_ttl_seconds: ${DELEGATION_MIN_TTL_SECONDS}..${DELEGATION_MAX_TTL_SECONDS} }`);
+    const { max_depth, max_ttl_seconds, ...rest } = v;
+    if (Object.keys(rest).length)
+        throw bad(`unknown field(s): ${Object.keys(rest).join(", ")}`);
+    if (!Number.isInteger(max_depth) || max_depth < 1 || max_depth > DELEGATION_MAX_DEPTH)
+        throw bad(`max_depth must be an integer from 1 to ${DELEGATION_MAX_DEPTH}`);
+    if (!Number.isInteger(max_ttl_seconds) || max_ttl_seconds < DELEGATION_MIN_TTL_SECONDS || max_ttl_seconds > DELEGATION_MAX_TTL_SECONDS)
+        throw bad(`max_ttl_seconds must be an integer from ${DELEGATION_MIN_TTL_SECONDS} to ${DELEGATION_MAX_TTL_SECONDS}`);
+    return { max_depth: max_depth, max_ttl_seconds: max_ttl_seconds };
+}
 const NETWORK = /^[a-z][a-z0-9_-]{1,31}$/;
 function validatePaymentInstruments(v, bad) {
     if (!Array.isArray(v) || v.length > 20)
@@ -123,7 +153,22 @@ export function normalizeCounterparty(c) {
         return digits.toUpperCase();
     return s.toLowerCase();
 }
-const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until"];
+/**
+ * Whether a mandate entry matches a normalized counterparty: exactly, or for a `*.domain` entry the domain itself
+ * and any subdomain (SPEC section 5).
+ */
+export function counterpartyMatches(entry, counterparty) {
+    const e = normalizeCounterparty(entry);
+    if (e === counterparty)
+        return true;
+    if (!e.startsWith("*."))
+        return false;
+    const base = e.slice(2);
+    return counterparty === base || counterparty.endsWith(`.${base}`);
+}
+// `delegation` is reserved (validated, never listed as not evaluated) but is not a rule on actions: it is
+// enforced when a delegation chain is verified (delegation.ts).
+const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until", "delegation"];
 /** Deterministic evaluation of the reserved mandate fields against an intended action. */
 export function checkAction(mandate, q) {
     const now = q.now ?? new Date();
@@ -150,7 +195,8 @@ export function checkAction(mandate, q) {
     }
     if (mandate.counterparties && mandate.counterparties.length && q.counterparty) {
         const c = normalizeCounterparty(q.counterparty);
-        push("counterparties", mandate.counterparties.includes(c), `${c} ${mandate.counterparties.includes(c) ? "is" : "is not"} an allowed counterparty`);
+        const ok = mandate.counterparties.some((m) => counterpartyMatches(m, c));
+        push("counterparties", ok, `${c} ${ok ? "is" : "is not"} an allowed counterparty`);
     }
     if (mandate.payment_instruments && mandate.payment_instruments.length && q.payment_ref_sha256) {
         const h = q.payment_ref_sha256.trim().toLowerCase();

package/dist/types.d.ts

@@ -27,6 +27,11 @@ export interface PaymentInstrument {
     /** Optional human label, e.g. "corporate card, purchasing". Never the card number. */
     label?: string;
 }
+/** What a mandate allows its agent to delegate (D-30). */
+export interface DelegationPolicy {
+    max_depth: number;
+    max_ttl_seconds: number;
+}
 export interface MandateCore {
     /** Actions the agent may take on behalf of the company (free vocabulary, lowercase: buy, sell, quote, pay, sign, ...). */
     actions?: string[];
@@ -50,6 +55,11 @@ export interface MandateCore {
      * removed, case kept); empty or absent = any.
      */
     payment_instruments?: PaymentInstrument[];
+    /**
+     * Delegation to sub-agents (D-30): the agent may hand a narrower mandate to other keys, up to `max_depth`
+     * levels below it, each delegation living at most `max_ttl_seconds`. Absent = the agent cannot delegate.
+     */
+    delegation?: DelegationPolicy;
     /** Mandate validity (ISO dates); the credential never outlives it. */
     valid_from?: string;
     valid_until?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/core",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "KYA Brasil as a library: verify and issue know-your-agent credentials for Brazilian companies without any hosted service. e-CNPJ (ICP-Brasil) CMS signature and chain validation, CRL revocation, CNPJ, agent key challenges (EVM, Ed25519 / Web Bot Auth, ERC-8004), mandate schema and evaluation (including payment instruments for card networks and acquirers), credential build, Ed25519 signing and verification, and e-CNPJ signing for the holder (A1 .pfx, or any token/HSM/cloud signer through a raw-sign callback). Pure functions: storage and network are yours.",
   "license": "MIT",
   "type": "module",