n_signer/documents/FIPS_DEPLOYMENT.md

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:

./build/nsigner --listen tcp:127.0.0.1:8080

Or IPv6 loopback:

./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:

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

• 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.