@kya-brasil/agent-tools 0.8.0 → 0.9.0

package/README.md

@@ -159,6 +159,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.8.0",
+  "version": "0.9.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.9.0"
   },
   "devDependencies": {
     "@peculiar/asn1-schema": "^2.3.15",