@kya-brasil/core 0.11.0 → 0.13.0

package/README.md

@@ -58,6 +58,47 @@ 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 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
+  require: ["credential"],                                          // add "certificate" to also require a CRL
+  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, pastNextUpdate: "accept" })));
+
+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
+```
+
+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)
 
 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,150 @@
+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 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: 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;
+    /**
+     * 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 {
+    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;
+    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;
+/** 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;
+    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;
+        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;
+            currency: string;
+        };
+        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 (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: {
+    action?: string;
+    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 name, amount and currency and the same clock.
+ */
+export declare function checkFreshAction(mandate: Mandate, q: ActionQuery & {
+    now: Date;
+}, 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,268 @@
+/**
+ * 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.
+ *
+ * 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";
+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}`);
+}
+/** 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;
+    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;
+    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");
+    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) 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: value, currency: policy.max_expected_loss.currency, kind, action: action?.trim().toLowerCase() || undefined });
+    }
+    else {
+        const rate = policy.revocation_rate_per_hour[kind] ?? 0;
+        if (value === undefined || value <= 0 || rate === 0)
+            return ceiling;
+        seconds = (policy.max_expected_loss.amount / (value * 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`;
+}
+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 (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;
+    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: nowText,
+        action: action ?? null,
+        amount: amount ?? null,
+        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 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 name, amount and currency and the same clock.
+ */
+export function checkFreshAction(mandate, q, p) {
+    const now = q.now;
+    const m = checkAction(mandate, { ...q, 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). */
+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/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/package.json

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