@kya-brasil/core 0.14.0 → 0.15.0

package/README.md

@@ -46,6 +46,25 @@ const verdict = checkAction(credential.mandate, {
 // verdict.allowed, verdict.checks (every rule evaluated, with its reason), verdict.not_evaluated (extensions)
 ```
 
+## Without trusting the issuer
+
+Since D-33 the e-CNPJ / e-CPF signs the agent and the mandate's hash, and the principal keeps the signed text and the
+`.p7s`. When the principal hands them to its agent, you can check the authorization against ICP-Brasil alone (SPEC
+section 19), and the issuer's key vouches only for the credential's status:
+
+```ts
+import { decodePrincipalProofHeader, verifyPrincipalProof, checkRevocation } from "@kya-brasil/core";
+
+const proof = decodePrincipalProofHeader(request.headers.get("KYA-Principal-Proof")!);
+const r = await verifyPrincipalProof({ credential, proof, anchors: icpBrasilAnchors, now: trustedClock() });
+// r.ok; r.checks: signature, certificate, agent, principal, issuer, mandate (each with its reason)
+// then the certificate's revocation, with a CRL you fetched from r.revocation.crl_urls:
+// await checkRevocation({ crlDer, serial: r.revocation!.serial_number, issuerCertificate: r.revocation!.issuer_certificate!, pastNextUpdate: "refuse" })
+```
+
+The CMS carries the signer's certificate (personal data): the principal decides when to share it, and you use it for
+this check only. The result carries nothing personal.
+
 ## Delegation chains (sub-agents)
 
 A mandate with `delegation: { max_depth, max_ttl_seconds }` lets the agent hand a narrower mandate to another key

package/dist/index.d.ts

@@ -12,3 +12,4 @@ export * from "./cloud-sign.js";
 export * from "./person.js";
 export * from "./delegation.js";
 export * from "./freshness.js";
+export * from "./principal-proof.js";

package/dist/index.js

@@ -12,3 +12,4 @@ export * from "./cloud-sign.js";
 export * from "./person.js";
 export * from "./delegation.js";
 export * from "./freshness.js";
+export * from "./principal-proof.js";

package/dist/principal-proof.d.ts

@@ -0,0 +1,38 @@
+import { type Credential } from "./types.js";
+/** What the agent presents: the exact challenge text the principal signed, and the detached CMS (base64 DER). */
+export interface PrincipalProof {
+    text: string;
+    cms: string;
+}
+export interface PrincipalProofCheck {
+    rule: "signature" | "certificate" | "agent" | "principal" | "issuer" | "mandate";
+    ok: boolean;
+    detail: string;
+}
+export interface PrincipalProofResult {
+    ok: boolean;
+    checks: PrincipalProofCheck[];
+    /** For the caller's revocation check of the signing certificate; null when the signature did not verify. */
+    revocation: {
+        serial_number: string;
+        issuer_certificate: string | null;
+        crl_urls: string[];
+    } | null;
+}
+/**
+ * Checks, against the credential and without the issuer, that the principal's own signature authorizes this
+ * agent with this mandate: the CMS verifies over the text up to the ICP-Brasil anchors; the certificate is the
+ * one the credential records; the text names the credential's agent, principal and issuer; and the mandate hash
+ * in the text equals the hash of the credential's mandate. `anchors`, `now` and the revocation check are the
+ * caller's. Never throws on a bad proof: every check is reported.
+ */
+export declare function verifyPrincipalProof(p: {
+    credential: Pick<Credential, "agent" | "principal" | "authorized_by" | "mandate" | "issuer">;
+    proof: PrincipalProof;
+    anchors: string[];
+    now: Date;
+}): Promise<PrincipalProofResult>;
+/** Header value for a request: base64url of the JSON { text, cms }. */
+export declare function encodePrincipalProofHeader(proof: PrincipalProof): string;
+/** Parses the header value; throws INVALID_INPUT when it is not a proof. */
+export declare function decodePrincipalProofHeader(value: string): PrincipalProof;

package/dist/principal-proof.js

@@ -0,0 +1,97 @@
+/**
+ * Verification without trusting the issuer (D-34, SPEC section 19).
+ *
+ * Since D-33 the principal signs, with the e-CNPJ or e-CPF, a challenge that names the agent and carries the
+ * mandate's SHA-256, and keeps the signed text and the detached CMS (.p7s). When the principal chooses to hand
+ * them to its agent, the agent can present them with a request, and any verifier can check by itself, with the
+ * ICP-Brasil trust anchors, that this principal authorized this agent with these powers: the issuer's key is
+ * then needed for nothing but the credential's status.
+ *
+ * Pure functions, no network. The certificate's revocation is the caller's: this module returns what is needed
+ * to fetch and check the CRL (checkRevocation, evidenceFromRevocation), never personal data. The CMS carries the
+ * signer's certificate, so the principal decides when to share it, and the verifier treats it as personal data.
+ */
+import { base64url, mandateSha256OfChallenge } from "./challenge.js";
+import { mandateSha256 } from "./credential.js";
+import { verifyIcpPersonSignature, verifyIcpSignature } from "./icp-brasil.js";
+import { KyaError, isPersonPrincipal } from "./types.js";
+const lineOf = (text, key) => {
+    const lines = text.split("\n").filter((l) => l.startsWith(`${key}: `));
+    return lines.length === 1 ? lines[0].slice(key.length + 2) : null;
+};
+/**
+ * Checks, against the credential and without the issuer, that the principal's own signature authorizes this
+ * agent with this mandate: the CMS verifies over the text up to the ICP-Brasil anchors; the certificate is the
+ * one the credential records; the text names the credential's agent, principal and issuer; and the mandate hash
+ * in the text equals the hash of the credential's mandate. `anchors`, `now` and the revocation check are the
+ * caller's. Never throws on a bad proof: every check is reported.
+ */
+export async function verifyPrincipalProof(p) {
+    const { credential: c, proof } = p;
+    const checks = [];
+    const push = (rule, ok, detail) => checks.push({ rule, ok, detail });
+    if (!proof || typeof proof.text !== "string" || typeof proof.cms !== "string") {
+        push("signature", false, "proof must carry the signed text and the CMS");
+        return { ok: false, checks, revocation: null };
+    }
+    if (!(p.now instanceof Date) || Number.isNaN(p.now.getTime())) {
+        push("signature", false, "the verifier's clock is not a valid date");
+        return { ok: false, checks, revocation: null };
+    }
+    const person = isPersonPrincipal(c.principal);
+    let certificateSha256 = null;
+    let revocation = null;
+    try {
+        const icp = person
+            ? await verifyIcpPersonSignature({ cmsBase64: proof.cms, challenge: proof.text, anchors: p.anchors, now: p.now })
+            : await verifyIcpSignature({ cmsBase64: proof.cms, challenge: proof.text, expectedCnpj: c.principal.cnpj, anchors: p.anchors, now: p.now });
+        certificateSha256 = icp.certificate_sha256;
+        revocation = { serial_number: icp.serial_number, issuer_certificate: icp.issuer_certificate, crl_urls: icp.crl_urls };
+        push("signature", true, `${person ? "e-CPF" : "e-CNPJ"} signature over the text verifies up to the ICP-Brasil anchors`);
+    }
+    catch (e) {
+        push("signature", false, e instanceof KyaError ? e.message : `signature does not verify: ${e.message}`);
+    }
+    if (certificateSha256 !== null) {
+        const same = certificateSha256 === c.authorized_by.certificate_sha256;
+        push("certificate", same, same ? "signed with the certificate the credential records" : "signed with another certificate than the one the credential records");
+    }
+    const agent = lineOf(proof.text, "agent");
+    const expectedAgent = `${c.agent.kind}:${c.agent.id}`;
+    push("agent", agent === expectedAgent, agent === expectedAgent ? `text names the credential's agent ${expectedAgent}` : `text names agent ${agent ?? "(none)"}, the credential ${expectedAgent}`);
+    if (person) {
+        const ok = lineOf(proof.text, "principal") === "person (e-CPF)";
+        push("principal", ok, ok ? "text is a natural person's authorization" : "text is not a natural person's authorization");
+    }
+    else {
+        const cnpj = lineOf(proof.text, "cnpj");
+        const expected = c.principal.cnpj;
+        push("principal", cnpj === expected, cnpj === expected ? `text names CNPJ ${expected}` : `text names CNPJ ${cnpj ?? "(none)"}, the credential ${expected}`);
+    }
+    const issuer = lineOf(proof.text, "issuer");
+    push("issuer", issuer === c.issuer, issuer === c.issuer ? `text names issuer ${c.issuer}` : `text names issuer ${issuer ?? "(none)"}, the credential ${c.issuer}`);
+    const signed = mandateSha256OfChallenge(proof.text);
+    const actual = await mandateSha256(c.mandate);
+    const recorded = c.authorized_by.mandate_sha256;
+    const mandateOk = signed !== null && signed === actual && (!recorded || recorded === signed);
+    push("mandate", mandateOk, signed === null ? "text carries no mandate hash (signed before D-33)" : mandateOk ? "text commits to the credential's mandate" : "text commits to another mandate than the credential's");
+    return { ok: checks.every((x) => x.ok), checks, revocation };
+}
+/** 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 })));
+}
+/** Parses the header value; throws INVALID_INPUT when it is not a proof. */
+export function decodePrincipalProofHeader(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(base64url.decode(value.trim())));
+    }
+    catch {
+        throw new KyaError("INVALID_INPUT", "KYA-Principal-Proof is not base64url JSON");
+    }
+    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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/core",
-  "version": "0.14.0",
+  "version": "0.15.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",