@kya-brasil/agent-tools 0.6.0 → 0.7.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,29 @@ 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
 ```
 
-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`.
+`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
+```
+
+The password comes from `KYA_PFX_PASSWORD` or is asked for without echo. Everything runs locally.
+
+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,78 @@
+#!/usr/bin/env node
+/**
+ * kya-sign: sign a KYA challenge (or a company request text) with the e-CNPJ in a .pfx / .p12 file.
+ *   npx -p @kya-brasil/agent-tools kya-sign --pfx empresa.pfx --text-file desafio.txt
+ *   npx -p @kya-brasil/agent-tools kya-sign --pfx empresa.pfx --link "https://…/sign?id=…&challenge_id=…&text=…&agent_signature=…"
+ * The password comes from KYA_PFX_PASSWORD or is asked for (not echoed). Prints the base64 signature, or with
+ * --link and an agent_signature in it, sends the proof and prints the issued credential.
+ * Everything happens on this machine; the certificate is never sent anywhere.
+ */
+import { readFileSync } from "node:fs";
+import { openPfx } from "./pfx.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 askPassword() {
+    if (process.env.KYA_PFX_PASSWORD !== undefined)
+        return process.env.KYA_PFX_PASSWORD;
+    if (!process.stdin.isTTY)
+        die("set KYA_PFX_PASSWORD (no terminal to ask for the password)");
+    process.stderr.write("Senha do certificado / certificate password: ");
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    let pw = "";
+    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(pw);
+                }
+                if (ch === "\u0003")
+                    process.exit(130);
+                pw = ch === "\u007f" ? pw.slice(0, -1) : pw + ch;
+            }
+        });
+    });
+}
+const fromB64u = (s) => new TextDecoder().decode(Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0)));
+async function main() {
+    if (args.includes("--help") || args.includes("-h") || !opt("pfx")) {
+        process.stdout.write("usage: kya-sign --pfx <file.pfx> (--text-file <file> | --text <text> | --link <signing link>)\n");
+        process.exit(args.includes("--help") || args.includes("-h") ? 0 : 2);
+    }
+    const link = opt("link") ? new URL(opt("link")) : null;
+    const text = link ? fromB64u(link.searchParams.get("text") ?? die("the link has no text")) : opt("text-file") ? readFileSync(opt("text-file"), "utf8") : (opt("text") ?? die("give --text-file, --text or --link"));
+    const signer = openPfx(new Uint8Array(readFileSync(opt("pfx"))), await askPassword());
+    const cnpj = /^cnpj: (\d{14})$/m.exec(text)?.[1];
+    process.stderr.write(`certificate: ${signer.subject}\n`);
+    if (cnpj && signer.cnpj && cnpj !== signer.cnpj)
+        die(`this certificate is for CNPJ ${signer.cnpj}, the text is for ${cnpj}`);
+    process.stderr.write(`signing:\n${text.split("\n").map((l) => `  ${l}`).join("\n")}\n`);
+    const signature = signer.sign(text);
+    const id = link?.searchParams.get("id");
+    const challengeId = link?.searchParams.get("challenge_id");
+    const agentSignature = link?.searchParams.get("agent_signature");
+    if (!link || !id || !challengeId || !agentSignature) {
+        process.stdout.write(`${signature}\n`);
+        return;
+    }
+    const res = await fetch(new URL(`/v1/agents/${encodeURIComponent(id)}/prove`, link.origin), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ challenge_id: challengeId, agent_signature: agentSignature, ecnpj_signature: signature })
+    });
+    const body = await res.text();
+    process.stdout.write(`${body}\n`);
+    if (!res.ok)
+        process.exit(1);
+}
+main().catch((e) => die(e.message));

package/dist/index.d.ts

@@ -361,3 +361,19 @@ export declare function verifyCredentialOffline(credential: Credential, opts?: {
     now?: Date;
 }): Promise<OfflineCheck>;
 export * from "./auth.js";
+export * from "./pfx.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

@@ -250,3 +250,19 @@ 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";
+export * from "./pfx.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 function signingLink(p) {
+    const u = new URL("/sign", p.baseUrl ?? DEFAULT_BASE_URL);
+    u.searchParams.set("id", p.credentialId);
+    u.searchParams.set("challenge_id", p.challenge.id);
+    u.searchParams.set("text", toBase64Url(new TextEncoder().encode(p.challenge.text)));
+    if (p.agentSignature)
+        u.searchParams.set("agent_signature", p.agentSignature);
+    return u.toString();
+}

package/dist/pfx.d.ts

@@ -0,0 +1,13 @@
+export interface PfxSigner {
+    /** Subject of the e-CNPJ certificate, e.g. "CN=ACME LTDA:11222333000181, ...". */
+    subject: string;
+    /** CNPJ read from the certificate's common name ("NAME:CNPJ"), when present. */
+    cnpj: string | null;
+    notAfter: Date;
+    /** Detached CMS/PKCS#7 SignedData (base64 DER) over `text`, with the certificate chain found in the file. */
+    sign(text: string): string;
+}
+/** Opens a PKCS#12 file (bytes) with its password; throws a readable error on a wrong password or an empty file. */
+export declare function openPfx(pfx: Uint8Array, password: string): PfxSigner;
+/** One call: sign `text` with the e-CNPJ in a .pfx/.p12 file. Returns the base64 DER the issuer expects as ecnpj_signature. */
+export declare function signWithECnpjPfx(pfx: Uint8Array, password: string, text: string): string;

package/dist/pfx.js

@@ -0,0 +1,66 @@
+/**
+ * e-CNPJ signing straight from the .pfx / .p12 file companies actually have (A1 certificates). node-forge reads
+ * the legacy PKCS#12 encryptions (3DES, RC2) that Web Crypto cannot, which many Brazilian A1 files still use.
+ * The page at <issuer>/sign runs the same steps in the browser; keep the two in sync.
+ */
+import forge from "node-forge";
+const OID = {
+    shroudedKeyBag: forge.pki.oids.pkcs8ShroudedKeyBag,
+    keyBag: forge.pki.oids.keyBag,
+    certBag: forge.pki.oids.certBag,
+    sha256: forge.pki.oids.sha256,
+    contentType: forge.pki.oids.contentType,
+    data: forge.pki.oids.data,
+    messageDigest: forge.pki.oids.messageDigest,
+    signingTime: forge.pki.oids.signingTime
+};
+const cnOf = (c) => String(c.subject.getField("CN")?.value ?? "");
+const cnpjOfCn = (cn) => /:(\d{14})\s*$/.exec(cn)?.[1] ?? null;
+/** Opens a PKCS#12 file (bytes) with its password; throws a readable error on a wrong password or an empty file. */
+export function openPfx(pfx, password) {
+    let p12;
+    try {
+        p12 = forge.pkcs12.pkcs12FromAsn1(forge.asn1.fromDer(forge.util.binary.raw.encode(pfx)), false, password);
+    }
+    catch (e) {
+        throw new Error(`could not open the certificate file (wrong password or not a .pfx/.p12): ${e.message}`);
+    }
+    const keyBag = [OID.shroudedKeyBag, OID.keyBag].flatMap((t) => p12.getBags({ bagType: t })[t] ?? []).find((b) => b.key);
+    if (!keyBag?.key)
+        throw new Error("the file has no private key");
+    const key = keyBag.key;
+    const certs = (p12.getBags({ bagType: OID.certBag })[OID.certBag] ?? []).map((b) => b.cert).filter((c) => !!c);
+    // The signer is the certificate whose public key matches the private key; the others are its chain.
+    const leaf = certs.find((c) => c.publicKey.n?.equals(key.n));
+    if (!leaf)
+        throw new Error("no certificate in the file matches its private key");
+    return {
+        subject: leaf.subject.attributes.map((a) => `${a.shortName ?? a.name}=${a.value}`).join(", "),
+        cnpj: cnpjOfCn(cnOf(leaf)),
+        notAfter: leaf.validity.notAfter,
+        sign(text) {
+            const p7 = forge.pkcs7.createSignedData();
+            p7.content = forge.util.createBuffer(forge.util.encodeUtf8(text));
+            p7.addCertificate(leaf);
+            for (const c of certs)
+                if (c !== leaf)
+                    p7.addCertificate(c);
+            p7.addSigner({
+                key,
+                certificate: leaf,
+                digestAlgorithm: OID.sha256,
+                authenticatedAttributes: [
+                    { type: OID.contentType, value: OID.data },
+                    { type: OID.messageDigest },
+                    { type: OID.signingTime, value: new Date() }
+                ]
+            });
+            p7.sign({ detached: true });
+            return forge.util.encode64(forge.asn1.toDer(p7.toAsn1()).getBytes());
+        }
+    };
+}
+/** One call: sign `text` with the e-CNPJ in a .pfx/.p12 file. Returns the base64 DER the issuer expects as ecnpj_signature. */
+export function signWithECnpjPfx(pfx, password, text) {
+    return openPfx(pfx, password).sign(text);
+}

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.7.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 .pfx, 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",
@@ -54,6 +54,7 @@
     "@x402/core": "^2.28.0",
     "@x402/evm": "^2.28.0",
     "@x402/fetch": "^2.28.0",
+    "node-forge": "1.4.0",
     "pkijs": "^3.4.1",
     "viem": "^2.57.5"
   },
@@ -63,8 +64,12 @@
     "@peculiar/asn1-x509": "^2.3.15",
     "@peculiar/x509": "^2.1.0",
     "@types/node": "^22.20.5",
+    "@types/node-forge": "^1.3.14",
     "reflect-metadata": "^0.2.2",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
+  },
+  "bin": {
+    "kya-sign": "./dist/cli.js"
   }
 }