v0.0.20 - Implement TCP auth envelope verification with signed caller pubkey identity, replay protection, tests, and deferred NIP-46 bunker plan

documents/CLIENT_IMPLEMENTATION.md

@@ -10,10 +10,11 @@ It is written for agent/tool authors implementing robust request flows against t
 
 ## 2. Discovery and socket targeting
 
-`nsigner` currently supports two transport families:
+`nsigner` currently supports three transport families:
 
 - Linux AF_UNIX **abstract namespace** sockets.
 - Stdio framed mode (`--listen stdio` and `--listen qrexec`) for one request/response exchange.
+- TCP framed mode (`--listen tcp:IPv4:PORT` or `--listen tcp:[IPv6]:PORT`).
 
 For AF_UNIX:
 
@@ -54,6 +55,14 @@ In server mode:
 
 This mode is server-side only in the current CLI (the `client` subcommand still targets AF_UNIX).
 
+### 2.4 TCP mode authentication (required)
+
+For TCP transport, requests MUST include an `auth` object containing a signed Nostr-style event envelope.
+
+- Missing `auth` returns `{"error":{"code":2014,"message":"auth_envelope_required"}}`.
+- Signature verification, method/id/body binding, timestamp skew checks, and replay checks are enforced before policy lookup.
+- On success, caller identity is normalized to `pubkey:<hex>` for policy checks.
+
 ---
 
 ## 3. Transport framing
@@ -147,6 +156,14 @@ Representative error names clients must handle:
 - `unauthorized`
 - `approval_denied`
 - `internal_error`
+- `auth_envelope_malformed` (2010)
+- `auth_body_mismatch` (2011)
+- `auth_signature_invalid` (2012)
+- `auth_kind_invalid` (2013)
+- `auth_envelope_required` (2014)
+- `auth_envelope_mismatch` (2015)
+- `auth_envelope_stale` (2016)
+- `auth_replay_detected` (2017)
 
 ### 5.1 Recovery guidance
 
@@ -158,6 +175,7 @@ Representative error names clients must handle:
 - `unauthorized`: caller identity disallowed by policy; do not blind-retry.
 - `approval_denied`: user rejected prompt; treat as final unless user initiates retry.
 - `internal_error`: bounded retry with backoff; surface diagnostics.
+- `auth_envelope_*` / `auth_*` (2010-2017): fix request signing/auth envelope generation; do not blind-retry unchanged payloads.
 
 ---
 

documents/SECURITY.md

@@ -428,9 +428,10 @@ Different transports give different identity quality. The wire format (4-byte le
 
 ### 11.3 TCP (advanced / opt-in)
 
-- Loopback addresses produce `tcp_local` identities. Remote addresses produce `tcp_remote` identities.
-- Identity is **transport-asserted only**. The TCP peer address proves a route, not a principal.
-- For TCP transports the **interactive approval prompt is the real authentication mechanism**. Do not enable TCP transports without a trustworthy local terminal.
+- Loopback and remote TCP callers must present a valid signed auth envelope.
+- Identity is normalized to caller `pubkey:<hex>` after signature verification; TCP peer address is context only.
+- The auth gate runs before policy: missing/invalid envelopes are rejected with `2010..2017` auth errors.
+- Prompt-driven approval still applies after auth; auth answers "who is calling", policy answers "is this caller allowed".
 
 ### 11.4 Future transports