@wipcomputer/wip-ldm-os 0.4.85-alpha.2 → 0.4.85-alpha.21

package/src/hosted-mcp/deploy.sh

@@ -1,70 +1,321 @@
 #!/usr/bin/env bash
-# deploy.sh: Deploy hosted MCP server to wip.computer
+# deploy.sh: Deploy hosted MCP server + nginx config to wip.computer.
+#
+# Writes a JSON provenance manifest to
+#   /var/www/wip.computer/deploy-manifests/hosted-mcp/<timestamp>.json
+# on the VPS per F-009 of the VPS hosted-mcp audit
+# (ai/product/bugs/security/2026-04-28--cc-mini--vps-hosted-mcp-audit.md).
+#
+# Manifest fields:
+#   deployedAt, deployedBy, git (remote + branch + commit + dirty),
+#   files[] (source, destination, sha256),
+#   nginx (test_pass, test_output) when nginx is deployed,
+#   pm2 (pid, status, restart_time, exec_path) when app is deployed.
+#
+# Usage:
+#   bash deploy.sh                       # deploy app + nginx + manifest
+#   bash deploy.sh --dry-run             # preview, no scp/reload/restart
+#   bash deploy.sh --allow-dirty         # allow uncommitted changes
+#   bash deploy.sh --skip-nginx          # only deploy Node app
+#   bash deploy.sh --skip-app            # only deploy nginx config
+#   bash deploy.sh --remote host         # override SSH host (default: wip.computer)
 #
 # Prerequisites:
-#   - SSH config has Host wip.computer
+#   - SSH config has Host wip.computer with key auth
+#   - VPS user has passwordless sudo for nginx + systemctl reload
 #   - pm2 installed on the server
-#   - nginx configured on the server
-#
-# Usage: bash deploy.sh
+#   - python3 and shasum/sha256sum available locally
 
 set -euo pipefail
 
+# ── Args ────────────────────────────────────────────────────────────
+
+DRY_RUN=0
+ALLOW_DIRTY=0
+SKIP_NGINX=0
+SKIP_APP=0
 REMOTE="wip.computer"
-REMOTE_DIR="/var/www/wip.computer/app/mcp-server"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)     DRY_RUN=1; shift ;;
+    --allow-dirty) ALLOW_DIRTY=1; shift ;;
+    --skip-nginx)  SKIP_NGINX=1; shift ;;
+    --skip-app)    SKIP_APP=1; shift ;;
+    --remote)      REMOTE=$2; shift 2 ;;
+    -h|--help)     sed -n '2,30p' "$0"; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+APP_REMOTE_DIR="/var/www/wip.computer/app/mcp-server"
+NGINX_SNIPPETS_DIR="/etc/nginx/snippets"
+NGINX_CONFD_DIR="/etc/nginx/conf.d"
+MANIFEST_DIR="/var/www/wip.computer/deploy-manifests/hosted-mcp"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-echo "Deploying hosted MCP server to ${REMOTE}..."
-
-# 1. Create remote directory structure
-echo "Creating remote directories..."
-ssh "${REMOTE}" "mkdir -p ${REMOTE_DIR}/inbox"
-
-# 2. Copy server files
-echo "Copying files..."
-scp "${SCRIPT_DIR}/server.mjs" "${REMOTE}:${REMOTE_DIR}/"
-scp "${SCRIPT_DIR}/inbox.mjs" "${REMOTE}:${REMOTE_DIR}/"
-scp "${SCRIPT_DIR}/tools.mjs" "${REMOTE}:${REMOTE_DIR}/"
-scp "${SCRIPT_DIR}/package.json" "${REMOTE}:${REMOTE_DIR}/"
-
-# 3. Install dependencies
-echo "Installing dependencies..."
-ssh "${REMOTE}" "cd ${REMOTE_DIR} && npm install --omit=dev"
-
-# 4. Register with pm2 (restart if already running)
-echo "Starting with pm2..."
-ssh "${REMOTE}" "cd ${REMOTE_DIR} && pm2 delete mcp-server 2>/dev/null || true && pm2 start server.mjs --name mcp-server && pm2 save"
-
-# 5. Configure nginx reverse proxy
-echo "Configuring nginx..."
-ssh "${REMOTE}" "cat > /tmp/mcp-server.conf << 'NGINX'
-# MCP server reverse proxy
-# Location block to add inside the wip.computer server block
-location /mcp {
-    proxy_pass http://127.0.0.1:18800/mcp;
-    proxy_http_version 1.1;
-    proxy_set_header Host \$host;
-    proxy_set_header X-Real-IP \$remote_addr;
-    proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto \$scheme;
-
-    # SSE support (for MCP Streamable HTTP GET streams)
-    proxy_set_header Connection '';
-    proxy_buffering off;
-    proxy_cache off;
-    proxy_read_timeout 86400;
-    chunked_transfer_encoding on;
+# Pick whichever sha256 tool is available locally (macOS vs Linux).
+if command -v sha256sum >/dev/null 2>&1; then
+  SHA256_CMD="sha256sum"
+elif command -v shasum >/dev/null 2>&1; then
+  SHA256_CMD="shasum -a 256"
+else
+  echo "FATAL: neither sha256sum nor shasum found locally" >&2
+  exit 1
+fi
+
+# Pick python3 for JSON-escape helpers; fall back to node if absent.
+if command -v python3 >/dev/null 2>&1; then
+  json_escape() { python3 -c 'import sys,json;print(json.dumps(sys.stdin.read()),end="")'; }
+elif command -v node >/dev/null 2>&1; then
+  json_escape() { node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>process.stdout.write(JSON.stringify(d)));'; }
+else
+  echo "FATAL: neither python3 nor node found locally for JSON escaping" >&2
+  exit 1
+fi
+
+# ── Pre-deploy: git state ───────────────────────────────────────────
+
+REPO_ROOT="$(cd "${SCRIPT_DIR}" && git rev-parse --show-toplevel)"
+cd "${REPO_ROOT}"
+GIT_REMOTE_URL="$(git config --get remote.origin.url || echo 'unknown')"
+GIT_COMMIT="$(git rev-parse HEAD)"
+GIT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+GIT_DIRTY_LIST="$(git status --porcelain)"
+if [ -n "$GIT_DIRTY_LIST" ] && [ "$ALLOW_DIRTY" -ne 1 ]; then
+  echo "FATAL: working tree has uncommitted changes:" >&2
+  echo "$GIT_DIRTY_LIST" >&2
+  echo "Pass --allow-dirty to deploy anyway (dev only)." >&2
+  exit 1
+fi
+GIT_DIRTY=false
+[ -n "$GIT_DIRTY_LIST" ] && GIT_DIRTY=true
+
+# ── File inventory ──────────────────────────────────────────────────
+#
+# Two parallel arrays: SRC_FILES (relative to SCRIPT_DIR) and DST_FILES
+# (absolute path on remote). Plain bash arrays for macOS bash 3.2
+# compatibility.
+
+SRC_FILES=()
+DST_FILES=()
+SHA_FILES=()
+
+add_file() {
+  local src=$1 dst=$2
+  if [ ! -f "${SCRIPT_DIR}/${src}" ]; then
+    echo "WARN: ${src} not found locally; skipping" >&2
+    return
+  fi
+  SRC_FILES+=("$src")
+  DST_FILES+=("$dst")
+  SHA_FILES+=("$(${SHA256_CMD} "${SCRIPT_DIR}/${src}" | awk '{print $1}')")
+}
+
+if [ "$SKIP_APP" -ne 1 ]; then
+  add_file "server.mjs"   "${APP_REMOTE_DIR}/server.mjs"
+  add_file "inbox.mjs"    "${APP_REMOTE_DIR}/inbox.mjs"
+  add_file "tools.mjs"    "${APP_REMOTE_DIR}/tools.mjs"
+  add_file "codex-relay-e2ee-registry.mjs" "${APP_REMOTE_DIR}/codex-relay-e2ee-registry.mjs"
+  add_file "package.json" "${APP_REMOTE_DIR}/package.json"
+  # Phone app static files (codex-remote-control, login).
+  if [ -d "${SCRIPT_DIR}/app" ]; then
+    while IFS= read -r f; do
+      rel=${f#${SCRIPT_DIR}/}
+      add_file "$rel" "${APP_REMOTE_DIR}/${rel}"
+    done < <(find "${SCRIPT_DIR}/app" -type f | sort)
+  fi
+  # Kaleidoscope demo files (login.html, index.html, agent.html, etc.).
+  if [ -d "${SCRIPT_DIR}/demo" ]; then
+    while IFS= read -r f; do
+      rel=${f#${SCRIPT_DIR}/}
+      add_file "$rel" "${APP_REMOTE_DIR}/${rel}"
+    done < <(find "${SCRIPT_DIR}/demo" -type f | sort)
+  fi
+fi
+
+if [ "$SKIP_NGINX" -ne 1 ]; then
+  # Snippets included from the site config.
+  if [ -d "${SCRIPT_DIR}/nginx" ]; then
+    while IFS= read -r f; do
+      rel=${f#${SCRIPT_DIR}/nginx/}
+      base=$(basename "$f")
+      case "$rel" in
+        conf.d/*) add_file "nginx/${rel}" "${NGINX_CONFD_DIR}/${base}" ;;
+        wip.computer.conf) ;;  # site config: deploy manually, has carry-over
+        *) add_file "nginx/${rel}" "${NGINX_SNIPPETS_DIR}/${base}" ;;
+      esac
+    done < <(find "${SCRIPT_DIR}/nginx" -maxdepth 2 -type f -name '*.conf' | sort)
+  fi
+fi
+
+# ── Dry-run preview ─────────────────────────────────────────────────
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  echo "DRY RUN. Git: ${GIT_BRANCH} @ ${GIT_COMMIT} (dirty=${GIT_DIRTY})"
+  echo "Remote: ${REMOTE}"
+  echo "Files (${#SRC_FILES[@]}):"
+  for ((i=0; i<${#SRC_FILES[@]}; i++)); do
+    printf "  %-40s -> %s  [%s]\n" "${SRC_FILES[$i]}" "${DST_FILES[$i]}" "${SHA_FILES[$i]:0:12}"
+  done
+  echo ""
+  echo "Would write manifest to: ${MANIFEST_DIR}/$(date -u +%Y-%m-%dT%H-%M-%SZ).json"
+  exit 0
+fi
+
+if [ ${#SRC_FILES[@]} -eq 0 ]; then
+  echo "Nothing to deploy (both --skip-app and --skip-nginx, or no files matched)." >&2
+  exit 1
+fi
+
+# ── Deploy app files ────────────────────────────────────────────────
+
+# /var/www/wip.computer/ is root-owned; the manifest dir must be
+# created with sudo on first deploy. After creation, parker:parker
+# ownership lets subsequent deploys write the manifest without sudo.
+ssh "${REMOTE}" "sudo install -d -o parker -g parker -m 0755 ${MANIFEST_DIR}"
+
+if [ "$SKIP_APP" -ne 1 ]; then
+  ssh "${REMOTE}" "mkdir -p ${APP_REMOTE_DIR}/inbox"
+fi
+
+# scp each file. Pre-create destination dir on the remote so app/foo/bar.html
+# does not fail on missing parent.
+for ((i=0; i<${#SRC_FILES[@]}; i++)); do
+  src=${SRC_FILES[$i]}
+  dst=${DST_FILES[$i]}
+  case "$dst" in
+    /etc/nginx/*) need_sudo=1 ;;
+    *)            need_sudo=0 ;;
+  esac
+  remote_parent=$(dirname "$dst")
+  if [ "$need_sudo" -eq 1 ]; then
+    # Stage to a temp dir on remote, then sudo mv into place.
+    tmp="/tmp/deploy-staging-$$/$(basename "$src")"
+    ssh "${REMOTE}" "mkdir -p $(dirname "$tmp")"
+    scp "${SCRIPT_DIR}/${src}" "${REMOTE}:${tmp}"
+    ssh "${REMOTE}" "sudo install -m 0644 ${tmp} ${dst}"
+  else
+    ssh "${REMOTE}" "mkdir -p ${remote_parent}"
+    scp "${SCRIPT_DIR}/${src}" "${REMOTE}:${dst}"
+  fi
+done
+
+# Cleanup staging dir if it exists.
+ssh "${REMOTE}" "rm -rf /tmp/deploy-staging-$$" || true
+
+# ── Verify post-deploy hashes (transfer integrity) ──────────────────
+
+for ((i=0; i<${#SRC_FILES[@]}; i++)); do
+  remote_sha=$(ssh "${REMOTE}" "sudo sha256sum ${DST_FILES[$i]}" 2>/dev/null | awk '{print $1}' || echo "")
+  if [ "${SHA_FILES[$i]}" != "$remote_sha" ]; then
+    echo "FATAL: post-deploy hash mismatch for ${SRC_FILES[$i]}" >&2
+    echo "  local : ${SHA_FILES[$i]}" >&2
+    echo "  remote: ${remote_sha}" >&2
+    exit 1
+  fi
+done
+
+# ── npm install (app only) ──────────────────────────────────────────
+
+if [ "$SKIP_APP" -ne 1 ]; then
+  ssh "${REMOTE}" "cd ${APP_REMOTE_DIR} && npm install --omit=dev"
+fi
+
+# ── nginx test + reload (nginx only) ────────────────────────────────
+
+NGINX_TEST_PASS=null
+NGINX_TEST_OUTPUT_JSON='""'
+if [ "$SKIP_NGINX" -ne 1 ]; then
+  set +e
+  NGINX_TEST_OUTPUT=$(ssh "${REMOTE}" "sudo nginx -t" 2>&1)
+  NGINX_TEST_RC=$?
+  set -e
+  if [ "$NGINX_TEST_RC" -eq 0 ]; then
+    NGINX_TEST_PASS=true
+    ssh "${REMOTE}" "sudo systemctl reload nginx"
+  else
+    NGINX_TEST_PASS=false
+    echo "FATAL: nginx -t failed; not reloading." >&2
+    echo "$NGINX_TEST_OUTPUT" >&2
+  fi
+  NGINX_TEST_OUTPUT_JSON=$(printf '%s' "$NGINX_TEST_OUTPUT" | json_escape)
+fi
+
+# ── PM2 reload ──────────────────────────────────────────────────────
+
+PM2_INFO_JSON=null
+if [ "$SKIP_APP" -ne 1 ]; then
+  ssh "${REMOTE}" "cd ${APP_REMOTE_DIR} && (pm2 reload mcp-server || (pm2 start server.mjs --name mcp-server && pm2 save))"
+
+  # Capture pm2 status for the manifest.
+  PM2_RAW=$(ssh "${REMOTE}" "pm2 jlist" 2>/dev/null || echo "[]")
+  PM2_INFO_JSON=$(printf '%s' "$PM2_RAW" | python3 -c '
+import json,sys
+data=json.load(sys.stdin)
+target="mcp-server"
+for p in data:
+    if p.get("name")==target:
+        env=p.get("pm2_env",{})
+        print(json.dumps({
+            "name": p.get("name"),
+            "pid": p.get("pid"),
+            "status": env.get("status"),
+            "restart_time": env.get("restart_time"),
+            "uptime": env.get("pm_uptime"),
+            "exec_path": env.get("pm_exec_path"),
+            "node_version": env.get("node_version"),
+        }))
+        break
+else:
+    print("null")
+')
+fi
+
+# ── Build manifest ──────────────────────────────────────────────────
+
+DEPLOYED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+TIMESTAMP_SLUG=$(date -u +%Y-%m-%dT%H-%M-%SZ)
+DEPLOYED_BY="$(whoami)@$(hostname)"
+
+# files[] JSON
+FILES_JSON=""
+for ((i=0; i<${#SRC_FILES[@]}; i++)); do
+  [ "$i" -eq 0 ] || FILES_JSON+=","
+  FILES_JSON+=$(printf '{"source":"%s","destination":"%s","sha256":"%s"}' \
+    "${SRC_FILES[$i]}" "${DST_FILES[$i]}" "${SHA_FILES[$i]}")
+done
+
+MANIFEST=$(cat <<JSON
+{
+  "deployedAt": "${DEPLOYED_AT}",
+  "deployedBy": "${DEPLOYED_BY}",
+  "git": {
+    "remote": "${GIT_REMOTE_URL}",
+    "branch": "${GIT_BRANCH}",
+    "commit": "${GIT_COMMIT}",
+    "dirty": ${GIT_DIRTY}
+  },
+  "files": [${FILES_JSON}],
+  "nginx": {
+    "skipped": $([ "$SKIP_NGINX" -eq 1 ] && echo true || echo false),
+    "test_pass": ${NGINX_TEST_PASS},
+    "test_output": ${NGINX_TEST_OUTPUT_JSON}
+  },
+  "pm2": ${PM2_INFO_JSON}
 }
-NGINX
-"
+JSON
+)
+
+# ── Write manifest to VPS ───────────────────────────────────────────
+
+MANIFEST_PATH="${MANIFEST_DIR}/${TIMESTAMP_SLUG}.json"
+printf '%s\n' "$MANIFEST" | ssh "${REMOTE}" "sudo install -d -m 0755 ${MANIFEST_DIR} && sudo tee ${MANIFEST_PATH} > /dev/null && sudo chmod 0644 ${MANIFEST_PATH}"
 
 echo ""
-echo "nginx config written to /tmp/mcp-server.conf on the server."
-echo "To activate, add it to your server block and reload:"
-echo "  ssh ${REMOTE} 'sudo cp /tmp/mcp-server.conf /etc/nginx/snippets/mcp-server.conf'"
-echo "  # Then include it in your server block: include snippets/mcp-server.conf;"
-echo "  ssh ${REMOTE} 'sudo nginx -t && sudo systemctl reload nginx'"
+echo "Deploy complete."
+echo "Manifest: ${REMOTE}:${MANIFEST_PATH}"
 echo ""
-echo "Deployment complete."
-echo "Health check: curl https://wip.computer/health"
-echo "MCP endpoint: https://wip.computer/mcp"
+echo "Verify:"
+echo "  curl -fsS https://wip.computer/health"
+echo "  bash ${SCRIPT_DIR}/scripts/verify-deploy.sh ${MANIFEST_PATH}"

package/src/hosted-mcp/docs/self-host.md

@@ -0,0 +1,268 @@
+# Hosted Relay Self-Host Guide
+
+This guide explains how to inspect and run the hosted relay source that backs WIP-hosted services such as Codex Remote Control.
+
+The public source lives here:
+
+```text
+src/hosted-mcp
+```
+
+WIP's production relay runs at `wip.computer`. Self-hosting means running the same relay source on your own domain, with your own database, TLS certificate, process manager, and secrets.
+
+## What The Hosted Relay Does
+
+The hosted relay is a Node server with several surfaces:
+
+- hosted MCP over HTTP at `/mcp`;
+- OAuth and passkey login routes;
+- demo routes under `/demo`;
+- Codex Remote Control pairing and relay routes under `/api/codex-relay/*`;
+- health reporting at `/health`.
+
+For Codex Remote Control, the relay lets a local `codex-daemon` dial out to a public server. Browser and phone clients connect to that same public server. After E2EE setup, prompt text, assistant output, command output, and errors are carried as encrypted frames. The relay routes and authorizes frames, but it is not the place where Codex runs.
+
+## Current Self-Host Status
+
+The relay source is inspectable and runnable, but the non-WIP self-host story is not yet a one-command installer.
+
+Important current constraints:
+
+- `server.mjs` currently defaults `ISSUER_URL`, `MCP_RESOURCE_URL`, `RP_ID`, and `RP_ORIGIN` to `wip.computer`;
+- the nginx examples are written for the WIP production domain and filesystem layout;
+- the Codex Remote Control browser surface at `/codex-remote-control/<threadId>` is served by the WIP web app, not by the hosted-mcp Node process itself;
+- `codex-daemon` can point at a custom relay with environment variables, but a complete non-WIP phone/web UI deployment must also point at that same relay.
+
+That means a production self-host should treat this guide as the infrastructure map. Before broad use, parameterize or patch the WIP domain constants for your domain.
+
+## Prerequisites
+
+You need:
+
+- Node.js 20 or newer;
+- npm;
+- Postgres;
+- nginx or another reverse proxy that supports WebSocket upgrades;
+- TLS for your domain;
+- PM2 or another process manager;
+- a public domain such as `relay.example.com`.
+
+Optional demo surfaces may also need:
+
+- `OPENAI_API_KEY`;
+- `XAI_API_KEY`.
+
+Codex Remote Control relay operation does not require those demo keys.
+
+## Environment
+
+Start from:
+
+```bash
+cd src/hosted-mcp
+cp .env.example .env
+```
+
+Required:
+
+```bash
+DATABASE_URL=postgresql://kaleidoscope:YOUR_PASSWORD@localhost:5432/kaleidoscope
+```
+
+Common optional variables:
+
+```bash
+MCP_PORT=18800
+LDM_HOSTED_MCP_WS_ORIGIN_ALLOWLIST=https://relay.example.com
+LDM_HOSTED_MCP_RL_MINT=30
+LDM_HOSTED_MCP_RL_VALIDATE=60
+LDM_HOSTED_MCP_RL_STATUS=120
+```
+
+Development-only variables:
+
+```bash
+LDM_HOSTED_MCP_DEV_MODE=1
+LDM_HOSTED_MCP_ALLOW_WS_URL_TOKEN=1
+```
+
+Do not enable those development flags in production. Production should use Postgres and bearer or ticket authentication, not JSON fallback files or URL token fallback.
+
+## Database Setup
+
+Create a Postgres database and user for the relay. Then run Prisma from `src/hosted-mcp`:
+
+```bash
+npm install
+npx prisma generate
+npx prisma migrate deploy
+```
+
+The Prisma schema stores:
+
+- users;
+- WebAuthn credentials;
+- device tokens;
+- wallets;
+- API keys.
+
+Production should use Postgres. If Prisma cannot connect and `LDM_HOSTED_MCP_DEV_MODE` is not set, the server fails closed.
+
+## Local Smoke Test
+
+From `src/hosted-mcp`:
+
+```bash
+npm install
+node server.mjs
+```
+
+In another shell:
+
+```bash
+curl -fsS http://127.0.0.1:18800/health
+```
+
+Expected result: JSON health output from the Node process.
+
+## Process Management
+
+WIP production uses PM2 with:
+
+```text
+src/hosted-mcp/ecosystem.config.cjs
+```
+
+For a self-host:
+
+```bash
+cd src/hosted-mcp
+pm2 start ecosystem.config.cjs --update-env
+pm2 save
+pm2 status mcp-server
+```
+
+If you use another process manager, preserve the same contract:
+
+- run `server.mjs` from `src/hosted-mcp`;
+- provide `DATABASE_URL`;
+- keep the process alive across restarts;
+- preserve environment variables on reload;
+- verify `/health` after restart.
+
+## Deploy Helper
+
+WIP's production deploy helper is:
+
+```text
+src/hosted-mcp/deploy.sh
+```
+
+It copies `server.mjs`, supporting modules, static app/demo files, nginx snippets, and package metadata to WIP's VPS, then reloads nginx, reloads PM2, and writes a deploy manifest.
+
+For self-hosting, read it as an example of the file inventory and verification sequence. Do not run it unmodified unless your SSH host, remote directories, nginx layout, PM2 process name, and deploy-manifest path intentionally match the WIP production layout.
+
+## nginx, TLS, And Domain
+
+The production nginx examples live in:
+
+```text
+src/hosted-mcp/nginx
+```
+
+Key files:
+
+- `codex-relay.conf` contains the `/api/codex-relay/*`, `/pair`, and WebSocket proxy routes;
+- `mcp-oauth.conf` and `mcp-server.conf` contain hosted MCP and OAuth routes;
+- `wip.computer.conf` shows how WIP includes those snippets inside the public site config;
+- `conf.d/redact-logs.conf` defines the redacted access-log format.
+
+For self-hosting:
+
+1. Put TLS in front of your relay domain.
+2. Proxy HTTP routes to `http://127.0.0.1:18800`.
+3. Preserve WebSocket upgrade headers for `/api/codex-relay/web/` and `/api/codex-relay/daemon`.
+4. Use redacted logs so bearer tokens, relay tickets, and API keys do not land in access logs.
+5. Replace WIP paths and domains with your own.
+
+Minimum verification:
+
+```bash
+sudo nginx -t
+sudo systemctl reload nginx
+curl -fsS https://relay.example.com/health
+```
+
+## Pointing Codex Remote Control At A Custom Relay
+
+`codex-daemon` defaults to WIP's hosted relay. For a custom relay, set the relay endpoints before pairing and starting the daemon:
+
+```bash
+export CODEX_DAEMON_RELAY_HTTP=https://relay.example.com
+export CODEX_DAEMON_RELAY_WS=wss://relay.example.com/api/codex-relay/daemon
+codex-daemon link
+codex-daemon start
+```
+
+The MCP tool that creates browser links also defaults to WIP's hosted origin. Set this for sessions that should generate links for your relay domain:
+
+```bash
+export CODEX_REMOTE_CONTROL_ORIGIN=https://relay.example.com
+```
+
+A full non-WIP deployment also needs a browser or phone UI that serves `/codex-remote-control/<threadId>` and talks to the same relay routes. In WIP production, that UI is part of the Kaleidoscope web app.
+
+## Verify The Relay
+
+Use these checks after any deploy:
+
+```bash
+curl -fsS https://relay.example.com/health
+curl -fsS https://relay.example.com/api/codex-relay/state
+```
+
+For WIP production deploys, `scripts/verify-deploy.sh` verifies a deploy manifest against live remote file hashes:
+
+```bash
+bash src/hosted-mcp/scripts/verify-deploy.sh latest
+```
+
+That script assumes the WIP deploy-manifest layout unless you pass a different manifest and remote.
+
+## What Not To Copy From WIP Production
+
+Do not copy:
+
+- WIP `.env` files;
+- WIP Postgres credentials;
+- WIP API keys or `ck-` tokens;
+- WIP passkey, device, wallet, or user rows;
+- WIP PM2 process state;
+- WIP nginx certificate paths;
+- WIP domain constants without changing them for your domain;
+- WIP deploy manifests as proof of your deploy.
+
+Use the source shape, not WIP's production secrets or account data.
+
+## Production Checklist
+
+- Domain and TLS are live.
+- `DATABASE_URL` points at your Postgres database.
+- Prisma migrations have run.
+- `server.mjs` starts without `LDM_HOSTED_MCP_DEV_MODE`.
+- nginx proxies `/health`, `/mcp`, `/oauth/*`, `/api/codex-relay/*`, `/pair`, and WebSocket upgrades.
+- WebSocket origins are restricted with `LDM_HOSTED_MCP_WS_ORIGIN_ALLOWLIST`.
+- URL token fallback is disabled.
+- Access logs redact bearer tokens, relay tickets, and `ck-` values.
+- `codex-daemon link` completes against your domain.
+- `codex-daemon start` reports relay paired.
+- Browser links are generated for your domain, not `wip.computer`.
+
+## Open Work
+
+The remaining product work is to turn this infrastructure map into a first-class self-host installer:
+
+- parameterize issuer and WebAuthn relying party settings;
+- package the phone/web Remote Control UI for non-WIP domains;
+- add a guided `ldm` self-host profile;
+- add an end-to-end self-host smoke test that pairs a daemon and browser through a non-WIP domain.

package/src/hosted-mcp/nginx/codex-relay.conf

@@ -107,3 +107,28 @@ location /api/codex-relay/daemon {
     proxy_send_timeout 86400;
     proxy_buffering off;
 }
+
+# /pair (bare) ... fallback manual code entry. Without this, nginx falls
+# through to `location /` and returns the static homepage. Pairs with
+# server.mjs pair-page route that serves app/pair.html.
+location = /pair {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# /pair/<CODE> ... URL-first pair flow. Real daemon alphabet
+# (CODEX_PAIR_ALPHABET): A-Z minus I and O, digits 2-9. Length 6. L IS
+# included. Per plan 2026-04-30--cc-mini--pair-via-login-qr-flow.md,
+# constraints C1+C3 round 5.
+location ~ "^/pair/[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{6}$" {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}