@kya-brasil/core 0.13.0 → 0.14.0

package/README.md

@@ -25,10 +25,13 @@ A credential from any KYA issuer (the hosted one, yours, a partner's) is checked
 published at `<issuer>/.well-known/kya.json`.
 
 ```ts
-import { verifyCredentialSignature, effectiveStatus, checkAction, hashPaymentRef } from "@kya-brasil/core";
+import { verifyCredentialSignature, verifyMandateAuthorization, effectiveStatus, checkAction, hashPaymentRef } from "@kya-brasil/core";
 
 const sig = await verifyCredentialSignature(credential, issuerPublicJwk); // { valid, key_id, signed_at }
 if (!sig.valid || effectiveStatus(credential) !== "active") deny();
+// D-33: the e-CNPJ / e-CPF signature covers the mandate when the credential carries its hash.
+const auth = await verifyMandateAuthorization(credential); // "signed" | "mismatch" | "not_covered" (issued before D-33)
+if (auth === "mismatch") deny(); // decide yourself whether "not_covered" (issuer attestation only) is enough
 // For live status (revoked or suspended after issuance) read credential.verify_url, or accept that risk until expires_at.
 
 const verdict = checkAction(credential.mandate, {

package/dist/challenge.d.ts

@@ -9,20 +9,30 @@ export declare function normalizeAgentKey(input: {
     kind?: unknown;
     id?: unknown;
 }): AgentKey;
-/** The exact text the agent signs. Line-based so wallets show it readably. */
+/**
+ * The exact text the agent and the e-CNPJ sign. Line-based so wallets show it readably. Since D-33 it carries
+ * the mandate's SHA-256, so the certificate signature covers the powers granted, not only the binding.
+ */
 export declare function challengeText(p: {
     issuer: string;
     challenge_id: string;
     agent: AgentKey;
     cnpj: string;
+    mandate_sha256: string;
     expires_at: string;
 }): string;
 export declare function newChallenge(p: {
     issuer: string;
     agent: AgentKey;
     cnpj: string;
+    mandate_sha256: string;
     now?: Date;
 }): Challenge;
+/**
+ * The mandate SHA-256 a signed challenge text commits to (its `mandate-sha256:` line), or null when the text
+ * has none (a challenge from before D-33). The issuer compares it with the mandate it is about to issue.
+ */
+export declare function mandateSha256OfChallenge(text: string): string | null;
 /** True when `signature` is the agent key's signature over `text`. Never throws on a bad signature. */
 export declare function verifyAgentSignature(agent: AgentKey, text: string, signature: string): Promise<boolean>;
 export declare const base64url: {

package/dist/challenge.js

@@ -4,8 +4,8 @@
  *   evm           EIP-191 personal_sign over the challenge text; address recovered and compared
  *   web-bot-auth  Ed25519 (RFC 9421 key material) raw signature over the challenge bytes
  *   erc8004       EIP-191 by the agent's on-chain agentWallet (resolved by the caller, see erc8004.ts)
- * The challenge text binds agent key, CNPJ, issuer and expiry, so a signature cannot be replayed
- * for another company or another issuer.
+ * The challenge text binds agent key, CNPJ, issuer, expiry and the mandate (its SHA-256, D-33), so a
+ * signature cannot be replayed for another company, another issuer or other powers.
  */
 import { verifyMessage, getAddress, isAddress } from "viem";
 import { KyaError } from "./types.js";
@@ -49,7 +49,16 @@ export function normalizeAgentKey(input) {
     }
     throw new KyaError("INVALID_INPUT", "agent.kind must be evm, web-bot-auth or erc8004");
 }
-/** The exact text the agent signs. Line-based so wallets show it readably. */
+const HEX64 = /^[0-9a-f]{64}$/;
+function requireMandateSha256(h) {
+    if (typeof h !== "string" || !HEX64.test(h))
+        throw new KyaError("INVALID_INPUT", "mandate_sha256 must be 64 lowercase hex characters (see mandateSha256)");
+    return h;
+}
+/**
+ * The exact text the agent and the e-CNPJ sign. Line-based so wallets show it readably. Since D-33 it carries
+ * the mandate's SHA-256, so the certificate signature covers the powers granted, not only the binding.
+ */
 export function challengeText(p) {
     return [
         "KYA Brasil: prove this agent key acts for a company",
@@ -57,6 +66,7 @@ export function challengeText(p) {
         `challenge: ${p.challenge_id}`,
         `agent: ${p.agent.kind}:${p.agent.id}`,
         `cnpj: ${p.cnpj}`,
+        `mandate-sha256: ${requireMandateSha256(p.mandate_sha256)}`,
         `expires: ${p.expires_at}`
     ].join("\n");
 }
@@ -64,7 +74,18 @@ export function newChallenge(p) {
     const now = p.now ?? new Date();
     const challenge_id = crypto.randomUUID();
     const expires_at = new Date(now.getTime() + CHALLENGE_TTL_SECONDS * 1000).toISOString();
-    return { challenge_id, expires_at, text: challengeText({ issuer: p.issuer, challenge_id, agent: p.agent, cnpj: p.cnpj, expires_at }) };
+    return { challenge_id, expires_at, text: challengeText({ issuer: p.issuer, challenge_id, agent: p.agent, cnpj: p.cnpj, mandate_sha256: p.mandate_sha256, expires_at }) };
+}
+/**
+ * The mandate SHA-256 a signed challenge text commits to (its `mandate-sha256:` line), or null when the text
+ * has none (a challenge from before D-33). The issuer compares it with the mandate it is about to issue.
+ */
+export function mandateSha256OfChallenge(text) {
+    const lines = text.split("\n").filter((l) => l.startsWith("mandate-sha256: "));
+    if (lines.length !== 1)
+        return null;
+    const h = lines[0].slice("mandate-sha256: ".length);
+    return HEX64.test(h) ? h : null;
 }
 /** True when `signature` is the agent key's signature over `text`. Never throws on a bad signature. */
 export async function verifyAgentSignature(agent, text, signature) {

package/dist/credential.d.ts

@@ -13,6 +13,8 @@ export declare function buildCredential(p: {
         signed_at: string;
     };
     mandate: Mandate;
+    /** D-33: the mandate SHA-256 the signed challenge carried (mandateSha256OfChallenge). */
+    mandate_sha256?: string;
     /** /v1 compatibility only; leave out (null). */
     kyb?: KybSnapshot | null;
     issuer: string;
@@ -30,6 +32,8 @@ export declare function buildPersonCredential(p: {
         signed_at: string;
     };
     mandate: Mandate;
+    /** D-33: the mandate SHA-256 the signed challenge carried (mandateSha256OfChallenge). */
+    mandate_sha256?: string;
     issuer: string;
     now?: Date;
 }): Credential;
@@ -54,3 +58,13 @@ export declare function principalDecision(registration_status: string): {
     reason: string | null;
 };
 export declare function effectiveStatus(c: Pick<Credential, "status" | "expires_at">, now?: Date): CredentialStatus;
+/** D-33: SHA-256 (lowercase hex) of the canonical JSON (section 7) of a mandate; what the challenge commits to. */
+export declare function mandateSha256(mandate: Mandate): Promise<string>;
+/**
+ * Offline: does the ICP-Brasil signature behind this credential cover its mandate (D-33)?
+ *   "signed"      authorized_by.mandate_sha256 equals the SHA-256 of credential.mandate;
+ *   "mismatch"    it does not: the mandate is not the one the principal signed (refuse the credential);
+ *   "not_covered" the credential predates D-33 and carries no hash: the mandate rests on the issuer's attestation.
+ * The certificate signature itself is verified by the issuer at issuance; the signed .p7s stays with the principal.
+ */
+export declare function verifyMandateAuthorization(c: Pick<Credential, "mandate" | "authorized_by">): Promise<"signed" | "mismatch" | "not_covered">;

package/dist/credential.js

@@ -17,7 +17,7 @@ export function buildCredential(p) {
         version: 1,
         agent: p.agent,
         principal: { cnpj, cnpj_formatted: formatCnpj(cnpj), legal_name: p.legal_name, registration_status: p.registration_status },
-        authorized_by: { method: "icp-brasil-e-cnpj", certificate_sha256: p.certificate.sha256, certificate_subject: p.certificate.subject, issuer: p.certificate.issuer, signed_at: p.certificate.signed_at },
+        authorized_by: { method: "icp-brasil-e-cnpj", certificate_sha256: p.certificate.sha256, certificate_subject: p.certificate.subject, issuer: p.certificate.issuer, signed_at: p.certificate.signed_at, ...(p.mandate_sha256 ? { mandate_sha256: p.mandate_sha256 } : {}) },
         mandate: p.mandate,
         kyb_snapshot: p.kyb ?? null,
         status: p.status ?? "active",
@@ -40,7 +40,7 @@ export function buildPersonCredential(p) {
         version: 1,
         agent: p.agent,
         principal: { kind: "person", verified_by: "icp-brasil-e-cpf" },
-        authorized_by: { method: "icp-brasil-e-cpf", certificate_sha256: p.certificate.sha256, issuer: p.certificate.issuer, signed_at: p.certificate.signed_at },
+        authorized_by: { method: "icp-brasil-e-cpf", certificate_sha256: p.certificate.sha256, issuer: p.certificate.issuer, signed_at: p.certificate.signed_at, ...(p.mandate_sha256 ? { mandate_sha256: p.mandate_sha256 } : {}) },
         mandate: p.mandate,
         kyb_snapshot: null,
         status: "active",
@@ -86,3 +86,21 @@ export function effectiveStatus(c, now = new Date()) {
         return "expired";
     return c.status;
 }
+/** D-33: SHA-256 (lowercase hex) of the canonical JSON (section 7) of a mandate; what the challenge commits to. */
+export async function mandateSha256(mandate) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalize(mandate)));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Offline: does the ICP-Brasil signature behind this credential cover its mandate (D-33)?
+ *   "signed"      authorized_by.mandate_sha256 equals the SHA-256 of credential.mandate;
+ *   "mismatch"    it does not: the mandate is not the one the principal signed (refuse the credential);
+ *   "not_covered" the credential predates D-33 and carries no hash: the mandate rests on the issuer's attestation.
+ * The certificate signature itself is verified by the issuer at issuance; the signed .p7s stays with the principal.
+ */
+export async function verifyMandateAuthorization(c) {
+    const h = c.authorized_by?.mandate_sha256;
+    if (!h)
+        return "not_covered";
+    return (await mandateSha256(c.mandate)) === h ? "signed" : "mismatch";
+}

package/dist/person.d.ts

@@ -26,11 +26,12 @@ export declare function personKeys(json: string | undefined): {
 } | null;
 /** Consent the person signs with the e-CPF; part of the challenge text, so the signature records it. */
 export declare const PERSON_CONSENT = "I authorize this issuer to keep a keyed hash of my CPF while this credential is valid and to answer, to verifiers who pay for each check, only whether a CPF they already have matches. My name and CPF are never stored in clear, published or revealed. / Autorizo este emissor a guardar um hash com chave do meu CPF enquanto esta credencial valer e a responder, a verificadores que pagam por consulta, apenas se um CPF que eles ja tem confere. Meu nome e meu CPF nunca sao guardados em claro, publicados ou revelados.";
-/** The text a person and the agent sign (no CPF: it comes from the e-CPF certificate). */
+/** The text a person and the agent sign (no CPF: it comes from the e-CPF certificate); with the mandate's SHA-256 (D-33). */
 export declare function personChallengeText(p: {
     issuer: string;
     challenge_id: string;
     agent: AgentKey;
+    mandate_sha256: string;
     expires_at: string;
 }): string;
 /** The text a person signs with the e-CPF to see their own agents (accepted for 10 minutes after `at`). */
@@ -38,5 +39,6 @@ export declare const personAgentsText: (at?: Date) => string;
 export declare function newPersonChallenge(p: {
     issuer: string;
     agent: AgentKey;
+    mandate_sha256: string;
     now?: Date;
 }): Challenge;

package/dist/person.js

@@ -66,8 +66,10 @@ export function personKeys(json) {
 }
 /** Consent the person signs with the e-CPF; part of the challenge text, so the signature records it. */
 export const PERSON_CONSENT = "I authorize this issuer to keep a keyed hash of my CPF while this credential is valid and to answer, to verifiers who pay for each check, only whether a CPF they already have matches. My name and CPF are never stored in clear, published or revealed. / Autorizo este emissor a guardar um hash com chave do meu CPF enquanto esta credencial valer e a responder, a verificadores que pagam por consulta, apenas se um CPF que eles ja tem confere. Meu nome e meu CPF nunca sao guardados em claro, publicados ou revelados.";
-/** The text a person and the agent sign (no CPF: it comes from the e-CPF certificate). */
+/** The text a person and the agent sign (no CPF: it comes from the e-CPF certificate); with the mandate's SHA-256 (D-33). */
 export function personChallengeText(p) {
+    if (typeof p.mandate_sha256 !== "string" || !/^[0-9a-f]{64}$/.test(p.mandate_sha256))
+        throw new KyaError("INVALID_INPUT", "mandate_sha256 must be 64 lowercase hex characters (see mandateSha256)");
     return [
         "KYA Brasil: prove this agent key acts for me, a natural person",
         `issuer: ${p.issuer}`,
@@ -75,6 +77,7 @@ export function personChallengeText(p) {
         `agent: ${p.agent.kind}:${p.agent.id}`,
         "principal: person (e-CPF)",
         `consent: ${PERSON_CONSENT}`,
+        `mandate-sha256: ${p.mandate_sha256}`,
         `expires: ${p.expires_at}`
     ].join("\n");
 }
@@ -84,5 +87,5 @@ export function newPersonChallenge(p) {
     const now = p.now ?? new Date();
     const challenge_id = crypto.randomUUID();
     const expires_at = new Date(now.getTime() + CHALLENGE_TTL_SECONDS * 1000).toISOString();
-    return { challenge_id, expires_at, text: personChallengeText({ issuer: p.issuer, challenge_id, agent: p.agent, expires_at }) };
+    return { challenge_id, expires_at, text: personChallengeText({ issuer: p.issuer, challenge_id, agent: p.agent, mandate_sha256: p.mandate_sha256, expires_at }) };
 }

package/dist/types.d.ts

@@ -97,13 +97,18 @@ export interface Credential {
     agent: AgentKey;
     /** A company (e-CNPJ) or, since D-29, a natural person (e-CPF) with no personal data: tell them apart by `kind`. */
     principal: CompanyPrincipal | PersonPrincipal;
-    /** How the principal authorized it: hash of the ICP-Brasil certificate that signed the challenge. No subject for persons. */
+    /**
+     * How the principal authorized it: hash of the ICP-Brasil certificate that signed the challenge. No subject for
+     * persons. `mandate_sha256` (D-33) is the mandate's SHA-256 that the signed challenge carried: when it equals
+     * mandateSha256(mandate), the certificate signature covers these powers (see verifyMandateAuthorization).
+     */
     authorized_by: {
         method: "icp-brasil-e-cnpj" | "icp-brasil-e-cpf";
         certificate_sha256: string;
         certificate_subject?: string;
         issuer: string;
         signed_at: string;
+        mandate_sha256?: string;
     };
     mandate: Mandate;
     /** Informative since D-15: the issuance decision uses only principal.registration_status and the certificate's revocation status. Always null from the reference issuer since D-23 (no KYB dependency); kept in /v1. Null when the issuer has no KYB source (D-17). */

package/package.json

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