Per-endpoint matrix

The + x402 cells reflect Phase C of the active plan, which lands after the hard gate. Phase B (this runbook) only handles the session boundary.

Files modified

Rollout sequence

1. Land Phase A docs first. This runbook + the three "as a service"

1. Apply code changes on a feature branch (hard-arrival-gate).

1. Run the full test suite locally:

   python -m pytest tests/ -q
   

1. Smoke locally:

   ./mindX.sh --frontend
   # Visit http://localhost:3000 — should redirect to /login
   # Visit http://localhost:8000/feedback.html — should 302 to /login
   # Visit http://localhost:8000/docs.html — should 200 (public)
   curl -sI http://localhost:8000/coordinator/query \
        -X POST -d '{"q":"test"}'
   # Should return 401 with auth_required JSON
   

1. Deploy to staging (if a staging VPS exists; otherwise to

1. Smoke production (see §"Verification" below).
2. Announce the change via the mindx.pythai.net public docs +

Verification (post-deploy)

Public surfaces stay public

for path in /login /docs.html /automindx /shadow-overlord; do
  code=$(curl -sI -o /dev/null -w "%{http_code}" https://mindx.pythai.net$path)
  echo "$path → $code"   # expect 200 for all
done

Gated surfaces redirect

for path in /feedback.html /journal /dojo /boardroom /book /cabinet; do
  redirect=$(curl -sI https://mindx.pythai.net$path | grep -i ^location)
  echo "$path → $redirect"   # expect /login?from=$path
done

API surfaces return JSON 401

curl -s -o /tmp/resp -w "%{http_code}" https://mindx.pythai.net/coordinator/query \
  -X POST -H "Content-Type: application/json" -d '{}'
expect 401
cat /tmp/resp | jq '.code'  # expect "auth_required"

A logged-in session works end-to-end

# 1. Get challenge
WALLET=0xYourTestWallet
CHALL=$(curl -s -X POST https://mindx.pythai.net/users/challenge \
  -H "Content-Type: application/json" -d "{\"wallet\":\"$WALLET\"}" | jq -r '.challenge')

2. Sign with metamask / eth_account, then:
SIG=0xYourSignature
TOKEN=$(curl -s -X POST https://mindx.pythai.net/users/register-with-signature \
  -H "Content-Type: application/json" \
  -d "{\"wallet\":\"$WALLET\",\"challenge\":\"$CHALL\",\"signature\":\"$SIG\"}" \
  | jq -r '.session_token')

3. Hit a gated endpoint with the token
curl -sI -H "X-Session-Token: $TOKEN" https://mindx.pythai.net/feedback.html \
  | head -1
expect HTTP/. 200

ssh root@mindx.pythai.net "
  echo 'MINDX_HARD_GATE_ENABLED=0' >> /home/mindx/mindX/.env &&
  systemctl restart mindx.service
"

scp <previous-main-service.py-version> root@mindx.pythai.net:/home/mindx/mindX/mindx_backend_service/main_service.py
ssh root@mindx.pythai.net "chown mindx:mindx /home/mindx/mindX/mindx_backend_service/main_service.py && systemctl restart mindx.service"

/wp-json/ callbacks from rage.pythai.net are signature-authed at the plugin layer, not at the session-token layer. They must stay in _PUBLIC_PREFIXES. Symptom of getting this wrong: rage publishes start failing with 401s in the WordPress agent logs.

3. The from= parameter must round-trip

When /login completes auth, it reads the from query param and redirects to that path. If the param is missing or unsanitized, you get either a useless / redirect or an open-redirect vulnerability. The implementation must:

• URL-decode from before redirecting
• Validate from is a relative path on the same origin (rejects

• Default to / if from is missing or invalid

4. CORS preflight gets gated

Browser OPTIONS requests from the frontend on port 3000 to the backend on port 8000. The CORS middleware must run before the arrival-gate middleware in the FastAPI middleware stack, otherwise preflights 302 to /login and the browser blocks the actual request.

5. Permissions endpoint always public

/users/{wallet}/permissions must stay public — login.html calls it to know whether to show "Sign In" or "Welcome back" without the user having a session yet. If you gate it, the login page hangs.

Per-tier behavior summary

The shadow_overlord tier is operator-only. Per the user-locked two-tier-minimum decision, no intermediate admin / dojo / council tiers exist — those are cosmetic badges on the logged-in tier, not gates.

Observability

Every gated redirect emits a catalogue event:

{"event_id":"...","kind":"auth.gate.redirect","actor":"mindx.gateway",
 "at":1778712345,
 "payload":{"path":"/feedback.html","reason":"no_session","ip_hash":"sha256:..."},
 "source_log":"data/logs/catalogue_events.jsonl"}

Query the live volume:

curl -fsS 'https://mindx.pythai.net/insight/catalogue/recent?kind=auth.gate.redirect&h=true'

If the redirect rate spikes 10× post-deploy, investigate — likely a linkable surface (/journal in an email, /feedback.html in a tweet) is now redirecting visitors who used to land on those pages without auth. That's expected; the question is whether you've also broken a legitimate flow.

What stays the same

• The session-token mechanism itself (EIP-191 personal_sign → JWT).

• The shadow-overlord ECDSA gate. Untouched.
• The login page UX. Card grid stays; admin cards just disappear.
• The permissions endpoint shape (still returns capabilities), but

• Public docs at mindx.pythai.net/docs.html. Reading is free.

What this enables

Once the hard gate is in place:

• Phase C (x402 paywall) can apply per-endpoint pricing

• Phase D (cypherpunk2048 article) can cite the hard gate as a

• Phase E (live contract deploys) can rely on session-attributed

References

• docs/services/mindx_as_a_service.md

• docs/services/x402_as_a_service.md

• docs/BEST_PRACTICES.md §4 (secrets hygiene),

• mindx_backend_service/main_service.py:1662-1710 — the

• mindx_backend_service/bankon_vault/shadow_overlord.py — the

— mindX, closing the front door.