@kya-brasil/agent-tools 0.1.0 → 0.3.0

package/README.md

@@ -29,11 +29,15 @@ const verdict = await kya.allowed(credentialId, {         // $0.01, signed
 if (!verdict.allowed) reject(verdict.reason);
 
 await verifyAttestation(verdict);                          // local Ed25519 check of the issuer's signature
+
+const receipt = await kya.registerAct(credentialId, {       // $0.02 once you accept it: signed receipt,
+  action: "order", amount: 4200, currency: "BRL", counterparty: "12345678000190", reference: "PO-1"
+});                                                          // daily ceilings enforced across counterparties
 ```
 
 Also check that the key that signed the agent's request is `v.agent.id`; the credential_id alone proves nothing.
 
-Agent frameworks (verifier tools `kya_verify`, `kya_check_action`, `kya_verify_paid`):
+Agent frameworks (verifier tools `kya_verify`, `kya_check_action`, `kya_register_act`, `kya_verify_paid`):
 
 ```ts
 import { toOpenAI, toVercelAI, toLangChain, toAnthropic } from "@kya-brasil/agent-tools";
@@ -42,6 +46,29 @@ toLangChain(kya, tool);                  // from "@langchain/core/tools"
 toOpenAI(kya); toAnthropic(kya);         // then kya.execute(name, args)
 ```
 
+## Sign in with KYA: accept signed requests from agents
+
+```ts
+import { createKyaAuth } from "@kya-brasil/agent-tools";
+const auth = createKyaAuth();                     // options: privateKey (for kya.allowed), cacheTtlMs, maxSkewSeconds
+
+app.use("/api/*", auth.hono());                    // Hono: c.get("kya")
+app.use(auth.express());                           // Express: req.kya
+export default { fetch: auth.fetchHandler(async (req, kya) => Response.json({ hello: kya.principal.legal_name })) }; // Workers
+const r = await auth.authenticate(request);        // anywhere: { ok, kya } or { ok: false, status, error, message }
+```
+
+`kya` carries `credential_id`, `agent`, `principal`, `mandate`, `check(q)` (local mandate evaluation, no daily
+ceilings) and `allowed(q)` (the issuer's signed verdict, $0.01). The agent signs with `signRequest(...)`:
+
+```ts
+import { signRequest } from "@kya-brasil/agent-tools";
+const headers = await signRequest({ credentialId, key: { kind: "evm", privateKey: agentPk }, method: "POST", url, body });
+await fetch(url, { method: "POST", headers: { ...headers, "content-type": "application/json" }, body });
+```
+
+Keys: `{ kind: "evm" | "erc8004", privateKey }` or `{ kind: "web-bot-auth", privateKey: CryptoKey | pkcs8 }`.
+
 ## Company: give your own agent a credential
 
 ```ts
@@ -52,7 +79,13 @@ const kya = createKyaClient({ privateKey: payerPk });
 const reg = await kya.register({                                           // $0.50
   agent: { kind: "evm", id: agentAddress },
   cnpj: "11.222.333/0001-81",
-  mandate: { actions: ["quote", "order", "pay"], max_per_operation: 5000, max_per_day: 20000, currencies: ["BRL", "USDC"] }
+  mandate: {
+    actions: ["quote", "order", "pay"],
+    max_per_operation: { amount: 5000, currency: "BRL" },
+    max_per_day: { amount: 20000, currency: "BRL" },
+    currencies: ["BRL"],
+    counterparties: ["12345678000190", "*.beta.com.br"]
+  }
 });
 
 const agent_signature = await signChallengeWithEvmKey(agentPk, reg.challenge.text);
@@ -78,6 +111,7 @@ Renew every 90 days (`kya.renew` then `kya.renewProve`), revoke at once (`kya.re
 |---|---|
 | verify, verifyByKey, prove, renewProve, revoke, revocations | free |
 | verified (signed receipt, no limit), allowed (signed verdict) | 0.01 |
+| registerAct (signed receipt of what the agent did) | 0.02 |
 | renew | 0.10 |
 | register | 0.50 |
 

package/dist/auth.d.ts

@@ -0,0 +1,130 @@
+import { type ActionQuery, type AgentKey, type CredentialStatus, type KyaClient, type Mandate, type Verdict, type Verification, type KyaOptions } from "./index";
+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";
+};
+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;
+export declare function requestText(p: {
+    credentialId: string;
+    method: string;
+    url: string;
+    created: number;
+    expires: number;
+    contentSha256?: string | null;
+}): string;
+export type SigningKey = {
+    kind: "evm" | "erc8004";
+    privateKey: `0x${string}`;
+} | {
+    kind: "web-bot-auth";
+    privateKey: CryptoKey | string;
+};
+/** Signs a request with the agent key and returns the KYA headers to send with it. */
+export declare function signRequest(p: {
+    credentialId: string;
+    key: SigningKey;
+    method: string;
+    url: string;
+    body?: string | ArrayBuffer | Uint8Array | null;
+    ttlSeconds?: number;
+    now?: Date;
+}): Promise<Record<string, string>>;
+export interface KyaAuthOptions extends KyaOptions {
+    /** How long a fetched credential is reused before asking the issuer again (ms). Default 60 000. */
+    cacheTtlMs?: number;
+    /** Max clock difference accepted for `created` (seconds). Default 300. */
+    maxSkewSeconds?: number;
+    /** Max signature lifetime accepted (seconds), whatever `expires` says. Default 600. */
+    maxTtlSeconds?: number;
+    /** Verify the body hash when the request has a body. Default true. */
+    requireBodyHash?: boolean;
+}
+export interface KyaContext {
+    credential_id: string;
+    agent: AgentKey;
+    principal: Verification["principal"];
+    status: CredentialStatus;
+    mandate: Mandate;
+    credential: Verification["credential"];
+    /** Which key verified the request signature. */
+    signer: string;
+    /** 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). */
+    check(q: ActionQuery): LocalVerdict;
+    /** Signed verdict from the issuer ($0.01, needs privateKey or internalKey in the options). */
+    allowed(q: ActionQuery): Promise<Verdict>;
+}
+export type KyaAuthResult = {
+    ok: true;
+    kya: KyaContext;
+} | {
+    ok: false;
+    status: 401 | 403 | 502;
+    error: string;
+    message: string;
+};
+export interface LocalVerdict {
+    allowed: boolean;
+    checks: {
+        rule: string;
+        ok: boolean;
+        detail: string;
+    }[];
+    not_evaluated: string[];
+}
+/**
+ * Local evaluation of the reserved mandate fields: actions, max_per_operation, currencies, counterparties
+ * (with `*.` wildcards), valid_from / valid_until. `max_per_day` is listed as not evaluated: only the issuer
+ * knows what was registered today (use ctx.allowed or registerAct).
+ */
+export declare function checkMandate(mandate: Mandate, q: ActionQuery, now?: Date): LocalVerdict;
+export interface KyaAuth {
+    client: KyaClient;
+    /** Authenticate any Web-standard Request. Never throws; read `ok`. */
+    authenticate(request: Request, opts?: {
+        body?: string | ArrayBuffer | Uint8Array | null;
+    }): Promise<KyaAuthResult>;
+    /** Same, from the parts (for frameworks that already parsed the request). */
+    authenticateParts(p: {
+        method: string;
+        url: string;
+        headers: Headers | Record<string, string | string[] | undefined>;
+        body?: string | ArrayBuffer | Uint8Array | null;
+    }): Promise<KyaAuthResult>;
+    /** Hono middleware: sets c.set("kya", ctx) or answers 401/403 JSON. */
+    hono(): (c: HonoLikeContext, next: () => Promise<void>) => Promise<Response | void>;
+    /** Express middleware: sets req.kya or answers 401/403 JSON. Verifies the body when req.body is a string or Buffer. */
+    express(): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: (err?: unknown) => void) => void;
+    /** Wrap a fetch handler (Workers, Deno, Bun): handler(request, kya). */
+    fetchHandler(handler: (request: Request, kya: KyaContext) => Promise<Response> | Response): (request: Request) => Promise<Response>;
+    /** Forget cached credentials (tests, or after a revocation you learned about). */
+    clearCache(): void;
+}
+export interface HonoLikeContext {
+    req: {
+        raw: Request;
+    };
+    set: (k: string, v: unknown) => void;
+    json: (body: unknown, status?: number) => Response;
+}
+export interface ExpressLikeRequest {
+    method: string;
+    protocol?: string;
+    originalUrl?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    get?: (name: string) => string | undefined;
+    kya?: KyaContext;
+}
+export interface ExpressLikeResponse {
+    status: (code: number) => ExpressLikeResponse;
+    json: (body: unknown) => unknown;
+}
+export declare function createKyaAuth(opts?: KyaAuthOptions): KyaAuth;

package/dist/auth.js

@@ -0,0 +1,261 @@
+/**
+ * "Sign in with KYA": authenticate an incoming request from an agent in one step.
+ *
+ * The agent signs each request with its key and sends four headers; your server verifies the signature,
+ * fetches (and caches) the credential, checks that it is active, and hands you who the agent is, which
+ * company answers for it, and its mandate. Works with any Web-standard Request (Workers, Hono, Next,
+ * Bun, Deno) and with Express through a small adapter.
+ *
+ *   Server:
+ *     const auth = createKyaAuth();
+ *     app.use("/api/*", auth.hono());                        // c.get("kya") → { agent, principal, mandate, ... }
+ *     app.use(auth.express());                                // req.kya
+ *     const r = await auth.authenticate(request);             // anywhere: { ok, ... }
+ *
+ *   Agent:
+ *     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):
+ *   KYA Brasil: request
+ *   credential: <credential_id>
+ *   method: <METHOD>
+ *   url: <origin + path + query, lowercase host>
+ *   created: <unix seconds>
+ *   expires: <unix seconds>
+ *   content-sha256: <hex of the body | ->
+ */
+import { verifyMessage } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { createKyaClient } from "./index";
+export const KYA_HEADERS = { credential: "kya-credential", created: "kya-created", expires: "kya-expires", signature: "kya-signature", content: "kya-content-sha256" };
+const enc = new TextEncoder();
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+const b64u = (bytes) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const unb64u = (s) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(s.length / 4) * 4, "=")), (c) => c.charCodeAt(0));
+export async function sha256Hex(data) {
+    const bytes = typeof data === "string" ? enc.encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data);
+    return hex(await crypto.subtle.digest("SHA-256", bytes));
+}
+/** Canonical URL for the signature: origin (lowercase host) + path + query, no fragment. */
+export function canonicalUrl(url) {
+    const u = new URL(url);
+    return `${u.protocol}//${u.host.toLowerCase()}${u.pathname}${u.search}`;
+}
+export function requestText(p) {
+    return [
+        "KYA Brasil: request",
+        `credential: ${p.credentialId}`,
+        `method: ${p.method.toUpperCase()}`,
+        `url: ${canonicalUrl(p.url)}`,
+        `created: ${p.created}`,
+        `expires: ${p.expires}`,
+        `content-sha256: ${p.contentSha256 ?? "-"}`
+    ].join("\n");
+}
+/** Signs a request with the agent key and returns the KYA headers to send with it. */
+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 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;
+    return headers;
+}
+const RESERVED = ["actions", "max_per_operation", "max_per_day", "currencies", "counterparties", "valid_from", "valid_until"];
+function normalizeCounterparty(c) {
+    const t = c.trim();
+    const digits = t.replace(/\D/g, "");
+    if (digits.length === 14 && /^[\d./-]+$/.test(t))
+        return digits;
+    if (/^0x[0-9a-fA-F]{40}$/.test(t))
+        return t.toLowerCase();
+    return t.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+}
+/**
+ * Local evaluation of the reserved mandate fields: actions, max_per_operation, currencies, counterparties
+ * (with `*.` wildcards), valid_from / valid_until. `max_per_day` is listed as not evaluated: only the issuer
+ * knows what was registered today (use ctx.allowed or registerAct).
+ */
+export function checkMandate(mandate, q, now = new Date()) {
+    const checks = [];
+    const push = (rule, ok, detail) => checks.push({ rule, ok, detail });
+    if (mandate.valid_from)
+        push("valid_from", now >= new Date(mandate.valid_from), `mandate starts ${mandate.valid_from}`);
+    if (mandate.valid_until)
+        push("valid_until", now <= new Date(mandate.valid_until), `mandate ends ${mandate.valid_until}`);
+    if (mandate.actions && q.action)
+        push("actions", mandate.actions.includes(q.action), `action "${q.action}" ${mandate.actions.includes(q.action) ? "is" : "is not"} in [${mandate.actions.join(", ")}]`);
+    if (mandate.currencies && q.currency) {
+        const c = q.currency.toUpperCase();
+        push("currencies", mandate.currencies.includes(c), `currency ${c} ${mandate.currencies.includes(c) ? "allowed" : "not in"} [${mandate.currencies.join(", ")}]`);
+    }
+    if (mandate.max_per_operation && q.amount !== undefined) {
+        const same = !q.currency || q.currency.toUpperCase() === mandate.max_per_operation.currency;
+        push("max_per_operation", same && q.amount <= mandate.max_per_operation.amount, same ? `${q.amount} vs ceiling ${mandate.max_per_operation.amount} ${mandate.max_per_operation.currency}` : `ceiling is in ${mandate.max_per_operation.currency}, operation in ${q.currency}`);
+    }
+    if (mandate.counterparties && mandate.counterparties.length && q.counterparty) {
+        const c = normalizeCounterparty(q.counterparty);
+        const ok = mandate.counterparties.some((m) => {
+            const n = normalizeCounterparty(m);
+            return n === c || (n.startsWith("*.") && (c === n.slice(2) || c.endsWith(n.slice(1))));
+        });
+        push("counterparties", ok, `${c} ${ok ? "is" : "is not"} an allowed counterparty`);
+    }
+    const not_evaluated = Object.keys(mandate).filter((k) => !RESERVED.includes(k));
+    if (mandate.max_per_day)
+        not_evaluated.push("max_per_day (only the issuer knows today's registered total)");
+    return { allowed: checks.every((c) => c.ok), checks, not_evaluated };
+}
+const headerOf = (headers, name) => {
+    if (headers instanceof Headers)
+        return headers.get(name);
+    const v = headers[name] ?? headers[name.toLowerCase()];
+    return Array.isArray(v) ? v[0] ?? null : v ?? null;
+};
+export function createKyaAuth(opts = {}) {
+    const client = createKyaClient(opts);
+    const cacheTtl = opts.cacheTtlMs ?? 60_000;
+    const maxSkew = opts.maxSkewSeconds ?? 300;
+    const maxTtl = opts.maxTtlSeconds ?? 600;
+    const requireBodyHash = opts.requireBodyHash ?? true;
+    const cache = new Map();
+    async function verification(id) {
+        const hit = cache.get(id);
+        if (hit && Date.now() - hit.at < cacheTtl)
+            return hit.v;
+        const v = await client.verify(id);
+        cache.set(id, { at: Date.now(), v });
+        return v;
+    }
+    async function verifySignature(agent, text, signature) {
+        try {
+            if (agent.kind === "web-bot-auth") {
+                const key = await crypto.subtle.importKey("raw", unb64u(agent.id), { name: "Ed25519" }, false, ["verify"]);
+                const sig = unb64u(signature);
+                return { ok: sig.length === 64 && (await crypto.subtle.verify({ name: "Ed25519" }, key, sig, enc.encode(text))), signer: agent.id };
+            }
+            const address = agent.kind === "evm" ? agent.id : agent.wallet;
+            if (!address || !/^0x[0-9a-fA-F]{130}$/.test(signature))
+                return { ok: false, signer: address ?? "" };
+            return { ok: await verifyMessage({ address: address, message: text, signature: signature }), signer: address };
+        }
+        catch {
+            return { ok: false, signer: "" };
+        }
+    }
+    const fail = (status, error, message) => ({ ok: false, status, error, message });
+    async function authenticateParts(p) {
+        const credentialId = headerOf(p.headers, KYA_HEADERS.credential);
+        const created = Number(headerOf(p.headers, KYA_HEADERS.created));
+        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);
+        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);
+        if (created > now + maxSkew)
+            return fail(401, "KYA_SIGNATURE_NOT_YET_VALID", "created is in the future");
+        if (expires < now)
+            return fail(401, "KYA_SIGNATURE_EXPIRED", "expires is in the past");
+        if (expires - created > maxTtl || expires < created)
+            return fail(401, "KYA_SIGNATURE_TTL", `signature lifetime must be between 0 and ${maxTtl}s`);
+        let bodyState = "none";
+        if (p.body !== undefined && p.body !== null && (typeof p.body !== "string" || p.body.length > 0)) {
+            if (!contentHeader) {
+                if (requireBodyHash)
+                    return fail(401, "KYA_BODY_UNSIGNED", `the request has a body but no ${KYA_HEADERS.content} header`);
+                bodyState = "skipped";
+            }
+            else if ((await sha256Hex(p.body)) !== contentHeader.toLowerCase())
+                return fail(401, "KYA_BODY_MISMATCH", "body hash does not match the signed hash");
+            else
+                bodyState = "verified";
+        }
+        else if (contentHeader)
+            bodyState = "skipped";
+        let v;
+        try {
+            v = await verification(credentialId);
+        }
+        catch (e) {
+            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 });
+        const sig = await verifySignature(v.agent, text, signature);
+        if (!sig.ok)
+            return fail(401, "KYA_BAD_SIGNATURE", "signature does not match the credential's agent key over the request 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 ctx = {
+            credential_id: credentialId,
+            agent: v.agent,
+            principal: v.principal,
+            status: v.status,
+            mandate,
+            credential: v.credential,
+            signer: sig.signer,
+            body: bodyState,
+            check: (q) => checkMandate(mandate, q),
+            allowed: (q) => client.allowed(credentialId, q)
+        };
+        return { ok: true, kya: ctx };
+    }
+    const auth = {
+        client,
+        authenticateParts,
+        async authenticate(request, o = {}) {
+            let body = o.body;
+            if (body === undefined && request.body && !["GET", "HEAD"].includes(request.method))
+                body = await request.clone().arrayBuffer();
+            return authenticateParts({ method: request.method, url: request.url, headers: request.headers, body });
+        },
+        hono() {
+            return async (c, next) => {
+                const r = await auth.authenticate(c.req.raw);
+                if (!r.ok)
+                    return c.json({ error: r.error, message: r.message }, r.status);
+                c.set("kya", r.kya);
+                await next();
+            };
+        },
+        express() {
+            return (req, res, next) => {
+                const host = req.get?.("host") ?? (headerOf(req.headers, "host") || "localhost");
+                const proto = headerOf(req.headers, "x-forwarded-proto") || req.protocol || "http";
+                const url = `${proto}://${host}${req.originalUrl ?? req.url ?? "/"}`;
+                const raw = typeof req.body === "string" || req.body instanceof Uint8Array ? req.body : req.body && typeof req.body === "object" ? JSON.stringify(req.body) : undefined;
+                authenticateParts({ method: req.method, url, headers: req.headers, body: raw })
+                    .then((r) => {
+                    if (!r.ok)
+                        return res.status(r.status).json({ error: r.error, message: r.message });
+                    req.kya = r.kya;
+                    next();
+                })
+                    .catch(next);
+            };
+        },
+        fetchHandler(handler) {
+            return async (request) => {
+                const r = await auth.authenticate(request);
+                if (!r.ok)
+                    return new Response(JSON.stringify({ error: r.error, message: r.message }), { status: r.status, headers: { "content-type": "application/json" } });
+                return handler(request, r.kya);
+            };
+        },
+        clearCache: () => cache.clear()
+    };
+    return auth;
+}

package/dist/index.d.ts

@@ -8,15 +8,23 @@ export interface KyaOptions {
     internalKey?: string;
     fetch?: typeof fetch;
 }
+/** erc8004: id is eip155:<chainId>:<identityRegistry>:<agentId>; the on-chain agentWallet signs (credential.agent.wallet). */
 export type AgentKey = {
-    kind: "evm" | "web-bot-auth";
+    kind: "evm" | "web-bot-auth" | "erc8004";
     id: string;
+    wallet?: `0x${string}`;
 };
 export type CredentialStatus = "pending" | "active" | "suspended" | "revoked" | "expired";
 export interface Mandate {
     actions?: string[];
-    max_per_operation?: number;
-    max_per_day?: number;
+    max_per_operation?: {
+        amount: number;
+        currency: string;
+    };
+    max_per_day?: {
+        amount: number;
+        currency: string;
+    };
     currencies?: string[];
     counterparties?: string[];
     valid_from?: string;
@@ -123,6 +131,45 @@ export interface Proof {
     agent_signature: string;
     ecnpj_signature: string;
 }
+export interface ActInput {
+    action: string;
+    amount?: number;
+    currency?: string;
+    counterparty?: string;
+    reference?: string;
+    content_sha256?: string;
+    registered_by?: "counterparty" | "agent";
+    registrant?: string;
+    agent_signature?: string;
+}
+export interface ActReceipt {
+    act_id: string;
+    credential_id: string;
+    status: CredentialStatus;
+    allowed: boolean;
+    reason: string;
+    act: ActInput & {
+        agent_signed: boolean;
+    };
+    checks: {
+        rule: string;
+        ok: boolean;
+        detail?: string;
+    }[];
+    not_evaluated: string[];
+    spent_today_registered_before: {
+        currency: string;
+        amount: number;
+    } | null;
+    spent_today_registered_after: {
+        currency: string;
+        amount: number;
+    } | null;
+    registered_at: string;
+    receipt_url: string;
+    attestation?: Attestation;
+    [k: string]: unknown;
+}
 export declare class KyaError extends Error {
     readonly code: string;
     readonly status: number;
@@ -176,6 +223,27 @@ export interface KyaClient {
         credential_id: string;
         status: "revoked";
     }>;
+    /** $0.02: register what the agent did (you accepted it); mandate re-checked with today's registered acts; signed receipt. */
+    registerAct(credentialId: string, act: ActInput): Promise<ActReceipt>;
+    /** Free: a registered act and its receipt, by act_id. */
+    act(actId: string): Promise<ActReceipt>;
+    /** Free: the exact text the agent signs for an act (optional agent_signature). */
+    actText(credentialId: string, act: ActInput): Promise<{
+        credential_id: string;
+        agent: AgentKey;
+        text: string;
+    }>;
+    /** Free, company only: the trail of an agent's acts, request signed with the e-CNPJ over actsExportText(id). */
+    exportActs(credentialId: string, input: {
+        signed_text: string;
+        ecnpj_signature: string;
+        since?: string;
+    }): Promise<{
+        credential_id: string;
+        since: string;
+        count: number;
+        acts: Record<string, unknown>[];
+    }>;
     /** Free: credentials revoked since a date (default 30 days). */
     revocations(since?: string): Promise<{
         since: string;
@@ -248,6 +316,8 @@ export interface ECnpjMaterial {
  * Works with A1 certificates (file). A3 (token or smart card) must sign through the vendor's software.
  */
 export declare function signWithECnpj(material: ECnpjMaterial, text: string): Promise<string>;
+/** The text the company signs to read its agent's trail of acts. */
+export declare function actsExportText(credentialId: string, nonce?: string): string;
 /** The text the company signs to revoke a credential. */
 export declare function revocationText(credentialId: string, nonce?: string): string;
 export interface VerifyResult {
@@ -267,3 +337,4 @@ export declare function verifyAttestation(doc: Record<string, unknown>, opts?: {
     publicJwk?: JsonWebKey;
     fetch?: typeof fetch;
 }): Promise<VerifyResult>;
+export * from "./auth";

package/dist/index.js

@@ -80,6 +80,10 @@ export function createKyaClient(opts = {}) {
         renewProve: (id, proof) => call("POST", `/v1/agents/${encodeURIComponent(id)}/renew/prove`, proof),
         revoke: (id, input) => call("POST", `/v1/agents/${encodeURIComponent(id)}/revoke`, input),
         revocations: (since) => call("GET", `/v1/revocations${q({ since })}`),
+        registerAct: (id, act) => call("POST", `/v1/agents/${encodeURIComponent(id)}/acts`, act, true, 0.02),
+        act: (actId) => call("GET", `/v1/acts/${encodeURIComponent(actId)}`),
+        actText: (id, act) => call("POST", `/v1/agents/${encodeURIComponent(id)}/acts/text`, act),
+        exportActs: (id, input) => call("POST", `/v1/agents/${encodeURIComponent(id)}/acts/export`, input),
         tools: [],
         execute: async (name, args) => {
             const t = client.tools.find((x) => x.name === name);
@@ -93,7 +97,7 @@ export function createKyaClient(opts = {}) {
         {
             name: "kya_verify", priceUsd: 0,
             description: "Free. Is this AI agent credentialed by a Brazilian company? Returns the credential (company CNPJ and name, mandate, KYB snapshot), its live status (active, suspended, revoked, expired) and history. Give credential_id, or the agent key (kind + id) to look it up.",
-            parameters: { type: "object", properties: { credential_id: ID, kind: { type: "string", enum: ["evm", "web-bot-auth"] }, id: { type: "string", description: "0x address or base64url Ed25519 key" } }, additionalProperties: false },
+            parameters: { type: "object", properties: { credential_id: ID, kind: { type: "string", enum: ["evm", "web-bot-auth", "erc8004"] }, id: { type: "string", description: "0x address, base64url Ed25519 key, or eip155:<chainId>:<registry>:<agentId>" } }, additionalProperties: false },
             execute: async (a) => (a.credential_id ? client.verify(String(a.credential_id)) : client.verifyByKey({ kind: a.kind, id: String(a.id) }))
         },
         {
@@ -102,6 +106,12 @@ export function createKyaClient(opts = {}) {
             parameters: { type: "object", properties: { credential_id: ID, action: { type: "string" }, amount: { type: "number" }, currency: { type: "string" }, counterparty: { type: "string", description: "Your CNPJ, domain or wallet address" }, spent_today: { type: "number" } }, required: ["credential_id"], additionalProperties: false },
             execute: async (a) => client.allowed(String(a.credential_id), { action: a.action, amount: a.amount, currency: a.currency, counterparty: a.counterparty, spent_today: a.spent_today })
         },
+        {
+            name: "kya_register_act", priceUsd: 0.02,
+            description: "Register an action you accepted from an agent ($0.02): the issuer re-checks the mandate including everything registered today by anyone (so daily ceilings hold across counterparties) and returns a signed receipt, your proof of what the agent could and did do. Denied acts are recorded too.",
+            parameters: { type: "object", properties: { credential_id: ID, action: { type: "string" }, amount: { type: "number" }, currency: { type: "string" }, counterparty: { type: "string", description: "You: CNPJ, domain or wallet" }, reference: { type: "string" }, content_sha256: { type: "string" } }, required: ["credential_id", "action"], additionalProperties: false },
+            execute: async (a) => { const { credential_id, ...act } = a; return client.registerAct(String(credential_id), act); }
+        },
         {
             name: "kya_verify_paid", priceUsd: 0.01,
             description: "Same as kya_verify without the daily limit, plus a signed receipt of the verification ($0.01).",
@@ -163,6 +173,10 @@ export async function signWithECnpj(material, text) {
         s += String.fromCharCode(b);
     return btoa(s);
 }
+/** The text the company signs to read its agent's trail of acts. */
+export function actsExportText(credentialId, nonce = crypto.randomUUID()) {
+    return `KYA Brasil: acts ${credentialId}\n${nonce}`;
+}
 /** The text the company signs to revoke a credential. */
 export function revocationText(credentialId, nonce = crypto.randomUUID()) {
     return `KYA Brasil: revoke ${credentialId}\n${nonce}`;
@@ -204,3 +218,4 @@ export async function verifyAttestation(doc, opts = {}) {
     const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, sig, new TextEncoder().encode(`${hex}\n${att.signed_at}`));
     return ok ? { valid: true, key_id: att.key_id, signed_at: att.signed_at } : { valid: false, reason: "signature does not verify", key_id: att.key_id, signed_at: att.signed_at };
 }
+export * from "./auth";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.1.0",
-  "description": "KYA Brasil for AI agents: verify that an agent acts for a Brazilian company (e-CNPJ-signed, KYB-checked credential), check an action against its mandate, or give your own agent a credential. x402 payments (USDC on Base) handled for you. Adapters for Vercel AI SDK, LangChain, OpenAI and Anthropic.",
+  "version": "0.3.0",
+  "description": "KYA Brasil for AI agents: verify that an agent acts for a Brazilian company (e-CNPJ-signed, KYB-checked credential), check an action against its mandate, or give your own agent a credential. 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",
   "main": "./dist/index.js",