@kya-brasil/agent-tools 0.11.0 → 0.12.0

package/README.md

@@ -117,6 +117,47 @@ const headers = await signRequest({ credentialId, key: subKey, delegation: chain
 Short-lived (at most `max_ttl_seconds`, never past the credential), contained in the parent mandate, at most 3
 levels; revoking the credential ends the whole tree. The issuer stores nothing. [SPEC](https://github.com/celfons/kya-brasil/blob/main/docs/SPEC.md) section 17.
 
+### Verify without the issuer (offline)
+
+Opt-in. The agent sends its credential and the principal's proof with the request; the middleware checks them
+against ICP-Brasil alone and never calls the issuer (or any network: the certificate's status is your callback).
+Works with self-issued credentials (`issuer: "urn:kya-brasil:self"`, issued with `@kya-brasil/core`'s
+`assembleCredential`) and with credentials from an issuer whose public key you list.
+
+```ts
+import { createKyaAuth, signRequest } from "@kya-brasil/agent-tools";
+import { checkRevocation, evidenceFromRevocation } from "@kya-brasil/core";
+
+// agent: credential and proof as assembleCredential returned them (or the issuer's credential + your .p7s proof)
+const headers = await signRequest({ credentialId, key, method: "POST", url, body, present: { credential, proof } });
+
+// server: nothing has a default; construction throws without anchors, now or certificateStatus
+const auth = createKyaAuth({
+  offline: {
+    anchors: icpBrasilRoots,                         // base64 DER / PEM
+    now: () => new Date(),                           // your clock
+    certificateStatus: async ({ revocation }) =>     // you fetch and cache the CRL
+      evidenceFromRevocation(await checkRevocation({ crlDer: await myCrl(revocation.crl_urls), serial: revocation.serial_number,
+        issuerCertificate: revocation.issuer_certificate!, pastNextUpdate: "refuse", now: new Date() })),
+    // freshness: { ... },                         // optional, SPEC section 18 (freshnessPolicy): check() also runs checkFreshAction
+    issuerKeys: { "https://kya-br-agents.marcelfons.workers.dev": issuerJwk }, // optional; others are refused
+    issuerFallback: false                            // optional: true sends requests without the credential to the issuer
+  }
+});
+```
+
+Headers: `KYA-Credential-Document` (base64url of the credential's JSON) and `KYA-Principal-Proof`, plus
+`KYA-Delegation` for a sub-agent. The middleware verifies the request signature (agent or last delegate), the
+proof (`verifySelfIssuedCredential`, or `verifyPrincipalProof` and the issuer's attestation), the delegation
+chain at your clock, and the certificate's status; `kya.offline` holds the evidence, and `check()` / `allowed()`
+evaluate every mandate locally (`allowed()` returns an unsigned local verdict). New errors:
+`KYA_CREDENTIAL_MISSING`, `KYA_CREDENTIAL_MALFORMED`, `KYA_CREDENTIAL_MISMATCH`, `KYA_PRINCIPAL_PROOF_MISSING`,
+`KYA_PRINCIPAL_PROOF_MALFORMED`, `KYA_PRINCIPAL_PROOF_INVALID`, `KYA_ISSUER_NOT_TRUSTED`,
+`KYA_CREDENTIAL_SIGNATURE_INVALID`, `KYA_CERTIFICATE_REVOKED`, `KYA_CERTIFICATE_STATUS_UNKNOWN`,
+`KYA_CERTIFICATE_STATUS_STALE` (403), `KYA_CERTIFICATE_STATUS_UNAVAILABLE` (502), `KYA_CLOCK_INVALID` (502).
+What it cannot see: a revocation or suspension made only at an issuer; daily ceilings need your `spent_today`.
+The headers carry the principal's certificate (personal data for an e-CPF): treat them as such.
+
 ## Person: an agent that acts for you (e-CPF)
 
 ```ts

package/dist/auth.d.ts

@@ -1,5 +1,11 @@
-import { type Delegation, type DelegationAnchor } from "@kya-brasil/core";
+import { type Delegation, type DelegationAnchor, type FreshnessVerdict, type PrincipalProof, type StatusEvidence } from "@kya-brasil/core";
 import { type ActionQuery, type AgentKey, type Credential, type CredentialStatus, type KyaClient, type Mandate, type Verdict, type Verification, type KyaOptions } from "./index.js";
+import { type KyaOfflineOptions } from "./offline.js";
+export { type CertificateStatusQuery, type KyaOfflineOptions, decodeCredentialHeader, encodeCredentialHeader } from "./offline.js";
+/**
+ * Request headers. `credentialDocument` and `principalProof` are sent only to verifiers that work without the
+ * issuer (offline option): the credential's JSON and the principal's proof, both base64url.
+ */
 export declare const KYA_HEADERS: {
     readonly credential: "kya-credential";
     readonly created: "kya-created";
@@ -7,6 +13,8 @@ export declare const KYA_HEADERS: {
     readonly signature: "kya-signature";
     readonly content: "kya-content-sha256";
     readonly delegation: "kya-delegation";
+    readonly credentialDocument: "kya-credential-document";
+    readonly principalProof: "kya-principal-proof";
 };
 export type { Delegation } from "@kya-brasil/core";
 export declare function sha256Hex(data: string | ArrayBuffer | Uint8Array): Promise<string>;
@@ -30,7 +38,8 @@ export type SigningKey = {
 };
 /**
  * Signs a request with the agent key and returns the KYA headers to send with it. A sub-agent passes its
- * `delegation` chain (from signDelegation) and signs with its own key.
+ * `delegation` chain (from signDelegation) and signs with its own key. `present` adds the credential and the
+ * principal's proof (KYA-Credential-Document, KYA-Principal-Proof) for verifiers that work without the issuer.
  */
 export declare function signRequest(p: {
     credentialId: string;
@@ -41,6 +50,10 @@ export declare function signRequest(p: {
     ttlSeconds?: number;
     now?: Date;
     delegation?: Delegation[];
+    present?: {
+        credential: Credential | object;
+        proof: PrincipalProof;
+    };
 }): Promise<Record<string, string>>;
 /** The key a signing key verifies as, in the form a credential or a delegation names it. */
 export declare function agentKeyOf(key: SigningKey): Promise<AgentKey>;
@@ -71,6 +84,12 @@ export interface KyaAuthOptions extends KyaOptions {
     maxTtlSeconds?: number;
     /** Verify the body hash when the request has a body. Default true. */
     requireBodyHash?: boolean;
+    /**
+     * Opt-in: accept requests that carry their own credential and principal's proof, with no issuer in the path
+     * (SPEC sections 14, 18-20). Trust anchors, clock and certificate status are required (construction throws
+     * without them); see KyaOfflineOptions. Absent: behaviour unchanged.
+     */
+    offline?: KyaOfflineOptions;
 }
 export interface KyaContext {
     credential_id: string;
@@ -94,6 +113,17 @@ export interface KyaContext {
     } | null;
     /** Whether the body hash was checked ("verified"), absent from the signature ("none") or not checkable ("skipped"). */
     body: "verified" | "none" | "skipped";
+    /**
+     * Present when the request was verified without the issuer (`offline` option): the credential came with the
+     * request, the principal's proof verified up to your anchors, and `evidence` is what your certificateStatus
+     * returned. check() and allowed() are then local, at your clock (allowed() never calls the issuer).
+     */
+    offline?: {
+        issuer: string;
+        self_issued: boolean;
+        verified_at: string;
+        evidence: StatusEvidence[];
+    };
     /** Local evaluation of the mandate (no daily ceilings; those need the issuer). On a delegated request, of every mandate in the chain. */
     check(q: ActionQuery): LocalVerdict;
     /**
@@ -120,6 +150,8 @@ export interface LocalVerdict {
         detail: string;
     }[];
     not_evaluated: string[];
+    /** Offline mode with a freshness policy: the status freshness verdict (SPEC section 18, checkFreshAction). */
+    freshness?: FreshnessVerdict;
 }
 /**
  * Local evaluation of the reserved mandate fields: actions, max_per_operation, currencies, counterparties

package/dist/auth.js

@@ -31,11 +31,17 @@
  *   content-sha256: <hex of the body | ->
  */
 import { verifyMessage } from "viem";
-import { encodeDelegationHeader, decodeDelegationHeader, prepareDelegation, verifyDelegationChain } from "@kya-brasil/core";
+import { SELF_ISSUER, checkFreshAction, decodePrincipalProofHeader, encodeDelegationHeader, encodePrincipalProofHeader, decodeDelegationHeader, prepareDelegation, verifyDelegationChain } from "@kya-brasil/core";
 import { privateKeyToAccount } from "viem/accounts";
 import { createKyaClient } from "./index.js";
 import { fromBase64Url, toBase64Url } from "./base64url.js";
-export const KYA_HEADERS = { credential: "kya-credential", created: "kya-created", expires: "kya-expires", signature: "kya-signature", content: "kya-content-sha256", delegation: "kya-delegation" };
+import { certificateStatusOf, decodeCredentialHeader, encodeCredentialHeader, resolveOffline, verifyPresentedCredential } from "./offline.js";
+export { decodeCredentialHeader, encodeCredentialHeader } from "./offline.js";
+/**
+ * Request headers. `credentialDocument` and `principalProof` are sent only to verifiers that work without the
+ * issuer (offline option): the credential's JSON and the principal's proof, both base64url.
+ */
+export const KYA_HEADERS = { credential: "kya-credential", created: "kya-created", expires: "kya-expires", signature: "kya-signature", content: "kya-content-sha256", delegation: "kya-delegation", credentialDocument: "kya-credential-document", principalProof: "kya-principal-proof" };
 const enc = new TextEncoder();
 const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 const b64u = toBase64Url;
@@ -72,7 +78,8 @@ async function signText(key, text) {
 }
 /**
  * Signs a request with the agent key and returns the KYA headers to send with it. A sub-agent passes its
- * `delegation` chain (from signDelegation) and signs with its own key.
+ * `delegation` chain (from signDelegation) and signs with its own key. `present` adds the credential and the
+ * principal's proof (KYA-Credential-Document, KYA-Principal-Proof) for verifiers that work without the issuer.
  */
 export async function signRequest(p) {
     const created = Math.floor((p.now ?? new Date()).getTime() / 1000);
@@ -87,6 +94,10 @@ export async function signRequest(p) {
         headers[KYA_HEADERS.content] = contentSha256;
     if (delegationHeader)
         headers[KYA_HEADERS.delegation] = delegationHeader;
+    if (p.present) {
+        headers[KYA_HEADERS.credentialDocument] = encodeCredentialHeader(p.present.credential);
+        headers[KYA_HEADERS.principalProof] = encodePrincipalProofHeader(p.present.proof);
+    }
     return headers;
 }
 /** The key a signing key verifies as, in the form a credential or a delegation names it. */
@@ -189,6 +200,8 @@ const headerOf = (headers, name) => {
     return Array.isArray(v) ? v[0] ?? null : v ?? null;
 };
 export function createKyaAuth(opts = {}) {
+    // Offline mode is opt-in and validated here: missing anchors, clock or certificate status throws.
+    const offline = opts.offline === undefined ? null : resolveOffline(opts.offline);
     const client = createKyaClient(opts);
     const cacheTtl = opts.cacheTtlMs ?? 60_000;
     const maxSkew = opts.maxSkewSeconds ?? 300;
@@ -220,6 +233,11 @@ export function createKyaAuth(opts = {}) {
         }
     }
     const fail = (status, error, message) => ({ ok: false, status, error, message });
+    /** The offline clock, checked on every use (a wrong clock makes stale evidence look fresh). */
+    function offlineNow() {
+        const d = offline?.now();
+        return d instanceof Date && !Number.isNaN(d.getTime()) ? d : null;
+    }
     async function authenticateParts(p) {
         const credentialId = headerOf(p.headers, KYA_HEADERS.credential);
         const created = Number(headerOf(p.headers, KYA_HEADERS.created));
@@ -227,9 +245,14 @@ export function createKyaAuth(opts = {}) {
         const signature = headerOf(p.headers, KYA_HEADERS.signature);
         const contentHeader = headerOf(p.headers, KYA_HEADERS.content);
         const delegationHeader = headerOf(p.headers, KYA_HEADERS.delegation);
+        const document = offline ? headerOf(p.headers, KYA_HEADERS.credentialDocument) : null;
+        const useOffline = offline !== null && (document !== null || !offline.issuerFallback);
         if (!credentialId || !signature || !Number.isFinite(created) || !Number.isFinite(expires))
             return fail(401, "KYA_HEADERS_MISSING", `send ${KYA_HEADERS.credential}, ${KYA_HEADERS.created}, ${KYA_HEADERS.expires} and ${KYA_HEADERS.signature}`);
-        const now = Math.floor(Date.now() / 1000);
+        const at = useOffline ? offlineNow() : new Date();
+        if (!at)
+            return fail(502, "KYA_CLOCK_INVALID", "the verifier's clock (offline.now) did not return a valid Date");
+        const now = Math.floor(at.getTime() / 1000);
         if (created > now + maxSkew)
             return fail(401, "KYA_SIGNATURE_NOT_YET_VALID", "created is in the future");
         if (expires < now)
@@ -250,6 +273,10 @@ export function createKyaAuth(opts = {}) {
         }
         else if (contentHeader)
             bodyState = "skipped";
+        const delegationSha256 = delegationHeader ? await sha256Hex(delegationHeader) : null;
+        const text = requestText({ credentialId, method: p.method, url: p.url, created, expires, contentSha256: contentHeader, delegationSha256 });
+        if (useOffline)
+            return authenticateOffline({ credentialId, document, proofHeader: headerOf(p.headers, KYA_HEADERS.principalProof), delegationHeader, text, signature, bodyState, at });
         let v;
         try {
             v = await verification(credentialId);
@@ -260,20 +287,19 @@ export function createKyaAuth(opts = {}) {
         }
         let delegation = null;
         if (delegationHeader) {
-            const d = await delegationOf(credentialId, v, delegationHeader);
+            if (!v.credential)
+                return fail(403, "KYA_CREDENTIAL_NOT_ACTIVE", `credential is ${v.status}`);
+            const d = await delegationOf(anchorOf(credentialId, v.agent, v.credential), delegationHeader);
             if (!d.ok)
                 return d.result;
             delegation = d.delegation;
         }
-        const delegationSha256 = delegationHeader ? await sha256Hex(delegationHeader) : null;
-        const text = requestText({ credentialId, method: p.method, url: p.url, created, expires, contentSha256: contentHeader, delegationSha256 });
         return finish(credentialId, v, text, signature, bodyState, delegation);
     }
+    const anchorOf = (credentialId, agent, credential) => ({ credential_id: credentialId, agent: agent, mandate: credential.mandate, expires_at: credential.expires_at });
     /** D-30: verifies a KYA-Delegation chain against the credential (offline, core rules). */
-    async function delegationOf(credentialId, v, header) {
+    async function delegationOf(anchor, header, now) {
         const no = (status, error, message) => ({ ok: false, result: fail(status, error, message) });
-        if (!v.credential)
-            return no(403, "KYA_CREDENTIAL_NOT_ACTIVE", `credential is ${v.status}`);
         let chain;
         try {
             chain = decodeDelegationHeader(header);
@@ -281,20 +307,84 @@ export function createKyaAuth(opts = {}) {
         catch (e) {
             return no(401, "KYA_DELEGATION_MALFORMED", e.message);
         }
-        const anchor = { credential_id: credentialId, agent: v.agent, mandate: v.credential.mandate, expires_at: v.credential.expires_at };
-        const r = await verifyDelegationChain({ credential: anchor, chain });
+        const r = await verifyDelegationChain({ credential: anchor, chain, now });
         if (!r.ok)
             return no(r.error === "KYA_DELEGATION_NOT_ALLOWED" || r.error === "KYA_DELEGATION_BROADER" ? 403 : 401, r.error, r.message);
         return { ok: true, delegation: { depth: r.depth, delegate: r.delegate, expires_at: r.expires_at, chain: chain, mandates: r.mandates } };
     }
+    /**
+     * Offline (opt-in): the credential and the principal's proof came with the request. Order: shape, delegation
+     * chain and request signature (cheap, reject strangers before anything else), then the principal's proof up to
+     * the anchors, then the caller's certificate status. No network here.
+     */
+    async function authenticateOffline(p) {
+        const o = offline;
+        if (!p.document)
+            return fail(401, "KYA_CREDENTIAL_MISSING", `this verifier works without the issuer: send ${KYA_HEADERS.credentialDocument} and ${KYA_HEADERS.principalProof}`);
+        let credential;
+        try {
+            credential = decodeCredentialHeader(p.document);
+        }
+        catch (e) {
+            return fail(401, "KYA_CREDENTIAL_MALFORMED", e.message);
+        }
+        if (!credential.agent || typeof credential.agent !== "object" || typeof credential.agent.id !== "string" || !credential.mandate || typeof credential.mandate !== "object" || typeof credential.expires_at !== "string" || !credential.principal || !credential.authorized_by)
+            return fail(401, "KYA_CREDENTIAL_MALFORMED", "KYA-Credential-Document is not a credential");
+        if (credential.credential_id !== p.credentialId)
+            return fail(401, "KYA_CREDENTIAL_MISMATCH", `${KYA_HEADERS.credentialDocument} is credential ${String(credential.credential_id)}, the request names ${p.credentialId}`);
+        if (!p.proofHeader)
+            return fail(401, "KYA_PRINCIPAL_PROOF_MISSING", `send ${KYA_HEADERS.principalProof} with ${KYA_HEADERS.credentialDocument}`);
+        let proof;
+        try {
+            proof = decodePrincipalProofHeader(p.proofHeader);
+        }
+        catch (e) {
+            return fail(401, "KYA_PRINCIPAL_PROOF_MALFORMED", e.message);
+        }
+        let delegation = null;
+        if (p.delegationHeader) {
+            const d = await delegationOf(anchorOf(p.credentialId, credential.agent, credential), p.delegationHeader, p.at);
+            if (!d.ok)
+                return d.result;
+            delegation = d.delegation;
+        }
+        const sig = await verifySignature(delegation ? delegation.delegate : credential.agent, p.text, p.signature);
+        if (!sig.ok)
+            return fail(401, "KYA_BAD_SIGNATURE", delegation ? "signature does not match the delegate's key over the signed text" : "signature does not match the credential's agent key over the signed text");
+        const presented = await verifyPresentedCredential(o, credential, proof, p.at);
+        if (!presented.ok)
+            return fail(presented.status, presented.error, presented.message);
+        const status = await certificateStatusOf(o, { credential, revocation: presented.revocation }, p.at);
+        if (!status.ok)
+            return fail(status.status, status.error, status.message);
+        const v = { credential_id: p.credentialId, status: "active", status_reason: null, agent: credential.agent, principal: credential.principal, credential, events: [] };
+        const info = { issuer: credential.issuer, self_issued: credential.issuer === SELF_ISSUER, verified_at: p.at.toISOString(), evidence: status.evidence };
+        return { ok: true, kya: contextOf(p.credentialId, v, sig.signer, p.bodyState, delegation, info) };
+    }
     async function finish(credentialId, v, text, signature, bodyState, delegation = null) {
         const sig = await verifySignature(delegation ? delegation.delegate : v.agent, text, signature);
         if (!sig.ok)
             return fail(401, "KYA_BAD_SIGNATURE", delegation ? "signature does not match the delegate's key over the signed text" : "signature does not match the credential's agent key over the signed text");
         if (v.status !== "active")
             return fail(403, "KYA_CREDENTIAL_NOT_ACTIVE", `credential is ${v.status}${v.status_reason ? `: ${v.status_reason}` : ""}`);
+        return { ok: true, kya: contextOf(credentialId, v, sig.signer, bodyState, delegation, null) };
+    }
+    function contextOf(credentialId, v, signer, bodyState, delegation, local) {
         const mandate = v.credential?.mandate ?? {};
         const mandates = delegation ? delegation.mandates : [mandate];
+        // Offline: every mandate at the verifier's clock, and, with a freshness policy, checkFreshAction on the evidence.
+        const offlineCheck = (q) => {
+            const at = offlineNow();
+            if (!at)
+                return { allowed: false, checks: [{ rule: "clock", ok: false, detail: "the verifier's clock (offline.now) did not return a valid Date" }], not_evaluated: [] };
+            const base = delegation ? checkMandates(mandates, q, at) : checkMandate(mandate, q, at);
+            const policy = offline.policy;
+            if (!policy || !local)
+                return base;
+            const f = checkFreshAction(mandate, { ...q, now: at }, { policy, evidence: local.evidence });
+            const freshness = f.freshness.checks.map((c) => ({ rule: `freshness (${c.kind})`, ok: c.ok, detail: c.detail }));
+            return { allowed: base.allowed && f.allowed, checks: [...base.checks, ...freshness], not_evaluated: base.not_evaluated, freshness: f.freshness };
+        };
         const ctx = {
             credential_id: credentialId,
             agent: v.agent,
@@ -302,26 +392,34 @@ export function createKyaAuth(opts = {}) {
             status: v.status,
             mandate,
             credential: v.credential,
-            signer: sig.signer,
+            signer,
             body: bodyState,
             delegation,
-            check: (q) => (delegation ? checkMandates(mandates, q) : checkMandate(mandate, q)),
+            ...(local ? { offline: local } : {}),
+            check: (q) => (local ? offlineCheck(q) : delegation ? checkMandates(mandates, q) : checkMandate(mandate, q)),
             allowed: async (q) => {
+                if (local) {
+                    // No issuer to ask: the local verdict, unsigned, in the issuer's shape.
+                    const l = offlineCheck(q);
+                    return { credential_id: credentialId, status: v.status, allowed: l.allowed, reason: l.allowed ? "inside every mandate (verified offline)" : "refused by the mandate or the status freshness (verified offline)", checks: l.checks.map((c) => ({ field: c.rule, ok: c.ok, detail: c.detail })), not_evaluated: l.not_evaluated, offline: true, ...(l.freshness ? { freshness: l.freshness } : {}) };
+                }
                 if (delegation) {
                     for (let i = 1; i < mandates.length; i++) {
-                        const local = checkMandate(mandates[i], q);
-                        if (!local.allowed) {
-                            return { credential_id: credentialId, status: v.status, allowed: false, reason: `outside the mandate of delegation ${i}`, checks: local.checks.map((c) => ({ field: c.rule, ok: c.ok, detail: c.detail })), not_evaluated: local.not_evaluated, delegation_level: i };
+                        const localVerdict = checkMandate(mandates[i], q);
+                        if (!localVerdict.allowed) {
+                            return { credential_id: credentialId, status: v.status, allowed: false, reason: `outside the mandate of delegation ${i}`, checks: localVerdict.checks.map((c) => ({ field: c.rule, ok: c.ok, detail: c.detail })), not_evaluated: localVerdict.not_evaluated, delegation_level: i };
                         }
                     }
                 }
                 return client.allowed(credentialId, q);
             }
         };
-        return { ok: true, kya: ctx };
+        return ctx;
     }
     /** Low level: verify a signature by a credential's agent key over a text you built yourself (used for signed responses). */
     async function verifySigned(p) {
+        if (offline && !offline.issuerFallback)
+            return fail(401, "KYA_CREDENTIAL_MISSING", "this verifier works without the issuer: a bare signature carries no credential to check");
         let v;
         try {
             v = await verification(p.credentialId);

package/dist/offline.d.ts

@@ -0,0 +1,87 @@
+/**
+ * "Sign in with KYA" without the issuer (opt-in): the agent presents its credential and the principal's proof with
+ * the request, and the verifier checks them against ICP-Brasil alone (SPEC sections 14, 18, 19 and 20).
+ *
+ *   KYA-Credential-Document   base64url (no padding) of the credential's JSON
+ *   KYA-Principal-Proof       base64url of { text, cms } (section 19, encodePrincipalProofHeader)
+ *
+ * A credential with `issuer: "urn:kya-brasil:self"` (issued by the principal, section 20) is checked with
+ * verifySelfIssuedCredential; any other with verifyPrincipalProof plus the issuer's attestation, verified with a
+ * public key the caller lists (`issuerKeys`), so the credential's own fields (id, expiry, status) are not the
+ * agent's word. Nothing here fetches: trust anchors, clock and certificate status are the caller's.
+ */
+import { type Credential as CoreCredential, type FreshnessPolicy, type FreshnessPolicyInput, type PrincipalProof, type StatusEvidence } from "@kya-brasil/core";
+import type { Credential } from "./index.js";
+/** What the caller's status callback receives: the credential and where to check its certificate (CRL). */
+export interface CertificateStatusQuery {
+    credential: Credential;
+    /** Serial number, issuing AC certificate (base64 DER, null when the CMS does not carry it) and CRL URLs of the signing certificate. */
+    revocation: {
+        serial_number: string;
+        issuer_certificate: string | null;
+        crl_urls: string[];
+    };
+}
+export interface KyaOfflineOptions {
+    /** ICP-Brasil trust anchors (base64 DER or PEM) the principal's certificate must chain to. Required, non-empty. */
+    anchors: string[];
+    /** The verifier's clock. Required: it decides validity of the certificate, credential, delegation and request window. */
+    now: () => Date;
+    /**
+     * Status of the principal's certificate, for every offline request. Required. Fetch and cache the CRL here (the
+     * middleware never does), e.g. `evidenceFromRevocation(await checkRevocation({ crlDer, serial, issuerCertificate,
+     * pastNextUpdate, now }))`. May also return `credential` evidence (evidenceFromSignedStatus) for the freshness
+     * policy. Throwing answers 502 KYA_CERTIFICATE_STATUS_UNAVAILABLE.
+     */
+    certificateStatus: (q: CertificateStatusQuery) => StatusEvidence | StatusEvidence[] | Promise<StatusEvidence | StatusEvidence[]>;
+    /**
+     * Optional status freshness proportional to the amount (section 18): validated with freshnessPolicy at
+     * construction; check() then also runs checkFreshAction with the evidence above and the clock. Without it the
+     * freshest certificate evidence only has to be in force and not past its valid_until.
+     */
+    freshness?: FreshnessPolicyInput;
+    /**
+     * Issuers whose credentials are accepted offline, by `issuer` value, with the Ed25519 public key that signed the
+     * credential (published at <issuer>/.well-known/kya.json). A credential from an issuer not listed here is refused;
+     * self-issued credentials need no entry.
+     */
+    issuerKeys?: Record<string, JsonWebKey>;
+    /** A request without KYA-Credential-Document goes to the issuer as before when true; refused when false or absent. */
+    issuerFallback?: boolean;
+}
+export interface ResolvedOffline {
+    anchors: string[];
+    now: () => Date;
+    certificateStatus: KyaOfflineOptions["certificateStatus"];
+    policy: FreshnessPolicy | null;
+    issuerKeys: Record<string, JsonWebKey>;
+    issuerFallback: boolean;
+}
+/** Validates the offline options; throws on anything missing (no defaults for risk parameters). */
+export declare function resolveOffline(o: KyaOfflineOptions): ResolvedOffline;
+/** KYA-Credential-Document value: base64url (no padding) of the credential's JSON. */
+export declare function encodeCredentialHeader(credential: Credential | CoreCredential): string;
+/** Parses a KYA-Credential-Document value; throws when it is not base64url JSON of an object. */
+export declare function decodeCredentialHeader(value: string): Credential;
+export type OfflineCredentialResult = {
+    ok: true;
+    revocation: CertificateStatusQuery["revocation"];
+} | {
+    ok: false;
+    status: 401 | 403;
+    error: string;
+    message: string;
+};
+/** Checks the presented credential and proof, without the issuer and without the certificate's status. */
+export declare function verifyPresentedCredential(o: ResolvedOffline, credential: Credential, proof: PrincipalProof, now: Date): Promise<OfflineCredentialResult>;
+export type CertificateStatusResult = {
+    ok: true;
+    evidence: StatusEvidence[];
+} | {
+    ok: false;
+    status: 403 | 502;
+    error: string;
+    message: string;
+};
+/** Asks the caller for the certificate's status and applies it: the freshest certificate evidence must be in force. */
+export declare function certificateStatusOf(o: ResolvedOffline, q: CertificateStatusQuery, now: Date): Promise<CertificateStatusResult>;

package/dist/offline.js

@@ -0,0 +1,108 @@
+/**
+ * "Sign in with KYA" without the issuer (opt-in): the agent presents its credential and the principal's proof with
+ * the request, and the verifier checks them against ICP-Brasil alone (SPEC sections 14, 18, 19 and 20).
+ *
+ *   KYA-Credential-Document   base64url (no padding) of the credential's JSON
+ *   KYA-Principal-Proof       base64url of { text, cms } (section 19, encodePrincipalProofHeader)
+ *
+ * A credential with `issuer: "urn:kya-brasil:self"` (issued by the principal, section 20) is checked with
+ * verifySelfIssuedCredential; any other with verifyPrincipalProof plus the issuer's attestation, verified with a
+ * public key the caller lists (`issuerKeys`), so the credential's own fields (id, expiry, status) are not the
+ * agent's word. Nothing here fetches: trust anchors, clock and certificate status are the caller's.
+ */
+import { SELF_ISSUER, effectiveStatus, freshnessPolicy, verifyCredentialSignature, verifyPrincipalProof, verifySelfIssuedCredential } from "@kya-brasil/core";
+import { fromBase64Url, toBase64Url } from "./base64url.js";
+/** Validates the offline options; throws on anything missing (no defaults for risk parameters). */
+export function resolveOffline(o) {
+    const no = (why) => {
+        throw new Error(`createKyaAuth offline: ${why}`);
+    };
+    if (!o || typeof o !== "object")
+        no("expected an object");
+    if (!Array.isArray(o.anchors) || !o.anchors.length || o.anchors.some((a) => typeof a !== "string" || !a.trim()))
+        no("anchors (ICP-Brasil trust anchors) are required");
+    if (typeof o.now !== "function")
+        no("now (the verifier's clock) is required");
+    if (typeof o.certificateStatus !== "function")
+        no("certificateStatus (the certificate's revocation evidence) is required");
+    if (o.issuerKeys !== undefined && (!o.issuerKeys || typeof o.issuerKeys !== "object" || Array.isArray(o.issuerKeys)))
+        no("issuerKeys must map issuer -> public JWK");
+    if (o.issuerFallback !== undefined && typeof o.issuerFallback !== "boolean")
+        no("issuerFallback must be a boolean");
+    return { anchors: [...o.anchors], now: o.now, certificateStatus: o.certificateStatus, policy: o.freshness === undefined ? null : freshnessPolicy(o.freshness), issuerKeys: { ...(o.issuerKeys ?? {}) }, issuerFallback: o.issuerFallback ?? false };
+}
+/** KYA-Credential-Document value: base64url (no padding) of the credential's JSON. */
+export function encodeCredentialHeader(credential) {
+    return toBase64Url(new TextEncoder().encode(JSON.stringify(credential)));
+}
+/** Parses a KYA-Credential-Document value; throws when it is not base64url JSON of an object. */
+export function decodeCredentialHeader(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(fromBase64Url(value.trim())));
+    }
+    catch {
+        throw new Error("KYA-Credential-Document is not base64url JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("KYA-Credential-Document must be a JSON object");
+    return parsed;
+}
+/** Checks the presented credential and proof, without the issuer and without the certificate's status. */
+export async function verifyPresentedCredential(o, credential, proof, now) {
+    const c = credential;
+    const failed = (checks) => checks.filter((x) => !x.ok);
+    const describe = (checks) => failed(checks).map((x) => `${x.rule}: ${x.detail}`).join("; ");
+    if (c.issuer === SELF_ISSUER) {
+        const r = await verifySelfIssuedCredential({ credential: c, proof, anchors: o.anchors, now });
+        if (r.ok && r.revocation)
+            return { ok: true, revocation: r.revocation };
+        const bad = failed(r.checks);
+        // Only the validity window failed: a sound credential that is not (or no longer) in force.
+        if (bad.length && bad.every((x) => x.rule === "validity"))
+            return { ok: false, status: 403, error: "KYA_CREDENTIAL_NOT_ACTIVE", message: describe(r.checks) };
+        return { ok: false, status: 401, error: "KYA_PRINCIPAL_PROOF_INVALID", message: describe(r.checks) || "proof does not verify" };
+    }
+    const key = typeof c.issuer === "string" && Object.hasOwn(o.issuerKeys, c.issuer) ? o.issuerKeys[c.issuer] : undefined;
+    if (!key)
+        return { ok: false, status: 401, error: "KYA_ISSUER_NOT_TRUSTED", message: `credentials from issuer ${String(c.issuer)} are not accepted offline (list its key in issuerKeys)` };
+    const att = await verifyCredentialSignature(c, key);
+    if (!att.valid)
+        return { ok: false, status: 401, error: "KYA_CREDENTIAL_SIGNATURE_INVALID", message: `issuer attestation: ${att.reason ?? "does not verify"}` };
+    const r = await verifyPrincipalProof({ credential: c, proof, anchors: o.anchors, now });
+    if (!r.ok || !r.revocation)
+        return { ok: false, status: 401, error: "KYA_PRINCIPAL_PROOF_INVALID", message: describe(r.checks) || "proof does not verify" };
+    const issued = Date.parse(c.issued_at);
+    const status = effectiveStatus(c, now);
+    if (!Number.isFinite(issued) || issued > now.getTime())
+        return { ok: false, status: 403, error: "KYA_CREDENTIAL_NOT_ACTIVE", message: `not yet valid (issued ${c.issued_at})` };
+    if (status !== "active")
+        return { ok: false, status: 403, error: "KYA_CREDENTIAL_NOT_ACTIVE", message: `credential is ${status}` };
+    return { ok: true, revocation: r.revocation };
+}
+/** Asks the caller for the certificate's status and applies it: the freshest certificate evidence must be in force. */
+export async function certificateStatusOf(o, q, now) {
+    let evidence;
+    try {
+        const r = await o.certificateStatus(q);
+        evidence = (Array.isArray(r) ? r : [r]).filter((e) => !!e && typeof e === "object");
+    }
+    catch (e) {
+        return { ok: false, status: 502, error: "KYA_CERTIFICATE_STATUS_UNAVAILABLE", message: e?.message ?? String(e) };
+    }
+    const nowMs = now.getTime();
+    const skewMs = (o.policy?.max_clock_skew_seconds ?? 0) * 1000;
+    const certs = evidence.filter((e) => e.kind === "certificate" && Number.isFinite(Date.parse(e.as_of)));
+    if (!certs.length)
+        return { ok: false, status: 403, error: "KYA_CERTIFICATE_STATUS_UNKNOWN", message: "no status evidence for the principal's certificate" };
+    const freshest = certs.reduce((a, b) => (Date.parse(b.as_of) > Date.parse(a.as_of) ? b : a));
+    const from = freshest.source ? ` (${freshest.source})` : "";
+    if (Date.parse(freshest.as_of) - nowMs > skewMs)
+        return { ok: false, status: 403, error: "KYA_CERTIFICATE_STATUS_STALE", message: `certificate evidence${from} is dated ${freshest.as_of}, after the verifier's clock` };
+    if (!freshest.in_force)
+        return { ok: false, status: 403, error: "KYA_CERTIFICATE_REVOKED", message: `the principal's certificate is not in force${freshest.status ? ` (${freshest.status})` : ""} as of ${freshest.as_of}${from}` };
+    const until = freshest.valid_until ? Date.parse(freshest.valid_until) : Number.NaN;
+    if (Number.isFinite(until) && until < nowMs && o.policy?.past_valid_until !== "accept")
+        return { ok: false, status: 403, error: "KYA_CERTIFICATE_STATUS_STALE", message: `certificate evidence${from} expired at ${freshest.valid_until}` };
+    return { ok: true, evidence };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-brasil/agent-tools",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "KYA Brasil for AI agents: verify that an agent acts for a Brazilian company (e-CNPJ-signed credential, revocation and company registration checked daily against the Receita's open data, no third-party service), check an action against its mandate, or give your own agent a credential (sign with the company's e-CNPJ: A1 .pfx or A3 token via PKCS#11, in code or with the kya-sign command). Sign in with KYA middleware (Hono, Express, Workers) and request signing. x402 payments (USDC on Base) handled for you. Adapters for Vercel AI SDK, LangChain, OpenAI and Anthropic.",
   "license": "MIT",
   "type": "module",
@@ -56,7 +56,7 @@
     "@x402/fetch": "^2.28.0",
     "pkijs": "^3.4.1",
     "viem": "^2.57.5",
-    "@kya-brasil/core": "^0.11.0"
+    "@kya-brasil/core": "^0.18.0"
   },
   "devDependencies": {
     "@peculiar/asn1-schema": "^2.3.15",