@kya-brasil/core 0.15.0 → 0.17.0

package/README.md

@@ -186,25 +186,28 @@ const ecnpj_signature = await signer.sign(challengeText);
 ```ts
 import {
   newChallenge, verifyAgentSignature, verifyIcpSignature, checkRevocation,
-  validateMandate, buildCredential, signCredential, importPrivateKey, generateAttestationKey
+  validateMandate, mandateSha256, buildCredential, signCredential, importPrivateKey, generateAttestationKey
 } from "@kya-brasil/core";
 
 const key = await generateAttestationKey();               // once; keep privateKeyPkcs8 secret, publish publicJwk
-const ch = newChallenge({ issuer: "https://kya.acquirer.example", agent, cnpj });
+const m = validateMandate(mandate);
+const mandate_sha256 = await mandateSha256(m);            // the e-CNPJ signs this hash with the challenge (D-33)
+const ch = newChallenge({ issuer: "https://kya.acquirer.example", agent, cnpj, mandate_sha256 });
 // The agent signs ch.text with its key; the company signs ch.text with its e-CNPJ (detached CMS).
 if (!(await verifyAgentSignature(agent, ch.text, agentSignature))) throw new Error("agent signature");
 const icp = await verifyIcpSignature({ cmsBase64: ecnpjSignature, challenge: ch.text, expectedCnpj: cnpj, anchors });
 // anchors: the ICP-Brasil roots as PEM strings (bundle in the repository: anchors/icp-brasil.pem).
 const crlDer = await fetchCrl(icp.crl_urls);             // yours: HTTP + cache
-const rev = await checkRevocation({ crlDer, serial: icp.serial_number, issuerCertificate: icp.issuer_certificate! });
+const rev = await checkRevocation({ crlDer, serial: icp.serial_number, issuerCertificate: icp.issuer_certificate!, pastNextUpdate: "refuse" });
 if (rev.revoked) throw new Error("certificate revoked");
 
 const credential = await signCredential(
   buildCredential({
     credential_id: crypto.randomUUID(), agent, cnpj,
     legal_name, registration_status,                      // from your registration source; "UNVERIFIED" if none answered
-    certificate: { sha256: icp.certificate_sha256, subject: icp.certificate_subject, issuer: icp.issuer, signed_at: icp.signed_at },
-    mandate: validateMandate(mandate),
+    certificate: { sha256: icp.certificate_sha256, subject: icp.certificate_subject, issuer: icp.issuer, signed_at: icp.signed_at, not_after: icp.not_after },
+    mandate: m, mandate_sha256,
+    ttl_seconds: 30 * 86400,                              // your risk decision; capped by the certificate and the mandate (D-35)
     issuer: "https://kya.acquirer.example"
   }),
   await importPrivateKey(key.privateKeyPkcs8), key.keyId

package/dist/credential.d.ts

@@ -1,18 +1,32 @@
-import type { Credential, CredentialStatus, KybSnapshot, Mandate, AgentKey } from "./types.js";
-export declare const CREDENTIAL_TTL_DAYS = 90;
+import { type Credential, type CredentialStatus, type KybSnapshot, type Mandate, type AgentKey } from "./types.js";
+/**
+ * D-35: when a credential expires. The lifetime is the caller's (`ttl_seconds`, no default: it is a risk decision),
+ * and the credential never outlives the mandate nor the certificate that signed it, so a proof checked against
+ * ICP-Brasil (D-34) never fails while the credential still reads as active.
+ */
+export declare function credentialExpiry(p: {
+    now: Date;
+    ttl_seconds: number;
+    mandate: Pick<Mandate, "valid_until">;
+    certificate_not_after: string;
+}): Date;
 export declare function buildCredential(p: {
     credential_id: string;
     agent: AgentKey;
     cnpj: string;
     legal_name: string;
     registration_status: string;
+    /** not_after: the signing certificate's end of validity (IcpProof.not_after); the credential never outlives it. */
     certificate: {
         sha256: string;
         subject: string;
         issuer: string;
         signed_at: string;
+        not_after: string;
     };
     mandate: Mandate;
+    /** D-35: the credential lifetime in seconds. Required, no default: how long a credential lives is the caller's risk. */
+    ttl_seconds: number;
     /** D-33: the mandate SHA-256 the signed challenge carried (mandateSha256OfChallenge). */
     mandate_sha256?: string;
     /** /v1 compatibility only; leave out (null). */
@@ -26,12 +40,16 @@ export declare function buildCredential(p: {
 export declare function buildPersonCredential(p: {
     credential_id: string;
     agent: AgentKey;
+    /** not_after: the signing certificate's end of validity (IcpPersonProof.not_after); the credential never outlives it. */
     certificate: {
         sha256: string;
         issuer: string;
         signed_at: string;
+        not_after: string;
     };
     mandate: Mandate;
+    /** D-35: the credential lifetime in seconds. Required, no default. */
+    ttl_seconds: number;
     /** D-33: the mandate SHA-256 the signed challenge carried (mandateSha256OfChallenge). */
     mandate_sha256?: string;
     issuer: string;

package/dist/credential.js

@@ -5,13 +5,29 @@
  */
 import { attestedPayload, canonicalize, signAttestation, verifyAttestation } from "./attestation.js";
 import { formatCnpj, normalizeCnpj } from "./cnpj.js";
-export const CREDENTIAL_TTL_DAYS = 90;
+import { KyaError } from "./types.js";
+/**
+ * D-35: when a credential expires. The lifetime is the caller's (`ttl_seconds`, no default: it is a risk decision),
+ * and the credential never outlives the mandate nor the certificate that signed it, so a proof checked against
+ * ICP-Brasil (D-34) never fails while the credential still reads as active.
+ */
+export function credentialExpiry(p) {
+    if (typeof p.ttl_seconds !== "number" || !Number.isFinite(p.ttl_seconds) || p.ttl_seconds <= 0)
+        throw new KyaError("INVALID_INPUT", "ttl_seconds must be a positive number of seconds (the credential lifetime is the caller's decision)");
+    const notAfter = new Date(p.certificate_not_after);
+    if (Number.isNaN(notAfter.getTime()))
+        throw new KyaError("INVALID_INPUT", "certificate.not_after must be an ISO 8601 date");
+    if (notAfter <= p.now)
+        throw new KyaError("CERTIFICATE_INVALID", `certificate expired on ${notAfter.toISOString()}`);
+    const candidates = [new Date(p.now.getTime() + p.ttl_seconds * 1000), notAfter];
+    if (p.mandate.valid_until)
+        candidates.push(new Date(p.mandate.valid_until));
+    return new Date(Math.min(...candidates.map((d) => d.getTime())));
+}
 export function buildCredential(p) {
     const now = p.now ?? new Date();
     const cnpj = normalizeCnpj(p.cnpj);
-    const ttl = new Date(now.getTime() + CREDENTIAL_TTL_DAYS * 86400000);
-    const mandateEnd = p.mandate.valid_until ? new Date(p.mandate.valid_until) : null;
-    const expires = mandateEnd && mandateEnd < ttl ? mandateEnd : ttl;
+    const expires = credentialExpiry({ now, ttl_seconds: p.ttl_seconds, mandate: p.mandate, certificate_not_after: p.certificate.not_after });
     return {
         credential_id: p.credential_id,
         version: 1,
@@ -32,9 +48,7 @@ export function buildCredential(p) {
 /** D-29: credential of a natural person. Nothing personal: no name, no CPF, no certificate subject. */
 export function buildPersonCredential(p) {
     const now = p.now ?? new Date();
-    const ttl = new Date(now.getTime() + CREDENTIAL_TTL_DAYS * 86400000);
-    const mandateEnd = p.mandate.valid_until ? new Date(p.mandate.valid_until) : null;
-    const expires = mandateEnd && mandateEnd < ttl ? mandateEnd : ttl;
+    const expires = credentialExpiry({ now, ttl_seconds: p.ttl_seconds, mandate: p.mandate, certificate_not_after: p.certificate.not_after });
     return {
         credential_id: p.credential_id,
         version: 1,

package/dist/revocation.d.ts

@@ -15,6 +15,8 @@ export interface RevocationStatus {
     revoked: boolean;
     revoked_at: string | null;
     reason: string | null;
+    /** RFC 5280 invalidityDate: when the key is known or suspected to have been compromised, if the AC says so. */
+    invalidity_date?: string | null;
     crl_this_update: string;
     crl_next_update: string | null;
 }
@@ -46,12 +48,33 @@ export declare function checkRevocation(p: {
     pastNextUpdate: "refuse" | "accept";
     now?: Date;
 }): Promise<RevocationStatus>;
+/** RFC 5280 CRL reason codes (section 5.3.1), by name. */
+export declare const CRL_REASONS: readonly ["unspecified", "keyCompromise", "cACompromise", "affiliationChanged", "superseded", "cessationOfOperation", "certificateHold", "removeFromCRL", "privilegeWithdrawn", "aACompromise"];
+export type CrlReason = (typeof CRL_REASONS)[number];
 /**
- * What a CRL entry does to a credential the certificate already authorized (D-16):
- *   - certificateHold: suspend (the AC may lift it; the review reinstates when the entry disappears);
- *   - superseded / cessationOfOperation dated after the authorization: nothing, the company replaced or
- *     retired the certificate without compromise and its signature stands (registration is checked apart);
- *   - anything else (unspecified, keyCompromise, privilegeWithdrawn, ...): revoke.
+ * D-36: what a revoked certificate does to what it already authorized, decided by whoever relies on it.
+ *   - `by_reason`: the effect of each CRL reason the caller has an opinion on: "revoke" (the authorization ends),
+ *     "suspend" (it stops while the entry stays, e.g. certificateHold) or "keep" (it stands: the certificate was
+ *     replaced or retired without compromise);
+ *   - `other`: the effect of any reason not listed, including an entry without a reason. Never "keep": an
+ *     unexplained revocation is not ignored.
+ * No default: which reasons end a mandate is a legal and risk decision (Código Civil art. 682; SPEC section 11).
+ */
+export interface CertificateRevocationPolicy {
+    by_reason: Partial<Record<CrlReason, "revoke" | "suspend" | "keep">>;
+    other: "revoke" | "suspend";
+}
+/** Throws INVALID_INPUT unless `p` is a complete CertificateRevocationPolicy. */
+export declare function certificateRevocationPolicy(p: CertificateRevocationPolicy): CertificateRevocationPolicy;
+/**
+ * What a CRL entry does to an authorization the certificate already signed (D-16, D-36), under the caller's policy.
+ * Two rules hold whatever the policy says, because they are about the signature, not about the mandate:
+ *   - "keep" applies only when the revocation, and the suspected compromise (invalidityDate) when the AC gives
+ *     one, come after the authorization; otherwise the authorization was signed with a certificate already
+ *     revoked or already compromised, and it is revoked (MP 2.200-2 art. 10 presumes only a valid certificate);
+ *   - without the authorization's date there is nothing to compare: "keep" becomes "revoke".
  * At issuance any entry refuses: a new authorization must be signed with a certificate in force.
  */
-export declare function revocationEffect(r: Pick<RevocationStatus, "revoked" | "revoked_at" | "reason">, authorizedAt: string | null): "none" | "suspend" | "revoke";
+export declare function revocationEffect(r: Pick<RevocationStatus, "revoked" | "revoked_at" | "reason"> & {
+    invalidity_date?: string | null;
+}, authorizedAt: string | null, policy: CertificateRevocationPolicy): "none" | "suspend" | "revoke";

package/dist/revocation.js

@@ -64,6 +64,7 @@ export async function verifyCrl(p) {
                 revoked: entry !== null,
                 revoked_at: entry ? entry.revocationDate.toISOString() : null,
                 reason: entry && entry.reason !== undefined ? (X509CrlReason[entry.reason] ?? String(entry.reason)) : null,
+                invalidity_date: entry?.invalidity ? entry.invalidity.toISOString() : null,
                 crl_this_update: this_update,
                 crl_next_update: next_update
             };
@@ -74,21 +75,45 @@ export async function verifyCrl(p) {
 export async function checkRevocation(p) {
     return (await verifyCrl(p)).lookup(p.serial);
 }
+/** RFC 5280 CRL reason codes (section 5.3.1), by name. */
+export const CRL_REASONS = ["unspecified", "keyCompromise", "cACompromise", "affiliationChanged", "superseded", "cessationOfOperation", "certificateHold", "removeFromCRL", "privilegeWithdrawn", "aACompromise"];
+/** Throws INVALID_INPUT unless `p` is a complete CertificateRevocationPolicy. */
+export function certificateRevocationPolicy(p) {
+    if (!p || typeof p !== "object")
+        throw new KyaError("INVALID_INPUT", "a certificate revocation policy is required: { by_reason, other }");
+    if (p.other !== "revoke" && p.other !== "suspend")
+        throw new KyaError("INVALID_INPUT", 'policy.other is required: "revoke" or "suspend" (an unexplained revocation is never ignored)');
+    if (!p.by_reason || typeof p.by_reason !== "object")
+        throw new KyaError("INVALID_INPUT", "policy.by_reason is required (it may be empty)");
+    for (const [k, v] of Object.entries(p.by_reason)) {
+        if (!CRL_REASONS.includes(k))
+            throw new KyaError("INVALID_INPUT", `policy.by_reason.${k} is not an RFC 5280 reason`);
+        if (v !== "revoke" && v !== "suspend" && v !== "keep")
+            throw new KyaError("INVALID_INPUT", `policy.by_reason.${k} must be "revoke", "suspend" or "keep"`);
+    }
+    return { by_reason: { ...p.by_reason }, other: p.other };
+}
+const isAfter = (a, b) => a !== null && Date.parse(a) > Date.parse(b);
 /**
- * What a CRL entry does to a credential the certificate already authorized (D-16):
- *   - certificateHold: suspend (the AC may lift it; the review reinstates when the entry disappears);
- *   - superseded / cessationOfOperation dated after the authorization: nothing, the company replaced or
- *     retired the certificate without compromise and its signature stands (registration is checked apart);
- *   - anything else (unspecified, keyCompromise, privilegeWithdrawn, ...): revoke.
+ * What a CRL entry does to an authorization the certificate already signed (D-16, D-36), under the caller's policy.
+ * Two rules hold whatever the policy says, because they are about the signature, not about the mandate:
+ *   - "keep" applies only when the revocation, and the suspected compromise (invalidityDate) when the AC gives
+ *     one, come after the authorization; otherwise the authorization was signed with a certificate already
+ *     revoked or already compromised, and it is revoked (MP 2.200-2 art. 10 presumes only a valid certificate);
+ *   - without the authorization's date there is nothing to compare: "keep" becomes "revoke".
  * At issuance any entry refuses: a new authorization must be signed with a certificate in force.
  */
-export function revocationEffect(r, authorizedAt) {
+export function revocationEffect(r, authorizedAt, policy) {
+    const pol = certificateRevocationPolicy(policy);
     if (!r.revoked)
         return "none";
-    if (r.reason === "certificateHold")
-        return "suspend";
-    const benign = r.reason === "superseded" || r.reason === "cessationOfOperation";
-    if (benign && authorizedAt && r.revoked_at && Date.parse(r.revoked_at) > Date.parse(authorizedAt))
-        return "none";
-    return "revoke";
+    const reason = r.reason && CRL_REASONS.includes(r.reason) ? r.reason : null;
+    const effect = (reason && pol.by_reason[reason]) ?? pol.other;
+    if (effect !== "keep")
+        return effect;
+    if (!authorizedAt || Number.isNaN(Date.parse(authorizedAt)))
+        return "revoke";
+    const revokedAfter = isAfter(r.revoked_at, authorizedAt);
+    const compromiseAfter = r.invalidity_date ? isAfter(r.invalidity_date, authorizedAt) : true;
+    return revokedAfter && compromiseAfter ? "none" : "revoke";
 }

package/package.json

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