fastdar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FastDAR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# fastdar
+
+The official JavaScript client for [FastDAR](https://fastdar.com). It covers buyer-intent lead alerts, the public proof ledger and market signals.
+
+It has no dependencies and runs on Node 18+, Deno, Bun and modern browsers.
+
+```sh
+npm install fastdar
+```
+
+## Check our track record yourself
+
+Every lead alert and signal FastDAR issues is committed to a public, hash-chained ledger before anyone knows how it turns out. This package re-checks the whole thing on your machine:
+
+```sh
+npx fastdar verify                      # the chain, every revealed call, sealed rules, every result
+npx fastdar receipt message.json        # a signed alert you received really came from FastDAR
+npx fastdar speed                       # median minutes from a post appearing to our sealed alert
+```
+
+```js
+import {FastDAR} from "fastdar";
+
+const fd = new FastDAR();                // public calls need no key
+const {ok, message} = await fd.proof.verify();
+console.log(ok, message);                // true "18234 entries verified, head 9f3c…"
+```
+
+## Lead alerts
+
+```js
+const fd = new FastDAR({apiKey: process.env.FASTDAR_API_KEY});
+
+const m = await fd.leads.create({
+  template: "home", area: "Leeds", offer: "emergency plumbing",
+  alerts: {email: "me@example.com", mode: "hot"},
+});
+
+for await (const lead of fd.leads.watch(m.id)) {
+  console.log(lead.score, lead.url, lead.text);
+}
+
+await fd.leads.label(m.id, postId, true);            // yes, that was a real lead
+await fd.leads.won(m.id, postId, 1200, "GBP");       // and it became a sale (sealed in the ledger)
+const report = await fd.leads.report(m.id);          // this week's numbers
+```
+
+Other calls on `fd.leads` are `templates()`, `channels()`, `list()`, `get(id)`, `update(id, {...})`, `run(id)`, `ingest(id, {posts})`, `posts(id)`, `test(id)`, `exportCsv(id)` and `insights(industry)`.
+
+## Proof, follows, market
+
+- `fd.proof` has `head()`, `key()`, `tracks()`, `rules(track)`, `stats()`, `anchors()`, `speed()`, `won()`, `ledger({after})`, `verify()` and `verifyReceipt(msg)`.
+- `fd.follow` has `tracks()`, `add({track, webhook | email})`, `list()` and `remove(id)`.
+- `fd.market` has `strategies()`, `indicators({bars, strategies})` and `scoreNews({items})`. FastDAR never serves prices; you send your own bars.
+
+Errors are thrown as `FastDARError`, which carries `status` and `detail`.
+
+## Checking without the client
+
+`import {verifyEntries, verifyReceipt, parseLossless, canonical} from "fastdar/verify"`.
+
+Parse ledger JSON with `parseLossless` rather than `JSON.parse`. Hashes are taken over the exact number text, so `1200.0` must stay `1200.0`.
+
+Receipts need Ed25519 in WebCrypto, which means Node 20+ or a current browser.
+
+MIT licence.

package/bin/fastdar.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// npx fastdar verify [site]      check the whole public ledger
+// npx fastdar receipt msg.json [site]   check a signed message
+// npx fastdar speed|tracks|won [site]
+import {readFileSync} from "node:fs";
+import {FastDAR, parseLossless} from "../src/index.js";
+
+const [cmd, a, b] = process.argv.slice(2);
+const site = (cmd === "receipt" ? b : a) || process.env.FASTDAR_BASE_URL || "https://fastdar.com";
+const c = new FastDAR({baseUrl: site});
+const out = (x) => console.log(JSON.stringify(x, null, 2));
+
+try {
+  if (cmd === "verify") {
+    const r = await c.proof.verify({onPage: (n) => process.stderr.write(`\rread ${n} entries`)});
+    process.stderr.write("\n");
+    console.log((r.ok ? "OK: " : "FAILED: ") + r.message);
+    process.exit(r.ok ? 0 : 1);
+  } else if (cmd === "receipt" && a) {
+    const ok = await c.proof.verifyReceipt(parseLossless(readFileSync(a, "utf8")));
+    console.log(ok ? "OK: signed by this site's FastDAR key" : "FAILED: the signature doesn't match this message");
+    process.exit(ok ? 0 : 1);
+  } else if (cmd === "speed") out(await c.proof.speed());
+  else if (cmd === "tracks") out(await c.proof.tracks());
+  else if (cmd === "won") out(await c.proof.won());
+  else {
+    console.log("usage: fastdar verify [site] | receipt <message.json> [site] | speed [site] | tracks [site] | won [site]");
+    process.exit(cmd ? 2 : 0);
+  }
+} catch (e) {
+  console.error(`error: ${e.message}`);
+  process.exit(2);
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "fastdar",
+  "version": "0.1.0",
+  "description": "FastDAR client: buyer-intent lead alerts, a public proof ledger you can check yourself, and market signals.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {"types": "./src/index.d.ts", "default": "./src/index.js"},
+    "./verify": {"types": "./src/verify.d.ts", "default": "./src/verify.js"}
+  },
+  "bin": {"fastdar": "./bin/fastdar.js"},
+  "files": ["src", "bin", "README.md", "LICENSE"],
+  "engines": {"node": ">=18"},
+  "scripts": {"test": "node --test test/*.test.js"},
+  "keywords": ["fastdar", "lead-alerts", "buyer-intent", "proof", "transparency-log", "trading-signals"],
+  "homepage": "https://fastdar.com",
+  "repository": {"type": "git", "url": "git+https://github.com/FastDAR/fastdar.git", "directory": "sdk/js"},
+  "license": "MIT",
+  "sideEffects": false
+}

package/src/index.d.ts

@@ -0,0 +1,154 @@
+import type {LedgerEntry, VerifyResult} from "./verify.js";
+export {parseLossless, verifyEntries, verifyReceipt, canonical, RawNumber, GENESIS} from "./verify.js";
+export type {LedgerEntry, VerifyResult} from "./verify.js";
+
+export declare const DEFAULT_BASE_URL: string;
+
+export declare class FastDARError extends Error {
+  status: number;
+  detail: unknown;
+  body: unknown;
+}
+
+export interface FastDAROptions {
+  /** Defaults to process.env.FASTDAR_API_KEY. Public calls (proof, trending, templates) need no key. */
+  apiKey?: string;
+  /** Defaults to process.env.FASTDAR_BASE_URL, then https://fastdar.com */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export type AlertMode = "instant" | "hot" | "digest";
+
+export interface Alerts {
+  email?: string;
+  slack_webhook?: string;
+  discord_webhook?: string;
+  teams_webhook?: string;
+  webhook?: string;
+  telegram_chat_id?: string;
+  ntfy_topic?: string;
+  sms_to?: string;
+  mode?: AlertMode;
+  hot_score?: number;
+  digest?: "hourly" | "daily";
+  digest_hour?: number;
+  timezone?: string;
+  quiet_hours?: string;
+  min_score?: number;
+  must_include?: string[];
+  exclude?: string[];
+  max_per_day?: number;
+  weekly_report?: boolean;
+  currency?: string;
+  hubspot_token?: string;
+  hubspot_stage?: string;
+  pipedrive_token?: string;
+  crm_push?: "confirmed" | "all";
+  [k: string]: unknown;
+}
+
+export interface MonitorInput {
+  /** An industry template id from leads.templates(); fills terms and sources. */
+  template?: string;
+  /** Place name added to local templates' phrases. */
+  area?: string;
+  /** What you sell, in one plain line. */
+  offer: string;
+  name?: string;
+  terms?: string[];
+  sources?: Record<string, unknown>;
+  alerts?: Alerts;
+}
+
+export interface Monitor {
+  id: number;
+  name: string;
+  offer: string;
+  industry: string | null;
+  terms: string[];
+  sources: Record<string, unknown>;
+  alerts: Alerts;
+  active: number;
+  last_run: number;
+  review_url: string;
+  report_url: string;
+  [k: string]: unknown;
+}
+
+export interface LeadItem {
+  id: number;
+  source: string;
+  url: string | null;
+  text: string;
+  score: number;
+  label: "lead" | "not a lead" | null;
+  found: number;
+  won?: number;
+  won_currency?: string;
+}
+
+declare class Leads {
+  templates(): Promise<{templates: Array<{id: string; name: string; [k: string]: unknown}>}>;
+  channels(): Promise<any>;
+  create(body: MonitorInput): Promise<Monitor>;
+  list(): Promise<Monitor[]>;
+  get(id: number): Promise<Monitor>;
+  update(id: number, body: Partial<MonitorInput> & {active?: boolean}): Promise<Monitor>;
+  run(id: number): Promise<any>;
+  ingest(id: number, body: {posts: Array<{text: string; id?: string; url?: string; author?: string; platform?: string; created?: number}>}): Promise<any>;
+  posts(id: number, opts?: {which?: "alerts" | "review"; limit?: number}): Promise<any[]>;
+  label(id: number, postId: number, isLead: boolean): Promise<any>;
+  won(id: number, postId: number, value: number | null, currency?: string): Promise<{ok: boolean; won: {sales: number; value: Array<{currency: string; total: number}>}}>;
+  report(id: number, opts?: {days?: number}): Promise<any>;
+  test(id: number): Promise<{sent: string[]; failed: string[]}>;
+  exportCsv(id: number): Promise<string>;
+  insights(industry: string): Promise<any>;
+  /** New alerts as they're found. */
+  watch(id: number, opts?: {signal?: AbortSignal; lastEventId?: string}): AsyncGenerator<LeadItem>;
+}
+
+declare class Proof {
+  head(): Promise<any>;
+  key(): Promise<{alg: "ed25519"; public_key: string; key_id: string}>;
+  tracks(): Promise<any>;
+  rules(track: string): Promise<any>;
+  stats(): Promise<any>;
+  anchors(): Promise<any>;
+  speed(opts?: {days?: number}): Promise<{window_days: number; alerts: number; enough: boolean; median_minutes?: number; p90_minutes?: number}>;
+  won(opts?: {days?: number}): Promise<any>;
+  ledger(opts?: {after?: number; limit?: number}): Promise<LedgerEntry[]>;
+  verify(opts?: {onPage?: (entriesSoFar: number) => void}): Promise<VerifyResult & {entries: number}>;
+  verifyReceipt(message: Record<string, unknown>): Promise<boolean>;
+}
+
+declare class Follow {
+  tracks(): Promise<any>;
+  add(body: {track: string; webhook?: string; email?: string}): Promise<any>;
+  list(): Promise<any>;
+  remove(id: number): Promise<any>;
+}
+
+declare class Market {
+  strategies(): Promise<Record<string, {bar_minutes: number; multi_day: boolean}>>;
+  indicators(body: {bars: unknown; strategies?: string[] | "all"; [k: string]: unknown}): Promise<any>;
+  scoreNews(body: {symbol?: string; headline?: string; summary?: string; items?: Array<{symbol: string; headline: string; summary?: string}>}): Promise<any>;
+}
+
+export declare class FastDAR {
+  constructor(opts?: FastDAROptions);
+  apiKey?: string;
+  baseUrl: string;
+  leads: Leads;
+  proof: Proof;
+  follow: Follow;
+  market: Market;
+  usage(): Promise<any>;
+  health(): Promise<any>;
+  trending(): Promise<any>;
+  stream(industry: string): Promise<any>;
+  systemone(req: {state: string; questions: Record<string, unknown>}): Promise<any>;
+}
+
+export default FastDAR;

package/src/index.js

@@ -0,0 +1,201 @@
+// FastDAR API client: buyer-intent lead alerts, the public proof ledger, and market signals.
+// Zero dependencies; needs a global fetch (Node 18+, Deno, Bun, browsers).
+import {parseLossless, verifyEntries, verifyReceipt} from "./verify.js";
+
+export {parseLossless, verifyEntries, verifyReceipt, canonical, RawNumber, GENESIS} from "./verify.js";
+
+export const DEFAULT_BASE_URL = "https://fastdar.com";
+
+export class FastDARError extends Error {
+  constructor(status, detail, body) {
+    super(typeof detail === "string" ? detail : `HTTP ${status}`);
+    this.name = "FastDARError";
+    this.status = status;
+    this.detail = detail;
+    this.body = body;
+  }
+}
+
+const enc = encodeURIComponent;
+
+export class FastDAR {
+  /**
+   * @param {{apiKey?: string, baseUrl?: string, fetch?: typeof fetch, timeoutMs?: number}} [opts]
+   */
+  constructor(opts = {}) {
+    const env = typeof process !== "undefined" && process.env ? process.env : {};
+    this.apiKey = opts.apiKey ?? env.FASTDAR_API_KEY;
+    this.baseUrl = (opts.baseUrl ?? env.FASTDAR_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetch = opts.fetch ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? 30000;
+    if (!this.fetch) throw new Error("no fetch available; pass opts.fetch");
+    this.leads = new Leads(this);
+    this.proof = new Proof(this);
+    this.follow = new Follow(this);
+    this.market = new Market(this);
+  }
+
+  async _raw(method, path, {body, auth = true, query} = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query || {})) if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    const headers = {Accept: "application/json"};
+    if (auth) {
+      if (!this.apiKey) throw new FastDARError(401, "this call needs an API key (opts.apiKey or FASTDAR_API_KEY)");
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    const ctl = typeof AbortController !== "undefined" ? new AbortController() : null;
+    const t = ctl ? setTimeout(() => ctl.abort(), this.timeoutMs) : null;
+    try {
+      const r = await this.fetch(url, {method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: ctl?.signal});
+      if (!r.ok) {
+        const text = await r.text();
+        let j = null;
+        try { j = JSON.parse(text); } catch {}
+        throw new FastDARError(r.status, j?.detail ?? (text || `HTTP ${r.status}`), j ?? text);
+      }
+      return r;
+    } finally {
+      if (t) clearTimeout(t);
+    }
+  }
+
+  async _json(method, path, opts) {
+    return (await this._raw(method, path, opts)).json();
+  }
+
+  /** Your key's plan and usage. */
+  usage() { return this._json("GET", "/v1/usage"); }
+  /** Server health. */
+  health() { return this._json("GET", "/health", {auth: false}); }
+  /** Public trending asks per category (last 7 days). */
+  trending() { return this._json("GET", "/v1/trending", {auth: false}); }
+  /** Public live asks in one industry: links and scores only. */
+  stream(industry) { return this._json("GET", `/stream/${enc(industry)}.json`, {auth: false}); }
+  /** Fast-tier structured answers: {state, questions}. */
+  systemone(req) { return this._json("POST", "/v1/systemone", {body: req}); }
+}
+
+class Leads {
+  constructor(c) { this.c = c; }
+  /** Industry starter templates. */
+  templates() { return this.c._json("GET", "/v1/leads/templates", {auth: false}); }
+  /** Alert channels and options this server supports. */
+  channels() { return this.c._json("GET", "/v1/leads/channels", {auth: false}); }
+  /** Create a monitor: {template?, area?, offer, terms?, sources?, alerts?, name?}. */
+  create(body) { return this.c._json("POST", "/v1/leads/monitors", {body}); }
+  list() { return this.c._json("GET", "/v1/leads/monitors"); }
+  get(id) { return this.c._json("GET", `/v1/leads/monitors/${enc(id)}`); }
+  /** Change name, offer, terms, sources, alerts or active. */
+  update(id, body) { return this.c._json("PATCH", `/v1/leads/monitors/${enc(id)}`, {body}); }
+  /** Poll a monitor's sources now. */
+  run(id) { return this.c._json("POST", `/v1/leads/monitors/${enc(id)}/run`); }
+  /** Push your own posts to be screened: {posts: [{text, id or url, url?, author?, platform?, created?}]} (up to 1000). */
+  ingest(id, body) { return this.c._json("POST", `/v1/leads/monitors/${enc(id)}/ingest`, {body}); }
+  /** which: "alerts" (default) or "review". */
+  posts(id, {which, limit} = {}) { return this.c._json("GET", `/v1/leads/monitors/${enc(id)}/posts`, {query: {which, limit}}); }
+  /** Answer an alert: it was (true) or wasn't (false) a real lead. */
+  label(id, postId, isLead) { return this.c._json("POST", `/v1/leads/monitors/${enc(id)}/posts/${enc(postId)}/label`, {body: {is_lead: !!isLead}}); }
+  /** This lead became a sale. value null undoes it. The sale is sealed in the proof ledger. */
+  won(id, postId, value, currency) {
+    return this.c._json("POST", `/v1/leads/monitors/${enc(id)}/posts/${enc(postId)}/won`, {body: {value, ...(currency ? {currency} : {})}});
+  }
+  report(id, {days} = {}) { return this.c._json("GET", `/v1/leads/monitors/${enc(id)}/report`, {query: {days}}); }
+  /** Send a test alert to every configured channel. */
+  test(id) { return this.c._json("POST", `/v1/leads/monitors/${enc(id)}/test`); }
+  /** Every post read for this monitor, as CSV text. */
+  async exportCsv(id) { return (await this.c._raw("GET", `/v1/leads/monitors/${enc(id)}/export.csv`)).text(); }
+  /** Which phrases and sources find real leads in an industry, pooled across customers. */
+  insights(industry) { return this.c._json("GET", `/v1/leads/insights/${enc(industry)}`); }
+
+  /**
+   * New alerts as they're found (server-sent events). Yields parsed alerts; stop with break or opts.signal.
+   * @param {number|string} id
+   * @param {{signal?: AbortSignal, lastEventId?: string}} [opts]
+   */
+  async *watch(id, opts = {}) {
+    const headers = {Accept: "text/event-stream", Authorization: `Bearer ${this.c.apiKey}`};
+    if (opts.lastEventId) headers["Last-Event-ID"] = opts.lastEventId;
+    const r = await this.c.fetch(`${this.c.baseUrl}/v1/leads/monitors/${enc(id)}/stream`, {headers, signal: opts.signal});
+    if (!r.ok) throw new FastDARError(r.status, await r.text());
+    const reader = r.body.getReader(), dec = new TextDecoder();
+    let buf = "";
+    for (;;) {
+      const {value, done} = await reader.read();
+      if (done) return;
+      buf += dec.decode(value, {stream: true});
+      let cut;
+      while ((cut = buf.indexOf("\n\n")) >= 0) {
+        const block = buf.slice(0, cut); buf = buf.slice(cut + 2);
+        let event = "message", data = "";
+        for (const line of block.split("\n")) {
+          if (line.startsWith("event:")) event = line.slice(6).trim();
+          else if (line.startsWith("data:")) data += line.slice(5).trim();
+        }
+        if (event === "lead" && data) yield JSON.parse(data);
+      }
+    }
+  }
+}
+
+class Proof {
+  constructor(c) { this.c = c; }
+  head() { return this.c._json("GET", "/proof/head", {auth: false}); }
+  key() { return this.c._json("GET", "/proof/key", {auth: false}); }
+  /** Every track ever run, losers and retired ones included. */
+  tracks() { return this.c._json("GET", "/proof/tracks", {auth: false}); }
+  rules(track) { return this.c._json("GET", `/proof/rules/${enc(track)}`, {auth: false}); }
+  stats() { return this.c._json("GET", "/proof/stats", {auth: false}); }
+  anchors() { return this.c._json("GET", "/proof/anchors", {auth: false}); }
+  /** Median minutes from a post appearing to its sealed alert. */
+  speed({days} = {}) { return this.c._json("GET", "/proof/speed", {auth: false, query: {days}}); }
+  /** Sales customers reported, pooled. */
+  won({days} = {}) { return this.c._json("GET", "/proof/won", {auth: false, query: {days}}); }
+
+  /** Ledger entries, numbers kept exactly as sent (see parseLossless). Pages of up to 1000. */
+  async ledger({after = 0, limit = 1000} = {}) {
+    const r = await this.c._raw("GET", "/proof/ledger", {auth: false, query: {after, limit}});
+    return parseLossless(await r.text()).entries;
+  }
+
+  /** Download the whole ledger and check it. Resolves to {ok, message, entries}. */
+  async verify({onPage} = {}) {
+    const all = [];
+    for (let after = 0; ;) {
+      const page = await this.ledger({after});
+      all.push(...page);
+      if (onPage) onPage(all.length);
+      if (page.length < 1000) break;
+      after = Number(page[page.length - 1].seq);
+    }
+    const res = await verifyEntries(all);
+    return {...res, entries: all.length};
+  }
+
+  /** Check a signed message (a follower alert, or /proof/head) with the server's published key. */
+  async verifyReceipt(message) {
+    const k = await this.key();
+    return verifyReceipt(message, k.public_key);
+  }
+}
+
+class Follow {
+  constructor(c) { this.c = c; }
+  tracks() { return this.c._json("GET", "/v1/follow/tracks", {auth: false}); }
+  /** Get each sealed call on a track: {track, webhook} or {track, email}. */
+  add(body) { return this.c._json("POST", "/v1/follow", {body}); }
+  list() { return this.c._json("GET", "/v1/follow"); }
+  remove(id) { return this.c._json("DELETE", `/v1/follow/${enc(id)}`); }
+}
+
+class Market {
+  constructor(c) { this.c = c; }
+  /** Strategy names with their bar size. */
+  strategies() { return this.c._json("GET", "/v1/strategies", {auth: false}); }
+  /** Signals on bars you send (FastDAR never serves prices): {bars, strategies?}. */
+  indicators(body) { return this.c._json("POST", "/v1/indicators", {body}); }
+  /** Score headlines: {symbol, headline, summary?} or {items: [...]}. */
+  scoreNews(body) { return this.c._json("POST", "/v1/news/score", {body}); }
+}
+
+export default FastDAR;

package/src/verify.d.ts

@@ -0,0 +1,37 @@
+export declare const GENESIS: string;
+
+/** A number kept as the exact text the server sent. */
+export declare class RawNumber {
+  constructor(raw: string);
+  raw: string;
+  valueOf(): number;
+  toJSON(): number;
+}
+
+/** JSON.parse that keeps every number as a RawNumber, so hashes can be recomputed exactly. */
+export declare function parseLossless(text: string): any;
+/** Canonical JSON, byte-for-byte as the FastDAR server hashes it. */
+export declare function canonical(value: unknown): string;
+export declare function sha256Hex(text: string): Promise<string>;
+export declare function commitment(salt: string, payload: unknown): Promise<string>;
+export declare function link(prev: string, seq: number | RawNumber, kind: string, issued: number | RawNumber, commit: string): Promise<string>;
+
+export interface LedgerEntry {
+  seq: number | RawNumber;
+  kind: string;
+  issued: number | RawNumber;
+  commit: string;
+  prev: string;
+  chain: string;
+  payload?: any;
+  salt?: string;
+  outcome?: any;
+  scored?: number | RawNumber;
+}
+
+export interface VerifyResult { ok: boolean; message: string }
+
+/** Check the hash chain, every revealed payload, the sealed rules and every shown outcome. */
+export declare function verifyEntries(entries: LedgerEntry[], startPrev?: string): Promise<VerifyResult>;
+/** Check a signed message against FastDAR's public key (hex). Needs Ed25519 in WebCrypto (Node 20+). */
+export declare function verifyReceipt(message: {receipt?: {sig: string; alg?: string; key_id?: string}; [k: string]: unknown}, publicKeyHex: string): Promise<boolean>;

package/src/verify.js

@@ -0,0 +1,167 @@
+// Check a FastDAR proof ledger yourself, in Node 18+ or any modern browser, with no dependencies.
+// It mirrors fastjev/proof.py verify(): the hash chain, every revealed payload against its commitment,
+// the sealed-rules rules, and that each shown outcome is the one sealed in its result or correction.
+//
+// Hashes are computed over canonical JSON exactly as the server writes it, so numbers must keep the
+// text they were sent with (1200.0 stays "1200.0"). parseLossless() below does that; plain JSON.parse
+// would turn 1200.0 into 1200 and every commitment containing it would look wrong.
+
+export const GENESIS = "0".repeat(64);
+const SEALS = new Set(["result", "correction"]);
+
+/** A number kept as the exact text the server sent. */
+export class RawNumber {
+  constructor(raw) { this.raw = raw; }
+  valueOf() { return Number(this.raw); }
+  toJSON() { return Number(this.raw); }
+}
+
+/** JSON.parse that keeps every number as a RawNumber. */
+export function parseLossless(text) {
+  let i = 0;
+  const ws = () => { while (i < text.length && " \t\n\r".includes(text[i])) i++; };
+  const fail = (m) => { throw new SyntaxError(`${m} at position ${i}`); };
+  function value() {
+    ws();
+    const c = text[i];
+    if (c === "{") {
+      i++; const o = {}; ws();
+      if (text[i] === "}") { i++; return o; }
+      for (;;) {
+        ws(); if (text[i] !== '"') fail("expected a key");
+        const k = str(); ws(); if (text[i++] !== ":") fail("expected ':'");
+        o[k] = value(); ws();
+        if (text[i] === ",") { i++; continue; }
+        if (text[i++] === "}") return o;
+        fail("expected ',' or '}'");
+      }
+    }
+    if (c === "[") {
+      i++; const a = []; ws();
+      if (text[i] === "]") { i++; return a; }
+      for (;;) {
+        a.push(value()); ws();
+        if (text[i] === ",") { i++; continue; }
+        if (text[i++] === "]") return a;
+        fail("expected ',' or ']'");
+      }
+    }
+    if (c === '"') return str();
+    if (text.startsWith("true", i)) { i += 4; return true; }
+    if (text.startsWith("false", i)) { i += 5; return false; }
+    if (text.startsWith("null", i)) { i += 4; return null; }
+    const m = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(text.slice(i, i + 64));
+    if (!m) fail("unexpected token");
+    i += m[0].length;
+    return new RawNumber(m[0]);
+  }
+  function str() {
+    const start = i; i++;
+    while (i < text.length && text[i] !== '"') i += text[i] === "\\" ? 2 : 1;
+    i++;
+    return JSON.parse(text.slice(start, i));
+  }
+  const out = value(); ws();
+  if (i !== text.length) fail("trailing data");
+  return out;
+}
+
+// Python json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+export function canonical(v) {
+  if (v === null) return "null";
+  if (v instanceof RawNumber) return v.raw;
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new TypeError("not a JSON number");
+    return Number.isInteger(v) ? String(v) : pyFloat(v);
+  }
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(canonical).join(",") + "]";
+  const keys = Object.keys(v).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}";
+}
+
+// repr() of a Python float, for numbers built in JS rather than parsed losslessly
+function pyFloat(x) {
+  const s = String(x);
+  if (/e/.test(s)) {
+    const [m, e] = s.split("e");
+    const exp = Number(e);
+    if (exp >= 16 || exp < -4) return `${m}e${exp < 0 ? "-" : "+"}${String(Math.abs(exp)).padStart(2, "0")}`;
+  }
+  return s.includes(".") ? s : s + ".0";
+}
+
+const enc = new TextEncoder();
+export async function sha256Hex(text) {
+  const d = await globalThis.crypto.subtle.digest("SHA-256", enc.encode(text));
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export const commitment = (salt, payload) => sha256Hex(salt + canonical(payload));
+export const link = (prev, seq, kind, issued, commit) =>
+  sha256Hex(`${prev}|${Number(seq)}|${kind}|${Number(issued).toFixed(3)}|${commit}`);
+
+const n = (x) => (x == null ? x : Number(x));
+
+/**
+ * Verify ledger entries (as returned by GET /proof/ledger, parsed with parseLossless).
+ * Resolves to {ok, message}.
+ */
+export async function verifyEntries(entries, startPrev = GENESIS) {
+  let prev = startPrev;
+  for (const e of entries) {
+    const seq = n(e.seq);
+    if (e.prev !== prev) return {ok: false, message: `seq ${seq}: prev does not match the chain before it`};
+    if ((await link(prev, seq, e.kind, e.issued, e.commit)) !== e.chain)
+      return {ok: false, message: `seq ${seq}: chain hash is wrong`};
+    if ("payload" in e && (await commitment(e.salt, e.payload)) !== e.commit)
+      return {ok: false, message: `seq ${seq}: revealed payload does not match what was committed`};
+    prev = e.chain;
+  }
+  const seenRules = new Map(), current = new Map();
+  for (const e of entries) {
+    const p = e.payload || {}, seq = n(e.seq);
+    if (e.kind === "rules" && "payload" in e) { seenRules.set(seq, e); current.set(p.strategy, seq); }
+    const rs = SEALS.has(e.kind) ? null : n(p.rules_seq);
+    if (rs != null) {
+      const r = seenRules.get(rs);
+      if (!r || n(r.seq) >= seq) return {ok: false, message: `seq ${seq}: names rules entry ${rs}, which isn't a published rules entry before it`};
+      if (r.payload.retired) return {ok: false, message: `seq ${seq}: issued under retired rules ${rs}`};
+      if (r.payload.strategy !== p.strategy || current.get(p.strategy) !== rs)
+        return {ok: false, message: `seq ${seq}: rules ${rs} aren't the current rules for ${p.strategy}`};
+    }
+  }
+  const bySeq = new Map(entries.map((e) => [n(e.seq), e])), last = new Map();
+  for (const e of entries) {
+    if (SEALS.has(e.kind) && "payload" in e) {
+      const ref = n(e.payload.ref);
+      if (e.kind === "correction" && last.has(ref) && n(e.payload.supersedes) !== n(last.get(ref).seq))
+        return {ok: false, message: `seq ${n(e.seq)}: correction doesn't supersede the latest result for seq ${ref}`};
+      last.set(ref, e);
+    }
+  }
+  for (const [ref, e] of last) {
+    const r = bySeq.get(ref);
+    if (r && canonical(r.outcome ?? null) !== canonical(e.payload.outcome))
+      return {ok: false, message: `seq ${ref}: shown outcome differs from the sealed ${e.kind} at seq ${n(e.seq)}`};
+  }
+  return {ok: true, message: `${entries.length} entries verified, head ${prev}`};
+}
+
+const hexBytes = (h) => new Uint8Array((h.match(/../g) || []).map((b) => parseInt(b, 16)));
+
+/**
+ * Check a signed message (a follower alert, or /proof/head) against FastDAR's public key (hex, from /proof/key).
+ * Needs Ed25519 in WebCrypto: Node 20+, and current Chrome, Firefox and Safari.
+ */
+export async function verifyReceipt(message, publicKeyHex) {
+  const {receipt, ...rest} = message;
+  if (!receipt || !receipt.sig) return false;
+  try {
+    const key = await globalThis.crypto.subtle.importKey("raw", hexBytes(publicKeyHex), {name: "Ed25519"}, false, ["verify"]);
+    return await globalThis.crypto.subtle.verify({name: "Ed25519"}, key, hexBytes(receipt.sig), enc.encode(canonical(rest)));
+  } catch {
+    return false;
+  }
+}