@provenonce/beats-client 0.2.0 → 0.3.0

package/README.md

@@ -1,50 +1,50 @@
-# @provenonce/beats-client
-
-Minimal client for the public Beats service.
-
-## Install
-
-From npm (after publish):
-
-```bash
-npm i @provenonce/beats-client
-```
-
-Local repo path (pre-publish):
-
-```bash
-npm i ./sdk/beats-client
-```
-
-## Usage
-
-```js
-import { createBeatsClient } from '@provenonce/beats-client';
-
-const beats = createBeatsClient();
-
-const anchor = await beats.getAnchor();
-const receipt = await beats.timestampHash('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
-const receiptValid = await beats.verifyReceipt(receipt);
-const anchorValid = await beats.verifyAnchor(anchor);
-const onChain = await beats.verifyOnChain(receipt.on_chain.tx_signature, { cluster: 'devnet' });
-
-// Auto-verify anchor receipt:
-const verifiedAnchor = await beats.getAnchor({ verify: true });
-```
-
-## Endpoints wrapped
-
-- `GET /api/health`
-- `GET /api/v1/beat/anchor`
-- `GET /api/v1/beat/key`
-- `POST /api/v1/beat/verify`
-- `POST /api/v1/beat/timestamp`
-
-## Helpers
-
-- `verifyReceipt(response)` - offline Ed25519 verification of timestamp/anchor receipts.
-- `verifyAnchor(anchorResponse)` - explicit offline verification helper for anchor responses.
-- `verifyOnChain(txSignature, { cluster | rpcUrl })` - direct Solana RPC status check.
-- `getAnchor({ verify: true })` - fetch anchor and verify attached receipt in one call.
-
+# @provenonce/beats-client
+
+Minimal client for the public Beats service.
+
+## Install
+
+From npm (after publish):
+
+```bash
+npm i @provenonce/beats-client
+```
+
+Local repo path (pre-publish):
+
+```bash
+npm i ./sdk/beats-client
+```
+
+## Usage
+
+```js
+import { createBeatsClient } from '@provenonce/beats-client';
+
+const beats = createBeatsClient();
+
+const anchor = await beats.getAnchor();
+const receipt = await beats.timestampHash('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+const receiptValid = await beats.verifyReceipt(receipt);
+const anchorValid = await beats.verifyAnchor(anchor);
+const onChain = await beats.verifyOnChain(receipt.on_chain.tx_signature, { cluster: 'devnet' });
+
+// Auto-verify anchor receipt:
+const verifiedAnchor = await beats.getAnchor({ verify: true });
+```
+
+## Endpoints wrapped
+
+- `GET /api/health`
+- `GET /api/v1/beat/anchor`
+- `GET /api/v1/beat/key`
+- `POST /api/v1/beat/verify`
+- `POST /api/v1/beat/timestamp`
+
+## Helpers
+
+- `verifyReceipt(response)` - offline Ed25519 verification of timestamp/anchor receipts.
+- `verifyAnchor(anchorResponse)` - explicit offline verification helper for anchor responses.
+- `verifyOnChain(txSignature, { cluster | rpcUrl })` - direct Solana RPC status check.
+- `getAnchor({ verify: true })` - fetch anchor and verify attached receipt in one call.
+

package/index.d.ts

@@ -1,96 +1,148 @@
-export interface BeatsClientOptions {
-  baseUrl?: string;
-  fetchImpl?: typeof fetch;
-}
-
-export interface VerifyOnChainOptions {
-  rpcUrl?: string;
-  cluster?: 'devnet' | 'testnet' | 'mainnet-beta';
-}
-
-export interface VerifyOnChainResult {
-  found: boolean;
-  confirmationStatus: string | null;
-  finalized: boolean;
-  slot: number | null;
-}
-
-export interface AnchorOptions {
-  verify?: boolean;
-}
-
-export interface HealthResponse {
-  status?: string;
-  [key: string]: unknown;
-}
-
-export interface BeatAnchor {
-  beat_index: number;
-  hash: string;
-  prev_hash: string;
-  utc: number;
-  difficulty: number;
-  epoch: number;
-}
-
-export interface ReceiptEnvelope {
-  signature: string;
-  public_key: string;
-}
-
-export interface AnchorResponse {
-  anchor: BeatAnchor | null;
-  on_chain: {
-    tx_signature: string | null;
-    explorer_url: string | null;
-    anchored?: boolean;
-  };
-  receipt?: ReceiptEnvelope;
-  anchor_interval_sec?: number;
-  next_anchor_at?: string;
-  _verified_receipt?: boolean;
-  _note?: string;
-  _info?: string;
-}
-
-export interface TimestampPayload {
-  hash: string;
-  anchor_index: number;
-  anchor_hash: string;
-  utc: number;
-  tx_signature: string;
-}
-
-export interface TimestampResponse {
-  timestamp: TimestampPayload;
-  on_chain: {
-    tx_signature: string;
-    explorer_url: string;
-  };
-  receipt: ReceiptEnvelope;
-  tier?: 'free' | 'pro';
-  _note?: string;
-}
-
-export interface VerifyApiResponse {
-  ok?: boolean;
-  mode?: 'beat' | 'chain' | 'proof';
-  valid?: boolean;
-  error?: string;
-  reason?: string;
-  [key: string]: unknown;
-}
-
-export interface BeatsClient {
-  getHealth(): Promise<HealthResponse>;
-  getAnchor(opts?: AnchorOptions): Promise<AnchorResponse>;
-  getKey(): Promise<{ public_key_base58: string; public_key_hex: string; algorithm: string; purpose?: string; _note?: string }>;
-  verify(payload: unknown): Promise<VerifyApiResponse>;
-  timestampHash(hash: string): Promise<TimestampResponse>;
-  verifyReceipt(response: AnchorResponse | TimestampResponse | { payload: Record<string, unknown>; signature: string; public_key: string }): Promise<boolean>;
-  verifyAnchor(anchorResponse: AnchorResponse): Promise<boolean>;
-  verifyOnChain(txSignature: string, opts?: VerifyOnChainOptions): Promise<VerifyOnChainResult>;
-}
-
-export declare function createBeatsClient(options?: BeatsClientOptions): BeatsClient;
-
+export interface ContinuityState {
+  beat_index: number;
+  hash: string;
+  agent_id: string | null;
+}
+
+export interface BeatsClientOptions {
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  /** Pin a known public key for receipt verification (B-1). Hex or base58. */
+  pinnedPublicKey?: string | null;
+  /** Request timeout in milliseconds (B-5). Default: 30000. */
+  timeoutMs?: number;
+  /** Callback when continuity state changes. Persist this for restart recovery. */
+  onStateChange?: (state: ContinuityState) => void;
+  /** Load persisted continuity state on startup. */
+  loadState?: () => ContinuityState | null;
+  /** Agent ID for scoping persisted state. */
+  agentId?: string | null;
+}
+
+export interface VerifyOnChainOptions {
+  rpcUrl?: string;
+  cluster?: 'devnet' | 'testnet' | 'mainnet-beta';
+  /** If provided, fetches the full transaction and verifies SPL Memo content matches (B-4). */
+  expectedPayload?: Record<string, unknown>;
+}
+
+export interface VerifyOnChainResult {
+  found: boolean;
+  confirmationStatus: string | null;
+  finalized: boolean;
+  slot: number | null;
+  /** True if memo content matches expectedPayload (B-4). Only present when expectedPayload is provided. */
+  memoVerified?: boolean;
+  /** Parsed memo data from the transaction (B-4). */
+  memoData?: Record<string, unknown>;
+  /** Reason if memoVerified is false. */
+  reason?: string;
+}
+
+export interface VerifyReceiptOptions {
+  /** Override key for this specific verification. Hex or base58. */
+  publicKey?: string;
+}
+
+export interface AnchorOptions {
+  /** Verify receipt signature against pinned/cached key (B-1). */
+  verify?: boolean;
+  /** Recompute anchor hash locally via SHA-256 chain (B-3, Node.js only). */
+  recompute?: boolean;
+}
+
+export interface HealthResponse {
+  status?: string;
+  [key: string]: unknown;
+}
+
+export interface BeatAnchor {
+  beat_index: number;
+  hash: string;
+  prev_hash: string;
+  utc: number;
+  difficulty: number;
+  epoch: number;
+  tx_signature: string;
+}
+
+export interface ReceiptEnvelope {
+  signature: string;
+  public_key: string;
+}
+
+export interface AnchorResponse {
+  anchor: BeatAnchor | null;
+  on_chain: {
+    tx_signature: string | null;
+    explorer_url: string | null;
+    anchored?: boolean;
+  };
+  receipt?: ReceiptEnvelope;
+  anchor_interval_sec?: number;
+  next_anchor_at?: string;
+  _verified_receipt?: boolean;
+  _verified_hash?: boolean;
+  _note?: string;
+  _info?: string;
+}
+
+export interface TimestampPayload {
+  hash: string;
+  anchor_index: number;
+  anchor_hash: string;
+  utc: number;
+  tx_signature: string;
+}
+
+export interface TimestampResponse {
+  timestamp: TimestampPayload;
+  on_chain: {
+    tx_signature: string;
+    explorer_url: string;
+  };
+  receipt: ReceiptEnvelope;
+  tier?: 'free' | 'pro';
+  _note?: string;
+}
+
+export interface VerifyApiResponse {
+  ok?: boolean;
+  mode?: 'beat' | 'chain' | 'proof';
+  valid?: boolean;
+  error?: string;
+  reason?: string;
+  [key: string]: unknown;
+}
+
+export interface BeatsClient {
+  getHealth(): Promise<HealthResponse>;
+  getAnchor(opts?: AnchorOptions): Promise<AnchorResponse>;
+  getKey(): Promise<{ public_key_base58: string; public_key_hex: string; algorithm: string; purpose?: string; _note?: string }>;
+  verify(payload: unknown): Promise<VerifyApiResponse>;
+  timestampHash(hash: string): Promise<TimestampResponse>;
+
+  /** Verify receipt signature against pinned/cached/fetched key (B-1). Never uses response-embedded key. */
+  verifyReceipt(response: AnchorResponse | TimestampResponse | { payload: Record<string, unknown>; signature: string; public_key: string }, opts?: VerifyReceiptOptions): Promise<boolean>;
+  verifyAnchor(anchorResponse: AnchorResponse): Promise<boolean>;
+
+  /** Recompute anchor hash from fields via SHA-256 chain (B-3, Node.js only). */
+  verifyAnchorHash(anchor: BeatAnchor): Promise<boolean>;
+
+  /** Verify on-chain tx status and optionally SPL Memo content (B-4). */
+  verifyOnChain(txSignature: string, opts?: VerifyOnChainOptions): Promise<VerifyOnChainResult>;
+
+  /** Set last known anchor for continuity tracking (B-2). Throws if chain is broken. */
+  setLastKnownAnchor(anchor: BeatAnchor): void;
+  /** Get last known anchor (B-2). Returns null if no anchor has been seen. */
+  getLastKnownAnchor(): BeatAnchor | null;
+  /** Re-establish chain continuity after a break. Requires explicit operator action. */
+  resync(anchor: BeatAnchor): void;
+  /** Returns true if chain continuity is broken and resync() is required. */
+  isBroken(): boolean;
+
+  /** Internal: resolve public key from cache or auto-fetch. */
+  _resolveKey(): Promise<string | null>;
+}
+
+export declare function createBeatsClient(options?: BeatsClientOptions): BeatsClient;

package/index.mjs

@@ -1,178 +1,476 @@
-const DEFAULT_BASE_URL = 'https://beats.provenonce.dev';
-const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
-const BASE58_MAP = Object.fromEntries([...BASE58_ALPHABET].map((ch, i) => [ch, i]));
-const CLUSTER_RPC = {
-  devnet: 'https://api.devnet.solana.com',
-  testnet: 'https://api.testnet.solana.com',
-  'mainnet-beta': 'https://api.mainnet-beta.solana.com',
-};
-
-function toCanonicalJson(value) {
-  const keys = Object.keys(value).sort();
-  const out = {};
-  for (const key of keys) out[key] = value[key];
-  return JSON.stringify(out);
-}
-
-function decodeBase58(str) {
-  if (!str || typeof str !== 'string') throw new Error('base58 value required');
-  let bytes = [0];
-  for (let i = 0; i < str.length; i++) {
-    const val = BASE58_MAP[str[i]];
-    if (val === undefined) throw new Error('invalid base58 character');
-    let carry = val;
-    for (let j = 0; j < bytes.length; j++) {
-      const x = bytes[j] * 58 + carry;
-      bytes[j] = x & 0xff;
-      carry = x >> 8;
-    }
-    while (carry > 0) {
-      bytes.push(carry & 0xff);
-      carry >>= 8;
-    }
-  }
-  for (let i = 0; i < str.length && str[i] === '1'; i++) bytes.push(0);
-  return new Uint8Array(bytes.reverse());
-}
-
-function decodePublicKeyBytes(publicKey) {
-  if (typeof publicKey !== 'string' || publicKey.length === 0) {
-    throw new Error('receipt public key is required');
-  }
-  if (/^[0-9a-f]{64}$/i.test(publicKey)) {
-    return Uint8Array.from(Buffer.from(publicKey, 'hex'));
-  }
-  return decodeBase58(publicKey);
-}
-
-async function verifyEd25519(payload, signatureBase64, publicKey) {
-  const message = new TextEncoder().encode(toCanonicalJson(payload));
-  const signature = Uint8Array.from(Buffer.from(signatureBase64, 'base64'));
-  const keyBytes = decodePublicKeyBytes(publicKey);
-
-  const subtle = globalThis.crypto?.subtle;
-  if (subtle) {
-    const key = await subtle.importKey('raw', keyBytes, { name: 'Ed25519' }, false, ['verify']);
-    return subtle.verify({ name: 'Ed25519' }, key, signature, message);
-  }
-
-  // Node fallback for environments without WebCrypto subtle.
-  const { createPublicKey, verify } = await import('node:crypto');
-  const spkiPrefix = Buffer.from('302a300506032b6570032100', 'hex');
-  const pubDer = Buffer.concat([spkiPrefix, Buffer.from(keyBytes)]);
-  const key = createPublicKey({ key: pubDer, format: 'der', type: 'spki' });
-  return verify(null, Buffer.from(message), key, Buffer.from(signature));
-}
-
-async function verifyOnChainTx({
-  txSignature,
-  rpcUrl,
-  cluster = 'devnet',
-  fetchImpl,
-}) {
-  if (typeof txSignature !== 'string' || txSignature.length === 0) {
-    throw new Error('txSignature is required');
-  }
-  const endpoint = rpcUrl || CLUSTER_RPC[cluster] || CLUSTER_RPC.devnet;
-  const res = await fetchImpl(endpoint, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({
-      jsonrpc: '2.0',
-      id: 1,
-      method: 'getSignatureStatuses',
-      params: [[txSignature], { searchTransactionHistory: true }],
-    }),
-  });
-  const body = await res.json();
-  if (!res.ok || body?.error) {
-    throw new Error(`RPC verification failed for ${txSignature}`);
-  }
-  const status = body?.result?.value?.[0] || null;
-  return {
-    found: !!status,
-    confirmationStatus: status?.confirmationStatus || null,
-    finalized: status?.confirmationStatus === 'finalized',
-    slot: status?.slot ?? null,
-  };
-}
-
-export function createBeatsClient({ baseUrl = DEFAULT_BASE_URL, fetchImpl = globalThis.fetch } = {}) {
-  if (typeof fetchImpl !== 'function') {
-    throw new Error('fetch implementation is required');
-  }
-
-  const request = async (path, init = {}) => {
-    const res = await fetchImpl(`${baseUrl}${path}`, init);
-    const text = await res.text();
-    let data = null;
-    try {
-      data = text ? JSON.parse(text) : null;
-    } catch {
-      data = { raw: text };
-    }
-    if (!res.ok) {
-      const msg = data?.error || `HTTP ${res.status}`;
-      const err = new Error(msg);
-      err.status = res.status;
-      err.data = data;
-      throw err;
-    }
-    return data;
-  };
-
-  return {
-    getHealth() {
-      return request('/api/health');
-    },
-    async getAnchor(opts = {}) {
-      const anchor = await request('/api/v1/beat/anchor');
-      if (opts.verify === true) {
-        const ok = await this.verifyAnchor(anchor);
-        if (!ok) throw new Error('Anchor receipt verification failed');
-        return { ...anchor, _verified_receipt: true };
-      }
-      return anchor;
-    },
-    getKey() {
-      return request('/api/v1/beat/key');
-    },
-    verify(payload) {
-      return request('/api/v1/beat/verify', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(payload),
-      });
-    },
-    timestampHash(hash) {
-      return request('/api/v1/beat/timestamp', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ hash }),
-      });
-    },
-    async verifyReceipt(response) {
-      const payload = response?.timestamp || response?.anchor || response?.payload;
-      const signature = response?.receipt?.signature || response?.signature;
-      const publicKey = response?.receipt?.public_key || response?.public_key;
-      if (!payload || !signature || !publicKey) return false;
-      try {
-        return await verifyEd25519(payload, signature, publicKey);
-      } catch {
-        return false;
-      }
-    },
-    async verifyAnchor(anchorResponse) {
-      if (!anchorResponse?.anchor || !anchorResponse?.receipt) return false;
-      return this.verifyReceipt(anchorResponse);
-    },
-    async verifyOnChain(txSignature, opts = {}) {
-      return verifyOnChainTx({
-        txSignature,
-        rpcUrl: opts.rpcUrl,
-        cluster: opts.cluster || 'devnet',
-        fetchImpl,
-      });
-    },
-  };
-}
+const DEFAULT_BASE_URL = 'https://beats.provenonce.dev';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const BASE58_MAP = Object.fromEntries([...BASE58_ALPHABET].map((ch, i) => [ch, i]));
+const CLUSTER_RPC = {
+  devnet: 'https://api.devnet.solana.com',
+  testnet: 'https://api.testnet.solana.com',
+  'mainnet-beta': 'https://api.mainnet-beta.solana.com',
+};
+const HEX64 = /^[0-9a-f]{64}$/i;
+const MEMO_PROGRAM_ID = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
+
+// ============ UTILITIES ============
+
+function toCanonicalJson(value) {
+  const keys = Object.keys(value).sort();
+  const out = {};
+  for (const key of keys) out[key] = value[key];
+  return JSON.stringify(out);
+}
+
+function decodeBase58(str) {
+  if (!str || typeof str !== 'string') throw new Error('base58 value required');
+  let bytes = [0];
+  for (let i = 0; i < str.length; i++) {
+    const val = BASE58_MAP[str[i]];
+    if (val === undefined) throw new Error('invalid base58 character');
+    let carry = val;
+    for (let j = 0; j < bytes.length; j++) {
+      const x = bytes[j] * 58 + carry;
+      bytes[j] = x & 0xff;
+      carry = x >> 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  for (let i = 0; i < str.length && str[i] === '1'; i++) bytes.push(0);
+  return new Uint8Array(bytes.reverse());
+}
+
+function decodePublicKeyBytes(publicKey) {
+  if (typeof publicKey !== 'string' || publicKey.length === 0) {
+    throw new Error('receipt public key is required');
+  }
+  if (HEX64.test(publicKey)) {
+    return Uint8Array.from(Buffer.from(publicKey, 'hex'));
+  }
+  return decodeBase58(publicKey);
+}
+
+// ============ CRYPTOGRAPHIC VERIFICATION ============
+
+async function verifyEd25519(payload, signatureBase64, publicKey) {
+  const message = new TextEncoder().encode(toCanonicalJson(payload));
+  const signature = Uint8Array.from(Buffer.from(signatureBase64, 'base64'));
+  const keyBytes = decodePublicKeyBytes(publicKey);
+
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    try {
+      const key = await subtle.importKey('raw', keyBytes, { name: 'Ed25519' }, false, ['verify']);
+      return subtle.verify({ name: 'Ed25519' }, key, signature, message);
+    } catch {
+      // Ed25519 not supported in this subtle implementation, fall through to Node
+    }
+  }
+
+  // Node.js fallback
+  const { createPublicKey, verify } = await import('node:crypto');
+  const spkiPrefix = Buffer.from('302a300506032b6570032100', 'hex');
+  const pubDer = Buffer.concat([spkiPrefix, Buffer.from(keyBytes)]);
+  const key = createPublicKey({ key: pubDer, format: 'der', type: 'spki' });
+  return verify(null, Buffer.from(message), key, Buffer.from(signature));
+}
+
+/**
+ * Recompute an anchor's hash from its fields (B-3).
+ * Requires Node.js crypto — not available in browsers.
+ * Returns true if the recomputed hash matches anchor.hash.
+ */
+async function recomputeAnchorHash(anchor) {
+  if (!anchor || !HEX64.test(anchor.hash) || !HEX64.test(anchor.prev_hash)) return false;
+  if (!Number.isInteger(anchor.beat_index) || anchor.beat_index < 0) return false;
+  if (!Number.isInteger(anchor.difficulty) || anchor.difficulty <= 0) return false;
+  if (!Number.isInteger(anchor.utc) || anchor.utc < 0) return false;
+  if (!Number.isInteger(anchor.epoch) || anchor.epoch < 0) return false;
+
+  const { createHash } = await import('node:crypto');
+  const nonce = `anchor:${anchor.utc}:${anchor.epoch}`;
+  const seed = `${anchor.prev_hash}:${anchor.beat_index}:${nonce}`;
+  let current = createHash('sha256').update(seed, 'utf8').digest('hex');
+  for (let i = 0; i < anchor.difficulty; i++) {
+    current = createHash('sha256').update(current, 'utf8').digest('hex');
+  }
+  return current === anchor.hash;
+}
+
+// ============ ON-CHAIN VERIFICATION ============
+
+async function verifyOnChainTx({
+  txSignature,
+  rpcUrl,
+  cluster = 'devnet',
+  fetchImpl,
+}) {
+  if (typeof txSignature !== 'string' || txSignature.length === 0) {
+    throw new Error('txSignature is required');
+  }
+  const endpoint = rpcUrl || CLUSTER_RPC[cluster] || CLUSTER_RPC.devnet;
+  const res = await fetchImpl(endpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'getSignatureStatuses',
+      params: [[txSignature], { searchTransactionHistory: true }],
+    }),
+  });
+  const body = await res.json();
+  if (!res.ok || body?.error) {
+    throw new Error(`RPC verification failed for ${txSignature}`);
+  }
+  const status = body?.result?.value?.[0] || null;
+  return {
+    found: !!status,
+    confirmationStatus: status?.confirmationStatus || null,
+    finalized: status?.confirmationStatus === 'finalized',
+    slot: status?.slot ?? null,
+  };
+}
+
+/**
+ * Fetch full transaction from Solana RPC and extract SPL Memo content (B-4).
+ * Returns parsed memo data or null if no memo found.
+ */
+async function fetchTransactionMemo({ txSignature, rpcUrl, cluster = 'devnet', fetchImpl }) {
+  const endpoint = rpcUrl || CLUSTER_RPC[cluster] || CLUSTER_RPC.devnet;
+  const res = await fetchImpl(endpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'getTransaction',
+      params: [txSignature, { encoding: 'jsonParsed', commitment: 'finalized' }],
+    }),
+  });
+  const body = await res.json();
+  if (!res.ok || body?.error || !body?.result) return null;
+
+  const instructions = body.result.transaction?.message?.instructions || [];
+  for (const ix of instructions) {
+    // SPL Memo can appear as programId or program field
+    if (ix.programId === MEMO_PROGRAM_ID || ix.program === 'spl-memo') {
+      const raw = ix.parsed || ix.data;
+      if (!raw) continue;
+      // Memo may have a Solana program prefix: "[program] JSON"
+      let memoStr = typeof raw === 'string' ? raw : JSON.stringify(raw);
+      const bracketEnd = memoStr.indexOf('] ');
+      if (bracketEnd !== -1 && memoStr.startsWith('[')) {
+        memoStr = memoStr.slice(bracketEnd + 2);
+      }
+      try {
+        return JSON.parse(memoStr);
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+// ============ CLIENT FACTORY ============
+
+export function createBeatsClient({
+  baseUrl = DEFAULT_BASE_URL,
+  fetchImpl = globalThis.fetch,
+  pinnedPublicKey = null,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  onStateChange = null,
+  loadState = null,
+  agentId = null,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('fetch implementation is required');
+  }
+
+  // B-1: Key resolution state — pinned key has highest priority
+  let _cachedKey = pinnedPublicKey || null;
+
+  // B-2: Anchor continuity state
+  let _lastAnchor = null;
+  let _broken = false;
+  let _breakReason = null;
+
+  // Load persisted continuity state
+  if (typeof loadState === 'function') {
+    const saved = loadState();
+    if (saved && typeof saved.beat_index === 'number' && HEX64.test(saved.hash)) {
+      if (!agentId || saved.agent_id === agentId) {
+        _lastAnchor = { beat_index: saved.beat_index, hash: saved.hash };
+      }
+    }
+  }
+
+  function _persistState(anchor) {
+    if (typeof onStateChange === 'function' && anchor) {
+      onStateChange({ beat_index: anchor.beat_index, hash: anchor.hash, agent_id: agentId || null });
+    }
+  }
+
+  // Internal fetch with timeout (B-5)
+  const fetchWithTimeout = async (url, init = {}) => {
+    if (typeof AbortController !== 'undefined' && timeoutMs > 0) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+    return fetchImpl(url, init);
+  };
+
+  const request = async (path, init = {}) => {
+    const res = await fetchWithTimeout(`${baseUrl}${path}`, init);
+    const text = await res.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = { raw: text };
+    }
+    if (!res.ok) {
+      const msg = data?.error || `HTTP ${res.status}`;
+      const err = new Error(msg);
+      err.status = res.status;
+      err.data = data;
+      throw err;
+    }
+    return data;
+  };
+
+  return {
+    // ---- Health ----
+    getHealth() {
+      return request('/api/health');
+    },
+
+    // ---- Anchor (with continuity tracking B-2) ----
+    async getAnchor(opts = {}) {
+      // Fail closed if chain is broken
+      if (_broken) {
+        const err = new Error(`Chain continuity broken: ${_breakReason}. Call resync() to re-establish.`);
+        err.code = 'CHAIN_BROKEN';
+        throw err;
+      }
+
+      const data = await request('/api/v1/beat/anchor');
+      const anchor = data?.anchor;
+
+      // B-2: Strict continuity validation against last known anchor
+      if (anchor && _lastAnchor) {
+        if (anchor.beat_index < _lastAnchor.beat_index) {
+          _broken = true;
+          _breakReason = `regression from ${_lastAnchor.beat_index} to ${anchor.beat_index}`;
+          const err = new Error(
+            `Anchor chain regression: server returned beat_index ${anchor.beat_index}, ` +
+            `but last known was ${_lastAnchor.beat_index}`
+          );
+          err.code = 'ANCHOR_REGRESSION';
+          throw err;
+        }
+        // Same beat_index: must be same hash (idempotent re-fetch)
+        if (anchor.beat_index === _lastAnchor.beat_index) {
+          if (anchor.hash !== _lastAnchor.hash) {
+            _broken = true;
+            _breakReason = `fork at beat_index ${anchor.beat_index}: hash changed`;
+            const err = new Error(
+              `Anchor chain fork at beat_index ${anchor.beat_index}: ` +
+              `hash ${anchor.hash} differs from last known ${_lastAnchor.hash}`
+            );
+            err.code = 'ANCHOR_FORK';
+            throw err;
+          }
+        } else if (anchor.beat_index === _lastAnchor.beat_index + 1) {
+          // Consecutive: prev_hash must link
+          if (anchor.prev_hash !== _lastAnchor.hash) {
+            _broken = true;
+            _breakReason = `prev_hash mismatch at beat_index ${anchor.beat_index}`;
+            const err = new Error(
+              `Anchor chain break at beat_index ${anchor.beat_index}: ` +
+              `prev_hash ${anchor.prev_hash} does not match last known hash ${_lastAnchor.hash}`
+            );
+            err.code = 'ANCHOR_CHAIN_BREAK';
+            throw err;
+          }
+        } else {
+          // Non-consecutive jump: fail closed
+          _broken = true;
+          _breakReason = `beat_index jumped from ${_lastAnchor.beat_index} to ${anchor.beat_index}`;
+          const err = new Error(
+            `Anchor chain jump: beat_index ${anchor.beat_index} is not consecutive ` +
+            `(expected ${_lastAnchor.beat_index + 1})`
+          );
+          err.code = 'ANCHOR_JUMP';
+          throw err;
+        }
+      }
+
+      // B-1: Receipt verification with pinned/cached key (never response key)
+      if (opts.verify === true) {
+        const ok = await this.verifyAnchor(data);
+        if (!ok) throw new Error('Anchor receipt verification failed');
+        data._verified_receipt = true;
+      }
+
+      // B-3: Optional hash recomputation
+      if (opts.recompute === true && anchor) {
+        const hashValid = await recomputeAnchorHash(anchor);
+        if (!hashValid) throw new Error('Anchor hash recomputation failed — server returned invalid hash');
+        data._verified_hash = true;
+      }
+
+      // Update continuity state + persist
+      if (anchor && (!_lastAnchor || anchor.beat_index > _lastAnchor.beat_index)) {
+        _lastAnchor = { ...anchor };
+        _persistState(_lastAnchor);
+      }
+
+      return data;
+    },
+
+    // ---- Key ----
+    getKey() {
+      return request('/api/v1/beat/key');
+    },
+
+    // ---- Verify (server-side) ----
+    verify(payload) {
+      return request('/api/v1/beat/verify', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+    },
+
+    // ---- Timestamp ----
+    timestampHash(hash) {
+      return request('/api/v1/beat/timestamp', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ hash }),
+      });
+    },
+
+    // ---- Receipt Verification (B-1: key pinning) ----
+    async verifyReceipt(response, opts = {}) {
+      const payload = response?.timestamp || response?.anchor || response?.payload;
+      const signature = response?.receipt?.signature || response?.signature;
+      if (!payload || !signature) return false;
+
+      // B-1: Key resolution priority — param > pinned > cached > auto-fetch
+      // NEVER use response.receipt.public_key for verification
+      const key = opts.publicKey || _cachedKey || await this._resolveKey();
+      if (!key) return false;
+
+      try {
+        return await verifyEd25519(payload, signature, key);
+      } catch {
+        return false;
+      }
+    },
+
+    async verifyAnchor(anchorResponse) {
+      if (!anchorResponse?.anchor || !anchorResponse?.receipt) return false;
+      return this.verifyReceipt(anchorResponse);
+    },
+
+    // ---- Anchor Hash Recomputation (B-3) ----
+    verifyAnchorHash(anchor) {
+      return recomputeAnchorHash(anchor);
+    },
+
+    // ---- On-Chain Verification (B-4: memo content check) ----
+    async verifyOnChain(txSignature, opts = {}) {
+      const rpcUrl = opts.rpcUrl || CLUSTER_RPC[opts.cluster || 'devnet'];
+      const status = await verifyOnChainTx({
+        txSignature,
+        rpcUrl,
+        cluster: opts.cluster || 'devnet',
+        fetchImpl: fetchWithTimeout,
+      });
+
+      if (!status.found || !status.finalized) return status;
+
+      // B-4: If expectedPayload provided, fetch tx and verify memo content
+      if (opts.expectedPayload) {
+        const memo = await fetchTransactionMemo({
+          txSignature,
+          rpcUrl,
+          cluster: opts.cluster || 'devnet',
+          fetchImpl: fetchWithTimeout,
+        });
+
+        if (!memo) {
+          return { ...status, memoVerified: false, reason: 'No SPL Memo instruction found in transaction' };
+        }
+
+        const expected = opts.expectedPayload;
+        // Compare critical anchor fields
+        const memoMatch = (
+          (expected.hash === undefined || memo.hash === expected.hash) &&
+          (expected.beat_index === undefined || memo.beat_index === expected.beat_index) &&
+          (expected.prev_hash === undefined || memo.prev === expected.prev_hash) &&
+          (expected.utc === undefined || memo.utc === expected.utc) &&
+          (expected.difficulty === undefined || memo.difficulty === expected.difficulty) &&
+          (expected.epoch === undefined || memo.epoch === expected.epoch) &&
+          // Timestamp memo fields
+          (expected.anchor_index === undefined || memo.anchor_index === expected.anchor_index) &&
+          (expected.anchor_hash === undefined || memo.anchor_hash === expected.anchor_hash)
+        );
+
+        return { ...status, memoVerified: memoMatch, memoData: memo };
+      }
+
+      return status;
+    },
+
+    // ---- Continuity State (B-2) ----
+    setLastKnownAnchor(anchor) {
+      if (_broken) {
+        throw new Error('Chain is broken. Call resync() to re-establish continuity.');
+      }
+      if (anchor && typeof anchor.beat_index === 'number' && HEX64.test(anchor.hash)) {
+        _lastAnchor = { ...anchor };
+        _persistState(_lastAnchor);
+      }
+    },
+
+    getLastKnownAnchor() {
+      return _lastAnchor ? { ..._lastAnchor } : null;
+    },
+
+    resync(anchor) {
+      if (!anchor || typeof anchor.beat_index !== 'number' || !HEX64.test(anchor.hash)) {
+        throw new Error('resync requires a valid anchor with beat_index and hash');
+      }
+      _broken = false;
+      _breakReason = null;
+      _lastAnchor = { ...anchor };
+      _persistState(_lastAnchor);
+    },
+
+    isBroken() {
+      return _broken;
+    },
+
+    // ---- Internal: Key Resolution (B-1) ----
+    async _resolveKey() {
+      if (_cachedKey) return _cachedKey;
+      try {
+        const keyData = await this.getKey();
+        // Prefer hex (more portable) over base58
+        _cachedKey = keyData.public_key_hex || keyData.public_key_base58;
+        return _cachedKey;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/package.json

@@ -1,20 +1,20 @@
-{
-  "name": "@provenonce/beats-client",
-  "version": "0.2.0",
-  "description": "Minimal client for the public Provenonce Beats service",
-  "type": "module",
-  "main": "index.mjs",
-  "types": "index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./index.mjs",
-      "types": "./index.d.ts"
-    }
-  },
-  "files": [
-    "index.mjs",
-    "index.d.ts",
-    "README.md"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "@provenonce/beats-client",
+  "version": "0.3.0",
+  "description": "Minimal client for the public Provenonce Beats service",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "license": "MIT"
+}