@kya-brasil/agent-tools 0.8.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
@@ -159,6 +175,10 @@ The PIN comes from `KYA_TOKEN_PIN` or is asked for. The key never leaves the tok
 software PKCS#11 token) in CI. The signing code is in `@kya-brasil/core` (`openPfx`, `ecnpjSigner`,
 `buildDetachedCms`), re-exported here; any other token or cloud signer plugs into `ecnpjSigner`.
 
+**Cloud certificate (PSC).** `kya-sign --cloud ./my-psc.mjs --link "<sign_url>"` with a module that implements
+`CloudSignatureProvider` for your PSC ([template](https://github.com/celfons/kya-brasil/tree/main/examples/cloud-provider));
+the browser opens for the approval and the terminal receives the redirect on `127.0.0.1`.
+
 **From the agent's side**, `kya.signLink(credentialId, { challenge_id, agent_signature })` (free) returns the
 `sign_url` to send, the same as `signingLink(...)` offline and the MCP tool `kya_sign_link`.
 

package/dist/cli.js

@@ -4,13 +4,20 @@
  *   A1 file:   kya-sign --pfx empresa.pfx --link "<sign_url>&agent_signature=…"
  *   A3 token:  kya-sign --pkcs11 /usr/lib/libeTPkcs11.so --link "<sign_url>&agent_signature=…"
  *              kya-sign --pkcs11 <library> --list              (certificates on the token)
+ *   Cloud:     kya-sign --cloud ./my-psc.mjs --link "<sign_url>&agent_signature=…"
+ *              (a module exporting a CloudSignatureProvider: yours, for your PSC; the browser opens for the
+ *               approval and comes back to a one-time local address)
  *   Text instead of a link: --text-file desafio.txt or --text "<text>" (prints the signature).
  * The password (A1) comes from KYA_PFX_PASSWORD and the PIN (A3) from KYA_TOKEN_PIN, or are asked for without
  * echo. With a link carrying agent_signature, the proof is sent and the issued credential printed. Everything
  * happens on this machine; the certificate and its password or PIN are never sent anywhere.
  */
 import { readFileSync } from "node:fs";
-import { openPfx, readSigningLink } from "@kya-brasil/core";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { cloudSigner, newState, pkcePair, openPfx, readSigningLink } from "@kya-brasil/core";
 import { listTokenCertificates, openToken } from "./pkcs11.js";
 const args = process.argv.slice(2);
 const opt = (name) => {
@@ -46,17 +53,69 @@ async function askSecret(envName, prompt) {
         });
     });
 }
+/** Loads a provider module: a path (./my-psc.mjs) or a package name; default export or `provider`. */
+async function loadProvider(spec) {
+    const url = spec.startsWith(".") || spec.startsWith("/") ? pathToFileURL(resolve(spec)).href : spec;
+    const mod = (await import(url));
+    const p = (mod.provider ?? mod.default);
+    if (!p || typeof p.authorizationUrl !== "function" || typeof p.exchangeCode !== "function")
+        die(`${spec} does not export a CloudSignatureProvider (default export or "provider")`);
+    return p;
+}
+/**
+ * OAuth with PKCE through the browser: a one-time server on 127.0.0.1 receives the code, checks the state,
+ * exchanges it and returns an e-CNPJ signer over the provider's session.
+ */
+async function cloudLogin(provider, port, open) {
+    const state = newState();
+    const { verifier, challenge } = await pkcePair();
+    let answer;
+    const answered = new Promise((r) => (answer = r));
+    const server = createServer((req, res) => {
+        const u = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (u.pathname !== "/callback")
+            return void res.writeHead(404).end();
+        const ok = u.searchParams.get("state") === state && !!u.searchParams.get("code");
+        res.writeHead(ok ? 200 : 400, { "content-type": "text/html; charset=utf-8" }).end(ok ? "<p>Autorizado. Pode fechar esta janela e voltar ao terminal.</p>" : "<p>Autorização recusada ou inválida.</p>");
+        answer(ok ? { code: u.searchParams.get("code") } : { error: u.searchParams.get("error_description") ?? u.searchParams.get("error") ?? "state mismatch" });
+    });
+    await new Promise((r) => server.listen(port, "127.0.0.1", r));
+    const addr = server.address();
+    const redirectUri = `http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : port}/callback`;
+    const timer = setTimeout(() => answer({ error: "no approval within 5 minutes" }), 300_000);
+    try {
+        const url = await provider.authorizationUrl({ redirectUri, state, codeChallenge: challenge });
+        process.stderr.write(`Abra para aprovar no ${provider.name} / open to approve:\n  ${url}\n`);
+        if (open) {
+            const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+            const a = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+            spawn(cmd, a, { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
+        }
+        const r = await answered;
+        if (!r.code)
+            throw new Error(`not authorized: ${r.error}`);
+        const session = await provider.exchangeCode({ code: r.code, redirectUri, codeVerifier: verifier });
+        const signer = await cloudSigner(session);
+        return { ...signer, close: async () => void (await session.close?.().catch(() => undefined)) };
+    }
+    finally {
+        clearTimeout(timer);
+        server.close();
+    }
+}
 const USAGE = `usage:
   kya-sign --pfx <file.pfx> (--link <signing link> | --text-file <file> | --text <text>)
   kya-sign --pkcs11 <library> [--slot N] [--label L] (--link … | --text-file … | --text …)
   kya-sign --pkcs11 <library> --list
+  kya-sign --cloud <provider module> [--port N] [--no-open] (--link … | --text-file … | --text …)
 `;
 async function main() {
     if (args.includes("--help") || args.includes("-h"))
         return void process.stdout.write(USAGE);
     const pfxPath = opt("pfx");
     const library = opt("pkcs11");
-    if (!pfxPath && !library) {
+    const cloud = opt("cloud");
+    if (!pfxPath && !library && !cloud) {
         process.stdout.write(USAGE);
         process.exit(2);
     }
@@ -69,7 +128,9 @@ async function main() {
     const link = opt("link") ? readSigningLink(opt("link")) : null;
     const text = link ? link.text : opt("text-file") ? readFileSync(opt("text-file"), "utf8") : (opt("text") ?? die("give --link, --text-file or --text"));
     let signer;
-    if (library)
+    if (cloud)
+        signer = await cloudLogin(await loadProvider(cloud), opt("port") ? Number(opt("port")) : 0, !args.includes("--no-open"));
+    else if (library)
         signer = await openToken({ library, slot, label: opt("label"), pin: await askSecret("KYA_TOKEN_PIN", "PIN do token / token PIN: ") });
     else
         signer = await openPfx(new Uint8Array(readFileSync(pfxPath)), await askSecret("KYA_PFX_PASSWORD", "Senha do certificado / certificate password: "));
@@ -90,7 +151,7 @@ async function main() {
             process.exitCode = 1;
     }
     finally {
-        signer.close?.();
+        await signer.close?.();
     }
 }
 main().catch((e) => die(e.message));

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.8.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.8.0"
+    "@kya-brasil/core": "^0.10.0"
   },
   "devDependencies": {
     "@peculiar/asn1-schema": "^2.3.15",