@crawlcheck/sdk 1.0.2 → 1.0.3

package/README.md

@@ -16,6 +16,8 @@ const { proceed, receipt } = await cc.guard("example.com", "read", { agent: "MyA
 // The receipt is a signed crawlcheck-decision; guard() verified it here and checked its key against the published directory.
 ```
 
+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.
+
 `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.
 
 ## Read a record

package/dist/index.d.ts

@@ -7,7 +7,17 @@ export interface VerifyCheck {
     why: string;
     [k: string]: unknown;
 }
-export interface BundleVerification {
+/**
+ * Three separate answers. integrity_valid: hashes and the signature agree with the document. issuer_trusted: the
+ * signing key is one CrawlCheck publishes (null offline: not decided). accepted: both - the only field to act on.
+ * A document someone else signed with their own key is verified: true offline and accepted: false.
+ */
+export interface Trust {
+    integrity_valid: boolean;
+    issuer_trusted: boolean | null;
+    accepted: boolean;
+}
+export interface BundleVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
     report: {
@@ -19,7 +29,7 @@ export interface BundleVerification {
     experiences: number | null;
     note: string;
 }
-export interface ReceiptVerification {
+export interface ReceiptVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
     receipt: {
@@ -36,7 +46,7 @@ export interface ReceiptVerification {
 export declare const verifyBundle: (b: unknown) => Promise<BundleVerification>;
 /** Verify a remediation receipt with no call to CrawlCheck. */
 export declare const verifyReceipt: (rc: unknown) => Promise<ReceiptVerification>;
-export interface DocumentVerification {
+export interface DocumentVerification extends Partial<Trust> {
     verified: boolean;
     summary: string;
     document: {
@@ -47,7 +57,7 @@ export interface DocumentVerification {
     checks: VerifyCheck[];
 }
 /** Verify a signed resolve answer, preflight decision receipt, data inventory, export part or deletion record offline. */
-export declare const verifyDocument: (doc: unknown) => Promise<DocumentVerification>;
+export declare const verifyDocument: (doc: unknown) => Promise<DocumentVerification & Trust>;
 /** Verify a signed evidence export (and every bundle and receipt inside it) offline. */
 export declare const verifyExport: (x: unknown) => Promise<{
     verified: boolean;
@@ -188,12 +198,12 @@ export declare class CrawlCheck {
     /** 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. */
-    verifyDocument(doc: unknown, onlineKeys?: boolean): Promise<DocumentVerification>;
+    verifyDocument(doc: unknown, onlineKeys?: boolean): Promise<DocumentVerification & Trust>;
     /** Preflight, verify the receipt, and decide. Proceeds on allow; warn only with allowWarn; require_confirmation only if confirm() says yes; block and unsupported never. */
     guard(domain: string, action?: Action, opts?: GuardOptions): Promise<{
         proceed: boolean;
         receipt: DecisionReceipt;
-        verification: DocumentVerification;
+        verification: DocumentVerification & Trust;
     }>;
     /** Signed change feed (what changed since a time, optionally for one domain). */
     changes(q?: QueryOf<"/api/v1/changes">): Promise<JsonObject>;
@@ -219,11 +229,11 @@ export declare class CrawlCheck {
     /** The evidence bundle (anonymous: subject and leaves withheld; with a licence for the domain: complete). */
     bundle(id: string): Promise<EvidenceBundleV1>;
     /** Download the bundle and verify it here, with the offline verifier: no trust in the API's own answer. */
-    verifyOffline(id: string): Promise<BundleVerification>;
+    verifyOffline(id: string): Promise<BundleVerification & Trust>;
     /** A signed remediation receipt by its id (rc1:…). */
     receipt(id: string): Promise<RemediationReceiptV1>;
     /** Fetch a receipt and verify its hash and signature here. key_published stays null offline: compare the key id with publishedKeyIds(). */
-    verifyReceiptOffline(id: string): Promise<ReceiptVerification>;
+    verifyReceiptOffline(id: string): Promise<ReceiptVerification & Trust>;
     /** The observer's published Ed25519 key ids (RFC 7638 thumbprints), to close the one check a verifier cannot do offline. */
     publishedKeyIds(): Promise<string[]>;
     receipts(domain: string): Promise<JsonObject>;

package/dist/index.js

@@ -1,10 +1,24 @@
 import * as V from "./verify.js";
+function withTrust(v, kid, published) {
+    let checks = v.checks;
+    let issuer = null;
+    if (published) {
+        issuer = !!kid && published.includes(kid);
+        const kc = { id: "key_published", ok: issuer, why: issuer ? "key id " + kid + " is in the published key directory" : "key id " + (kid || "?") + " is NOT in the published key directory - reject this document" };
+        checks = checks.some((c) => c.id === "key_published") ? checks.map((c) => c.id === "key_published" ? kc : c) : checks.concat([kc]);
+    }
+    const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
+    const verified = ran.length > 0 && failed.length === 0;
+    const integrity_valid = checks.filter((c) => c.id !== "key_published").every((c) => c.ok !== false);
+    return Object.assign({}, v, { checks, verified, summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed",
+        integrity_valid, issuer_trusted: issuer, accepted: verified && issuer === true });
+}
 /** Verify an evidence bundle with no call to CrawlCheck (the same code as /crawlcheck-verify.mjs). */
 export const verifyBundle = V.verifyBundle;
 /** Verify a remediation receipt with no call to CrawlCheck. */
 export const verifyReceipt = V.verifyReceipt;
 /** Verify a signed resolve answer, preflight decision receipt, data inventory, export part or deletion record offline. */
-export const verifyDocument = V.verifyDataDoc;
+export const verifyDocument = async (doc) => withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, null);
 /** Verify a signed evidence export (and every bundle and receipt inside it) offline. */
 export const verifyExport = V.verifyExport;
 /** Verify a signed dispute resolution offline (re-runs the published decision table over the recorded readings). */
@@ -67,19 +81,14 @@ export class CrawlCheck {
     }
     /** Verify a signed document here. With onlineKeys (default), its signing key must also be in the published directory. */
     async verifyDocument(doc, onlineKeys = true) {
-        const v = await verifyDocument(doc);
-        if (!onlineKeys)
-            return v;
-        const kid = doc?.signature?.kid;
-        const ok = !!kid && (await this.publishedKeyIds()).includes(kid);
-        const checks = v.checks.map((c) => c.id === "key_published" ? { id: c.id, ok, why: ok ? "key id " + kid + " is in the published key directory" : "key id " + kid + " is NOT in the published key directory" } : c);
-        const ran = checks.filter((c) => c.ok !== null), failed = checks.filter((c) => c.ok === false);
-        return { verified: ran.length > 0 && failed.length === 0, summary: failed.length ? failed.length + " check(s) FAILED" : ran.length + " of " + checks.length + " checks ran and passed", document: v.document, checks };
+        return withTrust(await V.verifyDataDoc(doc), doc?.signature?.kid, onlineKeys ? await this.publishedKeyIds() : null);
     }
     /** Preflight, verify the receipt, and decide. Proceeds on allow; warn only with allowWarn; require_confirmation only if confirm() says yes; block and unsupported never. */
     async guard(domain, action = "read", opts = {}) {
         const receipt = await this.preflight(domain, action, opts);
         const verification = await this.verifyDocument(receipt, opts.onlineKeys ?? true);
+        if (!verification.accepted && (opts.onlineKeys ?? true))
+            return { proceed: false, receipt, verification };
         if (!verification.verified)
             return { proceed: false, receipt, verification };
         const d = receipt.decision;
@@ -112,11 +121,11 @@ export class CrawlCheck {
     /** The evidence bundle (anonymous: subject and leaves withheld; with a licence for the domain: complete). */
     bundle(id) { return this.get("/api/bundle", { id, download: "0" }); }
     /** Download the bundle and verify it here, with the offline verifier: no trust in the API's own answer. */
-    async verifyOffline(id) { return verifyBundle(await this.bundle(id)); }
+    async verifyOffline(id) { const b = await this.bundle(id); return withTrust(await verifyBundle(b), b?.manifest?.signature?.kid, await this.publishedKeyIds()); }
     /** A signed remediation receipt by its id (rc1:…). */
     async receipt(id) { const r = await this.get("/api/receipt", { id }); return r.receipt; }
     /** Fetch a receipt and verify its hash and signature here. key_published stays null offline: compare the key id with publishedKeyIds(). */
-    async verifyReceiptOffline(id) { return verifyReceipt(await this.receipt(id)); }
+    async verifyReceiptOffline(id) { const rc = await this.receipt(id); return withTrust(await verifyReceipt(rc), rc?.signature?.kid, await this.publishedKeyIds()); }
     /** The observer's published Ed25519 key ids (RFC 7638 thumbprints), to close the one check a verifier cannot do offline. */
     async publishedKeyIds() {
         const d = await this.req("GET", "/.well-known/http-message-signatures-directory");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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",

package/test/sdk.test.js

@@ -59,5 +59,12 @@ test("live preflight: the decision receipt verifies offline, its key is publishe
   assert.equal(g.verification.verified, true);
   assert.equal(g.proceed, g.receipt.decision === "allow");
   const r = await c.resolve("example.com");
-  assert.equal((await verifyDocument(r)).verified, true);
+  const off = await verifyDocument(r);
+  assert.equal(off.verified, true); assert.equal(off.issuer_trusted, null); assert.equal(off.accepted, false, "offline is never accepted");
+  assert.equal((await c.verifyDocument(r)).accepted, true);
+  const ids = await c.publishedKeyIds();
+  const ix = await (await fetch(c.base + "/conformance/index.json")).json();
+  const foreign = await (await fetch(ix.fixtures.find((x) => x.name === "receipt-foreign-key").file)).json();
+  assert.equal((await verifyReceipt(foreign)).verified, true, "self-consistent offline");
+  assert.ok(!ids.includes(foreign.signature.kid), "but not a CrawlCheck key, so never accepted");
 });