@kya-brasil/agent-tools 0.10.0 → 0.11.0

package/README.md

@@ -100,6 +100,23 @@ const { response, callee } = await me.fetch("https://beta.com.br/orders", { meth
 if (!callee?.ok) throw new Error("unsigned or invalid callee");       // callee.kya: principal, mandate, status
 ```
 
+### Sub-agents (delegation, D-30): one certificate signature for the whole tree
+
+When the mandate carries `delegation: { max_depth, max_ttl_seconds }`, the agent hands a narrower mandate to
+another key with its own signature, no new e-CNPJ or e-CPF signature. The sub-agent signs its requests with its own
+key and sends the chain; your middleware verifies it offline and `check()` / `allowed()` evaluate every mandate in it.
+
+```ts
+import { signDelegation, signRequest } from "@kya-brasil/agent-tools";
+const chain = await signDelegation({ credential, key: agentKey, delegate: { kind: "web-bot-auth", id: subPublicKey },
+  mandate: { actions: ["quote"], max_per_operation: { amount: 500, currency: "BRL" } }, ttlSeconds: 600 });
+const headers = await signRequest({ credentialId, key: subKey, delegation: chain, method: "GET", url });
+// server side: c.get("kya").delegation → { depth, delegate, mandates, expires_at, chain }
+```
+
+Short-lived (at most `max_ttl_seconds`, never past the credential), contained in the parent mandate, at most 3
+levels; revoking the credential ends the whole tree. The issuer stores nothing. [SPEC](https://github.com/celfons/kya-brasil/blob/main/docs/SPEC.md) section 17.
+
 ## Person: an agent that acts for you (e-CPF)
 
 ```ts

package/dist/auth.d.ts

@@ -1,11 +1,14 @@
-import { type ActionQuery, type AgentKey, type CredentialStatus, type KyaClient, type Mandate, type Verdict, type Verification, type KyaOptions } from "./index.js";
+import { type Delegation, type DelegationAnchor } from "@kya-brasil/core";
+import { type ActionQuery, type AgentKey, type Credential, type CredentialStatus, type KyaClient, type Mandate, type Verdict, type Verification, type KyaOptions } from "./index.js";
 export declare const KYA_HEADERS: {
     readonly credential: "kya-credential";
     readonly created: "kya-created";
     readonly expires: "kya-expires";
     readonly signature: "kya-signature";
     readonly content: "kya-content-sha256";
+    readonly delegation: "kya-delegation";
 };
+export type { Delegation } from "@kya-brasil/core";
 export declare function sha256Hex(data: string | ArrayBuffer | Uint8Array): Promise<string>;
 /** Canonical URL for the signature: origin (lowercase host) + path + query, no fragment. */
 export declare function canonicalUrl(url: string): string;
@@ -16,6 +19,7 @@ export declare function requestText(p: {
     created: number;
     expires: number;
     contentSha256?: string | null;
+    delegationSha256?: string | null;
 }): string;
 export type SigningKey = {
     kind: "evm" | "erc8004";
@@ -24,7 +28,10 @@ export type SigningKey = {
     kind: "web-bot-auth";
     privateKey: CryptoKey | string;
 };
-/** Signs a request with the agent key and returns the KYA headers to send with it. */
+/**
+ * Signs a request with the agent key and returns the KYA headers to send with it. A sub-agent passes its
+ * `delegation` chain (from signDelegation) and signs with its own key.
+ */
 export declare function signRequest(p: {
     credentialId: string;
     key: SigningKey;
@@ -33,7 +40,28 @@ export declare function signRequest(p: {
     body?: string | ArrayBuffer | Uint8Array | null;
     ttlSeconds?: number;
     now?: Date;
+    delegation?: Delegation[];
 }): Promise<Record<string, string>>;
+/** The key a signing key verifies as, in the form a credential or a delegation names it. */
+export declare function agentKeyOf(key: SigningKey): Promise<AgentKey>;
+/**
+ * Delegation to a sub-agent (D-30): hands `delegate` a mandate contained in the delegator's, for `ttlSeconds`
+ * (at most the mandate's `delegation.max_ttl_seconds`). `key` is the credential's agent key, or, to delegate
+ * again, the key of the last delegate in `chain`. Returns the new chain; the sub-agent sends it with
+ * signRequest({ delegation }). Nothing goes to the issuer.
+ */
+export declare function signDelegation(p: {
+    credential: DelegationAnchor | Credential;
+    key: SigningKey;
+    delegate: {
+        kind: "evm" | "web-bot-auth";
+        id: string;
+    };
+    mandate: Mandate;
+    ttlSeconds: number;
+    chain?: Delegation[];
+    now?: Date;
+}): Promise<Delegation[]>;
 export interface KyaAuthOptions extends KyaOptions {
     /** How long a fetched credential is reused before asking the issuer again (ms). Default 60 000. */
     cacheTtlMs?: number;
@@ -51,13 +79,28 @@ export interface KyaContext {
     status: CredentialStatus;
     mandate: Mandate;
     credential: Verification["credential"];
-    /** Which key verified the request signature. */
+    /** Which key verified the request signature (the sub-agent's key on a delegated request). */
     signer: string;
+    /**
+     * D-30: present when a sub-agent signed the request under a delegation chain. `agent` above stays the
+     * credential's agent; `delegate` is the sub-agent; every mandate in `mandates` must allow an action.
+     */
+    delegation: {
+        depth: number;
+        delegate: AgentKey;
+        expires_at: string;
+        chain: Delegation[];
+        mandates: Mandate[];
+    } | null;
     /** Whether the body hash was checked ("verified"), absent from the signature ("none") or not checkable ("skipped"). */
     body: "verified" | "none" | "skipped";
-    /** Local evaluation of the mandate (no daily ceilings; those need the issuer). */
+    /** Local evaluation of the mandate (no daily ceilings; those need the issuer). On a delegated request, of every mandate in the chain. */
     check(q: ActionQuery): LocalVerdict;
-    /** Signed verdict from the issuer ($0.01, needs privateKey or internalKey in the options). */
+    /**
+     * Signed verdict from the issuer ($0.01, needs privateKey or internalKey in the options). The issuer evaluates
+     * the credential's mandate; on a delegated request the delegated mandates are evaluated here first, and when
+     * one refuses the answer is that local refusal (unsigned, `delegation_level` set, the issuer is not called).
+     */
     allowed(q: ActionQuery): Promise<Verdict>;
 }
 export type KyaAuthResult = {
@@ -84,6 +127,10 @@ export interface LocalVerdict {
  * max_per_day when you pass spent_today (nobody else counts it: the issuer keeps no record of acts).
  */
 export declare function checkMandate(mandate: Mandate, q: ActionQuery, now?: Date): LocalVerdict;
+/** checkMandate over every mandate of a delegation chain (credential first): allowed only when all allow it. */
+export declare function checkMandates(mandates: Mandate[], q: ActionQuery, now?: Date): LocalVerdict & {
+    levels: LocalVerdict[];
+};
 export interface KyaAuth {
     client: KyaClient;
     /** Authenticate any Web-standard Request. Never throws; read `ok`. */

package/dist/auth.js

@@ -16,9 +16,14 @@
  *     const headers = await signRequest({ credentialId, key: { kind: "evm", privateKey }, method: "POST", url, body });
  *     await fetch(url, { method: "POST", headers: { ...headers, "content-type": "application/json" }, body });
  *
- * Request text (what the agent signs; the profile is in docs/SPEC.md section 15):
+ *   Sub-agent (D-30, the credential's mandate allows delegation):
+ *     const chain = await signDelegation({ credential, key: parentKey, delegate: { kind: "evm", id: sub }, mandate: { actions: ["quote"] }, ttlSeconds: 600 });
+ *     const headers = await signRequest({ credentialId, key: subKey, delegation: chain, method: "GET", url });
+ *
+ * Request text (what the agent signs; the profile is in docs/SPEC.md section 14):
  *   KYA Brasil: request
  *   credential: <credential_id>
+ *   delegation: <sha256 hex of the KYA-Delegation header>      (only on delegated requests)
  *   method: <METHOD>
  *   url: <origin + path + query, lowercase host>
  *   created: <unix seconds>
@@ -26,10 +31,11 @@
  *   content-sha256: <hex of the body | ->
  */
 import { verifyMessage } from "viem";
+import { encodeDelegationHeader, decodeDelegationHeader, prepareDelegation, verifyDelegationChain } from "@kya-brasil/core";
 import { privateKeyToAccount } from "viem/accounts";
 import { createKyaClient } from "./index.js";
 import { fromBase64Url, toBase64Url } from "./base64url.js";
-export const KYA_HEADERS = { credential: "kya-credential", created: "kya-created", expires: "kya-expires", signature: "kya-signature", content: "kya-content-sha256" };
+export const KYA_HEADERS = { credential: "kya-credential", created: "kya-created", expires: "kya-expires", signature: "kya-signature", content: "kya-content-sha256", delegation: "kya-delegation" };
 const enc = new TextEncoder();
 const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 const b64u = toBase64Url;
@@ -47,6 +53,7 @@ export function requestText(p) {
     return [
         "KYA Brasil: request",
         `credential: ${p.credentialId}`,
+        ...(p.delegationSha256 ? [`delegation: ${p.delegationSha256}`] : []),
         `method: ${p.method.toUpperCase()}`,
         `url: ${canonicalUrl(p.url)}`,
         `created: ${p.created}`,
@@ -54,26 +61,57 @@ export function requestText(p) {
         `content-sha256: ${p.contentSha256 ?? "-"}`
     ].join("\n");
 }
-/** Signs a request with the agent key and returns the KYA headers to send with it. */
+// --- Agent side -------------------------------------------------------------------------------
+const importPkcs8 = (pem, extractable = false) => crypto.subtle.importKey("pkcs8", unb64u(pem.replace(/-----[^-]+-----/g, "").replace(/\s+/g, "")), { name: "Ed25519" }, extractable, ["sign"]);
+async function signText(key, text) {
+    if (key.kind === "web-bot-auth") {
+        const k = typeof key.privateKey === "string" ? await importPkcs8(key.privateKey) : key.privateKey;
+        return b64u(new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, k, enc.encode(text))));
+    }
+    return privateKeyToAccount(key.privateKey).signMessage({ message: text });
+}
+/**
+ * Signs a request with the agent key and returns the KYA headers to send with it. A sub-agent passes its
+ * `delegation` chain (from signDelegation) and signs with its own key.
+ */
 export async function signRequest(p) {
     const created = Math.floor((p.now ?? new Date()).getTime() / 1000);
     const expires = created + (p.ttlSeconds ?? 60);
     const contentSha256 = p.body !== undefined && p.body !== null && (typeof p.body !== "string" || p.body.length > 0) ? await sha256Hex(p.body) : null;
-    const text = requestText({ credentialId: p.credentialId, method: p.method, url: p.url, created, expires, contentSha256 });
-    let signature;
-    if (p.key.kind === "web-bot-auth") {
-        const key = typeof p.key.privateKey === "string" ? await crypto.subtle.importKey("pkcs8", unb64u(p.key.privateKey.replace(/-----[^-]+-----/g, "").replace(/\s+/g, "")), { name: "Ed25519" }, false, ["sign"]) : p.key.privateKey;
-        signature = b64u(new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, key, enc.encode(text))));
-    }
-    else {
-        signature = await privateKeyToAccount(p.key.privateKey).signMessage({ message: text });
-    }
+    const delegationHeader = p.delegation && p.delegation.length ? encodeDelegationHeader(p.delegation) : null;
+    const delegationSha256 = delegationHeader ? await sha256Hex(delegationHeader) : null;
+    const text = requestText({ credentialId: p.credentialId, method: p.method, url: p.url, created, expires, contentSha256, delegationSha256 });
+    const signature = await signText(p.key, text);
     const headers = { [KYA_HEADERS.credential]: p.credentialId, [KYA_HEADERS.created]: String(created), [KYA_HEADERS.expires]: String(expires), [KYA_HEADERS.signature]: signature };
     if (contentSha256)
         headers[KYA_HEADERS.content] = contentSha256;
+    if (delegationHeader)
+        headers[KYA_HEADERS.delegation] = delegationHeader;
     return headers;
 }
-const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until"];
+/** The key a signing key verifies as, in the form a credential or a delegation names it. */
+export async function agentKeyOf(key) {
+    if (key.kind !== "web-bot-auth")
+        return { kind: "evm", id: privateKeyToAccount(key.privateKey).address };
+    const k = typeof key.privateKey === "string" ? await importPkcs8(key.privateKey, true) : key.privateKey;
+    const jwk = (await crypto.subtle.exportKey("jwk", k));
+    if (!jwk.x)
+        throw new Error("cannot derive the Ed25519 public key from this private key");
+    return { kind: "web-bot-auth", id: jwk.x };
+}
+/**
+ * Delegation to a sub-agent (D-30): hands `delegate` a mandate contained in the delegator's, for `ttlSeconds`
+ * (at most the mandate's `delegation.max_ttl_seconds`). `key` is the credential's agent key, or, to delegate
+ * again, the key of the last delegate in `chain`. Returns the new chain; the sub-agent sends it with
+ * signRequest({ delegation }). Nothing goes to the issuer.
+ */
+export async function signDelegation(p) {
+    const chain = p.chain ?? [];
+    const { delegation, text } = await prepareDelegation({ credential: p.credential, chain, delegate: p.delegate, mandate: p.mandate, ttlSeconds: p.ttlSeconds, now: p.now });
+    const signature = await signText(p.key, text);
+    return [...chain, { ...delegation, signature }];
+}
+const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "payment_instruments", "valid_from", "valid_until", "delegation"];
 function normalizeCounterparty(c) {
     const t = c.trim();
     const digits = t.replace(/\D/g, "");
@@ -133,6 +171,17 @@ export function checkMandate(mandate, q, now = new Date()) {
         not_evaluated.push("max_per_day (pass spent_today: the issuer keeps no record of acts)");
     return { allowed: checks.every((c) => c.ok), checks, not_evaluated };
 }
+/** checkMandate over every mandate of a delegation chain (credential first): allowed only when all allow it. */
+export function checkMandates(mandates, q, now = new Date()) {
+    const levels = mandates.map((m) => checkMandate(m, q, now));
+    const prefix = (i, s) => (i === 0 ? s : `delegation ${i}: ${s}`);
+    return {
+        allowed: levels.length > 0 && levels.every((l) => l.allowed),
+        checks: levels.flatMap((l, i) => l.checks.map((c) => ({ ...c, rule: prefix(i, c.rule) }))),
+        not_evaluated: [...new Set(levels.flatMap((l, i) => l.not_evaluated.map((n) => prefix(i, n))))],
+        levels
+    };
+}
 const headerOf = (headers, name) => {
     if (headers instanceof Headers)
         return headers.get(name);
@@ -177,6 +226,7 @@ export function createKyaAuth(opts = {}) {
         const expires = Number(headerOf(p.headers, KYA_HEADERS.expires));
         const signature = headerOf(p.headers, KYA_HEADERS.signature);
         const contentHeader = headerOf(p.headers, KYA_HEADERS.content);
+        const delegationHeader = headerOf(p.headers, KYA_HEADERS.delegation);
         if (!credentialId || !signature || !Number.isFinite(created) || !Number.isFinite(expires))
             return fail(401, "KYA_HEADERS_MISSING", `send ${KYA_HEADERS.credential}, ${KYA_HEADERS.created}, ${KYA_HEADERS.expires} and ${KYA_HEADERS.signature}`);
         const now = Math.floor(Date.now() / 1000);
@@ -208,16 +258,43 @@ export function createKyaAuth(opts = {}) {
             const status = e.status;
             return status === 404 ? fail(401, "KYA_CREDENTIAL_UNKNOWN", "unknown credential_id") : fail(502, "KYA_ISSUER_UNAVAILABLE", e.message);
         }
-        const text = requestText({ credentialId, method: p.method, url: p.url, created, expires, contentSha256: contentHeader });
-        return finish(credentialId, v, text, signature, bodyState);
+        let delegation = null;
+        if (delegationHeader) {
+            const d = await delegationOf(credentialId, v, delegationHeader);
+            if (!d.ok)
+                return d.result;
+            delegation = d.delegation;
+        }
+        const delegationSha256 = delegationHeader ? await sha256Hex(delegationHeader) : null;
+        const text = requestText({ credentialId, method: p.method, url: p.url, created, expires, contentSha256: contentHeader, delegationSha256 });
+        return finish(credentialId, v, text, signature, bodyState, delegation);
+    }
+    /** D-30: verifies a KYA-Delegation chain against the credential (offline, core rules). */
+    async function delegationOf(credentialId, v, header) {
+        const no = (status, error, message) => ({ ok: false, result: fail(status, error, message) });
+        if (!v.credential)
+            return no(403, "KYA_CREDENTIAL_NOT_ACTIVE", `credential is ${v.status}`);
+        let chain;
+        try {
+            chain = decodeDelegationHeader(header);
+        }
+        catch (e) {
+            return no(401, "KYA_DELEGATION_MALFORMED", e.message);
+        }
+        const anchor = { credential_id: credentialId, agent: v.agent, mandate: v.credential.mandate, expires_at: v.credential.expires_at };
+        const r = await verifyDelegationChain({ credential: anchor, chain });
+        if (!r.ok)
+            return no(r.error === "KYA_DELEGATION_NOT_ALLOWED" || r.error === "KYA_DELEGATION_BROADER" ? 403 : 401, r.error, r.message);
+        return { ok: true, delegation: { depth: r.depth, delegate: r.delegate, expires_at: r.expires_at, chain: chain, mandates: r.mandates } };
     }
-    async function finish(credentialId, v, text, signature, bodyState) {
-        const sig = await verifySignature(v.agent, text, signature);
+    async function finish(credentialId, v, text, signature, bodyState, delegation = null) {
+        const sig = await verifySignature(delegation ? delegation.delegate : v.agent, text, signature);
         if (!sig.ok)
-            return fail(401, "KYA_BAD_SIGNATURE", "signature does not match the credential's agent key over the signed text");
+            return fail(401, "KYA_BAD_SIGNATURE", delegation ? "signature does not match the delegate's key over the signed text" : "signature does not match the credential's agent key over the signed text");
         if (v.status !== "active")
             return fail(403, "KYA_CREDENTIAL_NOT_ACTIVE", `credential is ${v.status}${v.status_reason ? `: ${v.status_reason}` : ""}`);
         const mandate = v.credential?.mandate ?? {};
+        const mandates = delegation ? delegation.mandates : [mandate];
         const ctx = {
             credential_id: credentialId,
             agent: v.agent,
@@ -227,8 +304,19 @@ export function createKyaAuth(opts = {}) {
             credential: v.credential,
             signer: sig.signer,
             body: bodyState,
-            check: (q) => checkMandate(mandate, q),
-            allowed: (q) => client.allowed(credentialId, q)
+            delegation,
+            check: (q) => (delegation ? checkMandates(mandates, q) : checkMandate(mandate, q)),
+            allowed: async (q) => {
+                if (delegation) {
+                    for (let i = 1; i < mandates.length; i++) {
+                        const local = checkMandate(mandates[i], q);
+                        if (!local.allowed) {
+                            return { credential_id: credentialId, status: v.status, allowed: false, reason: `outside the mandate of delegation ${i}`, checks: local.checks.map((c) => ({ field: c.rule, ok: c.ok, detail: c.detail })), not_evaluated: local.not_evaluated, delegation_level: i };
+                        }
+                    }
+                }
+                return client.allowed(credentialId, q);
+            }
         };
         return { ok: true, kya: ctx };
     }
@@ -309,13 +397,6 @@ export const KYA_REPLY_HEADER = "kya-in-reply-to";
 export function responseText(p) {
     return ["KYA Brasil: response", `credential: ${p.credentialId}`, `in-reply-to: ${p.inReplyTo}`, `created: ${p.created}`, `expires: ${p.expires}`, `content-sha256: ${p.contentSha256 ?? "-"}`].join("\n");
 }
-async function signText(key, text) {
-    if (key.kind === "web-bot-auth") {
-        const k = typeof key.privateKey === "string" ? await crypto.subtle.importKey("pkcs8", unb64u(key.privateKey.replace(/-----[^-]+-----/g, "").replace(/\s+/g, "")), { name: "Ed25519" }, false, ["sign"]) : key.privateKey;
-        return b64u(new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, k, enc.encode(text))));
-    }
-    return privateKeyToAccount(key.privateKey).signMessage({ message: text });
-}
 /** Callee side: headers that prove who answered, bound to the request signature it replies to. */
 export async function signResponse(p) {
     const created = Math.floor((p.now ?? new Date()).getTime() / 1000);

package/dist/index.d.ts

@@ -33,6 +33,11 @@ export interface Mandate {
         ref_sha256: string;
         label?: string;
     }[];
+    /** D-30: the agent may hand a narrower mandate to sub-agents (signDelegation), up to max_depth levels below it. */
+    delegation?: {
+        max_depth: number;
+        max_ttl_seconds: number;
+    };
     valid_from?: string;
     valid_until?: string;
     [k: string]: unknown;
@@ -408,6 +413,7 @@ export declare function verifyCredentialOffline(credential: Credential, opts?: {
 }): Promise<OfflineCheck>;
 export * from "./auth.js";
 export { isValidCpf, personAgentsText } from "@kya-brasil/core";
+export { checkDelegatedAction, decodeDelegationHeader, encodeDelegationHeader, isMandateSubset, mandateSubsetProblems, verifyDelegationChain } from "@kya-brasil/core";
 export { buildDetachedCms, cnpjFromCommonName, ecnpjSigner, openPfx, readSigningLink, signWithECnpjPfx, type ECnpjSigner, type RawSigner } from "@kya-brasil/core";
 export { listTokenCertificates, openToken, type TokenCertificate, type TokenOptions } from "./pkcs11.js";
 /**

package/dist/index.js

@@ -255,6 +255,8 @@ export async function verifyCredentialOffline(credential, opts = {}) {
 export * from "./auth.js";
 // e-CNPJ signing (D-26, D-27): the implementation lives in @kya-brasil/core, shared with anyone using the library.
 export { isValidCpf, personAgentsText } from "@kya-brasil/core";
+// Delegation to sub-agents (D-30): chain rules live in the core, signing and the middleware in ./auth.
+export { checkDelegatedAction, decodeDelegationHeader, encodeDelegationHeader, isMandateSubset, mandateSubsetProblems, verifyDelegationChain } from "@kya-brasil/core";
 export { buildDetachedCms, cnpjFromCommonName, ecnpjSigner, openPfx, readSigningLink, signWithECnpjPfx } from "@kya-brasil/core";
 export { listTokenCertificates, openToken } from "./pkcs11.js";
 import { signingLink as coreSigningLink } from "@kya-brasil/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "KYA Brasil for AI agents: verify that an agent acts for a Brazilian company (e-CNPJ-signed credential, revocation and company registration checked daily against the Receita's open data, no third-party service), check an action against its mandate, or give your own agent a credential (sign with the company's e-CNPJ: A1 .pfx or A3 token via PKCS#11, in code or with the kya-sign command). Sign in with KYA middleware (Hono, Express, Workers) and request signing. x402 payments (USDC on Base) handled for you. Adapters for Vercel AI SDK, LangChain, OpenAI and Anthropic.",
   "license": "MIT",
   "type": "module",
@@ -56,7 +56,7 @@
     "@x402/fetch": "^2.28.0",
     "pkijs": "^3.4.1",
     "viem": "^2.57.5",
-    "@kya-brasil/core": "^0.10.0"
+    "@kya-brasil/core": "^0.11.0"
   },
   "devDependencies": {
     "@peculiar/asn1-schema": "^2.3.15",