@crawlcheck/sdk 1.7.0 → 1.9.0

package/README.md

@@ -18,6 +18,14 @@ 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.9.0 `logCheck` reads the chain of signed heads 200 per request (`/api/v1/log/sths`) instead of one per batch, so a first check on a client holding no heads takes one or two requests; an older server is still walked one head per request.
+
+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

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;

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;

package/dist/log.d.ts

@@ -110,6 +110,7 @@ export function verifyWitnessToken(token: any, sthSha256: any, jwks: any): Promi
  * holds (at most opts.maxWalk batches), observing every link, so any head this client was shown that the witness's
  * chain does not contain surfaces as a fork. Heads newer than the witnessed one are listed as unwitnessed.
  */
+export function walkHeads(get: any, hi: any, lo: any): Promise<any[]>;
 export function logCheck(store: any, get: any, opts?: {}): Promise<{
     consistent: boolean;
     forks: any;

package/dist/log.js

@@ -146,6 +146,32 @@ export async function verifyWitnessToken(token, sthSha256, jwks) {
  * holds (at most opts.maxWalk batches), observing every link, so any head this client was shown that the witness's
  * chain does not contain surfaces as a fork. Heads newer than the witnessed one are listed as unwitnessed.
  */
+// Signed heads for batches hi down to lo, newest first. Since 1.9.0 one request per 200 batches (/api/v1/log/sths);
+// a server without that route is walked one head per request as before.
+export async function walkHeads(get, hi, lo) {
+    const out = [];
+    let k = hi;
+    while (k >= lo) {
+        const n = Math.min(200, k - lo + 1);
+        const d = await get("/api/v1/log/sths?to=" + k + "&n=" + n).catch(() => null);
+        if (!d || !Array.isArray(d.sths))
+            break;
+        const got = {};
+        for (const s of d.sths)
+            if (s && Number.isInteger(s.batch))
+                got[s.batch] = s;
+        for (let b = k; b > k - n; b--)
+            if (got[b])
+                out.push(got[b]);
+        k -= n;
+    }
+    for (; k >= lo; k--) {
+        const d = await get("/api/v1/log/sth/" + k).catch(() => null);
+        if (d && d.sth)
+            out.push(d.sth);
+    }
+    return out;
+}
 export async function logCheck(store, get, opts = {}) {
     const before = store.forks.length, o = { publishedKids: opts.publishedKids };
     const log = await get("/api/v1/log");
@@ -166,11 +192,8 @@ export async function logCheck(store, get, opts = {}) {
             store.witnessed = { batch: w.batch, sha256: sth.sha256, at: witnessed.at, run_id: witnessed.run_id };
         const held = Object.keys(store.heads).map(Number).filter((k) => k < w.batch);
         const lo = held.length ? Math.max(Math.min(...held), w.batch - (opts.maxWalk || 200)) : w.batch;
-        for (let k = w.batch - 1; k >= lo; k--) {
-            const d = await get("/api/v1/log/sth/" + k).catch(() => null);
-            if (d && d.sth)
-                await logObserve(store, d.sth, o);
-        }
+        for (const s of await walkHeads(get, w.batch - 1, lo))
+            await logObserve(store, s, o);
     }
     const wb = store.witnessed ? store.witnessed.batch : -1, now = Date.now(), maxAge = (opts.maxUnwitnessedMinutes || 120) * 60000;
     const unwitnessed = Object.keys(store.heads).map(Number).filter((k) => k > wb).sort((a, b) => a - b).map((k) => ({ batch: k, sha256: store.heads[k].sha256, created_at: store.heads[k].created_at }));

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

@@ -751,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.7.0",
+  "version": "1.9.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",