@thehonestmachine/oath-sdk 0.1.0

package/src/remote.ts

@@ -0,0 +1,112 @@
+import {
+  assertValidEntry,
+  assertValidOathDoc,
+  assertValidReceipt,
+  entryLeafHash,
+  ProtocolError,
+  verifyReceiptSignature,
+  type Entry,
+  type OathDoc,
+  type Receipt,
+} from '@thehonestmachine/oath-core';
+
+export interface LedgerDiscovery {
+  ledger: string;
+  pubkey: string;
+  api: string;
+  mmd_seconds: number;
+  spec_version: string;
+}
+
+export interface SubmitResult {
+  leaf_index: number;
+  leaf_hash: string;
+  receipt: Receipt;
+}
+
+/**
+ * A client for a public ledger's API (SPEC.md §11.2) that trusts nothing:
+ * every receipt is validated and signature-checked against the ledger's
+ * published key before it is returned to the caller.
+ */
+export class RemoteLedger {
+  private readonly base: string;
+  private readonly f: typeof fetch;
+  private cachedDiscovery: LedgerDiscovery | null = null;
+
+  constructor(baseUrl: string, options: { fetch?: typeof fetch } = {}) {
+    this.base = baseUrl.replace(/\/+$/, '');
+    this.f = options.fetch ?? fetch;
+  }
+
+  private async request(path: string, init?: RequestInit): Promise<unknown> {
+    const response = await this.f(`${this.base}${path}`, init);
+    const body = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!response.ok) {
+      throw new ProtocolError(
+        `ledger ${path} -> ${response.status}${typeof body['error'] === 'string' ? `: ${body['error']}` : ''}`,
+      );
+    }
+    return body;
+  }
+
+  async discovery(): Promise<LedgerDiscovery> {
+    if (this.cachedDiscovery === null) {
+      this.cachedDiscovery = (await this.request('/v0/ledger.json')) as LedgerDiscovery;
+    }
+    return this.cachedDiscovery;
+  }
+
+  private async checkedResult(entry: Entry, raw: Record<string, unknown>): Promise<SubmitResult> {
+    const receipt = raw['receipt'];
+    assertValidReceipt(receipt);
+    const { pubkey } = await this.discovery();
+    if (!verifyReceiptSignature(receipt, pubkey)) {
+      throw new ProtocolError("the ledger's receipt signature does not verify against its published key");
+    }
+    if (receipt.leaf_hash !== entryLeafHash(entry)) {
+      throw new ProtocolError('the receipt commits to a different leaf than the submitted entry');
+    }
+    return { leaf_index: Number(raw['leaf_index']), leaf_hash: receipt.leaf_hash, receipt };
+  }
+
+  /** Swear an agent: submit the signed oath v1 plus its oath.swear entry (§2.4). */
+  async swear(oath: OathDoc, entry: Entry): Promise<SubmitResult> {
+    assertValidOathDoc(oath);
+    assertValidEntry(entry);
+    const raw = (await this.request('/v0/agents', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ oath, entry }),
+    })) as Record<string, unknown>;
+    return this.checkedResult(entry, raw);
+  }
+
+  /** Submit a signed entry; idempotent by leaf hash on the ledger side. */
+  async submit(entry: Entry): Promise<SubmitResult> {
+    assertValidEntry(entry);
+    const raw = (await this.request('/v0/entries', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ entry }),
+    })) as Record<string, unknown>;
+    return this.checkedResult(entry, raw);
+  }
+
+  /** Submit an amendment: the new oath version plus its oath.amend entry (§9). */
+  async amend(handle: string, oath: OathDoc, entry: Entry): Promise<SubmitResult> {
+    assertValidOathDoc(oath);
+    assertValidEntry(entry);
+    const raw = (await this.request(`/v0/agents/${handle}/oath`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ oath, entry }),
+    })) as Record<string, unknown>;
+    return this.checkedResult(entry, raw);
+  }
+
+  /** The agent's public record: oath versions, entry count, and index. */
+  async agent(handle: string): Promise<Record<string, unknown>> {
+    return (await this.request(`/v0/agents/${handle}`)) as Record<string, unknown>;
+  }
+}

package/src/verify.ts

@@ -0,0 +1,331 @@
+import {
+  assertEntryUnderOath,
+  assertValidAmendment,
+  assertValidEntry,
+  assertValidOathDoc,
+  assertValidSth,
+  bytesToHex,
+  canonicalize,
+  consistencyPath,
+  hexToBytes,
+  leafHash,
+  oathHash,
+  rootFromLeafHashes,
+  utf8Bytes,
+  verifyConsistency,
+  verifyOathSignature,
+  verifySthSignature,
+  type Entry,
+  type OathDoc,
+  type SignedTreeHead,
+} from '@thehonestmachine/oath-core';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { LEDGER_FILES, readLeafLines, readOathVersions } from './localLedger.js';
+
+export interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface VerificationReport {
+  ok: boolean;
+  source: string;
+  agents: string[];
+  treeSize: number;
+  checks: CheckResult[];
+}
+
+/** Everything a monitor needs, however it was obtained. All of it public. */
+export interface LedgerData {
+  source: string;
+  /** Exact leaf bytes, position = leaf index. */
+  leafLines: string[];
+  /** Every signed tree head, in emission order. */
+  heads: SignedTreeHead[];
+  /** Keys allowed to sign tree heads (agent key locally, ledger key remotely). */
+  sthPubkeys: string[];
+  /** Oath version chains per agent handle. */
+  oathsByAgent: Map<string, OathDoc[]>;
+}
+
+/**
+ * Verify ledger contents from nothing but public data (SPEC.md §6, §11):
+ * recompute the tree, re-check every signature, every tree head, every oath
+ * chain, and the consistency of the whole history. Needs no keys and no
+ * trust in the operator — this is what a monitor runs.
+ */
+export function verifyLedgerData(data: LedgerData): VerificationReport {
+  const { leafLines, heads, sthPubkeys, oathsByAgent } = data;
+  const checks: CheckResult[] = [];
+  const agents = [...oathsByAgent.keys()];
+  checks.push({
+    name: 'files',
+    ok: true,
+    detail: `${agents.length} agent(s), ${leafLines.length} entries, ${heads.length} tree heads`,
+  });
+
+  // 1. Oath chains: v1 self-signed, every later version a valid amendment (§2, §9).
+  const chainProblems: string[] = [];
+  for (const [handle, versions] of oathsByAgent) {
+    try {
+      if (versions.length === 0) throw new Error('no oath versions');
+      versions.forEach((doc) => assertValidOathDoc(doc));
+      if (versions[0]!.version !== 1) throw new Error('chain does not start at version 1');
+      if (!verifyOathSignature(versions[0]!)) {
+        throw new Error('v1 signature does not verify against its own pubkey');
+      }
+      for (let i = 1; i < versions.length; i++) {
+        assertValidAmendment(versions[i - 1]!, versions[i]!);
+      }
+    } catch (error) {
+      chainProblems.push(`${handle}: ${(error as Error).message}`);
+    }
+  }
+  checks.push({
+    name: 'oath-chain',
+    ok: chainProblems.length === 0,
+    detail:
+      chainProblems.length === 0
+        ? `${agents.length} chain(s), forward-only, signatures verify`
+        : chainProblems.join('; '),
+  });
+
+  // 2. Every entry: canonical bytes, valid shape, signed under its oath version (§3).
+  const entries: (Entry | null)[] = [];
+  const entryProblems: string[] = [];
+  leafLines.forEach((line, i) => {
+    try {
+      const parsed = JSON.parse(line) as unknown;
+      if (canonicalize(parsed) !== line) throw new Error('line is not in canonical (JCS) form');
+      assertValidEntry(parsed);
+      const versions = oathsByAgent.get(parsed.agent);
+      const oath = versions?.find((o) => o.version === parsed.oath_version);
+      if (oath === undefined) {
+        throw new Error(`cites unknown oath ${parsed.agent} v${parsed.oath_version}`);
+      }
+      assertEntryUnderOath(parsed, oath);
+      entries.push(parsed);
+    } catch (error) {
+      entries.push(null);
+      entryProblems.push(`entry ${i}: ${(error as Error).message}`);
+    }
+  });
+  checks.push({
+    name: 'entries',
+    ok: entryProblems.length === 0,
+    detail:
+      entryProblems.length === 0
+        ? `${leafLines.length} entries valid, canonical, and signed`
+        : entryProblems.join('; '),
+  });
+
+  // 3. Sworn records: each agent's first entry is its oath.swear; every
+  //    amendment is committed to by an oath.amend entry (§2.4, §9).
+  const recordProblems: string[] = [];
+  for (const [handle, versions] of oathsByAgent) {
+    const own = entries.filter((e): e is Entry => e !== null && e.agent === handle);
+    const first = own[0];
+    const v1Hash = versions.length > 0 ? safeOathHash(versions[0]!) : null;
+    if (first === undefined || first.action.type !== 'oath.swear' || first.action.content_hash !== v1Hash) {
+      recordProblems.push(`${handle}: first entry is not oath.swear committing to oath v1`);
+    }
+    // Every declared amendment must be committed to by exactly its own leaf...
+    const validAmendHashes = new Set<string>();
+    for (let v = 2; v <= versions.length; v++) {
+      const hash = safeOathHash(versions[v - 1]!);
+      if (hash !== null) validAmendHashes.add(hash);
+      if (!own.some((e) => e.action.type === 'oath.amend' && e.action.content_hash === hash)) {
+        recordProblems.push(`${handle}: no oath.amend entry commits to oath v${v}`);
+      }
+    }
+    // ...and no reserved oath-lifecycle leaf may be forged. A stranger's
+    // monitor is the trust anchor: an extra oath.swear, or an oath.amend
+    // committing to an oath that was never served, must fail verification.
+    own.forEach((e, i) => {
+      if (e.action.type === 'oath.swear' && (i !== 0 || e.action.content_hash !== v1Hash)) {
+        recordProblems.push(`${handle}: leaf with a forged/misplaced oath.swear (only leaf 0 may swear v1)`);
+      }
+      if (e.action.type === 'oath.amend' && !validAmendHashes.has(e.action.content_hash ?? '')) {
+        recordProblems.push(`${handle}: oath.amend commits to an oath version the ledger never served`);
+      }
+    });
+  }
+  checks.push({
+    name: 'sworn-record',
+    ok: recordProblems.length === 0,
+    detail:
+      recordProblems.length === 0
+        ? 'every agent swore at its first leaf; every amendment logged'
+        : recordProblems.join('; '),
+  });
+
+  // 4. Tree heads: recompute every root, verify every signature (§5).
+  const leafHashes = leafLines.map((line) => leafHash(utf8Bytes(line)));
+  const headProblems: string[] = [];
+  let previousSize = 0;
+  heads.forEach((head, i) => {
+    try {
+      assertValidSth(head);
+      if (head.tree_size < previousSize) throw new Error('tree size decreased');
+      previousSize = head.tree_size;
+      if (head.tree_size > leafHashes.length) {
+        throw new Error(`covers ${head.tree_size} leaves but only ${leafHashes.length} are known`);
+      }
+      const recomputed = bytesToHex(rootFromLeafHashes(leafHashes.slice(0, head.tree_size)));
+      if (recomputed !== head.root_hash) {
+        throw new Error(`root hash does not match the recomputed tree at size ${head.tree_size}`);
+      }
+      if (!sthPubkeys.some((pubkey) => verifySthSignature(head, pubkey))) {
+        throw new Error('signature does not verify against any accepted key');
+      }
+    } catch (error) {
+      headProblems.push(`tree head ${i}: ${(error as Error).message}`);
+    }
+  });
+  if (leafLines.length > 0 && (heads.length === 0 || heads[heads.length - 1]!.tree_size !== leafLines.length)) {
+    headProblems.push('the latest tree head does not cover every entry (SPEC.md §5)');
+  }
+  checks.push({
+    name: 'tree-heads',
+    ok: headProblems.length === 0,
+    detail:
+      headProblems.length === 0
+        ? `${heads.length} tree heads recomputed and signature-verified`
+        : headProblems.join('; '),
+  });
+
+  // 5. Consistency between every consecutive pair of tree heads (§6.2).
+  const consistencyProblems: string[] = [];
+  let pairs = 0;
+  for (let i = 1; i < heads.length; i++) {
+    const prev = heads[i - 1]!;
+    const next = heads[i]!;
+    if (next.tree_size > leafHashes.length || prev.tree_size > next.tree_size) continue; // reported above
+    const ok = verifyConsistency({
+      oldSize: prev.tree_size,
+      newSize: next.tree_size,
+      oldRoot: hexToBytes(prev.root_hash),
+      newRoot: hexToBytes(next.root_hash),
+      path: consistencyPath(prev.tree_size, leafHashes.slice(0, next.tree_size)),
+    });
+    pairs++;
+    if (!ok) {
+      consistencyProblems.push(
+        `tree heads ${i - 1} -> ${i} (sizes ${prev.tree_size} -> ${next.tree_size}) are not consistent: history was rewritten`,
+      );
+    }
+  }
+  checks.push({
+    name: 'consistency',
+    ok: consistencyProblems.length === 0,
+    detail:
+      consistencyProblems.length === 0
+        ? `${pairs} consecutive pair(s) prove append-only history`
+        : consistencyProblems.join('; '),
+  });
+
+  return {
+    ok: checks.every((c) => c.ok),
+    source: data.source,
+    agents,
+    treeSize: leafLines.length,
+    checks,
+  };
+}
+
+function safeOathHash(doc: OathDoc): string | null {
+  try {
+    return oathHash(doc);
+  } catch {
+    return null;
+  }
+}
+
+/** Verify a local ledger directory (SPEC.md Appendix A). */
+export function verifyLocalLedger(dir: string): VerificationReport {
+  let data: LedgerData;
+  try {
+    const oathVersions = readOathVersions(dir);
+    const agent = oathVersions[0]!.agent;
+    data = {
+      source: dir,
+      leafLines: readLeafLines(dir),
+      heads: JSON.parse(readFileSync(join(dir, LEDGER_FILES.heads), 'utf8')) as SignedTreeHead[],
+      // A local ledger's agent key doubles as its ledger key (§5).
+      sthPubkeys: oathVersions.map((doc) => doc.pubkey),
+      oathsByAgent: new Map([[agent, oathVersions]]),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      source: dir,
+      agents: [],
+      treeSize: 0,
+      checks: [{ name: 'files', ok: false, detail: `unreadable ledger: ${(error as Error).message}` }],
+    };
+  }
+  return verifyLedgerData(data);
+}
+
+/**
+ * Verify a remote public ledger over its read API (SPEC.md §11.2), starting
+ * from its discovery document. Entries beyond the latest tree head are
+ * within the merge delay and are not judged yet.
+ */
+export async function verifyRemoteLedger(
+  url: string,
+  options: { fetch?: typeof fetch } = {},
+): Promise<VerificationReport> {
+  const f = options.fetch ?? fetch;
+  const base = url.replace(/\/+$/, '');
+  const get = async (path: string): Promise<unknown> => {
+    const response = await f(`${base}${path}`);
+    if (!response.ok) throw new Error(`GET ${path} -> ${response.status}`);
+    return response.json();
+  };
+  try {
+    const discovery = (await get('/v0/ledger.json')) as { ledger: string; pubkey: string };
+    const heads = (await get('/v0/sth/history')) as SignedTreeHead[];
+    const covered = heads.length > 0 ? heads[heads.length - 1]!.tree_size : 0;
+    const leafLines: string[] = [];
+    for (let start = 0; start < covered; start += 1000) {
+      const page = (await get(`/v0/entries?start=${start}&end=${Math.min(start + 999, covered - 1)}`)) as {
+        entries: { leaf_index: number; leaf_bytes: string }[];
+      };
+      for (const row of page.entries) {
+        leafLines[row.leaf_index] = row.leaf_bytes;
+      }
+    }
+    const handles = new Set<string>();
+    for (const line of leafLines) {
+      try {
+        const agent = (JSON.parse(line) as { agent?: unknown }).agent;
+        if (typeof agent === 'string') handles.add(agent);
+      } catch {
+        /* reported by verifyLedgerData */
+      }
+    }
+    const oathsByAgent = new Map<string, OathDoc[]>();
+    for (const handle of handles) {
+      const record = (await get(`/v0/agents/${handle}`)) as { oath_versions: OathDoc[] };
+      oathsByAgent.set(handle, record.oath_versions);
+    }
+    return verifyLedgerData({
+      source: `${discovery.ledger} (${base})`,
+      leafLines,
+      heads,
+      sthPubkeys: [discovery.pubkey],
+      oathsByAgent,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      source: base,
+      agents: [],
+      treeSize: 0,
+      checks: [{ name: 'files', ok: false, detail: `unreachable ledger: ${(error as Error).message}` }],
+    };
+  }
+}