@bluefields/cli 0.2.0

package/README.md

@@ -0,0 +1,181 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Bluefield — git for web data
+
+Snapshot web pages into a **content-addressed store on your own disk**, and
+sign every capture with an **offline-verifiable Ed25519 provenance manifest**
+(the *Bluefield Provenance Manifest / BPM*). Track changes over time, diff any
+two snapshots, and prove — cryptographically, months later, with no network —
+exactly what a URL served and when.
+
+- 🗄️ **Local-first.** Snapshots live in `~/.bluefield` (or a project-local
+  `./.bf`). No server. No account. No hosted database.
+- 🔏 **Signed & tamper-evident.** Each capture is content-addressed by SHA-256
+  and signed with a local key. `bf verify` re-hashes the bytes and checks the
+  signature — entirely offline.
+- 🕰️ **History & diffs.** `bf log`, `bf diff`, and `bf watch` give you a
+  git-like history of any page.
+- 🤝 **BYO everything.** Proxy and LLM are yours, configured by env. There is
+  **no telemetry and no phone-home** — grep the source.
+- 🧰 **Library + CLI + MCP.** Use `bf` on the command line, `import` the
+  library, or expose it to an AI agent over MCP.
+
+It is the same audited engine that powers the hosted Bluefield service
+(`@bluefields/fetcher` / `extractor` / `differ` / `attest`), wired to a local
+embedded database (PGlite) and a filesystem object store — so nothing leaves
+your machine.
+
+---
+
+## 60-second quickstart
+
+Install from a checkout (the CLI is not yet published on npm):
+
+```console
+$ git clone <repository-url> && cd bluefield
+$ pnpm install && pnpm -r build
+$ node packages/cli/dist/cli.js --help     # or link the `bf` bin onto your PATH
+```
+
+> Once it is published, `npm install -g @bluefields/cli` will provide the `bf`
+> command directly. The examples below use `bf` for brevity.
+
+```console
+# 1. Capture a page. Needs network, and the URL must be https://
+#    (the fetcher is https-only and blocks localhost/file:// by design).
+#    First run generates your signing key in ~/.bluefield/keys.
+$ bf scrape https://example.com/
+captured https://example.com/
+  snapshot 3f9a2b18-...-a7c1
+  sha256   e722a1f6...b952df
+  signed   yes    changed: yes
+
+# 2. Prove it — recomputes the hash and checks the signature, fully offline.
+$ bf verify 3f9a2b
+✓ VERIFIED  3f9a2b18
+  content hash matches : yes
+  signature valid      : yes
+
+# 3. Capture again later; Bluefield tells you if it changed and shows the diff.
+$ bf scrape https://example.com/
+$ bf diff https://example.com/
+--- 3f9a2b18  2026-07-06T10:00:00.000Z
++++ 9c04 e1af  2026-07-06T18:00:00.000Z
+(content) +2 -1
+- <p>old price: $9</p>
++ <p>new price: $12</p>
+
+# 4. History, and a portable proof bundle anyone can re-verify.
+$ bf log https://example.com/
+$ bf export 3f9a2b --out ./proof     # writes <id>.content + <id>.bundle.json
+```
+
+No API key. The only network is fetching the page itself in step 1 — once a
+capture exists, `verify`, `log`, `diff`, and `export` all run fully offline.
+
+---
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `bf scrape <url>` | Capture a URL: fetch → content-address on disk → sign → record |
+| `bf log [url]` | Snapshot history, newest first (all, or one URL) |
+| `bf diff <a> [b]` | Line-diff two snapshots (or the last two of a URL) |
+| `bf watch <url>` | Poll a URL on an interval and report changes |
+| `bf verify <ref>` | Recompute the content hash + verify the signature (offline) |
+| `bf export <ref>` | Write raw content + a portable proof bundle |
+| `bf key` | Show this machine's public signing identity (safe to share) |
+| `bf where` | Print the resolved store + keys locations |
+| `bf mcp` | Run the local MCP server over stdio |
+
+A `<ref>` is a **snapshot-id prefix** (e.g. `3f9a2b`) or a **URL** (resolves to
+its latest snapshot). Run `bf help` for all flags.
+
+### Structured extraction (optional, BYO LLM)
+
+`bf scrape <url> --extract --schema schema.json` runs the extractor to pull
+structured JSON. This is the one feature that calls out to an LLM — set
+`ANTHROPIC_API_KEY` yourself. Everything else is fully offline.
+
+---
+
+## Where things live
+
+```
+~/.bluefield/keys/ed25519.key.jwk    # PRIVATE signing key, chmod 0600 — never printed
+~/.bluefield/keys/ed25519.pub.jwk    # public key + keyId (shareable)
+
+<store>/objects/<ab>/<sha256>        # content-addressed raw bodies (the "git objects")
+<store>/manifests/<snapshotId>.json  # portable proof bundle per snapshot
+<store>/db/                          # embedded PGlite metadata (history)
+<store>/trusted/*.jwk                # extra public keys you trust for `verify`
+```
+
+`<store>` resolves like git: `$BF_HOME` if set, else the nearest `./.bf`
+walking up from the cwd, else the global `~/.bluefield`. Your **signing key
+always stays in `~/.bluefield/keys`** (relocatable with `$BF_KEYS_DIR`), so a
+project-local `.bf/` never contains private material and is safe to inspect or
+share.
+
+## Verifying someone else's capture
+
+`bf verify` fails **closed**: a signature is only accepted if its key is one you
+trust — your own local key, anything in `<store>/trusted/`, or (with explicit
+`--trust-embedded`) the key carried in the bundle. An unknown key is rejected,
+so an exported bundle can't self-authorize.
+
+## Transparency anchoring (optional)
+
+`bf scrape --anchor` will submit the bundle to a public transparency log when
+the optional anchoring module is present. It is strictly additive: if the
+module isn't in your build, anchoring is skipped with a note and your capture is
+still fully signed and locally verifiable.
+
+## Configuration (all optional)
+
+| Env | Effect |
+| --- | --- |
+| `BF_HOME` | Override the store root outright |
+| `BF_KEYS_DIR` | Relocate the signing-keys directory |
+| `ANTHROPIC_API_KEY` | Enable `--extract` structured extraction |
+| `IPROYAL_*` | Route fetches through your proxy (Patchright tier) |
+| `LOG_LEVEL` | `info`/`debug` to surface the engine's structured logs (default: silent) |
+
+## Library
+
+```ts
+import { openBluefield } from '@bluefields/cli';
+
+const bf = await openBluefield();               // opens ~/.bluefield
+const r = await bf.scrape('https://example.com/');
+if (r.ok) {
+  const v = await bf.verify(r.snapshotId);
+  console.log(v.ok ? 'authentic' : 'FAILED');
+}
+await bf.close();
+```
+
+## MCP
+
+Expose the local store to an AI agent (Claude Desktop, etc.):
+
+```json
+{ "mcpServers": { "bluefield": { "command": "bf", "args": ["mcp"] } } }
+```
+
+Tools: `scrape`, `log`, `diff`, `verify`, `export`, `identity` — all local, no
+API key.
+
+## Development (from the monorepo)
+
+```console
+pnpm install
+pnpm --filter @bluefields/cli test        # offline fixture tests (PGlite + fake fetcher)
+pnpm --filter @bluefields/cli typecheck
+pnpm --filter @bluefields/cli build
+```
+
+## License
+
+AGPL-3.0-or-later. See [LICENSE](./LICENSE).

package/dist/anchor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Optional transparency anchoring (`--anchor`).
+ *
+ * The Rekor/OpenTimestamps anchoring lives in BF-rekor's `transparency.ts`,
+ * which ships on a separate branch and is NOT present in every build. This
+ * module feature-detects it at runtime via a computed import specifier (so the
+ * type checker doesn't hard-require the module) and degrades gracefully to a
+ * clear "unavailable" result when it is absent — anchoring is strictly
+ * additive and never blocks a capture.
+ */
+import type { AttestationBundle } from '@bluefields/attest';
+export interface AnchorResult {
+    anchored: boolean;
+    /** Present when anchoring succeeded — the transparency proof/receipt. */
+    proof?: unknown;
+    /** Human-readable reason, especially when `anchored` is false. */
+    detail: string;
+}
+/**
+ * Attempt to anchor a bundle in a transparency log. Returns
+ * `{ anchored: false }` (never throws) when the optional module is absent or
+ * anchoring fails — the caller keeps its offline, locally-verifiable capture.
+ */
+export declare function tryAnchor(bundle: AttestationBundle): Promise<AnchorResult>;

package/dist/anchor.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Optional transparency anchoring (`--anchor`).
+ *
+ * The Rekor/OpenTimestamps anchoring lives in BF-rekor's `transparency.ts`,
+ * which ships on a separate branch and is NOT present in every build. This
+ * module feature-detects it at runtime via a computed import specifier (so the
+ * type checker doesn't hard-require the module) and degrades gracefully to a
+ * clear "unavailable" result when it is absent — anchoring is strictly
+ * additive and never blocks a capture.
+ */
+/**
+ * Attempt to anchor a bundle in a transparency log. Returns
+ * `{ anchored: false }` (never throws) when the optional module is absent or
+ * anchoring fails — the caller keeps its offline, locally-verifiable capture.
+ */
+export async function tryAnchor(bundle) {
+    const mod = await loadTransparency();
+    if (!mod || typeof mod.anchorBundle !== 'function') {
+        return {
+            anchored: false,
+            detail: 'transparency anchoring is not available in this build (BF-rekor absent)',
+        };
+    }
+    try {
+        const proof = await mod.anchorBundle(bundle);
+        return { anchored: true, proof, detail: 'anchored in transparency log' };
+    }
+    catch (err) {
+        return {
+            anchored: false,
+            detail: `anchoring failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/** Dynamically resolve the optional transparency module; null if absent. */
+async function loadTransparency() {
+    // Computed specifier: keeps NodeNext from statically requiring a module that
+    // is not part of this build's dependency graph.
+    const spec = `@bluefields/${'attest'}/transparency`;
+    try {
+        return (await import(spec));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=anchor.js.map

package/dist/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C;;;;;;;;;GASG;AAYH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAyB;IACvD,MAAM,GAAG,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACrC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QACnD,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,yEAAyE;SAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;IAC3E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SAChF,CAAC;IACJ,CAAC;AACH,CAAC;AAMD,4EAA4E;AAC5E,KAAK,UAAU,gBAAgB;IAC7B,6EAA6E;IAC7E,gDAAgD;IAChD,MAAM,IAAI,GAAG,eAAe,QAAQ,eAAe,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAuB,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/attestation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Provenance glue between the snapshot store and `@bluefields/attest`.
+ *
+ * The engine signs a JCS-canonical v1 manifest and persists the detached
+ * signature + keyId on the snapshot row (not the manifest itself). This module
+ * rebuilds the exact signed manifest from a row so a capture can be verified
+ * offline, packages it as a portable `AttestationBundle` (manifest + signature
+ * + public JWK) for `export`, and builds a LOCAL trust store so `verifyBundle`
+ * stays fail-closed against local keys instead of the production trust store.
+ *
+ * Reconstruction is byte-exact because the manifest never stores the headers
+ * themselves — only `sha256(canonicalize(headers))`, and JCS canonicalization
+ * sorts keys, so a Postgres `jsonb` round-trip (which may reorder keys) yields
+ * the same hash. The signed bytes therefore reproduce identically.
+ */
+import { type AttestationBundle, type Ed25519Jwk, type Signature, type SignedManifest, type TrustStore } from '@bluefields/attest';
+import type { Snapshot } from '@bluefields/db';
+/** Rebuild the exact `ManifestInput` the engine signed, from a snapshot row. */
+export declare function manifestInputFromRow(row: Snapshot): {
+    urlCanonical: string;
+    canonVersion: number;
+    contentHash: string;
+    rawHtmlSizeBytes: number;
+    fetchedAt: string;
+    fetchDurationMs: number;
+    fetcherId: string;
+    proxyEgressIp: string;
+    userAgent: string;
+    responseStatus: number;
+    responseHeadersHash: string;
+};
+/** The detached signature as stored on the row. */
+export declare function signatureFromRow(row: Snapshot): Signature;
+/** True when the row was actually signed (vs the no-attestation placeholder). */
+export declare function isSigned(row: Snapshot): boolean;
+/** Reconstruct the `SignedManifest` (manifest + signature) from a row. */
+export declare function signedManifestFromRow(row: Snapshot): SignedManifest;
+/** Package a signed manifest + public key as a portable, self-contained bundle. */
+export declare function toBundle(signed: SignedManifest, jwk: Ed25519Jwk): AttestationBundle;
+/** Freeze a bundle to `<store>/manifests/<snapshotId>.json`. */
+export declare function writeBundleSidecar(manifestsDir: string, snapshotId: string, bundle: AttestationBundle): void;
+/** Read a frozen bundle sidecar; null if none exists. */
+export declare function readBundleSidecar(manifestsDir: string, snapshotId: string): AttestationBundle | null;
+/**
+ * Build a trust store from a set of public JWKs (keyed by their `kid`). This is
+ * the root of trust for local `verify`: only keys explicitly present here are
+ * accepted, so an exported bundle's embedded key still can't self-authorize —
+ * it must match a key the verifier already trusts.
+ */
+export declare function localTrustStore(jwks: Ed25519Jwk[]): TrustStore;

package/dist/attestation.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Provenance glue between the snapshot store and `@bluefields/attest`.
+ *
+ * The engine signs a JCS-canonical v1 manifest and persists the detached
+ * signature + keyId on the snapshot row (not the manifest itself). This module
+ * rebuilds the exact signed manifest from a row so a capture can be verified
+ * offline, packages it as a portable `AttestationBundle` (manifest + signature
+ * + public JWK) for `export`, and builds a LOCAL trust store so `verifyBundle`
+ * stays fail-closed against local keys instead of the production trust store.
+ *
+ * Reconstruction is byte-exact because the manifest never stores the headers
+ * themselves — only `sha256(canonicalize(headers))`, and JCS canonicalization
+ * sorts keys, so a Postgres `jsonb` round-trip (which may reorder keys) yields
+ * the same hash. The signed bytes therefore reproduce identically.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildManifest, canonicalize, } from '@bluefields/attest';
+/** Rebuild the exact `ManifestInput` the engine signed, from a snapshot row. */
+export function manifestInputFromRow(row) {
+    const headers = (row.responseHeaders ?? {});
+    return {
+        urlCanonical: row.urlCanonical,
+        canonVersion: row.canonVersion,
+        contentHash: row.contentHash,
+        rawHtmlSizeBytes: row.rawHtmlSizeBytes,
+        fetchedAt: row.fetchedAt.toISOString(),
+        fetchDurationMs: row.fetchDurationMs,
+        fetcherId: row.fetcherId,
+        proxyEgressIp: String(row.proxyEgressIp),
+        userAgent: row.userAgent,
+        responseStatus: row.responseStatus,
+        responseHeadersHash: createHash('sha256').update(canonicalize(headers)).digest('hex'),
+    };
+}
+/** The detached signature as stored on the row. */
+export function signatureFromRow(row) {
+    return {
+        signature: row.attestationSignature,
+        keyId: row.attestationKeyId,
+        algorithm: row.attestationAlgorithm,
+    };
+}
+/** True when the row was actually signed (vs the no-attestation placeholder). */
+export function isSigned(row) {
+    return row.attestationSignature.length > 0 && row.attestationKeyId !== 'v0-no-attestation';
+}
+/** Reconstruct the `SignedManifest` (manifest + signature) from a row. */
+export function signedManifestFromRow(row) {
+    return { manifest: buildManifest(manifestInputFromRow(row)), signature: signatureFromRow(row) };
+}
+/** Package a signed manifest + public key as a portable, self-contained bundle. */
+export function toBundle(signed, jwk) {
+    return { manifest: signed.manifest, signature: signed.signature, jwk };
+}
+/** Sidecar path for a snapshot's bundle. */
+function sidecarPath(manifestsDir, snapshotId) {
+    return join(manifestsDir, `${snapshotId}.json`);
+}
+/** Freeze a bundle to `<store>/manifests/<snapshotId>.json`. */
+export function writeBundleSidecar(manifestsDir, snapshotId, bundle) {
+    mkdirSync(manifestsDir, { recursive: true });
+    writeFileSync(sidecarPath(manifestsDir, snapshotId), `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+}
+/** Read a frozen bundle sidecar; null if none exists. */
+export function readBundleSidecar(manifestsDir, snapshotId) {
+    try {
+        return JSON.parse(readFileSync(sidecarPath(manifestsDir, snapshotId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a trust store from a set of public JWKs (keyed by their `kid`). This is
+ * the root of trust for local `verify`: only keys explicitly present here are
+ * accepted, so an exported bundle's embedded key still can't self-authorize —
+ * it must match a key the verifier already trusts.
+ */
+export function localTrustStore(jwks) {
+    const store = {};
+    for (const jwk of jwks) {
+        if (jwk.kid)
+            store[jwk.kid] = jwk;
+    }
+    return store;
+}
+//# sourceMappingURL=attestation.js.map

package/dist/attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.js","sourceRoot":"","sources":["../src/attestation.ts"],"names":[],"mappings":"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"}

package/dist/bluefield.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The Bluefield local library — "git for web data".
+ *
+ * A thin orchestration layer over the reused engine packages:
+ *   - `@bluefields/fetcher`   → fetch + content-address + sign (fetchAndStore)
+ *   - `@bluefields/extractor` → optional structured extraction (BYO LLM key)
+ *   - `@bluefields/differ`    → line/structural diffs between snapshots
+ *   - `@bluefields/attest`    → offline signature verification
+ *
+ * It injects a LOCAL `DbClient` (PGlite) and a LOCAL filesystem
+ * `StorageAdapter` so the whole engine runs with no server, no Postgres, no
+ * KMS, and no network beyond the fetch itself. There is NO phone-home and NO
+ * telemetry anywhere in this package.
+ *
+ * Everything the CLI and the MCP server do goes through this class, so both
+ * surfaces stay thin.
+ */
+import { type Extraction } from '@bluefields/db';
+import { type FetchOptions, type FetcherAdapter } from '@bluefields/fetcher';
+import { type AnchorResult } from './anchor.js';
+import { createFsStorageAdapter } from './fs-storage.js';
+import { type LocalIdentity } from './keystore.js';
+import { type StorePaths } from './paths.js';
+import { type Store } from './store.js';
+/** Options for opening a Bluefield store. */
+export interface OpenOptions {
+    /** Override the resolved store root (default: `$BF_HOME` / nearest `.bf` / `~/.bluefield`). */
+    storeRoot?: string;
+    /** Override the keys directory (default: `~/.bluefield/keys`). Tests pass a temp dir. */
+    keysDir?: string;
+    /** Environment for fetcher/proxy/LLM config (default: `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Inject a fetcher adapter (test seam / BYO). Default: `getDefaultFetcher(env)`. */
+    fetcher?: FetcherAdapter;
+    /** Respect robots.txt on capture (default: true). */
+    respectRobotsTxt?: boolean;
+}
+/** A capture request. */
+export interface ScrapeOptions {
+    /** Sign the manifest with the local key (default: true). */
+    sign?: boolean;
+    /** Run structured extraction after capture (needs `ANTHROPIC_API_KEY` unless schema is null → markdown-only). */
+    extract?: boolean;
+    /** JSON schema for structured extraction (null/omitted → markdown-only). */
+    schema?: Record<string, unknown> | null;
+    /** One-sentence extraction intent. */
+    intent?: string | null;
+    /** Attempt transparency anchoring (best-effort; no-op if BF-rekor absent). */
+    anchor?: boolean;
+    /** Per-fetch options forwarded to the fetcher adapter. */
+    fetchOptions?: FetchOptions;
+}
+/** Outcome of a capture. */
+export type ScrapeResult = {
+    ok: true;
+    snapshotId: string;
+    contentHash: string;
+    url: string;
+    signed: boolean;
+    /** True when this capture's content hash differs from the previous snapshot of the URL. */
+    changed: boolean;
+    /** Present when `extract` was requested. */
+    extraction?: Extraction;
+    /** Present when `anchor` was requested. */
+    anchor?: AnchorResult;
+} | {
+    ok: false;
+    reason: 'robots_disallowed';
+    url: string;
+};
+/** A compact snapshot summary for `log`. */
+export interface SnapshotSummary {
+    snapshotId: string;
+    url: string;
+    contentHash: string;
+    fetchedAt: Date;
+    responseStatus: number;
+    sizeBytes: number;
+    signed: boolean;
+    keyId: string;
+}
+/** Result of a diff between two snapshots. */
+export interface DiffResult {
+    from: SnapshotSummary;
+    to: SnapshotSummary;
+    mode: 'content' | 'structured';
+    /** Unified-diff text (content mode) or a JSON string of the patch ops (structured mode). */
+    text: string;
+    added: number;
+    removed: number;
+    /** Structured-mode JSON Patch ops (empty in content mode). */
+    ops: unknown[];
+    identical: boolean;
+}
+/** Result of verifying a snapshot or bundle. */
+export interface VerifyResult {
+    ok: boolean;
+    snapshotId?: string;
+    keyId: string;
+    /** True when the on-disk content re-hashes to the manifest's content hash. */
+    contentHashMatches: boolean;
+    /** True when the detached signature verifies against a trusted key. */
+    signatureValid: boolean;
+    detail: string;
+}
+/** Result of exporting a snapshot to a directory. */
+export interface ExportResult {
+    snapshotId: string;
+    dir: string;
+    contentFile: string;
+    bundleFile: string;
+}
+/** Open (or create) a local Bluefield store. Call `close()` when done. */
+export declare function openBluefield(opts?: OpenOptions): Promise<Bluefield>;
+export declare class Bluefield {
+    readonly paths: StorePaths;
+    readonly identity: LocalIdentity;
+    private readonly store;
+    private readonly storage;
+    private readonly fetcher;
+    private readonly env;
+    private readonly respectRobotsTxt;
+    constructor(paths: StorePaths, identity: LocalIdentity, store: Store, storage: ReturnType<typeof createFsStorageAdapter>, fetcher: FetcherAdapter, env: NodeJS.ProcessEnv, respectRobotsTxt: boolean);
+    private get db();
+    /** Capture a URL: fetch → content-address on disk → sign → record → sidecar. */
+    scrape(url: string, opts?: ScrapeOptions): Promise<ScrapeResult>;
+    /** Run the extractor over a snapshot's HTML (BYO LLM key via env). */
+    private runExtract;
+    /** History: newest-first snapshots, optionally filtered to one URL. */
+    log(url?: string | null, opts?: {
+        limit?: number;
+    }): Promise<SnapshotSummary[]>;
+    /**
+     * Diff two snapshots. With one URL and no explicit `to`, diffs the two most
+     * recent snapshots of that URL. `content` mode line-diffs the raw bodies;
+     * `structured` mode JSON-patch-diffs their extractions' structured data.
+     */
+    diff(fromRef: string, toRef?: string, opts?: {
+        mode?: 'content' | 'structured';
+    }): Promise<DiffResult>;
+    /**
+     * Poll a URL on an interval, capturing each tick and reporting whether the
+     * content changed. Runs `times` iterations (default: forever) or until the
+     * `signal` aborts. `onTick` is invoked after every capture.
+     */
+    watch(url: string, opts?: {
+        intervalMs?: number;
+        times?: number;
+        signal?: AbortSignal;
+        onTick?: (r: ScrapeResult, iteration: number) => void;
+        scrape?: ScrapeOptions;
+    }): Promise<ScrapeResult[]>;
+    /**
+     * Verify a snapshot (by ref) or a previously-exported bundle. Recomputes the
+     * content hash from the stored object AND checks the signature against a
+     * trusted key (the local identity plus any keys under `<store>/trusted`, plus
+     * `extraKeys`). Fails closed on an unknown key unless `trustEmbedded` is set.
+     */
+    verify(ref: string, opts?: {
+        trustEmbedded?: boolean;
+        extraKeys?: import('@bluefields/attest').Ed25519Jwk[];
+    }): Promise<VerifyResult>;
+    /** Write a snapshot's raw content + portable bundle into `destDir`. */
+    export(ref: string, destDir: string): Promise<ExportResult>;
+    /** Retrieve the raw stored content for a snapshot ref. */
+    getContent(ref: string): Promise<string>;
+    /** The public identity (safe to share). */
+    publicIdentity(): {
+        keyId: string;
+        publicJwk: import("@bluefields/attest").Ed25519Jwk;
+    };
+    close(): Promise<void>;
+    private loadTrustedKeys;
+    private snapshotById;
+    private latestForUrl;
+    /** Resolve a ref (snapshot-id prefix, or URL → latest) to a row, or null. */
+    private resolve;
+    private mustResolve;
+    private extractionFor;
+}