@kya-brasil/core 0.18.0 → 0.19.0

package/README.md

@@ -106,6 +106,23 @@ mandate's `valid_until` nor the certificate's end of validity. To revoke before
 certificate or issues mandates with short lifetimes; there is no status service to ask. The certificate signer
 stays outside the core: an A3 token (PKCS#11 and PIN) is `openToken` in `@kya-brasil/agent-tools`.
 
+**Co-signature by a legal representative (SPEC section 21).** Holding the company's e-CNPJ does not make someone its
+representative. A self-issued company credential may carry co-signatures by e-CPF over the same text; the verifier
+supplies the representatives (the QSA, from its own source) and the core counts them:
+
+```ts
+import { addCosignature, verifyCompanyWill } from "@kya-brasil/core";
+
+const repCms = await representativeSigner.sign(proof.text);                 // e-CPF, the SAME text
+const cosigned = await addCosignature({ credential, proof }, repCms, [], { anchors: icpBrasilAnchors, now: new Date() });
+const will = await verifyCompanyWill(cosigned, { anchors: icpBrasilAnchors, now: new Date(), representatives: (cnpj) => qsaCpfs(cnpj), minCosigners: 1 });
+// will.ok, or will.code: NO_COSIGNATURE | COSIGNER_NOT_REPRESENTATIVE | COSIGNATURE_TEXT_MISMATCH |
+// COSIGNER_CERTIFICATE_INVALID | COSIGNATURE_NOT_RECORDED | INSUFFICIENT_COSIGNERS | COMPANY_SIGNATURE_INVALID
+```
+
+The credential records only the e-CPF certificate's hash, issuer and dates; the CMS (which carries the certificate,
+and so the CPF) travels in the proof (`proof.cosignatures`, also in `KYA-Principal-Proof`). The result has no CPF.
+
 Delegation, issued by the parent agent with its own key:
 
 ```ts

package/dist/cosign.d.ts

@@ -0,0 +1,50 @@
+import { type IssuedCredential } from "./issuance.js";
+/**
+ * Adds a legal representative's co-signature to a self-issued company credential: `cms` is a CMS by an e-CPF over
+ * `issued.proof.text` (the same bytes the e-CNPJ signed), `certChain` the chain to add when the CMS lacks it.
+ * Verifies the signature, the certificate's dates and chain up to `anchors`, and refuses an e-CNPJ, another text,
+ * a non-company or non-self-issued credential, and a certificate that already co-signed. Returns a new
+ * IssuedCredential: the credential gains a `cosignatures` entry (hash, issuer, dates; no CPF), the proof the CMS.
+ * Throws KyaError (INVALID_INPUT, CHALLENGE_FAILED, CERTIFICATE_INVALID).
+ */
+export declare function addCosignature(issued: IssuedCredential, cms: string, certChain: (Uint8Array | string)[], opts: {
+    anchors: string[];
+    now: Date;
+}): Promise<IssuedCredential>;
+export type CompanyWillCode = "COMPANY_SIGNATURE_INVALID" | "NO_COSIGNATURE" | "COSIGNATURE_TEXT_MISMATCH" | "COSIGNER_CERTIFICATE_INVALID" | "COSIGNATURE_NOT_RECORDED" | "COSIGNER_NOT_REPRESENTATIVE" | "INSUFFICIENT_COSIGNERS";
+export interface CosignerCheck {
+    /** Hash of the co-signer's e-CPF certificate (null when the CMS did not verify). Never the CPF. */
+    certificate_sha256: string | null;
+    ok: boolean;
+    representative: boolean;
+    code?: CompanyWillCode;
+    detail: string;
+    /** For the caller's revocation check of the e-CPF certificate (checkRevocation); null when it did not verify. */
+    revocation: {
+        serial_number: string;
+        issuer_certificate: string | null;
+        crl_urls: string[];
+    } | null;
+}
+export interface CompanyWillResult {
+    ok: boolean;
+    /** Why it was refused; absent when accepted. */
+    code?: CompanyWillCode;
+    detail: string;
+    /** Distinct representatives whose valid co-signature was counted. */
+    representatives_counted: number;
+    cosigners: CosignerCheck[];
+}
+/**
+ * Whether a self-issued company credential expresses the company's will: the e-CNPJ proof verifies
+ * (verifySelfIssuedCredential) AND at least `minCosigners` (default 1) distinct CPFs, read from valid e-CPF
+ * co-signatures over the same text, are among `representatives(cnpj)` (the verifier's QSA list). Every co-signature
+ * in the proof must be recorded in the credential (by certificate hash) and vice versa. Never throws on a bad
+ * credential; the result carries no CPF. Revocation of the e-CPF certificates is the caller's (`revocation`).
+ */
+export declare function verifyCompanyWill(issued: IssuedCredential, opts: {
+    anchors: string[];
+    now: Date;
+    representatives: (cnpj: string) => Promise<string[]> | string[];
+    minCosigners?: number;
+}): Promise<CompanyWillResult>;

package/dist/cosign.js

@@ -0,0 +1,117 @@
+/**
+ * Co-signature by a legal representative (SPEC section 21). Whoever holds a company's e-CNPJ can sign a mandate,
+ * whether or not they represent the company (shown by the Alloy model). A self-issued company credential may
+ * therefore carry co-signatures: CMS signatures by e-CPF over the SAME text the e-CNPJ signed
+ * (mandateSigningInput). The verifier supplies who represents the company (the QSA, from its own source): the core
+ * never calls the Receita Federal.
+ *
+ * Privacy (SPEC section 12): the credential keeps only, per co-signature, the e-CPF certificate's hash, issuer and
+ * dates. The CMS (which carries the certificate, and so the CPF and name) travels in the proof the agent presents,
+ * as the principal's own CMS does (section 19); the CPF is read from it at verification and never returned.
+ *
+ * Pure: no network, no storage, the clock is the caller's.
+ */
+import { normalizeCnpj } from "./cnpj.js";
+import { verifyIcpPersonSignature } from "./icp-brasil.js";
+import { SELF_ISSUER, verifySelfIssuedCredential, withCertificates } from "./issuance.js";
+import { KyaError, isPersonPrincipal } from "./types.js";
+const bad = (why) => new KyaError("INVALID_INPUT", why);
+const validDate = (d) => d instanceof Date && !Number.isNaN(d.getTime());
+/**
+ * Adds a legal representative's co-signature to a self-issued company credential: `cms` is a CMS by an e-CPF over
+ * `issued.proof.text` (the same bytes the e-CNPJ signed), `certChain` the chain to add when the CMS lacks it.
+ * Verifies the signature, the certificate's dates and chain up to `anchors`, and refuses an e-CNPJ, another text,
+ * a non-company or non-self-issued credential, and a certificate that already co-signed. Returns a new
+ * IssuedCredential: the credential gains a `cosignatures` entry (hash, issuer, dates; no CPF), the proof the CMS.
+ * Throws KyaError (INVALID_INPUT, CHALLENGE_FAILED, CERTIFICATE_INVALID).
+ */
+export async function addCosignature(issued, cms, certChain, opts) {
+    if (!issued?.credential || !issued.proof || typeof issued.proof.text !== "string")
+        throw bad("issued: { credential, proof } from assembleCredential is required");
+    const c = issued.credential;
+    if (c.issuer !== SELF_ISSUER)
+        throw bad(`only a self-issued credential (${SELF_ISSUER}) takes co-signatures`);
+    if (!c.principal || isPersonPrincipal(c.principal))
+        throw bad("only a company credential takes co-signatures of its legal representatives");
+    if (!validDate(opts?.now))
+        throw bad("opts.now must be a valid Date (the clock is the caller's)");
+    if (!Array.isArray(opts.anchors) || !opts.anchors.length)
+        throw bad("opts.anchors: the ICP-Brasil trust anchors are required");
+    if (typeof cms !== "string" || !cms.trim())
+        throw bad("cms: the co-signature (base64 DER) is required");
+    if (!Array.isArray(certChain))
+        throw bad("certChain must be an array; [] when the CMS already carries it");
+    const full = withCertificates(cms, certChain);
+    const icp = await verifyIcpPersonSignature({ cmsBase64: full, challenge: issued.proof.text, anchors: opts.anchors, now: opts.now });
+    const existing = c.cosignatures ?? [];
+    if (existing.some((x) => x.certificate_sha256 === icp.certificate_sha256))
+        throw new KyaError("CONFLICT", "this e-CPF certificate already co-signed the credential");
+    const entry = { method: "icp-brasil-e-cpf", certificate_sha256: icp.certificate_sha256, issuer: icp.issuer, signed_at: opts.now.toISOString(), not_after: icp.not_after };
+    return {
+        credential: { ...c, cosignatures: [...existing, entry] },
+        proof: { ...issued.proof, cosignatures: [...(issued.proof.cosignatures ?? []), full] }
+    };
+}
+/**
+ * Whether a self-issued company credential expresses the company's will: the e-CNPJ proof verifies
+ * (verifySelfIssuedCredential) AND at least `minCosigners` (default 1) distinct CPFs, read from valid e-CPF
+ * co-signatures over the same text, are among `representatives(cnpj)` (the verifier's QSA list). Every co-signature
+ * in the proof must be recorded in the credential (by certificate hash) and vice versa. Never throws on a bad
+ * credential; the result carries no CPF. Revocation of the e-CPF certificates is the caller's (`revocation`).
+ */
+export async function verifyCompanyWill(issued, opts) {
+    const refuse = (code, detail, cosigners = [], counted = 0) => ({ ok: false, code, detail, representatives_counted: counted, cosigners });
+    const min = opts?.minCosigners ?? 1;
+    if (!Number.isInteger(min) || min < 1)
+        throw bad("minCosigners must be an integer >= 1");
+    if (typeof opts?.representatives !== "function")
+        throw bad("representatives: (cnpj) => CPFs of the company's legal representatives is required");
+    const c = issued?.credential;
+    if (!c?.principal || isPersonPrincipal(c.principal))
+        return refuse("COMPANY_SIGNATURE_INVALID", "not a company credential");
+    const base = await verifySelfIssuedCredential({ credential: c, proof: issued.proof, anchors: opts.anchors, now: opts.now });
+    if (!base.ok)
+        return refuse("COMPANY_SIGNATURE_INVALID", base.checks.filter((x) => !x.ok).map((x) => `${x.rule}: ${x.detail}`).join("; "));
+    const cmsList = issued.proof.cosignatures ?? [];
+    const recorded = c.cosignatures ?? [];
+    if (!cmsList.length && !recorded.length)
+        return refuse("NO_COSIGNATURE", "the credential carries no co-signature by a legal representative (e-CPF)");
+    const cnpj = normalizeCnpj(c.principal.cnpj);
+    const reps = new Set((await opts.representatives(cnpj)).map((x) => String(x).replace(/\D/g, "")));
+    const cosigners = [];
+    const counted = new Set();
+    const seenCerts = new Set();
+    for (const cms of cmsList) {
+        try {
+            const icp = await verifyIcpPersonSignature({ cmsBase64: cms, challenge: issued.proof.text, anchors: opts.anchors, now: opts.now });
+            const revocation = { serial_number: icp.serial_number, issuer_certificate: icp.issuer_certificate, crl_urls: icp.crl_urls };
+            seenCerts.add(icp.certificate_sha256);
+            if (!recorded.some((r) => r.certificate_sha256 === icp.certificate_sha256)) {
+                cosigners.push({ certificate_sha256: icp.certificate_sha256, ok: false, representative: false, code: "COSIGNATURE_NOT_RECORDED", detail: "the credential does not record this co-signer's certificate", revocation });
+                continue;
+            }
+            const isRep = reps.has(icp.cpf);
+            if (isRep)
+                counted.add(icp.cpf);
+            cosigners.push({ certificate_sha256: icp.certificate_sha256, ok: isRep, representative: isRep, ...(isRep ? {} : { code: "COSIGNER_NOT_REPRESENTATIVE" }), detail: isRep ? "valid co-signature by a legal representative" : `the co-signer is not a legal representative of CNPJ ${cnpj}`, revocation });
+        }
+        catch (e) {
+            const k = e instanceof KyaError ? e.code : "CHALLENGE_FAILED";
+            const code = k === "CERTIFICATE_INVALID" ? "COSIGNER_CERTIFICATE_INVALID" : "COSIGNATURE_TEXT_MISMATCH";
+            cosigners.push({ certificate_sha256: null, ok: false, representative: false, code, detail: e.message, revocation: null });
+        }
+    }
+    for (const r of recorded) {
+        if (!seenCerts.has(r.certificate_sha256))
+            cosigners.push({ certificate_sha256: r.certificate_sha256, ok: false, representative: false, code: "COSIGNATURE_NOT_RECORDED", detail: "the credential records a co-signature the proof does not carry (or it did not verify)", revocation: null });
+    }
+    // A tampered or unmatched record is a refusal on its own: nothing about the cosignatures may be inconsistent.
+    const broken = cosigners.find((x) => x.code && x.code !== "COSIGNER_NOT_REPRESENTATIVE");
+    if (broken)
+        return refuse(broken.code, broken.detail, cosigners, counted.size);
+    if (counted.size >= min)
+        return { ok: true, detail: `${counted.size} legal representative(s) co-signed`, representatives_counted: counted.size, cosigners };
+    if (counted.size === 0)
+        return refuse("COSIGNER_NOT_REPRESENTATIVE", `no co-signer is a legal representative of CNPJ ${cnpj}`, cosigners, 0);
+    return refuse("INSUFFICIENT_COSIGNERS", `${counted.size} of ${min} required legal representatives co-signed`, cosigners, counted.size);
+}

package/dist/index.d.ts

@@ -14,3 +14,4 @@ export * from "./delegation.js";
 export * from "./freshness.js";
 export * from "./principal-proof.js";
 export * from "./issuance.js";
+export * from "./cosign.js";

package/dist/index.js

@@ -14,3 +14,4 @@ export * from "./delegation.js";
 export * from "./freshness.js";
 export * from "./principal-proof.js";
 export * from "./issuance.js";
+export * from "./cosign.js";

package/dist/principal-proof.d.ts

@@ -3,6 +3,12 @@ import { type Credential } from "./types.js";
 export interface PrincipalProof {
     text: string;
     cms: string;
+    /**
+     * Co-signatures by legal representatives (SPEC section 21): CMS by e-CPF over the same `text`. Optional, additive.
+     * They carry the representatives' certificates (and so their CPF): presented to the verifier, never stored in the
+     * credential.
+     */
+    cosignatures?: string[];
 }
 export interface PrincipalProofCheck {
     rule: "signature" | "certificate" | "agent" | "principal" | "issuer" | "mandate";

package/dist/principal-proof.js

@@ -79,7 +79,7 @@ export async function verifyPrincipalProof(p) {
 }
 /** Header value for a request: base64url of the JSON { text, cms }. */
 export function encodePrincipalProofHeader(proof) {
-    return base64url.encode(new TextEncoder().encode(JSON.stringify({ text: proof.text, cms: proof.cms })));
+    return base64url.encode(new TextEncoder().encode(JSON.stringify(proof.cosignatures?.length ? { text: proof.text, cms: proof.cms, cosignatures: proof.cosignatures } : { text: proof.text, cms: proof.cms })));
 }
 /** Parses the header value; throws INVALID_INPUT when it is not a proof. */
 export function decodePrincipalProofHeader(value) {
@@ -93,5 +93,9 @@ export function decodePrincipalProofHeader(value) {
     const o = parsed;
     if (!o || typeof o.text !== "string" || typeof o.cms !== "string")
         throw new KyaError("INVALID_INPUT", "KYA-Principal-Proof must carry text and cms");
-    return { text: o.text, cms: o.cms };
+    if (o.cosignatures === undefined)
+        return { text: o.text, cms: o.cms };
+    if (!Array.isArray(o.cosignatures) || !o.cosignatures.every((c) => typeof c === "string"))
+        throw new KyaError("INVALID_INPUT", "KYA-Principal-Proof cosignatures must be a list of base64 CMS");
+    return { text: o.text, cms: o.cms, cosignatures: o.cosignatures };
 }

package/dist/types.d.ts

@@ -121,6 +121,19 @@ export interface Credential {
     verify_url: string;
     revocation_url: string;
     attestation?: Attestation;
+    /**
+     * Co-signatures of a self-issued company credential by legal representatives (SPEC section 21, additive): which
+     * e-CPF certificates co-signed the same text, by hash. No CPF, no name: the CMS travel in the proof.
+     */
+    cosignatures?: Cosignature[];
+}
+/** A legal representative's co-signature as the credential records it: no personal data. */
+export interface Cosignature {
+    method: "icp-brasil-e-cpf";
+    certificate_sha256: string;
+    issuer: string;
+    signed_at: string;
+    not_after: string;
 }
 export declare class KyaError extends Error {
     code: "INVALID_INPUT" | "INVALID_CNPJ" | "NOT_FOUND" | "CHALLENGE_FAILED" | "CERTIFICATE_INVALID" | "CNPJ_MISMATCH" | "KYB_BLOCKED" | "KYB_UNAVAILABLE" | "CERTIFICATE_REVOKED" | "REVOCATION_UNAVAILABLE" | "REGISTRY_UNAVAILABLE" | "RATE_LIMITED" | "UPSTREAM_ERROR" | "CONFLICT";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/core",
-  "version": "0.18.0",
+  "version": "0.19.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, issuance by the principal itself (build the mandate, the exact bytes to sign, assemble and verify, no issuer service), 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",