web-agent-bridge 3.16.0 → 3.20.0

package/public/docs.html

@@ -41,80 +41,150 @@
       <!-- Sidebar -->
       <aside class="docs-sidebar">
         <ul>
+          <li style="opacity:.6;font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;padding:8px 0 4px;">Protocol</li>
           <li><a href="#overview" class="active">Overview</a></li>
-          <li><a href="#quick-start">Quick Start</a></li>
-          <li><a href="#configuration">Configuration</a></li>
+          <li><a href="#quick-start">Quick Start (modern)</a></li>
+          <li><a href="#wab-json">wab.json manifest</a></li>
+          <li><a href="#dns-discovery">DNS discovery</a></li>
+          <li><a href="/spec">Full Spec ↗</a></li>
+
+          <li style="opacity:.6;font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;padding:14px 0 4px;">Trust &amp; Security</li>
+          <li><a href="/security">Security model ↗</a></li>
+          <li><a href="/threat-model">Threat model ↗</a></li>
+          <li><a href="/responsible-disclosure">Responsible disclosure ↗</a></li>
+          <li><a href="/key-rotation">Key rotation ↗</a></li>
+
+          <li style="opacity:.6;font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;padding:14px 0 4px;">ATP (Transactions)</li>
+          <li><a href="/atp">ATP overview ↗</a></li>
+          <li><a href="/atp-semantics">Consistency model ↗</a></li>
+          <li><a href="/benchmarks">Benchmarks ↗</a></li>
+
+          <li style="opacity:.6;font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;padding:14px 0 4px;">API</li>
           <li><a href="#permissions">Permissions</a></li>
-          <li><a href="#api-reference">API Reference</a></li>
-          <li><a href="#actions">Actions</a></li>
-          <li><a href="#events">Events</a></li>
-          <li><a href="#agent-guide">Agent Integration Guide</a></li>
-          <li><a href="#security">Security</a></li>
-          <li><a href="#examples">Examples</a></li>
+          <li><a href="#api-reference">Browser API</a></li>
           <li><a href="#rest-api">REST API</a></li>
           <li><a href="#faq">FAQ</a></li>
+
+          <li style="opacity:.6;font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;padding:14px 0 4px;">Legacy (v1)</li>
+          <li><a href="#legacy-config">window.AIBridgeConfig</a></li>
+          <li><a href="#examples">Legacy examples</a></li>
         </ul>
       </aside>
 
       <!-- Content -->
       <div class="docs-content">
 
+        <div style="background:rgba(99,102,241,.08);border:1px solid rgba(99,102,241,.3);border-radius:12px;padding:14px 20px;margin:0 0 28px;display:flex;align-items:center;gap:12px;flex-wrap:wrap;">
+          <span style="font-size:1.3rem">📐</span>
+          <div>
+            <strong>New to WAB?</strong> These docs assume familiarity with the current protocol.
+            For a plain-English map of all six architectural layers and how WAB evolved from a browser script to a
+            full infrastructure layer, start with <a href="/wab-today" style="color:#818cf8;font-weight:600">WAB Today →</a>
+          </div>
+        </div>
+
         <h2 id="overview">Overview</h2>
         <p>
-          <strong>Web Agent Bridge (WAB)</strong> is an open-source middleware script that creates a standardized 
-          interface between AI agents and websites. Instead of forcing AI agents to parse and guess DOM structures, 
-          WAB provides a clean, documented command layer that agents can read and execute.
+          <strong>Web Agent Bridge (WAB)</strong> is an open protocol for discovery, trust, and transactions
+          between AI agents and websites. Sites publish a signed <code>wab.json</code> manifest declaring what
+          agents can do; agents discover it via DNS (<code>_wab.&lt;domain&gt;</code> TXT) or HTTPS; every action and
+          receipt is cryptographically verifiable (Ed25519).
         </p>
         <p>
-          When a website includes the WAB script, it exposes a <code>window.AICommands</code> object that describes 
-          all available actions, their parameters, and how to execute them. AI agents can discover these commands 
-          instantly and interact with the site accurately and securely.
+          WAB replaces guesswork (DOM scraping, brittle selectors, vision models) with a contract:
+          <em>scoped, rate-limited, idempotent, and auditable</em>. The browser SDK (<code>wab.min.js</code>) and the
+          original <code>window.AICommands</code> surface remain available for backward compatibility — see the
+          <a href="#legacy-config">Legacy section</a>.
         </p>
 
-        <h3>Key Concepts</h3>
+        <h3>The four layers</h3>
         <ul>
-          <li><strong>Bridge Script</strong> — The client-side JavaScript file added to websites</li>
-          <li><strong>Actions</strong> — Defined operations that AI agents can execute (click, fill, scroll, API call)</li>
-          <li><strong>Permissions</strong> — Granular controls over what agents are allowed to do</li>
-          <li><strong>License Key</strong> — Unique identifier that links a site to its WAB account</li>
-          <li><strong>Auto-Discovery</strong> — Automatic detection of interactive elements on the page</li>
+          <li><strong>Discovery</strong> — DNS TXT (<code>_wab.&lt;domain&gt;</code>) or <code>/.well-known/wab.json</code>.</li>
+          <li><strong>Manifest</strong> — <code>wab.json</code>: capabilities, scopes, public key, version.</li>
+          <li><strong>Trust</strong> — Ed25519 signatures, Ring 4 trust graph, replay protection, key rotation.</li>
+          <li><strong>Transactions (ATP)</strong> — signed intent contracts, idempotent execution, verifiable receipts. See <a href="/atp">/atp</a>.</li>
         </ul>
 
+        <div style="background:rgba(34,211,238,.07);border:1px solid rgba(34,211,238,.25);border-radius:12px;padding:14px 18px;margin:18px 0;">
+          <strong style="color:#22d3ee">📘 Looking for the full spec?</strong> The normative protocol
+          definition lives in <a href="/spec">/spec</a>. For the trust + security architecture, see
+          <a href="/security">/security</a> and <a href="/threat-model">/threat-model</a>.
+        </div>
+
         <h2 id="quick-start">Quick Start</h2>
-        <p>Get your website AI-ready in under 5 minutes.</p>
+        <p>Make your site discoverable and signed in three steps.</p>
 
-        <h3>Step 1: Create an Account</h3>
-        <p>Sign up at <a href="/register">/register</a> and add your site from the dashboard. You'll receive a license key.</p>
+        <h3>Step 1 — Initialize</h3>
+        <p>From your project root:</p>
+        <div class="code-block">
+          <div class="code-header">
+            <div class="code-dots"><span></span><span></span><span></span></div>
+            <span class="code-lang">bash</span>
+          </div>
+          <div class="code-body">
+<pre><code><span class="cm"># Generates wab.json + Ed25519 key pair, prints DNS TXT to publish</span>
+npx wab-init --site=https://yourdomain.com --yes</code></pre>
+          </div>
+        </div>
 
-        <h3>Step 2: Add the Script</h3>
-        <p>Include this in your website's HTML:</p>
+        <h3 id="wab-json">Step 2 — Publish <code>wab.json</code></h3>
+        <p>Host the generated manifest at <code>https://yourdomain.com/.well-known/wab.json</code>:</p>
         <div class="code-block">
           <div class="code-header">
             <div class="code-dots"><span></span><span></span><span></span></div>
-            <span class="code-lang">HTML</span>
+            <span class="code-lang">JSON — /.well-known/wab.json</span>
           </div>
           <div class="code-body">
-<pre><code><span class="cm">&lt;!-- Web Agent Bridge Configuration --&gt;</span>
-&lt;script&gt;
-window.AIBridgeConfig = {
-  <span class="prop">licenseKey</span>: <span class="str">"WAB-XXXXX-XXXXX-XXXXX-XXXXX"</span>,
-  <span class="prop">agentPermissions</span>: {
-    <span class="prop">readContent</span>: <span class="bool">true</span>,
-    <span class="prop">click</span>: <span class="bool">true</span>,
-    <span class="prop">fillForms</span>: <span class="bool">true</span>,
-    <span class="prop">scroll</span>: <span class="bool">true</span>
-  }
-};
-&lt;/script&gt;
-&lt;script src=<span class="str">"https://yourserver.com/script/ai-agent-bridge.js"</span>&gt;&lt;/script&gt;</code></pre>
+<pre><code>{
+  <span class="prop">"schema_version"</span>: <span class="str">"wab/1"</span>,
+  <span class="prop">"site"</span>: <span class="str">"https://yourdomain.com"</span>,
+  <span class="prop">"public_key"</span>: <span class="str">"ed25519:BASE64..."</span>,
+  <span class="prop">"capabilities"</span>: [
+    { <span class="prop">"name"</span>: <span class="str">"search"</span>, <span class="prop">"scope"</span>: <span class="str">"public"</span> },
+    { <span class="prop">"name"</span>: <span class="str">"cart.add"</span>, <span class="prop">"scope"</span>: <span class="str">"user"</span>, <span class="prop">"requires"</span>: [<span class="str">"atp:intent"</span>] }
+  ],
+  <span class="prop">"endpoints"</span>: {
+    <span class="prop">"atp"</span>: <span class="str">"https://yourdomain.com/api/atp"</span>
+  },
+  <span class="prop">"signature"</span>: <span class="str">"ed25519:BASE64..."</span>
+}</code></pre>
+          </div>
+        </div>
+
+        <h3 id="dns-discovery">Step 3 — Publish the DNS record</h3>
+        <p>Add a single TXT record so agents can discover you without scraping HTML:</p>
+        <div class="code-block">
+          <div class="code-header">
+            <div class="code-dots"><span></span><span></span><span></span></div>
+            <span class="code-lang">DNS — _wab.yourdomain.com</span>
+          </div>
+          <div class="code-body">
+<pre><code>_wab.yourdomain.com.  TXT  <span class="str">"v=wab1; pk=ed25519:BASE64...; url=https://yourdomain.com/.well-known/wab.json"</span></code></pre>
+          </div>
+        </div>
+
+        <p>That's it. Any WAB-aware agent can now discover, verify, and transact with your site.
+          Add the optional browser SDK for in-page hints:</p>
+        <div class="code-block">
+          <div class="code-header">
+            <div class="code-dots"><span></span><span></span><span></span></div>
+            <span class="code-lang">HTML — optional in-page bridge</span>
+          </div>
+          <div class="code-body">
+<pre><code>&lt;script src=<span class="str">"https://cdn.webagentbridge.com/wab.min.js"</span>&gt;&lt;/script&gt;</code></pre>
           </div>
         </div>
 
-        <h3>Step 3: Verify</h3>
-        <p>Open your browser console and type <code>window.AICommands</code>. You should see the bridge object with discovered actions.</p>
+        <h2 id="legacy-config">Legacy (v1) configuration</h2>
+        <div style="background:rgba(245,158,11,.08);border:1px solid rgba(245,158,11,.35);border-radius:12px;padding:14px 18px;margin:18px 0;">
+          <strong style="color:#fbbf24">⚠️ Legacy surface — backward compatible.</strong> The sections below
+          document the original v1 <code>window.AIBridgeConfig</code> object and license-key model. They remain
+          supported but are <em>not</em> the recommended path for new integrations. New work should use the
+          <code>wab.json</code> manifest + Ed25519 model documented above.
+        </div>
 
-        <h2 id="configuration">Configuration</h2>
-        <p>The bridge is configured through the <code>window.AIBridgeConfig</code> object, which must be set before loading the script.</p>
+        <h3 id="configuration">Configuration (legacy)</h3>
+        <p>The legacy bridge is configured through the <code>window.AIBridgeConfig</code> object, which must be set before loading the script.</p>
 
         <div class="code-block">
           <div class="code-header">

package/public/index.html

@@ -78,6 +78,7 @@
         <li class="nav-dropdown">
           <button class="nav-trigger" type="button" aria-haspopup="true" aria-expanded="false">Developers <span class="nav-caret" aria-hidden="true">▾</span></button>
           <div class="nav-menu" role="menu">
+            <a href="/wab-today" role="menuitem"><strong>📐 WAB Today</strong><span>Architecture &amp; identity map</span></a>
             <a href="/api" role="menuitem"><strong>API Reference</strong><span>OpenAPI 3.0</span></a>
             <a href="/whitepaper" role="menuitem"><strong>Whitepaper</strong><span>Protocol &amp; design</span></a>
             <a href="/integrations" role="menuitem"><strong>Integrations</strong><span>WordPress · Shopify · Next.js</span></a>
@@ -85,6 +86,14 @@
             <a href="/milestones" role="menuitem"><strong>🏆 Milestones</strong><span>Release history</span></a>
             <a href="#latest-additions" role="menuitem"><strong>What's New</strong><span>Latest additions</span></a>
             <a href="/growth" role="menuitem"><strong>Growth Suite</strong><span>Site-owner tools</span></a>
+            <a href="/wab-registry" role="menuitem"><strong>🌐 Spider Registry</strong><span>WAB-enabled sites network</span></a>
+            <a href="/wab-dataset" role="menuitem"><strong>📊 Training Dataset</strong><span>HuggingFace agent traces</span></a>
+            <a href="/viral-coefficient" role="menuitem"><strong>📈 Viral Coefficient</strong><span>Self-propagating network math</span></a>
+            <a href="/observatory" role="menuitem"><strong>🔭 Observatory</strong><span>WAB adoption tracker</span></a>
+            <a href="/notary" role="menuitem"><strong>✍️ Notary</strong><span>Ed25519 attestation</span></a>
+            <a href="/threat-model" role="menuitem"><strong>🛡️ Threat Model</strong><span>Adversary model &amp; trust boundaries</span></a>
+            <a href="/atp-semantics" role="menuitem"><strong>⚙️ ATP Semantics</strong><span>Consistency &amp; delivery guarantees</span></a>
+            <a href="/benchmarks" role="menuitem"><strong>📊 Benchmarks</strong><span>Latency, throughput &amp; baselines</span></a>
           </div>
         </li>
       </ul>
@@ -124,18 +133,20 @@
           <a href="/workspace" class="btn btn-secondary btn-lg" style="background:linear-gradient(135deg,#f59e0b,#ef4444);color:#fff;border:none">🤖 Agent Workspace</a>
           <a href="/demo" class="btn btn-secondary btn-lg" style="background:linear-gradient(135deg,#10b981,#059669);color:#fff;border:none">🧪 API Playground</a>
           <a href="/demo" class="btn btn-secondary btn-lg" style="background:linear-gradient(135deg,#06b6d4,#0ea5e9);color:#fff;border:none">🎮 Interactive Demo</a>
+          <a href="/viral-coefficient" class="btn btn-secondary btn-lg" style="background:linear-gradient(135deg,#a855f7,#6366f1);color:#fff;border:none">📈 Viral Coefficient <sup style="background:#10b981;color:#000;padding:2px 6px;border-radius:6px;font-size:0.55em;margin-left:6px;">NEW</sup></a>
+          <a href="/wab-dataset" class="btn btn-secondary btn-lg" style="background:linear-gradient(135deg,#f59e0b,#ef4444);color:#fff;border:none">📊 Agent Training Dataset <sup style="background:#10b981;color:#000;padding:2px 6px;border-radius:6px;font-size:0.55em;margin-left:6px;">NEW</sup></a>
         </div>
 
         <div class="hero-code fade-in fade-in-delay-2">
           <code>
-            <span class="comment">// Add the bridge to your website</span><br>
-            &lt;<span class="keyword">script</span>&gt;<br>
-            &nbsp;&nbsp;window.<span class="property">AIBridgeConfig</span> = {<br>
-            &nbsp;&nbsp;&nbsp;&nbsp;<span class="property">licenseKey</span>: <span class="string">"WAB-XXXXX-XXXXX"</span>,<br>
-            &nbsp;&nbsp;&nbsp;&nbsp;<span class="property">agentPermissions</span>: { <span class="property">click</span>: <span class="boolean">true</span>, <span class="property">fillForms</span>: <span class="boolean">true</span> }<br>
-            &nbsp;&nbsp;};<br>
-            &lt;/<span class="keyword">script</span>&gt;<br>
-            &lt;<span class="keyword">script</span> <span class="property">src</span>=<span class="string">"/script/ai-agent-bridge.js"</span>&gt;&lt;/<span class="keyword">script</span>&gt;
+            <span class="comment"># 1. Initialize — generates wab.json + Ed25519 keypair</span><br>
+            $ npx wab-init --site=https://yourdomain.com --yes<br>
+            <br>
+            <span class="comment"># 2. Publish DNS so agents can discover &amp; verify you</span><br>
+            _wab.yourdomain.com.&nbsp;&nbsp;<span class="keyword">TXT</span>&nbsp;&nbsp;<span class="string">"v=wab1; pk=ed25519:...; url=/.well-known/wab.json"</span><br>
+            <br>
+            <span class="comment"># 3. (optional) In-page bridge for SDK integrations</span><br>
+            &lt;<span class="keyword">script</span> <span class="property">src</span>=<span class="string">"https://cdn.webagentbridge.com/wab.min.js"</span>&gt;&lt;/<span class="keyword">script</span>&gt;
           </code>
         </div>
       </div>
@@ -1219,6 +1230,121 @@ console.<span class="fn">log</span>(actions);
     </div>
   </section>
 
+  <!-- ═══════════ SELF-PROPAGATING PROTOCOL (Phase 9) ═══════════ -->
+  <section class="section" id="self-propagating" style="background:linear-gradient(180deg,rgba(99,102,241,0.07),rgba(16,185,129,0.04));">
+    <div class="container">
+      <div class="section-header">
+        <span class="label" style="color:#a855f7">🧬 v3.20.0 — Zero Human Intervention</span>
+        <h2>WAB <span style="background:linear-gradient(135deg,#a855f7,#3fb950);-webkit-background-clip:text;-webkit-text-fill-color:transparent">Self-Propagating Protocol</span></h2>
+        <p>Once installed on a single site, the network grows by itself — through Beacons, Gossip, DNA headers, and AI Training Signals. No human needed after the first install.</p>
+      </div>
+
+      <!-- propagation chain visual -->
+      <div style="display:flex;align-items:center;justify-content:center;gap:0;flex-wrap:wrap;margin-bottom:40px;font-size:.82rem;font-weight:600;">
+        <div style="background:#1c2128;border:1px solid #30363d;border-radius:8px;padding:10px 16px;text-align:center;">Human installs WAB<br><span style="color:#8b949e;font-weight:400">once</span></div>
+        <div style="color:#a855f7;font-size:1.4rem;padding:0 6px">→</div>
+        <div style="background:#1a2a4a;border:1px solid #264a8e;border-radius:8px;padding:10px 16px;text-align:center;color:#58a6ff">/.wab Beacon<br><span style="color:#8b949e;font-weight:400">next[] peer list</span></div>
+        <div style="color:#a855f7;font-size:1.4rem;padding:0 6px">→</div>
+        <div style="background:#1a3a2a;border:1px solid #2a6a3a;border-radius:8px;padding:10px 16px;text-align:center;color:#3fb950">Gossip Exchange<br><span style="color:#8b949e;font-weight:400">peers propagate</span></div>
+        <div style="color:#a855f7;font-size:1.4rem;padding:0 6px">→</div>
+        <div style="background:#2a2015;border:1px solid #5a4020;border-radius:8px;padding:10px 16px;text-align:center;color:#f0883e">DNA Headers<br><span style="color:#8b949e;font-weight:400">X-WAB-Next-Sites</span></div>
+        <div style="color:#a855f7;font-size:1.4rem;padding:0 6px">→</div>
+        <div style="background:#1a2a4a;border:1px solid #264a8e;border-radius:8px;padding:10px 16px;text-align:center;color:#58a6ff">Training Dataset<br><span style="color:#8b949e;font-weight:400">HuggingFace JSONL</span></div>
+        <div style="color:#a855f7;font-size:1.4rem;padding:0 6px">→</div>
+        <div style="background:#1a1a3a;border:1px solid #4a3a8a;border-radius:8px;padding:10px 16px;text-align:center;color:#bc8cff">k &gt; 1<br><span style="color:#8b949e;font-weight:400">exponential growth</span></div>
+      </div>
+
+      <div class="grid-3">
+
+        <div class="card fade-in" style="border-left:3px solid #3fb950;background:linear-gradient(180deg,rgba(63,185,80,0.07),transparent);">
+          <div class="card-icon green">🌐</div>
+          <h3>Spider Registry &amp; Gossip Protocol <span style="background:#3fb950;color:#000;padding:2px 8px;border-radius:6px;font-size:0.6em;vertical-align:middle;margin-left:6px;">v3.20</span></h3>
+          <p>AI agents report WAB-enabled sites they discover while browsing. Each report includes a <code>gossip_peers[]</code> list — the server merges new domains and returns its own peer list, creating a bidirectional propagation chain. Every node knows every other node.</p>
+          <ul style="margin-top:10px;font-size:.85rem;color:var(--text-secondary);list-style:disc;padding-left:20px;">
+            <li><strong>POST /api/registry/report</strong> + gossip_peers[]</li>
+            <li><strong>GET /api/registry/gossip</strong> — seed your peer list</li>
+            <li>Registry grows without human action</li>
+            <li>BitTorrent-style DHT for WAB sites</li>
+          </ul>
+          <div style="margin-top:14px;display:flex;gap:10px;flex-wrap:wrap;">
+            <a href="/wab-registry" class="btn btn-primary btn-sm" style="background:linear-gradient(135deg,#3fb950,#0ea5e9);border:none;">Open Registry</a>
+            <a href="/api/registry/gossip" class="btn btn-secondary btn-sm">Gossip API</a>
+            <a href="/api/registry/stats" class="btn btn-secondary btn-sm">Live Stats</a>
+          </div>
+        </div>
+
+        <div class="card fade-in fade-in-delay-1" style="border-left:3px solid #f59e0b;background:linear-gradient(180deg,rgba(245,158,11,0.07),transparent);">
+          <div class="card-icon orange">📊</div>
+          <h3>Agent Training Dataset <span style="background:#f59e0b;color:#000;padding:2px 8px;border-radius:6px;font-size:0.6em;vertical-align:middle;margin-left:6px;">v3.20</span></h3>
+          <p>Every agent interaction — success or failure — is recorded as a public JSONL dataset on HuggingFace. The data proves empirically that WAB sites produce dramatically better outcomes. Future AI models fine-tune on this data and <strong>prefer WAB by default</strong>.</p>
+          <ul style="margin-top:10px;font-size:.85rem;color:var(--text-secondary);list-style:disc;padding-left:20px;">
+            <li>WAB: <strong>100% success</strong>, 1.2s median latency</li>
+            <li>Non-WAB: <strong>0% success</strong>, 8.4s, 3 retries</li>
+            <li>7× speed advantage in first 2 traces</li>
+            <li>CC-BY-4.0 · no PII · real-time JSONL</li>
+          </ul>
+          <div style="margin-top:14px;display:flex;gap:10px;flex-wrap:wrap;">
+            <a href="/wab-dataset" class="btn btn-primary btn-sm" style="background:linear-gradient(135deg,#f59e0b,#ef4444);border:none;">Open Dataset Page</a>
+            <a href="/api/traces/dataset" class="btn btn-secondary btn-sm">Download JSONL</a>
+            <a href="/api/traces/stats" class="btn btn-secondary btn-sm">Live Stats</a>
+          </div>
+        </div>
+
+        <div class="card fade-in fade-in-delay-2" style="border-left:3px solid #a855f7;background:linear-gradient(180deg,rgba(168,85,247,0.07),transparent);">
+          <div class="card-icon purple">📈</div>
+          <h3>Viral Coefficient — k-Factor <span style="background:#a855f7;color:#fff;padding:2px 8px;border-radius:6px;font-size:0.6em;vertical-align:middle;margin-left:6px;">v3.20</span></h3>
+          <p>Live mathematical model of the WAB Spider Network spread. Tracks k-factor (gossip-sourced / manually-seeded sites). When <strong>k &gt; 1</strong>, the network is self-sustaining. When <strong>k &gt; 2</strong>, it's exponential. Includes interactive simulator with sliders.</p>
+          <ul style="margin-top:10px;font-size:.85rem;color:var(--text-secondary);list-style:disc;padding-left:20px;">
+            <li>Live k-factor from registry + traces</li>
+            <li>Canvas growth simulator (seed × k^n)</li>
+            <li>Critical mass progress bar (target: 1,000 sites)</li>
+            <li>Per-source breakdown: gossip / spider / manual</li>
+          </ul>
+          <div style="margin-top:14px;display:flex;gap:10px;flex-wrap:wrap;">
+            <a href="/viral-coefficient" class="btn btn-primary btn-sm" style="background:linear-gradient(135deg,#a855f7,#6366f1);border:none;">Open Model</a>
+            <a href="/api/traces/viral" class="btn btn-secondary btn-sm">Viral API</a>
+          </div>
+        </div>
+
+        <div class="card fade-in" style="border-left:3px solid #58a6ff;">
+          <div class="card-icon blue">🧬</div>
+          <h3>WAB DNA — Every HTTP Response</h3>
+          <p>The <code>X-WAB-Next-Sites</code> header is now emitted on <strong>every single HTTP response</strong> from this server — carrying the top 5 WAB-enabled sites from the registry. Any agent reading HTTP headers learns the network topology passively, with zero interaction.</p>
+          <div style="margin-top:8px;background:#0d1117;border:1px solid #30363d;border-radius:6px;padding:10px 14px;font-family:monospace;font-size:.78rem;line-height:1.8;">
+            <span style="color:#8b949e">HTTP/1.1 200 OK</span><br>
+            <span style="color:#58a6ff">X-WAB-Enabled:</span> <span style="color:#3fb950">true</span><br>
+            <span style="color:#58a6ff">X-WAB-Next-Sites:</span> <span style="color:#f0883e">takeyourappointment.com, …</span>
+          </div>
+          <div style="margin-top:14px;">
+            <a href="/api/registry/gossip" class="btn btn-secondary btn-sm">See Live Peer List</a>
+          </div>
+        </div>
+
+        <div class="card fade-in fade-in-delay-1" style="border-left:3px solid #06b6d4;">
+          <div class="card-icon cyan">🔭</div>
+          <h3>Observatory, Notary &amp; Research</h3>
+          <p>Three interconnected tools for the WAB ecosystem: track WAB adoption across the web, issue Ed25519 Notary attestations with key rotation &amp; web-of-trust, and access a public CC-BY-4.0 research dataset.</p>
+          <div style="margin-top:14px;display:flex;gap:10px;flex-wrap:wrap;">
+            <a href="/observatory" class="btn btn-primary btn-sm">🔭 Observatory</a>
+            <a href="/notary" class="btn btn-secondary btn-sm">✍️ Notary</a>
+            <a href="/research" class="btn btn-secondary btn-sm">📚 Research</a>
+          </div>
+        </div>
+
+        <div class="card fade-in fade-in-delay-2" style="border-left:3px solid #ec4899;">
+          <div class="card-icon pink">🔍</div>
+          <h3>WAB Lens — Browser Extension</h3>
+          <p>Chrome/Edge/Brave MV3 extension. Shows a green checkmark badge on every WAB-verified site. Auto-discovers <code>/.well-known/wab.json</code>, links to Notary attestation, and optionally reports to the Observatory.</p>
+          <div style="margin-top:14px;display:flex;gap:10px;flex-wrap:wrap;">
+            <a href="/wab-lens" class="btn btn-primary btn-sm">Get Lens</a>
+            <a href="/downloads/wab-lens-extension.zip" class="btn btn-secondary btn-sm">Download .zip</a>
+          </div>
+        </div>
+
+      </div>
+    </div>
+  </section>
+
   <!-- ═══════════ LIVE DNS ADOPTION ═══════════ -->
   <section class="section" id="live-dns-adoption">
     <div class="container">
@@ -1292,6 +1418,14 @@ console.<span class="fn">log</span>(actions);
             <li><a href="https://github.com/abokenan444/web-agent-bridge" target="_blank" rel="noopener">GitHub</a></li>
           </ul>
         </div>
+        <div class="footer-col">
+          <h4>Security</h4>
+          <ul>
+            <li><a href="/security">Security Model</a></li>
+            <li><a href="/responsible-disclosure">Responsible Disclosure</a></li>
+            <li><a href="/researchers">Security Researchers</a></li>
+          </ul>
+        </div>
         <div class="footer-col">
           <h4>Legal</h4>
           <ul>

package/public/key-rotation.html

@@ -0,0 +1,184 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Key Rotation &amp; Emergency Revocation — Web Agent Bridge</title>
+<meta name="description" content="How WAB site keys and the Ring 4 trust anchor are rotated, including emergency revocation, grace windows, and audit semantics.">
+<link rel="canonical" href="https://webagentbridge.com/key-rotation">
+<link rel="preload" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" as="style" onload="this.onload=null;this.rel='stylesheet'">
+<link rel="stylesheet" href="/css/styles.css?v=3.0.1">
+<style>
+  .trust-page { max-width: 980px; margin: 0 auto; padding: 48px 24px 80px; }
+  .trust-page h1 { font-size: clamp(1.9rem, 4vw, 2.6rem); margin: 0 0 10px; }
+  .trust-page .lead { color: #94a3b8; font-size: 1.1rem; max-width: 760px; }
+  .trust-page h2 { margin-top: 48px; border-bottom: 1px solid #1f2937; padding-bottom: 8px; }
+  .trust-page h3 { margin-top: 28px; }
+  .trust-page table { width: 100%; border-collapse: collapse; margin: 16px 0; background: #10172a; border: 1px solid #1f2937; border-radius: 10px; overflow: hidden; }
+  .trust-page th, .trust-page td { padding: 12px 16px; text-align: left; border-bottom: 1px solid #1f2937; vertical-align: top; }
+  .trust-page th { background: #0d1322; color: #94a3b8; font-weight: 600; font-size: 0.85rem; text-transform: uppercase; letter-spacing: 0.05em; }
+  .trust-page code { background: rgba(34,211,238,.08); padding: 2px 6px; border-radius: 4px; font-family: 'JetBrains Mono', monospace; }
+  .trust-page pre { background: #0d1322; border: 1px solid #1f2937; border-radius: 10px; padding: 16px; overflow-x: auto; font-family: 'JetBrains Mono', monospace; font-size: 0.88rem; line-height: 1.55; }
+  .callout { background: rgba(34,211,238,.07); border: 1px solid rgba(34,211,238,.25); border-radius: 12px; padding: 14px 18px; margin: 18px 0; }
+  .callout.warn { background: rgba(245,158,11,.08); border-color: rgba(245,158,11,.35); }
+  .callout.danger { background: rgba(248,113,113,.08); border-color: rgba(248,113,113,.35); }
+  .timeline { border-left: 2px solid #22d3ee; margin: 24px 0; padding-left: 20px; }
+  .timeline .step { margin-bottom: 18px; }
+  .timeline .step strong { color: #22d3ee; }
+</style>
+</head>
+<body>
+
+<nav class="navbar">
+  <div class="container">
+    <a href="/" class="navbar-brand"><div class="brand-icon">⚡</div><span>WAB</span></a>
+    <ul class="navbar-links">
+      <li><a href="/docs">Docs</a></li>
+      <li><a href="/security">Security</a></li>
+      <li><a href="/threat-model">Threat Model</a></li>
+      <li><a href="/key-rotation" style="color:#f0f4ff;">Key Rotation</a></li>
+    </ul>
+    <div class="navbar-actions">
+      <a href="/login" class="btn btn-ghost">Sign In</a>
+      <a href="/register" class="btn btn-primary btn-sm">Get Started</a>
+    </div>
+  </div>
+</nav>
+
+<main class="trust-page">
+
+  <h1>Key Rotation &amp; Emergency Revocation</h1>
+  <p class="lead">
+    WAB key material is rotatable by design. This page documents the routine rotation procedure, the
+    emergency revocation procedure, and how downstream agents reconcile a rotation event.
+  </p>
+
+  <h2 id="kinds">1. Key kinds</h2>
+  <table>
+    <thead><tr><th>Key</th><th>Owner</th><th>Used for</th><th>Routine cadence</th></tr></thead>
+    <tbody>
+      <tr><td>Site Ed25519</td><td>Site operator</td><td>Signing <code>wab.json</code>, ATP receipts, intents</td><td>Recommended every 365 d</td></tr>
+      <tr><td>Site key-signing key (optional)</td><td>Site operator</td><td>Co-signing rotations of the Ed25519 key (anti-lockout)</td><td>3–5 years</td></tr>
+      <tr><td>Ring 4 anchor key</td><td>webagentbridge.com</td><td>Trust-graph attestations</td><td>Annual, scheduled</td></tr>
+      <tr><td>Webhook secret (HMAC)</td><td>Site operator</td><td>Stripe-style webhook auth</td><td>Per integration; rotate on suspicion</td></tr>
+    </tbody>
+  </table>
+
+  <h2 id="routine">2. Routine site-key rotation</h2>
+  <div class="timeline">
+    <div class="step">
+      <strong>T-7 days</strong> — Announce next-key. The site publishes <code>next_public_key</code> inside the current <code>wab.json</code>, co-signed by the existing key.
+    </div>
+    <div class="step">
+      <strong>T-0</strong> — Cutover. The site replaces <code>public_key</code> with the previously announced <code>next_public_key</code>, signs the new manifest with the new key, and lists the old key under <code>previous_keys</code> with a <code>valid_until</code> timestamp.
+    </div>
+    <div class="step">
+      <strong>T+30 days</strong> — Grace expires. Receipts signed by the old key after <code>valid_until</code> are rejected by compliant agents.
+    </div>
+    <div class="step">
+      <strong>T+90 days</strong> — Old key drops out of the manifest. Historical receipts remain verifiable from archived manifest snapshots.
+    </div>
+  </div>
+
+  <h3>Example manifest during a routine rotation</h3>
+  <pre><code>{
+  "schema_version": "wab/1",
+  "site": "https://yourdomain.com",
+  "public_key": "ed25519:NEW_KEY_BASE64",
+  "previous_keys": [
+    { "key": "ed25519:OLD_KEY_BASE64", "valid_until": "2026-06-25T00:00:00Z", "reason": "scheduled" }
+  ],
+  "next_public_key": null,
+  "signature": "ed25519:SIG_BY_NEW_KEY"
+}</code></pre>
+
+  <h2 id="emergency">3. Emergency revocation</h2>
+  <div class="callout danger">
+    Use this path when you believe the private key is — or may be — compromised. Speed matters more than ceremony.
+  </div>
+  <ol>
+    <li><strong>Generate a new Ed25519 keypair</strong> on a clean host. Keep the private key offline until publishing.</li>
+    <li><strong>Publish a revocation record</strong> at <code>https://yourdomain.com/.well-known/wab-revocations.json</code>:
+      <pre><code>{
+  "site": "https://yourdomain.com",
+  "revoked": [
+    { "key": "ed25519:COMPROMISED_BASE64", "revoked_at": "2026-05-25T12:00:00Z", "reason": "key_compromise" }
+  ],
+  "new_public_key": "ed25519:NEW_BASE64",
+  "signature_by_new_key": "ed25519:SIG",
+  "signature_by_dns_proof": "see wab.json TXT"
+}</code></pre>
+    </li>
+    <li><strong>Update DNS TXT</strong> at <code>_wab.&lt;domain&gt;</code> with the new public key. DNS propagation determines how quickly off-graph agents pick up the change; we recommend a TTL of 300 s on this record.</li>
+    <li><strong>Replace <code>/.well-known/wab.json</code></strong> with a manifest signed by the new key, listing the compromised key in <code>previous_keys</code> with <code>reason="key_compromise"</code> and <code>valid_until</code> set to the revocation timestamp.</li>
+    <li><strong>Notify Ring 4</strong> via <code>POST /api/trust/revoke</code> (signed by the new key). The trust graph propagates the revocation to attested agents within minutes.</li>
+    <li><strong>Audit receipts</strong> signed by the old key between the suspected compromise window and the revocation timestamp. Anything outside scope or above ambient compensation rate should be reviewed.</li>
+  </ol>
+
+  <h2 id="agent-behavior">4. Agent behavior during/after rotation</h2>
+  <ul>
+    <li>On every discovery refresh (default TTL ≤ 1 h), agents re-fetch <code>wab.json</code> and check <code>previous_keys</code> + <code>/.well-known/wab-revocations.json</code>.</li>
+    <li>Receipts signed by a key listed in <code>previous_keys</code> with <code>reason="key_compromise"</code> are flagged <em>distrusted</em> from <code>revoked_at</code> forward.</li>
+    <li>Receipts signed during the grace window (routine rotation) remain valid.</li>
+    <li>Agents <strong>must</strong> reject manifests whose <code>signature</code> does not validate against <code>public_key</code>, even if cached. No silent downgrade.</li>
+  </ul>
+
+  <h2 id="ring4">5. Ring 4 anchor rotation</h2>
+  <p>
+    The Ring 4 anchor key (held by webagentbridge.com) follows a stricter procedure:
+  </p>
+  <ol>
+    <li>New anchor key is generated and committed in a public transparency log <em>30 days</em> before activation.</li>
+    <li>Cross-signed by the previous anchor for a 90-day overlap.</li>
+    <li>Listed in DNS at <code>_anchor.webagentbridge.com</code> with both the old and new keys during overlap.</li>
+    <li>Old anchor key is retired and listed under <code>previous_anchors</code> with <code>valid_until</code>.</li>
+  </ol>
+  <p>
+    Emergency anchor rotation (compromise of the Ring 4 root) requires a published, signed
+    statement from the foundation, an out-of-band public announcement, and an attested transparency-log
+    entry. Trust scores from before the compromise event are recomputed.
+  </p>
+
+  <h2 id="webhook">6. Webhook secret rotation</h2>
+  <p>
+    Webhook HMAC secrets are rotated by your provider (e.g. Stripe). On the WAB side, support two secrets
+    in parallel for at least 30 days: the operator pastes the new one into the dashboard, requests roll the
+    old one out, and the system tries both during the overlap. Reject anything that matches neither.
+  </p>
+
+  <h2 id="checklist">7. Operator checklist</h2>
+  <ul>
+    <li>☐ Offline backup of the site Ed25519 private key (encrypted, two locations).</li>
+    <li>☐ Key-signing key (optional but recommended) on a separate device.</li>
+    <li>☐ DNS TXT TTL ≤ 300 s for <code>_wab</code> records.</li>
+    <li>☐ Routine rotation calendar entry annually.</li>
+    <li>☐ Runbook for emergency revocation tested at least once per year (table-top is fine).</li>
+    <li>☐ <code>security@</code> contact wired to a human, not a forwarding void.</li>
+  </ul>
+
+  <h2 id="changelog">8. Document history</h2>
+  <ul>
+    <li><strong>2026-05-25</strong> — Initial publication.</li>
+  </ul>
+
+  <p style="margin-top: 48px; color:#94a3b8;">
+    Related: <a href="/security">/security</a> ·
+    <a href="/threat-model">/threat-model</a> ·
+    <a href="/responsible-disclosure">/responsible-disclosure</a>
+  </p>
+
+</main>
+
+<footer class="footer" style="margin-top:32px;">
+  <div class="container">
+    <div class="footer-bottom">
+      <span>© 2026 Web Agent Bridge. Open Core.</span>
+      <a href="/" class="btn btn-ghost btn-sm">Back to Home</a>
+    </div>
+  </div>
+</footer>
+
+<script src="/js/auth-nav.js?v=3.0.1"></script>
+<script src="/js/cookie-consent.js?v=3.0.1"></script>
+</body>
+</html>