@crawlcheck/sdk 1.0.4 → 1.0.6

package/README.md

@@ -66,6 +66,23 @@ suite.ok;                              // every fixture gave exactly its expecte
 
 `npm test` in the installed package runs the conformance suite and live checks against crawlcheck.io.
 
+## Catch a split view
+
+Every Resolve answer names its leaf in CrawlCheck's transparency log and, once merged, carries the signed tree head of its batch. The client keeps every head it sees in `client.log` (plain JSON) and checks each new one against its neighbours: two heads for one batch, or a head that does not chain to the one before, is a **fork**, kept with both signed heads as proof. `guard()` refuses to proceed while the client holds one.
+
+```js
+import fs from "node:fs";
+import { CrawlCheck, newLogStore } from "@crawlcheck/sdk";
+const store = fs.existsSync("cc-log.json") ? JSON.parse(fs.readFileSync("cc-log.json", "utf8")) : newLogStore();
+const client = new CrawlCheck({ logStore: store });
+await client.resolve("example.com");                 // the answer's head is checked against the store
+const r = await client.logCheck();                   // current head + GitHub's witness co-signature + the chain down to your heads
+console.log(r.summary);                              // "consistent: ..." or "SPLIT VIEW: ..."
+fs.writeFileSync("cc-log.json", JSON.stringify(client.log));
+```
+
+`logCheck` verifies the outside witness: a GitHub Actions run re-checks the chain and co-signs the newest head with a GitHub OIDC token (RS256, GitHub's key) whose audience is the head's digest. A head the witness's chain does not contain shows up as a fork. Heads newer than the witnessed one are listed as `unwitnessed`. Clients can also swap heads directly: `logHeads(store)` on one side, `client.logGossip(heads)` on the other. Forks are reported to `/api/v1/log/gossip` (pass `{ report: false }` to skip).
+
 ## Errors
 
 A refused request throws `CrawlCheckError` with `status`, `body` and `locked` (true for "this needs a licence for the domain").