web-agent-bridge 3.3.0 → 3.8.1

package/sdk/safe-mode.js

@@ -0,0 +1,221 @@
+/**
+ * WAB Safe Mode — Agent-side trust gate.
+ *
+ * Splits the web into Trusted (WAB + valid signature) vs Untrusted, and
+ * gives the agent a single function to ask before any action:
+ *     await safeMode.evaluate(domain) → { level, verdict, allow_execute,
+ *                                          allow_read, reason }
+ *
+ * Trust levels:
+ *   3 — DNS + Ed25519 signature valid + telemetry score ≥ 60   (full execute)
+ *   2 — DNS + valid wab.json (no signature OR no telemetry)    (limited execute)
+ *   1 — Resolves but no _wab record / score below threshold    (read-only)
+ *   0 — Compliance verdict = deny / suspicious                 (block)
+ *
+ * Usage (Node):
+ *   const { WABSafeMode } = require('web-agent-bridge/sdk');
+ *   const safe = new WABSafeMode({ apiBase: 'https://webagentbridge.com' });
+ *   const v = await safe.evaluate('example.com');
+ *   if (v.allow_execute) await agent.execute(...);
+ *   else if (v.allow_read) await agent.readOnly(...);
+ *   else throw new Error('Blocked by Safe Mode: ' + v.reason);
+ */
+
+'use strict';
+
+const DEFAULT_API = 'https://webagentbridge.com';
+
+const POLICIES = {
+  strict:     { require_dnssec: true,  require_signature: true,  min_score: 75 },
+  standard:   { require_dnssec: false, require_signature: true,  min_score: 60 },
+  permissive: { require_dnssec: false, require_signature: false, min_score: 40 },
+};
+
+class WABSafeMode {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.apiBase='https://webagentbridge.com']
+   * @param {'strict'|'standard'|'permissive'} [opts.policy='standard']
+   * @param {number} [opts.cacheTtlMs=60000]   — verdicts cached this long
+   * @param {number} [opts.timeoutMs=8000]
+   * @param {function} [opts.fetch]            — fetch impl (defaults to global fetch)
+   */
+  constructor(opts = {}) {
+    this.apiBase   = (opts.apiBase || DEFAULT_API).replace(/\/+$/, '');
+    this.policy    = POLICIES[opts.policy] ? opts.policy : 'standard';
+    this.cacheTtl  = Number.isFinite(opts.cacheTtlMs) ? opts.cacheTtlMs : 60_000;
+    this.timeoutMs = Number.isFinite(opts.timeoutMs)  ? opts.timeoutMs  : 8_000;
+    this._fetch    = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+    this._cache    = new Map(); // domain → { at, value }
+    if (!this._fetch) {
+      // Node ≤ 17 fallback
+      try { this._fetch = require('node-fetch'); } catch { /* user must supply */ }
+    }
+  }
+
+  /** Normalises a domain or URL to bare hostname. */
+  static normalizeDomain(input) {
+    if (!input || typeof input !== 'string') return null;
+    let s = input.trim().toLowerCase();
+    s = s.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '');
+    return /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/.test(s) ? s : null;
+  }
+
+  async _get(path) {
+    if (!this._fetch) throw new Error('Safe Mode requires fetch (Node 18+ or pass opts.fetch)');
+    const ctl = (typeof AbortController !== 'undefined') ? new AbortController() : null;
+    const timer = ctl ? setTimeout(() => ctl.abort(), this.timeoutMs) : null;
+    try {
+      const r = await this._fetch(this.apiBase + path, ctl ? { signal: ctl.signal } : {});
+      if (!r.ok) return null;
+      return await r.json();
+    } catch { return null; }
+    finally { if (timer) clearTimeout(timer); }
+  }
+
+  /**
+   * Evaluate a domain and produce a verdict the agent can act on.
+   * @param {string} domain
+   * @param {object} [opts]
+   * @param {boolean} [opts.live=false] — force a live trust check (skip cache).
+   * @returns {Promise<{
+   *   domain: string, level: 0|1|2|3,
+   *   verdict: 'allow'|'restrict'|'deny',
+   *   allow_execute: boolean, allow_read: boolean,
+   *   score: number, score_label: string,
+   *   reason: string, reasons: Array,
+   *   trust: object|null, score_detail: object|null,
+   *   compliance: object|null,
+   *   evaluated_at: string,
+   * }>}
+   */
+  async evaluate(domain, opts = {}) {
+    const d = WABSafeMode.normalizeDomain(domain);
+    if (!d) {
+      return this._verdict(domain, 0, 'deny', 0, 'unrated',
+        'invalid_domain', [{ code: 'invalid_domain', severity: 'deny' }],
+        null, null, null);
+    }
+
+    const cached = this._cache.get(d);
+    if (!opts.live && cached && (Date.now() - cached.at) < this.cacheTtl) return cached.value;
+
+    // Optionally trigger a live trust check first so compliance has fresh data.
+    let trust = null;
+    if (opts.live) {
+      trust = await this._get(`/api/discovery/trust/${encodeURIComponent(d)}`);
+    }
+
+    const [score, compliance] = await Promise.all([
+      this._get(`/api/discovery/score/${encodeURIComponent(d)}`),
+      this._get(`/api/discovery/compliance/${encodeURIComponent(d)}?policy=${this.policy}`),
+    ]);
+
+    // Derive trust level
+    let level = 1;
+    let reasonCode = 'no_signal';
+    if (compliance) {
+      if (compliance.verdict === 'deny') { level = 0; reasonCode = 'compliance_deny'; }
+      else if (compliance.verdict === 'restrict') { level = 1; reasonCode = 'compliance_restrict'; }
+      else { // allow
+        const sigRate = score?.signature_valid_rate ?? compliance.signature_valid_rate ?? 0;
+        const sc = compliance.score ?? score?.score ?? 0;
+        if (sigRate > 0.5 && sc >= 60) { level = 3; reasonCode = 'trusted_full'; }
+        else { level = 2; reasonCode = 'trusted_limited'; }
+      }
+    } else {
+      level = 1;
+      reasonCode = 'no_compliance_record';
+    }
+
+    const verdict = compliance?.verdict || (level === 0 ? 'deny' : level >= 2 ? 'allow' : 'restrict');
+    const value = this._verdict(
+      d, level, verdict,
+      compliance?.score ?? score?.score ?? 0,
+      compliance?.score_label ?? score?.label ?? 'unrated',
+      reasonCode,
+      compliance?.reasons || [],
+      trust, score, compliance,
+    );
+
+    this._cache.set(d, { at: Date.now(), value });
+    return value;
+  }
+
+  _verdict(domain, level, verdict, score, label, reason, reasons, trust, scoreDetail, compliance) {
+    const allow_execute = level >= 2 && verdict === 'allow';
+    const allow_read    = level >= 1 && verdict !== 'deny';
+    return {
+      domain,
+      level,
+      verdict,
+      allow_execute,
+      allow_read,
+      score,
+      score_label: label,
+      reason,
+      reasons,
+      trust,
+      score_detail: scoreDetail,
+      compliance,
+      policy: this.policy,
+      evaluated_at: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Wrap an async action so it only runs if Safe Mode allows execute on the
+   * given domain. Throws WABSafeModeError otherwise.
+   */
+  async guardExecute(domain, action) {
+    const v = await this.evaluate(domain);
+    if (!v.allow_execute) {
+      const err = new WABSafeModeError(
+        `Safe Mode blocked execute on ${v.domain} (level ${v.level}, verdict ${v.verdict}, ${v.reason})`,
+        v,
+      );
+      throw err;
+    }
+    return await action(v);
+  }
+
+  /** Read-only variant: throws only if level === 0. */
+  async guardRead(domain, action) {
+    const v = await this.evaluate(domain);
+    if (!v.allow_read) {
+      throw new WABSafeModeError(
+        `Safe Mode blocked read on ${v.domain} (level ${v.level}, verdict ${v.verdict})`,
+        v,
+      );
+    }
+    return await action(v);
+  }
+
+  /** Picks the highest-trust domain from a candidate list. */
+  async pickBest(domains) {
+    const evals = await Promise.all(
+      (domains || []).map((d) => this.evaluate(d).catch(() => null)),
+    );
+    const sorted = evals.filter(Boolean).sort((a, b) => {
+      if (b.level !== a.level) return b.level - a.level;
+      return (b.score || 0) - (a.score || 0);
+    });
+    return sorted[0] || null;
+  }
+
+  clearCache(domain) {
+    if (domain) this._cache.delete(WABSafeMode.normalizeDomain(domain));
+    else this._cache.clear();
+  }
+}
+
+class WABSafeModeError extends Error {
+  constructor(message, verdict) {
+    super(message);
+    this.name = 'WABSafeModeError';
+    this.code = 'WAB_SAFE_MODE_BLOCKED';
+    this.verdict = verdict;
+  }
+}
+
+module.exports = { WABSafeMode, WABSafeModeError, POLICIES };

package/sdk/safety-shield.js

@@ -1,219 +1,219 @@
-/**
- * WAB Safety-Shield Client Helper (SPEC §8.10–§8.13)
- *
- * Wraps the 2-phase dry-run + human-gate protocol for HTTP API consumers
- * so agents don't have to reimplement plan_id / confirmation_id juggling.
- *
- * Usage:
- *   const { SafetyShieldClient } = require('@webagentbridge/sdk/safety-shield');
- *   const client = new SafetyShieldClient({
- *     baseUrl: 'https://webagentbridge.com',
- *     sessionToken: '<bearer-token>',
- *   });
- *
- *   // Single call — handles dry-run automatically, returns plan for review:
- *   const plan = await client.dryRun('deleteUser', { id: 42 });
- *   console.log(plan.simulation.summary);
- *
- *   // Confirm with the plan_id (and code if human-gate engaged):
- *   const result = await client.confirmAction(plan, { code: '123456' });
- */
-
-'use strict';
-
-const DEFAULT_HEADERS = { 'Content-Type': 'application/json' };
-
-class SafetyShieldClient {
-  /**
-   * @param {object} opts
-   * @param {string} opts.baseUrl — e.g. 'https://webagentbridge.com'
-   * @param {string} opts.sessionToken — Bearer token from /sessions
-   * @param {string} [opts.actionsPath='/api/wab/actions'] — endpoint root
-   * @param {string} [opts.humanGatePath='/api/wab/human-gate'] — endpoint root
-   * @param {function} [opts.fetchImpl=globalThis.fetch]
-   */
-  constructor(opts = {}) {
-    if (!opts.baseUrl) throw new Error('SafetyShieldClient: baseUrl required');
-    if (!opts.sessionToken) throw new Error('SafetyShieldClient: sessionToken required');
-    this.baseUrl = String(opts.baseUrl).replace(/\/$/, '');
-    this.sessionToken = opts.sessionToken;
-    this.actionsPath = opts.actionsPath || '/api/wab/actions';
-    this.humanGatePath = opts.humanGatePath || '/api/wab/human-gate';
-    this.fetch = opts.fetchImpl || globalThis.fetch;
-    if (typeof this.fetch !== 'function') {
-      throw new Error('SafetyShieldClient: no fetch implementation available (Node 18+ or pass fetchImpl)');
-    }
-  }
-
-  _headers() {
-    return {
-      ...DEFAULT_HEADERS,
-      Authorization: `Bearer ${this.sessionToken}`,
-    };
-  }
-
-  async _post(path, body) {
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
-      method: 'POST',
-      headers: this._headers(),
-      body: JSON.stringify(body || {}),
-    });
-    const text = await res.text();
-    let json = null;
-    try { json = text ? JSON.parse(text) : null; } catch { /* leave null */ }
-    return { status: res.status, ok: res.ok, body: json, raw: text };
-  }
-
-  async _get(path) {
-    const res = await this.fetch(`${this.baseUrl}${path}`, { headers: this._headers() });
-    const text = await res.text();
-    let json = null;
-    try { json = text ? JSON.parse(text) : null; } catch { /* leave null */ }
-    return { status: res.status, ok: res.ok, body: json };
-  }
-
-  /**
-   * Phase 1: Submit a dry-run for an action and return the plan envelope.
-   * Throws if the server returns an error other than a successful plan.
-   *
-   * @param {string} actionName
-   * @param {object} [params]
-   * @returns {Promise<{plan_id:string, simulation:object, expires_at:string, raw:object}>}
-   */
-  async dryRun(actionName, params = {}) {
-    const r = await this._post(`${this.actionsPath}/${encodeURIComponent(actionName)}`, {
-      params,
-      dry_run: true,
-    });
-    if (!r.ok) {
-      throw shieldError('dry_run_failed', r);
-    }
-    const result = (r.body && (r.body.result || r.body)) || {};
-    if (!result.plan_id) {
-      throw shieldError('dry_run_no_plan', r);
-    }
-    return {
-      action: actionName,
-      params,
-      plan_id: result.plan_id,
-      simulation: result.simulation || null,
-      expires_at: result.expires_at || null,
-      raw: r.body,
-    };
-  }
-
-  /**
-   * Phase 2: Execute the action, automatically handling the human-gate
-   * loop if the server returns HUMAN_GATE_REQUIRED.
-   *
-   * If a 6-digit `code` is supplied AND a challenge is issued, the helper
-   * will call /human-gate/approve and then retry execution. If no code is
-   * supplied and a challenge is issued, the helper returns a `pending`
-   * envelope so the caller can prompt the human, then resume by calling
-   * `confirmAction(plan, { code })` again.
-   *
-   * @param {{action:string, params?:object, plan_id:string}} plan — from dryRun()
-   * @param {object} [opts]
-   * @param {string} [opts.code] — 6-digit human-gate code
-   * @param {string} [opts.confirmation_id] — pre-existing approval id
-   * @returns {Promise<object>}
-   */
-  async confirmAction(plan, opts = {}) {
-    if (!plan || !plan.action || !plan.plan_id) {
-      throw new Error('confirmAction: plan must include {action, plan_id}');
-    }
-    const body = {
-      params: plan.params || {},
-      dry_run: false,
-      plan_id: plan.plan_id,
-    };
-    if (opts.confirmation_id) body.confirmation_id = opts.confirmation_id;
-
-    const r = await this._post(
-      `${this.actionsPath}/${encodeURIComponent(plan.action)}`,
-      body
-    );
-
-    const code = r.body && r.body.error && r.body.error.code;
-
-    // Happy path — HTTP 2xx with no error envelope.
-    if (r.ok && !code) return r.body;
-
-    // Human-gate flow
-    if (code === 'HUMAN_GATE_REQUIRED' && r.status === 202) {
-      const err = r.body.error || {};
-      const challengeId = err.challenge_id || err.details?.challenge_id;
-      if (!challengeId) throw shieldError('human_gate_malformed', r);
-
-      // No code provided — bubble up so caller can prompt human.
-      if (!opts.code) {
-        return {
-          status: 'pending_human_gate',
-          challenge_id: challengeId,
-          expires_at: err.expires_at || err.details?.expires_at || null,
-          dispatched_to: err.dispatched_to || err.details?.dispatched_to || null,
-          plan,
-        };
-      }
-
-      // Code supplied — approve and retry.
-      const approve = await this._post(`${this.humanGatePath}/approve`, {
-        challenge_id: challengeId,
-        code: String(opts.code),
-      });
-      if (!approve.ok) {
-        throw shieldError('human_gate_approve_failed', approve);
-      }
-      const confirmationId =
-        approve.body?.result?.confirmation_id ||
-        approve.body?.confirmation_id;
-      if (!confirmationId) throw shieldError('human_gate_no_confirmation', approve);
-      return this.confirmAction(plan, { confirmation_id: confirmationId });
-    }
-
-    if (code === 'HUMAN_GATE_PENDING') {
-      // Retry by polling status.
-      return {
-        status: 'pending_human_gate',
-        challenge_id: opts.confirmation_id,
-        plan,
-        message: r.body.error.message,
-      };
-    }
-
-    throw shieldError(code || 'execute_failed', r);
-  }
-
-  /**
-   * Convenience: dry-run + confirm in one call.
-   * If a human-gate is required and no code is passed, returns the pending
-   * envelope. Caller resumes by calling confirmAction(envelope.plan, {code}).
-   */
-  async safeExecute(actionName, params, opts = {}) {
-    const plan = await this.dryRun(actionName, params);
-    return this.confirmAction(plan, opts);
-  }
-
-  /**
-   * Poll a human-gate challenge status (rarely needed — confirmAction
-   * handles the round-trip). Returns the raw status envelope.
-   */
-  async humanGateStatus(challengeId) {
-    const r = await this._get(
-      `${this.humanGatePath}/${encodeURIComponent(challengeId)}/status`
-    );
-    return r.body;
-  }
-}
-
-function shieldError(code, response) {
-  const msg = response?.body?.error?.message ||
-    `WAB safety-shield error: ${code} (HTTP ${response?.status})`;
-  const err = new Error(msg);
-  err.code = code;
-  err.status = response?.status;
-  err.response = response?.body;
-  return err;
-}
-
-module.exports = { SafetyShieldClient };
+/**
+ * WAB Safety-Shield Client Helper (SPEC §8.10–§8.13)
+ *
+ * Wraps the 2-phase dry-run + human-gate protocol for HTTP API consumers
+ * so agents don't have to reimplement plan_id / confirmation_id juggling.
+ *
+ * Usage:
+ *   const { SafetyShieldClient } = require('@webagentbridge/sdk/safety-shield');
+ *   const client = new SafetyShieldClient({
+ *     baseUrl: 'https://webagentbridge.com',
+ *     sessionToken: '<bearer-token>',
+ *   });
+ *
+ *   // Single call — handles dry-run automatically, returns plan for review:
+ *   const plan = await client.dryRun('deleteUser', { id: 42 });
+ *   console.log(plan.simulation.summary);
+ *
+ *   // Confirm with the plan_id (and code if human-gate engaged):
+ *   const result = await client.confirmAction(plan, { code: '123456' });
+ */
+
+'use strict';
+
+const DEFAULT_HEADERS = { 'Content-Type': 'application/json' };
+
+class SafetyShieldClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl — e.g. 'https://webagentbridge.com'
+   * @param {string} opts.sessionToken — Bearer token from /sessions
+   * @param {string} [opts.actionsPath='/api/wab/actions'] — endpoint root
+   * @param {string} [opts.humanGatePath='/api/wab/human-gate'] — endpoint root
+   * @param {function} [opts.fetchImpl=globalThis.fetch]
+   */
+  constructor(opts = {}) {
+    if (!opts.baseUrl) throw new Error('SafetyShieldClient: baseUrl required');
+    if (!opts.sessionToken) throw new Error('SafetyShieldClient: sessionToken required');
+    this.baseUrl = String(opts.baseUrl).replace(/\/$/, '');
+    this.sessionToken = opts.sessionToken;
+    this.actionsPath = opts.actionsPath || '/api/wab/actions';
+    this.humanGatePath = opts.humanGatePath || '/api/wab/human-gate';
+    this.fetch = opts.fetchImpl || globalThis.fetch;
+    if (typeof this.fetch !== 'function') {
+      throw new Error('SafetyShieldClient: no fetch implementation available (Node 18+ or pass fetchImpl)');
+    }
+  }
+
+  _headers() {
+    return {
+      ...DEFAULT_HEADERS,
+      Authorization: `Bearer ${this.sessionToken}`,
+    };
+  }
+
+  async _post(path, body) {
+    const res = await this.fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify(body || {}),
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* leave null */ }
+    return { status: res.status, ok: res.ok, body: json, raw: text };
+  }
+
+  async _get(path) {
+    const res = await this.fetch(`${this.baseUrl}${path}`, { headers: this._headers() });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* leave null */ }
+    return { status: res.status, ok: res.ok, body: json };
+  }
+
+  /**
+   * Phase 1: Submit a dry-run for an action and return the plan envelope.
+   * Throws if the server returns an error other than a successful plan.
+   *
+   * @param {string} actionName
+   * @param {object} [params]
+   * @returns {Promise<{plan_id:string, simulation:object, expires_at:string, raw:object}>}
+   */
+  async dryRun(actionName, params = {}) {
+    const r = await this._post(`${this.actionsPath}/${encodeURIComponent(actionName)}`, {
+      params,
+      dry_run: true,
+    });
+    if (!r.ok) {
+      throw shieldError('dry_run_failed', r);
+    }
+    const result = (r.body && (r.body.result || r.body)) || {};
+    if (!result.plan_id) {
+      throw shieldError('dry_run_no_plan', r);
+    }
+    return {
+      action: actionName,
+      params,
+      plan_id: result.plan_id,
+      simulation: result.simulation || null,
+      expires_at: result.expires_at || null,
+      raw: r.body,
+    };
+  }
+
+  /**
+   * Phase 2: Execute the action, automatically handling the human-gate
+   * loop if the server returns HUMAN_GATE_REQUIRED.
+   *
+   * If a 6-digit `code` is supplied AND a challenge is issued, the helper
+   * will call /human-gate/approve and then retry execution. If no code is
+   * supplied and a challenge is issued, the helper returns a `pending`
+   * envelope so the caller can prompt the human, then resume by calling
+   * `confirmAction(plan, { code })` again.
+   *
+   * @param {{action:string, params?:object, plan_id:string}} plan — from dryRun()
+   * @param {object} [opts]
+   * @param {string} [opts.code] — 6-digit human-gate code
+   * @param {string} [opts.confirmation_id] — pre-existing approval id
+   * @returns {Promise<object>}
+   */
+  async confirmAction(plan, opts = {}) {
+    if (!plan || !plan.action || !plan.plan_id) {
+      throw new Error('confirmAction: plan must include {action, plan_id}');
+    }
+    const body = {
+      params: plan.params || {},
+      dry_run: false,
+      plan_id: plan.plan_id,
+    };
+    if (opts.confirmation_id) body.confirmation_id = opts.confirmation_id;
+
+    const r = await this._post(
+      `${this.actionsPath}/${encodeURIComponent(plan.action)}`,
+      body
+    );
+
+    const code = r.body && r.body.error && r.body.error.code;
+
+    // Happy path — HTTP 2xx with no error envelope.
+    if (r.ok && !code) return r.body;
+
+    // Human-gate flow
+    if (code === 'HUMAN_GATE_REQUIRED' && r.status === 202) {
+      const err = r.body.error || {};
+      const challengeId = err.challenge_id || err.details?.challenge_id;
+      if (!challengeId) throw shieldError('human_gate_malformed', r);
+
+      // No code provided — bubble up so caller can prompt human.
+      if (!opts.code) {
+        return {
+          status: 'pending_human_gate',
+          challenge_id: challengeId,
+          expires_at: err.expires_at || err.details?.expires_at || null,
+          dispatched_to: err.dispatched_to || err.details?.dispatched_to || null,
+          plan,
+        };
+      }
+
+      // Code supplied — approve and retry.
+      const approve = await this._post(`${this.humanGatePath}/approve`, {
+        challenge_id: challengeId,
+        code: String(opts.code),
+      });
+      if (!approve.ok) {
+        throw shieldError('human_gate_approve_failed', approve);
+      }
+      const confirmationId =
+        approve.body?.result?.confirmation_id ||
+        approve.body?.confirmation_id;
+      if (!confirmationId) throw shieldError('human_gate_no_confirmation', approve);
+      return this.confirmAction(plan, { confirmation_id: confirmationId });
+    }
+
+    if (code === 'HUMAN_GATE_PENDING') {
+      // Retry by polling status.
+      return {
+        status: 'pending_human_gate',
+        challenge_id: opts.confirmation_id,
+        plan,
+        message: r.body.error.message,
+      };
+    }
+
+    throw shieldError(code || 'execute_failed', r);
+  }
+
+  /**
+   * Convenience: dry-run + confirm in one call.
+   * If a human-gate is required and no code is passed, returns the pending
+   * envelope. Caller resumes by calling confirmAction(envelope.plan, {code}).
+   */
+  async safeExecute(actionName, params, opts = {}) {
+    const plan = await this.dryRun(actionName, params);
+    return this.confirmAction(plan, opts);
+  }
+
+  /**
+   * Poll a human-gate challenge status (rarely needed — confirmAction
+   * handles the round-trip). Returns the raw status envelope.
+   */
+  async humanGateStatus(challengeId) {
+    const r = await this._get(
+      `${this.humanGatePath}/${encodeURIComponent(challengeId)}/status`
+    );
+    return r.body;
+  }
+}
+
+function shieldError(code, response) {
+  const msg = response?.body?.error?.message ||
+    `WAB safety-shield error: ${code} (HTTP ${response?.status})`;
+  const err = new Error(msg);
+  err.code = code;
+  err.status = response?.status;
+  err.response = response?.body;
+  return err;
+}
+
+module.exports = { SafetyShieldClient };