Follow-up to #652: remaining wallet-security hardening (key-export route, per-route lockout, passphrase rotation, mTLS)

[fengtality]

Follow-up to #652. PR #659 addressed the highest-value items — at-rest KDF (scrypt + AES-256-GCM), loopback-by-default bind, opt-in API token, rate-limit loopback allow-list + ban, and /docs gating. This issue tracks the remaining hardening that was intentionally left out of that PR to keep it focused and reviewable.

1. Remove the networked private-key export from the HTTP API (#652 §1, remainder)

A "reveal raw private key" endpoint should never be reachable over the network, even when authenticated. Make it a CLI / localhost-only operation (a script that reads the encrypted store locally), or hard-restrict it to loopback and the API token. Pulling key export off the wire is the single highest-impact route to remove.

2. Per-route strict rate-limit + credential-keyed lockout (#652 §2, remainder)

PR #659 added a global, loopback-allow-listed limiter with ban. Auth-gated fund-moving routes should additionally carry tighter per-route limits (e.g. 3–5 attempts / 15 min) with exponential backoff/lockout. Note: 2025–2026 credential-stuffing bots rotate IPs/fingerprints, so lockout keyed only on source IP is weak — consider keying on the credential/identity as well.

3. Passphrase rotation without re-encrypting every wallet (KEK/DEK)

Today the Gateway passphrase is used directly as the encryption key for every keystore, so rotating it requires decrypting and re-encrypting every wallet. The standard fix is a random per-Gateway data-encryption key (DEK) wrapped by a passphrase-derived key-encryption key (KEK): rotating the passphrase then only re-wraps the DEK, not each wallet — and makes passphrase rotation a clean first-class operation.

4. Optional mTLS for networked deployments

For genuinely multi-client / networked setups, mutual TLS is stronger than a shared bearer token. Lower priority than the above for the single-user local case.

Notes

• The same "bind to loopback by default; expose only behind a VPN/overlay" principle should be reflected in the deployment docs for Gateway's companion services (message broker, database), which are commonly published on all interfaces.
• Threat model and rationale for the fix / harden Gateway wallet security — at-rest KDF, loopback bind, opt-in API auth, rate-limiting (#652) #659 changes are documented in docs/security-hardening.md (added in fix / harden Gateway wallet security — at-rest KDF, loopback bind, opt-in API auth, rate-limiting (#652) #659).

Refs: #652, #659

[ipezygj]

Went through the current development wallet-auth surface against the §1–§4 items here. One concrete gap on §2, plus two notes:

§2 — rate-limit vs auth trust asymmetry (the brute-force path). The onRequest auth hook trusts loopback only (isLoopbackAddress), but the global rate limiter allow-lists the whole private range (isTrustedLocalAddress → 10/8, 172.16/12, 192.168/16). So a LAN/compose-adjacent source must present the token (it isn't loopback) yet is never throttled — it can guess the token against the sensitive routes at unlimited rate. That's the "lockout after N failed attempts" this item calls for, and it also contradicts the gateway-security.ts header note that strict rate-limiting/lockout applies only to non-loopback requests.

Opened #663 for it: an IP-keyed failed-attempt lockout in the auth hook (only failed token checks count, so legitimate authenticated bot traffic — including a sibling container the limiter allow-lists — is untouched), plus a non-fatal warning when an operator-set GATEWAY_API_KEY is weak (<16 chars). Left the general limiter as-is so bot throughput is unchanged. As you note here, IP-keyed lockout doesn't stop IP-rotating attackers — credential-keyed lockout / per-route limits could layer on top.

§1 (private-key export): I couldn't find a networked key-export/reveal route in src/wallet/routes/* (get / add / addHardwareWallet / remove / setDefault only) — looks already resolved on development; worth a confirm.

Separate note (not this issue): all of #659 currently lives on development — main still binds 0.0.0.0 unconditionally and lacks the auth hook / hardened keystore KDF, so anyone deploying from main (or a release cut from it) is still exposed to the #652 scenario until this lands on main.