@kya-brasil/core 0.11.0 → 0.12.0

package/README.md

@@ -58,6 +58,36 @@ const verdict = checkDelegatedAction(r.mandates, { action: "quote", amount: 80,
 To delegate, `prepareDelegation({ credential, chain, delegate, mandate, ttlSeconds })` returns the delegation and
 the text the delegator signs with its agent key; `mandateSubsetProblems(parent, child)` says why a mandate is broader.
 
+## Status freshness proportional to the amount (offline)
+
+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):
+
+```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
+  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
+});
+
+// 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 })));
+
+const r = checkFreshAction(credential.mandate, { action: "buy", amount: 4200, currency: "BRL" }, { 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".
+`checkFreshness` and `maxStatusAgeSeconds` are available on their own.
+
 ## Payment instruments (card networks, acquirers, issuers)
 
 A mandate can list the instruments the agent may pay with. Each one is a network and the SHA-256 of a reference

package/dist/freshness.d.ts

@@ -0,0 +1,119 @@
+import { type ActionQuery, type ActionVerdict } from "./mandate.js";
+import { type Mandate } from "./types.js";
+import type { RevocationStatus } from "./revocation.js";
+/** What a piece of evidence is about: the KYA credential (issuer status) or the ICP-Brasil certificate (CRL). */
+export type EvidenceKind = "credential" | "certificate";
+export interface StatusEvidence {
+    kind: EvidenceKind;
+    /** True when the evidence says the subject is in force: credential `active`, certificate not on the CRL. */
+    in_force: boolean;
+    /** Instant at which the status was true: the issuer's `attestation.signed_at`, or the CRL's thisUpdate. */
+    as_of: string;
+    /** Instant after which the evidence must not be used at all (a CRL's nextUpdate). */
+    valid_until?: string | null;
+    /** Free text for the verdict, e.g. "issuer verdict" or "CRL of AC X". */
+    source?: string;
+    /** 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: {
+        amount: number;
+        currency: string;
+    };
+    /** λ: 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;
+    /**
+     * 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.
+     */
+    max_age?: (p: {
+        amount: number | undefined;
+        currency: string;
+        kind: EvidenceKind;
+    }) => number;
+}
+export interface FreshnessPolicy {
+    max_expected_loss: {
+        amount: number;
+        currency: string;
+    };
+    revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
+    require: EvidenceKind[];
+    max_age_seconds: number;
+    max_clock_skew_seconds: 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;
+export interface FreshnessCheck {
+    rule: "freshness";
+    kind: EvidenceKind;
+    ok: boolean;
+    detail: string;
+    age_seconds: number | null;
+    max_age_seconds: number;
+}
+export interface FreshnessVerdict {
+    ok: boolean;
+    checks: FreshnessCheck[];
+    /** Kinds for which fresher (or any) evidence would change the answer: fetch it, or ask the agent for it. */
+    refresh: EvidenceKind[];
+    /** The policy and clock actually applied, to keep with the verdict as proof of the risk accepted. */
+    applied: {
+        now: string;
+        amount: number | null;
+        currency: string;
+        max_expected_loss: {
+            amount: number;
+            currency: string;
+        };
+        revocation_rate_per_hour: Partial<Record<EvidenceKind, number>>;
+        max_age_seconds: number;
+        max_clock_skew_seconds: number;
+        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.
+ */
+export declare function checkFreshness(policy: FreshnessPolicy, evidence: StatusEvidence[], q?: {
+    amount?: number;
+    currency?: string;
+    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.
+ */
+export declare function checkFreshAction(mandate: Mandate, q: ActionQuery, p: {
+    policy: FreshnessPolicy;
+    evidence: StatusEvidence[];
+}): {
+    allowed: boolean;
+    mandate: ActionVerdict;
+    freshness: FreshnessVerdict;
+};
+/** Evidence about the certificate from a CRL lookup (checkRevocation / verifyCrl().lookup). */
+export declare function evidenceFromRevocation(r: RevocationStatus, source?: string): StatusEvidence;
+/**
+ * Evidence about the credential from an answer the issuer signed (a verdict from /allowed, a paid
+ * verification receipt): any answer carrying `credential_id`, `status` and an Ed25519 `attestation`. The
+ * agent can staple such an answer to its request so the verifier needs no network. The answer must be
+ * about `credentialId` and verify with the issuer's key; the status instant is the signature's.
+ */
+export declare function evidenceFromSignedStatus(answer: Record<string, unknown>, issuerPublicJwk: JsonWebKey, credentialId: string): Promise<StatusEvidence>;

package/dist/freshness.js

@@ -0,0 +1,206 @@
+/**
+ * Status freshness proportional to what is at stake (D-32, SPEC section 18).
+ *
+ * A verifier working offline holds evidence of status that is some time old: an issuer answer signed at a
+ * given instant (the credential's status), or a CRL issued at a given instant (the e-CNPJ / e-CPF
+ * certificate's status). Following Rivest (1998), the recency requirement is set by whoever accepts the
+ * action and runs the risk, not by the issuer: this module turns the verifier's loss tolerance into a
+ * maximum evidence age that shrinks as the amount grows, and refuses older evidence.
+ *
+ * Expected loss of accepting an action of value v on evidence of age t, when status changes at a rate of
+ * λ per hour: v × λ × t. Keeping it under the tolerance L gives the default maximum age
+ *
+ *     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.
+ */
+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}$/;
+function bad(message) {
+    throw new KyaError("INVALID_INPUT", `freshness policy: ${message}`);
+}
+/** Validates and normalizes a policy. Throws INVALID_INPUT on anything that would make it fail open. */
+export function freshnessPolicy(input) {
+    if (!input || typeof input !== "object")
+        bad("expected an object");
+    const loss = input.max_expected_loss;
+    if (!loss || typeof loss.amount !== "number" || !Number.isFinite(loss.amount) || loss.amount < 0)
+        bad("max_expected_loss.amount must be a finite number >= 0");
+    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"];
+    if (!Array.isArray(require) || !require.length || require.some((k) => !KINDS.includes(k)))
+        bad(`require must list one or more of ${KINDS.join(", ")}`);
+    const rates = {};
+    for (const [k, v] of Object.entries(input.revocation_rate_per_hour ?? {})) {
+        if (!KINDS.includes(k))
+            bad(`unknown evidence kind "${k}" in revocation_rate_per_hour`);
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+            bad(`revocation_rate_per_hour.${k} must be a finite number >= 0`);
+        rates[k] = v;
+    }
+    if (!input.max_age)
+        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");
+    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 };
+}
+/** Maximum evidence age, in whole seconds, for an action of `amount` (in the policy's currency). */
+export function maxStatusAgeSeconds(policy, kind, amount) {
+    const ceiling = policy.max_age_seconds;
+    let seconds;
+    if (policy.max_age) {
+        seconds = policy.max_age({ amount, currency: policy.max_expected_loss.currency, kind });
+    }
+    else {
+        const rate = policy.revocation_rate_per_hour[kind] ?? 0;
+        if (amount === undefined || amount <= 0 || rate === 0)
+            return ceiling;
+        seconds = (policy.max_expected_loss.amount / (amount * rate)) * 3600;
+    }
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return seconds === Infinity ? ceiling : 0;
+    // The epsilon keeps binary rounding (1 / (10000 × 1e-4) × 3600 = 3599.999…) from costing a whole second.
+    return Math.min(ceiling, Math.floor(seconds + 1e-6));
+}
+function human(seconds) {
+    if (seconds < 120)
+        return `${seconds} s`;
+    if (seconds < 7200)
+        return `${Math.floor(seconds / 60)} min`;
+    if (seconds < 172_800)
+        return `${Math.floor(seconds / 3600)} h`;
+    return `${Math.floor(seconds / 86_400)} d`;
+}
+/**
+ * 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.
+ */
+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();
+    const amount = q.amount;
+    const applied = {
+        now: Number.isNaN(nowMs) ? "invalid" : now.toISOString(),
+        amount: amount ?? null,
+        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,
+        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 };
+}
+/**
+ * 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.
+ */
+export function checkFreshAction(mandate, q, p) {
+    const now = q.now ?? new Date();
+    const m = checkAction(mandate, { ...q, now });
+    const f = checkFreshness(p.policy, p.evidence, { 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). */
+export function evidenceFromRevocation(r, source) {
+    return {
+        kind: "certificate",
+        in_force: !r.revoked,
+        as_of: r.crl_this_update,
+        valid_until: r.crl_next_update,
+        source: source ?? "CRL",
+        status: r.revoked ? (r.reason ?? "revoked") : "not revoked"
+    };
+}
+/**
+ * Evidence about the credential from an answer the issuer signed (a verdict from /allowed, a paid
+ * verification receipt): any answer carrying `credential_id`, `status` and an Ed25519 `attestation`. The
+ * agent can staple such an answer to its request so the verifier needs no network. The answer must be
+ * about `credentialId` and verify with the issuer's key; the status instant is the signature's.
+ */
+export async function evidenceFromSignedStatus(answer, issuerPublicJwk, credentialId) {
+    if (!answer || typeof answer !== "object")
+        throw new KyaError("INVALID_INPUT", "signed status: expected an object");
+    if (answer.credential_id !== credentialId)
+        throw new KyaError("INVALID_INPUT", `signed status is about ${String(answer.credential_id)}, not ${credentialId}`);
+    if (typeof answer.status !== "string")
+        throw new KyaError("INVALID_INPUT", "signed status has no status");
+    const sig = await verifyAttestation(answer, issuerPublicJwk);
+    if (!sig.valid || !sig.signed_at)
+        throw new KyaError("INVALID_INPUT", `signed status does not verify: ${sig.reason ?? "no signature time"}`);
+    return { kind: "credential", in_force: answer.status === "active", as_of: sig.signed_at, source: "issuer signed status", status: answer.status };
+}

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export * from "./ecnpj-sign.js";
 export * from "./cloud-sign.js";
 export * from "./person.js";
 export * from "./delegation.js";
+export * from "./freshness.js";

package/dist/index.js

@@ -11,3 +11,4 @@ export * from "./ecnpj-sign.js";
 export * from "./cloud-sign.js";
 export * from "./person.js";
 export * from "./delegation.js";
+export * from "./freshness.js";

package/package.json

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