@crawlcheck/sdk 1.6.0 → 1.8.0

package/README.md

@@ -18,11 +18,17 @@ const { proceed, receipt } = await cc.guard("example.com", "read", { agent: "MyA
 
 Every verification returns `integrity_valid`, `issuer_trusted` and `accepted`. Act on `accepted`: it needs the signing key to be one CrawlCheck publishes, so a document someone signed with their own key is `verified` offline but never `accepted`. The client methods (`verifyDocument`, `verifyOffline`, `verifyReceiptOffline`, `guard`) check the published key directory for you.
 
+Since 1.8.0 an MCP connect decision names the server and, with a lockfile, its approved `tools_sha256` (`preflight(domain, "connect", { mcp: { url, tools_sha256 } })`; `withPreflight` sends it for you). CrawlCheck reads the live tools from its own network: a changed tool list comes back as `block`, and the signed receipt's `assessed` block says exactly which endpoint and tool state it covered.
+
+Since 1.8.0 they also apply the signing policy (https://crawlcheck.io/keys#policy): which key purpose may sign which object at which time (decision receipts move to the decision key at 2026-11-09 17:00 UTC), retired keys (valid only for documents signed before they stopped) and compromised keys (never valid on their signature alone). The result carries `key_policy_valid`, and `accepted` needs it. Offline, build the same input from copies you saved: `keyPolicyFrom(savedDirectory, savedRotationRecord)`, then `applyKeyPolicy(result, doc, kp)` or `guard(domain, action, { onlineKeys: false, keyPolicy })`. A saved copy cannot know a key retired or compromised after you saved it.
+
+`accepted` says who signed a document. It is not permission to act: a valid receipt can say `block`, `warn` or `require_confirmation`. `guard()` decides that part.
+
 `preflight(domain, action, { agent, template, policy })` returns the signed receipt without deciding for you; `verifyDocument(doc)` verifies any signed resolve answer or decision receipt offline. `resolve(domain)` returns the full signed ResolveV1 answer.
 
 ## Give your agent the check as a tool
 
-Two tools your agent can call itself: `crawlcheck_check_site` (the signed, verified decision for an action on a site) and `crawlcheck_fetch` (fetches a page only after its domain, and every redirect hop, is allowed). Both fail closed.
+Three tools your agent can call itself: `crawlcheck_check_site` (the signed, verified decision for an action on a site, including the business facts the site publishes and which AI engines get them wrong), `crawlcheck_verify_fact` (one signed verdict on a phone number, address, hours or service area you hold: does the business publish it, did it once, or whose is it) and `crawlcheck_fetch` (fetches a page only after its domain, and every redirect hop, is allowed). All fail closed.
 
 ```js
 import { CrawlCheck, agentTools, toolsFor } from "@crawlcheck/sdk";

package/dist/index.d.ts

@@ -16,8 +16,50 @@ export interface VerifyCheck {
 export interface Trust {
     integrity_valid: boolean;
     issuer_trusted: boolean | null;
-    accepted: boolean;
+    accepted: boolean; /** conf2: the signing policy accepts this key for this object at its signing time (purpose, retired, compromised). null: not decided. */
+    key_policy_valid?: boolean | null; /** conf2: stable reason: ok, ok_bound, key_wrong_purpose, key_not_yet_active, key_retired, key_compromised, key_unknown, no_signing_time, or related_<code> for a key the document leans on. */
+    key_policy_code?: string | null;
+}
+/** conf2: the key directory and rotation record as the signing policy reads them (keyPolicyFrom / publishedKeyPolicy). */
+export interface KeyPolicyInput {
+    v: 2;
+    kids: string[];
+    keys: Record<string, {
+        purpose: string;
+        start: number | null;
+    }>;
+    retired: Record<string, {
+        purpose: string;
+        stopped: number | null;
+    }>;
+    compromised: Record<string, number>;
+    rotation: boolean;
+    read_at?: string;
+    source?: string;
+}
+export interface KeyPolicyResult {
+    ok: boolean | null;
+    code: string;
+    known: boolean;
+    purpose: string | null;
+    expected: string | null;
+    why: string;
 }
+/** The signing policy as data (https://crawlcheck.io/keys#policy): object purposes, purpose chains, start times. */
+export declare const KEY_POLICY: {
+    v: 2;
+    object_purpose: Record<string, string>;
+    chains: Record<string, string[]>;
+    starts: Record<string, string | null>;
+    bound: Record<string, string>;
+    purpose_aliases: Record<string, string>;
+};
+/** Build the policy input from a key directory you hold and, optionally, the rotation record saved with it. */
+export declare const keyPolicyFrom: (directory: unknown, rotation?: unknown) => Promise<KeyPolicyInput>;
+/** Does the signing policy accept this document's signing key for this object at its signing time? */
+export declare const keyPolicyCheck: (doc: unknown, kp: KeyPolicyInput) => KeyPolicyResult;
+/** Apply the signing policy to a verification: key_published (retired keys included), key_purpose, and the trust fields. */
+export declare const applyKeyPolicy: <T>(res: T, doc: unknown, kp: KeyPolicyInput) => T & Trust;
 export interface BundleVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
@@ -197,7 +239,11 @@ export interface PreflightOptions {
     template?: string;
     policy?: PreflightPolicy; /** 8-128 characters of A-Z a-z 0-9 . _ : - signed into the receipt (replay binding). guard() sends a fresh one when you give none. */
     nonce?: string; /** The exact operation this decision is for (method + url, or an MCP tool); signed into the receipt. */
-    operation?: Operation;
+    operation?: Operation; /** An MCP server on this domain and the tool-list hash you approved (mcp-lockfile tools_sha256). The decision then reads the live tools, blocks when they differ, and its signed `assessed` block names exactly what it covered. https://crawlcheck.io/spec/mcp-lockfile */
+    mcp?: {
+        url: string;
+        tools_sha256?: string;
+    };
 }
 /** What a receipt can be scoped to. Send only the keys that apply; CrawlCheck signs them back exactly as sent. https://crawlcheck.io/spec/guard#operation */
 export interface Operation {
@@ -236,6 +282,8 @@ export interface GuardOptions extends PreflightOptions {
     onlineKeys?: boolean;
     /** Pinned CrawlCheck key ids, for offline use with onlineKeys: false. */
     publishedKids?: string[];
+    /** conf2: a pinned key policy (keyPolicyFrom(savedDirectory, savedRotation)), for offline use with onlineKeys: false. Checks key purpose too. */
+    keyPolicy?: KeyPolicyInput;
     /** Testing clock (ms since epoch). Default Date.now(). */
     now?: number;
 }
@@ -619,7 +667,10 @@ export declare class CrawlCheck {
     }): Promise<RevocationSync>;
     /** The policy engine: a signed decision receipt (allow | warn | require_confirmation | block | unsupported). A policy can only make the decision stricter. */
     preflight(domain: string, action?: Action, opts?: PreflightOptions): Promise<DecisionReceipt>;
-    /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */
+    private kpCache;
+    /** conf2: the key directory and rotation record, read now (cached 10 minutes), as the signing policy reads them. */
+    publishedKeyPolicy(): Promise<KeyPolicyInput>;
+    /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory and the signing policy must accept it. */
     verifyDocument(doc: unknown, onlineKeys?: boolean): Promise<DocumentVerification & Trust>;
     /**
      * Preflight, verify the receipt, check it is for THIS operation, and decide. Proceeds on allow; warn only with allowWarn;
@@ -637,6 +688,8 @@ export declare class CrawlCheck {
     guardedFetch(url: string, opts?: GuardedFetchOptions): Promise<GuardedFetchResult>;
     /** Look a domain up without sending it: only the first prefixLen hex characters of sha256(domain) leave this process (one more character per 413, up to 8). found false with ready true means no public measurement. */
     /** Make a signed lockfile for an MCP server (CrawlCheck reads tools/list; no tool is called). Save it; check with checkLock before every connect. */
+    /** One signed verdict on a business fact (phone, address, hours, service_area) against what the business publishes: GET /api/v1/field-check. */
+    fieldCheck(domain: string, field: FactField, value: string): Promise<JsonObject>;
     mcpLock(url: string): Promise<McpLock & JsonObject>;
     /** Read the server's tools now (through CrawlCheck) and compare with a lockfile; the answer is signed. For a fully offline check, list the tools yourself and call checkLock. */
     mcpLockCheck(lock: McpLock, url?: string): Promise<McpLockCheck & JsonObject>;
@@ -687,11 +740,12 @@ export declare class CrawlCheck {
     private req;
 }
 /**
- * Agent tools (1.6.0): CrawlCheck as two tools any agent framework can register, so the check happens inside the agent's
- * own tool loop. crawlcheck_check_site returns the signed, verified decision for an action on a site; crawlcheck_fetch
+ * Agent tools (1.6.0; crawlcheck_verify_fact and decision facts 1.7.0): CrawlCheck as tools any agent framework can register, so the check happens inside the agent's
+ * own tool loop. crawlcheck_check_site returns the signed, verified decision for an action on a site (with the business facts the site publishes); crawlcheck_verify_fact checks one phone, address or hours value; crawlcheck_fetch
  * fetches a page only after its domain (and every redirect hop) proceeds. Both fail closed, exactly like guard().
  * toolsFor() shapes them for OpenAI function calling, Anthropic tool use, the Vercel AI SDK or an MCP server.
  */
+export type FactField = "phone" | "address" | "hours" | "service_area";
 export interface AgentTool {
     name: string;
     description: string;

package/dist/index.js

@@ -3,6 +3,14 @@ import * as L from "./log.js";
 import * as S from "./staple.js";
 import * as M from "./mcp.js";
 import * as R from "./revocations.js";
+/** The signing policy as data (https://crawlcheck.io/keys#policy): object purposes, purpose chains, start times. */
+export const KEY_POLICY = V.KEY_POLICY;
+/** Build the policy input from a key directory you hold and, optionally, the rotation record saved with it. */
+export const keyPolicyFrom = V.keyPolicyFrom;
+/** Does the signing policy accept this document's signing key for this object at its signing time? */
+export const keyPolicyCheck = V.keyPolicyCheck;
+/** Apply the signing policy to a verification: key_published (retired keys included), key_purpose, and the trust fields. */
+export const applyKeyPolicy = V.applyKeyPolicy;
 function withTrust(v, kid, published, related = []) {
     let checks = v.checks;
     let issuer = null;
@@ -302,11 +310,34 @@ export class CrawlCheck {
             b.nonce = opts.nonce;
         if (opts.operation)
             b.operation = opts.operation;
+        if (opts.mcp && opts.mcp.url)
+            b.mcp = (opts.mcp.tools_sha256 ? { url: opts.mcp.url, tools_sha256: opts.mcp.tools_sha256 } : { url: opts.mcp.url });
         return this.post("/api/v1/preflight", b);
     }
-    /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */
+    kpCache = null;
+    /** conf2: the key directory and rotation record, read now (cached 10 minutes), as the signing policy reads them. */
+    async publishedKeyPolicy() {
+        if (this.kpCache && Date.now() - this.kpCache.at < 600e3)
+            return this.kpCache.kp;
+        const d = await this.req("GET", "/.well-known/http-message-signatures-directory");
+        let rot = null;
+        try {
+            const r = await this.f(this.base + "/.well-known/security-key-rotation.json", { headers: { accept: "application/json" } });
+            if (r.ok)
+                rot = await r.json();
+        }
+        catch {
+            rot = null;
+        }
+        const kp = Object.assign(await keyPolicyFrom(d, rot), { read_at: new Date().toISOString(), source: "online" });
+        this.kpCache = { at: Date.now(), kp };
+        return kp;
+    }
+    /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory and the signing policy must accept it. */
     async verifyDocument(doc, onlineKeys = true) {
-        return withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, onlineKeys ? await this.publishedKeyIds() : null, V.relatedKids(doc));
+        const kp = onlineKeys ? await this.publishedKeyPolicy() : null;
+        const v = withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, kp ? kp.kids : null, V.relatedKids(doc));
+        return kp && doc?.signature ? applyKeyPolicy(v, doc, kp) : v;
     }
     /**
      * Preflight, verify the receipt, check it is for THIS operation, and decide. Proceeds on allow; warn only with allowWarn;
@@ -333,11 +364,14 @@ export class CrawlCheck {
         if (!receipt || typeof receipt !== "object")
             return no(scope.why);
         const online = opts.onlineKeys ?? true;
-        if (!online && !(Array.isArray(opts.publishedKids) && opts.publishedKids.length))
-            return no(["onlineKeys is false and no publishedKids were pinned: the signer cannot be checked"], receipt);
+        if (!online && !opts.keyPolicy && !(Array.isArray(opts.publishedKids) && opts.publishedKids.length))
+            return no(["onlineKeys is false and no keyPolicy or publishedKids were pinned: the signer cannot be checked"], receipt);
         let verification;
         try {
-            verification = withTrust(await V.verifyDataDoc(receipt), receipt?.signature?.kid, online ? await this.publishedKeyIds() : opts.publishedKids, V.relatedKids(receipt));
+            const kp = online ? await this.publishedKeyPolicy() : opts.keyPolicy || null; // conf2: purpose, retired and compromised keys, not only "published"
+            verification = withTrust(await V.verifyDataDoc(receipt), receipt?.signature?.kid, kp ? kp.kids : opts.publishedKids, V.relatedKids(receipt));
+            if (kp)
+                verification = applyKeyPolicy(verification, receipt, kp);
         }
         catch (e) {
             return no(["the receipt could not be verified: " + (e?.message || e)].concat(scope.why), receipt);
@@ -347,6 +381,8 @@ export class CrawlCheck {
             why.push("integrity failed: " + verification.checks.filter((c) => c.ok === false).map((c) => c.id).join(", "));
         if (verification.issuer_trusted !== true)
             why.push("signed by a key that is not in CrawlCheck's published key directory");
+        else if (verification.key_policy_valid === false)
+            why.push("the signing policy rejects this key for a decision receipt: " + (verification.checks.find((c) => c.id === "key_purpose") || {}).why);
         if (why.length)
             return no(why, receipt, verification);
         const d = receipt.decision;
@@ -423,6 +459,8 @@ export class CrawlCheck {
     }
     /** Look a domain up without sending it: only the first prefixLen hex characters of sha256(domain) leave this process (one more character per 413, up to 8). found false with ready true means no public measurement. */
     /** Make a signed lockfile for an MCP server (CrawlCheck reads tools/list; no tool is called). Save it; check with checkLock before every connect. */
+    /** One signed verdict on a business fact (phone, address, hours, service_area) against what the business publishes: GET /api/v1/field-check. */
+    async fieldCheck(domain, field, value) { return this.req("GET", "/api/v1/field-check", { domain: normalizeDomain(domain), field, value }); }
     async mcpLock(url) { return this.req("GET", "/api/v1/mcp/lock", { url }); }
     /** Read the server's tools now (through CrawlCheck) and compare with a lockfile; the answer is signed. For a fully offline check, list the tools yourself and call checkLock. */
     async mcpLockCheck(lock, url) { return this.req("POST", "/api/v1/mcp/lock/check", undefined, { lock, url: url ?? lock?.server?.url ?? undefined }); }
@@ -586,7 +624,31 @@ export function agentTools(cc, opts = {}) {
                     return { proceed: false, why: ["not a public domain name: " + String(a?.site ?? "")] };
                 const g = await cc.guard(domain, action, opts);
                 return { domain, action, proceed: g.proceed, decision: g.receipt ? String(g.receipt.decision) : null, why: g.why, reasons: Array.isArray(g.receipt?.steps) ? g.receipt.steps.map((x) => String(x?.why ?? "")).filter(Boolean) : [], reason_codes: g.receipt?.reason_codes ?? [],
-                    receipt_sha256: g.receipt?.sha256 ?? null, verified: g.verification ? g.verification.accepted : false, alternatives: g.receipt?.alternatives ?? null };
+                    receipt_sha256: g.receipt?.sha256 ?? null, verified: g.verification ? g.verification.accepted : false, alternatives: g.receipt?.alternatives ?? null,
+                    facts: g.receipt?.facts ?? null };
+            } },
+        { name: "crawlcheck_verify_fact",
+            description: "Check one fact you hold about a business against what the business itself publishes: its phone number, street address, opening hours or a place it serves. Returns CrawlCheck's signed verdict (published now, published before, or not this business, and who does publish it). Use it before giving someone a phone number, address or hours, especially ones that came from an AI answer or a directory.",
+            parameters: { type: "object", additionalProperties: false, required: ["site", "field", "value"], properties: {
+                    site: { type: "string", description: "The business's website domain or any URL on it" },
+                    field: { type: "string", enum: ["phone", "address", "hours", "service_area"], description: "Which fact the value is" },
+                    value: { type: "string", description: "The value you hold, e.g. (720) 555-0100, 1200 Main St, Mon 8am, or a city name" }
+                } },
+            execute: async (a) => {
+                const domain = atDomain(a?.site), field = String(a?.field ?? ""), value = String(a?.value ?? "").trim().slice(0, 200);
+                if (!domain)
+                    return { ok: false, why: ["not a public domain name: " + String(a?.site ?? "")] };
+                if (!["phone", "address", "hours", "service_area"].includes(field) || !value)
+                    return { ok: false, why: ["give field (phone, address, hours or service_area) and value"] };
+                let doc;
+                try {
+                    doc = await cc.fieldCheck(domain, field, value);
+                }
+                catch (e) {
+                    return { ok: false, domain, field, value, why: [String(e?.message ?? e)] };
+                }
+                const v = await cc.verifyDocument(doc).catch(() => null);
+                return Object.assign({}, doc, { ok: true, verified: v ? (v.accepted ?? v.verified) === true : false, verification: v ? v.summary : "could not verify" });
             } },
         { name: "crawlcheck_fetch",
             description: "Fetch a web page only if CrawlCheck allows reading that site; every redirect to a new domain is checked again before it is followed. Returns the page text (truncated) or, when refused, why. Prefer this over a plain fetch for sites you have not checked.",

package/dist/mcp.js

@@ -60,8 +60,12 @@ export function mcpPreflight(cc, opts = {}) {
             return false;
         return true;
     };
+    // tscope1: send the server URL and, with a lockfile, its approved tools_sha256, so CrawlCheck reads the live tools from its own
+    // vantage and the signed receipt names the endpoint and tool state it covered (a changed list comes back as block).
+    const mcpScope = function () { if (!state.url || !/^https:/i.test(state.url))
+        return undefined; const h = opts.lock && typeof opts.lock.tools_sha256 === "string" ? opts.lock.tools_sha256 : null; return h ? { url: state.url, tools_sha256: h } : { url: state.url }; };
     const decide = async function (host) {
-        const g = await cc.guard(host, "connect", { template, policy: opts.policy, agent: opts.agent, confirm: opts.confirm, allowWarn: !!opts.allowWarn, onlineKeys: opts.onlineKeys });
+        const g = await cc.guard(host, "connect", { template, policy: opts.policy, agent: opts.agent, confirm: opts.confirm, allowWarn: !!opts.allowWarn, onlineKeys: opts.onlineKeys, mcp: mcpScope() });
         state.receipt = g.receipt;
         state.verification = g.verification;
         state.decidedAt = Date.now();

package/dist/verify.d.ts

@@ -20,6 +20,42 @@ export function verifyThresholdSigners(x: any): Promise<{
     why: never[];
 }[]>;
 export function relatedKids(x: any): any[];
+export function keyPolicyFrom(directory: any, rotation: any): Promise<{
+    v: number;
+    kids: string[];
+    keys: {};
+    retired: {};
+    compromised: {};
+    rotation: boolean;
+}>;
+export function signedAtOf(x: any): number | null;
+export function keyPolicyCheck(x: any, kp: any): {
+    ok: false | null;
+    code: string | undefined;
+    known: boolean;
+    purpose: any;
+    expected: null;
+    why: string | undefined;
+} | {
+    ok: boolean;
+    code: string;
+    known: boolean;
+    purpose: any;
+    expected: any;
+    why: string;
+};
+export function applyKeyPolicy(res: any, x: any, kp: any): any;
+export function publishedKeyPolicy(base: any): Promise<{
+    v: number;
+    kids: string[];
+    keys: {};
+    retired: {};
+    compromised: {};
+    rotation: boolean;
+} & {
+    read_at: string;
+    source: string;
+}>;
 export function trustOf(res: any, kid: any, publishedKids: any, related: any): any;
 export function publishedKeyIds(base: any): Promise<string[]>;
 export function verifyBundle(b: any, opts: any): Promise<any>;
@@ -28,3 +64,29 @@ export function verifyExport(x: any, opts: any): Promise<any>;
 export function verifyResolution(x: any, opts: any): Promise<any>;
 export function verifyDnsTxt(txt: any, opts: any): Promise<any>;
 export function verifyDataDoc(x: any, opts: any): Promise<any>;
+export namespace KEY_POLICY {
+    let v: number;
+    let object_purpose: {
+        "crawlcheck-decision": string;
+        "crawlcheck-log-sth": string;
+        "*": string;
+    };
+    let chains: {
+        documents: string[];
+        decisions: string[];
+        "log heads": string[];
+    };
+    let starts: {
+        requests: null;
+        documents: string;
+        decisions: string;
+        "log heads": string;
+    };
+    let bound: {
+        "crawlcheck-resolve": string;
+        "crawlcheck-decision": string;
+    };
+    let purpose_aliases: {
+        "requests and documents": string;
+    };
+}

package/dist/verify.js

@@ -612,8 +612,10 @@ async function verifyDataDoc0(x) {
         throw new Error("this runtime has no WebCrypto (crypto.subtle)");
     const checks = [];
     const C = (id, ok, why) => checks.push({ id, ok, why });
-    if (!x || !/^crawlcheck-(data-inventory|data-export-part|deletion-record|resolve|decision|snapshot|visitor|conduct|traffic-index|anchor|anchor-check|content-clock|origin|claims|read-equivalence|rights|rights-feed|mcp-scan|mcp-lock|mcp-lock-check|mcp-shadow|mcp-auth|impersonation|task-canaries|agent-safety-benchmark|compliance-pack|share-of-preflight|incident|revocations|high-risk|log-sth|threshold-verdict|resolve-as-of)$/.test(String(x.kind)) || !x.signature)
-        throw new Error("not a CrawlCheck data inventory, export part, deletion record, resolve answer, decision receipt, snapshot manifest, visitor verdict, conduct record, traffic index, citation anchor, content clock, origin decision, claim ledger, read-equivalence certificate, rights answer, rights-feed manifest, MCP tool scan, MCP lockfile or lockfile check");
+    // 1.7.0: every kind the service signs with this scheme verifies (field checks, opt-out records, AI-visibility and what-moved
+    // readings were refused by the old fixed list though their signatures were valid); trust still rests on key_published.
+    if (!x || !/^crawlcheck-[a-z0-9]+(-[a-z0-9]+){0,6}$/.test(String(x.kind)) || !x.signature || !x.signature.message || String(x.signature.message).indexOf(DATA_SIG_PREFIX) !== 0)
+        throw new Error("not a signed CrawlCheck document (kind crawlcheck-*, signed with the crawlcheck-data-v1 scheme)");
     const body = {};
     for (const k of Object.keys(x))
         if (k !== "sha256" && k !== "signature")
@@ -749,6 +751,152 @@ export function relatedKids(x) {
     catch (e) { }
     return out.filter((k, i) => typeof k === "string" && out.indexOf(k) === i);
 }
+// conf2: the signing policy (https://crawlcheck.io/keys#policy, machine copy spec/key-policy/policy.json) as code. Which key
+// PURPOSE may sign which object at which time, retired keys, compromised keys. Same rule in the Python package.
+export const KEY_POLICY = { v: 2,
+    object_purpose: { "crawlcheck-decision": "decisions", "crawlcheck-log-sth": "log heads", "*": "documents" },
+    chains: { documents: ["documents", "requests"], decisions: ["decisions", "documents", "requests"], "log heads": ["log heads", "documents", "requests"] },
+    starts: { requests: null, documents: "2026-10-11T00:00:00Z", decisions: "2026-11-09T17:00:00Z", "log heads": "2026-11-09T17:00:00Z" },
+    bound: { "crawlcheck-resolve": "transparency.sth", "crawlcheck-decision": "resolve" },
+    purpose_aliases: { "requests and documents": "requests" } };
+const kpPurpose = (p) => { p = String(p || "requests"); return KEY_POLICY.purpose_aliases[p] || p; };
+const kpMs = (v) => { if (v === null || v === undefined || v === "")
+    return null; if (typeof v === "number")
+    return v < 1e11 ? v * 1000 : v; const t = Date.parse(String(v)); return isFinite(t) ? t : null; };
+// The key directory (and, when you have it, the rotation record) as the input every key-policy check reads.
+export async function keyPolicyFrom(directory, rotation) {
+    const keys = {}, retired = {}, compromised = {};
+    for (const k of (directory && directory.keys) || []) {
+        if (!k || !k.x)
+            continue;
+        const kid = b64u(await sha256(enc.encode(JSON.stringify({ crv: k.crv || "Ed25519", kty: k.kty || "OKP", x: k.x }))));
+        const purpose = kpPurpose(k.crawlcheck_purpose);
+        keys[kid] = { purpose, start: kpMs(k.crawlcheck_signs_from) ?? kpMs(k.nbf) ?? kpMs(KEY_POLICY.starts[purpose]) };
+    }
+    for (const r of (rotation && rotation.retired) || [])
+        if (r && r.thumbprint)
+            retired[r.thumbprint] = { purpose: kpPurpose(r.purpose), stopped: kpMs(r.stopped_signing_at) ?? kpMs(r.retired_at) };
+    for (const c of (rotation && rotation.compromised) || [])
+        if (c && c.thumbprint)
+            compromised[c.thumbprint] = kpMs(c.compromised_since) ?? 0;
+    return { v: 2, kids: Object.keys(keys), keys, retired, compromised, rotation: !!rotation };
+}
+export function signedAtOf(x) {
+    const s = x && x.signature, c = [s && s.signed_at, x && x.decided_at, x && x.answered_at, x && x.sealed_at, x && x.generated_at, x && x.issued_at, x && x.at];
+    for (const v of c) {
+        const t = kpMs(v);
+        if (t !== null)
+            return t;
+    }
+    return null;
+}
+function kpBoundKid(x) {
+    const path = KEY_POLICY.bound[x && x.kind];
+    if (!path)
+        return null;
+    const o = path.split(".").reduce((a, p) => (a && typeof a === "object" ? a[p] : undefined), x);
+    return (o && o.signature && o.signature.kid) || (o && typeof o.kid === "string" ? o.kid : null);
+}
+// One key against the policy at time t. Returns { known, ok, purpose, why } (ok null: could not be decided).
+function kpKey(kid, t, kp) {
+    if (!kid)
+        return { known: false, ok: false, code: "key_unknown", why: "no signing key named" };
+    if (kp.compromised[kid] !== undefined)
+        return { known: false, ok: false, code: "key_compromised", why: "key " + kid + " is listed as compromised since " + new Date(kp.compromised[kid]).toISOString() + ": its signature alone proves nothing (" + (t !== null && t >= kp.compromised[kid] ? "signed after that moment" : "only an outside anchor still proves documents signed before it") + ")" };
+    const k = kp.keys[kid];
+    if (k) {
+        if (t !== null && k.start !== null && t < k.start)
+            return { known: true, ok: false, purpose: k.purpose, code: "key_not_yet_active", why: "key " + kid + " (" + k.purpose + ") signs nothing before " + new Date(k.start).toISOString() };
+        return { known: true, ok: true, purpose: k.purpose, start: k.start };
+    }
+    const r = kp.retired[kid];
+    if (r) {
+        if (t === null)
+            return { known: true, ok: null, purpose: r.purpose, code: "no_signing_time", why: "retired key, and the document carries no signing time" };
+        return r.stopped !== null && t <= r.stopped ? { known: true, ok: true, purpose: r.purpose, retired: true, why: "retired key, signed before it stopped signing (" + new Date(r.stopped).toISOString() + ")" } : { known: false, ok: false, code: "key_retired", why: "key " + kid + " stopped signing at " + (r.stopped !== null ? new Date(r.stopped).toISOString() : "an unknown time") + "; this was signed after" };
+    }
+    return { known: false, ok: false, code: "key_unknown", why: "key " + kid + " is not in the published key directory" + (kp.rotation ? " or the rotation record" : "") };
+}
+function kpExpected(objPurpose, t, kp) {
+    for (const p of KEY_POLICY.chains[objPurpose]) {
+        if (p === "requests")
+            return p;
+        if (Object.keys(kp.keys).some((kid) => kp.keys[kid].purpose === p && kp.compromised[kid] === undefined && (t === null || kp.keys[kid].start === null || kp.keys[kid].start <= t)))
+            return p;
+    }
+    return "requests";
+}
+// Does the policy accept this signature on this document? { ok: true | false | null, code, purpose, expected, why }
+// code (stable): ok, ok_bound, key_wrong_purpose, key_not_yet_active, key_retired, key_compromised, key_unknown, no_signing_time;
+// applyKeyPolicy adds related_<code> when the key a document leans on (its answer, its log head) fails.
+export function keyPolicyCheck(x, kp) {
+    const kid = x && x.signature && x.signature.kid, t = signedAtOf(x);
+    const objPurpose = KEY_POLICY.object_purpose[x && x.kind] || KEY_POLICY.object_purpose["*"];
+    const k = kpKey(kid, t, kp);
+    if (k.ok !== true)
+        return { ok: k.ok, code: k.code, known: k.known, purpose: k.purpose || null, expected: null, why: k.why };
+    if (t === null)
+        return { ok: null, code: "no_signing_time", known: true, purpose: k.purpose, expected: null, why: "the document carries no signing time, so the key's purpose cannot be checked against the policy" };
+    const expected = kpExpected(objPurpose, t, kp), chain = KEY_POLICY.chains[objPurpose], at = new Date(t).toISOString();
+    if (k.purpose === expected)
+        return { ok: true, code: "ok", known: true, purpose: k.purpose, expected, why: "a " + k.purpose + " key signs " + objPurpose + " at " + at + (k.retired ? " (" + k.why + ")" : "") };
+    const later = chain.indexOf(k.purpose) > chain.indexOf(expected);
+    const bound = kpBoundKid(x), decisionKeyLive = objPurpose === "decisions" && expected === "decisions";
+    if (later && bound && bound === kid && !decisionKeyLive)
+        return { ok: true, code: "ok_bound", known: true, purpose: k.purpose, expected, why: "signed by the " + k.purpose + " key that signed the object it is bound to (" + KEY_POLICY.bound[x.kind] + "), as the policy allows" };
+    return { ok: false, code: "key_wrong_purpose", known: true, purpose: k.purpose, expected, why: "a " + k.purpose + " key does not sign " + objPurpose + " at " + at + ": the " + expected + " key does" + (chain.indexOf(k.purpose) < 0 ? " (" + k.purpose + " keys never sign them)" : "") };
+}
+// Apply the policy to a verification result: key_published (retired keys included), key_purpose, and the trust fields.
+export function applyKeyPolicy(res, x, kp) {
+    if (!res || !kp)
+        return res;
+    const main = keyPolicyCheck(x, kp), t = signedAtOf(x), rel = [];
+    let relCode = null;
+    if (x && x.kind === "crawlcheck-decision" && x.resolve && x.resolve.kid) {
+        const r = kpKey(x.resolve.kid, t, kp);
+        if (r.ok !== true) {
+            rel.push("the Resolve answer it names: " + r.why);
+            relCode = relCode || "related_" + (r.code || "key_unknown");
+        }
+    }
+    const sth = x && x.transparency && x.transparency.sth;
+    if (sth && sth.signature) {
+        const r = keyPolicyCheck(sth, kp);
+        if (r.ok === false) {
+            rel.push("its log head: " + r.why);
+            relCode = relCode || "related_" + r.code;
+        }
+    }
+    const kpub = { id: "key_published", ok: main.known && !rel.length, why: main.known && !rel.length ? "key " + (x.signature && x.signature.kid) + " is " + (kp.keys[x.signature && x.signature.kid] ? "in the published key directory" : "a retired key listed in the rotation record") + ((x && (x.kind === "crawlcheck-decision" || sth)) ? ", and so is every key it leans on" : "") : (main.known ? "it leans on a key the policy rejects: " + rel.join("; ") : main.why) + ": reject this document" };
+    const kpur = { id: "key_purpose", ok: rel.length ? false : main.ok, code: rel.length && main.ok !== false ? relCode : main.code, why: rel.length ? rel.join("; ") : main.why };
+    let checks = (res.checks || []).filter((c) => c.id !== "key_published" && c.id !== "key_purpose").concat([kpub, kpur]);
+    const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
+    const own = checks.filter((c) => c.id !== "key_published" && c.id !== "key_purpose");
+    const integrity_valid = own.some((c) => c.ok !== null) && own.every((c) => c.ok !== false);
+    const unavailable = checks.filter((c) => c.ok === null).map((c) => c.id);
+    const accepted = integrity_valid && kpub.ok === true && kpur.ok !== false;
+    return Object.assign({}, res, { checks, verified: ran.length > 0 && failed.length === 0, summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed",
+        integrity_valid, issuer_trusted: kpub.ok, key_policy_valid: kpur.ok, key_policy_code: kpur.code, accepted, accepted_strict: accepted && unavailable.length === 0, assurance: unavailable.length ? "partial" : "complete", unavailable });
+}
+// The directory and the rotation record, read now (online). The rotation record is optional: without it retired and
+// compromised keys are unknown, and only keys still in the directory are accepted.
+export async function publishedKeyPolicy(base) {
+    const b = String(base || "https://crawlcheck.io").replace(/\/+$/, "");
+    const r = await fetch(b + "/.well-known/http-message-signatures-directory");
+    if (!r.ok)
+        throw new Error("key directory answered HTTP " + r.status);
+    const d = await r.json();
+    let rot = null;
+    try {
+        const q = await fetch(b + "/.well-known/security-key-rotation.json");
+        if (q.ok)
+            rot = await q.json();
+    }
+    catch (e) {
+        rot = null;
+    }
+    return Object.assign(await keyPolicyFrom(d, rot), { read_at: new Date().toISOString(), source: "online" });
+}
 export function trustOf(res, kid, publishedKids, related) {
     let checks = Array.isArray(res && res.checks) ? res.checks : [];
     let issuer = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Typed client for the CrawlCheck API (generated from its OpenAPI document) and the zero-dependency offline verifier for evidence bundles and remediation receipts.",
   "type": "module",
   "main": "./dist/index.js",