chore: harden hosted dashboard demo (#30)

Author: TFT444

README.md

@@ -189,6 +189,10 @@ receipt. The manual Next/Back controls and optional auto-play reveal one result
 by the running gateway. Security decisions are live local computations; settlement is
 labelled simulation unless separate verified devnet evidence exists.
 
+For an optional public review deployment, use the checked-in Render Blueprint and follow
+the [hosted demonstration guide](docs/DEPLOYMENT.md). The hosted fallback requires no
+wallet credentials and continues to label settlement as simulated.
+
 After installing the official Pay CLI, attempt one external ephemeral-wallet sandbox purchase through the same gateway:
 
 ```bash
@@ -248,6 +252,8 @@ This is an early product thesis, not evidence of existing customers, revenue, or
 - [Threat model](docs/THREAT_MODEL.md)
 - [Metadata sanitization](docs/PRIVACY.md)
 - [Local security dashboard](docs/DASHBOARD.md)
+- [Hosted demonstration](docs/DEPLOYMENT.md)
+- [Judge demonstration runbook](docs/JUDGE_RUNBOOK.md)
 - [Audit receipts and local event stream](docs/AUDIT.md)
 - [Request integrity and replay protection](docs/INTEGRITY.md)
 - [Single-use wallet authorization](docs/AUTHORIZATION.md)

docs/DEPLOYMENT.md

@@ -0,0 +1,54 @@
+# Hosted demonstration
+
+The public dashboard is a demonstration surface for the running SolGuard gateway. It is
+not a production payment service. Every security decision is computed by the Python
+gateway; settlement remains explicitly labelled `SIMULATED` unless separately verified
+devnet evidence is supplied.
+
+## Render deployment
+
+The repository includes a Render Blueprint in `render.yaml`. It creates one Python web
+service in Frankfurt, installs the package, starts the dashboard on Render's assigned
+port, and checks `/healthz` before routing traffic. Automatic deployments wait for the
+linked commit's checks to pass.
+
+New Render services currently default to Python 3.14, which is outside this project's
+supported range. The existing committed `.python-version` intentionally selects Python
+3.11.
+
+1. In Render, choose **New > Blueprint**.
+2. Connect `ShieldTech-Ltd/SolGuard`.
+3. For a temporary review deployment, select `feature/stage-dashboard`. After the pull
+   request is reviewed and merged, deploy the protected integration branch instead.
+4. Confirm the Blueprint path is `render.yaml` and create the service.
+5. Wait for the health check to pass, then open the generated `onrender.com` URL.
+6. Run all four dashboard scenarios and confirm the page still says
+   **SIMULATED SETTLEMENT**.
+
+No wallet key, RPC credential, Pay.sh credential, or x402 secret is required or permitted
+for this hosted fallback. Do not add secrets to the Blueprint. A real devnet exercise is
+a separate, opt-in CLI path documented in `X402_LIVE_DEVNET.md`.
+
+## Local production-shaped check
+
+Run the same command shape used by Render:
+
+```bash
+uv run solguard-dashboard --host 0.0.0.0 --port 10000
+```
+
+Then verify:
+
+```bash
+curl http://127.0.0.1:10000/healthz
+```
+
+Expected response:
+
+```json
+{"service":"solguard-dashboard","settlement":"simulated","status":"ok"}
+```
+
+The dashboard state is intentionally process-local and resets on restart. This keeps the
+fallback deterministic and avoids presenting the prototype as durable production
+infrastructure.

docs/JUDGE_RUNBOOK.md

@@ -0,0 +1,111 @@
+# Judge demonstration runbook
+
+This runbook presents the live dashboard as evidence of the running gateway, not as a
+mock product animation. Use the guided mode so each screen is tied to one gateway result.
+
+## Before presenting
+
+1. Start `uv run solguard-dashboard` or open the verified hosted fallback.
+2. Confirm `/healthz` returns `status: ok`.
+3. Open the dashboard at a desktop width and select **Reset demo**.
+4. Confirm the header says **LIVE SECURITY ENGINE** and **SIMULATED SETTLEMENT**.
+5. Keep `uv run solguard-demo --skip-paysh` ready as a terminal fallback.
+
+Do not describe a settlement as real, devnet, or on-chain unless its transaction signature
+has been independently verified for that run.
+
+## Two-minute story
+
+### 1. State the problem
+
+> An autonomous agent can hold valid wallet access and still make a dangerous payment.
+> SolGuard decides whether that payment should reach the signer before money can move.
+
+Select **Start guided demo**. Point to the separation between the agent, SolGuard, the
+wallet boundary, and settlement.
+
+### 2. Allow ordinary commerce
+
+Run **Normal payment** and step through the request, integrity, mandate, behaviour, and
+authorization stages.
+
+Visible proof:
+
+- decision is `ALLOW`;
+- the request and policy digests come from the current event;
+- signing state is `SIGNED`; and
+- settlement is visibly labelled `SIMULATED`.
+
+Say: "The owner did not approve this payment manually. The agent operated inside a
+pre-approved mandate, so the gateway allowed it autonomously."
+
+### 3. Escalate uncertainty without stopping everything
+
+Run **First-seen recipient**.
+
+Visible proof:
+
+- decision is `REQUIRE_APPROVAL`;
+- the reason identifies recipient novelty; and
+- no signing authorization reaches the wallet.
+
+Say: "Autonomy is bounded, not removed. An unfamiliar but otherwise plausible payment is
+paused for approval instead of being silently signed."
+
+### 4. Prove integrity enforcement
+
+Run **Replay attack**.
+
+Visible proof:
+
+- the reused request is `BLOCK`;
+- the reason is `REQUEST_REPLAYED`; and
+- signing state remains `NOT_SIGNED`.
+
+Say: "A valid-looking payment cannot be reused with the same per-agent nonce."
+
+### 5. Trigger the memorable attack
+
+Run **Compound drain** and advance to the behaviour, wallet, and evidence stages.
+
+Visible proof:
+
+- the decision is `BLOCK`;
+- the reasons include compound drain, new recipient, and high velocity;
+- the wallet is `NOT_SIGNED` and has no settlement reference;
+- the simulated wallet balance does not fall for the blocked request;
+- the email and bearer token are redacted; and
+- the receipt chain verifies.
+
+Say: "The important output is not the red alert. It is the missing signature. The blocked
+request never crossed the wallet boundary."
+
+### 6. Close with the product
+
+> Payment protocols answer how an agent can pay. SolGuard answers whether that agent
+> should be allowed to pay. We are looking for an agent platform or wallet partner to
+> validate this pre-signing boundary with its own sandbox payment intents.
+
+## If the network or hosted page fails
+
+1. Start the local dashboard and repeat the same four controls.
+2. If a browser is unavailable, run `uv run solguard-demo --skip-paysh` and show the
+   emitted decisions and invariants.
+3. Use the recorded evidence package only as clearly labelled backup footage.
+
+Never replace a failed external integration with an unlabelled simulation. Reliability is
+part of the demonstration; accurate labels preserve reviewer trust.
+
+## Fast reviewer questions
+
+- **Is settlement real?** The hosted fallback uses simulated settlement. The security
+  decisions, signing-state outcome, sanitized receipt, and dashboard metrics are computed
+  by the running local gateway.
+- **Can blocked traffic poison the baseline?** No. The behaviour engine learns recipients
+  and amounts only from approved traffic.
+- **What stops replay?** Freshness and per-agent nonce checks run before policy and signing.
+- **What happens if a control fails?** The gateway fails closed and does not issue signing
+  authorization.
+- **Is this production-ready?** No. Durable replay coordination, multi-tenant isolation,
+  authenticated administration, hardened key custody, high availability, and independent
+  security review remain production work.

render.yaml

@@ -0,0 +1,10 @@
+services:
+  - type: web
+    name: solguard-demo
+    runtime: python
+    plan: free
+    region: frankfurt
+    buildCommand: pip install .
+    startCommand: solguard-dashboard --host 0.0.0.0 --port $PORT
+    healthCheckPath: /healthz
+    autoDeployTrigger: checksPass

src/solguard/dashboard.py

@@ -392,6 +392,8 @@ class DashboardRequestHandler(BaseHTTPRequestHandler):
     """Serve static dashboard assets and local scenario endpoints."""
 
     server: DashboardServer
+    server_version = "SolGuard"
+    sys_version = ""
 
     _ASSETS: ClassVar[dict[str, tuple[str, str]]] = {
         "/": ("index.html", "text/html; charset=utf-8"),
@@ -402,6 +404,15 @@ class DashboardRequestHandler(BaseHTTPRequestHandler):
 
     def do_GET(self) -> None:
         path = urlparse(self.path).path
+        if path == "/healthz":
+            self._send_json(
+                {
+                    "service": "solguard-dashboard",
+                    "settlement": "simulated",
+                    "status": "ok",
+                }
+            )
+            return
         if path == "/api/state":
             self._send_json(self.server.runtime.snapshot())
             return
@@ -469,7 +480,15 @@ def _send_bytes(
         self.send_header("Content-Length", str(len(body)))
         self.send_header("Cache-Control", "no-store")
         self.send_header("X-Content-Type-Options", "nosniff")
-        self.send_header("Content-Security-Policy", "default-src 'self'; connect-src 'self'")
+        self.send_header(
+            "Content-Security-Policy",
+            "default-src 'self'; base-uri 'none'; connect-src 'self'; "
+            "form-action 'none'; frame-ancestors 'none'; object-src 'none'",
+        )
+        self.send_header("Cross-Origin-Resource-Policy", "same-origin")
+        self.send_header("Permissions-Policy", "camera=(), microphone=(), geolocation=()")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.send_header("X-Frame-Options", "DENY")
         self.end_headers()
         self.wfile.write(body)
 

tests/test_dashboard.py

@@ -283,6 +283,25 @@ def test_server_delivers_dashboard_assets(path: str, content_type: str, marker:
     assert headers["Cache-Control"] == "no-store"
     assert headers["X-Content-Type-Options"] == "nosniff"
     assert "default-src 'self'" in headers["Content-Security-Policy"]
+    assert "frame-ancestors 'none'" in headers["Content-Security-Policy"]
+    assert headers["Cross-Origin-Resource-Policy"] == "same-origin"
+    assert headers["Permissions-Policy"] == "camera=(), microphone=(), geolocation=()"
+    assert headers["Referrer-Policy"] == "no-referrer"
+    assert headers["X-Frame-Options"] == "DENY"
+    assert headers["Server"].strip() == "SolGuard"
+
+
+def test_server_exposes_dependency_free_health_check() -> None:
+    with running_server(runtime()) as base:
+        status, body, headers = get(f"{base}/healthz")
+
+    assert status == 200
+    assert json.loads(body) == {
+        "service": "solguard-dashboard",
+        "settlement": "simulated",
+        "status": "ok",
+    }
+    assert headers["Cache-Control"] == "no-store"
 
 
 def test_stage_dashboard_packages_visible_enforcement_proof() -> None: