@kya-brasil/core 0.7.0 → 0.8.0

package/README.md

@@ -66,6 +66,27 @@ the network already gives (network token reference, Payment Account Reference),
 With the hosted issuer, the same check comes back signed from
 `GET /v1/agents/{id}/allowed?payment_network=visa&payment_ref_sha256=…`, which is evidence for a later dispute.
 
+## Sign as the e-CNPJ holder (A1 and A3)
+
+The company's side of the challenge, without the hosted page. The issuer only ever receives the signature.
+
+```ts
+import { openPfx, ecnpjSigner, readSigningLink } from "@kya-brasil/core";
+
+// A1: the .pfx / .p12 file (legacy 3DES/RC2 PKCS#12 included)
+const a1 = await openPfx(pfxBytes, password);
+const ecnpj_signature = await a1.sign(challengeText);       // detached CMS, base64: POST it to /v1/agents/{id}/prove
+
+// A3 token, smart card, HSM or cloud certificate: anything that signs bytes with the certificate's RSA key
+// (PKCS#1 v1.5 over SHA-256), plus the certificate chain in DER.
+const a3 = ecnpjSigner({ certificates: [certDer, ...chainDer], sign: (bytes) => myToken.sign("SHA256withRSA", bytes) });
+const sig = await a3.sign(readSigningLink(link).text);       // the text from a /sign link the agent sent
+```
+
+`sign` refuses a text whose `cnpj:` line names another company. For PKCS#11 tokens on Node,
+`openToken({ library, pin })` in `@kya-brasil/agent-tools` (and the `kya-sign --pkcs11` command) already wires
+`C_Sign` into `ecnpjSigner`.
+
 ## Run your own issuer
 
 ```ts

package/dist/ecnpj-sign.d.ts

@@ -0,0 +1,57 @@
+/** Signs `data` with the certificate's RSA private key: PKCS#1 v1.5 over SHA-256 (the signer hashes). */
+export type RawSigner = (data: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Detached CMS/PKCS#7 SignedData (base64 DER) over `text`, with signed attributes (content type, message
+ * digest, signing time) and the given certificates (signer first, then its chain, DER). The issuer accepts it as
+ * `ecnpj_signature`.
+ */
+export declare function buildDetachedCms(p: {
+    text: string;
+    certificates: Uint8Array[];
+    sign: RawSigner;
+    signingTime?: Date;
+}): Promise<string>;
+/** What a certificate holder exposes to sign: subject, CNPJ, validity, chain and the sign step. */
+export interface ECnpjSigner {
+    /** 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;
+    /** Signer certificate first, then the chain found with it (DER). */
+    certificates: Uint8Array[];
+    /** Detached CMS (base64 DER) over `text`; refuses a text whose "cnpj:" line names another company. */
+    sign(text: string): Promise<string>;
+}
+/** CNPJ in a common name ending in ":<14 digits>", the ICP-Brasil convention for e-CNPJ. */
+export declare const cnpjFromCommonName: (cn: string) => string | null;
+/** Wraps a raw signer and its certificates into an ECnpjSigner (used for A1 files, tokens, HSMs, cloud). */
+export declare function ecnpjSigner(p: {
+    certificates: Uint8Array[];
+    sign: RawSigner;
+}): ECnpjSigner;
+/** Opens an A1 e-CNPJ file (.pfx / .p12 bytes) with its password. The key stays in memory, inside Web Crypto. */
+export declare function openPfx(pfx: Uint8Array, password: string): Promise<ECnpjSigner>;
+/** One call: sign `text` with the e-CNPJ in an A1 file. Returns the base64 DER the issuer expects as ecnpj_signature. */
+export declare function signWithECnpjPfx(pfx: Uint8Array, password: string, text: string): Promise<string>;
+/**
+ * Link to an issuer's signing page (<issuer>/sign) for the person who holds the company's e-CNPJ. The agent
+ * registers, signs its half and sends this link; the person sees what they authorize and signs in the browser.
+ */
+export declare function signingLink(p: {
+    issuer: string;
+    credentialId: string;
+    challenge: {
+        id: string;
+        text: string;
+    };
+    agentSignature?: string;
+}): string;
+/** The challenge text carried by a signing link (inverse of signingLink), with its ids. */
+export declare function readSigningLink(link: string): {
+    issuer: string;
+    credentialId: string | null;
+    challengeId: string | null;
+    agentSignature: string | null;
+    text: string;
+};

package/dist/ecnpj-sign.js

@@ -0,0 +1,154 @@
+/**
+ * Signing with the company's e-CNPJ, for whoever holds it (D-26, D-27). One CMS builder for every kind of
+ * certificate: the caller gives the certificate chain and a function that signs bytes with the private key.
+ *   A1 (.pfx / .p12 file): openPfx / signWithECnpjPfx here (node-forge reads the legacy 3DES/RC2 PKCS#12
+ *     many Brazilian A1 files use; the key is then used through Web Crypto);
+ *   A3 (token, smart card), HSM, cloud certificate: anything that can produce an RSA PKCS#1 v1.5 SHA-256
+ *     signature (PKCS#11 C_Sign with CKM_SHA256_RSA_PKCS, a cloud signing API, ...) plugs into
+ *     buildDetachedCms. The kya-sign command in @kya-brasil/agent-tools does it for PKCS#11 tokens.
+ * Pure: no storage, no network. The issuer never receives the certificate or its password.
+ */
+import * as asn1js from "asn1js";
+import * as pkijs from "pkijs";
+import forge from "node-forge";
+import { KyaError } from "./types.js";
+const OID_DATA = "1.2.840.113549.1.7.1";
+const OID_SIGNED_DATA = "1.2.840.113549.1.7.2";
+const OID_SHA256 = "2.16.840.1.101.3.4.2.1";
+const OID_SHA256_RSA = "1.2.840.113549.1.1.11";
+const OID_CONTENT_TYPE = "1.2.840.113549.1.9.3";
+const OID_MESSAGE_DIGEST = "1.2.840.113549.1.9.4";
+const OID_SIGNING_TIME = "1.2.840.113549.1.9.5";
+const toArrayBuffer = (u) => u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+function ensureEngine() {
+    pkijs.setEngine("kya-sign", new pkijs.CryptoEngine({ name: "kya-sign", crypto: globalThis.crypto }));
+}
+/**
+ * Detached CMS/PKCS#7 SignedData (base64 DER) over `text`, with signed attributes (content type, message
+ * digest, signing time) and the given certificates (signer first, then its chain, DER). The issuer accepts it as
+ * `ecnpj_signature`.
+ */
+export async function buildDetachedCms(p) {
+    ensureEngine();
+    if (!p.certificates.length)
+        throw new KyaError("INVALID_INPUT", "no signer certificate");
+    const certs = p.certificates.map((der) => pkijs.Certificate.fromBER(toArrayBuffer(der)));
+    const leaf = certs[0];
+    const content = new TextEncoder().encode(p.text);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", content));
+    const signedAttrs = new pkijs.SignedAndUnsignedAttributes({
+        type: 0,
+        attributes: [
+            new pkijs.Attribute({ type: OID_CONTENT_TYPE, values: [new asn1js.ObjectIdentifier({ value: OID_DATA })] }),
+            new pkijs.Attribute({ type: OID_MESSAGE_DIGEST, values: [new asn1js.OctetString({ valueHex: toArrayBuffer(digest) })] }),
+            new pkijs.Attribute({ type: OID_SIGNING_TIME, values: [new asn1js.UTCTime({ valueDate: p.signingTime ?? new Date() })] })
+        ]
+    });
+    // What is signed is the DER of the attributes as a SET (tag 0x31), not the [0] IMPLICIT form they travel in.
+    const toBeSigned = new Uint8Array(signedAttrs.toSchema().toBER(false));
+    toBeSigned[0] = 0x31;
+    const signature = await p.sign(toBeSigned);
+    const signerInfo = new pkijs.SignerInfo({
+        version: 1,
+        sid: new pkijs.IssuerAndSerialNumber({ issuer: leaf.issuer, serialNumber: leaf.serialNumber }),
+        digestAlgorithm: new pkijs.AlgorithmIdentifier({ algorithmId: OID_SHA256 }),
+        signedAttrs,
+        signatureAlgorithm: new pkijs.AlgorithmIdentifier({ algorithmId: OID_SHA256_RSA }),
+        signature: new asn1js.OctetString({ valueHex: toArrayBuffer(signature) })
+    });
+    const signed = new pkijs.SignedData({
+        version: 1,
+        digestAlgorithms: [new pkijs.AlgorithmIdentifier({ algorithmId: OID_SHA256 })],
+        encapContentInfo: new pkijs.EncapsulatedContentInfo({ eContentType: OID_DATA }),
+        certificates: certs,
+        signerInfos: [signerInfo]
+    });
+    const ci = new pkijs.ContentInfo({ contentType: OID_SIGNED_DATA, content: signed.toSchema(true) });
+    const der = new Uint8Array(ci.toSchema().toBER(false));
+    let bin = "";
+    for (const b of der)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+/** CNPJ in a common name ending in ":<14 digits>", the ICP-Brasil convention for e-CNPJ. */
+export const cnpjFromCommonName = (cn) => /:(\d{14})\s*$/.exec(cn)?.[1] ?? null;
+/** Wraps a raw signer and its certificates into an ECnpjSigner (used for A1 files, tokens, HSMs, cloud). */
+export function ecnpjSigner(p) {
+    const leaf = forge.pki.certificateFromAsn1(forge.asn1.fromDer(forge.util.binary.raw.encode(p.certificates[0])));
+    const cn = String(leaf.subject.getField("CN")?.value ?? "");
+    const cnpj = cnpjFromCommonName(cn);
+    return {
+        subject: leaf.subject.attributes.map((a) => `${a.shortName ?? a.name}=${a.value}`).join(", "),
+        cnpj,
+        notAfter: leaf.validity.notAfter,
+        certificates: p.certificates,
+        async sign(text) {
+            const asked = /^cnpj: (\d{14})$/m.exec(text)?.[1];
+            if (asked && cnpj && asked !== cnpj)
+                throw new KyaError("CNPJ_MISMATCH", `this certificate is for CNPJ ${cnpj}, the text is for ${asked}`);
+            return buildDetachedCms({ text, certificates: p.certificates, sign: p.sign });
+        }
+    };
+}
+const certDer = (c) => new Uint8Array(forge.util.binary.raw.decode(forge.asn1.toDer(forge.pki.certificateToAsn1(c)).getBytes()));
+/** Opens an A1 e-CNPJ file (.pfx / .p12 bytes) with its password. The key stays in memory, inside Web Crypto. */
+export async 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 KyaError("INVALID_INPUT", `could not open the certificate file (wrong password or not a .pfx/.p12): ${e.message}`);
+    }
+    const oids = forge.pki.oids;
+    const keyBag = [oids.pkcs8ShroudedKeyBag, oids.keyBag].flatMap((t) => p12.getBags({ bagType: t })[t] ?? []).find((b) => b.key);
+    if (!keyBag?.key)
+        throw new KyaError("INVALID_INPUT", "the certificate file has no private key");
+    const key = keyBag.key;
+    const certs = (p12.getBags({ bagType: oids.certBag })[oids.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 KyaError("INVALID_INPUT", "no certificate in the file matches its private key");
+    const pkcs8 = forge.util.binary.raw.decode(forge.asn1.toDer(forge.pki.wrapRsaPrivateKey(forge.pki.privateKeyToAsn1(key))).getBytes());
+    const cryptoKey = await crypto.subtle.importKey("pkcs8", toArrayBuffer(pkcs8), { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
+    return ecnpjSigner({
+        certificates: [leaf, ...certs.filter((c) => c !== leaf)].map(certDer),
+        sign: async (data) => new Uint8Array(await crypto.subtle.sign({ name: "RSASSA-PKCS1-v1_5" }, cryptoKey, toArrayBuffer(data)))
+    });
+}
+/** One call: sign `text` with the e-CNPJ in an A1 file. Returns the base64 DER the issuer expects as ecnpj_signature. */
+export async function signWithECnpjPfx(pfx, password, text) {
+    return (await openPfx(pfx, password)).sign(text);
+}
+/**
+ * Link to an issuer's signing page (<issuer>/sign) for the person who holds the company's e-CNPJ. The agent
+ * registers, signs its half and sends this link; the person sees what they authorize and signs in the browser.
+ */
+export function signingLink(p) {
+    const u = new URL("/sign", p.issuer);
+    u.searchParams.set("id", p.credentialId);
+    u.searchParams.set("challenge_id", p.challenge.id);
+    let bin = "";
+    for (const b of new TextEncoder().encode(p.challenge.text))
+        bin += String.fromCharCode(b);
+    u.searchParams.set("text", btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""));
+    if (p.agentSignature)
+        u.searchParams.set("agent_signature", p.agentSignature);
+    return u.toString();
+}
+/** The challenge text carried by a signing link (inverse of signingLink), with its ids. */
+export function readSigningLink(link) {
+    const u = new URL(link);
+    const t = u.searchParams.get("text");
+    if (!t)
+        throw new KyaError("INVALID_INPUT", "the signing link has no text");
+    const bin = atob(t.replace(/-/g, "+").replace(/_/g, "/"));
+    return {
+        issuer: u.origin,
+        credentialId: u.searchParams.get("id"),
+        challengeId: u.searchParams.get("challenge_id"),
+        agentSignature: u.searchParams.get("agent_signature"),
+        text: new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)))
+    };
+}

package/dist/icp-brasil.js

@@ -87,6 +87,15 @@ export async function verifyIcpSignature(p) {
         throw new KyaError("CERTIFICATE_INVALID", "CMS carries no signer certificate");
     const trusted = p.anchors.map((a) => pkijs.Certificate.fromBER(unb64(a.replace(/-----[^-]+-----/g, ""))));
     const data = new TextEncoder().encode(p.challenge);
+    // An attached CMS (the .p7s carries the signed text) is verified over its own content by pkijs, whatever
+    // `data` says: it MUST carry exactly the challenge, or any document the company ever signed would pass.
+    const embedded = signed.encapContentInfo.eContent;
+    if (embedded) {
+        const content = new Uint8Array(embedded.getValue());
+        if (content.length !== data.length || !content.every((b, i) => b === data[i])) {
+            throw new KyaError("CHALLENGE_FAILED", "the signed content is not the challenge text (sign exactly the challenge, without extra line breaks)");
+        }
+    }
     let ok = false;
     try {
         ok = await signed.verify({ signer: 0, data: data.buffer, trustedCerts: trusted, checkChain: false, checkDate: now });

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export * from "./credential.js";
 export * from "./icp-brasil.js";
 export * from "./revocation.js";
 export * from "./erc8004.js";
+export * from "./ecnpj-sign.js";

package/dist/index.js

@@ -7,3 +7,4 @@ export * from "./credential.js";
 export * from "./icp-brasil.js";
 export * from "./revocation.js";
 export * from "./erc8004.js";
+export * from "./ecnpj-sign.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kya-brasil/core",
-  "version": "0.7.0",
-  "description": "KYA Brasil as a library: verify and issue know-your-agent credentials for Brazilian companies without any hosted service. e-CNPJ (ICP-Brasil) CMS signature and chain validation, CRL revocation, CNPJ, agent key challenges (EVM, Ed25519 / Web Bot Auth, ERC-8004), mandate schema and evaluation (including payment instruments for card networks and acquirers), credential build, Ed25519 signing and verification. Pure functions: storage and network are yours.",
+  "version": "0.8.0",
+  "description": "KYA Brasil as a library: verify and issue know-your-agent credentials for Brazilian companies without any hosted service. e-CNPJ (ICP-Brasil) CMS signature and chain validation, CRL revocation, CNPJ, agent key challenges (EVM, Ed25519 / Web Bot Auth, ERC-8004), mandate schema and evaluation (including payment instruments for card networks and acquirers), credential build, Ed25519 signing and verification, and e-CNPJ signing for the holder (A1 .pfx, or any token/HSM/cloud signer through a raw-sign callback). Pure functions: storage and network are yours.",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -57,12 +57,14 @@
     "@peculiar/asn1-x509": "^2.3.15",
     "@peculiar/x509": "^2.1.0",
     "asn1js": "^3.0.6",
+    "node-forge": "1.4.0",
     "pkijs": "^3.4.1",
     "reflect-metadata": "^0.2.2",
     "viem": "^2.57.5"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
+    "@types/node-forge": "^1.3.14",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
   },