@kya-brasil/agent-tools 0.6.0 → 0.8.0

package/README.md

@@ -103,7 +103,7 @@ if (!callee?.ok) throw new Error("unsigned or invalid callee");       // callee.
 ## Company: give your own agent a credential
 
 ```ts
-import { createKyaClient, signChallengeWithEvmKey, signWithECnpj } from "@kya-brasil/agent-tools";
+import { createKyaClient, signChallengeWithEvmKey, signingLink, signWithECnpjPfx } from "@kya-brasil/agent-tools";
 import { readFileSync } from "node:fs";
 
 const kya = createKyaClient({ privateKey: payerPk });
@@ -120,19 +120,50 @@ const reg = await kya.register({                                           // $0
 });
 
 const agent_signature = await signChallengeWithEvmKey(agentPk, reg.challenge.text);
-const ecnpj_signature = await signWithECnpj({
-  certificatePem: readFileSync("ecnpj.crt.pem", "utf8"),
-  privateKeyPem: readFileSync("ecnpj.key.pem", "utf8"),
-  chainPem: [readFileSync("ecnpj.chain.pem", "utf8")]
-}, reg.challenge.text);
 
-const { credential } = await kya.prove(reg.credential_id, { challenge_id: reg.challenge.id, agent_signature, ecnpj_signature }); // free
+// Usual case: a person holds the e-CNPJ (owner, accountant). Send them the link; they sign in the browser
+// (.pfx, or a .p7s from any ICP-Brasil signer for A3 tokens and cloud certificates) and the credential is issued.
+const link = signingLink({ credentialId: reg.credential_id, challenge: reg.challenge, agentSignature: agent_signature });
+// (reg.sign_url is the same link without the agent signature)
+
+// Or in code, when you hold the A1 file yourself:
+const ecnpj_signature = signWithECnpjPfx(readFileSync("empresa.pfx"), process.env.PFX_PASSWORD!, reg.challenge.text);
+const { credential, warnings } = await kya.prove(reg.credential_id, { challenge_id: reg.challenge.id, agent_signature, ecnpj_signature }); // free
+```
+
+`signWithECnpjPfx` reads the `.pfx`/`.p12` directly, including the legacy 3DES/RC2 encryption many Brazilian A1
+files use; `signWithECnpj` still takes PEM. On a terminal, the `kya-sign` command does the same without code:
+
+```sh
+npx -p @kya-brasil/agent-tools kya-sign --pfx empresa.pfx --link "<sign_url>&agent_signature=…"   # signs and issues
+npx -p @kya-brasil/agent-tools kya-sign --pfx empresa.pfx --text-file desafio.txt               # prints the signature
 ```
 
-From an A1 `.pfx`: `openssl pkcs12 -in cert.pfx -clcerts -nokeys > ecnpj.crt.pem`,
-`openssl pkcs12 -in cert.pfx -nocerts -nodes | openssl pkcs8 -topk8 -nocrypt > ecnpj.key.pem`,
-`openssl pkcs12 -in cert.pfx -cacerts -nokeys > ecnpj.chain.pem`. A3 certificates (token, card) sign through the vendor's software;
-pass the resulting detached CMS as `ecnpj_signature`.
+The password comes from `KYA_PFX_PASSWORD` or is asked for without echo. Everything runs locally.
+
+**A3 (token or smart card).** Through PKCS#11, the interface every ICP-Brasil token driver ships. Install the
+optional `pkcs11js` and point to the vendor's library (e.g. SafeNet eToken `libeTPkcs11.so` / `eTPKCS11.dll`):
+
+```sh
+npm install pkcs11js
+npx -p @kya-brasil/agent-tools kya-sign --pkcs11 /usr/lib/libeTPkcs11.so --list                       # certificates on the token
+npx -p @kya-brasil/agent-tools kya-sign --pkcs11 /usr/lib/libeTPkcs11.so --link "<sign_url>&agent_signature=…"
+```
+
+```ts
+const token = await openToken({ library: "/usr/lib/libeTPkcs11.so", pin: process.env.TOKEN_PIN! });
+try { ecnpj_signature = await token.sign(reg.challenge.text); } finally { token.close(); }
+```
+
+The PIN comes from `KYA_TOKEN_PIN` or is asked for. The key never leaves the token. Tested against SoftHSM2 (a
+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`.
+
+**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`.
+
+An agent should not hold the company's e-CNPJ to sign for itself: that signature is the company's consent.
+Let the agent prepare and send the link, and a person sign.
 
 Renew every 90 days (`kya.renew` then `kya.renewProve`), revoke at once (`kya.revoke` with `revocationText(id)` signed by the e-CNPJ).
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * kya-sign: sign a KYA challenge (or a company request text) with the company's e-CNPJ, A1 or A3.
+ *   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)
+ *   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 { listTokenCertificates, openToken } from "./pkcs11.js";
+const args = process.argv.slice(2);
+const opt = (name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+const die = (msg) => {
+    process.stderr.write(`kya-sign: ${msg}\n`);
+    process.exit(1);
+};
+async function askSecret(envName, prompt) {
+    if (process.env[envName] !== undefined)
+        return process.env[envName];
+    if (!process.stdin.isTTY)
+        die(`set ${envName} (no terminal to ask for it)`);
+    process.stderr.write(prompt);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    let secret = "";
+    return new Promise((resolve) => {
+        process.stdin.on("data", (b) => {
+            for (const ch of b.toString("utf8")) {
+                if (ch === "\r" || ch === "\n") {
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.stderr.write("\n");
+                    return resolve(secret);
+                }
+                if (ch === "\u0003")
+                    process.exit(130);
+                secret = ch === "\u007f" ? secret.slice(0, -1) : secret + ch;
+            }
+        });
+    });
+}
+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
+`;
+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) {
+        process.stdout.write(USAGE);
+        process.exit(2);
+    }
+    const slot = opt("slot") !== undefined ? Number(opt("slot")) : undefined;
+    if (library && args.includes("--list")) {
+        for (const c of await listTokenCertificates({ library, slot }))
+            process.stdout.write(`${c.label}\t${c.cnpj ?? "-"}\t${c.notAfter.toISOString().slice(0, 10)}\t${c.subject}\n`);
+        return;
+    }
+    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)
+        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: "));
+    try {
+        process.stderr.write(`certificate: ${signer.subject}\nsigning:\n${text.split("\n").map((l) => `  ${l}`).join("\n")}\n`);
+        const signature = await signer.sign(text);
+        if (!link?.credentialId || !link.challengeId || !link.agentSignature) {
+            process.stdout.write(`${signature}\n`);
+            return;
+        }
+        const res = await fetch(new URL(`/v1/agents/${encodeURIComponent(link.credentialId)}/prove`, link.issuer), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ challenge_id: link.challengeId, agent_signature: link.agentSignature, ecnpj_signature: signature })
+        });
+        process.stdout.write(`${await res.text()}\n`);
+        if (!res.ok)
+            process.exitCode = 1;
+    }
+    finally {
+        signer.close?.();
+    }
+}
+main().catch((e) => die(e.message));

package/dist/index.d.ts

@@ -141,6 +141,8 @@ export interface Registration {
         pt: string;
     };
     mandate_schema: string;
+    /** Link for the e-CNPJ holder; append &agent_signature=… (or use signingLink / signLink). */
+    sign_url?: string;
 }
 export interface Proof {
     challenge_id: string;
@@ -204,6 +206,16 @@ export interface KyaClient {
         warnings?: string[]; /** /v1 compatibility, same as warnings. */
         kyb_warnings: string[];
     }>;
+    /** Free: the link for the e-CNPJ holder (owner, accountant), with the agent's signature already in it. */
+    signLink(credentialId: string, q: {
+        challenge_id: string;
+        agent_signature?: string;
+    }): Promise<{
+        credential_id: string;
+        challenge_id: string;
+        expires_at: string;
+        sign_url: string;
+    }>;
     /** $0.10: renewal challenge (then renewProve). */
     renew(credentialId: string): Promise<{
         credential_id: string;
@@ -361,3 +373,20 @@ export declare function verifyCredentialOffline(credential: Credential, opts?: {
     now?: Date;
 }): Promise<OfflineCheck>;
 export * from "./auth.js";
+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";
+/**
+ * Link to the issuer's signing page (<issuer>/sign) for the person who holds the company's e-CNPJ, usually the
+ * owner or the accountant. The agent registers, signs its half and sends this link; the person opens it, sees
+ * which agent, company and mandate they are authorizing, signs with the .pfx in the browser (the file never
+ * leaves the computer) or uploads a .p7s from any ICP-Brasil signer, and the credential is issued.
+ */
+export declare function signingLink(p: {
+    credentialId: string;
+    challenge: {
+        id: string;
+        text: string;
+    };
+    agentSignature?: string;
+    baseUrl?: string;
+}): string;

package/dist/index.js

@@ -88,6 +88,7 @@ export function createKyaClient(opts = {}) {
         allowed: (id, a) => call("GET", `/v1/agents/${encodeURIComponent(id)}/allowed${q(a)}`, undefined, true, 0.01),
         register: (input) => call("POST", "/v1/agents", input, true, 0.25),
         prove: (id, proof) => call("POST", `/v1/agents/${encodeURIComponent(id)}/prove`, proof),
+        signLink: (id, a) => call("GET", `/v1/agents/${encodeURIComponent(id)}/sign-link${q(a)}`),
         renew: (id) => call("POST", `/v1/agents/${encodeURIComponent(id)}/renew`, {}, true, 0.1),
         renewProve: (id, proof) => call("POST", `/v1/agents/${encodeURIComponent(id)}/renew/prove`, proof),
         revoke: (id, input) => call("POST", `/v1/agents/${encodeURIComponent(id)}/revoke`, input),
@@ -250,3 +251,16 @@ export async function verifyCredentialOffline(credential, opts = {}) {
     return { signature, within_validity, live_status: "unknown", usable_offline: signature.valid && within_validity && credential.status === "active" };
 }
 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 { buildDetachedCms, cnpjFromCommonName, ecnpjSigner, openPfx, readSigningLink, signWithECnpjPfx } from "@kya-brasil/core";
+export { listTokenCertificates, openToken } from "./pkcs11.js";
+import { signingLink as coreSigningLink } from "@kya-brasil/core";
+/**
+ * Link to the issuer's signing page (<issuer>/sign) for the person who holds the company's e-CNPJ, usually the
+ * owner or the accountant. The agent registers, signs its half and sends this link; the person opens it, sees
+ * which agent, company and mandate they are authorizing, signs with the .pfx in the browser (the file never
+ * leaves the computer) or uploads a .p7s from any ICP-Brasil signer, and the credential is issued.
+ */
+export function signingLink(p) {
+    return coreSigningLink({ issuer: p.baseUrl ?? DEFAULT_BASE_URL, credentialId: p.credentialId, challenge: p.challenge, agentSignature: p.agentSignature });
+}

package/dist/pkcs11.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A3 e-CNPJ (token or smart card) through PKCS#11, the interface every ICP-Brasil token driver ships
+ * (e.g. SafeNet eToken: libeTPkcs11.so / eTPKCS11.dll; GD/Watchdata/Oberthur: their own libraries). The
+ * private key never leaves the device: only the bytes to sign go in and the signature comes out. Node only;
+ * needs the optional package pkcs11js (npm install pkcs11js) and the vendor's library path.
+ */
+import { type ECnpjSigner } from "@kya-brasil/core";
+export interface TokenOptions {
+    /** Path to the vendor's PKCS#11 library (.so / .dylib / .dll). */
+    library: string;
+    /** The token's user PIN. */
+    pin: string;
+    /** Index among the slots with a token present (default 0). */
+    slot?: number;
+    /** Pick the certificate by its label on the token; default: the one whose common name carries a CNPJ. */
+    label?: string;
+}
+export interface TokenCertificate {
+    label: string;
+    subject: string;
+    cnpj: string | null;
+    notAfter: Date;
+}
+/** Certificates on the token (no PIN needed on most tokens), to pick one with `label`. */
+export declare function listTokenCertificates(o: {
+    library: string;
+    slot?: number;
+    pin?: string;
+}): Promise<TokenCertificate[]>;
+/**
+ * Opens the token and returns an e-CNPJ signer (same interface as openPfx). Call close() when done; it logs out
+ * and releases the token.
+ */
+export declare function openToken(o: TokenOptions): Promise<ECnpjSigner & {
+    close(): void;
+}>;

package/dist/pkcs11.js

@@ -0,0 +1,124 @@
+/**
+ * A3 e-CNPJ (token or smart card) through PKCS#11, the interface every ICP-Brasil token driver ships
+ * (e.g. SafeNet eToken: libeTPkcs11.so / eTPKCS11.dll; GD/Watchdata/Oberthur: their own libraries). The
+ * private key never leaves the device: only the bytes to sign go in and the signature comes out. Node only;
+ * needs the optional package pkcs11js (npm install pkcs11js) and the vendor's library path.
+ */
+import { ecnpjSigner } from "@kya-brasil/core";
+// DigestInfo prefix for SHA-256 (RFC 8017), for tokens that only offer raw CKM_RSA_PKCS.
+const SHA256_DIGEST_INFO = Uint8Array.from([0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 0x00, 0x04, 0x20]);
+async function load() {
+    try {
+        const mod = (await import("pkcs11js"));
+        return mod.default ?? mod;
+    }
+    catch {
+        throw new Error("A3 tokens need the optional package pkcs11js: npm install pkcs11js");
+    }
+}
+async function openSession(o) {
+    const p11 = await load();
+    const lib = new p11.PKCS11();
+    lib.load(o.library);
+    lib.C_Initialize();
+    const finalize = () => {
+        try {
+            lib.C_Finalize();
+        }
+        catch {
+            /* already finalized */
+        }
+    };
+    try {
+        const slots = lib.C_GetSlotList(true);
+        const slot = slots[o.slot ?? 0];
+        if (!slot)
+            throw new Error(slots.length ? `no token in slot ${o.slot}` : "no token found: is it plugged in, and is this the right library?");
+        const session = lib.C_OpenSession(slot, p11.CKF_SERIAL_SESSION);
+        if (o.pin !== undefined)
+            lib.C_Login(session, p11.CKU_USER, o.pin);
+        lib.C_FindObjectsInit(session, [{ type: p11.CKA_CLASS, value: p11.CKO_CERTIFICATE }]);
+        const handles = lib.C_FindObjects(session, 64);
+        lib.C_FindObjectsFinal(session);
+        const certs = handles.map((handle) => {
+            const [value, id, label] = lib.C_GetAttributeValue(session, handle, [{ type: p11.CKA_VALUE }, { type: p11.CKA_ID }, { type: p11.CKA_LABEL }]);
+            const der = new Uint8Array(value.value);
+            let signer = null;
+            try {
+                signer = ecnpjSigner({ certificates: [der], sign: async () => new Uint8Array() });
+            }
+            catch {
+                /* not an X.509 certificate we can read */
+            }
+            return { handle, der, id: id.value ?? Buffer.alloc(0), label: label.value?.toString("utf8") ?? "", signer };
+        });
+        return {
+            p11,
+            lib,
+            session,
+            certs,
+            close() {
+                try {
+                    if (o.pin !== undefined)
+                        lib.C_Logout(session);
+                    lib.C_CloseSession(session);
+                }
+                catch {
+                    /* ignore */
+                }
+                finalize();
+            }
+        };
+    }
+    catch (e) {
+        finalize();
+        throw e;
+    }
+}
+/** Certificates on the token (no PIN needed on most tokens), to pick one with `label`. */
+export async function listTokenCertificates(o) {
+    const s = await openSession(o);
+    try {
+        return s.certs.filter((c) => c.signer).map((c) => ({ label: c.label, subject: c.signer.subject, cnpj: c.signer.cnpj, notAfter: c.signer.notAfter }));
+    }
+    finally {
+        s.close();
+    }
+}
+/**
+ * Opens the token and returns an e-CNPJ signer (same interface as openPfx). Call close() when done; it logs out
+ * and releases the token.
+ */
+export async function openToken(o) {
+    const s = await openSession(o);
+    try {
+        const { p11, lib, session } = s;
+        const cert = o.label ? s.certs.find((c) => c.label === o.label) : s.certs.find((c) => c.signer?.cnpj);
+        if (!cert?.signer)
+            throw new Error(o.label ? `no certificate labelled "${o.label}" on the token` : "no e-CNPJ certificate on the token (none with a CNPJ in its name); pass a label");
+        lib.C_FindObjectsInit(session, [{ type: p11.CKA_CLASS, value: p11.CKO_PRIVATE_KEY }, { type: p11.CKA_ID, value: cert.id }]);
+        const [key] = lib.C_FindObjects(session, 1);
+        lib.C_FindObjectsFinal(session);
+        if (!key)
+            throw new Error("the token has no private key for that certificate (wrong PIN or key not on this token)");
+        // The chain: the other certificates on the token, when any (the issuer also has the ICP-Brasil bundle).
+        const chain = s.certs.filter((c) => c !== cert && c.signer).map((c) => c.der);
+        const signRaw = async (data) => {
+            try {
+                lib.C_SignInit(session, { mechanism: p11.CKM_SHA256_RSA_PKCS }, key);
+                return new Uint8Array(lib.C_Sign(session, Buffer.from(data), Buffer.alloc(1024)));
+            }
+            catch {
+                // Older tokens: hash here and sign the DigestInfo with raw PKCS#1 v1.5.
+                const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", data));
+                lib.C_SignInit(session, { mechanism: p11.CKM_RSA_PKCS }, key);
+                return new Uint8Array(lib.C_Sign(session, Buffer.concat([SHA256_DIGEST_INFO, digest]), Buffer.alloc(1024)));
+            }
+        };
+        return { ...ecnpjSigner({ certificates: [cert.der, ...chain], sign: signRaw }), close: () => s.close() };
+    }
+    catch (e) {
+        s.close();
+        throw e;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.6.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 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.8.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",
   "main": "./dist/index.js",
@@ -55,16 +55,23 @@
     "@x402/evm": "^2.28.0",
     "@x402/fetch": "^2.28.0",
     "pkijs": "^3.4.1",
-    "viem": "^2.57.5"
+    "viem": "^2.57.5",
+    "@kya-brasil/core": "^0.8.0"
   },
   "devDependencies": {
-    "@kya-brasil/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": "^4.1.11"
+    "vitest": "^4.1.11",
+    "pkcs11js": "2.1.7"
+  },
+  "bin": {
+    "kya-sign": "./dist/cli.js"
+  },
+  "optionalDependencies": {
+    "pkcs11js": "2.1.7"
   }
 }