v0.0.6 - Tier-1 TCP listener + FIPS deployment documentation

documents/FIPS_DEPLOYMENT.md

@@ -0,0 +1,185 @@
+# FIPS_DEPLOYMENT.md
+
+## 1. Scope
+
+This runbook covers a practical Tier-1 deployment of `nsigner` over a loopback TCP listener, with connectivity provided by FIPS as the network substrate.
+
+Tier-1 objective:
+
+- Keep `nsigner` transport simple (`--listen tcp:127.0.0.1:PORT` or `--listen tcp:[::1]:PORT`).
+- Use FIPS to carry traffic between peers.
+- Do not add FIPS runtime dependencies into `nsigner`.
+
+Out of scope in this document:
+
+- Remote non-loopback TCP exposure (`--allow-remote`, TLS) planned for later phase.
+- Automatic caller->npub enrichment from FIPS session metadata.
+
+---
+
+## 2. Architecture
+
+Two cooperating layers:
+
+1. **Signer process layer** (`nsigner`)
+   - Listens on loopback TCP only.
+   - Uses existing 4-byte big-endian framed JSON-RPC protocol.
+   - Keeps existing policy/prompt behavior.
+
+2. **Network substrate layer** (FIPS)
+   - Establishes peer connectivity between nodes/qubes.
+   - Carries application traffic to a local loopback endpoint on each side.
+
+Conceptually:
+
+`client app -> local FIPS endpoint -> FIPS mesh -> remote FIPS endpoint -> 127.0.0.1:PORT -> nsigner`
+
+---
+
+## 3. Prerequisites
+
+On signer host/qube:
+
+- Built `nsigner` binary.
+- FIPS installed and running.
+- Local firewall policy that keeps signer listener local-only.
+
+On caller host/qube:
+
+- FIPS installed and peered with signer host/qube.
+- A client implementation that speaks `nsigner` framed JSON-RPC (see `documents/CLIENT_IMPLEMENTATION.md`).
+
+Operational assumptions:
+
+- Operator controls both endpoints.
+- Manual verification of peer identity is performed in FIPS tooling before enabling signer traffic.
+
+---
+
+## 4. Start signer in Tier-1 TCP mode
+
+Run `nsigner` in loopback TCP listen mode:
+
+```bash
+./build/nsigner --listen tcp:127.0.0.1:8080
+```
+
+Or IPv6 loopback:
+
+```bash
+./build/nsigner --listen tcp:[::1]:8080
+```
+
+Behavior notes:
+
+- Non-loopback values are rejected by design.
+- No TUI hotkey loop is required in TCP mode; process serves requests until terminated.
+- Caller identity is shown as a TCP endpoint descriptor in activity/prompt context.
+
+---
+
+## 5. FIPS substrate wiring pattern
+
+Because FIPS deployment topologies vary, use this generic pattern:
+
+1. Bind `nsigner` on loopback in signer environment.
+2. Configure FIPS service/forwarding so remote authenticated peer traffic is delivered to that loopback endpoint.
+3. On caller side, direct client traffic to the local FIPS ingress endpoint for that remote service.
+
+Validation checklist:
+
+- FIPS session is established between caller and signer nodes.
+- Transport path from caller -> signer loopback endpoint succeeds.
+- `nsigner` receives framed request and returns framed response.
+
+---
+
+## 6. Minimal validation flow
+
+### 6.1 Liveness check
+
+From caller side, send a framed `get_public_key` request through the FIPS-backed endpoint.
+
+Request JSON:
+
+```json
+{"id":"1","method":"get_public_key","params":[]}
+```
+
+Expected response:
+
+```json
+{"id":"1","result":"<hex_pubkey>"}
+```
+
+### 6.2 Signing check
+
+Send `sign_event` with explicit role selector:
+
+```json
+{
+  "id": "2",
+  "method": "sign_event",
+  "params": ["<event_json>", {"role":"main"}]
+}
+```
+
+Expected result: signed event JSON in `result`.
+
+### 6.3 Negative check (policy)
+
+Trigger a request path that requires prompt/denial and confirm client handles policy denial as a normal result path.
+
+---
+
+## 7. Security guardrails
+
+- Keep listener loopback-only in Tier-1.
+- Do not expose signer port directly on LAN/WAN.
+- Keep FIPS peer allowlist tight; avoid broad trust domains.
+- Treat FIPS connectivity as transport, not authorization bypass.
+- Preserve interactive approval where required by policy.
+
+---
+
+## 8. Troubleshooting
+
+### 8.1 `invalid tcp listen target`
+
+Cause:
+- `--listen` argument does not match `tcp:HOST:PORT` or `tcp:[::1]:PORT`.
+
+Fix:
+- Use explicit loopback host and valid numeric port.
+
+### 8.2 `non-loopback TCP bind denied`
+
+Cause:
+- Attempt to bind non-loopback target in Tier-1 mode.
+
+Fix:
+- Switch to `127.x.x.x` or `::1` target.
+
+### 8.3 Framing parse failures (`parse_error`)
+
+Cause:
+- Client sent line-delimited/raw JSON instead of framed JSON.
+
+Fix:
+- Send 4-byte big-endian length prefix followed by exact UTF-8 JSON payload bytes.
+
+### 8.4 FIPS path up, signer path down
+
+Cause:
+- FIPS session exists but forwarding/service mapping to signer loopback endpoint is missing.
+
+Fix:
+- Verify substrate service routing config and local endpoint mapping.
+
+---
+
+## 9. Next hardening steps (post Tier-1)
+
+- Add automated two-node validation script for operator smoke checks.
+- Add optional identity enrichment from FIPS session metadata (`peer_npub`).
+- Introduce remote TCP mode only with mandatory TLS + authenticated caller key flow.