feat(anchor-providers): real implementations for OTS, WORM, Ethereum, Rekor

Each provider now does the actual external publish via either pure HTTP
(OTS, Rekor) or a dynamic SDK import (@aws-sdk/client-s3 for WORM,
ethers v6 for Ethereum). All four return structured failures instead
of throwing; the previous `notImplemented: true` flag is gone now that
the implementations are real.

OpenTimestampsProvider — POSTs the SHA-256 digest to one or more public
OTS calendars and stores each calendar's binary attestation as base64
inside the externalRef. New `requireAllCalendars` flag toggles between
quorum modes. Verify re-POSTs and matches the stored attestation hash
(weak verify; full Bitcoin-anchor verification still needs
javascript-opentimestamps).

WormSnapshotProvider — PutObject with Object Lock retention (GOVERNANCE
or COMPLIANCE), recording the SHA-256 in object metadata so verify can
do a constant-time integrity check via HeadObject without re-reading
the body. Supports MinIO / LocalStack via the optional `endpoint` +
forcePathStyle.

EthereumProvider — sends the anchor hash as transaction calldata. Two
modes: raw-calldata (self-transfer with 0x + hash) or contract-call
against `anchor(bytes32)`. Verify recovers tx.data (or decodes the
contract input) and asserts equality with the recomputed canonical
anchor hash. ethers v6.

RekorProvider — submits a hashedrekord v0.0.1 entry. The caller must
provide `publicKeyPem` and a `signArtifact(bytes) => signature`
callback that signs the raw hash bytes (NOT the merkleRoot string
AgentKeyManager defaults to). This is the only honest way to make
Rekor's hashedrekord verifier accept the entry. Verify GETs the entry
by UUID and compares the stored hash with the recomputed digest;
inclusion-proof verification against the signed tree head is left to
sigstore.verify(bundle) for callers who need it.

Tests rewritten to assert against the real success/failure paths with
vi.stubGlobal('fetch', ...) mocks. 19 tests total, all green.

Author: jddunn

registry/curated/provenance/anchor-providers/README.md

@@ -304,35 +304,38 @@ Computes SHA-256 hex digest of the canonical anchor representation.
 
 ## Implementation Status
 
-| Provider | Status | Notes |
-|----------|--------|-------|
-| WormSnapshotProvider | Stub | Requires `@aws-sdk/client-s3` implementation |
-| RekorProvider | Stub | Requires `sigstore` SDK implementation |
-| OpenTimestampsProvider | Stub | Requires `opentimestamps` implementation |
-| EthereumProvider | Stub | Requires `ethers` implementation |
-| SolanaProvider | Implemented | Requires `@solana/web3.js` (and a funded signer) |
+| Provider | Status | Runtime requirements |
+|----------|--------|----------------------|
+| OpenTimestampsProvider | Implemented (weak verify) | None — uses global `fetch` against public OTS calendars |
+| WormSnapshotProvider | Implemented | `@aws-sdk/client-s3` (dynamic import) + S3 bucket with Object Lock enabled |
+| EthereumProvider | Implemented | `ethers` v6 (dynamic import) + funded signer + RPC endpoint |
+| RekorProvider | Implemented (weak verify) | `publicKeyPem` + `signArtifact` callback (Ed25519 sig over raw hash bytes) |
+| SolanaProvider | Implemented | `@solana/web3.js` (dynamic import) + funded signer |
 
-All providers **except SolanaProvider** currently return `{ success: false }` from `publish()` until their respective SDK integrations are implemented. SolanaProvider is functional when its optional peer dependencies are installed and the configured signer is funded.
+All five providers return `{ success: true, externalRef, metadata: {...} }` on a successful publish. Failed publishes return `{ success: false, error, metadata }` — never throw — so a composite anchor strategy can fall through cleanly.
 
-### Detecting stubbed providers programmatically
+### Verification strength
 
-Stub providers set `metadata.notImplemented: true` on the failure result so callers can distinguish "configured provider is not yet implemented" from "implemented provider failed at runtime". Use this when composing fallback strategies:
+| Provider | Verify behaviour |
+|----------|------------------|
+| OpenTimestampsProvider | Weak — re-POSTs the digest to a stored calendar URL and confirms the returned bytes hash to the stored attestation hash. For full Bitcoin-block proof, parse the stored base64 with `javascript-opentimestamps` and run its `verify()` against Bitcoin. |
+| WormSnapshotProvider | Strong — `HeadObjectCommand` confirms the object still exists, the Object Lock retention is still active, and the stored SHA-256 metadata matches the recomputed canonical anchor hash. |
+| EthereumProvider | Strong — fetches the transaction + receipt by hash, decodes calldata (or contract input via the `anchor(bytes32)` ABI), and asserts equality with the recomputed canonical anchor hash. |
+| RekorProvider | Weak — GETs the entry by UUID, decodes the body, and compares the stored hash with the recomputed canonical anchor hash. The inclusion proof against the signed tree head is not verified here; wire `sigstore.verify(bundle)` afterwards for compliance workflows. |
+| SolanaProvider | Strong — reads the on-chain account, decodes the manifest hash + content hash, and compares both against the recomputed canonical values. |
+
+### Failure detection
+
+Failed publishes set `metadata` with provider-specific diagnostics (bucket / region / chainId / serverUrl etc.). For SDK-missing failures the WORM provider sets `metadata.sdkMissing: true` so callers composing fallback strategies can distinguish "this provider can't run on this machine" from "transient runtime error":
 
 ```ts
 const result = await provider.publish(anchor);
 if (!result.success) {
-  if (result.metadata?.notImplemented === true) {
-    // Skip this provider; fall through to the next one in the
-    // composite without surfacing the failure as a real error.
-    continue;
-  }
-  // Real failure — log, alert, retry.
+  if (result.metadata?.sdkMissing === true) continue; // fall through
   throw new Error(`Anchor publish failed: ${result.error}`);
 }
 ```
 
-The error message also names the missing dependency / configuration in plain text so operator-facing logs are immediately actionable.
-
 ## Testing
 
 ```bash

registry/curated/provenance/anchor-providers/src/providers/EthereumProvider.ts

@@ -2,84 +2,263 @@
 /**
  * @file EthereumProvider.ts
  * @description Ethereum on-chain anchor provider.
- * Publishes anchor Merkle roots as calldata in Ethereum transactions.
+ *
+ * `publish()` writes the SHA-256 of the canonical anchor as calldata on
+ * an Ethereum transaction so the anchor becomes inseparable from a
+ * specific block (and via the block, a specific point in time). Two
+ * modes:
+ *
+ *   1. **Self-transfer with calldata** (default when `contractAddress`
+ *      is unset): the signer sends 0 wei to itself with the anchor hash
+ *      packed into the `data` field. Cheap, no contract needed.
+ *   2. **Contract anchor** (when `contractAddress` is set): an ABI call
+ *      to `anchor(bytes32 merkleRoot)` so on-chain consumers can filter
+ *      / index anchor events.
+ *
+ * `verify()` fetches the transaction's receipt, recovers the calldata,
+ * and confirms it matches the recomputed canonical anchor hash.
  *
  * Proof level: `publicly-timestamped`
- * Required peer dependency: `ethers`
+ * Required peer dependency: `ethers` (loaded via dynamic import).
  *
  * @module @framers/agentos-ext-anchor-providers
  */
 
 import type { AnchorProvider, AnchorRecord, AnchorProviderResult, ProofLevel } from '@framers/agentos';
 import type { BaseProviderConfig } from '../types.js';
 import { resolveBaseConfig } from '../types.js';
+import { hashCanonicalAnchor } from '../utils/serialization.js';
 
 export interface EthereumProviderConfig extends BaseProviderConfig {
   /** JSON-RPC endpoint URL. */
   rpcUrl: string;
-  /** Contract address for anchor storage (optional — can use raw calldata tx). */
+  /** Contract address for anchor storage. Omit for raw-calldata mode. */
   contractAddress?: string;
-  /** Private key hex for signing transactions. */
+  /** Private key hex (0x-prefixed) for signing transactions. */
   signerPrivateKey?: string;
   /** Chain ID. Default: 1 (mainnet). */
   chainId?: number;
   /** Gas limit override. Default: auto-estimate. */
   gasLimit?: number;
+  /** Number of confirmations to wait for. Default: 1. */
+  confirmations?: number;
 }
 
+/**
+ * Minimal ABI fragment for an `anchor(bytes32)` contract. Callers can
+ * deploy any contract with this method signature (e.g. logging the
+ * merkleRoot to an event) and point `contractAddress` at it.
+ */
+const ANCHOR_CONTRACT_ABI = ['function anchor(bytes32 merkleRoot)'];
+
 export class EthereumProvider implements AnchorProvider {
   readonly id = 'ethereum';
   readonly name = 'Ethereum On-Chain Anchor';
   readonly proofLevel: ProofLevel = 'publicly-timestamped';
 
-  private readonly config: EthereumProviderConfig;
+  private readonly config: Required<Omit<EthereumProviderConfig, 'contractAddress' | 'signerPrivateKey' | 'gasLimit'>> & {
+    contractAddress?: string;
+    signerPrivateKey?: string;
+    gasLimit?: number;
+  };
   private readonly baseConfig: Required<BaseProviderConfig>;
 
+  /** Cached ethers Provider — reused across calls. */
+  private cachedProvider: any = null;
+  /** Cached ethers Wallet — only present when signing is configured. */
+  private cachedWallet: any = null;
+
   constructor(config: EthereumProviderConfig) {
     this.config = {
-      chainId: 1,
-      ...config,
+      rpcUrl: config.rpcUrl,
+      chainId: config.chainId ?? 1,
+      confirmations: config.confirmations ?? 1,
+      timeoutMs: config.timeoutMs ?? 30_000,
+      retries: config.retries ?? 3,
+      retryDelayMs: config.retryDelayMs ?? 1_000,
+      contractAddress: config.contractAddress,
+      signerPrivateKey: config.signerPrivateKey,
+      gasLimit: config.gasLimit,
     };
     this.baseConfig = resolveBaseConfig(config);
   }
 
-  async publish(_anchor: AnchorRecord): Promise<AnchorProviderResult> {
-    // Stubbed pending ethers/viem wiring + funded signer. Required steps:
-    //   1. Compute SHA-256 of canonical anchor: hashCanonicalAnchor(anchor)
-    //   2. `new ethers.JsonRpcProvider(this.config.rpcUrl)`
-    //   3. `new ethers.Wallet(this.config.signerPrivateKey, provider)`
-    //   4. If `contractAddress` is set: ABI-encode `anchor(bytes32)` and
-    //      `wallet.sendTransaction` to it.
-    //      Otherwise: self-transfer with `data: '0x' + hash` as calldata.
-    //   5. Await receipt (1 confirmation by default; configurable).
-    //   6. Return `externalRef: 'eth:${chainId}:${txHash}'` plus
-    //      blockNumber/blockHash/gasUsed in metadata.
-    // Verify path: fetch receipt by tx hash, decode calldata or read the
-    // contract event log, compare against `hashCanonicalAnchor(anchor)`.
-    return {
-      providerId: this.id,
-      success: false,
-      error:
-        'EthereumProvider not implemented. Pending: `ethers` (or `viem`) + funded signer + RPC endpoint. See provider source for the implementation outline.',
-      metadata: {
-        notImplemented: true,
-        chainId: this.config.chainId,
-        rpcUrl: this.config.rpcUrl,
-        hasContract: Boolean(this.config.contractAddress),
-      },
-    };
+  async publish(anchor: AnchorRecord): Promise<AnchorProviderResult> {
+    if (!this.config.signerPrivateKey) {
+      return {
+        providerId: this.id,
+        success: false,
+        error: 'EthereumProvider.publish requires signerPrivateKey to send transactions.',
+        metadata: { chainId: this.config.chainId },
+      };
+    }
+
+    let ethers: any;
+    try {
+      ethers = await this.loadEthers();
+    } catch (e) {
+      return {
+        providerId: this.id,
+        success: false,
+        error: e instanceof Error ? e.message : String(e),
+        metadata: { sdkMissing: true },
+      };
+    }
+
+    const digestHex = await hashCanonicalAnchor(anchor);
+    const dataHex = `0x${digestHex}`;
+
+    try {
+      const wallet = await this.getWallet(ethers);
+      let txResponse: any;
+
+      if (this.config.contractAddress) {
+        // Contract-call mode: invoke anchor(bytes32) so on-chain
+        // listeners can index anchor commits by event.
+        const contract = new ethers.Contract(this.config.contractAddress, ANCHOR_CONTRACT_ABI, wallet);
+        const overrides: Record<string, unknown> = {};
+        if (this.config.gasLimit !== undefined) overrides.gasLimit = this.config.gasLimit;
+        txResponse = await contract.anchor(dataHex, overrides);
+      } else {
+        // Raw-calldata mode: self-transfer with the digest packed into
+        // the data field. No contract required; the proof is just the
+        // existence of a tx with this calldata in a finalised block.
+        const tx: Record<string, unknown> = {
+          to: await wallet.getAddress(),
+          value: 0n,
+          data: dataHex,
+        };
+        if (this.config.gasLimit !== undefined) tx.gasLimit = this.config.gasLimit;
+        txResponse = await wallet.sendTransaction(tx);
+      }
+
+      const receipt = await txResponse.wait(this.config.confirmations);
+      if (!receipt) {
+        return {
+          providerId: this.id,
+          success: false,
+          error: 'Transaction sent but receipt was null',
+          metadata: { txHash: txResponse.hash, chainId: this.config.chainId },
+        };
+      }
+
+      return {
+        providerId: this.id,
+        success: true,
+        externalRef: `eth:${this.config.chainId}:${receipt.hash ?? txResponse.hash}`,
+        publishedAt: new Date().toISOString(),
+        metadata: {
+          chainId: this.config.chainId,
+          txHash: receipt.hash ?? txResponse.hash,
+          blockNumber: receipt.blockNumber,
+          blockHash: receipt.blockHash,
+          gasUsed: receipt.gasUsed?.toString(),
+          contractAddress: this.config.contractAddress,
+          mode: this.config.contractAddress ? 'contract' : 'calldata',
+        },
+      };
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      return {
+        providerId: this.id,
+        success: false,
+        error: `Ethereum transaction failed: ${message}`,
+        metadata: { chainId: this.config.chainId },
+      };
+    }
   }
 
+  /**
+   * Confirm the anchor's `eth:` externalRef points at a finalised tx
+   * whose calldata (or contract input) matches the recomputed canonical
+   * anchor digest. Does not re-execute the contract — just compares the
+   * stored calldata against the expected hash.
+   */
   async verify(anchor: AnchorRecord): Promise<boolean> {
-    // Pending implementation. Parse the `eth:${chainId}:${txHash}` ref,
-    // fetch the receipt via the configured RPC, decode calldata (or read
-    // the contract event), and compare against the recomputed canonical
-    // anchor hash.
-    if (!anchor.externalRef) return false;
-    return false;
+    if (!anchor.externalRef?.startsWith('eth:')) return false;
+    let ethers: any;
+    try {
+      ethers = await this.loadEthers();
+    } catch {
+      return false;
+    }
+
+    // Parse eth:${chainId}:${txHash}
+    const parts = anchor.externalRef.split(':');
+    if (parts.length < 3) return false;
+    const txHash = parts.slice(2).join(':'); // tolerate 0x... that already has colons (defensive)
+
+    try {
+      const provider = this.getProvider(ethers);
+      const tx = await provider.getTransaction(txHash);
+      if (!tx) return false;
+      const receipt = await provider.getTransactionReceipt(txHash);
+      if (!receipt || receipt.status === 0) return false;
+
+      const expectedHex = `0x${await hashCanonicalAnchor(anchor)}`;
+
+      if (this.config.contractAddress) {
+        // For contract calls, the calldata is the ABI-encoded anchor()
+        // function call. Decode and compare the bytes32 arg.
+        const iface = new ethers.Interface(ANCHOR_CONTRACT_ABI);
+        try {
+          const parsed = iface.parseTransaction({ data: tx.data, value: tx.value });
+          if (!parsed || parsed.name !== 'anchor') return false;
+          const argHex = (parsed.args[0] as string).toLowerCase();
+          return argHex === expectedHex;
+        } catch {
+          return false;
+        }
+      }
+
+      // Raw-calldata mode: tx.data is the digest hex directly.
+      return tx.data?.toLowerCase() === expectedHex;
+    } catch {
+      return false;
+    }
   }
 
   async dispose(): Promise<void> {
-    // TODO: Disconnect provider if persistent connection was established
+    if (this.cachedProvider && typeof this.cachedProvider.destroy === 'function') {
+      try {
+        this.cachedProvider.destroy();
+      } catch {
+        // Best-effort cleanup.
+      }
+    }
+    this.cachedProvider = null;
+    this.cachedWallet = null;
+  }
+
+  private async loadEthers(): Promise<any> {
+    const moduleName = 'ethers';
+    try {
+      const mod = await import(moduleName);
+      // ethers v6 exports a namespace under default; v5 exports flat.
+      // We use namespace-style access (`ethers.Wallet`, `ethers.Contract`)
+      // which works for v6 root export.
+      return (mod as any).ethers ?? mod;
+    } catch {
+      throw new Error(
+        'EthereumProvider requires ethers (v6) at runtime. ' +
+          'Install it in your project to enable Ethereum anchoring.',
+      );
+    }
+  }
+
+  private getProvider(ethers: any): any {
+    if (this.cachedProvider) return this.cachedProvider;
+    this.cachedProvider = new ethers.JsonRpcProvider(this.config.rpcUrl, this.config.chainId);
+    return this.cachedProvider;
+  }
+
+  private async getWallet(ethers: any): Promise<any> {
+    if (this.cachedWallet) return this.cachedWallet;
+    if (!this.config.signerPrivateKey) {
+      throw new Error('signerPrivateKey is required to obtain a wallet for publishing.');
+    }
+    const provider = this.getProvider(ethers);
+    this.cachedWallet = new ethers.Wallet(this.config.signerPrivateKey, provider);
+    return this.cachedWallet;
   }
 }