@rel-time/mcp-server 1.2.7 → 1.2.9

package/index.js

@@ -56,7 +56,7 @@ let LAST_INVOICE_PACK = null;
 
 const SERVER_INFO = {
   name: "rel-time-mcp-server",
-  version: "1.2.7",
+  version: "1.2.9",
 };
 
 /**
@@ -477,6 +477,1056 @@ async function stampLocalFileOptionA(filePath, svgContent, customOutputPath = nu
   }
 }
 
+/**
+ * Extracts an embedded Rel-Time verification hash from a Stamped Copy (.png or .pdf) if present.
+ */
+function extractStampedCopyEmbeddedHash(filePath, fileBuffer) {
+  try {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".png" || ext === ".pdf" || ext === ".svg") {
+      const latin1 = fileBuffer.toString("latin1");
+      const m = latin1.match(/rel-time\.com\/verify\?t=([0-9a-fA-F]{64})/);
+      if (m && m[1]) {
+        return m[1].toLowerCase();
+      }
+    }
+  } catch (e) {
+    // Ignore extraction errors
+  }
+  return null;
+}
+
+function escapeHtml(str) {
+  return String(str == null ? "" : str)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Generates a self-contained, institutional-grade Rel-Time Superhighway Cryptographic Audit Trail HTML report.
+ */
+function generateAuditReportHtml(audit) {
+  const generatedUtc = audit.generated_at_utc || new Date().toISOString();
+  const acct = audit.account_overview || {};
+  const sum = audit.audit_summary || {};
+  const modes = sum.mode_breakdown || {};
+  const btc = sum.bitcoin_settlement || {};
+  const signers = Array.isArray(sum.hardware_passkey_signers) ? sum.hardware_passkey_signers : [];
+  const localCheck = audit.local_path_verification || null;
+  const entries = Array.isArray(audit.audit_trail) ? audit.audit_trail : [];
+
+  const totalMatched = Math.max(1, Number(sum.matched_entries_count || entries.length || 1));
+  const settledCount = Number(sum.settled_on_bitcoin_count || 0);
+  const pendingCount = Number(sum.pending_finality_count || 0);
+  const standardCount = Number(modes.standard_count || 0);
+  const temporalCount = Number(modes.temporal_vdf_count || 0);
+  const biometricCount = Number(modes.biometric_passkey_count || 0);
+  const machineCount = Math.max(0, Number(sum.matched_entries_count || entries.length) - biometricCount);
+
+  const settledPct = Math.round((settledCount / totalMatched) * 100);
+  const standardPct = Math.round((standardCount / totalMatched) * 100);
+  const biometricPct = Math.round((biometricCount / totalMatched) * 100);
+
+  // Build Bitcoin Block Settlement Topology nodes from entries
+  const blockGroupsMap = new Map();
+  for (const e of entries) {
+    if (e.status === "settled" && e.block_height) {
+      const bh = String(e.block_height);
+      const cur = blockGroupsMap.get(bh) || {
+        block_height: bh,
+        count: 0,
+        txid: e.txid || null,
+        max_ticks: 0,
+        timestamp_utc: e.timestamp_utc || null,
+      };
+      cur.count++;
+      if (!cur.txid && e.txid) cur.txid = e.txid;
+      if (Number(e.vdf_ticks || 0) > cur.max_ticks) cur.max_ticks = Number(e.vdf_ticks || 0);
+      blockGroupsMap.set(bh, cur);
+    }
+  }
+  const sortedBlocks = Array.from(blockGroupsMap.values())
+    .sort((a, b) => Number(a.block_height) - Number(b.block_height))
+    .slice(-5);
+
+  const topologyNodesHtml = [
+    ...sortedBlocks.map(
+      (b) => `
+      <div class="topo-node">
+        <div class="topo-node-top">
+          <span class="dot dot-settled"></span>
+          <span class="mono topo-height">BLOCK #${escapeHtml(b.block_height)}</span>
+        </div>
+        <div class="topo-metric mono">${b.count} ${b.count === 1 ? "ANCHOR" : "ANCHORS"}</div>
+        <div class="topo-meta mono">
+          ${
+            b.txid
+              ? `<a href="https://mempool.space/tx/${escapeHtml(b.txid)}" target="_blank" rel="noopener">TX ${escapeHtml(
+                  b.txid.slice(0, 8)
+                )}…${escapeHtml(b.txid.slice(-4))} ↗</a>`
+              : "SETTLED"
+          }
+        </div>
+      </div>`
+    ),
+    pendingCount > 0
+      ? `
+      <div class="topo-node topo-node-pending">
+        <div class="topo-node-top">
+          <span class="dot dot-pending"></span>
+          <span class="mono topo-height">VDF MEMPOOL QUEUE</span>
+        </div>
+        <div class="topo-metric mono">${pendingCount} PENDING</div>
+        <div class="topo-meta mono">NEXT EPOCH (~10m)</div>
+      </div>`
+      : "",
+  ]
+    .filter(Boolean)
+    .join(`<div class="topo-connector"></div>`);
+
+  const signerRowsHtml = signers.length
+    ? signers
+        .map((s, idx) => {
+          const sharePct = Math.round((Number(s.anchor_count || 0) / totalMatched) * 100);
+          return `
+        <tr>
+          <td class="mono muted">${String(idx + 1).padStart(2, "0")}</td>
+          <td>
+            <div class="signer-key-header">
+              <span class="tag tag-neutral">FIDO2 / COSE P-256</span>
+              <span class="mono muted">KEY ID: ${escapeHtml(s.signer_public_key.slice(0, 16).toUpperCase())}</span>
+            </div>
+            <div class="mono hash-full" style="margin-top:5px">${escapeHtml(s.signer_public_key)}</div>
+          </td>
+          <td class="mono">
+            <div style="display:flex;align-items:center;gap:10px">
+              <span style="font-weight:700;color:var(--text);min-width:24px">${s.anchor_count}</span>
+              <div class="mini-bar-track"><div class="mini-bar-fill" style="width:${sharePct}%"></div></div>
+              <span class="muted" style="font-size:11px">${sharePct}%</span>
+            </div>
+          </td>
+          <td class="mono">${s.settled_count} / ${s.anchor_count}</td>
+          <td class="mono muted">${escapeHtml(s.latest_timestamp_utc || "—")}</td>
+        </tr>`;
+        })
+        .join("")
+    : `<tr><td colspan="5" class="empty-cell">No hardware Passkey signatures recorded in this window. Link a FIDO2/WebAuthn hardware key with <code>reltime_link_passkey</code> and anchor with <code>biometric: true</code>.</td></tr>`;
+
+  const localVerificationHtml = localCheck
+    ? `
+    <section class="panel">
+      <div class="panel-header">
+        <div>
+          <div class="section-index">SECTION 01 // ZERO-KNOWLEDGE LOCAL FILE INTEGRITY MATRIX</div>
+          <h2>Local Directory Cross-Reference</h2>
+          <p class="section-sub">Target Path: <span class="mono" style="color:var(--text-secondary)">${escapeHtml(
+            localCheck.target_path
+          )}</span> · 0 Bytes Uploaded · Local SHA-256 vs. Bitcoin Ledger</p>
+        </div>
+        <div class="status-pill ${
+          localCheck.summary.unanchored_or_modified_count === 0 ? "status-pill-ok" : "status-pill-alert"
+        }">
+          <span class="dot ${
+            localCheck.summary.unanchored_or_modified_count === 0 ? "dot-settled" : "dot-alert"
+          }"></span>
+          <span>${
+            localCheck.summary.unanchored_or_modified_count === 0
+              ? `INTEGRITY VERIFIED (${localCheck.summary.total_files_scanned}/${localCheck.summary.total_files_scanned})`
+              : `${localCheck.summary.unanchored_or_modified_count} UNANCHORED OR MODIFIED`
+          }</span>
+        </div>
+      </div>
+      <div class="table-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th style="width:42px">#</th>
+              <th>Artifact / File Name</th>
+              <th>Bytes</th>
+              <th>Local SHA-256 Digest</th>
+              <th>Verification Status</th>
+              <th>Attestation / Mode</th>
+              <th>Timechain Settlement</th>
+              <th style="text-align:right">Receipt</th>
+            </tr>
+          </thead>
+          <tbody>
+            ${localCheck.files
+              .map((f, idx) => {
+                const statusTag =
+                  f.integrity_status === "VERIFIED_SETTLED"
+                    ? `<span class="status-cell"><span class="dot dot-settled"></span><span class="mono" style="color:var(--text)">VERIFIED · SETTLED</span></span>`
+                    : f.integrity_status === "VERIFIED_PENDING"
+                    ? `<span class="status-cell"><span class="dot dot-pending"></span><span class="mono" style="color:var(--text-secondary)">VERIFIED · PENDING</span></span>`
+                    : `<span class="status-cell"><span class="dot dot-alert"></span><span class="mono" style="color:var(--crimson)">UNANCHORED / MODIFIED</span></span>`;
+
+                const signerText = f.signer_public_key
+                  ? `<span class="tag tag-neutral" title="Passkey COSE: ${escapeHtml(
+                      f.signer_public_key
+                    )}">PASSKEY ${escapeHtml(f.signer_public_key.slice(0, 8).toUpperCase())}…</span>`
+                  : f.anchor_mode
+                  ? `<span class="tag tag-neutral">${escapeHtml(f.anchor_mode.toUpperCase())}</span>`
+                  : `<span class="mono muted">—</span>`;
+
+                const btcText = f.block_height
+                  ? `<span class="mono" style="color:var(--text)">BLOCK #${escapeHtml(f.block_height)}</span>`
+                  : f.integrity_status === "VERIFIED_PENDING"
+                  ? `<span class="mono muted">MEMPOOL QUEUE</span>`
+                  : `<span class="mono muted">—</span>`;
+
+                const verifyLink = f.verify_url
+                  ? `<a class="action-link" href="${escapeHtml(f.verify_url)}" target="_blank" rel="noopener">VERIFY ↗</a>`
+                  : `<span class="mono muted">—</span>`;
+
+                return `
+                <tr>
+                  <td class="mono muted">${String(idx + 1).padStart(2, "0")}</td>
+                  <td>
+                    <span style="font-weight:600;color:var(--text)">${escapeHtml(f.file_name)}</span>
+                    ${f.is_stamped_copy ? `<span class="tag tag-subtle" style="margin-left:8px">STAMPED COPY</span>` : ""}
+                  </td>
+                  <td class="mono muted">${escapeHtml(f.size_human)}</td>
+                  <td class="mono" style="color:var(--text-secondary)" title="${escapeHtml(f.local_sha256)}">${escapeHtml(
+                  f.local_sha256.slice(0, 16)
+                )}…${escapeHtml(f.local_sha256.slice(-10))}</td>
+                  <td>${statusTag}</td>
+                  <td>${signerText}</td>
+                  <td>${btcText}</td>
+                  <td style="text-align:right">${verifyLink}</td>
+                </tr>`;
+              })
+              .join("")}
+          </tbody>
+        </table>
+      </div>
+    </section>`
+    : "";
+
+  const ledgerSectionNum = localCheck ? "03" : "02";
+  const signerSectionNum = localCheck ? "02" : "01";
+
+  const ledgerRowsHtml = entries.length
+    ? entries
+        .map((e, idx) => {
+          const isSettled = e.status === "settled";
+          const isBiometric = Boolean(e.signer_public_key);
+          const modeType = e.anchor_mode || "standard";
+          const filterClasses = [
+            isSettled ? "status-settled" : "status-pending",
+            `mode-${modeType}`,
+            isBiometric ? "mode-biometric" : "",
+          ]
+            .filter(Boolean)
+            .join(" ");
+
+          const statusHtml = isSettled
+            ? `<span class="status-cell"><span class="dot dot-settled"></span><span class="mono" style="color:var(--text)">SETTLED</span></span>`
+            : `<span class="status-cell"><span class="dot dot-pending"></span><span class="mono muted">PENDING</span></span>`;
+
+          const modeHtml = `
+            <span class="tag tag-neutral">${escapeHtml(modeType.toUpperCase())}</span>
+            ${
+              isBiometric
+                ? `<span class="tag tag-subtle" title="Passkey COSE: ${escapeHtml(
+                    e.signer_public_key
+                  )}">PK:${escapeHtml(e.signer_public_key.slice(0, 8).toUpperCase())}</span>`
+                : ""
+            }
+          `;
+
+          const btcHtml = isSettled
+            ? `
+              <div class="mono" style="color:var(--text);font-weight:600">BLOCK #${escapeHtml(e.block_height || "—")}</div>
+              ${
+                e.txid
+                  ? `<a class="mono tx-link" href="https://mempool.space/tx/${escapeHtml(
+                      e.txid
+                    )}" target="_blank" rel="noopener" title="${escapeHtml(e.txid)}">TX ${escapeHtml(
+                      e.txid.slice(0, 10)
+                    )}…${escapeHtml(e.txid.slice(-6))} ↗</a>`
+                  : ""
+              }
+            `
+            : `<span class="mono muted">AWAITING BLOCK</span>`;
+
+          return `
+          <tr class="ledger-row ${filterClasses}" data-search="${escapeHtml(
+            `${e.client_hash} ${e.t_index} ${e.original_file_hash || ""} ${e.signer_public_key || ""} ${
+              e.txid || ""
+            } ${e.block_height || ""} ${modeType}`.toLowerCase()
+          )}">
+            <td class="mono muted">${String(idx + 1).padStart(2, "0")}</td>
+            <td class="mono muted">${escapeHtml((e.timestamp_utc || "—").replace(".000Z", "Z"))}</td>
+            <td>${statusHtml}</td>
+            <td>${modeHtml}</td>
+            <td class="mono" style="color:var(--text-secondary)" title="Client Hash: ${escapeHtml(e.client_hash)}${
+            e.original_file_hash ? ` | Original File SHA-256: ${escapeHtml(e.original_file_hash)}` : ""
+          }">
+              <div>${escapeHtml(e.client_hash.slice(0, 14))}…${escapeHtml(e.client_hash.slice(-10))}</div>
+              ${
+                e.original_file_hash
+                  ? `<div class="muted" style="font-size:10.5px;margin-top:2px">FILE: ${escapeHtml(
+                      e.original_file_hash.slice(0, 12)
+                    )}…</div>`
+                  : ""
+              }
+            </td>
+            <td class="mono" style="color:var(--text-secondary)" title="T_index: ${escapeHtml(e.t_index)} | Solar Ticks: ${escapeHtml(
+            e.vdf_ticks
+          )}">
+              <div>${escapeHtml(e.t_index.slice(0, 14))}…${escapeHtml(e.t_index.slice(-8))}</div>
+              <div class="muted" style="font-size:10.5px;margin-top:2px">VDF TICKS: ${Number(
+                e.vdf_ticks || 0
+              ).toLocaleString()}</div>
+            </td>
+            <td>${btcHtml}</td>
+            <td style="text-align:right">
+              <a class="action-link" href="${escapeHtml(e.verify_url)}" target="_blank" rel="noopener">VERIFY ↗</a>
+            </td>
+          </tr>`;
+        })
+        .join("")
+    : `<tr><td colspan="8" class="empty-cell">No ledger entries matched the active filter criteria.</td></tr>`;
+
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Rel-Time Superhighway // Forensic Timechain Audit Report</title>
+  <style>
+    :root {
+      --bg: #050506;
+      --grid-line: rgba(255, 255, 255, 0.015);
+      --panel: #0a0a0c;
+      --panel-alt: #0e0e12;
+      --border: #1e1e24;
+      --border-strong: #2e2e38;
+      --text: #f4f4f5;
+      --text-secondary: #d4d4d8;
+      --muted: #71717a;
+      --amber: #f59e0b;
+      --emerald: #10b981;
+      --crimson: #ef4444;
+      --track-bg: #18181d;
+      --bar-primary: #e4e4e7;
+      --bar-muted: #3f3f46;
+      --tag-bg: #141418;
+      --tab-active-bg: #18181f;
+      --row-hover: rgba(255, 255, 255, 0.015);
+      --btn-primary-fg: #050506;
+    }
+    html[data-theme="light"] {
+      --bg: #f4f4f6;
+      --grid-line: rgba(0, 0, 0, 0.03);
+      --panel: #ffffff;
+      --panel-alt: #f8f8fa;
+      --border: #e4e4e7;
+      --border-strong: #d4d4d8;
+      --text: #09090b;
+      --text-secondary: #3f3f46;
+      --muted: #71717a;
+      --amber: #d97706;
+      --emerald: #059669;
+      --crimson: #dc2626;
+      --track-bg: #e4e4e7;
+      --bar-primary: #18181b;
+      --bar-muted: #a1a1aa;
+      --tag-bg: #f4f4f5;
+      --tab-active-bg: #f4f4f5;
+      --row-hover: rgba(0, 0, 0, 0.02);
+      --btn-primary-fg: #ffffff;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      padding: 28px 24px 64px;
+      background-color: var(--bg);
+      background-image:
+        linear-gradient(to right, var(--grid-line) 1px, transparent 1px),
+        linear-gradient(to bottom, var(--grid-line) 1px, transparent 1px);
+      background-size: 32px 32px;
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif;
+      font-size: 13px;
+      line-height: 1.45;
+      -webkit-font-smoothing: antialiased;
+      transition: background-color 0.15s ease, color 0.15s ease;
+    }
+    .container { max-width: 1360px; margin: 0 auto; }
+    .mono {
+      font-family: "JetBrains Mono", "SF Mono", "Fira Code", Menlo, Consolas, monospace;
+      font-variant-numeric: tabular-nums;
+      font-size: 12px;
+    }
+    .muted { color: var(--muted); }
+
+    /* Masthead */
+    .masthead {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-top: 2px solid var(--amber);
+      padding: 22px 26px;
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: space-between;
+      align-items: flex-start;
+      gap: 20px;
+      margin-bottom: 16px;
+    }
+    .eyebrow {
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10.5px;
+      letter-spacing: 0.16em;
+      text-transform: uppercase;
+      color: var(--amber);
+      margin-bottom: 6px;
+    }
+    h1 {
+      margin: 0;
+      font-size: 22px;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+      color: var(--text);
+    }
+    .masthead-meta {
+      margin-top: 10px;
+      display: flex;
+      flex-wrap: wrap;
+      gap: 18px;
+      font-size: 11.5px;
+      color: var(--muted);
+    }
+    .masthead-meta span strong {
+      color: var(--text-secondary);
+      font-weight: 600;
+    }
+    .actions-bar {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+      align-items: center;
+    }
+    .btn-primary {
+      background: var(--text);
+      color: var(--btn-primary-fg);
+      border: 1px solid var(--text);
+      padding: 9px 14px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 11px;
+      font-weight: 700;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      cursor: pointer;
+      text-decoration: none;
+    }
+    .btn-primary:hover {
+      background: var(--amber);
+      border-color: var(--amber);
+      color: #050506;
+    }
+    .btn-secondary {
+      background: transparent;
+      color: var(--text-secondary);
+      border: 1px solid var(--border-strong);
+      padding: 9px 14px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 11px;
+      font-weight: 600;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      cursor: pointer;
+      text-decoration: none;
+    }
+    .btn-secondary:hover {
+      border-color: var(--text-secondary);
+      color: var(--text);
+    }
+
+    /* Flush Architectural Telemetry Strip */
+    .telemetry-strip {
+      display: grid;
+      grid-template-columns: repeat(6, 1fr);
+      background: var(--panel);
+      border: 1px solid var(--border);
+      margin-bottom: 16px;
+    }
+    @media (max-width: 1100px) {
+      .telemetry-strip { grid-template-columns: repeat(3, 1fr); }
+    }
+    @media (max-width: 640px) {
+      .telemetry-strip { grid-template-columns: repeat(2, 1fr); }
+    }
+    .telemetry-cell {
+      padding: 16px 20px;
+      border-right: 1px solid var(--border);
+      border-bottom: 1px solid var(--border);
+    }
+    .telemetry-cell:last-child { border-right: none; }
+    .telemetry-label {
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10px;
+      text-transform: uppercase;
+      letter-spacing: 0.12em;
+      color: var(--muted);
+      margin-bottom: 8px;
+    }
+    .telemetry-val {
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 24px;
+      font-weight: 700;
+      color: var(--text);
+      letter-spacing: -0.02em;
+    }
+    .telemetry-sub {
+      font-size: 11px;
+      color: var(--muted);
+      margin-top: 4px;
+    }
+
+    /* Visualization Grid (2 Columns) */
+    .viz-grid {
+      display: grid;
+      grid-template-columns: 1fr 1.25fr;
+      gap: 16px;
+      margin-bottom: 16px;
+    }
+    @media (max-width: 980px) {
+      .viz-grid { grid-template-columns: 1fr; }
+    }
+    .panel {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      padding: 20px 24px;
+      margin-bottom: 16px;
+    }
+    .viz-grid .panel { margin-bottom: 0; }
+    .panel-header {
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: space-between;
+      align-items: flex-start;
+      gap: 12px;
+      padding-bottom: 14px;
+      border-bottom: 1px solid var(--border);
+      margin-bottom: 16px;
+    }
+    .section-index {
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10px;
+      letter-spacing: 0.14em;
+      text-transform: uppercase;
+      color: var(--muted);
+      margin-bottom: 3px;
+    }
+    h2 {
+      margin: 0;
+      font-size: 15px;
+      font-weight: 700;
+      letter-spacing: -0.01em;
+      color: var(--text);
+    }
+    .section-sub {
+      margin: 3px 0 0;
+      font-size: 12px;
+      color: var(--muted);
+    }
+
+    /* Distribution Bars */
+    .dist-row {
+      margin-bottom: 14px;
+    }
+    .dist-row:last-child { margin-bottom: 0; }
+    .dist-header {
+      display: flex;
+      justify-content: space-between;
+      font-size: 11.5px;
+      margin-bottom: 6px;
+    }
+    .dist-track {
+      height: 6px;
+      width: 100%;
+      background: var(--track-bg);
+      display: flex;
+      overflow: hidden;
+    }
+    .dist-seg-primary { background: var(--bar-primary); height: 100%; }
+    .dist-seg-emerald { background: var(--emerald); height: 100%; }
+    .dist-seg-amber { background: var(--amber); height: 100%; }
+    .dist-seg-muted { background: var(--bar-muted); height: 100%; }
+
+    /* Bitcoin Topology Strip */
+    .topo-chain {
+      display: flex;
+      align-items: stretch;
+      gap: 0;
+      overflow-x: auto;
+      padding: 6px 0 4px;
+    }
+    .topo-node {
+      flex: 1;
+      min-width: 135px;
+      background: var(--panel-alt);
+      border: 1px solid var(--border-strong);
+      padding: 12px 14px;
+    }
+    .topo-node-pending {
+      border-style: dashed;
+      border-color: rgba(245, 158, 11, 0.55);
+    }
+    .topo-node-top {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      margin-bottom: 8px;
+    }
+    .topo-height {
+      font-size: 11px;
+      font-weight: 700;
+      color: var(--text);
+    }
+    .topo-metric {
+      font-size: 14px;
+      font-weight: 700;
+      color: var(--text-secondary);
+      margin-bottom: 4px;
+    }
+    .topo-meta {
+      font-size: 10.5px;
+      color: var(--muted);
+    }
+    .topo-meta a {
+      color: var(--muted);
+      text-decoration: none;
+      border-bottom: 1px dotted var(--muted);
+    }
+    .topo-meta a:hover { color: var(--text); border-bottom-color: var(--text); }
+    .topo-connector {
+      width: 18px;
+      min-width: 18px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      position: relative;
+    }
+    .topo-connector::before {
+      content: "";
+      width: 100%;
+      height: 1px;
+      background: var(--border-strong);
+    }
+
+    /* Status Dots & Tags */
+    .status-cell {
+      display: inline-flex;
+      align-items: center;
+      gap: 7px;
+      white-space: nowrap;
+    }
+    .dot {
+      width: 6px;
+      height: 6px;
+      border-radius: 50%;
+      display: inline-block;
+      flex-shrink: 0;
+    }
+    .dot-settled { background: var(--emerald); }
+    .dot-pending { background: var(--amber); }
+    .dot-alert { background: var(--crimson); }
+
+    .status-pill {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      padding: 5px 10px;
+      border: 1px solid var(--border-strong);
+      background: var(--panel-alt);
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 11px;
+      font-weight: 600;
+    }
+    .status-pill-ok { border-color: rgba(16, 185, 129, 0.4); color: var(--text); }
+    .status-pill-alert { border-color: rgba(239, 68, 68, 0.5); color: var(--crimson); }
+
+    .tag {
+      display: inline-block;
+      padding: 2px 6px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10px;
+      font-weight: 600;
+      letter-spacing: 0.04em;
+      white-space: nowrap;
+    }
+    .tag-neutral {
+      background: var(--tag-bg);
+      border: 1px solid var(--border-strong);
+      color: var(--text-secondary);
+    }
+    .tag-subtle {
+      background: transparent;
+      border: 1px solid var(--border);
+      color: var(--muted);
+    }
+
+    .mini-bar-track {
+      width: 72px;
+      height: 4px;
+      background: var(--track-bg);
+      overflow: hidden;
+    }
+    .mini-bar-fill {
+      height: 100%;
+      background: var(--text-secondary);
+    }
+
+    /* Filter Bar */
+    .filter-bar {
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: space-between;
+      gap: 10px;
+      align-items: center;
+      margin-bottom: 14px;
+    }
+    .search-input {
+      background: var(--bg);
+      border: 1px solid var(--border-strong);
+      color: var(--text);
+      padding: 7px 12px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 11.5px;
+      min-width: 290px;
+      outline: none;
+    }
+    .search-input:focus { border-color: var(--text-secondary); }
+    .tab-group {
+      display: inline-flex;
+      border: 1px solid var(--border-strong);
+      background: var(--bg);
+    }
+    .filter-tab {
+      background: transparent;
+      border: none;
+      border-right: 1px solid var(--border);
+      color: var(--muted);
+      padding: 6px 11px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10.5px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      cursor: pointer;
+    }
+    .filter-tab:last-child { border-right: none; }
+    .filter-tab:hover { color: var(--text-secondary); }
+    .filter-tab.active {
+      background: var(--tab-active-bg);
+      color: var(--text);
+      box-shadow: inset 0 -2px 0 var(--amber);
+    }
+
+    /* Tables */
+    .table-wrap { overflow-x: auto; }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+    }
+    th {
+      text-align: left;
+      padding: 10px 12px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      color: var(--muted);
+      background: var(--bg);
+      border-top: 1px solid var(--border);
+      border-bottom: 1px solid var(--border);
+      white-space: nowrap;
+    }
+    td {
+      padding: 11px 12px;
+      border-bottom: 1px solid var(--border);
+      vertical-align: middle;
+    }
+    tr:hover td { background: var(--row-hover); }
+    .hash-full {
+      word-break: break-all;
+      color: var(--text-secondary);
+      font-size: 11px;
+    }
+    .signer-key-header {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+    .action-link {
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 10.5px;
+      font-weight: 600;
+      color: var(--text-secondary);
+      text-decoration: none;
+      padding: 4px 8px;
+      border: 1px solid var(--border-strong);
+      background: var(--bg);
+      white-space: nowrap;
+    }
+    .action-link:hover {
+      border-color: var(--amber);
+      color: var(--amber);
+    }
+    .tx-link {
+      color: var(--muted);
+      text-decoration: none;
+      font-size: 10.5px;
+      display: inline-block;
+      margin-top: 2px;
+    }
+    .tx-link:hover { color: var(--text); }
+    .empty-cell {
+      text-align: center;
+      color: var(--muted);
+      padding: 24px;
+      font-family: "JetBrains Mono", "SF Mono", Menlo, monospace;
+      font-size: 11.5px;
+    }
+    @media print {
+      body { background: var(--bg) !important; -webkit-print-color-adjust: exact; print-color-adjust: exact; padding: 10px; }
+      .no-print { display: none !important; }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header class="masthead">
+      <div>
+        <div class="eyebrow">REL-TIME SOVEREIGN PROVENANCE PROTOCOL // FORENSIC AUDIT LEDGER</div>
+        <h1>Cryptographic Data Integrity &amp; Timechain Settlement Report</h1>
+        <div class="masthead-meta mono">
+          <span>GENERATED UTC: <strong>${escapeHtml(generatedUtc)}</strong></span>
+          <span>SLA TIER: <strong>${escapeHtml(acct.tier || "Active")}</strong></span>
+          <span>CREDENTIAL: <strong>${escapeHtml(acct.masked_api_key || "rel_key_***")}</strong></span>
+        </div>
+      </div>
+      <div class="actions-bar no-print">
+        <button id="themeToggleBtn" class="btn-secondary" onclick="toggleTheme()">[ ☀ LIGHT MODE ]</button>
+        <a class="btn-secondary" href="https://rel-time.com/verify" target="_blank" rel="noopener">[ OPEN VERIFIER ↗ ]</a>
+        <button class="btn-primary" onclick="window.print()">[ EXPORT PDF CERTIFICATE ]</button>
+      </div>
+    </header>
+
+    <div class="telemetry-strip">
+      <div class="telemetry-cell">
+        <div class="telemetry-label">Audited Scope</div>
+        <div class="telemetry-val">${Number(sum.matched_entries_count || 0).toLocaleString()}</div>
+        <div class="telemetry-sub mono">LIFETIME: ${Number(acct.lifetime_anchors || 0).toLocaleString()}</div>
+      </div>
+      <div class="telemetry-cell">
+        <div class="telemetry-label">Timechain Finality</div>
+        <div class="telemetry-val">${settledCount.toLocaleString()} <span style="font-size:14px;color:var(--muted)">/ ${Number(
+    sum.matched_entries_count || 0
+  )}</span></div>
+        <div class="telemetry-sub mono">${escapeHtml(sum.settlement_rate_pct || "0%")} SETTLED · ${pendingCount} QUEUED</div>
+      </div>
+      <div class="telemetry-cell">
+        <div class="telemetry-label">Bitcoin Blocks</div>
+        <div class="telemetry-val">${Number(btc.unique_blocks_count || 0)}</div>
+        <div class="telemetry-sub mono">${Number(btc.unique_txids_count || 0)} OP_RETURN TXS${
+    btc.latest_settled_block ? ` · #${escapeHtml(btc.latest_settled_block)}` : ""
+  }</div>
+      </div>
+      <div class="telemetry-cell">
+        <div class="telemetry-label">Mode Split</div>
+        <div class="telemetry-val">${standardCount} <span style="font-size:14px;color:var(--muted)">:</span> ${temporalCount}</div>
+        <div class="telemetry-sub mono">STANDARD : TEMPORAL VDF</div>
+      </div>
+      <div class="telemetry-cell">
+        <div class="telemetry-label">Passkey Authorities</div>
+        <div class="telemetry-val">${signers.length}</div>
+        <div class="telemetry-sub mono">${biometricCount} BIOMETRIC SIGNATURES</div>
+      </div>
+      <div class="telemetry-cell">
+        <div class="telemetry-label">Available Fuel</div>
+        <div class="telemetry-val" style="color:var(--amber)">${Number(
+          acct.hash_credits_remaining || 0
+        ).toLocaleString()}</div>
+        <div class="telemetry-sub mono">HASH CREDITS REMAINING</div>
+      </div>
+    </div>
+
+    <div class="viz-grid">
+      <div class="panel">
+        <div class="panel-header" style="margin-bottom:14px;padding-bottom:10px">
+          <div>
+            <div class="section-index">TELEMETRY // DISTRIBUTION METRICS</div>
+            <h2>Pipeline &amp; Attestation Ratios</h2>
+          </div>
+        </div>
+        <div class="dist-row">
+          <div class="dist-header mono">
+            <span>BITCOIN FINALITY (${settledPct}% SETTLED)</span>
+            <span class="muted">${settledCount} SETTLED / ${pendingCount} PENDING</span>
+          </div>
+          <div class="dist-track">
+            <div class="dist-seg-emerald" style="width:${settledPct}%"></div>
+            <div class="dist-seg-amber" style="width:${100 - settledPct}%"></div>
+          </div>
+        </div>
+        <div class="dist-row">
+          <div class="dist-header mono">
+            <span>HASHING ARCHITECTURE (${standardPct}% STANDARD)</span>
+            <span class="muted">${standardCount} INTEGRITY / ${temporalCount} TEMPORAL VDF</span>
+          </div>
+          <div class="dist-track">
+            <div class="dist-seg-primary" style="width:${standardPct}%"></div>
+            <div class="dist-seg-muted" style="width:${100 - standardPct}%"></div>
+          </div>
+        </div>
+        <div class="dist-row">
+          <div class="dist-header mono">
+            <span>HARDWARE PASSKEY ATTESTATION (${biometricPct}%)</span>
+            <span class="muted">${biometricCount} FIDO2 SIGNED / ${machineCount} MACHINE</span>
+          </div>
+          <div class="dist-track">
+            <div class="dist-seg-primary" style="width:${biometricPct}%"></div>
+            <div class="dist-seg-muted" style="width:${100 - biometricPct}%"></div>
+          </div>
+        </div>
+      </div>
+
+      <div class="panel">
+        <div class="panel-header" style="margin-bottom:14px;padding-bottom:10px">
+          <div>
+            <div class="section-index">TIMECHAIN TOPOLOGY // MERKLE BATCH ANCHORS</div>
+            <h2>Bitcoin Block Settlement Sequence</h2>
+          </div>
+          <span class="mono muted" style="font-size:11px">SHA-256 MERKLE ROOT ➔ OP_RETURN</span>
+        </div>
+        <div class="topo-chain">
+          ${
+            topologyNodesHtml ||
+            `<div class="empty-cell" style="width:100%;padding:16px">No settled Bitcoin blocks in current filter window.</div>`
+          }
+        </div>
+      </div>
+    </div>
+
+    ${localVerificationHtml}
+
+    <section class="panel">
+      <div class="panel-header">
+        <div>
+          <div class="section-index">SECTION ${signerSectionNum} // CORPORATE HARDWARE PASSKEY REGISTRY</div>
+          <h2>Authorized WebAuthn / FIDO2 Signer Authorities</h2>
+          <p class="section-sub">Non-exportable Secure Enclave &amp; YubiKey COSE public keys recorded across this corporate credential</p>
+        </div>
+      </div>
+      <div class="table-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th style="width:42px">#</th>
+              <th>Hardware Signer Public Key (COSE Hex)</th>
+              <th style="width:200px">Attested Volume</th>
+              <th style="width:130px">Finality Ratio</th>
+              <th style="width:190px">Latest Attestation (UTC)</th>
+            </tr>
+          </thead>
+          <tbody>
+            ${signerRowsHtml}
+          </tbody>
+        </table>
+      </div>
+    </section>
+
+    <section class="panel">
+      <div class="panel-header">
+        <div>
+          <div class="section-index">SECTION ${ledgerSectionNum} // CHRONOLOGICAL TIMECHAIN LEDGER</div>
+          <h2>Cryptographic Anchor &amp; VDF Sequence Log</h2>
+          <p class="section-sub">Immutable record of SHA-256 payload digests, VDF thermodynamic proofs (T_index), and Bitcoin Merkle settlements</p>
+        </div>
+      </div>
+      <div class="filter-bar no-print">
+        <div class="tab-group">
+          <button class="filter-tab active" onclick="setPill(this, 'all')">All (${entries.length})</button>
+          <button class="filter-tab" onclick="setPill(this, 'status-settled')">Settled (${settledCount})</button>
+          <button class="filter-tab" onclick="setPill(this, 'status-pending')">Pending (${pendingCount})</button>
+          <button class="filter-tab" onclick="setPill(this, 'mode-biometric')">Passkey (${biometricCount})</button>
+          <button class="filter-tab" onclick="setPill(this, 'mode-temporal')">Temporal VDF (${temporalCount})</button>
+          <button class="filter-tab" onclick="setPill(this, 'mode-standard')">Standard (${standardCount})</button>
+        </div>
+        <input id="searchInput" class="search-input" type="text" placeholder="QUERY SHA-256 / T_INDEX / PASSKEY / TXID / BLOCK..." oninput="filterLedger()" />
+      </div>
+      <div class="table-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th style="width:42px">#</th>
+              <th>Timestamp (UTC)</th>
+              <th>Finality</th>
+              <th>Mode / Authority</th>
+              <th>Client / File SHA-256 Digest</th>
+              <th>Thermodynamic Proof (T_Index)</th>
+              <th>Bitcoin Settlement</th>
+              <th style="text-align:right">Proof</th>
+            </tr>
+          </thead>
+          <tbody id="ledgerBody">
+            ${ledgerRowsHtml}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  </div>
+
+  <script>
+    let currentFilter = 'all';
+    function applyTheme(theme) {
+      const root = document.documentElement;
+      const btn = document.getElementById('themeToggleBtn');
+      if (theme === 'light') {
+        root.setAttribute('data-theme', 'light');
+        if (btn) btn.textContent = '[ ☾ DARK MODE ]';
+      } else {
+        root.setAttribute('data-theme', 'dark');
+        if (btn) btn.textContent = '[ ☀ LIGHT MODE ]';
+      }
+      try { localStorage.setItem('reltime_audit_theme', theme); } catch (e) {}
+    }
+    function toggleTheme() {
+      const current = document.documentElement.getAttribute('data-theme') || 'dark';
+      applyTheme(current === 'dark' ? 'light' : 'dark');
+    }
+    (function initTheme() {
+      try {
+        const saved = localStorage.getItem('reltime_audit_theme');
+        if (saved === 'light' || saved === 'dark') applyTheme(saved);
+      } catch (e) {}
+    })();
+    function setPill(btn, filter) {
+      currentFilter = filter;
+      document.querySelectorAll('.filter-tab').forEach(el => el.classList.remove('active'));
+      btn.classList.add('active');
+      filterLedger();
+    }
+    function filterLedger() {
+      const q = (document.getElementById('searchInput').value || '').trim().toLowerCase();
+      document.querySelectorAll('.ledger-row').forEach(row => {
+        const matchesFilter = currentFilter === 'all' || row.classList.contains(currentFilter);
+        const matchesQuery = !q || (row.getAttribute('data-search') || '').includes(q);
+        row.style.display = (matchesFilter && matchesQuery) ? '' : 'none';
+      });
+    }
+  </script>
+</body>
+</html>`;
+}
+
 const TOOLS = [
   {
     name: "reltime_anchor_file",
@@ -685,6 +1735,64 @@ const TOOLS = [
       required: ["action"],
     },
   },
+  {
+    name: "reltime_audit_trail",
+    description:
+      "Superhighway Cryptographic Audit Trail & Local Folder Integrity Verifier (`GET /api/v1/account` + `GET /api/v1/account/history` + local SHA-256 cross-reference). Fetches the account's chronological anchor ledger, aggregates Bitcoin block settlements, VDF `T_index` ticks, and Corporate Hardware Passkey (`signer_public_key`) signatures, optionally verifies a local file or entire folder bit-for-bit against the ledger (`verify_local_path`), and spins up a self-contained interactive HTML Audit Report (`reltime-audit-report-*.html`) in the user's browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        verify_local_path: {
+          type: "string",
+          description:
+            "Optional local file path or folder/directory path to audit bit-for-bit (Zero-Knowledge local SHA-256 + Passkey attestation check + Stamped Copy check) against the Rel-Time Bitcoin ledger.",
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of audit ledger entries to retrieve (default 100, max 500).",
+        },
+        status_filter: {
+          type: "string",
+          enum: ["all", "settled", "pending"],
+          description: "Filter ledger entries by settlement status: 'all' (default), 'settled', or 'pending'.",
+        },
+        mode_filter: {
+          type: "string",
+          enum: ["all", "standard", "temporal", "biometric"],
+          description:
+            "Filter ledger entries by mode: 'all' (default), 'standard', 'temporal' (VDF T_index), or 'biometric' (Hardware Passkey attested).",
+        },
+        signer_filter: {
+          type: "string",
+          description:
+            "Optional full or partial Hardware Passkey `public_key_hex` to filter anchors signed by a specific employee or corporate YubiKey.",
+        },
+        save_html_report: {
+          type: "boolean",
+          description:
+            "If true (default), saves an interactive dark-mode HTML Superhighway Audit Trail dashboard (`reltime-audit-report-<date>.html`).",
+        },
+        open_in_browser: {
+          type: "boolean",
+          description:
+            "If true (default), automatically opens the generated HTML Audit Trail dashboard in the user's browser.",
+        },
+        export_csv: {
+          type: "boolean",
+          description: "If true, also exports the audit ledger to a `.csv` spreadsheet file.",
+        },
+        output_dir: {
+          type: "string",
+          description:
+            "Optional directory where the generated `.html` / `.csv` audit reports should be saved (defaults to `verify_local_path` folder or `~/.reltime/audits`).",
+        },
+        api_key: {
+          type: "string",
+          description: "Optional override for RELTIME_API_KEY.",
+        },
+      },
+    },
+  },
 ];
 
 async function executeTool(name, args = {}) {
@@ -984,6 +2092,405 @@ async function executeTool(name, args = {}) {
     return data;
   }
 
+  if (name === "reltime_audit_trail") {
+    if (!key) {
+      return buildPackSelectionPrompt(
+        "To run a Superhighway Audit Trail, a Rel-Time API key is required. Ask the user which tier and payment method they would like to provision:"
+      );
+    }
+
+    const acctRes = await fetch(`${API_BASE}/account`, {
+      headers: { Authorization: `Bearer ${key}` },
+    });
+    if (!acctRes.ok) {
+      if (acctRes.status === 401 || acctRes.status === 403) {
+        return buildPackSelectionPrompt(
+          "The configured API key was not recognized. Ask the user which tier and payment method they would like to provision:"
+        );
+      }
+      throw new Error(`Rel-Time Account error (${acctRes.status}): ${await acctRes.text()}`);
+    }
+    const acctData = await acctRes.json();
+
+    const maxEntries = Math.min(500, Math.max(1, Number(args.limit) || 100));
+    const pageSize = Math.min(100, maxEntries);
+    const pagesToFetch = Math.ceil(maxEntries / pageSize);
+    let rawHistory = [];
+    let totalInLedger = 0;
+
+    for (let p = 1; p <= pagesToFetch; p++) {
+      const histRes = await fetch(`${API_BASE}/account/history?page=${p}&limit=${pageSize}`, {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!histRes.ok) break;
+      const histJson = await histRes.json();
+      totalInLedger = Number(histJson.total || 0);
+      const batch = Array.isArray(histJson.history) ? histJson.history : [];
+      rawHistory.push(...batch);
+      if (batch.length < pageSize || rawHistory.length >= maxEntries || rawHistory.length >= totalInLedger) {
+        break;
+      }
+    }
+    rawHistory = rawHistory.slice(0, maxEntries);
+
+    const statusFilter = (args.status_filter || "all").toLowerCase();
+    const modeFilter = (args.mode_filter || "all").toLowerCase();
+    const signerFilter = (args.signer_filter || "").trim().toLowerCase();
+
+    const normalizedEntries = rawHistory.map((item) => {
+      const clientHash = (item.client_hash || "").toLowerCase();
+      const tIndex = (item.t_index || "").toLowerCase();
+      const origHash = item.original_file_hash ? item.original_file_hash.toLowerCase() : null;
+      const mode = (item.anchor_mode || "standard").toLowerCase();
+      const lookupHash = mode === "temporal" ? tIndex || clientHash : clientHash;
+      const tsSec = Number(item.timestamp || 0);
+      const tsUtc = tsSec > 0 ? new Date(tsSec * 1000).toISOString() : null;
+      return {
+        timestamp: tsSec,
+        timestamp_utc: tsUtc,
+        status: item.status || "pending_finality",
+        anchor_mode: mode,
+        identity_mode: item.signer_public_key ? "biometric_passkey" : "anonymous",
+        client_hash: clientHash,
+        original_file_hash: origHash,
+        t_index: tIndex,
+        vdf_ticks: Number(item.vdf_ticks || 0),
+        signer_public_key: item.signer_public_key || null,
+        block_height: item.block_height || null,
+        block_time: item.block_time || null,
+        block_time_utc: item.block_time ? new Date(Number(item.block_time) * 1000).toISOString() : null,
+        txid: item.txid || null,
+        merkle_root: item.merkle_root || null,
+        verify_url: `https://rel-time.com/verify?t=${lookupHash}`,
+        sun_stamp_svg_url: `${API_BASE}/stamp/${lookupHash}`,
+      };
+    });
+
+    const filteredEntries = normalizedEntries.filter((e) => {
+      if (statusFilter === "settled" && e.status !== "settled") return false;
+      if (statusFilter === "pending" && e.status === "settled") return false;
+      if (modeFilter === "standard" && e.anchor_mode !== "standard") return false;
+      if (modeFilter === "temporal" && e.anchor_mode !== "temporal") return false;
+      if (modeFilter === "biometric" && !e.signer_public_key) return false;
+      if (signerFilter && !(e.signer_public_key || "").toLowerCase().includes(signerFilter)) return false;
+      return true;
+    });
+
+    // Aggregate KPI & Hardware Passkey Signer statistics
+    let settledCount = 0;
+    let pendingCount = 0;
+    let standardCount = 0;
+    let temporalCount = 0;
+    let biometricCount = 0;
+    const uniqueBlocks = new Set();
+    const uniqueTxids = new Set();
+    let latestBlock = null;
+    let latestTxid = null;
+    const signerMap = new Map();
+
+    for (const e of filteredEntries) {
+      if (e.status === "settled") {
+        settledCount++;
+        if (e.block_height) {
+          uniqueBlocks.add(e.block_height);
+          if (!latestBlock || Number(e.block_height) > Number(latestBlock)) {
+            latestBlock = e.block_height;
+            latestTxid = e.txid || latestTxid;
+          }
+        }
+        if (e.txid) uniqueTxids.add(e.txid);
+      } else {
+        pendingCount++;
+      }
+
+      if (e.anchor_mode === "temporal") temporalCount++;
+      else standardCount++;
+
+      if (e.signer_public_key) {
+        biometricCount++;
+        const pk = e.signer_public_key;
+        const cur = signerMap.get(pk) || {
+          signer_public_key: pk,
+          short_key: `${pk.slice(0, 12)}...${pk.slice(-8)}`,
+          anchor_count: 0,
+          settled_count: 0,
+          latest_timestamp_utc: e.timestamp_utc,
+        };
+        cur.anchor_count++;
+        if (e.status === "settled") cur.settled_count++;
+        if (e.timestamp_utc && (!cur.latest_timestamp_utc || e.timestamp_utc > cur.latest_timestamp_utc)) {
+          cur.latest_timestamp_utc = e.timestamp_utc;
+        }
+        signerMap.set(pk, cur);
+      }
+    }
+
+    // Build fast lookup index of all known hashes in account history + known passkeys
+    const ledgerByHash = new Map();
+    const knownPasskeys = new Set();
+    const localPasskey = loadSavedPasskey();
+    if (localPasskey && localPasskey.public_key_hex) {
+      knownPasskeys.add(localPasskey.public_key_hex);
+    }
+    for (const e of normalizedEntries) {
+      if (e.client_hash) ledgerByHash.set(e.client_hash, e);
+      if (e.t_index) ledgerByHash.set(e.t_index, e);
+      if (e.original_file_hash) ledgerByHash.set(e.original_file_hash, e);
+      if (e.signer_public_key) knownPasskeys.add(e.signer_public_key);
+    }
+
+    // Optional Zero-Knowledge Local File / Folder Integrity Verification
+    let localPathVerification = null;
+    if (args.verify_local_path) {
+      const targetPath = resolveLocalFilePath(args.verify_local_path);
+      if (!fs.existsSync(targetPath)) {
+        throw new Error(`verify_local_path not found: ${targetPath}`);
+      }
+      const stat = fs.statSync(targetPath);
+      let candidateFiles = [];
+      if (stat.isFile()) {
+        candidateFiles.push(targetPath);
+      } else if (stat.isDirectory()) {
+        const dirItems = fs.readdirSync(targetPath);
+        for (const item of dirItems) {
+          if (item.startsWith(".")) continue;
+          if (
+            item.startsWith("reltime-stamp-") ||
+            item.startsWith("reltime-doomsday-proof-") ||
+            item.startsWith("reltime-proof-") ||
+            item.startsWith("reltime-audit-report-")
+          ) {
+            continue;
+          }
+          const fullItemPath = path.join(targetPath, item);
+          try {
+            if (fs.statSync(fullItemPath).isFile()) {
+              candidateFiles.push(fullItemPath);
+            }
+          } catch (e) {
+            // Skip unreadable entry
+          }
+        }
+      }
+
+      const fileAuditResults = [];
+      let vSettled = 0;
+      let vPending = 0;
+      let vUnanchored = 0;
+
+      for (const fPath of candidateFiles) {
+        const buf = fs.readFileSync(fPath);
+        const fName = path.basename(fPath);
+        const rawSha256 = crypto.createHash("sha256").update(buf).digest("hex");
+        const embeddedHash = extractStampedCopyEmbeddedHash(fPath, buf);
+        const isStampedCopy = Boolean(embeddedHash) || fName.startsWith("reltime-stamped-");
+
+        let matchedEntry =
+          ledgerByHash.get(rawSha256) || (embeddedHash ? ledgerByHash.get(embeddedHash) : null) || null;
+
+        // Also check biometric attested hashes SHA-256(rawSha256 + passkey_hex)
+        if (!matchedEntry) {
+          for (const pkHex of knownPasskeys) {
+            const attestedCandidate = crypto
+              .createHash("sha256")
+              .update(`${rawSha256}${pkHex}`, "utf8")
+              .digest("hex");
+            if (ledgerByHash.has(attestedCandidate)) {
+              matchedEntry = ledgerByHash.get(attestedCandidate);
+              break;
+            }
+          }
+        }
+
+        // Fallback: query live GET /v1/proof/{hash} in case it was anchored outside the recent history window
+        const probeHash = embeddedHash || rawSha256;
+        if (!matchedEntry) {
+          try {
+            const proofRes = await fetch(`${API_BASE}/proof/${probeHash}`);
+            if (proofRes.ok) {
+              const proofData = await proofRes.json();
+              const s = proofData.settlement || {};
+              matchedEntry = {
+                status: proofData.status || "settled",
+                anchor_mode: proofData.anchor_mode || "standard",
+                client_hash: proofData.client_hash || probeHash,
+                t_index: proofData.t_index || probeHash,
+                signer_public_key: proofData.signer_public_key || null,
+                block_height: s.bitcoin_block_height || s.block_height || null,
+                txid: s.bitcoin_txid || null,
+                merkle_root: s.merkle_root || null,
+                verify_url: `https://rel-time.com/verify?t=${probeHash}`,
+              };
+            }
+          } catch (e) {
+            // Ignore network error during fallback lookup
+          }
+        }
+
+        let integrityStatus = "UNANCHORED_OR_MODIFIED";
+        if (matchedEntry) {
+          if (matchedEntry.status === "settled") {
+            integrityStatus = "VERIFIED_SETTLED";
+            vSettled++;
+          } else {
+            integrityStatus = "VERIFIED_PENDING";
+            vPending++;
+          }
+        } else {
+          vUnanchored++;
+        }
+
+        const bytes = buf.length;
+        const sizeHuman =
+          bytes >= 1048576
+            ? `${(bytes / 1048576).toFixed(2)} MB`
+            : bytes >= 1024
+            ? `${(bytes / 1024).toFixed(1)} KB`
+            : `${bytes} B`;
+
+        fileAuditResults.push({
+          file_name: fName,
+          file_path: fPath,
+          size_bytes: bytes,
+          size_human: sizeHuman,
+          local_sha256: embeddedHash || rawSha256,
+          raw_file_sha256: rawSha256,
+          embedded_stamp_hash: embeddedHash,
+          is_stamped_copy: isStampedCopy,
+          integrity_status: integrityStatus,
+          anchor_mode: matchedEntry ? matchedEntry.anchor_mode : null,
+          signer_public_key: matchedEntry ? matchedEntry.signer_public_key : null,
+          t_index: matchedEntry ? matchedEntry.t_index : null,
+          block_height: matchedEntry ? matchedEntry.block_height : null,
+          txid: matchedEntry ? matchedEntry.txid : null,
+          verify_url: matchedEntry ? matchedEntry.verify_url : null,
+        });
+      }
+
+      localPathVerification = {
+        target_path: targetPath,
+        summary: {
+          total_files_scanned: fileAuditResults.length,
+          verified_settled_count: vSettled,
+          verified_pending_count: vPending,
+          unanchored_or_modified_count: vUnanchored,
+          overall_integrity: vUnanchored === 0 ? "ALL_FILES_VERIFIED" : "ATTENTION_UNANCHORED_OR_MODIFIED_FILES",
+        },
+        files: fileAuditResults,
+      };
+    }
+
+    const maskedKey = key.length > 16 ? `${key.slice(0, 14)}…${key.slice(-4)}` : "rel_key_***";
+    const settlementRatePct =
+      filteredEntries.length > 0 ? `${Math.round((settledCount / filteredEntries.length) * 100)}%` : "0%";
+
+    const auditPayload = {
+      status: "audit_complete",
+      generated_at_utc: new Date().toISOString(),
+      account_overview: {
+        tier: acctData.tier || "Active",
+        hash_credits_remaining: Number(acctData.hash_credits || 0),
+        lifetime_anchors: Number(acctData.total_usage || totalInLedger || 0),
+        masked_api_key: maskedKey,
+      },
+      audit_summary: {
+        total_ledger_entries: totalInLedger,
+        matched_entries_count: filteredEntries.length,
+        settled_on_bitcoin_count: settledCount,
+        pending_finality_count: pendingCount,
+        settlement_rate_pct: settlementRatePct,
+        mode_breakdown: {
+          standard_count: standardCount,
+          temporal_vdf_count: temporalCount,
+          biometric_passkey_count: biometricCount,
+        },
+        bitcoin_settlement: {
+          unique_blocks_count: uniqueBlocks.size,
+          unique_txids_count: uniqueTxids.size,
+          latest_settled_block: latestBlock,
+          latest_txid: latestTxid,
+        },
+        hardware_passkey_signers: Array.from(signerMap.values()),
+      },
+      local_path_verification: localPathVerification,
+      audit_trail: filteredEntries,
+    };
+
+    // Determine output directory for reports
+    let reportDir = path.join(PASSKEY_CONFIG_DIR, "audits");
+    if (args.output_dir) {
+      reportDir = resolveLocalFilePath(args.output_dir);
+    } else if (localPathVerification) {
+      const tp = localPathVerification.target_path;
+      reportDir = fs.statSync(tp).isDirectory() ? tp : path.dirname(tp);
+    }
+    if (!fs.existsSync(reportDir)) {
+      fs.mkdirSync(reportDir, { recursive: true });
+    }
+
+    const dateStamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const savedReports = {};
+
+    if (args.save_html_report !== false) {
+      const htmlPath = path.join(reportDir, `reltime-audit-report-${dateStamp}.html`);
+      const htmlContent = generateAuditReportHtml(auditPayload);
+      fs.writeFileSync(htmlPath, htmlContent, "utf8");
+      savedReports.html_report_path = htmlPath;
+
+      if (args.open_in_browser !== false) {
+        try {
+          openSystemBrowser(htmlPath);
+          savedReports.opened_in_browser = true;
+        } catch (e) {
+          savedReports.opened_in_browser = false;
+        }
+      }
+    }
+
+    if (args.export_csv) {
+      const csvPath = path.join(reportDir, `reltime-audit-trail-${dateStamp}.csv`);
+      const csvHeader = [
+        "timestamp_utc",
+        "status",
+        "anchor_mode",
+        "identity_mode",
+        "client_hash",
+        "original_file_hash",
+        "t_index",
+        "vdf_ticks",
+        "signer_public_key",
+        "bitcoin_block_height",
+        "bitcoin_txid",
+        "merkle_root",
+        "verify_url",
+      ].join(",");
+      const csvRows = filteredEntries.map((e) =>
+        [
+          e.timestamp_utc || "",
+          e.status || "",
+          e.anchor_mode || "",
+          e.identity_mode || "",
+          e.client_hash || "",
+          e.original_file_hash || "",
+          e.t_index || "",
+          e.vdf_ticks || 0,
+          e.signer_public_key || "",
+          e.block_height || "",
+          e.txid || "",
+          e.merkle_root || "",
+          e.verify_url || "",
+        ]
+          .map((v) => `"${String(v).replace(/"/g, '""')}"`)
+          .join(",")
+      );
+      fs.writeFileSync(csvPath, [csvHeader, ...csvRows].join("\n"), "utf8");
+      savedReports.csv_report_path = csvPath;
+    }
+
+    auditPayload.saved_reports = savedReports;
+    return auditPayload;
+  }
+
   if (name === "reltime_provision_agent_key") {
     if (args.action === "create_invoice") {
       const validPacks = ["universal", "launch", "standard", "enterprise", "superhighway"];