laantungir/signer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 12 Wiki Activity
Files
7bc367e69562e69aeee310285dcfab428d94a6fc
signer/plans/port_nsigner_to_rust.md
T

19 KiB
Raw Blame History

n_signer → Rust Port Implementation Plan

Overview

Port the C-based n_signer (located at ~/lt/n_signer) to Rust, targeting x86_64 Linux only. Microcontroller implementations (ESP32, KB2040, etc.) are excluded. The Rust port will use ~/lt/nostr_core_lib_rust as the crypto/Nostr protocol library.

Architecture

graph TB
    subgraph "n_signer_rust"
        Main[main.rs<br/>CLI + startup + TUI loop]
        Main --> SecureMem
        Main --> Mnemonic
        Main --> RoleWizard
        Main --> Server
        Main --> Policy

        SecureMem[secure_mem.rs<br/>mlock + zeroize]
        Mnemonic[mnemonic.rs<br/>BIP-39 via nips::nip006]

        RoleTable[role_table.rs<br/>role entries + path templates]
        Selector[selector.rs<br/>role resolution]
        Enforcement[enforcement.rs<br/>verb/algorithm validation]
        Policy[policy.rs<br/>caller access control]

        Dispatcher[dispatcher.rs<br/>JSON-RPC 2.0 routing]
        Dispatcher --> KeyStore
        Dispatcher --> AlgCache
        Dispatcher --> OtpPad
        Dispatcher --> Miner

        KeyStore[key_store.rs<br/>derived keys via nostr_core]
        AlgCache[alg_cache.rs<br/>on-demand key derivation]
        OtpPad[otp_pad.rs<br/>one-time pad encrypt/decrypt]
        Miner[miner.rs<br/>NIP-13 PoW via nips::nip013]

        Server[server.rs<br/>multi-transport poll loop]
        Server --> Transport
        Server --> AuthEnvelope
        Server --> Policy
        Server --> Dispatcher

        Transport[transport.rs<br/>framed JSON + HTTP]
        AuthEnvelope[auth_envelope.rs<br/>request authentication]

        PQCrypto[pq_crypto.rs<br/>ed25519, x25519, PQ algorithms]
        Tui[tui.rs<br/>terminal UI]
    end

    subgraph "nostr_core_lib_rust"
        Core[core::<br/>keys, sha256, hmac, nip44]
        Nips[nips::<br/>nip001, nip004, nip006, nip013, nip019, nip044]
        SignerLib[signer::<br/>NostrSigner trait]
    end

    KeyStore --> Core
    KeyStore --> Nips
    Dispatcher --> Nips
    Miner --> Nips
    PQCrypto --> Core

Dependency Mapping: C → Rust

C Module Rust Module nostr_core_lib_rust Usage External Crates
secure_mem.c secure_mem.rs — zeroize, libc (mlock/munlock)
mnemonic.c mnemonic.rs nips::nip006 (BIP-39 wordlist, mnemonic_to_seed) —
role_table.c role_table.rs — —
selector.c selector.rs — —
enforcement.c enforcement.rs — —
policy.c policy.rs — —
key_store.c key_store.rs core::crypto::keys, nips::nip001, nips::nip004, nips::nip044 secp256k1 (via nostr_core)
pq_crypto.c pq_crypto.rs — ed25519-dalek, x25519-dalek, pqcrypto (or vendored PQClean)
pq_drbg.c pq_drbg.rs — sha3 (SHAKE-256)
dispatcher.c dispatcher.rs nips::nip001, nips::nip004, nips::nip044, nips::nip013 serde_json
server.c server.rs — libc (sockets, SO_PEERCRED)
transport_frame.c transport.rs — —
http_listener.c http.rs — —
auth_envelope.c auth_envelope.rs core::crypto::keys (verify) —
miner.c miner.rs nips::nip013 std::thread
otp_pad.c otp_pad.rs — —
socket_name.c socket_name.rs nips::nip006 (BIP-39 wordlist for random names) —
main.c (TUI) tui.rs — crossterm or ratatui
main.c (CLI) main.rs — clap

Key Design Decisions

1. Memory Safety

  • C: Manual mlock/munlock + explicit_bzero via secure_buf_t
  • Rust: zeroize crate with ZeroizeOnDrop derive. Wrap sensitive buffers in a SecureBuf type that calls mlock on alloc and munlock+zeroize on drop. Use libc::mlock/libc::munlock for the syscall.

2. Concurrency Model

  • C: Single-threaded poll loop with detached pthread for nostr_mine_event
  • Rust: Same model — single-threaded poll(2) loop via mio or raw libc::poll. Mining runs in std::thread::spawn. No async runtime needed (the C version is sync).

3. JSON Handling

  • C: cJSON (manual parse/build)
  • Rust: serde_json with typed structs for request/response

4. Error Handling

  • C: Integer error codes + string messages
  • Rust: thiserror-based NsignerError enum. The JSON-RPC error codes are preserved exactly for wire compatibility.

5. Transport

  • C: Raw syscalls (socket, bind, accept, SO_PEERCRED)
  • Rust: std::os::unix::net::UnixListener + libc for SO_PEERCRED. TCP via std::net::TcpListener. HTTP via a minimal hand-rolled parser (same as C — no framework).

6. TUI

  • C: tui_continuous vendored library
  • Rust: crossterm for terminal control + custom rendering (or ratatui if it fits the continuous-redraw model). Start with crossterm + manual rendering to match the C behavior closely.

7. PQ Crypto

  • C: PQClean vendored sources + custom DRBG
  • Rust: Use ed25519-dalek and x25519-dalek for classic curves. For PQ algorithms (ML-DSA-65, SLH-DSA-128s, ML-KEM-768), either:
    • Option A: FFI to the existing PQClean C code (fastest path to working)
    • Option B: Use pqcrypto crate or vendor the PQClean Rust ports
    • Recommendation: Start with Option A (FFI) for Phase 13, migrate to pure Rust later

8. nostr_core_lib_rust Integration

The Rust library provides:

  • core::crypto::keys — secp256k1 key generation, Schnorr sign/verify, ECDH
  • core::crypto::hmac — HMAC-SHA256/512, HKDF
  • core::crypto::nip44 — NIP-44 encryption (ChaCha20-Poly1305)
  • core::types — Event, PublicKey, SecretKey, Signature, etc.
  • nips::nip001 — create_and_sign_event, validate_event
  • nips::nip004 — NIP-04 encrypt/decrypt
  • nips::nip006 — BIP-39 mnemonic generation, validation, mnemonic_to_seed, keypair_from_seed
  • nips::nip013 — NIP-13 proof-of-work mining
  • nips::nip019 — bech32 encoding (npub, nsec)
  • signer::NostrSigner trait — can be used for the signer abstraction

Gap: nips::nip006::keypair_from_seed currently uses the master key directly rather than doing full BIP-32 derivation through m/44'/1237'/0'/0/0. The port needs to implement proper BIP-32 HD derivation (either add it to nostr_core_lib_rust or implement locally in n_signer).

Phased Implementation

Phase 1: Project Scaffolding

  • Create Cargo.toml workspace with path dependency on ~/lt/nostr_core_lib_rust
  • Create src/ module structure matching the C source layout
  • Add dependencies: serde, serde_json, libc, zeroize, clap, crossterm, hex, base64, thiserror, secp256k1 (transitive via nostr_core)
  • Create build.rs if PQClean FFI is needed
  • Verify cargo build compiles with empty module stubs

Phase 2: Secure Memory (secure_mem.rs)

  • SecureBuf struct: holds Vec<u8>, locked: bool
  • SecureBuf::alloc(size) — malloc + libc::mlock + zero init
  • SecureBuf::free() — zeroize + libc::munlock + drop
  • secure_memzero() — use zeroize::zeroize()
  • allow_unlocked() flag for dev mode
  • Implement Drop trait for automatic cleanup
  • Unit tests: alloc/free, zeroization verification

Phase 3: Mnemonic (mnemonic.rs)

  • MnemonicState struct: holds SecureBuf, loaded: bool, word_count: u8
  • mnemonic_load(phrase) — validate via nips::nip006::mnemonic_validate, store in SecureBuf
  • mnemonic_generate(word_count) — use nips::nip006::mnemonic_from_bytes with rand::thread_rng entropy
  • mnemonic_unload() — wipe SecureBuf
  • Unit tests: valid/invalid mnemonics, word count validation

Phase 4: Role Table, Selector, Enforcement

  • RolePurpose enum: Nostr, Bitcoin, Ssh, Age, Fips, PqSig, PqKem
  • RoleCurve enum: Secp256k1, Ed25519, X25519, MlDsa65, SlhDsa128s, MlKem768
  • RoleEntry struct: name, purpose, curve, selector_type, path, range, allowed_indices, requires_approval
  • RoleTable struct: Vec of entries, add/find/register methods
  • Path template parser: wildcard (*), range (N-M), set (A+B+C), fixed path
  • SelectorRequest struct: has_role, has_role_path, has_index
  • selector_resolve() — match role+path against table
  • enforce_verb_role() — check purpose==Nostr && curve==Secp256k1 for nostr verbs
  • enforce_verb_algorithm() — check verb+algorithm validity
  • Unit tests: path template parsing, selector resolution, enforcement matrix

Phase 5: Policy (policy.rs)

  • PromptMode enum: Never, FirstPerBoot, EveryRequest, Deny
  • PolicyEntry struct: caller, verbs, roles, purposes, algorithms, index range, prompt mode, source
  • PolicyTable struct: Vec of entries
  • policy_check() — role-based check
  • policy_check_algorithm() — algorithm-based check
  • policy_check_with_role() — role-as-password shortcut (requires_approval==0 → allow)
  • parse_preapprove_spec() — parse caller=uid:1000,role=main,verb=sign
  • Session grants: insert before catch-all
  • Unit tests: policy matching, preapprove parsing, session grants

Phase 6: Key Store & Crypto (key_store.rs + alg_cache.rs)

  • DerivedKey struct: private_key (SecureBuf), public_key (SecureBuf), pubkey_hex, npub, alg
  • KeyStore struct: Vec of derived keys per role
  • BIP-32 HD derivation: implement proper path derivation (m/44'/1237'/<n>'/0/0)
    • Either add BIP-32 to nostr_core_lib_rust or implement locally using secp256k1 crate
  • SLIP-0010 derivation for ed25519/x25519 (HMAC-SHA512, all-hardened paths)
  • crypto_derive_all() — derive keys for all roles
  • crypto_derive_one() — derive for a single role (on-demand)
  • crypto_sign_event() — via nips::nip001::create_and_sign_event
  • crypto_nip04_encrypt/decrypt() — via nips::nip004
  • crypto_nip44_encrypt/decrypt() — via core::crypto::nip44
  • AlgorithmKeyCache — FIFO cache of on-demand derived keys (alg, index) → keypair
  • Unit tests: derivation determinism, sign/verify roundtrip

Phase 7: Dispatcher (dispatcher.rs)

  • DispatcherContext struct: references to role_table, mnemonic, key_store, alg_cache
  • dispatcher_handle_request(json) → response JSON string
  • Parse JSON-RPC: id, method, params, options
  • Route algorithm verbs: get_public_key, sign, verify, encapsulate, decapsulate, derive_shared_secret, derive
  • Route nostr verbs: nostr_get_public_key, nostr_sign_event, nostr_mine_event, nostr_nip04_*, nostr_nip44_*
  • Route OTP verbs: encrypt, decrypt
  • Route metadata: get_info
  • Error response builder with exact error codes from C API
  • Unit tests: each verb with valid/invalid params

Phase 8: Transport (transport.rs + http.rs)

  • transport_send_framed(fd, payload) — 4-byte BE length prefix + data
  • transport_recv_framed(fd) — read length, then payload
  • http_recv_request(fd) — minimal HTTP/1.1 POST parser
  • http_send_response(fd, json) — HTTP 200 + CORS headers
  • http_send_error(fd, code, message)
  • http_send_cors_preflight(fd) — OPTIONS response
  • Unit tests: framing roundtrip, HTTP parse

Phase 9: Server (server.rs)

  • ListenMode enum: Unix, Stdio, Qrexec, Tcp, Http
  • CallerIdentity struct: uid, gid, pid, kind, caller_id, source_qube, auth fields
  • ServerContext struct: socket_name, listen_fd, listen_mode, dispatcher, policy, auth_mode, whitelists
  • server_start() — bind socket (abstract Unix / TCP / HTTP)
  • server_handle_one() — accept, read request, auth verify, policy check, dispatch, send response
  • server_get_caller() — SO_PEERCRED for Unix, getpeername for TCP
  • Bridge-source-trusted preamble handling
  • Approval callback mechanism
  • Non-blocking poll loop integration
  • Integration tests: Unix socket roundtrip, HTTP roundtrip

Phase 10: Miner (miner.rs)

  • MineResult struct: best_event, achieved_difficulty, target_difficulty, target_reached, elapsed_sec, total_attempts
  • miner_run(event, private_key, target_difficulty, thread_count, timeout_sec) → MineResult
  • Multi-threaded: each thread tries nonces with unique stride
  • Stop on target reached or timeout
  • Use nips::nip013 for PoW computation
  • Unit tests: difficulty achievement, timeout behavior

Phase 11: Auth Envelope (auth_envelope.rs)

  • AuthNonceCache — per-pubkey monotonic timestamp + event ID tracking
  • auth_envelope_verify_request() — verify auth field in JSON-RPC request
  • Replay protection: check created_at > max_seen, check event_id uniqueness
  • Unit tests: valid/invalid auth, replay detection

Phase 12: OTP Pad (otp_pad.rs)

  • OtpPadState struct: bound, pads_dir, chksum, pad_path, pad_file, pad_size, offset, scratch buffer
  • otp_pad_bind(dir, spec, allow_blkback) — open pad file, read checksum, verify
  • otp_pad_encrypt(plaintext, encoding) — XOR with pad bytes, advance offset
  • otp_pad_decrypt(ciphertext, encoding) — reverse XOR
  • ASCII armor encoding + binary encoding
  • Pad offset persistence (.state file)
  • Unit tests: encrypt/decrypt roundtrip, offset advancement

Phase 13: PQ Crypto (pq_crypto.rs + pq_drbg.rs)

  • CryptoAlg enum: Secp256k1, Ed25519, X25519, MlDsa65, SlhDsa128s, MlKem768
  • CryptoAlgSizes struct: priv/pub/sig/ciphertext/shared_secret lengths
  • ed25519: ed25519-dalek crate
  • x25519: x25519-dalek crate
  • SHAKE-256 DRBG: sha3 crate
  • ML-DSA-65, SLH-DSA-128s, ML-KEM-768: FFI to PQClean (initial), pure Rust later
  • crypto_alg_from_role(), crypto_alg_from_str(), crypto_alg_to_str()
  • Keygen, sign, verify, encaps, decaps for each algorithm
  • Unit tests: keygen determinism, sign/verify roundtrip

Phase 14: TUI (tui.rs)

  • Terminal setup via crossterm
  • render_status() — roles table, activity log, status line, menu
  • render_connections() — on-demand connection display (press d)
  • Approval prompt screen
  • Role wizard (preset menu, path editor)
  • Transport selection menu
  • Mnemonic entry screen (echo disabled)
  • Mnemonic generation display
  • Index whitelist prompt
  • OTP pad selection prompt
  • Hotkeys: l (lock), r (refresh), d (connections), q (quit)
  • Terminal resize handling

Phase 15: Main (main.rs)

  • CLI parsing with clap: --socket-name, --listen, --preapprove, --register-role, --auth, --mnemonic-stdin, --mnemonic-fd, --allow-all, --bridge-source-trusted, --otp-pad-dir, --otp-pad
  • Subcommands: client, bridge, list
  • Startup flow: mnemonic → roles → transport → socket name → server start → TUI loop
  • Session lock/re-unlock
  • Signal handling: SIGINT, SIGTERM, SIGPIPE (ignore)
  • Shutdown: wipe all secrets, close sockets
  • Non-interactive mode: --mnemonic-stdin / --mnemonic-fd / --register-role

Phase 16: Integration Tests & Build

  • End-to-end test: start signer, send get_info, get_public_key, nostr_sign_event
  • Algorithm verb tests: sign/verify for each algorithm
  • NIP-04/NIP-44 encrypt/decrypt roundtrip
  • NIP-13 mining test
  • Policy enforcement tests: allow/deny/prompt
  • Multi-transport test: Unix + HTTP simultaneously
  • OTP encrypt/decrypt test
  • cargo build --release verification
  • Static build target (musl) investigation

File Structure

signer/
├── Cargo.toml
├── build.rs                    # PQClean FFI build script (Phase 13)
├── src/
│   ├── main.rs                 # CLI + startup + TUI loop
│   ├── lib.rs                  # Public API re-exports
│   ├── secure_mem.rs           # SecureBuf, mlock, zeroize
│   ├── mnemonic.rs             # BIP-39 mnemonic state
│   ├── role_table.rs           # Role entries, path templates
│   ├── selector.rs             # Role selector resolution
│   ├── enforcement.rs          # Verb/role/algorithm enforcement
│   ├── policy.rs               # Caller access control
│   ├── key_store.rs            # Derived key storage
│   ├── alg_cache.rs            # On-demand algorithm key cache
│   ├── pq_crypto.rs            # ed25519, x25519, PQ algorithms
│   ├── pq_drbg.rs              # SHAKE-256 DRBG for PQ keygen
│   ├── dispatcher.rs           # JSON-RPC 2.0 request routing
│   ├── server.rs               # Multi-transport server
│   ├── transport.rs            # Length-prefixed framing
│   ├── http.rs                 # Minimal HTTP/1.1 parser
│   ├── auth_envelope.rs        # Request authentication
│   ├── miner.rs                # NIP-13 PoW mining
│   ├── otp_pad.rs              # One-time pad encryption
│   ├── socket_name.rs          # Abstract socket naming
│   ├── tui.rs                  # Terminal UI
│   └── error.rs                # NsignerError enum
├── tests/
│   ├── integration_test.rs
│   ├── algorithm_test.rs
│   ├── policy_test.rs
│   └── transport_test.rs
└── resources/
    └── pqclean/                # Vendored PQClean (if FFI path)

Cargo.toml (Draft)

[package]
name = "nsigner"
version = "0.1.0"
edition = "2021"

[dependencies]
nostr-core = { path = "../nostr_core_lib_rust/nostr-core" }
nips = { path = "../nostr_core_lib_rust/nips" }
serde = { workspace = true }
serde_json = { workspace = true }
zeroize = { workspace = true }
libc = "0.2"
clap = { version = "4", features = ["derive"] }
crossterm = "0.27"
hex = { workspace = true }
base64 = { workspace = true }
thiserror = { workspace = true }
secp256k1 = { workspace = true }
sha2 = { workspace = true }
hmac = { workspace = true }
rand = { workspace = true }
ed25519-dalek = "2"
x25519-dalek = "2"
sha3 = "0.10"

[dev-dependencies]
tempfile = "3"

Compatibility Requirements

  1. Wire protocol: JSON-RPC 2.0 request/response format must be byte-identical to C version
  2. Error codes: All error codes (-32700, -32600, 1001-2009) must match exactly
  3. Derivation paths: BIP-32/SLIP-0010 paths must produce identical keys from the same mnemonic
  4. Socket protocol: Length-prefixed framing (4-byte BE) must be compatible
  5. HTTP: Same minimal HTTP/1.1 POST-only parser behavior
  6. Abstract socket names: @nsigner_<word1>_<word2> format preserved

Open Questions

  1. BIP-32 derivation: nostr_core_lib_rust nips::nip006::keypair_from_seed does not do full BIP-32 HD derivation through the path. Should we:

    • (a) Add proper BIP-32 to nostr_core_lib_rust, or
    • (b) Implement BIP-32 locally in n_signer using the secp256k1 crate directly?

  2. PQ crypto: Should we FFI to PQClean C code initially, or find/use Rust PQ crates?

  3. TUI scope: Full TUI parity with C version (role wizard, transport menu, approval prompts, connection display), or start with a simpler CLI?

Reference in New Issue View Git Blame Copy Permalink