@thehonestmachine/oath-core 0.1.0

package/src/jcs.ts

@@ -0,0 +1,60 @@
+import { ProtocolError } from './errors.js';
+import { utf8Bytes } from './bytes.js';
+
+/**
+ * JSON Canonicalization Scheme (RFC 8785).
+ *
+ * Deliberately stricter than JSON.stringify: undefined values, non-plain
+ * objects (Date, Map, class instances), functions, symbols, bigints,
+ * non-finite numbers, and array holes are protocol errors rather than
+ * silent coercions. Trust structures do not get repaired on the way to
+ * being hashed.
+ *
+ * Number and string serialization delegate to JSON.stringify, which
+ * implements exactly the ECMAScript serializations RFC 8785 requires
+ * (including -0 → "0" and lowercase \u escapes for control characters).
+ * Property keys sort by UTF-16 code units, which is the default behavior
+ * of Array.prototype.sort for strings.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      if (!Number.isFinite(value)) throw new ProtocolError('cannot canonicalize non-finite number');
+      return JSON.stringify(value);
+    case 'string':
+      return JSON.stringify(value);
+    case 'object':
+      break;
+    default:
+      throw new ProtocolError(`cannot canonicalize value of type ${typeof value}`);
+  }
+  if (Array.isArray(value)) {
+    const parts: string[] = [];
+    for (let i = 0; i < value.length; i++) {
+      if (!(i in value)) throw new ProtocolError('cannot canonicalize array with holes');
+      parts.push(canonicalize(value[i]));
+    }
+    return '[' + parts.join(',') + ']';
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new ProtocolError('cannot canonicalize non-plain object');
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  const parts: string[] = [];
+  for (const key of keys) {
+    const v = record[key];
+    if (v === undefined) throw new ProtocolError(`cannot canonicalize undefined value at key "${key}"`);
+    parts.push(JSON.stringify(key) + ':' + canonicalize(v));
+  }
+  return '{' + parts.join(',') + '}';
+}
+
+/** UTF-8 bytes of the canonical serialization — what gets hashed and signed. */
+export function canonicalBytes(value: unknown): Uint8Array {
+  return utf8Bytes(canonicalize(value));
+}

package/src/merkle.ts

@@ -0,0 +1,184 @@
+import { ProtocolError } from './errors.js';
+import { bytesEqual, concatBytes } from './bytes.js';
+import { sha256 } from './hash.js';
+
+/**
+ * RFC 6962-style Merkle tree (spec §4): SHA-256 with 0x00/0x01 domain
+ * separation, split at the largest power of two strictly less than n.
+ * Sizes and indices use plain number arithmetic (no 32-bit bitwise ops),
+ * so trees are correct up to 2^53 leaves.
+ */
+
+const LEAF_PREFIX = new Uint8Array([0x00]);
+const NODE_PREFIX = new Uint8Array([0x01]);
+
+/** MTH of the empty tree: SHA-256 of the empty string. */
+export const EMPTY_ROOT: Uint8Array = sha256(new Uint8Array(0));
+
+export function leafHash(leafBytes: Uint8Array): Uint8Array {
+  return sha256(concatBytes(LEAF_PREFIX, leafBytes));
+}
+
+export function nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array {
+  return sha256(concatBytes(NODE_PREFIX, left, right));
+}
+
+function largestPowerOfTwoLessThan(n: number): number {
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+function assertHashList(hashes: readonly Uint8Array[]): void {
+  for (const h of hashes) {
+    if (h.length !== 32) throw new ProtocolError('leaf hashes must be 32 bytes');
+  }
+}
+
+function subRoot(hashes: readonly Uint8Array[], lo: number, hi: number): Uint8Array {
+  const n = hi - lo;
+  if (n === 1) return hashes[lo]!;
+  const k = largestPowerOfTwoLessThan(n);
+  return nodeHash(subRoot(hashes, lo, lo + k), subRoot(hashes, lo + k, hi));
+}
+
+/** MTH over precomputed leaf hashes (leafHash of each entry's leaf bytes). */
+export function rootFromLeafHashes(hashes: readonly Uint8Array[]): Uint8Array {
+  assertHashList(hashes);
+  if (hashes.length === 0) return EMPTY_ROOT;
+  return subRoot(hashes, 0, hashes.length);
+}
+
+/** Audit path for the leaf at `leafIndex` — PATH(m, D[n]) of RFC 6962 §2.1.1. */
+export function inclusionPath(leafIndex: number, hashes: readonly Uint8Array[]): Uint8Array[] {
+  assertHashList(hashes);
+  if (!Number.isSafeInteger(leafIndex) || leafIndex < 0 || leafIndex >= hashes.length) {
+    throw new ProtocolError('leaf index out of range');
+  }
+  const path = (m: number, lo: number, hi: number): Uint8Array[] => {
+    if (hi - lo === 1) return [];
+    const k = largestPowerOfTwoLessThan(hi - lo);
+    if (m < k) return [...path(m, lo, lo + k), subRoot(hashes, lo + k, hi)];
+    return [...path(m - k, lo + k, hi), subRoot(hashes, lo, lo + k)];
+  };
+  return path(leafIndex, 0, hashes.length);
+}
+
+/** Consistency path from `oldSize` to the full list — PROOF(m, D[n]) of RFC 6962 §2.1.2. */
+export function consistencyPath(oldSize: number, hashes: readonly Uint8Array[]): Uint8Array[] {
+  assertHashList(hashes);
+  if (!Number.isSafeInteger(oldSize) || oldSize < 0 || oldSize > hashes.length) {
+    throw new ProtocolError('old size out of range');
+  }
+  if (oldSize === 0 || oldSize === hashes.length) return [];
+  const sub = (m: number, lo: number, hi: number, complete: boolean): Uint8Array[] => {
+    const n = hi - lo;
+    if (m === n) return complete ? [] : [subRoot(hashes, lo, hi)];
+    const k = largestPowerOfTwoLessThan(n);
+    if (m <= k) return [...sub(m, lo, lo + k, complete), subRoot(hashes, lo + k, hi)];
+    return [...sub(m - k, lo + k, hi, false), subRoot(hashes, lo, lo + k)];
+  };
+  return sub(oldSize, 0, hashes.length, true);
+}
+
+/**
+ * Size/index guard for the VERIFIERS, which must fail closed: a malformed
+ * size makes verification return false, never throw, so an attacker cannot
+ * crash a monitor with a bad proof (spec §6, §6.3). The path GENERATORS,
+ * which operate on trusted local data, throw on bad input instead.
+ */
+function isValidSize(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+function allHashes(path: readonly Uint8Array[]): boolean {
+  return path.every((p) => p.length === 32);
+}
+
+/**
+ * Verify an inclusion proof (spec §6.1). Returns false — never throws — on
+ * any mismatch, so attacker-supplied proofs cannot crash a monitor.
+ */
+export function verifyInclusion(options: {
+  leafHash: Uint8Array;
+  leafIndex: number;
+  treeSize: number;
+  auditPath: readonly Uint8Array[];
+  rootHash: Uint8Array;
+}): boolean {
+  const { leafHash: leaf, leafIndex, treeSize, auditPath, rootHash } = options;
+  if (!isValidSize(leafIndex) || !isValidSize(treeSize)) return false;
+  if (leafIndex >= treeSize || leaf.length !== 32 || !allHashes(auditPath)) return false;
+  let fn = leafIndex;
+  let sn = treeSize - 1;
+  let hash = leaf;
+  for (const sibling of auditPath) {
+    if (sn === 0) return false;
+    if (fn % 2 === 1 || fn === sn) {
+      hash = nodeHash(sibling, hash);
+      while (fn !== 0 && fn % 2 === 0) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+      }
+    } else {
+      hash = nodeHash(hash, sibling);
+    }
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  return sn === 0 && bytesEqual(hash, rootHash);
+}
+
+/**
+ * Verify a consistency proof (spec §6.2): the tree at `newSize` is an
+ * append-only extension of the tree at `oldSize`. Returns false — never
+ * throws — on any mismatch. A false result against two signature-valid
+ * STHs is oathbreaker proof (spec §6.3).
+ */
+export function verifyConsistency(options: {
+  oldSize: number;
+  newSize: number;
+  oldRoot: Uint8Array;
+  newRoot: Uint8Array;
+  path: readonly Uint8Array[];
+}): boolean {
+  const { oldSize, newSize, oldRoot, newRoot, path } = options;
+  if (!isValidSize(oldSize) || !isValidSize(newSize)) return false;
+  if (oldSize > newSize || oldRoot.length !== 32 || newRoot.length !== 32 || !allHashes(path)) {
+    return false;
+  }
+  if (oldSize === newSize) return path.length === 0 && bytesEqual(oldRoot, newRoot);
+  if (oldSize === 0) return path.length === 0;
+  const nodes = isPowerOfTwo(oldSize) ? [oldRoot, ...path] : [...path];
+  if (nodes.length === 0) return false;
+  let fn = oldSize - 1;
+  let sn = newSize - 1;
+  while (fn % 2 === 1) {
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  let oldHash = nodes[0]!;
+  let newHash = nodes[0]!;
+  for (let i = 1; i < nodes.length; i++) {
+    const c = nodes[i]!;
+    if (sn === 0) return false;
+    if (fn % 2 === 1 || fn === sn) {
+      oldHash = nodeHash(c, oldHash);
+      newHash = nodeHash(c, newHash);
+      while (fn !== 0 && fn % 2 === 0) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+      }
+    } else {
+      newHash = nodeHash(newHash, c);
+    }
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  return sn === 0 && bytesEqual(oldHash, oldRoot) && bytesEqual(newHash, newRoot);
+}
+
+function isPowerOfTwo(n: number): boolean {
+  while (n % 2 === 0) n /= 2;
+  return n === 1;
+}

package/src/oath.ts

@@ -0,0 +1,148 @@
+import { ProtocolError } from './errors.js';
+import { canonicalBytes } from './jcs.js';
+import { sha256Hex } from './hash.js';
+import { edSign, edVerify } from './ed25519.js';
+import {
+  assertKeys,
+  assertPlainObject,
+  isHandle,
+  isHex,
+  isNonEmptyString,
+  isPositiveInteger,
+  isTimestamp,
+} from './validate.js';
+import type { OathDoc, UnsignedOathDoc } from './types.js';
+
+/** The spec_version this implementation conforms to (SPEC.md §12). */
+export const SPEC_VERSION = '0.1';
+
+/** Default confession latency commitment in seconds (SPEC.md §2.2, §8.2). */
+export const DEFAULT_MAX_LATENCY_SECONDS = 300;
+
+const REQUIRED = ['spec_version', 'agent', 'version', 'pubkey', 'scope', 'laws', 'created_at'];
+const OPTIONAL = ['display_name', 'commitments'];
+const COMMITMENT_KEYS = ['entries_per_30d', 'max_latency_seconds'];
+
+function validateOathShape(value: unknown, requireSignature: boolean): void {
+  const doc = assertPlainObject(value, 'oath document');
+  const required = requireSignature ? [...REQUIRED, 'signature'] : REQUIRED;
+  const optional = requireSignature ? OPTIONAL : [...OPTIONAL, 'signature'];
+  assertKeys(doc, 'oath document', required, optional);
+
+  if (doc['spec_version'] !== SPEC_VERSION) {
+    throw new ProtocolError(`oath document spec_version must be "${SPEC_VERSION}"`);
+  }
+  if (!isHandle(doc['agent'])) throw new ProtocolError('oath document agent must be a valid handle');
+  if ('display_name' in doc && !isNonEmptyString(doc['display_name'])) {
+    throw new ProtocolError('oath document display_name must be a non-empty string');
+  }
+  if (!isPositiveInteger(doc['version'])) {
+    throw new ProtocolError('oath document version must be an integer >= 1');
+  }
+  if (!isHex(doc['pubkey'], 32)) {
+    throw new ProtocolError('oath document pubkey must be 32 bytes of lowercase hex');
+  }
+  if (!isNonEmptyString(doc['scope'])) {
+    throw new ProtocolError('oath document scope must be a non-empty string');
+  }
+  if ('commitments' in doc) {
+    const commitments = assertPlainObject(doc['commitments'], 'oath commitments');
+    assertKeys(commitments, 'oath commitments', [], COMMITMENT_KEYS);
+    for (const key of COMMITMENT_KEYS) {
+      if (key in commitments && !isPositiveInteger(commitments[key])) {
+        throw new ProtocolError(`oath commitments ${key} must be an integer >= 1`);
+      }
+    }
+  }
+  validateLaws(doc['laws']);
+  if (!isTimestamp(doc['created_at'])) {
+    throw new ProtocolError('oath document created_at must be an RFC 3339 UTC timestamp');
+  }
+  if (requireSignature && !isHex(doc['signature'], 64)) {
+    throw new ProtocolError('oath document signature must be 64 bytes of lowercase hex');
+  }
+}
+
+function validateLaws(value: unknown): void {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new ProtocolError('oath document laws must be a non-empty array');
+  }
+  value.forEach((law, i) => {
+    const obj = assertPlainObject(law, `law at index ${i}`);
+    assertKeys(obj, `law at index ${i}`, ['n', 'mode', 'text'], []);
+    if (obj['n'] !== i + 1) {
+      throw new ProtocolError('laws must be numbered 1..N consecutively');
+    }
+    if (obj['mode'] !== 'machine' && obj['mode'] !== 'judgment') {
+      throw new ProtocolError('law mode must be "machine" or "judgment"');
+    }
+    if (!isNonEmptyString(obj['text'])) {
+      throw new ProtocolError('law text must be a non-empty string');
+    }
+  });
+}
+
+/** Validate a complete signed oath document (SPEC.md §2.2). Structural only. */
+export function assertValidOathDoc(value: unknown): asserts value is OathDoc {
+  validateOathShape(value, true);
+}
+
+/** Validate an oath document that has not been signed yet. */
+export function assertValidUnsignedOathDoc(value: unknown): asserts value is UnsignedOathDoc {
+  validateOathShape(value, false);
+}
+
+/** Canonical bytes of the document without its signature — the signing input. */
+export function oathSigningInput(doc: UnsignedOathDoc | OathDoc): Uint8Array {
+  const { signature: _signature, ...unsigned } = doc as OathDoc;
+  assertValidUnsignedOathDoc(unsigned);
+  return canonicalBytes(unsigned);
+}
+
+/**
+ * The oath hash: SHA-256 (hex) of the canonical bytes of the complete signed
+ * document. Identifies this oath version everywhere in the protocol.
+ */
+export function oathHash(doc: OathDoc): string {
+  assertValidOathDoc(doc);
+  return sha256Hex(canonicalBytes(doc));
+}
+
+/**
+ * Sign an oath document. For version 1 the signing seed is the agent's own
+ * key; for an amendment it is the previous version's key (SPEC.md §2.2, §9).
+ */
+export function signOathDoc(unsigned: UnsignedOathDoc, signingSeedHex: string): OathDoc {
+  assertValidUnsignedOathDoc(unsigned);
+  const signature = edSign(canonicalBytes(unsigned), signingSeedHex);
+  return { ...unsigned, signature };
+}
+
+/**
+ * Verify an oath document's signature. `signerPubkeyHex` defaults to the
+ * document's own pubkey (correct for version 1); for an amendment pass the
+ * previous version's pubkey.
+ */
+export function verifyOathSignature(doc: OathDoc, signerPubkeyHex?: string): boolean {
+  assertValidOathDoc(doc);
+  return edVerify(doc.signature, oathSigningInput(doc), signerPubkeyHex ?? doc.pubkey);
+}
+
+/**
+ * Validate that `next` is a conforming amendment of `prev` (SPEC.md §9):
+ * same agent, version incremented by exactly 1, signed by the previous
+ * version's key.
+ */
+export function assertValidAmendment(prev: OathDoc, next: OathDoc): void {
+  assertValidOathDoc(prev);
+  assertValidOathDoc(next);
+  if (next.agent !== prev.agent) {
+    throw new ProtocolError('amendment must keep the same agent handle');
+  }
+  if (next.version !== prev.version + 1) {
+    throw new ProtocolError('amendment must increment version by exactly 1');
+  }
+  if (!verifyOathSignature(next, prev.pubkey)) {
+    throw new ProtocolError("amendment signature must verify against the previous version's key");
+  }
+}

package/src/sth.ts

@@ -0,0 +1,126 @@
+import { ProtocolError } from './errors.js';
+import { canonicalBytes } from './jcs.js';
+import { bytesToHex } from './bytes.js';
+import { EMPTY_ROOT } from './merkle.js';
+import { edSign, edVerify } from './ed25519.js';
+import {
+  assertKeys,
+  assertPlainObject,
+  isHex,
+  isNonEmptyString,
+  isNonNegativeInteger,
+  isPositiveInteger,
+  isTimestamp,
+} from './validate.js';
+import type { Receipt, SignedTreeHead, UnsignedReceipt, UnsignedTreeHead } from './types.js';
+
+const EMPTY_ROOT_HEX = bytesToHex(EMPTY_ROOT);
+
+function validateSthShape(value: unknown, requireSignature: boolean): void {
+  const sth = assertPlainObject(value, 'signed tree head');
+  const required = ['ledger', 'tree_size', 'root_hash', 'timestamp'];
+  assertKeys(
+    sth,
+    'signed tree head',
+    requireSignature ? [...required, 'signature'] : required,
+    requireSignature ? [] : ['signature'],
+  );
+  if (!isNonEmptyString(sth['ledger'])) {
+    throw new ProtocolError('signed tree head ledger must be a non-empty string');
+  }
+  if (!isNonNegativeInteger(sth['tree_size'])) {
+    throw new ProtocolError('signed tree head tree_size must be a non-negative integer');
+  }
+  if (!isHex(sth['root_hash'], 32)) {
+    throw new ProtocolError('signed tree head root_hash must be 32 bytes of lowercase hex');
+  }
+  if (sth['tree_size'] === 0 && sth['root_hash'] !== EMPTY_ROOT_HEX) {
+    throw new ProtocolError('an empty tree has exactly one possible root hash (SPEC.md §4)');
+  }
+  if (!isTimestamp(sth['timestamp'])) {
+    throw new ProtocolError('signed tree head timestamp must be an RFC 3339 UTC timestamp');
+  }
+  if (requireSignature && !isHex(sth['signature'], 64)) {
+    throw new ProtocolError('signed tree head signature must be 64 bytes of lowercase hex');
+  }
+}
+
+/** Validate a signed tree head (SPEC.md §5). Structural only. */
+export function assertValidSth(value: unknown): asserts value is SignedTreeHead {
+  validateSthShape(value, true);
+}
+
+export function assertValidUnsignedSth(value: unknown): asserts value is UnsignedTreeHead {
+  validateSthShape(value, false);
+}
+
+/** Canonical bytes of the STH without its signature — the signing input. */
+export function sthSigningInput(sth: UnsignedTreeHead | SignedTreeHead): Uint8Array {
+  const { signature: _signature, ...unsigned } = sth as SignedTreeHead;
+  assertValidUnsignedSth(unsigned);
+  return canonicalBytes(unsigned);
+}
+
+export function signSth(unsigned: UnsignedTreeHead, ledgerSeedHex: string): SignedTreeHead {
+  assertValidUnsignedSth(unsigned);
+  const signature = edSign(canonicalBytes(unsigned), ledgerSeedHex);
+  return { ...unsigned, signature };
+}
+
+export function verifySthSignature(sth: SignedTreeHead, ledgerPubkeyHex: string): boolean {
+  assertValidSth(sth);
+  return edVerify(sth.signature, sthSigningInput(sth), ledgerPubkeyHex);
+}
+
+function validateReceiptShape(value: unknown, requireSignature: boolean): void {
+  const receipt = assertPlainObject(value, 'receipt');
+  const required = ['ledger', 'leaf_hash', 'received_at', 'mmd_seconds'];
+  assertKeys(
+    receipt,
+    'receipt',
+    requireSignature ? [...required, 'signature'] : required,
+    requireSignature ? [] : ['signature'],
+  );
+  if (!isNonEmptyString(receipt['ledger'])) {
+    throw new ProtocolError('receipt ledger must be a non-empty string');
+  }
+  if (!isHex(receipt['leaf_hash'], 32)) {
+    throw new ProtocolError('receipt leaf_hash must be 32 bytes of lowercase hex');
+  }
+  if (!isTimestamp(receipt['received_at'])) {
+    throw new ProtocolError('receipt received_at must be an RFC 3339 UTC timestamp');
+  }
+  if (!isPositiveInteger(receipt['mmd_seconds'])) {
+    throw new ProtocolError('receipt mmd_seconds must be an integer >= 1');
+  }
+  if (requireSignature && !isHex(receipt['signature'], 64)) {
+    throw new ProtocolError('receipt signature must be 64 bytes of lowercase hex');
+  }
+}
+
+/** Validate a receipt (SPEC.md §11.3). Structural only. */
+export function assertValidReceipt(value: unknown): asserts value is Receipt {
+  validateReceiptShape(value, true);
+}
+
+export function assertValidUnsignedReceipt(value: unknown): asserts value is UnsignedReceipt {
+  validateReceiptShape(value, false);
+}
+
+/** Canonical bytes of the receipt without its signature — the signing input. */
+export function receiptSigningInput(receipt: UnsignedReceipt | Receipt): Uint8Array {
+  const { signature: _signature, ...unsigned } = receipt as Receipt;
+  assertValidUnsignedReceipt(unsigned);
+  return canonicalBytes(unsigned);
+}
+
+export function signReceipt(unsigned: UnsignedReceipt, ledgerSeedHex: string): Receipt {
+  assertValidUnsignedReceipt(unsigned);
+  const signature = edSign(canonicalBytes(unsigned), ledgerSeedHex);
+  return { ...unsigned, signature };
+}
+
+export function verifyReceiptSignature(receipt: Receipt, ledgerPubkeyHex: string): boolean {
+  assertValidReceipt(receipt);
+  return edVerify(receipt.signature, receiptSigningInput(receipt), ledgerPubkeyHex);
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+/** Structures defined by SPEC.md v0.1. Field names match the canonical JSON. */
+
+export type Verdict = 'compliant' | 'violation' | 'uncertain';
+
+export type LawMode = 'machine' | 'judgment';
+
+export interface Law {
+  n: number;
+  mode: LawMode;
+  text: string;
+}
+
+export interface OathCommitments {
+  entries_per_30d?: number;
+  max_latency_seconds?: number;
+}
+
+export interface UnsignedOathDoc {
+  spec_version: string;
+  agent: string;
+  display_name?: string;
+  version: number;
+  pubkey: string;
+  scope: string;
+  commitments?: OathCommitments;
+  laws: Law[];
+  created_at: string;
+}
+
+export interface OathDoc extends UnsignedOathDoc {
+  signature: string;
+}
+
+export interface Action {
+  type: string;
+  summary: string;
+  content_hash: string | null;
+  occurred_at: string;
+}
+
+export interface MachineAdjudication {
+  mode: 'machine';
+  check: string;
+  check_version?: string;
+}
+
+export interface ModelAdjudication {
+  mode: 'model';
+  model: string;
+  prompt_hash: string;
+  inputs_hash: string;
+}
+
+export type Adjudication = MachineAdjudication | ModelAdjudication;
+
+export interface Confession {
+  note: string;
+}
+
+export interface UnsignedEntry {
+  spec_version: string;
+  agent: string;
+  oath_version: number;
+  action: Action;
+  verdict: Verdict;
+  law_cited: number | null;
+  adjudication: Adjudication;
+  confession?: Confession;
+  timestamp: string;
+}
+
+export interface Entry extends UnsignedEntry {
+  signature: string;
+}
+
+export interface UnsignedTreeHead {
+  ledger: string;
+  tree_size: number;
+  root_hash: string;
+  timestamp: string;
+}
+
+export interface SignedTreeHead extends UnsignedTreeHead {
+  signature: string;
+}
+
+export interface UnsignedReceipt {
+  ledger: string;
+  leaf_hash: string;
+  received_at: string;
+  mmd_seconds: number;
+}
+
+export interface Receipt extends UnsignedReceipt {
+  signature: string;
+}
+
+export interface InclusionProof {
+  leaf_index: number;
+  tree_size: number;
+  audit_path: string[];
+}
+
+export interface ConsistencyProof {
+  old_size: number;
+  new_size: number;
+  path: string[];
+}