From c73fe67e8124d8583c0650e555c253d8d0f9b0b2 Mon Sep 17 00:00:00 2001
From: jedarden <github@jedarden.com>
Date: Thu, 23 Apr 2026 21:31:24 -0400
Subject: [PATCH] feat(bd-ch6.4): add startup warning and token rotation docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Warn at startup when FABRIC_AUTH_TOKEN is unset so operators know
  POST /api/events is open to any local process; surfaced before
  "Press Ctrl+C to stop" so it's visible in systemd journal
- Add "Token rotation" section to README with step-by-step procedure:
  generate new secret, update secrets.env (0600), restart service,
  verify 401 enforcement; notes that NEEDLE workers reload on next task
  start when auth_token uses \${FABRIC_AUTH_TOKEN} substitution

The full auth chain is now in place end-to-end:
  ~/.config/fabric/secrets.env (0600) → EnvironmentFile →
  FABRIC_AUTH_TOKEN env var → server auth middleware → 401/403 on
  unauthenticated POST; NEEDLE config auth_token: "\${FABRIC_AUTH_TOKEN}"
  routes worker events through the same token.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md         | 27 +++++++++++++++++++++++++++
 src/web/server.ts |  7 +++++++
 2 files changed, 34 insertions(+)

diff --git a/README.md b/README.md
index e3cc6f2..424f997 100644
--- a/README.md
+++ b/README.md
@@ -127,6 +127,33 @@ curl -X POST http://localhost:3000/api/events \
 
 If no auth token is configured, all POST requests are accepted without authentication (suitable for local-only use).
 
+#### Token rotation
+
+To rotate `FABRIC_AUTH_TOKEN` with zero dropped events:
+
+```bash
+# 1. Generate a new token
+NEW_TOKEN=$(openssl rand -hex 32)
+
+# 2. Write it to the secrets file (0600 — not readable by other users)
+install -m 0600 /dev/null ~/.config/fabric/secrets.env
+echo "FABRIC_AUTH_TOKEN=${NEW_TOKEN}" > ~/.config/fabric/secrets.env
+
+# 3. Update ~/.needle/config.yaml if the old token was hard-coded there
+#    (if using ${FABRIC_AUTH_TOKEN} substitution, no change needed)
+
+# 4. Restart the service so FABRIC picks up the new token
+systemctl --user restart fabric-web
+
+# 5. Confirm the service is using the new token
+systemctl --user status fabric-web
+curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/api/events \
+  -X POST -H 'Content-Type: application/json' -d '{}'
+# Expected: 401 (auth enforced)
+```
+
+NEEDLE workers reload their config on the next task start — no restart needed on the worker side when `auth_token: "${FABRIC_AUTH_TOKEN}"` is used.
+
 ### Option 2: OTLP (recommended for multi-host or production)
 
 NEEDLE ships with an `otlp` feature (enabled by default in `Cargo.toml`) that exports telemetry over the standard OpenTelemetry OTLP protocol. No rebuild or extra flags are needed — just set two environment variables before launching workers:
diff --git a/src/web/server.ts b/src/web/server.ts
index 6a64287..1dfd85f 100644
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -633,6 +633,13 @@ export function createWebServer(options: WebServerOptions): WebServer {
       console.log(`FABRIC Web Dashboard running at http://localhost:${port}`);
       console.log(`API: http://localhost:${port}/api/`);
       console.log(`Watching: ${logPath}`);
+      if (!authToken) {
+        console.warn(
+          'WARNING: FABRIC_AUTH_TOKEN is not set. ' +
+          'POST /api/events is unauthenticated and accepts events from any process. ' +
+          'Set FABRIC_AUTH_TOKEN (or --auth-token) before exposing FABRIC outside localhost.'
+        );
+      }
       console.log('Press Ctrl+C to stop');
       emitter.emit('start');
     });