@kya-brasil/core 0.7.1 → 0.9.0

package/README.md

@@ -66,6 +66,43 @@ 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`.
+
+### Cloud certificates (PSC)
+
+`CloudSignatureProvider` is the interface for an e-CNPJ held by an ICP-Brasil PSC: `authorizationUrl` (OAuth with
+PKCE), `exchangeCode` returning a session with `certificates()` and `signHash(sha256)`. No PSC is implemented here
+(each has its own contract); implement it for yours from
+[examples/cloud-provider](https://github.com/celfons/kya-brasil/tree/main/examples/cloud-provider) and then:
+
+```ts
+import { cloudSigner, pkcePair, newState } from "@kya-brasil/core";
+const { verifier, challenge } = await pkcePair();
+const url = await provider.authorizationUrl({ redirectUri, state: newState(), codeChallenge: challenge });
+// … the person approves, your redirect URI gets ?code=…&state=…
+const signer = await cloudSigner(await provider.exchangeCode({ code, redirectUri, codeVerifier: verifier }));
+const ecnpj_signature = await signer.sign(challengeText);
+```
+
 ## Run your own issuer
 
 ```ts

package/dist/cloud-sign.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cloud e-CNPJ (D-28): the certificate lives at an ICP-Brasil PSC (prestador de serviço de confiança) and signs
+ * after the holder approves, usually on the phone. Each PSC has its own contract, registration and API details,
+ * so this project ships the interface only: whoever has an agreement with a PSC implements CloudSignatureProvider
+ * for it and plugs it into the three entry points (this library, `kya-sign --cloud`, the /sign page of a
+ * self-hosted issuer). The KYA side (PKCE, single-use state, the CMS, what is signed) is done here.
+ *
+ * Typical PSC flow (OAuth 2.0 authorization code with PKCE): send the person to authorizationUrl, get a code at
+ * the redirect URI, exchange it for a session, read the certificate, sign hashes. Ask the PSC for the narrowest
+ * session it offers (one signature, minutes of lifetime).
+ */
+import { type ECnpjSigner } from "./ecnpj-sign.js";
+/** An authorized session at the PSC: the certificate and a way to sign one SHA-256 hash. */
+export interface CloudSession {
+    /** Signer certificate first, then the chain if the PSC returns it (DER). */
+    certificates(): Promise<Uint8Array[]>;
+    /**
+     * RSA PKCS#1 v1.5 signature over a SHA-256 hash (32 bytes) computed by the caller: what PSC APIs usually
+     * call a "raw" or "PKCS1" signature of a hash. Return the signature bytes.
+     */
+    signHash(sha256: Uint8Array): Promise<Uint8Array>;
+    /** Revoke or forget the session at the PSC, when it supports it. */
+    close?(): Promise<void>;
+}
+/** One PSC. Implement it with your own registration (client id/secret, redirect URIs) and the PSC's API. */
+export interface CloudSignatureProvider {
+    /** Short id used in URLs and on the command line, e.g. "my-psc". Lowercase letters, digits, "-". */
+    readonly id: string;
+    /** Name shown to the person, e.g. "BirdID", "VIDaaS". */
+    readonly name: string;
+    /**
+     * Where to send the person to log in and approve. Must carry `state` and the PKCE `codeChallenge` (S256) so the
+     * code comes back to `redirectUri` bound to this request. `loginHint` may carry a CNPJ/CPF when the PSC accepts it.
+     */
+    authorizationUrl(p: {
+        redirectUri: string;
+        state: string;
+        codeChallenge: string;
+        loginHint?: string;
+    }): string | Promise<string>;
+    /** Exchanges the code for a session (server or CLI side: this is where a client secret would be used). */
+    exchangeCode(p: {
+        code: string;
+        redirectUri: string;
+        codeVerifier: string;
+    }): Promise<CloudSession>;
+}
+/** PKCE (RFC 7636, S256): a random verifier kept by us and the challenge sent to the PSC. */
+export declare function pkcePair(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+/** A random, single-use OAuth state value. */
+export declare const newState: () => string;
+/** Valid provider ids: what can safely go in a URL path or a CLI flag. */
+export declare const isProviderId: (id: string) => boolean;
+/**
+ * An e-CNPJ signer over a PSC session: the CMS is built here, the PSC only signs the SHA-256 of the signed
+ * attributes. Same interface as openPfx (A1) and openToken (A3), so everything downstream is unchanged.
+ */
+export declare function cloudSigner(session: CloudSession): Promise<ECnpjSigner>;

package/dist/cloud-sign.js

@@ -0,0 +1,49 @@
+/**
+ * Cloud e-CNPJ (D-28): the certificate lives at an ICP-Brasil PSC (prestador de serviço de confiança) and signs
+ * after the holder approves, usually on the phone. Each PSC has its own contract, registration and API details,
+ * so this project ships the interface only: whoever has an agreement with a PSC implements CloudSignatureProvider
+ * for it and plugs it into the three entry points (this library, `kya-sign --cloud`, the /sign page of a
+ * self-hosted issuer). The KYA side (PKCE, single-use state, the CMS, what is signed) is done here.
+ *
+ * Typical PSC flow (OAuth 2.0 authorization code with PKCE): send the person to authorizationUrl, get a code at
+ * the redirect URI, exchange it for a session, read the certificate, sign hashes. Ask the PSC for the narrowest
+ * session it offers (one signature, minutes of lifetime).
+ */
+import { ecnpjSigner } from "./ecnpj-sign.js";
+import { KyaError } from "./types.js";
+const toArrayBuffer = (u) => u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
+const b64url = (u) => {
+    let s = "";
+    for (const b of u)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+/** PKCE (RFC 7636, S256): a random verifier kept by us and the challenge sent to the PSC. */
+export async function pkcePair() {
+    const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
+    const challenge = b64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+    return { verifier, challenge };
+}
+/** A random, single-use OAuth state value. */
+export const newState = () => b64url(crypto.getRandomValues(new Uint8Array(24)));
+/** Valid provider ids: what can safely go in a URL path or a CLI flag. */
+export const isProviderId = (id) => /^[a-z0-9][a-z0-9-]{0,31}$/.test(id);
+/**
+ * An e-CNPJ signer over a PSC session: the CMS is built here, the PSC only signs the SHA-256 of the signed
+ * attributes. Same interface as openPfx (A1) and openToken (A3), so everything downstream is unchanged.
+ */
+export async function cloudSigner(session) {
+    const certificates = await session.certificates();
+    if (!certificates.length)
+        throw new KyaError("CERTIFICATE_INVALID", "the cloud provider returned no certificate");
+    return ecnpjSigner({
+        certificates,
+        sign: async (data) => {
+            const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", toArrayBuffer(data)));
+            const sig = await session.signHash(hash);
+            if (!sig?.length)
+                throw new KyaError("UPSTREAM_ERROR", "the cloud provider returned an empty signature");
+            return sig;
+        }
+    });
+}

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/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kya-brasil/core",
-  "version": "0.7.1",
-  "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.9.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"
   },