n_signer/documents/FIPS_DEPLOYMENT.md

FIPS_DEPLOYMENT.md

1. Scope

This runbook covers a practical Tier-1 deployment of nsigner over a TCP listener, with connectivity provided by FIPS as the network substrate.

Tier-1 objective:

• Keep nsigner transport simple (--listen tcp:IPv4:PORT or --listen tcp:[IPv6]:PORT).
• Use FIPS to carry traffic between peers.
• Do not add FIPS runtime dependencies into nsigner.

Out of scope in this document:

• Mandatory transport-level TLS/authentication hardening (still planned for a later phase).
• Automatic caller->npub enrichment from FIPS session metadata.

---

2. Architecture

Two cooperating layers:

1. Signer process layer (nsigner)

   • Listens on operator-selected TCP endpoint (IPv4 or IPv6).
   • 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 the configured signer TCP endpoint.

Conceptually:

client app -> local FIPS endpoint -> FIPS mesh -> remote FIPS endpoint -> signer TCP endpoint -> 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 TCP listen mode:

./build/nsigner --listen tcp:[::]:11111

Or bind to a specific FIPS ULA address:

./build/nsigner --listen tcp:[fd00::1234]:11111

Behavior notes:

• Bind target is operator-controlled; pick the narrowest reachable address that satisfies your topology.
• 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 a deliberate signer endpoint ([::]:PORT for broad reach, or specific fd.. for tighter scope).
2. Configure FIPS service/forwarding so remote authenticated peer traffic is delivered to that signer 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 -> configured signer 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:

{"id":"1","method":"get_public_key","params":[]}

Expected response:

{"id":"1","result":"<hex_pubkey>"}

6.2 Signing check

Send sign_event with explicit role selector:

{
  "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

• Prefer binding to a specific FIPS IPv6 ULA (fd..) rather than wildcard ([::]) when possible.
• 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:[IPv6]:PORT.

Fix:

• Use valid numeric port and valid IPv4/IPv6 literal host.

8.2 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.3 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.