safehands-pharos 1.5.0 → 2.8.0

package/dist/api/broadcastRoutes.js

@@ -0,0 +1,147 @@
+import { broadcastSignedSchema } from "./schemas.js";
+import { getPreparedTx, markPreparedTxUsed } from "../lib/preparedTxStore.js";
+import { parseTransaction, recoverTransactionAddress, keccak256, isAddressEqual } from "viem";
+import { broadcastSignedTransaction } from "../lib/pharos/userSignedBroadcaster.js";
+import { checkAttestationConfig, publishAttestation, getAttestationRecord } from "../lib/pharos/attestationPublisher.js";
+import { lookupAttestationInGoldsky, lookupAttestationOnchain } from "../lib/goldsky.js";
+import { auditLog } from "../lib/auditLog.js";
+import { getActiveNetworkName } from "../lib/networks.js";
+import { readOnlyMeta } from "./response.js";
+export async function handleBroadcastSigned(raw) {
+    const input = broadcastSignedSchema.parse(raw);
+    // 1. Load prepared record
+    const record = getPreparedTx(input.preparedTransactionId);
+    if (!record) {
+        throw new Error("Prepared transaction not found or expired.");
+    }
+    if (record.hash !== input.preparedTransactionHash) {
+        throw new Error("Prepared transaction hash mismatch.");
+    }
+    if (record.usedAt) {
+        throw new Error("Prepared transaction has already been broadcast.");
+    }
+    if (record.expiresAt < Date.now()) {
+        throw new Error("Prepared transaction has expired.");
+    }
+    if (record.decision === "BLOCK") {
+        throw new Error("Action is blocked by SafeHands policy.");
+    }
+    // Deliberate stance split vs the MCP write gate (see docs/DECISION_CONTRACT.md):
+    // the MCP tools accept caller `confirm=true` because the MCP host / human operator
+    // relaying the call is the trust anchor attesting the review happened. This HTTP
+    // relay has NO such trusted channel — any client can set a boolean — so a
+    // REQUIRE_CONFIRMATION record is refused outright rather than self-confirmed.
+    if (record.decision === "REQUIRE_CONFIRMATION") {
+        throw new Error("Action requires confirmation. No trusted confirmation-satisfied mechanism is currently implemented.");
+    }
+    // 2. Decode and verify the raw signed transaction
+    const parsedTx = parseTransaction(input.rawSignedTransaction);
+    // Recover the sender from the signature
+    const recoveredAddress = await recoverTransactionAddress({
+        serializedTransaction: input.rawSignedTransaction,
+    });
+    if (!isAddressEqual(recoveredAddress, record.from)) {
+        throw new Error(`Signer mismatch: expected ${record.from}, got ${recoveredAddress}`);
+    }
+    if (parsedTx.to && !isAddressEqual(parsedTx.to, record.to)) {
+        throw new Error(`To address mismatch: expected ${record.to}, got ${parsedTx.to}`);
+    }
+    const expectedValue = record.value ? BigInt(record.value) : 0n;
+    const actualValue = parsedTx.value || 0n;
+    if (expectedValue !== actualValue) {
+        throw new Error(`Value mismatch: expected ${expectedValue}, got ${actualValue}`);
+    }
+    const actualData = parsedTx.data || "0x";
+    const actualDataHash = keccak256(actualData);
+    if (actualDataHash !== record.dataHash) {
+        throw new Error("Transaction data mismatch.");
+    }
+    if (parsedTx.chainId !== record.chainId) {
+        throw new Error(`ChainId mismatch: expected ${record.chainId}, got ${parsedTx.chainId}`);
+    }
+    // 3. Check for Live Broadcast capability
+    const isBroadcastEnabled = process.env.SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED === "true";
+    let txHash;
+    let broadcastStatus = "verify_only_passed";
+    let attestationStatus = "skipped";
+    // Deliberately static: this relay returns right after eth_sendRawTransaction and
+    // never waits for the receipt, so the on-chain outcome is genuinely unknown here.
+    // Callers poll get_transaction_status with the returned txHash for the mined result.
+    const executionStatus = "UNKNOWN";
+    let message = "Transaction signature and fields verified successfully. Broadcast is disabled in verify-only mode.";
+    if (isBroadcastEnabled) {
+        if (record.chainId !== 1672) {
+            throw new Error("Live broadcast is only supported on Pharos Pacific Mainnet (chainId 1672).");
+        }
+        // 3.5 Check attestation config before broadcast
+        checkAttestationConfig();
+        // 4. Mark used BEFORE broadcast to eliminate async race window
+        markPreparedTxUsed(record.id);
+        // 5. Broadcast
+        txHash = await broadcastSignedTransaction(input.rawSignedTransaction, record.chainId);
+        // 6. Attest. In production required/sync mode, wait for the first attempt so
+        // the response reflects durable state; retries continue from the persistent queue.
+        attestationStatus = "pending_retry";
+        const shouldSyncAttestation = process.env.SAFEHANDS_ATTESTATION_REQUIRED === "true" || process.env.SAFEHANDS_ATTESTATION_SYNC === "true";
+        if (shouldSyncAttestation) {
+            attestationStatus = await publishAttestation(txHash, parsedTx, record);
+        }
+        else {
+            publishAttestation(txHash, parsedTx, record).catch(console.error);
+        }
+        auditLog({
+            ts: new Date().toISOString(),
+            tool: "broadcast_signed",
+            success: true,
+            txHash,
+            preparedTransactionId: record.id,
+            preparedTransactionHash: record.hash,
+            attestationStatus,
+            chainId: record.chainId,
+        });
+        broadcastStatus = "success";
+        message = "Transaction verified and broadcast. The execution outcome is not awaited; poll get_transaction_status with the returned txHash for the mined receipt.";
+    }
+    return {
+        broadcastStatus,
+        attestationStatus,
+        executionStatus,
+        message,
+        txHash,
+        preparedTransactionId: record.id,
+        preparedTransactionHash: record.hash,
+        decision: record.decision,
+        network: getActiveNetworkName(),
+        chainId: record.chainId,
+        ...readOnlyMeta(),
+    };
+}
+export async function handleGetBroadcastAttestationStatus(txHash) {
+    const localRecord = getAttestationRecord(txHash);
+    const goldsky = await lookupAttestationInGoldsky(txHash);
+    const onchain = goldsky.indexed
+        ? { source: "contract", skipped: true, reason: "Goldsky already indexed the on-chain attestation event." }
+        : await lookupAttestationOnchain(txHash);
+    const attestationStatus = localRecord?.status || (goldsky.indexed ? "indexed" : ("skipped"));
+    return {
+        txHash,
+        status: goldsky.indexed || ("onchainVerified" in onchain && onchain.onchainVerified)
+            ? "attested"
+            : localRecord?.status === "pending_retry"
+                ? "pending_retry"
+                : localRecord?.status === "failed"
+                    ? "failed"
+                    : "not_found",
+        attestationStatus,
+        local: {
+            found: Boolean(localRecord),
+            record: localRecord,
+        },
+        goldsky,
+        onchain,
+        lookupOrder: ["local", "goldsky", "contract_fallback"],
+        network: getActiveNetworkName(),
+        ...readOnlyMeta(),
+    };
+}
+//# sourceMappingURL=broadcastRoutes.js.map

package/dist/api/broadcastRoutes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcastRoutes.js","sourceRoot":"","sources":["../../src/api/broadcastRoutes.ts"],"names":[],"mappings":"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"}

package/dist/api/consolePage.d.ts

@@ -0,0 +1,2 @@
+export declare const DEMO_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>SafeHands: live policy demo \u00B7 Pharos Pacific Mainnet</title>\n<meta name=\"description\" content=\"Paste an agent intent, get a real ALLOW / BLOCK decision from the live SafeHands policy engine on Pharos Pacific Mainnet (1672).\">\n<style>\n  :root{\n    --bg0:#0d1117; --bg1:#151c2e; --panel:#161d2f; --line:#232c44;\n    --text:#f0f6fc; --muted:#9da7b3; --dim:#6e7781;\n    --violet:#7c3aed; --cyan:#0891b2;\n    --allow:#16a34a; --block:#dc2626; --confirm:#d97706; --prepare:#0891b2;\n  }\n  *{box-sizing:border-box}\n  body{margin:0;background:linear-gradient(160deg,var(--bg0),var(--bg1));min-height:100vh;\n    color:var(--text);font:15px/1.55 ui-sans-serif,system-ui,-apple-system,\"Segoe UI\",Roboto,sans-serif;}\n  .wrap{max-width:880px;margin:0 auto;padding:40px 20px 64px}\n  header{display:flex;align-items:baseline;gap:12px;flex-wrap:wrap}\n  h1{font-size:26px;margin:0;letter-spacing:-.02em}\n  h1 .shield{background:linear-gradient(90deg,var(--violet),var(--cyan));\n    -webkit-background-clip:text;background-clip:text;color:transparent}\n  .chip{font:12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted);\n    border:1px solid var(--line);border-radius:999px;padding:5px 10px;white-space:nowrap}\n  .sub{color:var(--muted);margin:10px 0 0;max-width:64ch}\n  .sub b{color:var(--text);font-weight:600}\n  .grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:10px;margin:28px 0 14px}\n  .preset{appearance:none;text-align:left;cursor:pointer;border:1px solid var(--line);\n    background:var(--panel);color:var(--text);border-radius:10px;padding:12px 14px;\n    transition:border-color .15s,transform .15s}\n  .preset:hover{border-color:var(--cyan);transform:translateY(-1px)}\n  .preset small{display:block;color:var(--dim);margin-top:3px}\n  .preset .tag{float:right;font:11px/1 ui-monospace,monospace;padding:3px 7px;border-radius:6px;margin-left:8px}\n  .tag.allow{color:var(--allow);border:1px solid var(--allow)}\n  .tag.prepare{color:var(--prepare);border:1px solid var(--prepare)}\n  .tag.block{color:var(--block);border:1px solid var(--block)}\n  .tag.confirm{color:var(--confirm);border:1px solid var(--confirm)}\n  label{display:block;color:var(--muted);font-size:13px;margin:18px 0 6px}\n  textarea{width:100%;min-height:150px;resize:vertical;background:#0b101d;color:var(--text);\n    border:1px solid var(--line);border-radius:10px;padding:12px 14px;\n    font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace}\n  textarea:focus{outline:none;border-color:var(--violet)}\n  .run{margin-top:12px;cursor:pointer;border:none;border-radius:10px;padding:12px 22px;\n    font-weight:600;font-size:15px;color:#fff;\n    background:linear-gradient(90deg,var(--violet),var(--cyan))}\n  .run:disabled{opacity:.55;cursor:wait}\n  #result{margin-top:26px}\n  .card{border-radius:12px;border:1px solid var(--line);background:var(--panel);overflow:hidden}\n  .verdict{display:flex;align-items:center;gap:12px;padding:16px 18px;font-size:18px;font-weight:700;\n    border-left:6px solid var(--dim)}\n  .verdict .lvl{font:12px/1 ui-monospace,monospace;font-weight:400;color:var(--muted)}\n  .v-ALLOW{border-left-color:var(--allow);color:var(--allow)}\n  .v-BLOCK{border-left-color:var(--block);color:var(--block)}\n  .v-REQUIRE_CONFIRMATION{border-left-color:var(--confirm);color:var(--confirm)}\n  .v-PREPARE_ONLY{border-left-color:var(--prepare);color:var(--prepare)}\n  .v-ERROR{border-left-color:var(--block);color:var(--block)}\n  .body{padding:2px 18px 16px;color:var(--muted)}\n  .body ul{margin:8px 0;padding-left:20px}\n  details{border-top:1px solid var(--line);padding:10px 18px}\n  summary{cursor:pointer;color:var(--dim);font-size:13px}\n  pre{overflow:auto;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted);margin:10px 0 4px}\n  footer{margin-top:44px;color:var(--dim);font-size:13px;border-top:1px solid var(--line);padding-top:16px}\n  footer a{color:var(--muted)}\n  .spin{display:inline-block;width:14px;height:14px;border:2px solid #fff5;border-top-color:#fff;\n    border-radius:50%;animation:r .7s linear infinite;vertical-align:-2px;margin-right:8px}\n  @keyframes r{to{transform:rotate(360deg)}}\n</style>\n</head>\n<body>\n<div class=\"wrap\">\n  <header>\n    <h1><span class=\"shield\">\uD83D\uDEE1 SafeHands</span> live policy demo</h1>\n    <span class=\"chip\">Pharos Pacific Mainnet \u00B7 1672</span>\n    <span class=\"chip\">zero-custody \u00B7 read-only</span>\n  </header>\n  <p class=\"sub\">Every button below sends a real agent intent to the <b>live deterministic policy engine</b> running behind this page (<code>POST /tools/safehands_preflight_check</code>). No wallet, no keys, no transaction: this is the check an AI agent runs <b>before</b> it signs anything on Pharos.</p>\n\n  <div class=\"grid\" id=\"presets\"></div>\n\n  <label for=\"intent\">Agent intent (editable JSON)</label>\n  <textarea id=\"intent\" spellcheck=\"false\"></textarea>\n  <button class=\"run\" id=\"run\">Run preflight</button>\n\n  <div id=\"result\"></div>\n\n  <footer>\n    SafeHands never holds keys and never signs for you. \u00B7\n    <a href=\"https://github.com/SZtch/safehands-pharos\" rel=\"noopener\">GitHub</a> \u00B7\n    <a href=\"https://www.pharosscan.xyz/address/0x428e02bf85412e7242d991cd6725ec59e8b06c8d\" rel=\"noopener\">Registry contract</a> \u00B7\n    <a href=\"https://www.pharosscan.xyz/address/0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c\" rel=\"noopener\">Attestation contract</a>\n  </footer>\n</div>\n<script>\n(function(){\n  \"use strict\";\n  var PRESETS = [\n    { name: \"Unlimited approval\", hint: \"agent grants a spender forever\", tag: \"BLOCK\", cls: \"block\",\n      intent: { actionType: \"approve_token\", chainId: 1672, approvalToken: \"USDC\",\n                spender: \"0x000000000000000000000000000000000000dEaD\", approvalAmount: \"max\" } },\n    { name: \"Wrong chain\", hint: \"agent targets Ethereum, not Pharos\", tag: \"BLOCK\", cls: \"block\",\n      intent: { actionType: \"send_payment\", chainId: 1, amount: \"0.5\", amountUnit: \"PROS\",\n                recipient: \"0x0000000000000000000000000000000000000001\" } },\n    { name: \"Safe small payment\", hint: \"0.001 PROS within policy: safe; sign it yourself\", tag: \"PREPARE\", cls: \"prepare\",\n      intent: { actionType: \"send_payment\", chainId: 1672, isMainnet: true, amount: \"0.001\",\n                amountUnit: \"PROS\", recipient: \"0x0000000000000000000000000000000000000001\" } },\n    { name: \"Unregistered RWA token\", hint: \"tokenized asset not in registry\", tag: \"CONFIRM\", cls: \"confirm\",\n      intent: { actionType: \"approve_token\", chainId: 1672, isMainnet: true, approvalAmount: \"25\",\n                tokenAddress: \"0x00000000000000000000000000000000000000aa\",\n                spender: \"0x0000000000000000000000000000000000000001\", spenderVerified: false } },\n    { name: \"Malicious x402 endpoint\", hint: \"payment to an internal IP\", tag: \"BLOCK\", cls: \"block\",\n      intent: { actionType: \"x402_pay_and_fetch\", chainId: 1672,\n                url: \"http://169.254.169.254/latest/meta-data\", paymentAmountUsdc: \"0.01\" } },\n    { name: \"Oversized settlement\", hint: \"5 USDC over the x402 policy cap\", tag: \"BLOCK\", cls: \"block\",\n      intent: { actionType: \"x402_pay_and_fetch\", chainId: 1672, isMainnet: true,\n                url: \"https://rpc.pharos.xyz/\", paymentAmountUsdc: \"5\" } }\n  ];\n\n  var box = document.getElementById(\"intent\");\n  var out = document.getElementById(\"result\");\n  var run = document.getElementById(\"run\");\n  var grid = document.getElementById(\"presets\");\n\n  PRESETS.forEach(function (p) {\n    var b = document.createElement(\"button\");\n    b.className = \"preset\";\n    b.innerHTML = \"<span class='tag \" + p.cls + \"'>\" + p.tag + \"</span><strong>\" + p.name +\n      \"</strong><small>\" + p.hint + \"</small>\";\n    b.addEventListener(\"click\", function () {\n      box.value = JSON.stringify(p.intent, null, 2);\n      submit();\n    });\n    grid.appendChild(b);\n  });\n\n  box.value = JSON.stringify(PRESETS[0].intent, null, 2);\n\n  function esc(s) {\n    return String(s).replace(/[&<>\"]/g, function (c) {\n      return { \"&\": \"&amp;\", \"<\": \"&lt;\", \">\": \"&gt;\", '\"': \"&quot;\" }[c];\n    });\n  }\n\n  function list(title, items) {\n    if (!items || !items.length) return \"\";\n    return \"<div><b>\" + title + \"</b><ul>\" + items.map(function (r) {\n      return \"<li>\" + esc(r) + \"</li>\";\n    }).join(\"\") + \"</ul></div>\";\n  }\n\n  function render(payload) {\n    var html;\n    if (payload && payload.success && payload.data) {\n      var d = payload.data;\n      var decision = d.decision || d.guardianDecision || \"UNKNOWN\";\n      html =\n        \"<div class='card'>\" +\n        \"<div class='verdict v-\" + esc(decision) + \"'>\" + esc(decision) +\n        (d.riskLevel ? \" <span class='lvl'>risk: \" + esc(d.riskLevel) + \"</span>\" : \"\") + \"</div>\" +\n        \"<div class='body'>\" + list(\"Why\", d.reasons) + list(\"Required actions\", d.requiredActions) +\n        (!d.reasons || !d.reasons.length ? \"<div>All policy checks passed for this intent.</div>\" : \"\") +\n        \"</div>\" +\n        \"<details><summary>Raw response</summary><pre>\" + esc(JSON.stringify(payload, null, 2)) + \"</pre></details>\" +\n        \"</div>\";\n    } else {\n      var err = (payload && payload.error) || {};\n      html =\n        \"<div class='card'>\" +\n        \"<div class='verdict v-ERROR'>\" + esc(err.code || \"ERROR\") + \"</div>\" +\n        \"<div class='body'>\" + esc(err.message || \"Request failed.\") + \"</div>\" +\n        \"<details><summary>Raw response</summary><pre>\" + esc(JSON.stringify(payload, null, 2)) + \"</pre></details>\" +\n        \"</div>\";\n    }\n    out.innerHTML = html;\n  }\n\n  function submit() {\n    var body;\n    try { body = JSON.parse(box.value); }\n    catch (e) { render({ success: false, error: { code: \"INVALID_JSON\", message: \"The intent is not valid JSON: \" + e.message } }); return; }\n    run.disabled = true;\n    run.innerHTML = \"<span class='spin'></span>Checking\u2026\";\n    fetch(\"/tools/safehands_preflight_check\", {\n      method: \"POST\",\n      headers: { \"content-type\": \"application/json\" },\n      body: JSON.stringify(body)\n    })\n      .then(function (r) { return r.json(); })\n      .then(render)\n      .catch(function (e) { render({ success: false, error: { code: \"NETWORK_ERROR\", message: String(e) } }); })\n      .then(function () { run.disabled = false; run.textContent = \"Run preflight\"; });\n  }\n\n  run.addEventListener(\"click\", submit);\n})();\n</script>\n</body>\n</html>\n";
+//# sourceMappingURL=consolePage.d.ts.map

package/dist/api/consolePage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolePage.d.ts","sourceRoot":"","sources":["../../src/api/consolePage.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,cAAc,urVAqM1B,CAAC"}

package/dist/api/consolePage.js

@@ -0,0 +1,206 @@
+// ─── SafeHands Interactive Demo Page (GET /demo) ────────────────────────
+// A single self-contained HTML page (no build tooling, no external assets,
+// no dependencies) served by the read-only API. It calls the same-origin
+// hosted tool gateway (POST /tools/safehands_preflight_check) so visitors
+// get REAL decisions from the live deterministic policy engine.
+// Zero-custody: the page never asks for keys and never signs anything.
+// ────────────────────────────────────────────────────────────────────────
+export const DEMO_PAGE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SafeHands: live policy demo · Pharos Pacific Mainnet</title>
+<meta name="description" content="Paste an agent intent, get a real ALLOW / BLOCK decision from the live SafeHands policy engine on Pharos Pacific Mainnet (1672).">
+<style>
+  :root{
+    --bg0:#0d1117; --bg1:#151c2e; --panel:#161d2f; --line:#232c44;
+    --text:#f0f6fc; --muted:#9da7b3; --dim:#6e7781;
+    --violet:#7c3aed; --cyan:#0891b2;
+    --allow:#16a34a; --block:#dc2626; --confirm:#d97706; --prepare:#0891b2;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:linear-gradient(160deg,var(--bg0),var(--bg1));min-height:100vh;
+    color:var(--text);font:15px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;}
+  .wrap{max-width:880px;margin:0 auto;padding:40px 20px 64px}
+  header{display:flex;align-items:baseline;gap:12px;flex-wrap:wrap}
+  h1{font-size:26px;margin:0;letter-spacing:-.02em}
+  h1 .shield{background:linear-gradient(90deg,var(--violet),var(--cyan));
+    -webkit-background-clip:text;background-clip:text;color:transparent}
+  .chip{font:12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted);
+    border:1px solid var(--line);border-radius:999px;padding:5px 10px;white-space:nowrap}
+  .sub{color:var(--muted);margin:10px 0 0;max-width:64ch}
+  .sub b{color:var(--text);font-weight:600}
+  .grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:10px;margin:28px 0 14px}
+  .preset{appearance:none;text-align:left;cursor:pointer;border:1px solid var(--line);
+    background:var(--panel);color:var(--text);border-radius:10px;padding:12px 14px;
+    transition:border-color .15s,transform .15s}
+  .preset:hover{border-color:var(--cyan);transform:translateY(-1px)}
+  .preset small{display:block;color:var(--dim);margin-top:3px}
+  .preset .tag{float:right;font:11px/1 ui-monospace,monospace;padding:3px 7px;border-radius:6px;margin-left:8px}
+  .tag.allow{color:var(--allow);border:1px solid var(--allow)}
+  .tag.prepare{color:var(--prepare);border:1px solid var(--prepare)}
+  .tag.block{color:var(--block);border:1px solid var(--block)}
+  .tag.confirm{color:var(--confirm);border:1px solid var(--confirm)}
+  label{display:block;color:var(--muted);font-size:13px;margin:18px 0 6px}
+  textarea{width:100%;min-height:150px;resize:vertical;background:#0b101d;color:var(--text);
+    border:1px solid var(--line);border-radius:10px;padding:12px 14px;
+    font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace}
+  textarea:focus{outline:none;border-color:var(--violet)}
+  .run{margin-top:12px;cursor:pointer;border:none;border-radius:10px;padding:12px 22px;
+    font-weight:600;font-size:15px;color:#fff;
+    background:linear-gradient(90deg,var(--violet),var(--cyan))}
+  .run:disabled{opacity:.55;cursor:wait}
+  #result{margin-top:26px}
+  .card{border-radius:12px;border:1px solid var(--line);background:var(--panel);overflow:hidden}
+  .verdict{display:flex;align-items:center;gap:12px;padding:16px 18px;font-size:18px;font-weight:700;
+    border-left:6px solid var(--dim)}
+  .verdict .lvl{font:12px/1 ui-monospace,monospace;font-weight:400;color:var(--muted)}
+  .v-ALLOW{border-left-color:var(--allow);color:var(--allow)}
+  .v-BLOCK{border-left-color:var(--block);color:var(--block)}
+  .v-REQUIRE_CONFIRMATION{border-left-color:var(--confirm);color:var(--confirm)}
+  .v-PREPARE_ONLY{border-left-color:var(--prepare);color:var(--prepare)}
+  .v-ERROR{border-left-color:var(--block);color:var(--block)}
+  .body{padding:2px 18px 16px;color:var(--muted)}
+  .body ul{margin:8px 0;padding-left:20px}
+  details{border-top:1px solid var(--line);padding:10px 18px}
+  summary{cursor:pointer;color:var(--dim);font-size:13px}
+  pre{overflow:auto;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted);margin:10px 0 4px}
+  footer{margin-top:44px;color:var(--dim);font-size:13px;border-top:1px solid var(--line);padding-top:16px}
+  footer a{color:var(--muted)}
+  .spin{display:inline-block;width:14px;height:14px;border:2px solid #fff5;border-top-color:#fff;
+    border-radius:50%;animation:r .7s linear infinite;vertical-align:-2px;margin-right:8px}
+  @keyframes r{to{transform:rotate(360deg)}}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1><span class="shield">🛡 SafeHands</span> live policy demo</h1>
+    <span class="chip">Pharos Pacific Mainnet · 1672</span>
+    <span class="chip">zero-custody · read-only</span>
+  </header>
+  <p class="sub">Every button below sends a real agent intent to the <b>live deterministic policy engine</b> running behind this page (<code>POST /tools/safehands_preflight_check</code>). No wallet, no keys, no transaction: this is the check an AI agent runs <b>before</b> it signs anything on Pharos.</p>
+
+  <div class="grid" id="presets"></div>
+
+  <label for="intent">Agent intent (editable JSON)</label>
+  <textarea id="intent" spellcheck="false"></textarea>
+  <button class="run" id="run">Run preflight</button>
+
+  <div id="result"></div>
+
+  <footer>
+    SafeHands never holds keys and never signs for you. ·
+    <a href="https://github.com/SZtch/safehands-pharos" rel="noopener">GitHub</a> ·
+    <a href="https://www.pharosscan.xyz/address/0x428e02bf85412e7242d991cd6725ec59e8b06c8d" rel="noopener">Registry contract</a> ·
+    <a href="https://www.pharosscan.xyz/address/0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c" rel="noopener">Attestation contract</a>
+  </footer>
+</div>
+<script>
+(function(){
+  "use strict";
+  var PRESETS = [
+    { name: "Unlimited approval", hint: "agent grants a spender forever", tag: "BLOCK", cls: "block",
+      intent: { actionType: "approve_token", chainId: 1672, approvalToken: "USDC",
+                spender: "0x000000000000000000000000000000000000dEaD", approvalAmount: "max" } },
+    { name: "Wrong chain", hint: "agent targets Ethereum, not Pharos", tag: "BLOCK", cls: "block",
+      intent: { actionType: "send_payment", chainId: 1, amount: "0.5", amountUnit: "PROS",
+                recipient: "0x0000000000000000000000000000000000000001" } },
+    { name: "Safe small payment", hint: "0.001 PROS within policy: safe; sign it yourself", tag: "PREPARE", cls: "prepare",
+      intent: { actionType: "send_payment", chainId: 1672, isMainnet: true, amount: "0.001",
+                amountUnit: "PROS", recipient: "0x0000000000000000000000000000000000000001" } },
+    { name: "Unregistered RWA token", hint: "tokenized asset not in registry", tag: "CONFIRM", cls: "confirm",
+      intent: { actionType: "approve_token", chainId: 1672, isMainnet: true, approvalAmount: "25",
+                tokenAddress: "0x00000000000000000000000000000000000000aa",
+                spender: "0x0000000000000000000000000000000000000001", spenderVerified: false } },
+    { name: "Malicious x402 endpoint", hint: "payment to an internal IP", tag: "BLOCK", cls: "block",
+      intent: { actionType: "x402_pay_and_fetch", chainId: 1672,
+                url: "http://169.254.169.254/latest/meta-data", paymentAmountUsdc: "0.01" } },
+    { name: "Oversized settlement", hint: "5 USDC over the x402 policy cap", tag: "BLOCK", cls: "block",
+      intent: { actionType: "x402_pay_and_fetch", chainId: 1672, isMainnet: true,
+                url: "https://rpc.pharos.xyz/", paymentAmountUsdc: "5" } }
+  ];
+
+  var box = document.getElementById("intent");
+  var out = document.getElementById("result");
+  var run = document.getElementById("run");
+  var grid = document.getElementById("presets");
+
+  PRESETS.forEach(function (p) {
+    var b = document.createElement("button");
+    b.className = "preset";
+    b.innerHTML = "<span class='tag " + p.cls + "'>" + p.tag + "</span><strong>" + p.name +
+      "</strong><small>" + p.hint + "</small>";
+    b.addEventListener("click", function () {
+      box.value = JSON.stringify(p.intent, null, 2);
+      submit();
+    });
+    grid.appendChild(b);
+  });
+
+  box.value = JSON.stringify(PRESETS[0].intent, null, 2);
+
+  function esc(s) {
+    return String(s).replace(/[&<>"]/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c];
+    });
+  }
+
+  function list(title, items) {
+    if (!items || !items.length) return "";
+    return "<div><b>" + title + "</b><ul>" + items.map(function (r) {
+      return "<li>" + esc(r) + "</li>";
+    }).join("") + "</ul></div>";
+  }
+
+  function render(payload) {
+    var html;
+    if (payload && payload.success && payload.data) {
+      var d = payload.data;
+      var decision = d.decision || d.guardianDecision || "UNKNOWN";
+      html =
+        "<div class='card'>" +
+        "<div class='verdict v-" + esc(decision) + "'>" + esc(decision) +
+        (d.riskLevel ? " <span class='lvl'>risk: " + esc(d.riskLevel) + "</span>" : "") + "</div>" +
+        "<div class='body'>" + list("Why", d.reasons) + list("Required actions", d.requiredActions) +
+        (!d.reasons || !d.reasons.length ? "<div>All policy checks passed for this intent.</div>" : "") +
+        "</div>" +
+        "<details><summary>Raw response</summary><pre>" + esc(JSON.stringify(payload, null, 2)) + "</pre></details>" +
+        "</div>";
+    } else {
+      var err = (payload && payload.error) || {};
+      html =
+        "<div class='card'>" +
+        "<div class='verdict v-ERROR'>" + esc(err.code || "ERROR") + "</div>" +
+        "<div class='body'>" + esc(err.message || "Request failed.") + "</div>" +
+        "<details><summary>Raw response</summary><pre>" + esc(JSON.stringify(payload, null, 2)) + "</pre></details>" +
+        "</div>";
+    }
+    out.innerHTML = html;
+  }
+
+  function submit() {
+    var body;
+    try { body = JSON.parse(box.value); }
+    catch (e) { render({ success: false, error: { code: "INVALID_JSON", message: "The intent is not valid JSON: " + e.message } }); return; }
+    run.disabled = true;
+    run.innerHTML = "<span class='spin'></span>Checking…";
+    fetch("/tools/safehands_preflight_check", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    })
+      .then(function (r) { return r.json(); })
+      .then(render)
+      .catch(function (e) { render({ success: false, error: { code: "NETWORK_ERROR", message: String(e) } }); })
+      .then(function () { run.disabled = false; run.textContent = "Run preflight"; });
+  }
+
+  run.addEventListener("click", submit);
+})();
+</script>
+</body>
+</html>
+`;
+//# sourceMappingURL=consolePage.js.map

package/dist/api/consolePage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolePage.js","sourceRoot":"","sources":["../../src/api/consolePage.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,yEAAyE;AACzE,0EAA0E;AAC1E,gEAAgE;AAChE,uEAAuE;AACvE,2EAA2E;AAE3E,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqM7B,CAAC"}

package/dist/api/httpHardening.d.ts

@@ -0,0 +1,75 @@
+import { type ToolFailure } from "../lib/toolResponse.js";
+import type { QuotaConfig } from "../lib/observability/quota.js";
+/** Railway/containers require binding all interfaces. */
+export declare const BIND_HOST = "0.0.0.0";
+/** Default API port when neither PORT nor GUARDIAN_API_PORT is set. */
+export declare const DEFAULT_PORT = 4022;
+type Env = Record<string, string | undefined>;
+/** Resolve the listen port. Railway injects PORT; never hardcode a fixed port. */
+export declare function resolvePort(env?: Env): number;
+/** True only when NODE_ENV is exactly "production". */
+export declare function isProduction(env?: Env): boolean;
+export interface CorsConfig {
+    /** "wildcard" ⇒ allow any origin (safe for a public, read-only API). */
+    mode: "wildcard" | "allowlist";
+    /** Explicit allowed origins (only when mode === "allowlist"). */
+    origins: string[];
+}
+/**
+ * Resolve CORS from env. `CORS_ORIGIN` or `SAFEHANDS_ALLOWED_ORIGINS` (comma-separated)
+ * define an allowlist; either set to `*` (or unset) ⇒ wildcard. The default is wildcard
+ * because the hosted API is public and read-only — we never hardcode a private domain.
+ */
+export declare function resolveCorsConfig(env?: Env): CorsConfig;
+/**
+ * The value to send for `Access-Control-Allow-Origin` given the request `Origin`:
+ *  - wildcard ⇒ "*"
+ *  - allowlist + origin present + allowed ⇒ the reflected origin
+ *  - allowlist + no/Origin not allowed ⇒ the first allowlisted origin (never a secret;
+ *    never wide-open). Returns null only when there is genuinely nothing to advertise.
+ */
+export declare function corsOriginValue(requestOrigin: string | undefined, cfg: CorsConfig): string | null;
+/** Express body-parser limit; small by default (read-only payloads are tiny). */
+export declare function resolveJsonLimit(env?: Env): string;
+export interface RateLimitConfig {
+    enabled: boolean;
+    windowMs: number;
+    max: number;
+}
+/** Lightweight in-memory rate-limit config. Disable with SAFEHANDS_RATE_LIMIT_ENABLED=false. */
+export declare function resolveRateLimitConfig(env?: Env): RateLimitConfig;
+export interface ActivityConfig {
+    enabled: boolean;
+    capacity: number;
+}
+/** In-memory activity ring config. Enabled by default; capacity clamped 10–5000. */
+export declare function resolveActivityConfig(env?: Env): ActivityConfig;
+export interface RequestLoggingConfig {
+    enabled: boolean;
+    format: "json";
+}
+/** Structured JSON request log to stdout. Enabled by default; silence via env. */
+export declare function resolveLoggingConfig(env?: Env): RequestLoggingConfig;
+/**
+ * Per-tier in-memory quota config. Shares the rate-limit enable/window defaults so
+ * existing behavior is preserved: the `anonymous` tier defaults to the base
+ * rate-limit max (120/60s). Generous defaults keep smoke tests + reviewer demos green.
+ */
+export declare function resolveQuotaConfig(env?: Env): QuotaConfig;
+export interface ErrorResponse {
+    status: number;
+    body: ToolFailure;
+}
+/**
+ * Map any thrown value to a safe HTTP error response. ZodError ⇒ 400 with field
+ * issues. Handler guard messages (requires/invalid/must/unknown) ⇒ 400. Everything
+ * else ⇒ 500. **Stack traces are never included**, and in production the 500 message
+ * is generic so internal details never leak.
+ */
+export declare function errorResponseBody(err: unknown, opts: {
+    production: boolean;
+}): ErrorResponse;
+/** Consistent 404 body for unmatched routes. */
+export declare function notFoundBody(method: string, path: string): ToolFailure;
+export {};
+//# sourceMappingURL=httpHardening.d.ts.map

package/dist/api/httpHardening.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpHardening.d.ts","sourceRoot":"","sources":["../../src/api/httpHardening.ts"],"names":[],"mappings":"AAUA,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAIjE,yDAAyD;AACzD,eAAO,MAAM,SAAS,YAAY,CAAC;AAEnC,uEAAuE;AACvE,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,CAI1D;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,GAAG,GAAE,GAAiB,GAAG,OAAO,CAE5D;AAID,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;IAC/B,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,GAAiB,GAAG,UAAU,CAMpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAIjG;AAID,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,CAG/D;AAID,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,GAAiB,GAAG,eAAe,CAK9E;AAUD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,GAAiB,GAAG,cAAc,CAK5E;AAID,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,GAAiB,GAAG,oBAAoB,CAEjF;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,GAAiB,GAAG,WAAW,CAQtE;AAID,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,GAAG,aAAa,CAW5F;AAED,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAEtE"}

package/dist/api/httpHardening.js

@@ -0,0 +1,122 @@
+// ─── SafeHands API — Production HTTP Hardening (read-only) ─────
+// Pure, deterministic, offline-testable configuration helpers for the production
+// Express server: PORT/host resolution, env-driven CORS allowlist, JSON body limit,
+// in-memory rate-limit config, a consistent error-response shape (no stack traces in
+// production), and a 404 body. NOTHING here signs, sends, holds keys, or calls the
+// network — it only shapes HTTP behaviour. All inputs come from `env` so tests can
+// pass a synthetic environment.
+// ────────────────────────────────────────────────────────────────────────
+import { ZodError } from "zod";
+import { fail } from "../lib/toolResponse.js";
+const SOURCE = "guardian_api";
+/** Railway/containers require binding all interfaces. */
+export const BIND_HOST = "0.0.0.0";
+/** Default API port when neither PORT nor GUARDIAN_API_PORT is set. */
+export const DEFAULT_PORT = 4022;
+/** Resolve the listen port. Railway injects PORT; never hardcode a fixed port. */
+export function resolvePort(env = process.env) {
+    const raw = env.PORT || env.GUARDIAN_API_PORT;
+    const n = raw ? parseInt(raw, 10) : DEFAULT_PORT;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_PORT;
+}
+/** True only when NODE_ENV is exactly "production". */
+export function isProduction(env = process.env) {
+    return env.NODE_ENV === "production";
+}
+/**
+ * Resolve CORS from env. `CORS_ORIGIN` or `SAFEHANDS_ALLOWED_ORIGINS` (comma-separated)
+ * define an allowlist; either set to `*` (or unset) ⇒ wildcard. The default is wildcard
+ * because the hosted API is public and read-only — we never hardcode a private domain.
+ */
+export function resolveCorsConfig(env = process.env) {
+    const raw = (env.CORS_ORIGIN ?? env.SAFEHANDS_ALLOWED_ORIGINS ?? "").trim();
+    if (raw === "" || raw === "*")
+        return { mode: "wildcard", origins: [] };
+    const origins = raw.split(",").map((o) => o.trim()).filter(Boolean);
+    if (origins.length === 0 || origins.includes("*"))
+        return { mode: "wildcard", origins: [] };
+    return { mode: "allowlist", origins };
+}
+/**
+ * The value to send for `Access-Control-Allow-Origin` given the request `Origin`:
+ *  - wildcard ⇒ "*"
+ *  - allowlist + origin present + allowed ⇒ the reflected origin
+ *  - allowlist + no/Origin not allowed ⇒ the first allowlisted origin (never a secret;
+ *    never wide-open). Returns null only when there is genuinely nothing to advertise.
+ */
+export function corsOriginValue(requestOrigin, cfg) {
+    if (cfg.mode === "wildcard")
+        return "*";
+    if (requestOrigin && cfg.origins.includes(requestOrigin))
+        return requestOrigin;
+    return cfg.origins[0] ?? null;
+}
+// ── JSON body limit ───────────────────────────────────────────────────────
+/** Express body-parser limit; small by default (read-only payloads are tiny). */
+export function resolveJsonLimit(env = process.env) {
+    const raw = (env.SAFEHANDS_JSON_LIMIT ?? "").trim();
+    return raw || "64kb";
+}
+/** Lightweight in-memory rate-limit config. Disable with SAFEHANDS_RATE_LIMIT_ENABLED=false. */
+export function resolveRateLimitConfig(env = process.env) {
+    const enabled = env.SAFEHANDS_RATE_LIMIT_ENABLED !== "false";
+    const windowMs = toPositiveInt(env.SAFEHANDS_RATE_LIMIT_WINDOW_MS, 60_000);
+    const max = toPositiveInt(env.SAFEHANDS_RATE_LIMIT_MAX, 120);
+    return { enabled, windowMs, max };
+}
+function toPositiveInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** In-memory activity ring config. Enabled by default; capacity clamped 10–5000. */
+export function resolveActivityConfig(env = process.env) {
+    const enabled = env.SAFEHANDS_ACTIVITY_ENABLED !== "false";
+    const raw = toPositiveInt(env.SAFEHANDS_ACTIVITY_CAPACITY, 500);
+    const capacity = Math.min(5000, Math.max(10, raw));
+    return { enabled, capacity };
+}
+/** Structured JSON request log to stdout. Enabled by default; silence via env. */
+export function resolveLoggingConfig(env = process.env) {
+    return { enabled: env.SAFEHANDS_REQUEST_LOG_ENABLED !== "false", format: "json" };
+}
+// ── Tiered quota (Phase 8B) ────────────────────────────────────────────────
+/**
+ * Per-tier in-memory quota config. Shares the rate-limit enable/window defaults so
+ * existing behavior is preserved: the `anonymous` tier defaults to the base
+ * rate-limit max (120/60s). Generous defaults keep smoke tests + reviewer demos green.
+ */
+export function resolveQuotaConfig(env = process.env) {
+    const enabled = env.SAFEHANDS_RATE_LIMIT_ENABLED !== "false";
+    const windowMs = toPositiveInt(env.SAFEHANDS_QUOTA_WINDOW_MS ?? env.SAFEHANDS_RATE_LIMIT_WINDOW_MS, 60_000);
+    const anonymous = toPositiveInt(env.SAFEHANDS_QUOTA_ANON_MAX ?? env.SAFEHANDS_RATE_LIMIT_MAX, 120);
+    const apiKey = toPositiveInt(env.SAFEHANDS_QUOTA_KEY_MAX, 600);
+    const agent = toPositiveInt(env.SAFEHANDS_QUOTA_AGENT_MAX, 600);
+    const a2a = toPositiveInt(env.SAFEHANDS_QUOTA_A2A_MAX, agent);
+    return { enabled, windowMs, max: { anonymous, "api-key": apiKey, agent, a2a } };
+}
+/**
+ * Map any thrown value to a safe HTTP error response. ZodError ⇒ 400 with field
+ * issues. Handler guard messages (requires/invalid/must/unknown) ⇒ 400. Everything
+ * else ⇒ 500. **Stack traces are never included**, and in production the 500 message
+ * is generic so internal details never leak.
+ */
+export function errorResponseBody(err, opts) {
+    if (err instanceof ZodError) {
+        const message = err.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return { status: 400, body: fail("VALIDATION_ERROR", message, false, SOURCE) };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const isClient = /requires|invalid|must|unknown/i.test(message);
+    if (isClient)
+        return { status: 400, body: fail("BAD_REQUEST", message, false, SOURCE) };
+    // 500-class: never echo internal error text in production.
+    const safeMessage = opts.production ? "Internal server error." : message;
+    return { status: 500, body: fail("INTERNAL_ERROR", safeMessage, false, SOURCE) };
+}
+/** Consistent 404 body for unmatched routes. */
+export function notFoundBody(method, path) {
+    return fail("NOT_FOUND", `No route for ${method} ${path}.`, false, SOURCE);
+}
+//# sourceMappingURL=httpHardening.js.map

package/dist/api/httpHardening.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpHardening.js","sourceRoot":"","sources":["../../src/api/httpHardening.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,iFAAiF;AACjF,oFAAoF;AACpF,qFAAqF;AACrF,mFAAmF;AACnF,mFAAmF;AACnF,gCAAgC;AAChC,2EAA2E;AAE3E,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EAAE,IAAI,EAAoB,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,GAAG,cAAc,CAAC;AAE9B,yDAAyD;AACzD,MAAM,CAAC,MAAM,SAAS,GAAG,SAAS,CAAC;AAEnC,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAIjC,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,MAAW,OAAO,CAAC,GAAG;IAChD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,iBAAiB,CAAC;IAC9C,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IACjD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;AACxD,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,MAAW,OAAO,CAAC,GAAG;IACjD,OAAO,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;AACvC,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAW,OAAO,CAAC,GAAG;IACtD,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5E,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACxE,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IAC5F,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,aAAiC,EAAE,GAAe;IAChF,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,GAAG,CAAC;IACxC,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IAC/E,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAChC,CAAC;AAED,6EAA6E;AAE7E,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,MAAW,OAAO,CAAC,GAAG;IACrD,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,OAAO,GAAG,IAAI,MAAM,CAAC;AACvB,CAAC;AAUD,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAC,MAAW,OAAO,CAAC,GAAG;IAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,4BAA4B,KAAK,OAAO,CAAC;IAC7D,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,8BAA8B,EAAE,MAAM,CAAC,CAAC;IAC3E,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;IAC7D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,aAAa,CAAC,GAAuB,EAAE,QAAgB;IAC9D,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpD,CAAC;AASD,oFAAoF;AACpF,MAAM,UAAU,qBAAqB,CAAC,MAAW,OAAO,CAAC,GAAG;IAC1D,MAAM,OAAO,GAAG,GAAG,CAAC,0BAA0B,KAAK,OAAO,CAAC;IAC3D,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACnD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AASD,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CAAC,MAAW,OAAO,CAAC,GAAG;IACzD,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,6BAA6B,KAAK,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACpF,CAAC;AAED,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAW,OAAO,CAAC,GAAG;IACvD,MAAM,OAAO,GAAG,GAAG,CAAC,4BAA4B,KAAK,OAAO,CAAC;IAC7D,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,yBAAyB,IAAI,GAAG,CAAC,8BAA8B,EAAE,MAAM,CAAC,CAAC;IAC5G,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,wBAAwB,IAAI,GAAG,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;IACnG,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;IAC9D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;AAClF,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,IAA6B;IAC3E,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjG,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;IACjF,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,gCAAgC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;IACxF,2DAA2D;IAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,OAAO,CAAC;IACzE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,IAAY;IACvD,OAAO,IAAI,CAAC,WAAW,EAAE,gBAAgB,MAAM,IAAI,IAAI,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC"}