web-agent-bridge 3.3.0 → 3.4.0

package/public/js/dns.js

@@ -0,0 +1,438 @@
+// ═══════════ Bilingual toggle ═══════════
+window.setLang = function (lang) {
+  const isAr = lang === 'ar';
+  document.documentElement.lang = isAr ? 'ar' : 'en';
+  document.documentElement.dir = isAr ? 'rtl' : 'ltr';
+  const enBtn = document.getElementById('enBtn');
+  const arBtn = document.getElementById('arBtn');
+  if (enBtn) enBtn.classList.toggle('active', !isAr);
+  if (arBtn) arBtn.classList.toggle('active', isAr);
+  document.querySelectorAll('[data-en]').forEach((el) => {
+    el.textContent = isAr ? (el.getAttribute('data-ar') || el.textContent) : (el.getAttribute('data-en') || el.textContent);
+  });
+};
+
+// ═══════════ Live DoH Verifier ═══════════
+window.verifyDns = async function () {
+  const domain = (document.getElementById('dnsDomain').value || '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  const resolver = document.getElementById('dnsResolver').value;
+  const status = document.getElementById('dnsStatus');
+  const out = document.getElementById('dnsOut');
+  if (!domain) {
+    status.innerHTML = '<span class="danger">Please enter a domain.</span>';
+    return;
+  }
+  const fqdn = '_wab.' + domain;
+  status.innerHTML = '<span class="warn">Querying ' + fqdn + ' …</span>';
+  out.textContent = '';
+  try {
+    const url = resolver + '?name=' + encodeURIComponent(fqdn) + '&type=TXT';
+    const res = await fetch(url, { headers: { accept: 'application/dns-json' } });
+    const data = await res.json();
+    out.textContent = JSON.stringify(data, null, 2);
+    const answers = (data.Answer || []).filter((a) => a.type === 16);
+    if (!answers.length) {
+      status.innerHTML = '<span class="danger">No _wab TXT record found for <b>' + domain + '</b>. The domain has not enabled WAB DNS Discovery (yet).</span>';
+      return;
+    }
+    const value = answers.map((a) => (a.data || '').replace(/^"|"$/g, '').replace(/" "/g, '')).join(' ');
+    const versionMatch = /v=([^;\s]+)/.exec(value);
+    const endpointMatch = /endpoint=([^;\s]+)/.exec(value);
+    if (versionMatch && endpointMatch && versionMatch[1].startsWith('wab')) {
+      status.innerHTML = '<span class="ok">✓ Valid WAB record found. Version: <b>' + versionMatch[1] + '</b> · Endpoint: <a href="' + endpointMatch[1] + '" target="_blank" style="color:#7dd3fc">' + endpointMatch[1] + '</a></span>';
+    } else {
+      status.innerHTML = '<span class="warn">TXT record found but it does not match the WAB format (v=wab1; endpoint=…).</span>';
+    }
+  } catch (err) {
+    status.innerHTML = '<span class="danger">Lookup failed: ' + ((err && err.message) || err) + '</span>';
+  }
+};
+
+window.copyExample = function () {
+  const txt = 'v=wab1; endpoint=https://yourdomain.com/.well-known/wab.json';
+  navigator.clipboard.writeText(txt).then(() => {
+    const s = document.getElementById('dnsStatus');
+    s.innerHTML = '<span class="ok">✓ Example record copied to clipboard.</span>';
+  });
+};
+
+function _statePill(label, ok) {
+  return '<span style="display:inline-block;margin:3px 6px 3px 0;padding:4px 9px;border-radius:999px;font-size:.74rem;border:1px solid ' +
+    (ok ? 'rgba(74,222,128,.5);color:#4ade80;background:rgba(74,222,128,.12)' : 'rgba(248,113,113,.4);color:#f87171;background:rgba(248,113,113,.1)') +
+    '">' + label + '</span>';
+}
+
+function renderProof(data) {
+  const status = document.getElementById('proofStatus');
+  const out = document.getElementById('proofOut');
+  const txt = document.getElementById('proofTxt');
+  const wab = document.getElementById('proofWabJson');
+  const use = document.getElementById('useCaseValue');
+  const badges = document.getElementById('stateBadges');
+  const discoverPathBadge = document.getElementById('proofDiscoverPathBadge');
+  const usageKpi = document.getElementById('usageKpiValue');
+  if (!status || !out || !txt || !wab || !use || !badges) return;
+
+  const states = data.statuses || {};
+  badges.innerHTML = [
+    _statePill('Registered', states.registered === 'yes'),
+    _statePill('DNS Verified', states.dns_verified === 'yes'),
+    _statePill('Agent-Ready', states.agent_ready === 'yes'),
+    _statePill('Production', states.production === 'yes'),
+  ].join('');
+
+  const rawTxt = ((data.dns && data.dns.records) || [])[0] || '—';
+  txt.textContent = rawTxt;
+  const wabUrl = data.wab_json && data.wab_json.url;
+  wab.innerHTML = wabUrl ? ('<a href="' + wabUrl + '" target="_blank" style="color:#7dd3fc">' + wabUrl + '</a>') : '—';
+  use.textContent = (data.wab_json && data.wab_json.use_case) || '—';
+  out.textContent = JSON.stringify(data, null, 2);
+
+  const agentOk = data.execution_proof && data.execution_proof.ok;
+  const coreOk = data.dns && data.dns.ok && data.wab_json && data.wab_json.ok;
+
+  if (discoverPathBadge) {
+    const discoverStep = data.execution_proof && data.execution_proof.steps
+      ? data.execution_proof.steps.find((s) => s.key === 'agent_discover_call')
+      : null;
+    const detail = discoverStep && typeof discoverStep.detail === 'string' ? discoverStep.detail : '';
+    const usedFallback = detail.includes('fallback /agent-bridge.json succeeded');
+    const usedPrimary = detail.includes('GET /api/wab/discover succeeded');
+
+    if (usedFallback) {
+      discoverPathBadge.style.display = 'block';
+      discoverPathBadge.innerHTML = '<span style="display:inline-block;padding:4px 10px;border-radius:999px;background:rgba(250,204,21,.15);border:1px solid rgba(250,204,21,.45);color:#fde68a;font-size:.78rem;font-weight:700;letter-spacing:.03em">Fallback Used: /agent-bridge.json</span>';
+    } else if (usedPrimary) {
+      discoverPathBadge.style.display = 'block';
+      discoverPathBadge.innerHTML = '<span style="display:inline-block;padding:4px 10px;border-radius:999px;background:rgba(34,197,94,.15);border:1px solid rgba(34,197,94,.45);color:#86efac;font-size:.78rem;font-weight:700;letter-spacing:.03em">Primary Path: /api/wab/discover</span>';
+    } else if (discoverStep && discoverStep.ok === false) {
+      const detailText = detail ? (' — ' + detail.replace(/"/g, '&quot;')) : '';
+      discoverPathBadge.style.display = 'block';
+      discoverPathBadge.innerHTML = '<span style="display:inline-block;padding:4px 10px;border-radius:999px;background:rgba(239,68,68,.15);border:1px solid rgba(239,68,68,.45);color:#fca5a5;font-size:.78rem;font-weight:700;letter-spacing:.03em" title="' + detail.replace(/"/g, '&quot;') + '">Discovery Path Failed' + detailText + '</span>';
+    } else {
+      discoverPathBadge.style.display = 'none';
+      discoverPathBadge.innerHTML = '';
+    }
+  }
+
+  status.innerHTML = '<span class="' + ((agentOk || coreOk) ? 'ok' : 'danger') + '">' +
+    ((agentOk || coreOk)
+      ? '✓ Verifiable proof ready.'
+      : '✗ Verification incomplete. Check DNS record, endpoint, and agent flow.') +
+    '</span>';
+
+  if (usageKpi) {
+    if (data && data.kpi) {
+      usageKpi.textContent =
+        'value_score=' + (data.kpi.value_score != null ? data.kpi.value_score : '—') +
+        ' · actions=' + (data.kpi.discovered_actions_count != null ? data.kpi.discovered_actions_count : '—') +
+        ' · business_cmds=' + (data.kpi.business_commands_count != null ? data.kpi.business_commands_count : '—') +
+        ' · e2e_ms=' + (data.kpi.end_to_end_ms != null ? data.kpi.end_to_end_ms : '—');
+    } else {
+      usageKpi.textContent = '—';
+    }
+  }
+}
+
+window.verifyLiveProof = async function () {
+  const domain = (document.getElementById('dnsDomain').value || '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  const status = document.getElementById('proofStatus');
+  if (!status) return;
+  if (!domain) {
+    status.innerHTML = '<span class="danger">Please enter a domain.</span>';
+    return;
+  }
+  status.innerHTML = '<span class="warn">Running live verification…</span>';
+  try {
+    const res = await fetch('/api/discovery/verify-live?domain=' + encodeURIComponent(domain));
+    const data = await res.json();
+    renderProof(data);
+  } catch (err) {
+    status.innerHTML = '<span class="danger">Verification failed: ' + ((err && err.message) || err) + '</span>';
+  }
+};
+
+window.testWithAgent = async function () {
+  const domain = (document.getElementById('dnsDomain').value || '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  const status = document.getElementById('proofStatus');
+  if (!status) return;
+  if (!domain) {
+    status.innerHTML = '<span class="danger">Please enter a domain.</span>';
+    return;
+  }
+  status.innerHTML = '<span class="warn">Running agent flow (discover → ping)…</span>';
+  try {
+    const res = await fetch('/api/discovery/test-agent?domain=' + encodeURIComponent(domain));
+    const data = await res.json();
+    renderProof(data);
+  } catch (err) {
+    status.innerHTML = '<span class="danger">Agent test failed: ' + ((err && err.message) || err) + '</span>';
+  }
+};
+
+window.runUsageProof = async function () {
+  const domain = (document.getElementById('dnsDomain').value || '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  const apiKey = (document.getElementById('dnsUsageApiKey') && document.getElementById('dnsUsageApiKey').value || '').trim();
+  const preferredUseCase = (document.getElementById('dnsUsageUseCase') && document.getElementById('dnsUsageUseCase').value || '').trim();
+  const status = document.getElementById('proofStatus');
+  if (!status) return;
+  if (!domain) {
+    status.innerHTML = '<span class="danger">Please enter a domain.</span>';
+    return;
+  }
+  status.innerHTML = '<span class="warn">Running usage proof (' + (apiKey ? 'real execution' : 'readiness only') + ')…</span>';
+  try {
+    const res = await fetch('/api/discovery/usage-proof', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({
+        domain,
+        api_key: apiKey,
+        preferred_use_case: preferredUseCase || undefined,
+      }),
+    });
+    const data = await res.json();
+    renderProof(data);
+    if (data && data.usage_proof) {
+      const ok = data.usage_proof.ok || data.usage_proof.readiness_ok;
+      status.innerHTML = '<span class="' + (ok ? 'ok' : 'danger') + '">' +
+        (data.usage_proof.detail || (ok ? 'Usage proof completed.' : 'Usage proof failed.')) +
+      '</span>';
+    }
+    loadUsageTrend(domain).catch(() => {});
+  } catch (err) {
+    status.innerHTML = '<span class="danger">Usage proof failed: ' + ((err && err.message) || err) + '</span>';
+  }
+};
+
+async function loadUsageTrend(domain) {
+  const summary = document.getElementById('usageTrendSummary');
+  const list = document.getElementById('usageTrendList');
+  if (!summary || !list) return;
+
+  const cleanDomain = (domain || '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  if (!cleanDomain) {
+    summary.textContent = 'Enter a domain to load usage trend.';
+    list.textContent = '—';
+    return;
+  }
+
+  summary.textContent = 'Loading usage trend…';
+  list.textContent = '';
+
+  try {
+    const res = await fetch('/api/discovery/usage-proof-runs?domain=' + encodeURIComponent(cleanDomain) + '&limit=20');
+    const data = await res.json();
+    const runs = Array.isArray(data && data.runs) ? data.runs : [];
+
+    if (!runs.length) {
+      summary.textContent = 'No usage proof runs yet for this domain.';
+      list.textContent = 'Run Usage Proof to start collecting trend data.';
+      return;
+    }
+
+    const avgScore = Math.round(runs.reduce((acc, r) => acc + Number(r.value_score || 0), 0) / runs.length);
+    const execSuccessCount = runs.filter((r) => r.execution_succeeded).length;
+    const readinessCount = runs.filter((r) => r.readiness_ok).length;
+    summary.textContent = 'runs=' + runs.length + ' · avg_score=' + avgScore + ' · readiness_ok=' + readinessCount + ' · execution_ok=' + execSuccessCount;
+
+    list.innerHTML = runs.slice(0, 20).map((r) => {
+      const state = r.execution_succeeded ? 'exec-ok' : (r.readiness_ok ? 'ready' : 'fail');
+      const action = r.selected_action || '—';
+      const t = r.created_at || 'unknown-time';
+      return '<div>[' + state + '] score=' + Number(r.value_score || 0) + ' · action=' + escapeHtml(action) + ' · ms=' + (r.end_to_end_ms != null ? r.end_to_end_ms : '—') + ' · ' + escapeHtml(t) + '</div>';
+    }).join('');
+  } catch (err) {
+    summary.textContent = 'Failed to load usage trend.';
+    list.textContent = ((err && err.message) || err);
+  }
+}
+
+window.toggleAdvanced = function () {
+  const blocks = document.querySelectorAll('.advanced-block');
+  blocks.forEach((el) => {
+    el.style.display = (el.style.display === 'none' || !el.style.display) ? 'block' : 'none';
+  });
+};
+
+// ═══════════ Canonical records — live status ═══════════
+const RR_TYPE = { TXT: 16, CAA: 257, A: 1, AAAA: 28, CNAME: 5 };
+
+function _decodeCAARdata(hex) {
+  try {
+    const bytes = hex.replace(/\\#\s*\d+\s*/, '').replace(/\s+/g, '');
+    const buf = bytes.match(/.{1,2}/g).map((b) => parseInt(b, 16));
+    const tagLen = buf[1];
+    let tag = '';
+    let val = '';
+    for (let i = 0; i < tagLen; i++) tag += String.fromCharCode(buf[2 + i]);
+    for (let i = 2 + tagLen; i < buf.length; i++) val += String.fromCharCode(buf[i]);
+    return { tag, value: val };
+  } catch {
+    return null;
+  }
+}
+
+function _normalizeAnswer(answer, type) {
+  const data = answer.data || '';
+  if (type === 'CAA') {
+    const decoded = _decodeCAARdata(data);
+    if (decoded) return decoded.tag + ' ' + decoded.value;
+    return data;
+  }
+  return data.replace(/^"|"$/g, '').replace(/"\s*"/g, '');
+}
+
+async function _doh(name, type) {
+  const url = 'https://cloudflare-dns.com/dns-query?name=' +
+    encodeURIComponent(name) + '&type=' + encodeURIComponent(type) + '&do=1';
+  const res = await fetch(url, { headers: { accept: 'application/dns-json' } });
+  const data = await res.json();
+  const want = RR_TYPE[type];
+  const answers = (data.Answer || []).filter((a) => a.type === want)
+    .map((a) => _normalizeAnswer(a, type));
+  Object.defineProperty(answers, '_ad', { value: !!data.AD, enumerable: false });
+  return answers;
+}
+
+async function checkDnssecForWab() {
+  const el = document.getElementById('dnssecLiveStatus');
+  const rowState = document.getElementById('dnssecRowState');
+  if (!el) return;
+  try {
+    const ans = await _doh('_wab.webagentbridge.com', 'TXT');
+    if (ans._ad) {
+      el.className = 'ok';
+      el.textContent = '✓ DNSSEC validated (AD=1) at resolver';
+      if (rowState) {
+        rowState.className = 'ok';
+        rowState.textContent = '✓ DNSSEC validated';
+      }
+    } else {
+      el.className = 'warn';
+      el.textContent = '⚠ DNSSEC not yet enabled on this zone (AD=0). Roadmap: enable DS at registrar.';
+    }
+  } catch {
+    el.className = 'warn';
+    el.textContent = '… could not verify (DoH unreachable)';
+  }
+}
+
+async function checkCanonicalRecords() {
+  const rows = document.querySelectorAll('#recordsTable tr[data-record]');
+  const summary = document.getElementById('recordsLiveStatus');
+  let pass = 0;
+  let fail = 0;
+  const tasks = Array.from(rows).map(async (row) => {
+    const cell = row.querySelector('.live-cell');
+    const name = row.dataset.record;
+    const type = row.dataset.rtype;
+    const match = row.dataset.match;
+    try {
+      const answers = await _doh(name, type);
+      const hit = answers.some((a) => a.toLowerCase().includes(match.toLowerCase()));
+      if (hit) {
+        cell.innerHTML = '<span class="ok" title="Verified live via Cloudflare DoH">✓ live</span>';
+        pass++;
+      } else {
+        cell.innerHTML = '<span class="danger" title="Record not yet propagated or missing">✗ missing</span>';
+        fail++;
+      }
+    } catch {
+      cell.innerHTML = '<span class="warn" title="Lookup failed">… error</span>';
+    }
+  });
+  await Promise.allSettled(tasks);
+  const total = pass + fail;
+  summary.innerHTML = '<span class="' + (fail === 0 ? 'ok' : 'warn') + '">' +
+    (fail === 0
+      ? '✓ All ' + total + ' canonical records verified live (Cloudflare DoH).'
+      : '⚠ ' + pass + '/' + total + ' records live — ' + fail + ' missing or propagating.') + '</span>';
+}
+
+async function loadLiveAdoption() {
+  const status = document.getElementById('liveAdoptionStatus');
+  const list = document.getElementById('liveAdoptionList');
+  if (!status || !list) return;
+
+  status.innerHTML = '<span class="warn">Loading live registry…</span>';
+  list.style.display = 'none';
+  list.innerHTML = '';
+
+  try {
+    const res = await fetch('/api/discovery/registry?limit=24');
+    const data = await res.json();
+    const entries = Array.isArray(data && data.listings) ? data.listings : [];
+
+    if (!entries.length) {
+      status.innerHTML = '<span class="warn">No businesses are currently listed. New registrations will appear here automatically.</span>';
+      return;
+    }
+
+    const cards = entries.map((entry) => {
+      const safeName = escapeHtml(entry.name || entry.domain || 'Unnamed site');
+      const safeDomain = escapeHtml(entry.domain || '');
+      const safeDescription = escapeHtml(entry.description || 'WAB-enabled website');
+      const safeCategory = escapeHtml(entry.category || 'general');
+      const score = Number.isFinite(Number(entry.neutrality_score)) ? Number(entry.neutrality_score) : 0;
+
+      return '<article class="live-item">' +
+        '<h4>' + safeName + '</h4>' +
+        '<p>' + safeDescription + '</p>' +
+        '<div class="live-meta">' + safeDomain + ' · ' + safeCategory + ' · score ' + score + '</div>' +
+      '</article>';
+    }).join('');
+
+    list.innerHTML = cards;
+    list.style.display = 'grid';
+    status.innerHTML = '<span class="ok">✓ Live list loaded from real registrations.</span>';
+  } catch (err) {
+    status.innerHTML = '<span class="danger">Failed to load live registry: ' + ((err && err.message) || err) + '</span>';
+  }
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function bindHandlers() {
+  const enBtn = document.getElementById('enBtn');
+  const arBtn = document.getElementById('arBtn');
+  const verifyBtn = document.getElementById('dnsVerifyBtn');
+  const copyBtn = document.getElementById('dnsCopyBtn');
+  const advancedBtn = document.getElementById('dnsAdvancedToggleBtn');
+  const proofVerifyBtn = document.getElementById('dnsProofVerifyBtn');
+  const proofAgentBtn = document.getElementById('dnsProofAgentBtn');
+  const usageProofBtn = document.getElementById('dnsUsageProofBtn');
+
+  if (enBtn) enBtn.addEventListener('click', () => window.setLang('en'));
+  if (arBtn) arBtn.addEventListener('click', () => window.setLang('ar'));
+  if (verifyBtn) verifyBtn.addEventListener('click', () => window.verifyDns());
+  if (copyBtn) copyBtn.addEventListener('click', () => window.copyExample());
+  if (advancedBtn) advancedBtn.addEventListener('click', () => window.toggleAdvanced());
+  if (proofVerifyBtn) proofVerifyBtn.addEventListener('click', () => window.verifyLiveProof());
+  if (proofAgentBtn) proofAgentBtn.addEventListener('click', () => window.testWithAgent());
+  if (usageProofBtn) usageProofBtn.addEventListener('click', () => window.runUsageProof());
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  bindHandlers();
+  checkCanonicalRecords().catch(() => {});
+  checkDnssecForWab().catch(() => {});
+  loadLiveAdoption().catch(() => {});
+  const initDomain = (document.getElementById('dnsDomain') && document.getElementById('dnsDomain').value || '').trim();
+  loadUsageTrend(initDomain).catch(() => {});
+  const navbar = document.getElementById('navbar');
+  window.addEventListener('scroll', () => {
+    if (!navbar) return;
+    navbar.style.background = window.scrollY > 50
+      ? 'rgba(7, 13, 25, 0.92)'
+      : 'rgba(7, 13, 25, 0.78)';
+  });
+});
+

package/public/openapi.json

@@ -26,6 +26,7 @@
   ],
   "tags": [
     {"name": "Discovery", "description": "WAB Discovery Protocol endpoints"},
+    {"name": "Provider", "description": "DNS provider and registrar integration APIs"},
     {"name": "WAB Protocol", "description": "Core WAB command protocol over HTTP"},
     {"name": "Registry", "description": "Public directory of WAB-enabled sites"},
     {"name": "Plans", "description": "Subscription plan information"},
@@ -348,6 +349,94 @@
         }
       }
     },
+    "/api/discovery/provider/manifest": {
+      "get": {
+        "tags": ["Provider"],
+        "summary": "Provider protocol manifest",
+        "description": "Machine-readable contract for DNS providers and registrars implementing one-click WAB DNS Discovery.",
+        "operationId": "providerManifest",
+        "responses": {
+          "200": {"description": "Provider manifest"}
+        }
+      }
+    },
+    "/api/discovery/provider/record-template": {
+      "get": {
+        "tags": ["Provider"],
+        "summary": "Build record template",
+        "description": "Returns ready-to-write TXT record payload for a specific domain.",
+        "operationId": "providerRecordTemplate",
+        "parameters": [
+          {"name": "domain", "in": "query", "required": true, "schema": {"type": "string"}},
+          {"name": "endpoint", "in": "query", "required": false, "schema": {"type": "string"}}
+        ],
+        "responses": {
+          "200": {"description": "Record template payload"},
+          "400": {"description": "Invalid domain or endpoint"}
+        }
+      }
+    },
+    "/api/discovery/provider/enable-plan": {
+      "get": {
+        "tags": ["Provider"],
+        "summary": "Get one-click enable/disable plan",
+        "description": "Returns an implementation playbook with DNS operation, verify polling, and rollback hints.",
+        "operationId": "providerEnablePlan",
+        "parameters": [
+          {"name": "domain", "in": "query", "required": true, "schema": {"type": "string"}},
+          {"name": "action", "in": "query", "required": false, "schema": {"type": "string", "enum": ["enable", "disable"], "default": "enable"}},
+          {"name": "endpoint", "in": "query", "required": false, "schema": {"type": "string"}}
+        ],
+        "responses": {
+          "200": {"description": "Enable/disable execution plan"},
+          "400": {"description": "Invalid request"}
+        }
+      }
+    },
+    "/api/discovery/provider/status": {
+      "get": {
+        "tags": ["Provider"],
+        "summary": "Provider status check",
+        "description": "Returns machine-friendly state for UI toggles: enabled, partial, or disabled.",
+        "operationId": "providerStatus",
+        "parameters": [
+          {"name": "domain", "in": "query", "required": true, "schema": {"type": "string"}}
+        ],
+        "responses": {
+          "200": {"description": "Current provider status"},
+          "400": {"description": "Domain required"}
+        }
+      }
+    },
+    "/api/discovery/provider/verify-batch": {
+      "post": {
+        "tags": ["Provider"],
+        "summary": "Batch verify domains",
+        "description": "Verifies up to 50 domains in one request and optionally sends callback webhook with results.",
+        "operationId": "providerVerifyBatch",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["domains"],
+                "properties": {
+                  "domains": {"type": "array", "items": {"type": "string"}, "maxItems": 50},
+                  "include_agent_run": {"type": "boolean", "default": false},
+                  "callback_url": {"type": "string", "format": "uri"},
+                  "callback_secret": {"type": "string"}
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {"description": "Batch verification results"},
+          "400": {"description": "Invalid request"}
+        }
+      }
+    },
     "/api/plans": {
       "get": {
         "tags": ["Plans"],