@kya-brasil/agent-tools 0.4.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # @kya-brasil/agent-tools
 
 **Know-your-agent for Brazil, as code.** Verify that an AI agent really acts for a Brazilian company
-(credential signed by the company's e-CNPJ, company cleared by [KYB Brasil](https://kyb-br-agents.marcelfons.workers.dev)),
+(credential signed by the company's e-CNPJ, checked against its AC's revocation list, company active at the Receita Federal),
 check an action against the agent's mandate, or give your own agent a credential.
 
 Paid per call with [x402](https://x402.org) (USDC on Base, no signup). Free verification works without a wallet
@@ -11,12 +11,15 @@ Paid per call with [x402](https://x402.org) (USDC on Base, no signup). Free veri
 npm i @kya-brasil/agent-tools
 ```
 
+The same build is mirrored to GitHub Packages as `@celfons/kya-agent-tools` (listed on the repository page;
+installing from there needs a GitHub token). npmjs.com is the channel to install from.
+
 Node 18+ (global `fetch`, WebCrypto). ESM.
 
 ## Verifier: you receive an action from someone else's agent
 
 ```ts
-import { createKyaClient, verifyAttestation } from "@kya-brasil/agent-tools";
+import { createKyaClient, verifyAttestation, verifyCredentialOffline, companyText, signWithECnpj } from "@kya-brasil/agent-tools";
 
 const kya = createKyaClient({ privateKey: process.env.KYA_PAYER_PK as `0x${string}` }); // wallet optional
 
@@ -30,14 +33,25 @@ 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
+// max_per_day: pass your own spent_today; the issuer does not record acts.
+
+const offline = await verifyCredentialOffline(credential);   // issuer down: signature + expires_at only,
+                                                             // live_status "unknown" (your risk until expires_at)
 ```
 
 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_register_act`, `kya_verify_paid`):
+Company side, after issuance: see every agent in your name and get signed events (issued, renewed, suspended,
+reinstated, revoked) at your webhook. Both requests are signed with the e-CNPJ:
+
+```ts
+const text = companyText("webhook", cnpj, { url: "https://acme.com.br/kya-events" });
+await kya.setCompanyWebhook(cnpj, { signed_text: text, ecnpj_signature: await signWithECnpj(material, text) });
+const inv = await kya.companyAgents(cnpj, { signed_text: t2, ecnpj_signature: s2 });   // t2 = companyText("agents", cnpj)
+// on your webhook: (await verifyAttestation(body)).valid before trusting the event
+```
+
+Agent frameworks (verifier tools `kya_verify`, `kya_check_action`, `kya_verify_paid`):
 
 ```ts
 import { toOpenAI, toVercelAI, toLangChain, toAnthropic } from "@kya-brasil/agent-tools";
@@ -124,9 +138,8 @@ Renew every 90 days (`kya.renew` then `kya.renewProve`), revoke at once (`kya.re
 
 | Call | Price |
 |---|---|
-| verify, verifyByKey, prove, renewProve, revoke, revocations | free |
+| verify, verifyByKey, prove, renewProve, revoke, revocations, companyAgents, setCompanyWebhook | 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

@@ -81,7 +81,7 @@ export interface LocalVerdict {
 /**
  * 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).
+ * knows nothing of it either: pass your own spent_today to ctx.allowed.
  */
 export declare function checkMandate(mandate: Mandate, q: ActionQuery, now?: Date): LocalVerdict;
 export interface KyaAuth {

package/dist/auth.js

@@ -28,11 +28,12 @@
 import { verifyMessage } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { createKyaClient } from "./index";
+import { fromBase64Url, toBase64Url } from "./base64url";
 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));
+const b64u = toBase64Url;
+const unb64u = fromBase64Url;
 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));
@@ -80,12 +81,15 @@ function normalizeCounterparty(c) {
         return digits;
     if (/^0x[0-9a-fA-F]{40}$/.test(t))
         return t.toLowerCase();
-    return t.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    // Domain or URL: drop the scheme, then everything from the first "/" (indexOf, no backtracking regex).
+    const host = t.toLowerCase().replace(/^https?:\/\//, "");
+    const slash = host.indexOf("/");
+    return slash === -1 ? host : host.slice(0, slash);
 }
 /**
  * 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).
+ * knows nothing of it either: pass your own spent_today to ctx.allowed.
  */
 export function checkMandate(mandate, q, now = new Date()) {
     const checks = [];

package/dist/base64url.d.ts

@@ -0,0 +1,4 @@
+/** Base64url without padding (RFC 4648 §5), for agent signatures and keys. Linear time, no regex. */
+export declare function stripPadding(s: string): string;
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(s: string): Uint8Array<ArrayBuffer>;

package/dist/base64url.js

@@ -0,0 +1,14 @@
+/** Base64url without padding (RFC 4648 §5), for agent signatures and keys. Linear time, no regex. */
+export function stripPadding(s) {
+    let end = s.length;
+    while (end > 0 && s[end - 1] === "=")
+        end--;
+    return s.slice(0, end);
+}
+export function toBase64Url(bytes) {
+    return stripPadding(btoa(String.fromCodePoint(...bytes)).replaceAll("+", "-").replaceAll("/", "_"));
+}
+export function fromBase64Url(s) {
+    const b64 = s.replaceAll("-", "+").replaceAll("_", "/");
+    return Uint8Array.from(atob(b64.padEnd(Math.ceil(b64.length / 4) * 4, "=")), (c) => c.codePointAt(0) ?? 0);
+}

package/dist/index.d.ts

@@ -56,7 +56,8 @@ export interface Credential {
         signed_at: string;
     };
     mandate: Mandate;
-    kyb_snapshot: Record<string, unknown>;
+    /** Informative; null when the issuer has no KYB source. */
+    kyb_snapshot: Record<string, unknown> | null;
     status: CredentialStatus;
     issued_at: string;
     expires_at: string;
@@ -131,44 +132,30 @@ 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 type CompanyEvent = "credential.issued" | "credential.renewed" | "credential.suspended" | "credential.reinstated" | "credential.revoked";
+/** Body POSTed to the company's webhook. Check it with verifyAttestation(event) before trusting it. */
+export interface CompanyWebhookEvent {
+    event: CompanyEvent;
+    cnpj: string;
+    at: string;
+    data: Record<string, unknown>;
+    attestation?: Attestation;
 }
-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;
+export interface CompanyInventory {
+    cnpj: string;
+    cnpj_formatted: string;
+    count: number;
+    agents: {
+        credential_id: string;
+        agent: AgentKey;
+        status: CredentialStatus | "pending";
+        status_reason: string | null;
+        mandate: Mandate;
+        certificate_sha256: string | null;
+        created_at: string;
+        issued_at: string | null;
+        expires_at: string | null;
     }[];
-    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;
@@ -196,7 +183,7 @@ export interface KyaClient {
         cnpj: string;
         mandate: Mandate;
     }): Promise<Registration>;
-    /** Free: send both signatures; the credential is issued if the e-CNPJ, the CNPJ and KYB Brasil all clear. */
+    /** Free: send both signatures; the credential is issued if the e-CNPJ is valid and not revoked, the CNPJ matches and the company is ATIVA. */
     prove(credentialId: string, proof: Proof): Promise<{
         credential: Credential;
         kyb_warnings: string[];
@@ -223,26 +210,20 @@ 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: {
+    /** Free, company only: every credential registered for the CNPJ, any status. signed_text = companyText("agents", cnpj), signed with the e-CNPJ. */
+    companyAgents(cnpj: string, input: {
+        signed_text: string;
+        ecnpj_signature: string;
+    }): Promise<CompanyInventory>;
+    /** Free, company only: sets (or removes, with "-") the https URL that receives signed CompanyWebhookEvent. signed_text = companyText("webhook", cnpj, { url }). */
+    setCompanyWebhook(cnpj: string, input: {
         signed_text: string;
         ecnpj_signature: string;
-        since?: string;
     }): Promise<{
-        credential_id: string;
-        since: string;
-        count: number;
-        acts: Record<string, unknown>[];
+        cnpj: string;
+        webhook: string | null;
+        signed_at: string;
+        events: CompanyEvent[];
     }>;
     /** Free: credentials revoked since a date (default 30 days). */
     revocations(since?: string): Promise<{
@@ -316,8 +297,14 @@ 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 for its inventory or its webhook. The issuer accepts it for 10 minutes after `at`
+ * (and a webhook change only if newer than the last accepted one). For the webhook, url "-" removes it.
+ */
+export declare function companyText(verb: "agents" | "webhook", cnpj: string, opts?: {
+    url?: string;
+    at?: Date;
+}): string;
 /** The text the company signs to revoke a credential. */
 export declare function revocationText(credentialId: string, nonce?: string): string;
 export interface VerifyResult {
@@ -337,4 +324,23 @@ export declare function verifyAttestation(doc: Record<string, unknown>, opts?: {
     publicJwk?: JsonWebKey;
     fetch?: typeof fetch;
 }): Promise<VerifyResult>;
+export interface OfflineCheck {
+    /** Issuer signature over the credential: proves what was issued and that it was not modified. */
+    signature: VerifyResult;
+    /** expires_at is in the future (the credential's own deadline). */
+    within_validity: boolean;
+    /**
+     * Always "unknown": a signature cannot say whether the credential was suspended or revoked after it was issued.
+     * Check verify() (or /v1/revocations) when you can; accepting an offline-only check is your risk until expires_at.
+     */
+    live_status: "unknown";
+    usable_offline: boolean;
+}
+/** Checks a credential with no call to the issuer's API (only the published key, unless publicJwk is given). */
+export declare function verifyCredentialOffline(credential: Credential, opts?: {
+    baseUrl?: string;
+    publicJwk?: JsonWebKey;
+    fetch?: typeof fetch;
+    now?: Date;
+}): Promise<OfflineCheck>;
 export * from "./auth";

package/dist/index.js

@@ -21,6 +21,7 @@ import { toClientEvmSigner } from "@x402/evm";
 import { wrapFetchWithPayment } from "@x402/fetch";
 import { privateKeyToAccount } from "viem/accounts";
 import * as pkijs from "pkijs";
+import { toBase64Url } from "./base64url";
 export const DEFAULT_BASE_URL = "https://kya-br-agents.marcelfons.workers.dev";
 export class KyaError extends Error {
     code;
@@ -80,10 +81,8 @@ 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),
+        companyAgents: (cnpj, input) => call("POST", `/v1/companies/${encodeURIComponent(cnpj)}/agents`, input),
+        setCompanyWebhook: (cnpj, input) => call("POST", `/v1/companies/${encodeURIComponent(cnpj)}/webhook`, input),
         tools: [],
         execute: async (name, args) => {
             const t = client.tools.find((x) => x.name === name);
@@ -106,12 +105,6 @@ 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).",
@@ -143,7 +136,7 @@ export async function signChallengeWithEvmKey(privateKey, text) {
 export async function signChallengeWithEd25519(privateKey, text) {
     const key = typeof privateKey === "string" ? await crypto.subtle.importKey("pkcs8", Uint8Array.from(atob(privateKey), (c) => c.charCodeAt(0)), { name: "Ed25519" }, false, ["sign"]) : privateKey;
     const sig = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, key, new TextEncoder().encode(text)));
-    return btoa(String.fromCharCode(...sig)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    return toBase64Url(sig);
 }
 const pemToDer = (pem) => Uint8Array.from(atob(pem.replace(/-----[^-]+-----/g, "").replace(/\s+/g, "")), (c) => c.charCodeAt(0)).buffer;
 const pemBlocks = (pem) => [...pem.matchAll(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g)].map((m) => m[0]);
@@ -173,22 +166,43 @@ 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 for its inventory or its webhook. The issuer accepts it for 10 minutes after `at`
+ * (and a webhook change only if newer than the last accepted one). For the webhook, url "-" removes it.
+ */
+export function companyText(verb, cnpj, opts = {}) {
+    const digits = cnpj.replace(/\D/g, "");
+    const extra = verb === "webhook" ? [`url: ${opts.url ?? "-"}`] : [];
+    return [`KYA Brasil: ${verb} ${digits}`, ...extra, `at: ${(opts.at ?? new Date()).toISOString()}`].join("\n");
 }
 /** The text the company signs to revoke a credential. */
 export function revocationText(credentialId, nonce = crypto.randomUUID()) {
     return `KYA Brasil: revoke ${credentialId}\n${nonce}`;
 }
 // --- Local verification of a credential or a signed answer (no network once you hold the key) ---
+/**
+ * Key order of the canonical JSON: UTF-16 code units, exactly what a comparator-less sort() does. Not
+ * localeCompare: a locale-dependent order would change the signed bytes between machines and break every
+ * signature already issued.
+ */
+function byCodeUnit(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
 function canonicalize(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v);
     if (Array.isArray(v))
         return `[${v.map(canonicalize).join(",")}]`;
     const o = v;
-    return `{${Object.keys(o).filter((k) => o[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(o[k])}`).join(",")}}`;
+    const members = Object.keys(o)
+        .filter((k) => o[k] !== undefined)
+        .sort(byCodeUnit)
+        .map((k) => JSON.stringify(k) + ":" + canonicalize(o[k]));
+    return "{" + members.join(",") + "}";
 }
 /**
  * Verifies the Ed25519 attestation of a credential or a signed answer: recomputes the SHA-256 of the
@@ -218,4 +232,10 @@ 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 };
 }
+/** Checks a credential with no call to the issuer's API (only the published key, unless publicJwk is given). */
+export async function verifyCredentialOffline(credential, opts = {}) {
+    const signature = await verifyAttestation(credential, opts);
+    const within_validity = Date.parse(credential.expires_at) > (opts.now ?? new Date()).getTime();
+    return { signature, within_validity, live_status: "unknown", usable_offline: signature.valid && within_validity && credential.status === "active" };
+}
 export * from "./auth";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.4.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.",
+  "version": "0.5.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), 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",
@@ -58,12 +58,13 @@
     "viem": "^2.57.5"
   },
   "devDependencies": {
+    "@kya-br/core": "workspace:*",
     "@peculiar/asn1-schema": "^2.3.15",
     "@peculiar/asn1-x509": "^2.3.15",
     "@peculiar/x509": "^2.1.0",
+    "@types/node": "^22.20.5",
     "reflect-metadata": "^0.2.2",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
-    "@kya-br/core": "workspace:*"
+    "vitest": "^4.1.11"
   }
 }