@kya-brasil/agent-tools 0.9.0 → 0.10.0

package/README.md

@@ -100,6 +100,22 @@ 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
 ```
 
+## Person: an agent that acts for you (e-CPF)
+
+```ts
+const reg = await kya.register({ agent: { kind: "evm", id: agentAddress }, principal: "person", mandate }); // $0.25
+// agent signs reg.challenge.text; you sign it with your e-CPF (reg.sign_url, kya-sign or signWithECnpjPfx: same code)
+const { credential } = await kya.prove(reg.credential_id, { challenge_id: reg.challenge.id, agent_signature, ecnpj_signature: ecpfSignature });
+// credential.principal = { kind: "person", verified_by: "icp-brasil-e-cpf" }: nothing personal
+
+// A verifier that already has the person's CPF:
+const m = await kya.principalMatch(credentialId, "529.982.247-25");   // $0.01, signed: { match, subject_ref? }
+
+// The person, to see their agents and every check made on them:
+const text = personAgentsText();                                        // sign it with the e-CPF
+const mine = await kya.personAgents({ signed_text: text, ecpf_signature });
+```
+
 ## Company: give your own agent a credential
 
 ```ts

package/dist/index.d.ts

@@ -49,10 +49,13 @@ export interface Credential {
     credential_id: string;
     version: number;
     agent: AgentKey;
+    /** A company, or (D-29) a person: { kind: "person", verified_by: "icp-brasil-e-cpf" } with nothing personal. */
     principal: {
-        cnpj: string;
+        kind?: "company" | "person";
+        cnpj?: string;
         legal_name?: string;
         registration_status?: string;
+        verified_by?: string;
     };
     authorized_by: {
         method: string;
@@ -79,9 +82,11 @@ export interface Verification {
     status_reason: string | null;
     agent: AgentKey;
     principal: {
-        cnpj: string;
-        cnpj_formatted: string;
-        legal_name: string | null;
+        kind?: "person";
+        verified_by?: string;
+        cnpj?: string;
+        cnpj_formatted?: string;
+        legal_name?: string | null;
     };
     credential: Credential | null;
     events: {
@@ -127,8 +132,9 @@ export interface Registration {
     credential_id: string;
     agent: AgentKey;
     principal: {
-        cnpj: string;
-        cnpj_formatted: string;
+        kind?: "person";
+        cnpj?: string;
+        cnpj_formatted?: string;
     };
     mandate: Mandate;
     challenge: {
@@ -195,11 +201,39 @@ export interface KyaClient {
     /** $0.01: signed verdict, is this action inside the mandate and is the credential active? */
     allowed(credentialId: string, q: ActionQuery): Promise<Verdict>;
     /** $0.25: register an agent for a company; returns the challenge both parties sign. */
+    /** $0.25: register an agent for a company (cnpj) or, with principal "person", for a natural person who signs with an e-CPF (D-29). */
     register(input: {
         agent: AgentKey;
-        cnpj: string;
+        cnpj?: string;
+        principal?: "company" | "person";
         mandate: Mandate;
     }): Promise<Registration>;
+    /** $0.01 (D-29): does the CPF you already have match the person behind this credential? On a match, your own subject_ref for that person. Never reveals the CPF. */
+    principalMatch(credentialId: string, cpf: string): Promise<{
+        credential_id: string;
+        match: boolean;
+        subject_ref?: string;
+        verifier: string;
+        checked_at: string;
+        attestation?: Attestation;
+    }>;
+    /** Free (D-29): the person's own credentials and the CPF checks made on each; sign personAgentsText() with the e-CPF. */
+    personAgents(input: {
+        signed_text: string;
+        ecpf_signature: string;
+    }): Promise<{
+        agents: {
+            credential_id: string;
+            agent: AgentKey;
+            status: string;
+            expires_at: string | null;
+            checks: {
+                verifier: string;
+                matched: boolean;
+                at: string;
+            }[];
+        }[];
+    }>;
     /** 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; /** D-24: e.g. registration status not confirmed (issued anyway). */
@@ -373,6 +407,7 @@ export declare function verifyCredentialOffline(credential: Credential, opts?: {
     now?: Date;
 }): Promise<OfflineCheck>;
 export * from "./auth.js";
+export { isValidCpf, personAgentsText } 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

@@ -94,6 +94,8 @@ export function createKyaClient(opts = {}) {
         revoke: (id, input) => call("POST", `/v1/agents/${encodeURIComponent(id)}/revoke`, input),
         revocations: (since) => call("GET", `/v1/revocations${q({ since })}`),
         companyAgents: (cnpj, input) => call("POST", `/v1/companies/${encodeURIComponent(cnpj)}/agents`, input),
+        principalMatch: (id, cpf) => call("POST", `/v1/agents/${encodeURIComponent(id)}/principal-match`, { cpf }, true, 0.01),
+        personAgents: (input) => call("POST", "/v1/people/agents", input),
         setCompanyWebhook: (cnpj, input) => call("POST", `/v1/companies/${encodeURIComponent(cnpj)}/webhook`, input),
         tools: [],
         execute: async (name, args) => {
@@ -252,6 +254,7 @@ 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";
 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.9.0",
+  "version": "0.10.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.9.0"
+    "@kya-brasil/core": "^0.10.0"
   },
   "devDependencies": {
     "@peculiar/asn1-schema": "^2.3.15",