@kya-brasil/core 0.12.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, {
@@ -63,29 +66,40 @@ the text the delegator signs with its agent key; `mandateSubsetProblems(parent,
 Offline, a verifier only has status evidence of some age: an answer the issuer signed (the credential's status) or a
 CRL (the certificate's). How old is acceptable is the verifier's call, because the verifier runs the risk (SPEC
 section 18). Declare the expected loss you accept per action (`L`) and the revocation rate you assume (`λ`, per hour);
-the maximum age is `L / (amount × λ)`, capped (one day by default):
+the maximum age is `L / (amount × λ)`, capped by your ceiling. The library holds no business values: every
+parameter below is required, and so is the clock.
 
 ```ts
 import { freshnessPolicy, checkFreshAction, evidenceFromSignedStatus, evidenceFromRevocation } from "@kya-brasil/core";
 
 const policy = freshnessPolicy({
   max_expected_loss: { amount: 1, currency: "BRL" },               // L: your tolerance, per action
-  revocation_rate_per_hour: { credential: lambda, certificate: mu }, // λ: what you assume; no default
+  revocation_rate_per_hour: { credential: lambda, certificate: mu }, // λ: what you assume
   require: ["credential"],                                          // add "certificate" to also require a CRL
-  // max_age_seconds: 86_400, max_clock_skew_seconds: 300, or max_age: ({ amount, kind }) => seconds
+  max_age_seconds: ceiling,                                         // your ceiling, whatever the value
+  max_clock_skew_seconds: skew,                                     // tolerance for evidence dated in the future
+  unvalued_action: "refuse",                                        // or "ceiling": actions of unknown value
+  past_valid_until: "refuse",                                       // or "accept": a CRL past nextUpdate, judged by age
+  // action_risk_value: { sign_contract: 100_000 }, max_age: ({ amount, kind, action }) => seconds
 });
 
 // The agent may staple a recent signed verdict to its request: then no network is needed.
 const evidence = [await evidenceFromSignedStatus(stapledVerdict, issuerPublicJwk, credential.credential_id)];
-// evidence.push(evidenceFromRevocation(await checkRevocation({ crlDer, serial, issuerCertificate })));
+// evidence.push(evidenceFromRevocation(await checkRevocation({ crlDer, serial, issuerCertificate, pastNextUpdate: "accept" })));
 
-const r = checkFreshAction(credential.mandate, { action: "buy", amount: 4200, currency: "BRL" }, { policy, evidence });
+const r = checkFreshAction(credential.mandate, { action: "buy", amount: 4200, currency: "BRL", now: trustedClock() }, { policy, evidence });
 // r.allowed; r.freshness.refresh = kinds to fetch again (or ask the agent for); r.freshness.applied = policy and
 // clock used, keep it with the verdict as the risk you accepted
 ```
 
-It fails closed: no evidence, another currency, an invalid amount or clock, evidence dated in the future beyond the
-skew, or a CRL past its `nextUpdate`. The freshest statement wins, so a later revocation beats an earlier "active".
+Actions without an amount (signing, reading data, calling an API) take the risk value you assign them:
+`action_risk_value: { sign_contract: 100_000, read_data: 50 }` in the policy's currency; an action with neither an
+amount nor a risk value is refused or gets the ceiling, as `unvalued_action` says. A custom `max_age` also receives the action.
+The daily ceiling (`max_per_day` with your own `spent_today`) is what bounds a stolen key inside the window; the
+counting, and any stricter ceiling of your own, are yours.
+
+It fails closed: no evidence, another currency, an invalid amount, a missing or invalid clock, evidence dated in the
+future beyond your skew, or a CRL past its `nextUpdate` when `past_valid_until` is `"refuse"`. The freshest statement wins, so a later revocation beats an earlier "active".
 `checkFreshness` and `maxStatusAgeSeconds` are available on their own.
 
 ## Payment instruments (card networks, acquirers, issuers)

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

@@ -16,9 +16,6 @@ export interface StatusEvidence {
     /** Status as stated by the evidence, for the verdict ("active", "revoked", "certificateHold", ...). */
     status?: string;
 }
-export declare const FRESHNESS_DEFAULT_MAX_AGE_SECONDS = 86400;
-export declare const FRESHNESS_LIMIT_MAX_AGE_SECONDS: number;
-export declare const FRESHNESS_DEFAULT_CLOCK_SKEW_SECONDS = 300;
 export interface FreshnessPolicyInput {
     /** L: the expected loss the verifier accepts per action, in the currency of the amounts it checks. */
     max_expected_loss: {
@@ -27,20 +24,37 @@ export interface FreshnessPolicyInput {
     };
     /** λ: probability per hour that a subject in force stops being so, per kind of evidence. */
     revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
-    /** Kinds of evidence an action needs. Default ["credential"]. */
-    require?: EvidenceKind[];
-    /** Ceiling on the evidence age, whatever the amount. Default 86400 (one day), at most 90 days. */
-    max_age_seconds?: number;
-    /** Tolerance for evidence dated after the verifier's clock. Default 300, at most 3600. */
-    max_clock_skew_seconds?: number;
+    /** Kinds of evidence an action needs: one or more of "credential", "certificate". */
+    require: EvidenceKind[];
+    /** Ceiling on the evidence age, in seconds, whatever the value at risk. */
+    max_age_seconds: number;
+    /** Tolerance, in seconds, for evidence dated after the verifier's clock. */
+    max_clock_skew_seconds: number;
     /**
-     * Replaces the default formula. Receives the amount (undefined when the action has none) and the kind;
-     * returns seconds. The result is clamped to [0, max_age_seconds]; anything not finite counts as 0.
+     * What to do with an action that has neither an amount nor a risk value in `action_risk_value`:
+     * "refuse" fails the check; "ceiling" accepts evidence up to `max_age_seconds`.
+     */
+    unvalued_action: "refuse" | "ceiling";
+    /**
+     * What to do with evidence past its own `valid_until` (a CRL past nextUpdate): "refuse" fails the check;
+     * "accept" lets its age alone decide, as Li and Feigenbaum (FC 2001) propose.
+     */
+    past_valid_until: "refuse" | "accept";
+    /**
+     * Value at risk, in the policy's currency, of actions that carry no amount (`sign`, `read`, `call`...),
+     * keyed by action name. Used only when the action has no amount; see `unvalued_action` for the rest.
+     */
+    action_risk_value?: Record<string, number>;
+    /**
+     * Replaces the default formula. Receives the value at risk (the amount, or the action's risk value; undefined
+     * when there is neither), the action and the kind; returns seconds. The result is clamped to
+     * [0, max_age_seconds]; anything not finite counts as 0.
      */
     max_age?: (p: {
         amount: number | undefined;
         currency: string;
         kind: EvidenceKind;
+        action?: string;
     }) => number;
 }
 export interface FreshnessPolicy {
@@ -52,12 +66,20 @@ export interface FreshnessPolicy {
     require: EvidenceKind[];
     max_age_seconds: number;
     max_clock_skew_seconds: number;
+    unvalued_action: "refuse" | "ceiling";
+    past_valid_until: "refuse" | "accept";
+    action_risk_value: Record<string, number>;
     max_age?: FreshnessPolicyInput["max_age"];
 }
 /** Validates and normalizes a policy. Throws INVALID_INPUT on anything that would make it fail open. */
 export declare function freshnessPolicy(input: FreshnessPolicyInput): FreshnessPolicy;
-/** Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency). */
-export declare function maxStatusAgeSeconds(policy: FreshnessPolicy, kind: EvidenceKind, amount?: number): number;
+/** The value at risk of an action: its amount, or else the risk value the policy gives its name. */
+export declare function valueAtRisk(policy: FreshnessPolicy, amount?: number, action?: string): number | undefined;
+/**
+ * Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency) or, with no
+ * amount, of the risk value the policy assigns to `action`.
+ */
+export declare function maxStatusAgeSeconds(policy: FreshnessPolicy, kind: EvidenceKind, amount?: number, action?: string): number;
 export interface FreshnessCheck {
     rule: "freshness";
     kind: EvidenceKind;
@@ -74,7 +96,10 @@ export interface FreshnessVerdict {
     /** The policy and clock actually applied, to keep with the verdict as proof of the risk accepted. */
     applied: {
         now: string;
+        action: string | null;
         amount: number | null;
+        /** The amount, or the risk value assigned to the action; null when there was neither (ceiling applied). */
+        value_at_risk: number | null;
         currency: string;
         max_expected_loss: {
             amount: number;
@@ -83,24 +108,30 @@ export interface FreshnessVerdict {
         revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
         max_age_seconds: number;
         max_clock_skew_seconds: number;
+        unvalued_action: "refuse" | "ceiling";
+        past_valid_until: "refuse" | "accept";
         custom_max_age: boolean;
     };
 }
 /**
  * Checks that, for every kind the policy requires, the freshest evidence given says "in force", is not
- * past its own validity, is not dated in the future beyond the clock skew, and is younger than the maximum
- * age for this amount. Fails closed: missing, malformed or foreign-currency input never passes.
+ * past its own validity (unless the policy accepts that), is not dated in the future beyond the clock skew,
+ * and is younger than the maximum age for this value. Fails closed: missing, malformed or foreign-currency
+ * input never passes.
  */
-export declare function checkFreshness(policy: FreshnessPolicy, evidence: StatusEvidence[], q?: {
+export declare function checkFreshness(policy: FreshnessPolicy, evidence: StatusEvidence[], q: {
+    action?: string;
     amount?: number;
     currency?: string;
-    now?: Date;
+    now: Date;
 }): FreshnessVerdict;
 /**
  * The mandate (checkAction) and the freshness of the status, in one answer: allowed only when both pass.
- * The freshness check uses the action's amount and currency and the same clock.
+ * The freshness check uses the action's name, amount and currency and the same clock.
  */
-export declare function checkFreshAction(mandate: Mandate, q: ActionQuery, p: {
+export declare function checkFreshAction(mandate: Mandate, q: ActionQuery & {
+    now: Date;
+}, p: {
     policy: FreshnessPolicy;
     evidence: StatusEvidence[];
 }): {

package/dist/freshness.js

@@ -12,17 +12,19 @@
  *
  *     max_age(v) = L / (v × λ)   hours, capped by max_age_seconds.
  *
- * Pure functions, no network: the caller obtains the evidence (cache, CRL download, an issuer answer the
- * agent staples to its request) and passes the clock it trusts.
+ * Any action, not only payments: for an action with no amount (sign a document, read data, call an API) the
+ * verifier assigns a risk value per action (`action_risk_value`), or decides the age itself (`max_age`).
+ *
+ * Pure functions, no network, no business defaults: every value that expresses a risk decision (loss
+ * tolerance, rates, ceiling, clock skew, kinds required, what to do with an action of unknown value, the clock
+ * itself) is the caller's and must be passed. The module only validates that the values are well formed.
  */
 import { verifyAttestation } from "./attestation.js";
 import { checkAction } from "./mandate.js";
 import { KyaError } from "./types.js";
-export const FRESHNESS_DEFAULT_MAX_AGE_SECONDS = 86_400;
-export const FRESHNESS_LIMIT_MAX_AGE_SECONDS = 90 * 86_400;
-export const FRESHNESS_DEFAULT_CLOCK_SKEW_SECONDS = 300;
 const KINDS = ["credential", "certificate"];
 const CURRENCY = /^[A-Z0-9]{2,10}$/;
+const ACTION = /^[a-z][a-z0-9_-]{1,31}$/;
 function bad(message) {
     throw new KyaError("INVALID_INPUT", `freshness policy: ${message}`);
 }
@@ -36,7 +38,7 @@ export function freshnessPolicy(input) {
     const currency = typeof loss.currency === "string" ? loss.currency.trim().toUpperCase() : "";
     if (!CURRENCY.test(currency))
         bad("max_expected_loss.currency must match ^[A-Z0-9]{2,10}$");
-    const require = input.require ?? ["credential"];
+    const require = input.require;
     if (!Array.isArray(require) || !require.length || require.some((k) => !KINDS.includes(k)))
         bad(`require must list one or more of ${KINDS.join(", ")}`);
     const rates = {};
@@ -51,28 +53,57 @@ export function freshnessPolicy(input) {
         for (const k of require)
             if (rates[k] === undefined)
                 bad(`revocation_rate_per_hour.${k} is required (or give max_age)`);
-    const ceiling = input.max_age_seconds ?? FRESHNESS_DEFAULT_MAX_AGE_SECONDS;
-    if (!Number.isInteger(ceiling) || ceiling < 0 || ceiling > FRESHNESS_LIMIT_MAX_AGE_SECONDS)
-        bad(`max_age_seconds must be an integer in 0..${FRESHNESS_LIMIT_MAX_AGE_SECONDS}`);
-    const skew = input.max_clock_skew_seconds ?? FRESHNESS_DEFAULT_CLOCK_SKEW_SECONDS;
-    if (!Number.isInteger(skew) || skew < 0 || skew > 3600)
-        bad("max_clock_skew_seconds must be an integer in 0..3600");
+    const ceiling = input.max_age_seconds;
+    if (!Number.isSafeInteger(ceiling) || ceiling < 0)
+        bad("max_age_seconds is required: an integer >= 0");
+    const skew = input.max_clock_skew_seconds;
+    if (!Number.isSafeInteger(skew) || skew < 0)
+        bad("max_clock_skew_seconds is required: an integer >= 0");
+    const unvalued = input.unvalued_action;
+    if (unvalued !== "refuse" && unvalued !== "ceiling")
+        bad('unvalued_action is required: "refuse" or "ceiling"');
+    const pastValid = input.past_valid_until;
+    if (pastValid !== "refuse" && pastValid !== "accept")
+        bad('past_valid_until is required: "refuse" or "accept"');
     if (input.max_age !== undefined && typeof input.max_age !== "function")
         bad("max_age must be a function");
-    return { max_expected_loss: { amount: loss.amount, currency }, revocation_rate_per_hour: rates, require: [...new Set(require)], max_age_seconds: ceiling, max_clock_skew_seconds: skew, max_age: input.max_age };
+    const values = {};
+    if (input.action_risk_value !== undefined) {
+        if (!input.action_risk_value || typeof input.action_risk_value !== "object" || Array.isArray(input.action_risk_value))
+            bad("action_risk_value must be an object of action -> value");
+        for (const [a, v] of Object.entries(input.action_risk_value)) {
+            if (!ACTION.test(a))
+                bad(`action_risk_value: "${a}" is not a mandate action name (^[a-z][a-z0-9_-]{1,31}$)`);
+            if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+                bad(`action_risk_value.${a} must be a finite number >= 0`);
+            values[a] = v;
+        }
+    }
+    return { max_expected_loss: { amount: loss.amount, currency }, revocation_rate_per_hour: rates, require: [...new Set(require)], max_age_seconds: ceiling, max_clock_skew_seconds: skew, unvalued_action: unvalued, past_valid_until: pastValid, action_risk_value: values, max_age: input.max_age };
+}
+/** The value at risk of an action: its amount, or else the risk value the policy gives its name. */
+export function valueAtRisk(policy, amount, action) {
+    if (amount !== undefined)
+        return amount;
+    const a = action?.trim().toLowerCase();
+    return a && Object.hasOwn(policy.action_risk_value, a) ? policy.action_risk_value[a] : undefined;
 }
-/** Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency). */
-export function maxStatusAgeSeconds(policy, kind, amount) {
+/**
+ * Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency) or, with no
+ * amount, of the risk value the policy assigns to `action`.
+ */
+export function maxStatusAgeSeconds(policy, kind, amount, action) {
     const ceiling = policy.max_age_seconds;
+    const value = valueAtRisk(policy, amount, action);
     let seconds;
     if (policy.max_age) {
-        seconds = policy.max_age({ amount, currency: policy.max_expected_loss.currency, kind });
+        seconds = policy.max_age({ amount: value, currency: policy.max_expected_loss.currency, kind, action: action?.trim().toLowerCase() || undefined });
     }
     else {
         const rate = policy.revocation_rate_per_hour[kind] ?? 0;
-        if (amount === undefined || amount <= 0 || rate === 0)
+        if (value === undefined || value <= 0 || rate === 0)
             return ceiling;
-        seconds = (policy.max_expected_loss.amount / (amount * rate)) * 3600;
+        seconds = (policy.max_expected_loss.amount / (value * rate)) * 3600;
     }
     if (!Number.isFinite(seconds) || seconds < 0)
         return seconds === Infinity ? ceiling : 0;
@@ -88,91 +119,122 @@ function human(seconds) {
         return `${Math.floor(seconds / 3600)} h`;
     return `${Math.floor(seconds / 86_400)} d`;
 }
+function failAll(policy, detail) {
+    return policy.require.map((kind) => ({ rule: "freshness", kind, ok: false, detail, age_seconds: null, max_age_seconds: 0 }));
+}
+/** Why the action cannot be judged at all (bad clock, bad amount, other currency, unknown value refused), or null. */
+function preconditionProblem(policy, nowValid, amountValid, qCurrency, c) {
+    const currency = policy.max_expected_loss.currency;
+    if (!nowValid)
+        return "the verifier's clock is not a valid date";
+    if (!amountValid)
+        return "amount is not a finite number >= 0";
+    if (qCurrency && qCurrency !== currency)
+        return `loss tolerance is in ${currency}, operation in ${qCurrency}`;
+    if (c.value === undefined && c.amount === undefined && policy.unvalued_action === "refuse") {
+        const subject = c.action ? `"${c.action}"` : "an unnamed action";
+        return `no amount and no risk value for ${subject}; the policy refuses actions of unknown value`;
+    }
+    return null;
+}
+/** What the limit is based on, for the verdict's text. */
+function basisOf(c, currency) {
+    if (c.amount !== undefined)
+        return `for ${c.amount} ${currency}`;
+    if (c.value !== undefined)
+        return `for "${c.action}" (risk value ${c.value} ${currency})`;
+    const forAction = c.action ? ` and no risk value for "${c.action}"` : "";
+    return `no amount${forAction}, ceiling applies`;
+}
+/** The evidence with the latest as_of: a newer statement supersedes an older one, whatever it says. */
+function freshestOf(usable) {
+    let e = usable[0];
+    let asOf = Date.parse(e.as_of);
+    for (const candidate of usable) {
+        const t = Date.parse(candidate.as_of);
+        if (t > asOf) {
+            e = candidate;
+            asOf = t;
+        }
+    }
+    return { e, asOf };
+}
+function isPastValidity(e, nowMs) {
+    if (!e.valid_until)
+        return false;
+    const until = Date.parse(e.valid_until);
+    return !Number.isNaN(until) && until < nowMs;
+}
+/** One required kind: its check, and whether fresher (or any) evidence would change the answer. */
+function checkKind(kind, evidence, c) {
+    const { policy, nowMs } = c;
+    const max = maxStatusAgeSeconds(policy, kind, c.amount, c.action);
+    const limit = `${basisOf(c, policy.max_expected_loss.currency)}: at most ${human(max)}`;
+    const result = (ok, detail, age, refresh = false) => ({ check: { rule: "freshness", kind, ok, detail, age_seconds: age, max_age_seconds: max }, refresh });
+    const usable = evidence.filter((e) => e && e.kind === kind && !Number.isNaN(Date.parse(e.as_of)));
+    if (!usable.length)
+        return result(false, `no ${kind} status evidence; ${limit}`, null, true);
+    const { e, asOf } = freshestOf(usable);
+    const age = Math.floor((nowMs - asOf) / 1000);
+    const ageShown = Math.max(0, age);
+    const from = e.source ? ` (${e.source})` : "";
+    if (asOf - nowMs > policy.max_clock_skew_seconds * 1000) {
+        return result(false, `${kind} evidence${from} is dated ${e.as_of}, after the verifier's clock ${c.nowText} beyond the ${policy.max_clock_skew_seconds} s tolerance`, age);
+    }
+    if (policy.past_valid_until === "refuse" && isPastValidity(e, nowMs))
+        return result(false, `${kind} evidence${from} expired at ${e.valid_until}`, ageShown, true);
+    if (!e.in_force) {
+        const status = e.status ? ` (${e.status})` : "";
+        return result(false, `${kind} is not in force${status} as of ${e.as_of}${from}`, ageShown);
+    }
+    const fresh = ageShown <= max;
+    return result(fresh, `${kind} status${from} is ${human(ageShown)} old; ${limit}`, ageShown, !fresh);
+}
 /**
  * Checks that, for every kind the policy requires, the freshest evidence given says "in force", is not
- * past its own validity, is not dated in the future beyond the clock skew, and is younger than the maximum
- * age for this amount. Fails closed: missing, malformed or foreign-currency input never passes.
+ * past its own validity (unless the policy accepts that), is not dated in the future beyond the clock skew,
+ * and is younger than the maximum age for this value. Fails closed: missing, malformed or foreign-currency
+ * input never passes.
  */
-export function checkFreshness(policy, evidence, q = {}) {
-    const now = q.now ?? new Date();
-    const nowMs = now.getTime();
-    const currency = policy.max_expected_loss.currency;
-    const qCurrency = q.currency?.trim().toUpperCase();
+export function checkFreshness(policy, evidence, q) {
+    const now = q.now;
+    const nowValid = now instanceof Date && !Number.isNaN(now.getTime());
     const amount = q.amount;
+    const action = q.action?.trim().toLowerCase() || undefined;
+    const amountValid = amount === undefined || (typeof amount === "number" && Number.isFinite(amount) && amount >= 0);
+    const value = amountValid ? valueAtRisk(policy, amount, action) : undefined;
+    const nowText = nowValid ? now.toISOString() : "invalid";
     const applied = {
-        now: Number.isNaN(nowMs) ? "invalid" : now.toISOString(),
+        now: nowText,
+        action: action ?? null,
         amount: amount ?? null,
-        currency,
+        value_at_risk: value ?? null,
+        currency: policy.max_expected_loss.currency,
         max_expected_loss: policy.max_expected_loss,
         revocation_rate_per_hour: policy.revocation_rate_per_hour,
         max_age_seconds: policy.max_age_seconds,
         max_clock_skew_seconds: policy.max_clock_skew_seconds,
+        unvalued_action: policy.unvalued_action,
+        past_valid_until: policy.past_valid_until,
         custom_max_age: !!policy.max_age
     };
-    const checks = [];
-    const refresh = [];
-    if (Number.isNaN(nowMs)) {
-        for (const kind of policy.require)
-            checks.push({ rule: "freshness", kind, ok: false, detail: "the verifier's clock is not a valid date", age_seconds: null, max_age_seconds: 0 });
-        return { ok: false, checks, refresh, applied };
-    }
-    const amountOk = amount === undefined || (typeof amount === "number" && Number.isFinite(amount) && amount >= 0);
-    if (!amountOk || (qCurrency && qCurrency !== currency)) {
-        const detail = !amountOk ? "amount is not a finite number >= 0" : `loss tolerance is in ${currency}, operation in ${qCurrency}`;
-        for (const kind of policy.require)
-            checks.push({ rule: "freshness", kind, ok: false, detail, age_seconds: null, max_age_seconds: 0 });
-        return { ok: false, checks, refresh, applied };
-    }
-    for (const kind of policy.require) {
-        const max = maxStatusAgeSeconds(policy, kind, amount);
-        const limit = `${amount === undefined ? "no amount given, ceiling applies" : `for ${amount} ${currency}`}: at most ${human(max)}`;
-        const usable = evidence.filter((e) => e && e.kind === kind && !Number.isNaN(Date.parse(e.as_of)));
-        if (!usable.length) {
-            checks.push({ rule: "freshness", kind, ok: false, detail: `no ${kind} status evidence; ${limit}`, age_seconds: null, max_age_seconds: max });
-            refresh.push(kind);
-            continue;
-        }
-        // Freshest first: a newer statement supersedes an older one, whatever it says.
-        let e = usable[0];
-        let asOf = Date.parse(e.as_of);
-        for (const candidate of usable) {
-            const t = Date.parse(candidate.as_of);
-            if (t > asOf) {
-                e = candidate;
-                asOf = t;
-            }
-        }
-        const age = Math.floor((nowMs - asOf) / 1000);
-        const from = e.source ? ` (${e.source})` : "";
-        if (asOf - nowMs > policy.max_clock_skew_seconds * 1000) {
-            checks.push({ rule: "freshness", kind, ok: false, detail: `${kind} evidence${from} is dated ${e.as_of}, after the verifier's clock ${applied.now} beyond the ${policy.max_clock_skew_seconds} s tolerance`, age_seconds: age, max_age_seconds: max });
-            continue;
-        }
-        if (e.valid_until && !Number.isNaN(Date.parse(e.valid_until)) && Date.parse(e.valid_until) < nowMs) {
-            checks.push({ rule: "freshness", kind, ok: false, detail: `${kind} evidence${from} expired at ${e.valid_until}`, age_seconds: Math.max(0, age), max_age_seconds: max });
-            refresh.push(kind);
-            continue;
-        }
-        if (!e.in_force) {
-            checks.push({ rule: "freshness", kind, ok: false, detail: `${kind} is not in force${e.status ? ` (${e.status})` : ""} as of ${e.as_of}${from}`, age_seconds: Math.max(0, age), max_age_seconds: max });
-            continue;
-        }
-        const ageShown = Math.max(0, age);
-        const fresh = ageShown <= max;
-        checks.push({ rule: "freshness", kind, ok: fresh, detail: `${kind} status${from} is ${human(ageShown)} old; ${limit}`, age_seconds: ageShown, max_age_seconds: max });
-        if (!fresh)
-            refresh.push(kind);
-    }
-    return { ok: checks.length > 0 && checks.every((c) => c.ok), checks, refresh, applied };
+    const c = { policy, nowMs: nowValid ? now.getTime() : Number.NaN, nowText, amount, action, value };
+    const problem = preconditionProblem(policy, nowValid, amountValid, q.currency?.trim().toUpperCase(), c);
+    if (problem)
+        return { ok: false, checks: failAll(policy, problem), refresh: [], applied };
+    const results = policy.require.map((kind) => checkKind(kind, evidence, c));
+    const checks = results.map((r) => r.check);
+    const refresh = policy.require.filter((_, i) => results[i].refresh);
+    return { ok: checks.length > 0 && checks.every((x) => x.ok), checks, refresh, applied };
 }
 /**
  * The mandate (checkAction) and the freshness of the status, in one answer: allowed only when both pass.
- * The freshness check uses the action's amount and currency and the same clock.
+ * The freshness check uses the action's name, amount and currency and the same clock.
  */
 export function checkFreshAction(mandate, q, p) {
-    const now = q.now ?? new Date();
+    const now = q.now;
     const m = checkAction(mandate, { ...q, now });
-    const f = checkFreshness(p.policy, p.evidence, { amount: q.amount, currency: q.currency, now });
+    const f = checkFreshness(p.policy, p.evidence, { action: q.action, amount: q.amount, currency: q.currency, now });
     return { allowed: m.allowed && f.ok, mandate: m, freshness: f };
 }
 /** Evidence about the certificate from a CRL lookup (checkRevocation / verifyCrl().lookup). */

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

@@ -26,11 +26,16 @@ export interface VerifiedCrl {
 }
 /**
  * Parses and verifies a DER CRL against `issuerCertificate` (base64 DER). Throws REVOCATION_UNAVAILABLE
- * when the CRL cannot be trusted (bad encoding, other issuer, bad signature, stale).
+ * when the CRL cannot be trusted (bad encoding, other issuer, bad signature).
+ *
+ * `pastNextUpdate` is the caller's choice for a CRL whose nextUpdate has passed: "refuse" throws (the usual
+ * reading of RFC 5280); "accept" returns it, still reporting next_update, for callers that bound the risk by
+ * the CRL's age instead (Li and Feigenbaum, FC 2001; SPEC section 18).
  */
 export declare function verifyCrl(p: {
     crlDer: ArrayBuffer | Uint8Array;
     issuerCertificate: string;
+    pastNextUpdate: "refuse" | "accept";
     now?: Date;
 }): Promise<VerifiedCrl>;
 /** One-shot check of `serial` against a DER CRL signed by `issuerCertificate`; see verifyCrl. */
@@ -38,6 +43,7 @@ export declare function checkRevocation(p: {
     crlDer: ArrayBuffer | Uint8Array;
     serial: string;
     issuerCertificate: string;
+    pastNextUpdate: "refuse" | "accept";
     now?: Date;
 }): Promise<RevocationStatus>;
 /**

package/dist/revocation.js

@@ -27,9 +27,15 @@ export function crlUrlsOf(cert) {
 }
 /**
  * Parses and verifies a DER CRL against `issuerCertificate` (base64 DER). Throws REVOCATION_UNAVAILABLE
- * when the CRL cannot be trusted (bad encoding, other issuer, bad signature, stale).
+ * when the CRL cannot be trusted (bad encoding, other issuer, bad signature).
+ *
+ * `pastNextUpdate` is the caller's choice for a CRL whose nextUpdate has passed: "refuse" throws (the usual
+ * reading of RFC 5280); "accept" returns it, still reporting next_update, for callers that bound the risk by
+ * the CRL's age instead (Li and Feigenbaum, FC 2001; SPEC section 18).
  */
 export async function verifyCrl(p) {
+    if (p.pastNextUpdate !== "refuse" && p.pastNextUpdate !== "accept")
+        throw new KyaError("INVALID_INPUT", 'pastNextUpdate is required: "refuse" or "accept"');
     const now = p.now ?? new Date();
     let crl;
     let issuer;
@@ -44,7 +50,7 @@ export async function verifyCrl(p) {
         throw new KyaError("REVOCATION_UNAVAILABLE", `CRL issued by "${crl.issuer}", not by the certificate's AC "${issuer.subject}"`);
     if (!(await crl.verify({ publicKey: issuer }, globalThis.crypto)))
         throw new KyaError("REVOCATION_UNAVAILABLE", "CRL signature does not match the AC certificate");
-    if (crl.nextUpdate && crl.nextUpdate < now)
+    if (p.pastNextUpdate === "refuse" && crl.nextUpdate && crl.nextUpdate < now)
         throw new KyaError("REVOCATION_UNAVAILABLE", `CRL is stale (nextUpdate ${crl.nextUpdate.toISOString()})`);
     const this_update = crl.thisUpdate.toISOString();
     const next_update = crl.nextUpdate ? crl.nextUpdate.toISOString() : null;

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.12.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",