n_signer/plans/mnemonic_startup_input.md

Plan: Non-interactive mnemonic input at startup (--mnemonic-stdin, --mnemonic-fd)

Status: ready to implement. Related: documents/SECURITY.md, src/main.c, src/mnemonic.c. Companion plan (future work): plans/embedded_nsigner_spawn.md.

1. Goal

Allow n_signer to receive its mnemonic from a parent process at startup, without the human re-typing it, while preserving the project's existing security posture:

• nothing on the filesystem
• nothing in argv (no --mnemonic <phrase> flag)
• nothing in environment (no NSIGNER_MNEMONIC env var) for production use
• the mnemonic source is wiped from process memory immediately after a successful load

Two new CLI flags are added:

• --mnemonic-stdin — read one line from stdin during the unlock phase, treat that line as the mnemonic, then continue to the normal status display. Stdin is closed (or replaced with /dev/null) before the running phase begins so the listener loop and TUI hotkeys keep working.
• --mnemonic-fd N — read one line from file descriptor N, then close it. Intended to be wired by parent processes to a pipe2(O_CLOEXEC) write end or a memfd_create(2) region. No filesystem path is involved — N is an inherited FD number, equivalent to stdin in lifecycle but separable so it can coexist with --listen stdio.

The existing interactive TUI prompt remains the default when neither flag is given.

2. Why no --mnemonic <phrase> argv flag

Listed only to make the rejection explicit and discoverable in git log:

• visible to every same-uid process via /proc/<pid>/cmdline
• captured by ps auxww
• captured by shell history (bash/zsh HISTFILE)
• captured by audit subsystems (auditd, sysmon-like agents)
• captured by container/VM platform telemetry that records launch commands

Stdin and inherited FDs do not appear in any of those surfaces. They are the right primitive.

Likewise no NSIGNER_MNEMONIC environment variable, because envp is exposed via /proc/<pid>/environ to same-uid readers. Any future env-based override should be opt-in for testing only and named NSIGNER_TEST_* like the existing test hooks.

3. CLI surface changes

3.1 New flags (in src/main.c)

Flag	Argument	Behavior
--mnemonic-stdin	none	read mnemonic from FD 0, then close FD 0 and reopen as /dev/null
--mnemonic-fd <N>	int	read mnemonic from FD N, then close FD N

Both flags are mutually exclusive with each other.

3.2 Compatibility with --listen modes

Listen mode	--mnemonic-stdin	--mnemonic-fd
unix (default)	OK	OK
tcp:HOST:PORT	OK	OK
stdio	rejected (stdin is the request transport)	OK (FD must not be 0/1)
qrexec	rejected (stdio is the request transport)	OK (FD must not be 0/1)

If both --mnemonic-stdin and --listen stdio/qrexec are passed, n_signer exits with a clear error before doing anything else.

--mnemonic-fd rejects N == 0 if --listen stdio/qrexec is also passed, and rejects N == 1 always (stdout is reserved for response framing in stdio/qrexec modes and for the TUI in unix/tcp modes).

3.3 Updated print_usage()

Two new lines added under the existing options section:

  --mnemonic-stdin    Read mnemonic from stdin (one line). Default unlock prompt is skipped.
  --mnemonic-fd N     Read mnemonic from inherited FD N (anonymous, no filesystem). Same-line semantics.

3.4 --help discoverability

The current print_usage() block in src/main.c already lists the other flags in tabular form; the two new lines slot in next to --auth. No structural change.

4. Behavioral spec

4.1 prompt_load_mnemonic becomes load_mnemonic

The existing function prompt_load_mnemonic() is renamed/refactored to load_mnemonic(mnemonic_state_t*, mnemonic_source_t) where:

typedef enum {
    MNEMONIC_SRC_TUI_PROMPT = 0,   /* current default behavior */
    MNEMONIC_SRC_STDIN,            /* --mnemonic-stdin */
    MNEMONIC_SRC_FD,               /* --mnemonic-fd N */
} mnemonic_source_kind_t;

typedef struct {
    mnemonic_source_kind_t kind;
    int fd;                        /* used for SRC_STDIN (=0) and SRC_FD */
} mnemonic_source_t;

For SRC_STDIN and SRC_FD:

1. Read up to MNEMONIC_MAX_LEN bytes from the FD using a small bounded read loop (read(2)), stopping at the first \n or EOF.
2. Trim a single trailing \n and any single trailing \r (handle Windows-style line endings just in case).
3. Reject input containing any embedded \0 (defensive; mnemonic is text).
4. Reject input that ends without seeing EOF or \n after MNEMONIC_MAX_LEN bytes (caller is misbehaving).
5. Pass the buffer to mnemonic_load() which already validates word count.
6. Zeroize the local read buffer with secure_memzero regardless of success/failure.
7. On success, close the source FD. For SRC_STDIN, also dup2() /dev/null onto FD 0 so subsequent read()s on FD 0 don't accidentally consume bytes meant for nothing.
8. On failure (read error, validation error), exit non-zero. There is no retry loop in non-interactive mode — the parent should fix its input and re-spawn; silently retrying could mask a serious bug like leaked mnemonic-passing logic.

For SRC_TUI_PROMPT: unchanged, current behavior preserved verbatim, including the existing 10-attempt retry loop.

4.2 Lock/unlock keystroke (l hotkey)

Currently the l hotkey calls prompt_load_mnemonic() again interactively. After this change:

• If the original startup used the TUI prompt: l re-runs the TUI prompt (unchanged).
• If the original startup used --mnemonic-stdin or --mnemonic-fd: the source FD has already been closed and zeroized, so re-locking would have no source to re-read from. Two options:
  • Option A (chosen): the l hotkey falls back to the TUI prompt on re-unlock, regardless of how the original unlock happened. The user is at the terminal, so the TUI prompt is always available.
  • Option B: disable l entirely if non-interactive source was used. Rejected — too restrictive.

Implementation: track the original source kind in a static in main.c; when the user presses l after non-interactive startup, log a one-line notice ("re-unlock via terminal prompt") and call the TUI variant.

4.3 Trim/normalize rules

The mnemonic line is treated as ASCII text. Allowed transformations before validation:

• strip a single trailing \r\n or \n
• strip leading and trailing ASCII whitespace (space, tab)
• collapse internal runs of whitespace? No — mnemonic_load() already tokenizes on whitespace; passing the trimmed string through unchanged is simpler and matches typed-mnemonic behavior.

4.4 Error messages

All errors go to stderr (not the TUI), prefixed nsigner:, and exit with status 1:

• nsigner: --mnemonic-stdin and --mnemonic-fd are mutually exclusive
• nsigner: --mnemonic-stdin requires --listen unix or --listen tcp:...
• nsigner: --mnemonic-fd N: invalid FD value
• nsigner: --mnemonic-fd N: read failed: <strerror>
• nsigner: mnemonic input exceeded maximum length
• nsigner: mnemonic validation failed

The actual mnemonic content is never printed in any error message. The generic "validation failed" message is intentional.

5. Security review checklist

Items the implementer should verify before merging:

1. The stack buffer used for the read is wiped with secure_memzero on every exit path, including early-error returns.
2. If an mlock-backed temporary buffer is used instead of a stack buffer, it must be secure_buf_alloc'd and secure_buf_free'd.
3. The source FD is close(2)'d after read, before mnemonic_load returns control to main(). Close happens even on failure paths.
4. For --mnemonic-stdin, FD 0 is replaced with /dev/null (open("/dev/null", O_RDONLY) then dup2) so later code paths cannot read leftover bytes.
5. The new flags are documented in README.md §3.1 (Startup phase) with an explicit note that they are intended for parent-process spawning and that the parent is responsible for FD hygiene.
6. The new flags are documented in documents/SECURITY.md under §2 ("trust anchors") — the parent process now joins the trust chain when these flags are used.
7. No new path is added that prints the mnemonic to logs, the activity buffer, or any debug output.
8. man-style banner / help output never echoes the mnemonic.

6. Testing plan

New tests:

• tests/test_mnemonic_input.c (new file) covering:
  1. --mnemonic-stdin happy path: spawn nsigner with a pipe, write a valid 12-word mnemonic + \n, expect successful unlock.
  2. --mnemonic-stdin invalid mnemonic: write garbage, expect non-zero exit.
  3. --mnemonic-stdin no newline before EOF: write valid mnemonic without \n, close pipe, expect success.
  4. --mnemonic-stdin line too long: write 1024 bytes, expect non-zero exit with the length error.
  5. --mnemonic-fd 3 happy path: parent opens an O_CLOEXEC=0 pipe, dups its write end as FD 3 in the child via posix_spawn_file_actions_*, writes mnemonic, expects success.
  6. Mutually-exclusive flag combinations: --mnemonic-stdin --mnemonic-fd 3, --mnemonic-stdin --listen stdio, --mnemonic-fd 0 --listen stdio — all expected to exit 1 with the matching error string.
  7. Lock-then-reunlock after --mnemonic-stdin startup: verify the TUI prompt path still works (using NSIGNER_TEST_HOTKEYS and NSIGNER_TEST_NONINTERACTIVE_PROMPT test hooks).

Existing tests must continue to pass:

• tests/test_mnemonic.c (mnemonic library unit tests — unchanged surface)
• tests/test_integration.c (default TUI-prompt path)
• tests/test.sh wrapper.

Add a row to Makefile test target for the new test binary.

7. Documentation updates

• README.md §3.1: add a paragraph at the end noting the two new flags and pointing to this plan.
• documents/SECURITY.md §2.3: add a row to the trust-anchors table for "the parent process when --mnemonic-stdin/--mnemonic-fd is used".
• documents/CLIENT_IMPLEMENTATION.md: no changes (client wire protocol unaffected).
• New section in README.md under "Operating modes" pointing readers to the future spawning plan once that lands.

8. Out of scope (handled by companion plan)

• Embedding the nsigner binary into a host program via objcopy blob + memfd_create + fexecve. See plans/embedded_nsigner_spawn.md.
• Reusable C client helper that picks a terminal emulator and wires the pipe. Same companion plan.
• examples/spawn_and_sign.c. Same companion plan.

9. Acceptance criteria

• nsigner --mnemonic-stdin reads one line, validates, and proceeds to status display without prompting.
• nsigner --mnemonic-fd 3 (with FD 3 inherited from a parent test harness) does the same.
• Invalid mnemonics exit non-zero with the generic validation message; mnemonic content is never printed.
• Mutually exclusive flag combinations are rejected at argument-parse time.
• --listen stdio and --mnemonic-stdin are mutually exclusive.
• After non-interactive unlock, pressing l falls back to the TUI prompt for re-unlock and the running phase otherwise behaves identically.
• The mnemonic source FD is closed and the source buffer is zeroized on every path.
• All existing tests still pass; new tests in tests/test_mnemonic_input.c pass.
• README.md and documents/SECURITY.md are updated.