v0.0.27 - Refine TUI login flow, fix menu hotkey underlining, and pin connection info header

.roo/commands/push.md

@@ -1,5 +1,5 @@
 ---
-description: "Brief description of what this command does"
+description: "This command increments the version number and then adds, commits and pushes to the repo."
 ---
 
 Run increment_and_push.sh, and supply a good git commit message. For example:

Dockerfile.alpine-musl

@@ -55,6 +55,7 @@ RUN if [ "$(uname -m)" = "aarch64" ] && ! command -v aarch64-linux-gnu-gcc >/dev
 
 # Copy source files
 COPY src/ /build/src/
+COPY resources/tui_continuous/ /build/resources/tui_continuous/
 
 # Build nsigner as a fully static binary
 RUN ARCH="$(uname -m)"; \
@@ -68,6 +69,7 @@ RUN ARCH="$(uname -m)"; \
       -I/build/nostr_core_lib \
       -I/build/nostr_core_lib/nostr_core \
       -I/build/nostr_core_lib/cjson \
+      -I/build/resources/tui_continuous \
       /build/src/main.c \
       /build/src/secure_mem.c \
       /build/src/mnemonic.c \
@@ -80,6 +82,8 @@ RUN ARCH="$(uname -m)"; \
       /build/src/transport_frame.c \
       /build/src/key_store.c \
       /build/src/socket_name.c \
+      /build/src/auth_envelope.c \
+      /build/resources/tui_continuous/tui_continuous.c \
       "$NOSTR_LIB" \
       -o /build/nsigner_static \
       $(pkg-config --static --libs libcurl openssl) \

Makefile

@@ -1,10 +1,12 @@
 CC := gcc
-CFLAGS := -Wall -Wextra -std=c99 -Os -ffunction-sections -fdata-sections -Isrc -Iresources/nostr_core_lib -Iresources/nostr_core_lib/nostr_core -Iresources/nostr_core_lib/cjson
+CFLAGS := -Wall -Wextra -std=c99 -Os -ffunction-sections -fdata-sections -Isrc -Iresources/nostr_core_lib -Iresources/nostr_core_lib/nostr_core -Iresources/nostr_core_lib/cjson -Iresources/tui_continuous
 LDFLAGS := -Wl,--gc-sections resources/nostr_core_lib/libnostr_core_x64.a -lz -ldl -lpthread -lm -lssl -lcrypto -lcurl -lsecp256k1
 
 SRC_DIR := src
 BUILD_DIR := build
 TEST_DIR := tests
+CLIENT_DIR := client
+EXAMPLES_DIR := examples
 
 TARGET_DEV := $(BUILD_DIR)/nsigner
 
@@ -21,7 +23,8 @@ SOURCES := \
 	$(SRC_DIR)/transport_frame.c \
 	$(SRC_DIR)/key_store.c \
 	$(SRC_DIR)/socket_name.c \
-	$(SRC_DIR)/auth_envelope.c
+	$(SRC_DIR)/auth_envelope.c \
+	resources/tui_continuous/tui_continuous.c
 
 HEADERS :=
 
@@ -35,8 +38,12 @@ TEST_POLICY_TARGET := $(BUILD_DIR)/test_policy
 TEST_INTEGRATION_TARGET := $(BUILD_DIR)/test_integration
 TEST_SOCKET_NAME_TARGET := $(BUILD_DIR)/test_socket_name
 TEST_AUTH_ENVELOPE_TARGET := $(BUILD_DIR)/test_auth_envelope
+TEST_QREXEC_AUTH_TARGET := $(BUILD_DIR)/test_qrexec_auth
+TEST_MNEMONIC_INPUT_TARGET := $(BUILD_DIR)/test_mnemonic_input
+EXAMPLE_GET_PUBLIC_KEY_TARGET := $(BUILD_DIR)/example_get_public_key_client
+EXAMPLE_SIGN_EVENT_TARGET := $(BUILD_DIR)/example_sign_event_client
 
-.PHONY: all lib dev static static-debug static-arm64 test test-integration test-mnemonic test-role test-selector test-enforcement test-dispatcher test-policy test-socket-name test-auth-envelope clean
+.PHONY: all lib dev static static-debug static-arm64 test test-integration test-mnemonic test-mnemonic-input test-role test-selector test-enforcement test-dispatcher test-policy test-socket-name test-auth-envelope test-qrexec-auth examples test-client clean
 
 all: dev
 
@@ -61,7 +68,7 @@ static-arm64:
 	chmod +x ./build_static.sh
 	./build_static.sh --arch arm64
 
-test: lib test-mnemonic test-role test-selector test-enforcement test-dispatcher test-policy test-socket-name test-auth-envelope
+test: lib test-mnemonic test-mnemonic-input test-role test-selector test-enforcement test-dispatcher test-policy test-socket-name test-auth-envelope test-qrexec-auth test-client
 
 test-integration: $(TEST_INTEGRATION_TARGET) $(TARGET_DEV)
 	./$(TEST_INTEGRATION_TARGET)
@@ -69,6 +76,9 @@ test-integration: $(TEST_INTEGRATION_TARGET) $(TARGET_DEV)
 test-mnemonic: $(TEST_MNEMONIC_TARGET)
 	./$(TEST_MNEMONIC_TARGET)
 
+test-mnemonic-input: $(TEST_MNEMONIC_INPUT_TARGET)
+	./$(TEST_MNEMONIC_INPUT_TARGET)
+
 test-role: $(TEST_ROLE_TARGET)
 	./$(TEST_ROLE_TARGET)
 
@@ -90,10 +100,21 @@ test-socket-name: $(TEST_SOCKET_NAME_TARGET)
 test-auth-envelope: $(TEST_AUTH_ENVELOPE_TARGET)
 	./$(TEST_AUTH_ENVELOPE_TARGET)
 
+test-qrexec-auth: $(TEST_QREXEC_AUTH_TARGET) $(TARGET_DEV)
+	./$(TEST_QREXEC_AUTH_TARGET)
+
+test-client: examples
+
+examples: $(EXAMPLE_GET_PUBLIC_KEY_TARGET) $(EXAMPLE_SIGN_EVENT_TARGET)
+
 $(TEST_MNEMONIC_TARGET): $(TEST_DIR)/test_mnemonic.c $(SRC_DIR)/mnemonic.c $(SRC_DIR)/secure_mem.c
 	@mkdir -p $(BUILD_DIR)
 	$(CC) $(CFLAGS) $(TEST_DIR)/test_mnemonic.c $(SRC_DIR)/mnemonic.c $(SRC_DIR)/secure_mem.c -o $(TEST_MNEMONIC_TARGET) $(LDFLAGS)
 
+$(TEST_MNEMONIC_INPUT_TARGET): $(TEST_DIR)/test_mnemonic_input.c
+	@mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) -I$(CLIENT_DIR) $(TEST_DIR)/test_mnemonic_input.c -o $(TEST_MNEMONIC_INPUT_TARGET) $(LDFLAGS)
+
 $(TEST_ROLE_TARGET): $(TEST_DIR)/test_role_table.c $(SRC_DIR)/role_table.c
 	@mkdir -p $(BUILD_DIR)
 	$(CC) $(CFLAGS) $(TEST_DIR)/test_role_table.c $(SRC_DIR)/role_table.c -o $(TEST_ROLE_TARGET) $(LDFLAGS)
@@ -114,9 +135,9 @@ $(TEST_POLICY_TARGET): $(TEST_DIR)/test_policy.c $(SRC_DIR)/policy.c
 	@mkdir -p $(BUILD_DIR)
 	$(CC) $(CFLAGS) $(TEST_DIR)/test_policy.c $(SRC_DIR)/policy.c -o $(TEST_POLICY_TARGET) $(LDFLAGS)
 
-$(TEST_INTEGRATION_TARGET): $(TEST_DIR)/test_integration.c
+$(TEST_INTEGRATION_TARGET): $(TEST_DIR)/test_integration.c $(CLIENT_DIR)/nsigner_client.c $(SRC_DIR)/auth_envelope.c
 	@mkdir -p $(BUILD_DIR)
-	$(CC) $(CFLAGS) $(TEST_DIR)/test_integration.c -o $(TEST_INTEGRATION_TARGET) $(LDFLAGS)
+	$(CC) $(CFLAGS) -I$(CLIENT_DIR) $(TEST_DIR)/test_integration.c $(CLIENT_DIR)/nsigner_client.c $(SRC_DIR)/auth_envelope.c -o $(TEST_INTEGRATION_TARGET) $(LDFLAGS)
 
 $(TEST_SOCKET_NAME_TARGET): $(TEST_DIR)/test_socket_name.c $(SRC_DIR)/socket_name.c
 	@mkdir -p $(BUILD_DIR)
@@ -126,5 +147,17 @@ $(TEST_AUTH_ENVELOPE_TARGET): $(TEST_DIR)/test_auth_envelope.c $(SRC_DIR)/auth_e
 	@mkdir -p $(BUILD_DIR)
 	$(CC) $(CFLAGS) $(TEST_DIR)/test_auth_envelope.c $(SRC_DIR)/auth_envelope.c -o $(TEST_AUTH_ENVELOPE_TARGET) $(LDFLAGS)
 
+$(TEST_QREXEC_AUTH_TARGET): $(TEST_DIR)/test_qrexec_auth.c $(SRC_DIR)/auth_envelope.c
+	@mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) $(TEST_DIR)/test_qrexec_auth.c $(SRC_DIR)/auth_envelope.c -o $(TEST_QREXEC_AUTH_TARGET) $(LDFLAGS)
+
+$(EXAMPLE_GET_PUBLIC_KEY_TARGET): $(EXAMPLES_DIR)/get_public_key_client.c $(CLIENT_DIR)/nsigner_client.c $(SRC_DIR)/auth_envelope.c
+	@mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) -I$(CLIENT_DIR) $(EXAMPLES_DIR)/get_public_key_client.c $(CLIENT_DIR)/nsigner_client.c $(SRC_DIR)/auth_envelope.c -o $(EXAMPLE_GET_PUBLIC_KEY_TARGET) $(LDFLAGS)
+
+$(EXAMPLE_SIGN_EVENT_TARGET): $(EXAMPLES_DIR)/sign_event_client.c $(CLIENT_DIR)/nsigner_client.c $(SRC_DIR)/auth_envelope.c
+	@mkdir -p $(BUILD_DIR)
+	$(CC) $(CFLAGS) -I$(CLIENT_DIR) $(EXAMPLES_DIR)/sign_event_client.c $(CLIENT_DIR)/nsigner_client.c $(SRC_DIR)/auth_envelope.c -o $(EXAMPLE_SIGN_EVENT_TARGET) $(LDFLAGS)
+
 clean:
 	rm -rf $(BUILD_DIR)

README.md

@@ -80,6 +80,13 @@ When started, `n_signer` immediately enters terminal input mode:
 
 No startup files are read or written. The mnemonic — typed or generated — lives only in `mlock`'d memory and is zeroized on shutdown or crash.
 
+For parent-process launchers, startup can also be non-interactive:
+
+- `--mnemonic-stdin`: read one mnemonic line from stdin at startup, then continue normally.
+- `--mnemonic-fd N`: read one mnemonic line from inherited file descriptor `N` at startup.
+
+These modes avoid putting mnemonic material in argv/environment and are designed for supervised spawners. See [`plans/mnemonic_startup_input.md`](plans/mnemonic_startup_input.md) for the full behavior contract.
+
 ### 3.2 Running phase (status display + signer)
 
 After unlock, terminal becomes a live status and control console. Example layout:
@@ -366,6 +373,7 @@ Build outputs a single executable artifact.
 - [`build_static.sh`](build_static.sh): musl-static build path
 - [`Makefile`](Makefile): local build targets
 - [`Dockerfile.alpine-musl`](Dockerfile.alpine-musl): reproducible Alpine musl toolchain
+- [`resources/tui_continuous/tui_continuous.h`](resources/tui_continuous/tui_continuous.h) + [`resources/tui_continuous/tui_continuous.c`](resources/tui_continuous/tui_continuous.c): vendored continuous-TUI component (from `~/lt/aesthetics`, API baseline `TUI_CONTINUOUS_VERSION 0.0.9`)
 - [`increment_and_push.sh`](increment_and_push.sh): version/tag/release workflow
 - [`src/main.c`](src/main.c): version macros (`NSIGNER_VERSION*`)
 

client/README.md

@@ -0,0 +1,47 @@
+# n_signer C Reference Client
+
+This directory provides a minimal copy/paste-friendly C client for `n_signer`.
+
+## Files
+
+- `nsigner_client.h` / `nsigner_client.c`:
+  - Unix abstract socket connect helper
+  - length-prefixed frame send/receive
+  - generic request API
+  - helpers for `get_public_key` and `sign_event`
+  - optional TCP auth envelope attachment via `auth_envelope_build_for_request()`
+
+## API at a glance
+
+```c
+nsigner_client_t client;
+nsigner_client_init(&client);
+
+nsigner_client_connect_unix(&client, "nsigner", 5000);
+
+char *resp = NULL;
+nsigner_client_get_public_key(&client, "1", "", &resp);
+free(resp);
+
+nsigner_client_close(&client);
+```
+
+## Auth envelope usage
+
+If transport requires auth envelopes (for TCP mode), set a private key once:
+
+```c
+unsigned char privkey[32] = { /* caller key */ };
+nsigner_client_set_auth(&client, privkey, "example-client");
+```
+
+Subsequent requests automatically include an `auth` object.
+
+## Ownership rules
+
+- Any `out_response_json` returned by the API must be freed by caller using `free()`.
+- `nsigner_client_close()` only closes the socket; it does not free the client struct itself.
+
+## License
+
+Source files in this directory use SPDX `0BSD` headers for permissive reuse in external projects.

client/nsigner_client.c

@@ -0,0 +1,369 @@
+/*
+ * SPDX-License-Identifier: 0BSD
+ */
+
+#define _GNU_SOURCE
+
+#include "nsigner_client.h"
+
+#include <arpa/inet.h>
+#include <errno.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/socket.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <time.h>
+#include <unistd.h>
+
+#include <cJSON.h>
+
+#include "auth_envelope.h"
+
+#define NSIGNER_CLIENT_MAX_FRAME (65536U)
+
+static void client_set_error(nsigner_client_t *client, const char *fmt, ...) {
+    va_list ap;
+
+    if (client == NULL) {
+        return;
+    }
+
+    va_start(ap, fmt);
+    vsnprintf(client->last_error, sizeof(client->last_error), fmt, ap);
+    va_end(ap);
+}
+
+static int write_full(int fd, const void *buf, size_t len) {
+    const unsigned char *p = (const unsigned char *)buf;
+    size_t off = 0;
+
+    while (off < len) {
+        ssize_t n = write(fd, p + off, len - off);
+        if (n < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            return -1;
+        }
+        off += (size_t)n;
+    }
+
+    return 0;
+}
+
+static int read_full(int fd, void *buf, size_t len) {
+    unsigned char *p = (unsigned char *)buf;
+    size_t off = 0;
+
+    while (off < len) {
+        ssize_t n = read(fd, p + off, len - off);
+        if (n == 0) {
+            return -1;
+        }
+        if (n < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            return -1;
+        }
+        off += (size_t)n;
+    }
+
+    return 0;
+}
+
+static int send_framed(int fd, const char *payload) {
+    uint32_t len;
+    uint32_t be_len;
+
+    if (payload == NULL) {
+        return -1;
+    }
+
+    len = (uint32_t)strlen(payload);
+    be_len = htonl(len);
+
+    if (write_full(fd, &be_len, sizeof(be_len)) != 0) {
+        return -1;
+    }
+    if (write_full(fd, payload, len) != 0) {
+        return -1;
+    }
+
+    return 0;
+}
+
+static int recv_framed(int fd, char **out_payload) {
+    uint32_t be_len;
+    uint32_t len;
+    char *payload;
+
+    if (out_payload == NULL) {
+        return -1;
+    }
+
+    *out_payload = NULL;
+
+    if (read_full(fd, &be_len, sizeof(be_len)) != 0) {
+        return -1;
+    }
+
+    len = ntohl(be_len);
+    if (len == 0 || len > NSIGNER_CLIENT_MAX_FRAME) {
+        return -1;
+    }
+
+    payload = (char *)malloc((size_t)len + 1U);
+    if (payload == NULL) {
+        return -1;
+    }
+
+    if (read_full(fd, payload, len) != 0) {
+        free(payload);
+        return -1;
+    }
+
+    payload[len] = '\0';
+    *out_payload = payload;
+    return 0;
+}
+
+static int sleep_ms(int ms) {
+    struct timespec ts;
+    ts.tv_sec = ms / 1000;
+    ts.tv_nsec = (long)(ms % 1000) * 1000000L;
+    return nanosleep(&ts, NULL);
+}
+
+void nsigner_client_init(nsigner_client_t *client) {
+    if (client == NULL) {
+        return;
+    }
+
+    memset(client, 0, sizeof(*client));
+    client->fd = -1;
+    client->timeout_ms = 5000;
+}
+
+void nsigner_client_close(nsigner_client_t *client) {
+    if (client == NULL) {
+        return;
+    }
+
+    if (client->fd >= 0) {
+        close(client->fd);
+        client->fd = -1;
+    }
+}
+
+int nsigner_client_connect_unix(nsigner_client_t *client,
+                                const char *socket_name,
+                                int timeout_ms) {
+    struct sockaddr_un addr;
+    socklen_t addr_len;
+    int elapsed = 0;
+
+    if (client == NULL || socket_name == NULL || socket_name[0] == '\0') {
+        return -1;
+    }
+
+    timeout_ms = (timeout_ms > 0) ? timeout_ms : 5000;
+    nsigner_client_close(client);
+
+    memset(&addr, 0, sizeof(addr));
+    addr.sun_family = AF_UNIX;
+    addr.sun_path[0] = '\0';
+    strncpy(&addr.sun_path[1], socket_name, sizeof(addr.sun_path) - 2);
+    addr.sun_path[sizeof(addr.sun_path) - 1] = '\0';
+    addr_len = (socklen_t)(sizeof(sa_family_t) + 1 + strlen(socket_name));
+
+    while (elapsed < timeout_ms) {
+        int fd = socket(AF_UNIX, SOCK_STREAM, 0);
+        if (fd < 0) {
+            client_set_error(client, "socket failed: %s", strerror(errno));
+            return -1;
+        }
+
+        if (connect(fd, (struct sockaddr *)&addr, addr_len) == 0) {
+            client->fd = fd;
+            client->timeout_ms = timeout_ms;
+            client_set_error(client, "ok");
+            return 0;
+        }
+
+        close(fd);
+        sleep_ms(100);
+        elapsed += 100;
+    }
+
+    client_set_error(client, "connect timeout: %s", strerror(errno));
+    return -1;
+}
+
+int nsigner_client_set_auth(nsigner_client_t *client,
+                            const unsigned char privkey[32],
+                            const char *label) {
+    if (client == NULL || privkey == NULL) {
+        return -1;
+    }
+
+    memcpy(client->auth_privkey, privkey, 32);
+    client->auth_enabled = 1;
+
+    if (label == NULL) {
+        label = "";
+    }
+    strncpy(client->auth_label, label, sizeof(client->auth_label) - 1);
+    client->auth_label[sizeof(client->auth_label) - 1] = '\0';
+
+    return 0;
+}
+
+const char *nsigner_client_last_error(const nsigner_client_t *client) {
+    if (client == NULL) {
+        return "invalid_client";
+    }
+    return client->last_error;
+}
+
+int nsigner_client_request_raw(nsigner_client_t *client,
+                               const char *request_json,
+                               char **out_response_json) {
+    char *response_json = NULL;
+
+    if (client == NULL || request_json == NULL || out_response_json == NULL) {
+        return -1;
+    }
+    if (client->fd < 0) {
+        client_set_error(client, "not connected");
+        return -1;
+    }
+
+    *out_response_json = NULL;
+
+    if (send_framed(client->fd, request_json) != 0) {
+        client_set_error(client, "send failed");
+        return -1;
+    }
+
+    if (recv_framed(client->fd, &response_json) != 0) {
+        client_set_error(client, "receive failed");
+        return -1;
+    }
+
+    *out_response_json = response_json;
+    client_set_error(client, "ok");
+    return 0;
+}
+
+int nsigner_client_request(nsigner_client_t *client,
+                           const char *id,
+                           const char *method,
+                           const cJSON *params,
+                           char **out_response_json) {
+    cJSON *root = NULL;
+    cJSON *params_copy = NULL;
+    cJSON *auth = NULL;
+    char *request_json = NULL;
+    int rc = -1;
+
+    if (client == NULL || id == NULL || method == NULL || out_response_json == NULL) {
+        return -1;
+    }
+
+    root = cJSON_CreateObject();
+    if (root == NULL) {
+        client_set_error(client, "out of memory");
+        goto cleanup;
+    }
+
+    cJSON_AddStringToObject(root, "id", id);
+    cJSON_AddStringToObject(root, "method", method);
+
+    if (params != NULL) {
+        params_copy = cJSON_Duplicate((cJSON *)params, 1);
+    } else {
+        params_copy = cJSON_CreateArray();
+    }
+
+    if (params_copy == NULL) {
+        client_set_error(client, "failed to create params");
+        goto cleanup;
+    }
+    cJSON_AddItemToObject(root, "params", params_copy);
+
+    if (client->auth_enabled) {
+        if (auth_envelope_build_for_request(id,
+                                            method,
+                                            params_copy,
+                                            client->auth_privkey,
+                                            client->auth_label,
+                                            time(NULL),
+                                            &auth) != 0) {
+            client_set_error(client, "failed to build auth envelope");
+            goto cleanup;
+        }
+        cJSON_AddItemToObject(root, "auth", auth);
+        auth = NULL;
+    }
+
+    request_json = cJSON_PrintUnformatted(root);
+    if (request_json == NULL) {
+        client_set_error(client, "failed to serialize request");
+        goto cleanup;
+    }
+
+    rc = nsigner_client_request_raw(client, request_json, out_response_json);
+
+cleanup:
+    cJSON_Delete(root);
+    cJSON_Delete(auth);
+    free(request_json);
+    return rc;
+}
+
+int nsigner_client_get_public_key(nsigner_client_t *client,
+                                  const char *id,
+                                  const char *selector,
+                                  char **out_response_json) {
+    cJSON *params = cJSON_CreateArray();
+    int rc;
+
+    if (params == NULL) {
+        return -1;
+    }
+
+    cJSON_AddItemToArray(params, cJSON_CreateString((selector != NULL) ? selector : ""));
+    rc = nsigner_client_request(client, id, "get_public_key", params, out_response_json);
+    cJSON_Delete(params);
+    return rc;
+}
+
+int nsigner_client_sign_event(nsigner_client_t *client,
+                              const char *id,
+                              const char *event_json,
+                              const char *role,
+                              char **out_response_json) {
+    cJSON *params = cJSON_CreateArray();
+    cJSON *opts = cJSON_CreateObject();
+    int rc;
+
+    if (params == NULL || opts == NULL || event_json == NULL) {
+        cJSON_Delete(params);
+        cJSON_Delete(opts);
+        return -1;
+    }
+
+    cJSON_AddItemToArray(params, cJSON_CreateString(event_json));
+    if (role != NULL && role[0] != '\0') {
+        cJSON_AddStringToObject(opts, "role", role);
+    }
+    cJSON_AddItemToArray(params, opts);
+
+    rc = nsigner_client_request(client, id, "sign_event", params, out_response_json);
+    cJSON_Delete(params);
+    return rc;
+}

client/nsigner_client.h

@@ -0,0 +1,56 @@
+/*
+ * SPDX-License-Identifier: 0BSD
+ */
+
+#ifndef NSIGNER_CLIENT_H
+#define NSIGNER_CLIENT_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <cJSON.h>
+
+typedef struct {
+    int fd;
+    int timeout_ms;
+    unsigned char auth_privkey[32];
+    int auth_enabled;
+    char auth_label[64];
+    char last_error[128];
+} nsigner_client_t;
+
+void nsigner_client_init(nsigner_client_t *client);
+void nsigner_client_close(nsigner_client_t *client);
+
+int nsigner_client_connect_unix(nsigner_client_t *client,
+                                const char *socket_name,
+                                int timeout_ms);
+
+int nsigner_client_set_auth(nsigner_client_t *client,
+                            const unsigned char privkey[32],
+                            const char *label);
+
+const char *nsigner_client_last_error(const nsigner_client_t *client);
+
+int nsigner_client_request_raw(nsigner_client_t *client,
+                               const char *request_json,
+                               char **out_response_json);
+
+int nsigner_client_request(nsigner_client_t *client,
+                           const char *id,
+                           const char *method,
+                           const cJSON *params,
+                           char **out_response_json);
+
+int nsigner_client_get_public_key(nsigner_client_t *client,
+                                  const char *id,
+                                  const char *selector,
+                                  char **out_response_json);
+
+int nsigner_client_sign_event(nsigner_client_t *client,
+                              const char *id,
+                              const char *event_json,
+                              const char *role,
+                              char **out_response_json);
+
+#endif

documents/CLIENT_IMPLEMENTATION.md

@@ -6,6 +6,12 @@ This document is the client-integration spec for `nsigner`.
 
 It is written for agent/tool authors implementing robust request flows against the local signer process.
 
+Reference implementation in this repository:
+
+- Reusable C client library: `client/nsigner_client.h` + `client/nsigner_client.c`
+- Minimal usage examples: `examples/get_public_key_client.c` and `examples/sign_event_client.c`
+- Auth envelope builder used by the client: `src/auth_envelope.h` (`auth_envelope_build_for_request`)
+
 ---
 
 ## 2. Discovery and socket targeting
@@ -55,7 +61,17 @@ 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)
+### 2.4 qrexec authentication posture (`--auth`)
+
+qrexec now supports configurable auth-envelope handling:
+
+- `--listen qrexec --auth off` (default): legacy behavior. Requests are authorized as `qubes:<vm-name>` only.
+- `--listen qrexec --auth optional`: if the request includes an `auth` field, it is verified using the same auth envelope rules as TCP. On success, caller identity is upgraded to `qubes:<vm-name>+pubkey:<hex>`.
+- `--listen qrexec --auth required`: every request must carry a valid `auth` envelope, and caller identity is `qubes:<vm-name>+pubkey:<hex>`.
+
+When `--auth optional` is used, a malformed or invalid `auth` object is rejected with auth-layer errors (`2010..2017`) rather than silently falling back to `qubes:<vm-name>`.
+
+### 2.5 TCP mode authentication (required)
 
 For TCP transport, requests MUST include an `auth` object containing a signed Nostr-style event envelope.
 

documents/QUBES_OS.md

@@ -49,6 +49,16 @@ Still missing for complete Qubes integration:
 - qrexec policy in dom0 remains first enforcement boundary.
 - `n_signer` policy/approval remains second boundary.
 
+### 3.4 Optional per-program identity inside one qube (`--auth optional`)
+
+qrexec now supports an optional auth-envelope layer:
+
+- `nsigner --listen qrexec --auth off` (default): identity remains `qubes:<source-vm>`.
+- `nsigner --listen qrexec --auth optional`: if a caller includes a valid auth envelope, identity becomes `qubes:<source-vm>+pubkey:<hex>`.
+- `nsigner --listen qrexec --auth required`: all requests must carry valid envelopes and identity is always `qubes:<source-vm>+pubkey:<hex>`.
+
+This enables per-program approvals inside a single caller qube while preserving existing behavior for legacy callers that do not emit auth envelopes.
+
 ---
 
 ## 4. Required implementation tasks
@@ -102,6 +112,12 @@ In qrexec mode, default prompt behavior is now:
 
 This replaces the previous permissive `PROMPT_NEVER` temporary setting.
 
+If qrexec auth envelopes are enabled (`--auth optional` or `--auth required`), approved callers can also be recorded as composite identities:
+
+- `qubes:<vm>+pubkey:<hex>`
+
+This gives independent approval rows for distinct programs running in the same source qube.
+
 ## 4.4 Client helper examples ✅ Implemented
 
 Added:
@@ -135,6 +151,7 @@ Includes:
 - from caller qube, invoke test request (`get_public_key`)
 - confirm signer qube receives request
 - confirm activity log displays `qubes:<source-vm>` caller prefix
+- with `--auth optional`, confirm envelope-enabled clients show `qubes:<source-vm>+pubkey:<hex>`
 - validate deny behavior from unauthorized qube
 
 ## 5.4 Failure checks

documents/SECURITY.md

@@ -21,6 +21,8 @@ The security posture is intentionally minimalist:
 
 Authoritative behavior reference: [`README.md`](../README.md). Implementation roadmap: [`plans/nsigner.md`](../plans/nsigner.md). Approval model plan: [`plans/deny_by_default_approvals.md`](../plans/deny_by_default_approvals.md). Wire contract for clients: [`documents/CLIENT_IMPLEMENTATION.md`](CLIENT_IMPLEMENTATION.md).
 
+Interactive terminal presentation now follows the continuous-TUI conventions from `~/lt/aesthetics/TUI.md`, implemented via vendored [`resources/tui_continuous/tui_continuous.h`](../resources/tui_continuous/tui_continuous.h) / [`resources/tui_continuous/tui_continuous.c`](../resources/tui_continuous/tui_continuous.c) (baseline `TUI_CONTINUOUS_VERSION 0.0.9`).
+
 ---
 
 ## 2. Threat model
@@ -49,6 +51,7 @@ Authoritative behavior reference: [`README.md`](../README.md). Implementation ro
 | The kernel and `mlock` / `getrandom` syscalls | Used for in-memory protection and entropy. |
 | The static binary itself | Built reproducibly via [`build_static.sh`](../build_static.sh) and shipped as one musl-static artifact. |
 | The launcher that started `n_signer` | Whoever ran the process chose the `--preapprove` flags. In interactive use that's the human; in `n_OS_tr` boot it's the OS init system. The launcher's integrity is part of the trust chain. |
+| Parent process (when using `--mnemonic-stdin` / `--mnemonic-fd`) | In non-interactive startup mode, the parent provides mnemonic bytes over stdin/inherited FD. That parent is now explicitly in the trust chain for mnemonic handling correctness and secrecy. |
 
 Everything else — clients, other processes, other users, remote callers — is **untrusted by default** and must clear an approval check.
 
@@ -94,12 +97,13 @@ An identity is a tagged caller record built from the transport. Different transp
 |---|---|---|
 | `unix_peer` | `uid`, `pid` from `SO_PEERCRED` on an abstract Unix socket. | Kernel — the client cannot forge it. |
 | `qubes` | source qube name from `QREXEC_REMOTE_DOMAIN`. | Qubes RPC framework. |
+| `qubes_pubkey` | source qube + verified auth-envelope pubkey (`qubes:<vm>+pubkey:<hex>`). | Qubes RPC framework + application-layer signature verification. |
 | `tcp_local` | Loopback address of caller. | TCP socket peer address — opt-in transport. |
-| `tcp_remote` | Address plus an authenticated pubkey (planned). | Application-layer authentication. |
+| `tcp_remote` | Verified auth-envelope pubkey (`pubkey:<hex>`). | Application-layer authentication. |
 | `fips` | Peer npub from a NIP-46 style flow (planned). | Application-layer authentication. |
 | `usb_serial` | Device path plus an asserted caller (planned). | Trust-on-first-use. |
 
-Identity quality varies. `unix_peer` and `qubes` are vouched for by the kernel or hypervisor — strong. `tcp_local` and `tcp_remote` are transport-asserted only — only as good as the human at the terminal who chose to approve them.
+Identity quality varies. `unix_peer` and `qubes` are vouched for by the kernel or hypervisor — strong. `qubes_pubkey` is stronger still for multi-program qubes because it combines hypervisor-vouched source-qube identity with a per-program cryptographic identity. `tcp_local` and `tcp_remote` rely on transport/app-layer checks and are only as strong as deployment choices.
 
 ### Index (or path) — *which key*
 
@@ -423,7 +427,8 @@ Different transports give different identity quality. The wire format (4-byte le
 ### 11.2 Stdio / qrexec mode
 
 - One framed request, one framed response, then exit.
-- Identity: `qubes:<vm-name>` from `QREXEC_REMOTE_DOMAIN`, vouched for by Qubes.
+- Identity defaults to `qubes:<vm-name>` from `QREXEC_REMOTE_DOMAIN`, vouched for by Qubes.
+- With `--listen qrexec --auth optional|required`, requests carrying a valid auth envelope are upgraded to `qubes:<vm-name>+pubkey:<hex>`.
 - Risk surface: only what Qubes RPC policy permits. See [`packaging/qubes/`](../packaging/qubes/).
 
 ### 11.3 TCP (advanced / opt-in)

examples/get_public_key_client.c

@@ -0,0 +1,32 @@
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "../client/nsigner_client.h"
+
+int main(int argc, char **argv) {
+    const char *socket_name = "nsigner";
+    nsigner_client_t client;
+    char *response = NULL;
+
+    if (argc > 1 && argv[1] != NULL && argv[1][0] != '\0') {
+        socket_name = argv[1];
+    }
+
+    nsigner_client_init(&client);
+
+    if (nsigner_client_connect_unix(&client, socket_name, 5000) != 0) {
+        fprintf(stderr, "connect failed: %s\n", nsigner_client_last_error(&client));
+        return 1;
+    }
+
+    if (nsigner_client_get_public_key(&client, "example-1", "", &response) != 0) {
+        fprintf(stderr, "request failed: %s\n", nsigner_client_last_error(&client));
+        nsigner_client_close(&client);
+        return 1;
+    }
+
+    printf("%s\n", response);
+    free(response);
+    nsigner_client_close(&client);
+    return 0;
+}

examples/sign_event_client.c

@@ -0,0 +1,33 @@
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "../client/nsigner_client.h"
+
+int main(int argc, char **argv) {
+    const char *socket_name = "nsigner";
+    const char *event_json = "{\"kind\":1,\"content\":\"hello from client example\",\"tags\":[],\"created_at\":1700000000}";
+    nsigner_client_t client;
+    char *response = NULL;
+
+    if (argc > 1 && argv[1] != NULL && argv[1][0] != '\0') {
+        socket_name = argv[1];
+    }
+
+    nsigner_client_init(&client);
+
+    if (nsigner_client_connect_unix(&client, socket_name, 5000) != 0) {
+        fprintf(stderr, "connect failed: %s\n", nsigner_client_last_error(&client));
+        return 1;
+    }
+
+    if (nsigner_client_sign_event(&client, "example-2", event_json, "main", &response) != 0) {
+        fprintf(stderr, "request failed: %s\n", nsigner_client_last_error(&client));
+        nsigner_client_close(&client);
+        return 1;
+    }
+
+    printf("%s\n", response);
+    free(response);
+    nsigner_client_close(&client);
+    return 0;
+}

increment_and_push.sh

@@ -153,14 +153,42 @@ git_commit_and_push_no_tag() {
     git push origin "$NEW_VERSION" || git push --force origin "$NEW_VERSION"
 }
 
+verify_binary_version() {
+    local bin_path="$1"
+    local expected="$2"
+
+    if [[ ! -x "$bin_path" ]]; then
+        print_error "Binary not found or not executable: $bin_path"
+        return 1
+    fi
+
+    local got
+    got="$($bin_path --version 2>/dev/null | awk '{print $2}')"
+    if [[ "$got" != "$expected" ]]; then
+        print_error "Binary version mismatch for $(basename "$bin_path"): expected $expected, got ${got:-<unknown>}"
+        return 1
+    fi
+
+    return 0
+}
+
 build_release_binary() {
     if [[ ! -f "build_static.sh" ]]; then
         print_error "build_static.sh not found"
         return 1
     fi
 
+    # Prevent stale artifacts from previous builds being uploaded.
+    rm -f build/nsigner_static_x86_64 build/nsigner_static_arm64
+
     ./build_static.sh > /dev/null 2>&1 || return 1
+    verify_binary_version "build/nsigner_static_x86_64" "$NEW_VERSION" || return 1
+
     ./build_static.sh --arch arm64 > /dev/null 2>&1 || print_warning "ARM64 build failed (continuing)"
+    if [[ -x "build/nsigner_static_arm64" ]]; then
+        verify_binary_version "build/nsigner_static_arm64" "$NEW_VERSION" || return 1
+    fi
+
     return 0
 }
 
@@ -253,9 +281,12 @@ main() {
             git tag "$NEW_VERSION" > /dev/null 2>&1
         fi
 
-        git_commit_and_push_no_tag
+        if ! build_release_binary; then
+            print_error "x86_64 release build failed; aborting release before push/upload"
+            exit 1
+        fi
 
-        build_release_binary || print_warning "x86_64 build failed"
+        git_commit_and_push_no_tag
 
         local binary_path_x86="build/nsigner_static_x86_64"
         local binary_path_arm64="build/nsigner_static_arm64"

install_qube_fips_nsigner.sh

@@ -110,6 +110,32 @@ download_nsigner_asset_url() {
     | head -n1 || true
 }
 
+verify_installed_version() {
+  local expected="$1"
+  local got_line=""
+  local got_ver=""
+
+  if [[ ! -x "${PREFIX_BIN}/nsigner" ]]; then
+    err "Installed binary missing: ${PREFIX_BIN}/nsigner"
+    exit 1
+  fi
+
+  got_line="$("${PREFIX_BIN}/nsigner" --version 2>/dev/null || true)"
+  got_ver="$(printf '%s\n' "${got_line}" | awk '{print $2}')"
+
+  if [[ -z "${got_ver}" ]]; then
+    err "Could not determine installed n_signer version from: ${got_line}"
+    exit 1
+  fi
+
+  if [[ "${got_ver}" != "${expected}" ]]; then
+    err "Downloaded binary version mismatch: expected ${expected}, got ${got_ver}"
+    err "Release asset appears stale or mislabeled."
+    err "Use NSIGNER_BINARY_URL to pin a known-good binary, or wait for a rebuilt release artifact."
+    exit 1
+  fi
+}
+
 install_nsigner() {
   local release_page=""
 
@@ -137,6 +163,8 @@ install_nsigner() {
     curl -fL -o "${PREFIX_BIN}/nsigner" "${asset_url}"
   fi
   chmod 0755 "${PREFIX_BIN}/nsigner"
+
+  verify_installed_version "${NSIGNER_VERSION}"
   log "Installed ${PREFIX_BIN}/nsigner from release binary"
 }
 

plans/auth_envelope_other_transports.md

@@ -0,0 +1,271 @@
+# Plan: Where else does the Schnorr auth envelope earn its keep?
+
+Status: **draft v1 — design exploration, for review**
+
+> **Origin.** [`plans/caller_token_identity.md`](caller_token_identity.md) introduced a per-request, BIP-340-Schnorr-signed *auth envelope* (Nostr kind 27235) that gives the TCP transport an application-layer identity. The TCP plan was deliberate about scope: AF_UNIX and qrexec keep their kernel/hypervisor identities, stdio inherits them, and the envelope is gated to TCP only. This document asks the next obvious question — **for which other transports is the same envelope actually useful, and where is it noise or worse?** — and proposes a small, conservative extension.
+
+The thesis up front: **the envelope is a tool for binding a stable program identity to a stream that the OS/hypervisor cannot itself attribute to a program**. Anywhere the OS already names the caller better than a pubkey could, the envelope adds attack surface for no gain. Anywhere the OS names a *machine* (uid, qube name) but cannot tell us *which program inside that machine*, the envelope earns its keep.
+
+---
+
+## 1. The framework: a 2x2 of what the substrate vouches for
+
+Every transport `n_signer` supports today, or might support tomorrow, can be classified along two axes:
+
+| | Substrate names a **principal** (uid, qube, account) | Substrate does **not** name a principal |
+|---|---|---|
+| **Substrate names a specific program** | A. Both. Strongest. | (impossible — naming a program implies naming its principal) |
+| **Substrate names only a machine/account, not a program** | B. Principal-only. The "which program" gap. | C. Anonymous pipe. |
+
+- **A** is hypothetical for our context. Not even AF_UNIX gives us this — `SO_PEERCRED.pid` is UX, not identity, because PIDs are reusable and the kernel does not bind PID to executable.
+- **B** is where AF_UNIX, qrexec, and stdio-via-qrexec actually live today. We learn `uid:1000` or `qubes:foo`, but two different binaries running as the same uid in the same qube look identical.
+- **C** is plain TCP, anonymous pipes, USB serial, Bluetooth — substrates that say only "some bytes arrived from somewhere."
+
+**The auth envelope's job is to upgrade B → A and C → A** by letting the program-with-a-keypair speak for itself, on top of whatever the substrate already provides. It does *not* replace substrate identity; it composes with it.
+
+This re-framing is the whole answer to the user's question. Every transport below is just a worked example of which cell it lives in.
+
+---
+
+## 2. Per-transport verdict
+
+| Transport | Substrate identity | Cell | Envelope verdict |
+|---|---|---|---|
+| AF_UNIX (current) | `SO_PEERCRED.uid` (kernel-attested) | B | **Optional, off by default.** Adds program-level identity inside one uid; useful for multi-program desktops, redundant for single-user vault qubes. |
+| qrexec (current) | `QREXEC_REMOTE_DOMAIN` (Xen-attested) | B | **Optional, off by default, but the most interesting case.** Solves the "many tools in one caller qube share one approval row" problem and the cross-qube state continuity question. See §3. |
+| stdio (current, interactive) | inherited uid of launching shell | B | **Off.** The user is at the terminal; substrate identity is the human, and the envelope cannot improve on that. |
+| stdio (current, qrexec-launched) | `QREXEC_REMOTE_DOMAIN` from env | B | **Same as qrexec row.** stdio over qrexec is qrexec by another name. |
+| stdio (anonymous pipe, e.g. systemd socket-activated, or shelled out from a daemon) | none | C | **Required if used in production.** No principal at all otherwise. See §4. |
+| TCP (implemented v2) | peer addr (forgeable beyond loopback) | C | **Required, on every request.** Already shipped; this plan does not modify it. |
+| FIPS / serial-over-USB (planned) | device path; no principal | C | **Required.** Same reasoning as TCP — substrate provides confidentiality of the wire (in FIPS's case) but no caller identity. |
+| Bluetooth / NFC (hypothetical) | MAC address (forgeable) | C | **Required.** |
+
+The verdict column collapses to three modes — **off**, **optional** (accepted if present, ignored if absent), **required** (rejected if absent) — selectable per listener.
+
+---
+
+## 3. The qrexec story (the user's actual question)
+
+Qubes is the case where the envelope buys the most, and where it most clearly solves a problem the user has named: *"keeping state between qubes is difficult."* Two distinct sub-problems hide under that phrase. The envelope addresses one of them cleanly and the other partially.
+
+### 3.1 Sub-problem 1: many programs, one approval row
+
+A typical caller qube — say `personal` — runs nostr_terminal, a browser extension, a CLI scratch tool, and a backup script. Today they all show up to the signer as `qubes:personal`. The user approves once, and from then on **every program in that qube is a signer for that nostr_index**. There is no way to express "the browser extension may sign kind-1 events but the CLI scratch tool may not." Approval granularity is one-per-qube, which is too coarse for any caller qube that holds more than one tool.
+
+With the envelope optional-on for qrexec:
+
+- nostr_terminal in `personal` signs envelopes with its caller pubkey `Pk_term`. Browser extension signs with `Pk_ext`. The signer records *two distinct caller_ids* — `qubes:personal+pubkey:<Pk_term>` and `qubes:personal+pubkey:<Pk_ext>` (composite form, see §6) — and prompts once per program.
+- Programs that send no envelope keep the legacy `qubes:personal` identity and the legacy approval row. Backwards compatible.
+- The user gets per-program revocation: removing the approval for `Pk_ext` does not affect nostr_terminal, even though both run inside `personal`.
+
+This is the same connection-churn fix the TCP plan delivered, applied to a different ambiguity: not "same network address, different process" but "same qube, different program." The fix is identical because the underlying gap is identical — the substrate names something coarser than the unit we want to authorize.
+
+### 3.2 Sub-problem 2: state continuity between qubes
+
+In Qubes, programs that want shared identity across qubes — say a tool the user runs in both `personal` and `work`, or a tool installed in a disposable that is recreated each launch — cannot use any of the usual "save a token to disk" tricks because the qubes are separate state domains. The qrexec policy can route the call but cannot share secrets.
+
+The envelope does not magically share state across qubes — but **it makes the question well-formed**. Two patterns become available:
+
+- **Per-qube installation, distinct identity.** Tool `T` installed in `personal` generates its own keypair on first run, stored in that qube. Tool `T` in `work` generates a different keypair. The signer sees two callers; the user approves each. This is exactly what the security model wants — the qubes are *different trust domains*, so they should have different identities, full stop.
+- **Per-tool identity, shared across qubes via deliberate seed copy.** A power user who genuinely wants "the same identity for nostr_terminal in `personal` and `work`" can copy nostr_terminal's seed (or derived caller key) between the two qubes themselves, using Qubes' usual file-copy primitives. The signer then sees one caller identity from two qubes. Whether that is a good idea is a user-policy decision; the protocol simply tolerates it.
+
+The disposable-VM case is the most interesting. A disposable that re-rolls its caller keypair on every boot will re-prompt the signer every boot — which is correct behavior. *"This is a fresh untrusted environment"* is exactly what a disposable is. If the user wants disposable-but-recognized, they are asking for the per-tool seed pattern above and have to accept the tradeoff that the seed material outlives the disposable.
+
+The envelope does not solve cross-qube state by itself. What it does is **give the user a stable, signer-visible name to make their state-management decisions against** — instead of forcing every cross-qube identity question through the qube-name primitive, which is too coarse to express the question.
+
+### 3.3 Why "optional, off by default" rather than "required"
+
+Required envelopes for qrexec would break every existing caller (shell scripts, the existing client examples in [`documents/qubes_client_examples.md`](../documents/qubes_client_examples.md)) and force every Qubes caller to grow Schnorr-signing capability before it can talk to the signer. That is too high a cost for a transport whose substrate identity is already strong.
+
+Optional means:
+
+- Old callers keep working unchanged. Their `caller_id` stays `qubes:<vm>`.
+- New callers that *want* per-program approvals send envelopes and get `qubes:<vm>+pubkey:<hex>`.
+- Operators who want to enforce envelope-on-qrexec for a hardened deployment can flip a flag (`--qrexec-require-auth`).
+
+The default-off posture matches the TCP plan's principle: *give the weakest substrate the strongest application-layer identity.* qrexec is not the weakest; it is the second-strongest. It earns the upgrade only where the operator opts in.
+
+---
+
+## 4. The stdio story
+
+stdio mode in `n_signer` has three real-world spawning patterns:
+
+1. **Interactive: a user runs `nsigner --listen stdio` in a terminal and pipes a request in.** Substrate identity is the user's own uid. The user is physically present at the prompt anyway. **Envelope adds nothing.** Off.
+
+2. **qrexec service: stdio with `QREXEC_REMOTE_DOMAIN` set.** Already covered as the qrexec row in §2. Same verdict as qrexec.
+
+3. **Spawned by another program over an anonymous pipe.** Daemon `D` execs `nsigner --listen stdio` and pipes JSON-RPC over the inherited fds. The signer sees only `STDIN_FILENO`; there is no `SO_PEERCRED` (no socket), no `QREXEC_REMOTE_DOMAIN`, no peer address. Today the signer falls back to its own uid as caller_id, which is to say *the signer is its own caller* — meaningless as identity. **This is cell C.** If anyone is using this pattern, the envelope is the only available identity primitive.
+
+The third pattern is rare but not hypothetical. systemd socket-activated services, container init wrappers, and "supervisor that spawns one signer process per request" deployments all fit. Today they are silently insecure (any program in the same uid can pipe a request in and be `caller_id = uid:1000`, indistinguishable from any other). With envelope-required for anonymous-pipe stdio, the daemon must hold a keypair and identify itself, and the signer can record per-daemon approvals.
+
+The detection rule is mechanical: if the listen mode is stdio AND `QREXEC_REMOTE_DOMAIN` is unset AND `SO_PEERCRED` is unavailable on stdin (it is not a socket), classify the stream as anonymous-pipe stdio and require the envelope. Two existing pieces of code already participate in this branch: [`server_get_caller`](../src/server.c:1181) for the QREXEC env check, and the listen-mode plumbing in [`src/main.c:1043`](../src/main.c:1043).
+
+---
+
+## 5. The AF_UNIX story (briefly)
+
+AF_UNIX is the strongest substrate today and the one most likely to be misjudged. It is tempting to say "uid is enough." For single-user vault qubes it is. For shared workstations or for the per-program-revocation use case described in §3.1, it is not.
+
+The right disposition for AF_UNIX is identical to qrexec: **optional envelope, off by default, on-flag to require**. Same composite caller_id form. The only difference is that the prompt UX should still surface `pid=N (exe=/path)` from `SO_PEERCRED` as decoration alongside the npub, because on a local machine the user can `ps -p N` to verify in a way they cannot for a remote pubkey.
+
+This was [`plans/caller_token_identity.md`](caller_token_identity.md) §13 open question 5 ("should AF_UNIX accept an envelope as additional identity?") with the v2 default of "no." This document **revisits that default** and proposes "yes, but optional." See §6 and §8.
+
+---
+
+## 6. Composite caller_id form
+
+When envelope is **optional and present** on a non-TCP transport, the caller_id needs to combine substrate identity and pubkey identity. The proposed form:
+
+```
+qubes:personal+pubkey:abc123…def
+uid:1000+pubkey:abc123…def
+anon-stdio+pubkey:abc123…def      ; for case §4.3
+```
+
+Properties:
+
+- **Lexicographic prefix matches substrate-only callers.** A policy entry for `qubes:personal` does **not** match `qubes:personal+pubkey:…` — they are distinct strings, distinct rows. This is intentional: opting into envelope auth means opting into a new, separate identity, not "same identity but with extra proof."
+- **The plus character is illegal in every existing caller_id form** (uids are digits, pubkeys are hex, qube names are alphanumeric+hyphen). Using `+` as separator avoids ambiguity.
+- **Width.** `caller_id` was widened to 80 bytes in v2 of the TCP plan ([`plans/caller_token_identity.md:181`](caller_token_identity.md:181)). The composite form needs `len("qubes:") + 64 + len("+pubkey:") + 64 + 1` ≈ 144 bytes. Bumps to 160 to round.
+
+Approvals attach to the composite string. A user who approves the composite form is approving "this program *running in* this qube," not "this program anywhere" and not "this qube's anything." That is the correct semantics for the per-program-revocation use case.
+
+For TCP — where substrate identity does not exist — the form remains the bare `pubkey:<hex>` from v2. No change.
+
+---
+
+## 7. Wire-protocol changes (small)
+
+The existing envelope already carries everything needed; only the verification gate changes per transport.
+
+### 7.1 Per-listener auth posture
+
+Three settings, one per listener:
+
+| Posture | Behavior on receipt |
+|---|---|
+| `off` | `auth` field, if present, is **ignored**. caller_id is substrate-only. Default for AF_UNIX, qrexec, interactive stdio. |
+| `optional` | If `auth` is present and verifies → composite caller_id. If `auth` is absent → substrate-only caller_id. If `auth` is present and fails verification → reject. Operator opt-in for AF_UNIX/qrexec/stdio. |
+| `required` | `auth` must be present and verify. Default for TCP, FIPS-serial, anonymous-pipe stdio. |
+
+CLI plumbing extends what the TCP plan already added:
+
+```
+--listen unix --auth off            # default
+--listen unix --auth optional
+--listen qrexec --auth optional
+--listen stdio --auth required      # for anon-pipe deployments
+--listen tcp:... --auth required    # only legal value for tcp; kept explicit
+```
+
+The auth-skew-seconds and nonce cache are listener-context state; they already exist in `server_ctx_t` from v2 and are reused unmodified.
+
+### 7.2 The envelope itself: zero changes
+
+Same kind 27235, same three required tags, same JCS body hash, same Schnorr verification primitive [`nostr_verify_event_signature`](../resources/nostr_core_lib/nostr_core/nip001.h:20). A client that signs envelopes for TCP today can sign them for qrexec tomorrow with no code change. This is the single most important property of the proposal — it preserves the v2 envelope as a portable, transport-independent artifact.
+
+### 7.3 Replay cache scoping
+
+One subtle question: is the nonce cache per-listener or process-global? Process-global is simpler and strictly stricter (an envelope replayed across two listeners is also rejected). Per-listener is more permissive but has no real attack-model justification. **Default: process-global**, unchanged from v2.
+
+---
+
+## 8. Decision matrix and recommended defaults
+
+| Transport | Default posture | Operator can flip to | Rationale |
+|---|---|---|---|
+| AF_UNIX | off | optional, required | uid is strong; envelope is for power users who need per-program granularity. |
+| qrexec | off | optional, required | qube is strong; envelope solves §3.1 for users who hit it. |
+| stdio (interactive) | off | (locked off) | Envelope cannot improve on a human at the terminal. |
+| stdio (qrexec-launched) | inherits qrexec posture | (inherits) | Same substrate. |
+| stdio (anonymous pipe) | required | (locked required) | No substrate identity exists; refusing is the only safe default. |
+| TCP | required | (locked required) | Already v2 default. Unchanged. |
+| FIPS / USB-serial (planned) | required | (locked required) | Same as TCP — wire identity is fictional. |
+
+"Locked" rows reflect transports where flipping the posture would re-introduce the gap the envelope was designed to close, and the CLI rejects the change.
+
+---
+
+## 9. Implementation order
+
+Each step is independently mergeable, gated behind the per-listener `--auth` flag default of `off` for the new transports so existing callers see no behavior change.
+
+1. **Refactor: lift the v2 auth gate out of the TCP-specific branch in [`server_handle_one`](../src/server.c:1192) into a transport-agnostic helper** parameterized by posture. No semantic change yet; TCP listener still passes `required`.
+2. **Add the `--auth {off|optional|required}` CLI flag** with per-listener storage on `server_ctx_t`. Default off for unix/qrexec, required for tcp, off-locked for interactive stdio, required-locked for anonymous-pipe stdio.
+3. **Add anonymous-pipe-stdio detection.** In [`server_get_caller`](../src/server.c:1181), when listen mode is stdio and `QREXEC_REMOTE_DOMAIN` is unset, probe `SO_PEERCRED` on stdin; on failure mark the stream as anonymous-pipe and require auth.
+4. **Composite caller_id format** in [`caller_identity_t`](../src/server.c:404). Widen to 160. Add a small helper `caller_id_compose(buf, sz, substrate_kind, substrate_value, pubkey_hex)`.
+5. **`--preapprove` extension.** Accept the composite form (`caller=qubes:personal+pubkey:<hex>`, `caller=uid:1000+pubkey:<hex>`). Existing forms stay valid.
+6. **Tests.**
+   - Optional-mode AF_UNIX accepting both with-envelope and without-envelope requests, producing two distinct caller_ids.
+   - Optional-mode qrexec with two distinct pubkeys from one source qube → two prompts, two approvals, independent revocation.
+   - Anonymous-pipe-stdio rejects no-envelope requests with code 2014.
+   - TCP behavior unchanged (regression check on v2).
+7. **Documentation.**
+   - [`documents/SECURITY.md`](../documents/SECURITY.md) §3 identity table: add the composite kinds; clarify that envelope is now a portable identity layer, not a TCP-only feature.
+   - [`documents/QUBES_OS.md`](../documents/QUBES_OS.md): add a §3.4 on per-program identity within a qube and the disposable-VM tradeoff.
+   - [`documents/CLIENT_IMPLEMENTATION.md`](../documents/CLIENT_IMPLEMENTATION.md): note that any client may attach an envelope on any transport; the signer's posture decides whether it is honored or required.
+
+## 10. What this plan deliberately does not do
+
+- **Does not change TCP behavior.** The v2 contract on TCP — required envelope, every request — is preserved exactly.
+- **Does not introduce a new envelope format, kind, or canonicalization.** Reuses kind 27235 and the JCS body-hash rule from v2 verbatim.
+- **Does not propose persistent state** anywhere. Approvals stay in RAM; no caller registry on disk; the §1 "crash equals total wipe" property of [`documents/SECURITY.md:19`](../documents/SECURITY.md:19) is unchanged.
+- **Does not invent an answer to cross-qube state continuity.** It articulates the question and gives the user a primitive (a stable pubkey-named caller) against which to make their own state decisions.
+- **Does not add transport encryption** for any substrate. Confidentiality is the substrate's job (FIPS, qrexec, AF_UNIX with abstract namespace, loopback). The envelope is auth, not encryption.
+
+## 11. Open questions for review
+
+1. **Is the composite caller_id form (`substrate+pubkey:...`) the right disposition, or should the envelope, when present, *override* substrate identity entirely (replacing rather than composing)?** The override form is simpler — one identity, not two — but it discards information the user might want (the npub is verified; the qube name is hypervisor-attested; both data points are useful at the prompt). Default: compose.
+2. **Should anonymous-pipe stdio be required or rejected outright?** A reasonable case can be made that `nsigner --listen stdio` over a non-tty, non-socket fd is just *misuse* and should refuse to start rather than silently demand envelopes. Default: require envelope; allow operator to disable the listen mode entirely if undesired.
+3. **Should the `--auth optional` setting on AF_UNIX/qrexec be a per-listener flag (today's proposal) or per-method (e.g. envelope required for `sign_event` but not for `get_public_key`)?** Per-method adds policy surface for limited gain; substrate identity is already the per-method gate via the existing role table. Default: per-listener only.
+4. **Does the v2 nonce cache size of 1024 still suffice when up to four listeners may share it?** Yes — the bound is "envelopes per skew window," not "listeners." Confirmed sufficient. No change.
+5. **Should `qubes:<vm>+pubkey:<hex>` and `pubkey:<hex>` (TCP) for the same pubkey be considered the same caller for `--preapprove` convenience?** No. They are different identities by construction (different substrates, different threat models). An operator who wants both pre-approved writes both lines. Default: keep them distinct.
+
+---
+
+## Appendix A — Mermaid: revised per-transport decision tree
+
+```mermaid
+flowchart TD
+    A[Request arrives on a listener] --> B{listener auth posture}
+    B -- off --> C[ignore any auth field]
+    C --> D[caller_id = substrate-only]
+    B -- optional --> E{auth field present?}
+    E -- no --> D
+    E -- yes --> F[verify envelope per v2 rules]
+    F -- fail --> G[reject 2010-2017]
+    F -- ok --> H[caller_id = substrate + pubkey:hex]
+    B -- required --> I{auth field present?}
+    I -- no --> J[reject 2014 auth_envelope_required]
+    I -- yes --> F
+    D --> K[normal policy_check]
+    H --> K
+    K --> L{verdict}
+    L -- ALLOW --> M[dispatch RPC]
+    L -- DENY --> N[2001 policy_denied]
+    L -- PROMPT --> O[approve / save / register caller_id]
+    O --> M
+```
+
+## Appendix B — Worked example: per-program identity inside a qube
+
+Caller qube `personal` runs two tools:
+
+- nostr_terminal, holding caller key `Pk_term`.
+- A custom shell script, no keypair.
+
+Operator starts the signer with:
+
+```
+nsigner --listen qrexec --auth optional \
+  --preapprove caller=qubes:personal+pubkey:Pk_term,role=main
+```
+
+First request from nostr_terminal carries an envelope signed by `Pk_term`. Signer verifies, builds caller_id `qubes:personal+pubkey:Pk_term`, hits the pre-approval, signs without prompting.
+
+First request from the shell script carries no envelope. Signer skips verification, builds caller_id `qubes:personal`, finds no approval, prompts the user. User can approve `[a]` for the shell script independently of nostr_terminal.
+
+Later, the user wants to revoke the shell script's access (a future TUI hotkey). They remove the `qubes:personal` row. nostr_terminal continues to work because its row `qubes:personal+pubkey:Pk_term` is untouched. **Per-program revocation, achieved without any change to qrexec policy or the qube boundary.**
+
+This is the concrete answer to the user's "is this useful for other transports" question — yes, in qrexec specifically, where it converts qube-granularity approvals into program-granularity approvals while leaving the qube boundary itself unchanged.

plans/docker_runtime_image.md

@@ -0,0 +1,277 @@
+# Plan: Runtime Docker image for n_signer with TCP + auth-envelope onboarding
+
+Status: **draft v1 — for review**
+
+This plan documents a path for new users to download and run [`n_signer`](../README.md) inside a Docker container with minimal friction, while preserving the project's existing security posture (zero filesystem footprint at runtime, mlock'd in-memory secrets, deny-by-default approvals, crash-equals-total-wipe). It complements — and does not replace — the native binary distribution.
+
+The companion work breakdown is tracked as todos in this task; this document captures the rationale and architectural decisions behind those todos.
+
+Related plans and references:
+
+- [`plans/caller_token_identity.md`](caller_token_identity.md) — the auth envelope spec that makes TCP a first-class authenticated transport.
+- [`plans/nip46_bunker_mode.md`](nip46_bunker_mode.md) — deferred relay-based transport that would offer a Docker-friendly future alternative.
+- [`Dockerfile.alpine-musl`](../Dockerfile.alpine-musl) — current build-only Dockerfile that this plan extends.
+- [`build_static.sh`](../build_static.sh) — host-side wrapper around the build image.
+- [`increment_and_push.sh`](../increment_and_push.sh) — existing release flow that this plan extends.
+- [`src/server.c`](../src/server.c) — current transport implementation (`unix`, `stdio`, `qrexec`, `tcp:HOST:PORT`).
+- [`src/auth_envelope.c`](../src/auth_envelope.c) — verifier of NIP-01-shaped `kind:27235` auth envelopes.
+
+---
+
+## 1. Why this plan exists
+
+Today a new user has three realistic on-ramps to `n_signer`:
+
+1. Download the static binary from a release and run it natively.
+2. Clone the repo and rebuild via [`build_static.sh`](../build_static.sh), which itself uses Docker as a build environment but produces a host binary.
+3. Hand-roll a `Dockerfile` and `docker run` invocation around the static binary.
+
+None of those produce a one-command `docker pull` + `docker run` experience. [`Dockerfile.alpine-musl`](../Dockerfile.alpine-musl) ends with `FROM scratch` and copies the binary out — it is a build artifact, not a runnable image. This plan closes that gap.
+
+The Docker path also gives users defense-in-depth that the native path cannot offer: PID-namespace isolation prevents same-user processes on the host from `ptrace`'ing the signer, mount-namespace isolation hides the binary, default seccomp shrinks the kernel attack surface, and `--cap-drop ALL` plus `--security-opt no-new-privileges` constrain a hypothetical compromise of the signer itself. None of this defends against host root, kernel exploits, or side channels — that boundary requires a VM-class isolation like the Qubes path described in [`documents/QUBES_OS.md`](../documents/QUBES_OS.md).
+
+---
+
+## 2. Goals
+
+1. **One-command run.** A new user with Docker installed should be able to `docker pull` and `docker run` to get a working interactive `n_signer` TUI, with no source checkout and no manual binary placement.
+2. **Hardened by default.** The recommended invocation in the documentation must include `--read-only`, `--cap-drop ALL`, `--security-opt no-new-privileges`, resource limits, and `127.0.0.1`-only port publishing. Users who copy-paste the docs land on the safer configuration without having to think.
+3. **TCP is the supported transport for the image.** Out of the four current transports, TCP is the only one that crosses the container/host network-namespace boundary cleanly today, and it is the only one with a working caller-authentication story per [`plans/caller_token_identity.md`](caller_token_identity.md). The image's `ENTRYPOINT` reflects this.
+4. **No new transport code in v1.** This plan uses transports that already exist in [`src/server.c`](../src/server.c). Adding a `unix-path` transport variant for bind-mounted UNIX sockets is a separate plan that this one explicitly does not depend on.
+5. **Preserve the runtime invariants.** Zero filesystem footprint at runtime, mlock'd secrets, crash-equals-total-wipe, and human-attended TUI all carry over. The image runs `--read-only`; no state files; SIGTERM from `docker stop` triggers the same wipe path as Ctrl-C in a terminal.
+6. **Verifiable provenance.** Pulled images must be cryptographically verifiable to a release tag, with an SBOM and vulnerability scan attached as release assets so users can inspect what they are running.
+7. **No regression for the native path.** The static-binary distribution and the `build_static.sh` build flow continue to work unchanged. The Docker image is an *additional* on-ramp, not a replacement.
+
+---
+
+## 3. Non-goals
+
+- **No multi-user, long-running daemon mode.** The TUI-attended, foreground-only design from [`README.md`](../README.md) is preserved. The image is run with `-it`, attached to a terminal. Background `docker run -d` is explicitly unsupported and will be documented as such.
+- **No bundled clients.** The image contains only the signer binary. Clients (browser extension, native apps, examples) ship separately.
+- **No persistent volume.** No mnemonic-on-disk, no policy-on-disk. The signer's "no runtime config or state files" rule from [`README.md`](../README.md) applies unchanged inside the container.
+- **No network exposure beyond loopback by default.** The documented invocation publishes ports to `127.0.0.1` only. LAN/WAN exposure is out of scope and would require a separate threat model plus TLS termination, which is its own plan.
+- **No NIP-46 relay transport.** That remains deferred per [`plans/nip46_bunker_mode.md`](nip46_bunker_mode.md).
+- **No host-UNIX-socket bridging.** Bind-mounting a UNIX socket from the container to the host is appealing for UID-based identity but requires a `--listen unix-path:` mode that does not exist today. Tracked as a follow-up note (todo 20), out of scope here.
+- **No image-internal privilege separation.** The signer runs as a single non-root user inside the container; further compartmentalization (separate uid for TUI vs network handling) is not in scope for v1.
+
+---
+
+## 4. Threat model delta vs. the native binary
+
+The Docker image inherits the same in-process threat model as the native binary (mlock'd secrets, no disk artifacts, deny-by-default approvals). It adds:
+
+| Boundary | Native terminal | Docker image (this plan) |
+|---|---|---|
+| Same-UID host process reads signer memory | Vulnerable to `ptrace`, `/proc/<pid>/mem` | Blocked by PID namespace |
+| Compromised signer escalates on host | Has full UID privileges on host | Constrained by `--cap-drop ALL`, `--security-opt no-new-privileges`, default seccomp |
+| Compromised signer writes persistent files | Can write anywhere UID has access | `--read-only` rootfs blocks writes; no volumes mounted |
+| Core dump leaks key material | Possible if `ulimit` or systemd allows | `--read-only` plus no writable paths means no core file path |
+| Host root reads signer memory | Unconstrained | Still unconstrained — `nsenter`, `docker exec`, host `/proc` all work. **Documented as a non-defense.** |
+| Kernel exploit | Full host compromise | Full host compromise — shared kernel. **Documented as a non-defense.** |
+| Network reachability | Bound by socket file perms or abstract namespace | Bound by Docker port publishing; `127.0.0.1` only by docs |
+| TCP caller identity | Auth envelope (per [`plans/caller_token_identity.md`](caller_token_identity.md)) | Same — unchanged inside the container |
+
+The user-facing security message in [`documents/SECURITY.md`](../documents/SECURITY.md) gets a small subsection (todo 12) calling out exactly this — what Docker buys you and what it does not — so users do not over-trust container isolation.
+
+---
+
+## 5. Image architecture
+
+### 5.1 Multi-stage Dockerfile
+
+Extend [`Dockerfile.alpine-musl`](../Dockerfile.alpine-musl) with a third stage that produces a runnable image. The existing two stages — `builder` and the `FROM scratch AS output` extraction stage — are preserved unchanged so [`build_static.sh`](../build_static.sh) keeps working.
+
+```mermaid
+graph LR
+    A[Stage: builder<br/>alpine:3.19 + toolchain] --> B[Stage: output<br/>FROM scratch<br/>used by build_static.sh]
+    A --> C[Stage: runtime<br/>FROM scratch<br/>ENTRYPOINT nsigner]
+    B -.-> D[host binary<br/>build/nsigner_static_*]
+    C -.-> E[OCI image<br/>nsigner:vX.Y.Z]
+
+    style C fill:#9f9
+    style E fill:#9f9
+```
+
+The runtime stage:
+
+- Starts `FROM scratch` (no shell, no libc, no busybox — the binary is fully static MUSL).
+- Copies in the stripped static binary as `/nsigner`.
+- Sets `ENTRYPOINT ["/nsigner"]` and a default `CMD` of `["--listen", "tcp:0.0.0.0:7777"]`. Users can override CMD to pick another transport, but the ENTRYPOINT remains fixed at the binary.
+- Declares OCI image labels (todo 3) — source URL, version, revision (git SHA), licenses, title, description — sourced from the existing `NSIGNER_VERSION` macro that [`increment_and_push.sh`](../increment_and_push.sh) already maintains.
+- Runs as a non-root UID. Because `FROM scratch` has no `/etc/passwd`, this is done with a numeric UID via `USER 65532`. The static binary has no UID-name dependencies.
+- `EXPOSE 7777` for documentation only (does not affect runtime).
+
+### 5.2 Default `--listen` choice
+
+The image defaults to `--listen tcp:0.0.0.0:7777`. Rationale (todo 15):
+
+- It is the only existing transport that crosses the container netns boundary without `--network=host` (which would defeat the isolation we are running Docker for).
+- It is the only transport with a working caller-authentication story today, via the auth envelope verified in [`src/auth_envelope.c`](../src/auth_envelope.c) and required for TCP per [`src/server.c`](../src/server.c) lines around 1313.
+- `0.0.0.0` inside the container is safe **only** when the host publishes to `127.0.0.1`. The documentation makes this binding explicit and warns against `-p 7777:7777` (which publishes to all host interfaces). Todo 16 covers this in detail.
+- Users who want stdio (one-shot) or qrexec (Qubes-specific) override `CMD` themselves; the default targets the dominant Docker-on-laptop case.
+
+### 5.3 Image size and layers
+
+Static MUSL binary, stripped, is roughly single-digit MB. The runtime image will be that plus the OCI metadata — well under 10 MB. `docker pull` is a few seconds on any reasonable connection. This is documented as a property, not just a coincidence, because it directly supports the "easy for new users" goal.
+
+---
+
+## 6. Build, tag, and publish flow
+
+```mermaid
+graph LR
+    Dev[Developer<br/>./increment_and_push.sh -r] --> Bump[Bump version macros]
+    Bump --> Tag[git tag vX.Y.Z]
+    Tag --> Build[Build static binaries<br/>x86_64 + arm64]
+    Build --> Test[Run make test inside builder]
+    Test --> Img[Build runtime image<br/>buildx multiarch]
+    Img --> Sbom[Generate SBOM + vuln scan]
+    Sbom --> Sign[cosign sign image]
+    Sign --> Push[Push image and assets<br/>to registry]
+    Push --> Release[Create Gitea release<br/>with binary, sbom, image digest, verify cmd]
+```
+
+### 6.1 Registry choice
+
+Decision pending (todo 4). Three viable destinations:
+
+1. **The existing Gitea registry at `git.laantungir.net`.** Aligns with the existing release flow that already uses `~/.gitea_token`. Self-hosted, under project control. Downside: less familiar to new users; they may need to log in to pull.
+2. **GitHub Container Registry (GHCR).** Free, public, well-known, integrates with cosign keyless signing using GitHub OIDC. Requires a GitHub mirror.
+3. **Docker Hub.** Most familiar to new users. Rate limits on anonymous pulls. Requires a Docker Hub account and token.
+
+The plan recommends GHCR as primary because keyless cosign signing dramatically simplifies the trust story for new users (`cosign verify ghcr.io/...` with no key management). The Gitea registry is a viable alternative if the project prefers to stay self-hosted; in that case, key-based cosign signing replaces keyless. Either way, the choice is documented up front so users know where to pull from.
+
+### 6.2 Multi-arch
+
+Built via `docker buildx build --platform linux/amd64,linux/arm64`. The existing builder stage already handles both architectures (it picks `libnostr_core_x64.a` vs `libnostr_core_arm64.a` based on `uname -m`). A `Makefile` target (todo 2) wraps this so the developer command is `make docker-image-multiarch`.
+
+### 6.3 Tags
+
+- `vX.Y.Z` — immutable, matches git tag and binary release.
+- `latest` — moves to newest stable release.
+- `vX` and `vX.Y` — moving tags for users who want major/minor pinning.
+
+All tags are signed; `latest` is signed at each release.
+
+### 6.4 Provenance
+
+Every release attaches:
+
+- Image digest (`sha256:...`) in release notes.
+- `cosign verify` command line as a copy-pasteable block.
+- SBOM in SPDX or CycloneDX format (syft) as a release asset and as an OCI attestation attached to the image.
+- Vulnerability scan output (grype or trivy) as a release asset.
+
+This makes "is the image I pulled the one the project published?" a one-command answer. Todos 6 and 7 cover this.
+
+### 6.5 Hooks into the existing release script
+
+[`increment_and_push.sh`](../increment_and_push.sh) currently:
+
+1. Bumps the version macros in `src/main.h` or `src/main.c`.
+2. Tags the commit.
+3. Builds x86_64 and arm64 static binaries.
+4. Verifies `--version` of each binary matches the new tag.
+5. Creates a Gitea release and uploads the binaries and a source tarball.
+
+The image flow plugs in between steps 4 and 5 (todo 5):
+
+5a. Build the runtime image for both architectures via buildx.
+5b. Generate SBOM and vuln scan.
+5c. Sign with cosign.
+5d. Push the image and signatures to the chosen registry.
+5e. Capture the resulting digest for the release notes.
+
+Each of these steps is gated on a credential being present, mirroring the existing `~/.gitea_token` check. A developer without registry credentials still gets a successful binary release; the image steps emit warnings and skip. This keeps the local release flow usable in offline or partial-credential setups.
+
+### 6.6 CI integration
+
+A CI smoke test (todo 13) boots the just-built runtime image with the default `--listen tcp:0.0.0.0:7777`, drives a single `get_public_key` request from a host client over the published port, and asserts a clean shutdown. This catches regressions where the binary builds but cannot actually serve TCP from inside a container — for example, a future code change that defaults to abstract sockets in a way that breaks netns separation.
+
+The existing `make test` suite is also run inside the builder stage (todo 14) before the artifact is extracted, so we have a tested-then-shipped guarantee on the binary that ends up in the image.
+
+---
+
+## 7. New-user runbook (target end-state)
+
+This is the experience the plan is optimizing for. After the work is done, the [`documents/DOCKER.md`](../documents/DOCKER.md) (todo 8) opens with effectively this:
+
+```bash
+# 1. Verify the image you are about to run
+cosign verify ghcr.io/laantungir/nsigner:v0.X.Y \
+  --certificate-identity-regexp 'https://github.com/laantungir/n_signer' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+# 2. Run with hardened defaults
+docker run -it --rm \
+  --read-only \
+  --cap-drop ALL \
+  --security-opt no-new-privileges \
+  --pids-limit 64 \
+  --memory 128m \
+  -p 127.0.0.1:7777:7777 \
+  ghcr.io/laantungir/nsigner:v0.X.Y
+```
+
+The TUI then comes up exactly as it does for the native binary — mnemonic prompt, role table, status display, approval prompts. From the user's perspective, the only differences are the longer command line and the fact that pressing Ctrl-C now also stops the container.
+
+A second documentation block (todo 9) walks through writing a TCP client that builds a `kind:27235` auth envelope per [`plans/caller_token_identity.md`](caller_token_identity.md), signs it with BIP-340 Schnorr, and gets approved exactly once at the TUI. A worked example client is added to [`examples/`](../examples) (todo 10) so users have a copy-pasteable starting point that they can run on the host against the containerized signer.
+
+---
+
+## 8. Risks and decisions
+
+### 8.1 TCP-only is a real limitation
+
+UID-based identity is preserved on AF_UNIX abstract sockets, which is a strong primitive in the native deployment. In Docker, that primitive is gone — abstract sockets do not cross netns. This plan accepts that and shifts to pubkey-based identity via the auth envelope. The trade-off is documented; users who specifically want UID-based identity stay on the native binary, or wait for the future `unix-path` transport plan (todo 20) that would let them bind-mount a pathname socket and recover `SO_PEERCRED.uid`. UID identity inside the container is also affected by Docker user-namespace remapping, which is another reason this plan does not pretend AF_UNIX inside a container is equivalent to AF_UNIX on the host.
+
+### 8.2 `0.0.0.0` inside the container is unforgiving of misconfiguration
+
+If a user copies the image's default `CMD` but writes `-p 7777:7777` (forgetting the `127.0.0.1:` prefix), they expose the signer to any host on the network. This is documented prominently (todo 16) with the explicit warning. We considered defaulting the CMD to `tcp:127.0.0.1:7777`, but that breaks Docker's port-publishing model — the host-side `127.0.0.1:7777` proxy needs to talk to the container's network interface, which is not loopback. So the safer-looking default is actually broken. The chosen approach (default `0.0.0.0` inside, document loopback publishing on the host) is the only one that works with Docker's networking semantics, but it requires that warning.
+
+### 8.3 TUI under `docker run -it` may have edge cases
+
+The signer's TUI uses raw terminal input for keystroke approvals, ANSI status redraws, and signal-driven shutdown. Most of this works under `docker run -it` but the plan reserves a verification step (todo 19) to confirm:
+
+- `a` / `y` / `n` / `q` / `l` keystrokes deliver the same response as on a native terminal.
+- ANSI redraws do not get garbled by Docker's TTY layer.
+- `docker stop` (which sends SIGTERM, then SIGKILL after grace) triggers the same total-state-wipe path as Ctrl-C, including mnemonic zeroization.
+- `docker kill` (SIGKILL only) leaves no recoverable state — by the existing crash-equals-wipe property, this should already hold, but the plan explicitly tests it.
+
+Any deviation discovered is documented as a caveat in [`documents/DOCKER.md`](../documents/DOCKER.md), not silently worked around.
+
+### 8.4 Host root is not blocked
+
+The plan documents this as a non-defense. Users whose threat model includes "another user on the same host has root" should not assume Docker isolates against that. They should run on a system where they trust root, or move to a Qubes-style VM compartment as documented in [`documents/QUBES_OS.md`](../documents/QUBES_OS.md). This is not a flaw in the plan; it is a property of containers that is easy to misunderstand and therefore worth stating up front.
+
+### 8.5 Image sprawl across registries
+
+If both Gitea and GHCR end up hosting the image, users may pull the wrong one or skip signature verification because "the other registry's image is the same anyway." The decision in §6.1 (one primary registry) is made specifically to avoid this. A secondary mirror is acceptable only if it carries the same digests and the same cosign signatures, and the documentation makes the mirror status explicit.
+
+---
+
+## 9. Out of scope, explicitly
+
+Listed so the plan's scope is clear:
+
+- TLS termination for TCP (a reverse-proxy-in-container pattern).
+- Remote signing (binding TCP to non-loopback). Both require a separate threat model and are deferred.
+- A `--listen unix-path:` transport that would let Docker users bind-mount a pathname socket. Tracked as todo 20 for a follow-up plan.
+- A NIP-46 relay transport. Deferred per [`plans/nip46_bunker_mode.md`](nip46_bunker_mode.md).
+- Reproducible builds in the strict bit-for-bit sense. The static-binary build is already close to deterministic, but full reproducibility (matching digests across rebuilds at a given tag) is its own engineering problem and is not promised here.
+- Distro packages (deb, rpm, Homebrew). The native binary remains a release asset; OS-native packaging is its own track.
+
+---
+
+## 10. Acceptance criteria
+
+The plan is considered delivered when **all** of the following are true:
+
+1. A new user with only Docker installed can pull and run the image with one `docker run` command from [`documents/DOCKER.md`](../documents/DOCKER.md) and see the same TUI they would see from the native binary.
+2. `cosign verify` against the published image passes for the chosen registry, and the verification command is in the release notes for that tag.
+3. SBOM and vulnerability scan output are attached to the release.
+4. Pressing Ctrl-C in the attached terminal, and `docker stop` from another shell, both result in the signer process exiting cleanly with the existing zeroization path having run. No leftover state on the container's writable layer (which is `--read-only` anyway).
+5. A TCP client running on the host, using the example added in todo 10, can complete one `get_public_key` round trip after a single `[a]` approval at the TUI, and a second request from the same client pubkey is served silently.
+6. The CI smoke test (todo 13) is green on every PR that touches `Dockerfile.alpine-musl`, the runtime stage, or `src/server.c`.
+7. [`README.md`](../README.md) links to [`documents/DOCKER.md`](../documents/DOCKER.md) from a "Run in Docker" quickstart section, and [`documents/SECURITY.md`](../documents/SECURITY.md) carries the Docker-specific subsection from todo 12.
+8. The native binary distribution and `make static` flow produce identical artifacts to before this plan landed. No regression.

plans/embedded_nsigner_spawn.md

@@ -0,0 +1,253 @@
+# Plan (future): Host programs that embed and spawn `n_signer`
+
+Status: design only. Do not implement until [`plans/mnemonic_startup_input.md`](mnemonic_startup_input.md) has landed and been used in at least one host program.
+
+This plan describes how a host program (for example `~/lt/nostr_terminal`, future Bitcoin or SSH frontends) can embed the `nsigner` binary into itself and launch it in a new visible terminal window with the mnemonic pre-loaded and pre-approvals declared, without any new on-disk artifact for `nsigner`.
+
+## 1. Why embed at all
+
+Goals motivating this plan:
+
+1. **Single-binary deployment.** A user installs `nostr_terminal` and gets `nsigner` for free; no separate package manager step, no `$PATH` confusion, no version skew.
+2. **Version pinning.** The host always launches the exact `nsigner` it was tested against.
+3. **Zero filesystem footprint preserved.** Spawning `nsigner` does not put a copy of the binary anywhere persistent; it runs out of an anonymous in-kernel memory object.
+4. **Same security boundary.** `nsigner` continues to run as a separate process with its own address space, mlock'd pages, and approval prompt loop. The host does not become the signer; it merely launches it.
+5. **Reusable across host programs.** Any program in the user's `~/lt/*` ecosystem can adopt the same helper.
+
+Non-goals (explicit):
+
+- Running `nsigner` *inside* the host process. That collapses the security boundary and is rejected. See [`documents/SECURITY.md`](../documents/SECURITY.md) "One process. One terminal. One human."
+- Hiding the `nsigner` window. The TUI is the trust anchor; it must be visible and attended.
+- Making `nsigner` a daemon. Same reason.
+
+## 2. Architecture overview
+
+```text
++----------------------------------------------------------------+
+| host program (e.g. nostr_terminal)                             |
+|                                                                |
+|  +-- embedded blob ---------------------------------+          |
+|  |   _binary_nsigner_start ... _binary_nsigner_end  |          |
+|  |   (the full statically-linked nsigner ELF)       |          |
+|  +--------------------------------------------------+          |
+|                                                                |
+|  user types mnemonic into host's TUI                           |
+|     |                                                          |
+|     v                                                          |
+|  nsigner_spawn_embedded(...)                                   |
+|     |                                                          |
+|     | 1. memfd_create(MFD_CLOEXEC)                             |
+|     | 2. write(memfd, blob, blob_len)                          |
+|     | 3. pipe2(stdin_pipe, O_CLOEXEC)                          |
+|     | 4. fork() terminal emulator wrapper                      |
+|     |        child: dup2 stdin_pipe[0] -> 0                    |
+|     |               execvp("kitty","-e","/proc/self/fd/<memfd>"|
+|     |                       --listen unix --name <chosen>      |
+|     |                       --mnemonic-stdin                   |
+|     |                       --preapprove ...)                  |
+|     | 5. parent: write(stdin_pipe[1], mnemonic); close + wipe  |
+|     | 6. return chosen socket name to caller                   |
++----------------------------------------------------------------+
+                                |
+                                v   (new graphical terminal window)
++----------------------------------------------------------------+
+| nsigner (separate process)                                     |
+|   - reads mnemonic from FD 0, closes FD 0                      |
+|   - binds @nsigner_<chosen> abstract unix socket               |
+|   - shows status TUI                                           |
+|   - applies pre-approvals from --preapprove                    |
++----------------------------------------------------------------+
+                                ^
+                                |  (host can now connect)
++----------------------------------------------------------------+
+| host re-uses client/nsigner_client.{c,h} to issue requests     |
++----------------------------------------------------------------+
+```
+
+## 3. Build-time integration
+
+### 3.1 Producing the blob
+
+Add a Makefile rule (in `n_signer`'s Makefile) that exposes the binary as a relocatable object usable by other projects:
+
+```make
+nsigner_blob.o: nsigner
+	$(LD) -r -b binary -o $@ $<
+	# results in symbols:
+	#   _binary_nsigner_start
+	#   _binary_nsigner_end
+	#   _binary_nsigner_size
+```
+
+Alternatives considered:
+
+- `xxd -i nsigner > nsigner_blob.h` — produces a C header with a `unsigned char` array. Works, but adds compile time linear in blob size and blocks ccache usefulness.
+- `objcopy -I binary -O elf64-x86-64 -B i386 nsigner nsigner_blob.o` — same effect as `ld -r -b binary` on most toolchains. Either is fine.
+
+### 3.2 Embedding into the host
+
+The host program adds these lines to its build:
+
+```make
+HOST_OBJS += nsigner_blob.o nsigner_spawn.o
+```
+
+and links them into its final executable. The blob lives in `.data` (read-only on most toolchains) and adds roughly the size of the `nsigner` binary to the host (currently ~1–3 MB for the musl static build).
+
+### 3.3 Symbol declaration
+
+```c
+extern const unsigned char _binary_nsigner_start[];
+extern const unsigned char _binary_nsigner_end[];
+/* size = _binary_nsigner_end - _binary_nsigner_start */
+```
+
+## 4. Runtime spawn helper API
+
+New file pair: `client/nsigner_spawn.h` and `client/nsigner_spawn.c`.
+
+### 4.1 Public API sketch
+
+```c
+typedef struct {
+    /* required */
+    const char *mnemonic;        /* will be written to child stdin pipe and then wiped */
+    size_t      mnemonic_len;
+
+    /* optional */
+    const char *const *preapprove_specs;  /* array of "caller=...,nostr_index=N" strings */
+    size_t             preapprove_count;
+
+    const char *socket_name;     /* if NULL, helper picks a random BIP-39 pair */
+    const char *terminal_hint;   /* "kitty"|"foot"|"alacritty"|"xterm"|... or NULL = autodetect */
+
+    /* outputs */
+    char  *out_socket_name;      /* caller-supplied buffer */
+    size_t out_socket_name_size;
+
+    pid_t *out_terminal_pid;     /* may be NULL */
+} nsigner_spawn_opts_t;
+
+/* Returns 0 on success, negative on error. On success, the embedded nsigner
+ * binary has been written to a memfd, the terminal window has been launched,
+ * the mnemonic has been written into the child's stdin pipe, and the local
+ * `mnemonic` buffer has been zeroized.
+ *
+ * After return, the host can connect to the socket using
+ *   client/nsigner_client.{c,h}
+ * with the chosen socket name in opts->out_socket_name.
+ */
+int nsigner_spawn_embedded(nsigner_spawn_opts_t *opts);
+```
+
+Optional readiness primitive (post-MVP): a `nsigner_spawn_wait_ready()` call that polls the abstract socket until it accepts a connection or until a timeout, so the host doesn't race the child's bind step.
+
+### 4.2 Internal pipeline
+
+1. Validate inputs: non-empty mnemonic, sane buffer sizes, `out_socket_name` non-NULL.
+2. Pick a socket name: random BIP-39 word pair if not provided. Reuses the same name-generation routine that `nsigner` itself uses; consider extracting it into a shared header `src/socket_name.h` already exists ([`src/socket_name.c`](../src/socket_name.c:1)) and exposing the generator publicly.
+3. Create memfd: `memfd_create("nsigner", MFD_CLOEXEC)`. On older kernels (no `memfd_create`), return an error rather than falling back to disk — the whole point is no filesystem footprint. (Linux 3.17+ has memfd; the project's deployment targets all qualify.)
+4. Write the embedded blob to the memfd. `lseek` back to zero is unnecessary because `fexecve`/`execveat` does not care about offset.
+5. Create stdin pipe: `pipe2(stdin_pipe, O_CLOEXEC)`. Mark only the read end as inheritable in the child (clear `FD_CLOEXEC` on the read end after `fork`).
+6. Pick a terminal emulator. Detection order: `$NSIGNER_TERMINAL` env override, then `terminal_hint`, then a built-in priority list:
+
+   | Emulator | Run-this flag | Notes |
+   |---|---|---|
+   | `kitty` | `--detach -- <argv>` | preserves stdin |
+   | `foot` | `-- <argv>` | preserves stdin |
+   | `alacritty` | `-e <argv>` | preserves stdin |
+   | `wezterm` | `start -- <argv>` | preserves stdin |
+   | `xterm` | `-e <argv>` | preserves stdin (legacy reliable) |
+   | `gnome-terminal` | **avoided** | dbus-launches, drops stdin/FDs |
+   | `konsole` | `-e <argv>` | mostly preserves stdin |
+
+   If none found, return an error and let the host print a hint to install one.
+7. Build child argv:
+   - `[0] = chosen_terminal`
+   - `[1..]` = the terminal's "exec" flag(s) and separator
+   - then `[N+0] = "/proc/self/fd/<memfd>"` (path the kernel exposes for the memfd, valid only inside the child's process tree — no on-disk file is created)
+   - then `--listen unix --name <chosen> --mnemonic-stdin`
+   - then each `--preapprove <spec>` pair
+8. `fork()`. In the child:
+   - `dup2(stdin_pipe[0], 0)` (replace stdin with the read end)
+   - `close(stdin_pipe[1])`
+   - clear `FD_CLOEXEC` on the memfd so `/proc/self/fd/<memfd>` resolves after `execvp` runs the terminal — the terminal then runs `nsigner` via the inherited memfd path
+   - `execvp(chosen_terminal, child_argv)`
+9. In the parent:
+   - `close(stdin_pipe[0])`
+   - `write(stdin_pipe[1], mnemonic, mnemonic_len)`
+   - `write(stdin_pipe[1], "\n", 1)`
+   - `close(stdin_pipe[1])`
+   - `secure_memzero` over the host's mnemonic buffer
+   - close the memfd in the parent (the child kernel reference keeps it alive)
+   - copy the chosen socket name into `out_socket_name`
+   - return 0
+
+### 4.3 Failure modes and cleanup
+
+Every failure path must:
+
+- close any FDs already opened (memfd, both pipe ends)
+- zeroize the mnemonic buffer if it was already copied locally
+- not leave a child process behind: if `fork` succeeded but a later step failed, `waitpid` the child after `kill(SIGTERM)`
+
+A short error-string accessor (`const char *nsigner_spawn_strerror(int)`) keeps callers from needing to know the internal codes.
+
+## 5. Security review (to perform before implementation)
+
+These items are flagged now so the implementation phase doesn't drift:
+
+1. **Confirm memfd contents are not exposed to other processes.** `/proc/self/fd/<memfd>` is per-process; another process cannot dereference another's `/proc/self/fd/N`. Document that fact in the code comments and in [`documents/SECURITY.md`](../documents/SECURITY.md).
+2. **Confirm `MFD_CLOEXEC` actually closes on the *outer* exec.** We need the memfd open across `fork`+`execvp(terminal)` but want it gone from the terminal emulator's children that aren't `nsigner`. Tested behavior: clear `FD_CLOEXEC` only on this one FD before `execvp` so the terminal inherits it; the terminal itself doesn't close arbitrary FDs in its child by default but a few do. Document the matrix.
+3. **Sealing.** Optionally `fcntl(memfd, F_ADD_SEALS, F_SEAL_WRITE | F_SEAL_SHRINK | F_SEAL_GROW)` before exec, so even a compromised child cannot rewrite the binary it is about to execute.
+4. **Pre-approval defaults.** The helper must NOT silently inject a default `--preapprove` for the host's uid. The host must declare every approval explicitly. This keeps the `documents/SECURITY.md` "deny by default" guarantee intact.
+5. **Mnemonic in pipe buffer.** The kernel pipe buffer (4 KiB) holds the mnemonic for the moment between parent's `write` and child's `read`. This is in-kernel anonymous memory, comparable to a `mlock`'d page in lifetime, and is freed when both ends close. Acceptable.
+6. **Mnemonic in environment of the host.** The helper does not put the mnemonic in `envp`. It only goes through the pipe.
+7. **Host trust elevation.** When the host calls this helper, the host program joins the trust chain (it already had the mnemonic). Document that in [`documents/SECURITY.md`](../documents/SECURITY.md) §2.3 trust-anchors table.
+8. **Terminal emulator trust.** The chosen terminal emulator is now part of the trust chain (it sees stdin and could capture it). Document; recommend `kitty`/`foot`/`alacritty`/`xterm` and warn against modifying via plugins/config that record stdin.
+
+## 6. Documentation deliverables
+
+- `documents/SPAWN.md`: how host programs embed `nsigner_blob.o` and use `nsigner_spawn.{c,h}`.
+- Update [`documents/SECURITY.md`](../documents/SECURITY.md) §2.3 with the host-program and terminal-emulator trust-chain rows.
+- Update [`README.md`](../README.md) §3.1 with a one-paragraph "Running embedded inside a host program" note pointing here.
+- New worked example `examples/spawn_and_sign.c`: takes a mnemonic from its own argv (for the example only — clearly labeled "EXAMPLE: argv mnemonic, not for production"), spawns `nsigner` via the helper, then issues `get_public_key` over the resulting socket and prints the result. This demonstrates the full pattern in ~80 lines.
+
+## 7. Testing strategy
+
+Tests are inherently more involved because they require spawning a real terminal emulator. Recommended approach:
+
+1. **Unit tests for the helper** (`tests/test_spawn_unit.c`):
+   - argv builder produces the expected list given a fixture options struct.
+   - terminal autodetect returns the correct emulator given a fake `$PATH`.
+   - the memfd write produces a payload whose first 4 bytes are `\x7fELF` (sanity).
+2. **Integration test under a headless terminal** (`tests/test_spawn_integration.c`):
+   - use `xvfb-run` plus `xterm -e` (or `foot --headless`-ish modes if available) so CI can spawn a window without a display server.
+   - the test passes a known mnemonic, waits for the abstract socket to appear, calls `get_public_key`, asserts the returned pubkey matches the BIP-39 vector for that mnemonic.
+   - this test is gated on a build flag because not every CI environment has a usable headless emulator; `make test-spawn` rather than the default `make test`.
+3. **Manual smoke checklist** in `documents/SPAWN.md` covering the four supported emulators.
+
+## 8. Open questions to resolve before implementation
+
+- Should the helper live in `client/` (next to `nsigner_client.{c,h}`) or in a new top-level `embed/` directory? Recommendation: `client/` keeps related host-side code together.
+- Should the embedded blob be compressed (e.g. zstd-decompress on the fly into the memfd)? Probably not for the first version — extra dependency, marginal size benefit on already-small statically-linked `nsigner`.
+- How does this interact with code signing on platforms that enforce it (Windows, macOS, signed Linux distros)? Linux generally allows `fexecve` of memfd content; macOS would require a different path. The plan is Linux-only for now; document that.
+- Should `nsigner` itself learn a `--print-socket-name-on-startup` flag (one line to a designated FD) so the spawn helper doesn't have to choose the name? Useful future addition; keep it as a follow-up after the memfd path proves out.
+
+## 9. Acceptance criteria (when the time comes to implement)
+
+- [ ] `make nsigner_blob.o` produces a relocatable object usable by host projects.
+- [ ] `client/nsigner_spawn.{c,h}` compiles cleanly and links into a host program with no extra dependencies.
+- [ ] `examples/spawn_and_sign.c` runs end-to-end and prints a valid pubkey.
+- [ ] No file is created on disk during a successful spawn (verified by `lsof` snapshot or `inotifywait` on `/tmp`, `/run/user/$UID`, `$HOME`).
+- [ ] Host's mnemonic buffer is wiped on the path to `execvp`.
+- [ ] Pre-approvals declared by the host appear in the spawned `nsigner`'s policy table without prompting.
+- [ ] Documentation updates landed in `documents/SPAWN.md`, [`documents/SECURITY.md`](../documents/SECURITY.md), and [`README.md`](../README.md).
+- [ ] Tests in `tests/test_spawn_unit.c` pass on plain CI; `tests/test_spawn_integration.c` passes under `xvfb-run` on the spawn-CI lane.
+
+## 10. Relationship to other plans
+
+- Builds on [`plans/mnemonic_startup_input.md`](mnemonic_startup_input.md) — the embedded helper consumes `--mnemonic-stdin`.
+- Compatible with [`plans/deny_by_default_approvals.md`](deny_by_default_approvals.md) — every host-issued approval still goes through `--preapprove`.
+- Compatible with [`plans/caller_token_identity.md`](caller_token_identity.md) — host identity is conveyed via `unix_peer` over the abstract socket like any other client.
+- Companion to [`plans/auth_envelope_other_transports.md`](auth_envelope_other_transports.md): a host that spawns `nsigner` may also wish to forward authenticated requests on its behalf; out of scope here.

plans/mnemonic_startup_input.md

@@ -0,0 +1,195 @@
+# Plan: Non-interactive mnemonic input at startup (`--mnemonic-stdin`, `--mnemonic-fd`)
+
+Status: ready to implement.
+Related: [`documents/SECURITY.md`](../documents/SECURITY.md), [`src/main.c`](../src/main.c:1006), [`src/mnemonic.c`](../src/mnemonic.c:1).
+Companion plan (future work): [`plans/embedded_nsigner_spawn.md`](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`](../src/main.c:1187))
+
+| 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`](../src/main.c:615) 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()`](../src/main.c:1006) is renamed/refactored to `load_mnemonic(mnemonic_state_t*, mnemonic_source_t)` where:
+
+```c
+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()`](../src/mnemonic.c:1) 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()`](../src/main.c:1527) 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`](../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`](../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`](../tests/test_mnemonic.c) (mnemonic library unit tests — unchanged surface)
+- [`tests/test_integration.c`](../tests/test_integration.c) (default TUI-prompt path)
+- [`tests/test.sh`](../tests/test.sh) wrapper.
+
+Add a row to `Makefile` `test` target for the new test binary.
+
+## 7. Documentation updates
+
+- [`README.md`](../README.md) §3.1: add a paragraph at the end noting the two new flags and pointing to this plan.
+- [`documents/SECURITY.md`](../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`](../documents/CLIENT_IMPLEMENTATION.md): no changes (client wire protocol unaffected).
+- New section in [`README.md`](../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`](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`](../README.md) and [`documents/SECURITY.md`](../documents/SECURITY.md) are updated.

plans/tui_continuous_integration.md

@@ -0,0 +1,101 @@
+# tui_continuous integration plan for n_signer
+
+## Goal
+
+Adopt the `tui_continuous` style from `/home/user/lt/aesthetics` with minimal-risk restructuring:
+
+- keep caller-owned poll loop and line-input model
+- avoid ncurses/event-loop inversion
+- preserve non-interactive behavior and test compatibility
+
+## Scope
+
+### 1) Vendor and wire library
+
+- Vendor `tui_continuous.c/.h` into this repository under a stable path (planned: `resources/tui_continuous/`).
+- Add include path and source wiring to:
+  - `Makefile` dev build
+  - targets that link `src/main.c` (notably integration path)
+  - static build flow (`build_static.sh`, Alpine musl path)
+
+### 2) Main-screen TUI adapter in `src/main.c`
+
+- Introduce a small adapter layer that owns:
+  - persistent `TuiFrame` (`app_name=nsigner`, `app_version=NSIGNER_VERSION`, breadcrumb)
+  - hotkey menu definitions matching existing behavior (`q/x`, `l`, `r`, `A`)
+  - status text composition (`locked/unlocked`, words, socket, derived, auto-approve)
+
+### 3) Replace legacy `render_status()` with `tui_continuous`
+
+- Use `tui_render_screen()` for top framing/menu/status strip.
+- Render roles with `tui_render_table()` using columns:
+  - role name
+  - purpose
+  - curve
+  - selector
+- Render activity log (latest first) via `tui_print()`.
+- Keep prompt anchoring stable with `tui_anchor_prompt()`.
+
+### 4) Resize behavior
+
+- Install SIGWINCH handler with `tui_install_resize_handler()` before unix interactive loop.
+- On each poll tick, if `tui_resize_pending()` is set, repaint current view.
+
+### 5) Approval flow refactor (`src/server.c` + `src/main.c`)
+
+- Add server approval callback API in `server.c`:
+  - callback typedef
+  - registration function (`server_set_approval_cb(...)`)
+  - compact request payload struct (caller/method/role/purpose/derivation + optional peer display)
+- Keep default callback behavior equivalent to existing stdio prompt output for non-TUI and tests.
+- In `main.c` unix interactive mode, register a TUI-aware callback that:
+  - paints an approval content screen
+  - shows `[y]/[n]/[e]/[a]` options
+  - reads line input (fgets-compatible behavior)
+  - returns policy decision enums
+  - repaints main status screen after decision
+
+### 6) Mnemonic prompt styling
+
+- Keep `fgets` input path intact for paste reliability.
+- Re-style startup and lock/reunlock prompts using `tui_render_content_screen()` + `tui_print()`.
+
+### 7) Output safety boundaries
+
+- Keep machine-readable output untouched (client JSON-RPC responses remain raw).
+- Restrict style updates for non-interactive surfaces to human-facing usage/banner text only.
+
+### 8) Validation
+
+- Run/build validation for:
+  - normal dev build
+  - static build flow
+  - existing prompt-related test paths (`NSIGNER_TEST_FORCE_PROMPT`, `NSIGNER_TEST_NONINTERACTIVE_PROMPT`)
+- Manual visual checks:
+  - narrow/normal/wide terminal widths
+  - live resize behavior
+  - approval prompt arriving during idle and proper redraw afterwards
+
+### 9) Documentation updates
+
+- Update `README.md` and security docs where relevant to mention:
+  - adopted TUI style source (`aesthetics/TUI.md`)
+  - vendored `tui_continuous` component/version
+
+## Execution order
+
+1. Vendor library and wire build
+2. Implement main screen adapter + rendering
+3. Add resize repaint
+4. Refactor approval callback plumbing
+5. Add TUI approval view in main
+6. Re-style mnemonic prompts
+7. Validate tests/builds + manual UX checks
+8. Update docs
+
+## Non-goals
+
+- No ncurses integration
+- No event loop ownership changes
+- No changes to transport semantics (`unix`, `stdio`, `qrexec`, `tcp`)
+- No machine-readable output format changes

run.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BUILD_SCRIPT="$SCRIPT_DIR/build_static.sh"
+BUILD_DIR="$SCRIPT_DIR/build"
+
+HOST_UNAME="$(uname -m)"
+case "$HOST_UNAME" in
+    x86_64)
+        OUTPUT_NAME="nsigner_static_x86_64"
+        ;;
+    aarch64|arm64)
+        OUTPUT_NAME="nsigner_static_arm64"
+        ;;
+    armv7l|armv7)
+        OUTPUT_NAME="nsigner_static_armv7"
+        ;;
+    *)
+        echo "ERROR: Unsupported host architecture '$HOST_UNAME'"
+        exit 1
+        ;;
+esac
+
+"$BUILD_SCRIPT"
+
+BINARY_PATH="$BUILD_DIR/$OUTPUT_NAME"
+if [[ ! -x "$BINARY_PATH" ]]; then
+    echo "ERROR: Compiled binary not found or not executable: $BINARY_PATH"
+    exit 1
+fi
+
+exec "$BINARY_PATH" "$@"

src/auth_envelope.c

@@ -87,36 +87,40 @@ static int json_item_to_compact_string(const cJSON *item, char *out, size_t out_
     return 0;
 }
 
-static int compute_params_hash_hex(cJSON *root, char *out_hex, size_t out_hex_sz) {
-    cJSON *params = cJSON_GetObjectItemCaseSensitive(root, "params");
+static int compute_hash_hex_for_json_item(const cJSON *item, char *out_hex, size_t out_hex_sz) {
     unsigned char hash[32];
-    char *params_compact = NULL;
+    char *compact = NULL;
 
     if (out_hex == NULL || out_hex_sz < 65) {
         return -1;
     }
 
-    if (params == NULL) {
-        params_compact = strdup("null");
+    if (item == NULL) {
+        compact = strdup("null");
     } else {
-        params_compact = cJSON_PrintUnformatted(params);
+        compact = cJSON_PrintUnformatted((cJSON *)item);
     }
 
-    if (params_compact == NULL) {
+    if (compact == NULL) {
         return -1;
     }
 
-    if (nostr_sha256((const unsigned char *)params_compact, strlen(params_compact), hash) != 0) {
-        free(params_compact);
+    if (nostr_sha256((const unsigned char *)compact, strlen(compact), hash) != 0) {
+        free(compact);
         return -1;
     }
 
     nostr_bytes_to_hex(hash, sizeof(hash), out_hex);
     out_hex[64] = '\0';
-    free(params_compact);
+    free(compact);
     return 0;
 }
 
+static int compute_params_hash_hex(cJSON *root, char *out_hex, size_t out_hex_sz) {
+    cJSON *params = cJSON_GetObjectItemCaseSensitive(root, "params");
+    return compute_hash_hex_for_json_item(params, out_hex, out_hex_sz);
+}
+
 static cJSON *find_tag_value(cJSON *tags, const char *name) {
     int i;
 
@@ -148,6 +152,73 @@ static cJSON *find_tag_value(cJSON *tags, const char *name) {
     return NULL;
 }
 
+static cJSON *build_tag_pair(const char *name, const char *value) {
+    cJSON *pair;
+
+    if (name == NULL || value == NULL) {
+        return NULL;
+    }
+
+    pair = cJSON_CreateArray();
+    if (pair == NULL) {
+        return NULL;
+    }
+
+    cJSON_AddItemToArray(pair, cJSON_CreateString(name));
+    cJSON_AddItemToArray(pair, cJSON_CreateString(value));
+    return pair;
+}
+
+int auth_envelope_build_for_request(const char *request_id,
+                                    const char *method,
+                                    const cJSON *params,
+                                    const unsigned char privkey[32],
+                                    const char *label,
+                                    time_t created_at,
+                                    cJSON **out_auth) {
+    cJSON *tags = NULL;
+    cJSON *auth = NULL;
+    char body_hash_hex[65];
+
+    if (out_auth == NULL || request_id == NULL || method == NULL ||
+        privkey == NULL || request_id[0] == '\0' || method[0] == '\0') {
+        return -1;
+    }
+
+    *out_auth = NULL;
+
+    if (compute_hash_hex_for_json_item(params, body_hash_hex, sizeof(body_hash_hex)) != 0) {
+        return -1;
+    }
+
+    tags = cJSON_CreateArray();
+    if (tags == NULL) {
+        return -1;
+    }
+
+    cJSON_AddItemToArray(tags, build_tag_pair("nsigner_rpc", request_id));
+    cJSON_AddItemToArray(tags, build_tag_pair("nsigner_method", method));
+    cJSON_AddItemToArray(tags, build_tag_pair("nsigner_body_hash", body_hash_hex));
+
+    if (created_at <= 0) {
+        created_at = time(NULL);
+    }
+
+    auth = nostr_create_and_sign_event(AUTH_EVENT_KIND,
+                                       (label != NULL) ? label : "",
+                                       tags,
+                                       privkey,
+                                       created_at);
+
+    if (auth == NULL) {
+        cJSON_Delete(tags);
+        return -1;
+    }
+
+    *out_auth = auth;
+    return 0;
+}
+
 int auth_envelope_verify_request(const char *request_json,
                                  auth_nonce_cache_t *cache,
                                  int skew_seconds,

src/auth_envelope.h

@@ -3,6 +3,9 @@
 
 #include <stddef.h>
 #include <stdint.h>
+#include <time.h>
+
+#include <cJSON.h>
 
 #define AUTH_NONCE_CACHE_SIZE 1024
 #define AUTH_DEFAULT_SKEW_SECONDS 30
@@ -35,4 +38,12 @@ int auth_envelope_verify_request(const char *request_json,
                                  int *out_error_code,
                                  const char **out_error_message);
 
+int auth_envelope_build_for_request(const char *request_id,
+                                    const char *method,
+                                    const cJSON *params,
+                                    const unsigned char privkey[32],
+                                    const char *label,
+                                    time_t created_at,
+                                    cJSON **out_auth);
+
 #endif

src/dispatcher.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -396,7 +396,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/enforcement.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/key_store.c

@@ -231,7 +231,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -389,7 +389,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/mnemonic.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/policy.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/role_table.c

@@ -232,7 +232,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -387,7 +387,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/secure_mem.c

@@ -231,7 +231,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -386,7 +386,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/selector.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

src/server.c

@@ -234,7 +234,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -397,13 +397,17 @@ char *dispatcher_handle_request(dispatcher_ctx_t *ctx, const char *json_request)
 #define NSIGNER_LISTEN_QREXEC 2
 #define NSIGNER_LISTEN_TCP    3
 
+#define NSIGNER_AUTH_OFF      0
+#define NSIGNER_AUTH_OPTIONAL 1
+#define NSIGNER_AUTH_REQUIRED 2
+
 /* Caller identity */
 typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
     int kind;
-    char caller_id[80];     /* "uid:<n>", "qubes:<vm>", or "pubkey:<hex>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];     /* "uid:<n>", "qubes:<vm>", or "pubkey:<hex>" */
     char source_qube[64];
     int auth_present;
     char auth_pubkey_hex[65];
@@ -421,12 +425,16 @@ typedef struct {
     dispatcher_ctx_t *dispatcher;
     policy_table_t *policy;
     int socket_name_explicit;
+    int auth_mode;
+    int auth_skew_seconds;
 } server_ctx_t;
 
 /* Initialize server context. socket_name is the abstract namespace name (e.g. "nsigner").
  * socket_name_explicit should be non-zero when provided via --socket-name override. */
 void server_init(server_ctx_t *ctx, const char *socket_name, int socket_name_explicit,
                  int listen_mode,
+                 int auth_mode,
+                 int auth_skew_seconds,
                  dispatcher_ctx_t *dispatcher, policy_table_t *policy);
 
 /* Start listening. Returns 0 on success, -1 on error. */
@@ -446,6 +454,19 @@ void server_stop(server_ctx_t *ctx);
 /* Extract caller identity from connected fd */
 int server_get_caller(int fd, caller_identity_t *out);
 
+typedef struct {
+    const caller_identity_t *caller;
+    const char *method;
+    const char *role_name;
+    const char *purpose;
+    int pending_derivation;
+    const char *fips_peer_npub;
+    const char *fips_peer_name;
+} server_approval_request_t;
+
+typedef int (*server_approval_cb)(const server_approval_request_t *req, void *user_data);
+void server_set_approval_cb(server_approval_cb cb, void *user_data);
+
 
 /* from socket_name.h */
 
@@ -494,6 +515,8 @@ static int g_prompt_always_allow = 0;
 static int g_noninteractive_prompt_default = -1;
 static auth_nonce_cache_t g_auth_nonce_cache;
 static int g_auth_nonce_cache_inited = 0;
+static server_approval_cb g_approval_cb = NULL;
+static void *g_approval_cb_user_data = NULL;
 
 static int caller_id_extract_ipv6(const char *caller_id, char *out_ipv6, size_t out_sz) {
     const char *start;
@@ -658,6 +681,11 @@ void server_set_noninteractive_prompt_default(int decision) {
     }
 }
 
+void server_set_approval_cb(server_approval_cb cb, void *user_data) {
+    g_approval_cb = cb;
+    g_approval_cb_user_data = user_data;
+}
+
 static int prompt_for_policy_decision(const caller_identity_t *caller,
                                       const char *method,
                                       const char *role_name,
@@ -677,6 +705,32 @@ static int prompt_for_policy_decision(const caller_identity_t *caller,
         return POLICY_DENY;
     }
 
+    if (g_approval_cb != NULL) {
+        server_approval_request_t req;
+        char ipv6[INET6_ADDRSTRLEN];
+        char npub[128];
+        char display_name[128];
+
+        req.caller = caller;
+        req.method = method;
+        req.role_name = role_name;
+        req.purpose = purpose;
+        req.pending_derivation = pending_derivation;
+        req.fips_peer_npub = NULL;
+        req.fips_peer_name = NULL;
+
+        npub[0] = '\0';
+        display_name[0] = '\0';
+        if (caller != NULL && caller->kind == NSIGNER_LISTEN_TCP &&
+            caller_id_extract_ipv6(caller->caller_id, ipv6, sizeof(ipv6)) == 0 &&
+            lookup_fips_peer_for_ipv6(ipv6, npub, sizeof(npub), display_name, sizeof(display_name)) == 0) {
+            req.fips_peer_npub = (npub[0] != '\0') ? npub : NULL;
+            req.fips_peer_name = (display_name[0] != '\0') ? display_name : NULL;
+        }
+
+        return g_approval_cb(&req, g_approval_cb_user_data);
+    }
+
     printf("\nApproval required\n");
     printf("caller: %s\n", (caller != NULL) ? caller->caller_id : "unknown");
     if (caller != NULL && caller->kind == NSIGNER_LISTEN_TCP) {
@@ -684,6 +738,9 @@ static int prompt_for_policy_decision(const caller_identity_t *caller,
         char npub[128];
         char display_name[128];
 
+        npub[0] = '\0';
+        display_name[0] = '\0';
+
         if (caller_id_extract_ipv6(caller->caller_id, ipv6, sizeof(ipv6)) == 0 &&
             lookup_fips_peer_for_ipv6(ipv6, npub, sizeof(npub), display_name, sizeof(display_name)) == 0) {
             if (display_name[0] != '\0') {
@@ -693,6 +750,7 @@ static int prompt_for_policy_decision(const caller_identity_t *caller,
             }
         }
     }
+
     printf("method: %s\n", (method != NULL) ? method : "unknown");
     printf("role: %s\n", (role_name != NULL) ? role_name : "unknown");
     printf("purpose: %s\n", (purpose != NULL) ? purpose : "unknown");
@@ -871,6 +929,43 @@ static int extract_request_id_compact(const char *json, char *out_id, size_t out
     return -1;
 }
 
+static int request_has_auth_field(const char *json) {
+    cJSON *root;
+    cJSON *auth;
+    int has_auth;
+
+    if (json == NULL) {
+        return 0;
+    }
+
+    root = cJSON_Parse(json);
+    if (root == NULL) {
+        return 0;
+    }
+
+    auth = cJSON_GetObjectItemCaseSensitive(root, "auth");
+    has_auth = (auth != NULL) ? 1 : 0;
+    cJSON_Delete(root);
+    return has_auth;
+}
+
+static void caller_id_compose_with_pubkey(char *out,
+                                          size_t out_sz,
+                                          int caller_kind,
+                                          const char *source_qube,
+                                          const char *pubkey_hex) {
+    if (out == NULL || out_sz == 0 || pubkey_hex == NULL) {
+        return;
+    }
+
+    if (caller_kind == NSIGNER_LISTEN_QREXEC && source_qube != NULL && source_qube[0] != '\0') {
+        (void)snprintf(out, out_sz, "qubes:%s+pubkey:%s", source_qube, pubkey_hex);
+        return;
+    }
+
+    (void)snprintf(out, out_sz, "pubkey:%s", pubkey_hex);
+}
+
 static int extract_method_and_selector(const char *json,
                                        char *method,
                                        size_t method_sz,
@@ -934,6 +1029,8 @@ static int extract_method_and_selector(const char *json,
 
 void server_init(server_ctx_t *ctx, const char *socket_name, int socket_name_explicit,
                  int listen_mode,
+                 int auth_mode,
+                 int auth_skew_seconds,
                  dispatcher_ctx_t *dispatcher, policy_table_t *policy) {
     if (ctx == NULL) {
         return;
@@ -951,6 +1048,8 @@ void server_init(server_ctx_t *ctx, const char *socket_name, int socket_name_exp
     ctx->dispatcher = dispatcher;
     ctx->policy = policy;
     ctx->socket_name_explicit = socket_name_explicit ? 1 : 0;
+    ctx->auth_mode = auth_mode;
+    ctx->auth_skew_seconds = (auth_skew_seconds > 0) ? auth_skew_seconds : AUTH_DEFAULT_SKEW_SECONDS;
     if (!g_auth_nonce_cache_inited) {
         auth_nonce_cache_init(&g_auth_nonce_cache);
         g_auth_nonce_cache_inited = 1;
@@ -1310,51 +1409,72 @@ int server_handle_one(server_ctx_t *ctx, server_activity_cb cb, void *cb_data) {
     auth_pubkey[0] = '\0';
     auth_label[0] = '\0';
 
-    if (caller.kind == NSIGNER_LISTEN_TCP) {
-        if (auth_envelope_verify_request(request,
-                                         &g_auth_nonce_cache,
-                                         AUTH_DEFAULT_SKEW_SECONDS,
-                                         auth_pubkey,
-                                         sizeof(auth_pubkey),
-                                         auth_label,
-                                         sizeof(auth_label),
-                                         &auth_err_code,
-                                         &auth_err_msg) != 0) {
-            (void)extract_request_id_compact(request, request_id, sizeof(request_id));
-            if (auth_err_msg == NULL) {
-                auth_err_msg = "auth_envelope_malformed";
+    {
+        int auth_required = 0;
+        int auth_optional = 0;
+        int has_auth_field = 0;
+
+        if (caller.kind == NSIGNER_LISTEN_TCP) {
+            auth_required = 1;
+        } else if (caller.kind == NSIGNER_LISTEN_QREXEC) {
+            if (ctx->auth_mode == NSIGNER_AUTH_REQUIRED) {
+                auth_required = 1;
+            } else if (ctx->auth_mode == NSIGNER_AUTH_OPTIONAL) {
+                auth_optional = 1;
             }
-            {
-                char errbuf[256];
-                (void)snprintf(errbuf,
-                               sizeof(errbuf),
-                               "{\"id\":\"%s\",\"error\":{\"code\":%d,\"message\":\"%s\"}}",
-                               request_id,
-                               (auth_err_code != 0) ? auth_err_code : AUTH_ERR_ENVELOPE_MALFORMED,
-                               auth_err_msg);
-                response = strdup(errbuf);
-            }
-            if (response != NULL) {
-                (void)transport_send_framed((client_fd == STDIN_FILENO) ? STDOUT_FILENO : client_fd, response);
-                free(response);
-            }
-            free(request);
-            if (client_fd != STDIN_FILENO) {
-                close(client_fd);
-            }
-            return 1;
         }
 
-        caller.auth_present = 1;
-        json_copy_string(caller.auth_pubkey_hex,
-                         sizeof(caller.auth_pubkey_hex),
-                         auth_pubkey,
-                         "");
-        json_copy_string(caller.auth_label,
-                         sizeof(caller.auth_label),
-                         auth_label,
-                         "");
-        (void)snprintf(caller.caller_id, sizeof(caller.caller_id), "pubkey:%s", auth_pubkey);
+        has_auth_field = request_has_auth_field(request);
+        if (auth_required || (auth_optional && has_auth_field)) {
+            if (auth_envelope_verify_request(request,
+                                             &g_auth_nonce_cache,
+                                             ctx->auth_skew_seconds,
+                                             auth_pubkey,
+                                             sizeof(auth_pubkey),
+                                             auth_label,
+                                             sizeof(auth_label),
+                                             &auth_err_code,
+                                             &auth_err_msg) != 0) {
+                (void)extract_request_id_compact(request, request_id, sizeof(request_id));
+                if (auth_err_msg == NULL) {
+                    auth_err_msg = "auth_envelope_malformed";
+                }
+                {
+                    char errbuf[256];
+                    (void)snprintf(errbuf,
+                                   sizeof(errbuf),
+                                   "{\"id\":\"%s\",\"error\":{\"code\":%d,\"message\":\"%s\"}}",
+                                   request_id,
+                                   (auth_err_code != 0) ? auth_err_code : AUTH_ERR_ENVELOPE_MALFORMED,
+                                   auth_err_msg);
+                    response = strdup(errbuf);
+                }
+                if (response != NULL) {
+                    (void)transport_send_framed((client_fd == STDIN_FILENO) ? STDOUT_FILENO : client_fd, response);
+                    free(response);
+                }
+                free(request);
+                if (client_fd != STDIN_FILENO) {
+                    close(client_fd);
+                }
+                return 1;
+            }
+
+            caller.auth_present = 1;
+            json_copy_string(caller.auth_pubkey_hex,
+                             sizeof(caller.auth_pubkey_hex),
+                             auth_pubkey,
+                             "");
+            json_copy_string(caller.auth_label,
+                             sizeof(caller.auth_label),
+                             auth_label,
+                             "");
+            caller_id_compose_with_pubkey(caller.caller_id,
+                                          sizeof(caller.caller_id),
+                                          caller.kind,
+                                          caller.source_qube,
+                                          auth_pubkey);
+        }
     }
 
     if (extract_method_and_selector(request, method, sizeof(method), &selector_req) == 0) {

src/socket_name.c

@@ -231,7 +231,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -386,7 +386,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

tests/test.sh

@@ -172,5 +172,13 @@ else
   echo "[warn] no @nsigner entries found"
 fi
 
+echo
+echo "[extra] mnemonic startup input tests"
+if [[ -x ./build/test_mnemonic_input ]]; then
+  ./build/test_mnemonic_input || true
+else
+  echo "[warn] build/test_mnemonic_input not found (run: make test-mnemonic-input)"
+fi
+
 echo
 echo "Smoke test complete."

tests/test_dispatcher.c

@@ -232,7 +232,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -390,7 +390,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

tests/test_enforcement.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

tests/test_integration.c

@@ -231,7 +231,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -386,7 +386,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */
@@ -464,6 +464,8 @@ int socket_name_random(char *out, size_t out_len);
 #include <time.h>
 #include <unistd.h>
 
+#include "nsigner_client.h"
+
 #define SOCKET_NAME_A "nsigner_test_run_a"
 #define SOCKET_NAME_B "nsigner_test_run_b"
 #define MAX_MSG_SIZE 65536
@@ -630,6 +632,8 @@ int main(void) {
     char *resp = NULL;
     int status;
 
+    (void)signal(SIGPIPE, SIG_IGN);
+
     if (pipe(stdin_pipe) != 0) {
         perror("pipe");
         return 1;
@@ -704,42 +708,57 @@ int main(void) {
 
     sleep_ms(1000);
 
-    if (request_roundtrip_to(SOCKET_NAME_A, "{\"id\":\"1\",\"method\":\"get_public_key\",\"params\":[\"\"]}", &resp) == 0) {
-        check_condition("get_public_key response id", strstr(resp, "\"id\":\"1\"") != NULL);
-        check_condition("get_public_key has result", strstr(resp, "\"result\":") != NULL);
-    } else {
-        check_condition("get_public_key request roundtrip", 0);
-    }
-    free(resp);
-    resp = NULL;
+    {
+        nsigner_client_t client;
+        nsigner_client_init(&client);
+        if (nsigner_client_connect_unix(&client, SOCKET_NAME_A, 5000) == 0) {
+            if (nsigner_client_get_public_key(&client, "1", "", &resp) == 0) {
+                check_condition("get_public_key response id", strstr(resp, "\"id\":\"1\"") != NULL);
+                check_condition("get_public_key has result", strstr(resp, "\"result\":") != NULL);
+            } else {
+                check_condition("get_public_key request roundtrip", 0);
+            }
+            free(resp);
+            resp = NULL;
+            nsigner_client_close(&client);
+        } else {
+            check_condition("connect signer socket for client library", 0);
+        }
 
-    if (request_roundtrip_to(SOCKET_NAME_A, "{\"id\":\"2\",\"method\":\"sign_event\",\"params\":[\"{\\\"kind\\\":1,\\\"content\\\":\\\"hello\\\",\\\"tags\\\":[],\\\"created_at\\\":1700000000}\",{\"role\":\"main\"}]}", &resp) == 0) {
-        check_condition("sign_event response id", strstr(resp, "\"id\":\"2\"") != NULL);
-        check_condition("sign_event has result", strstr(resp, "\"result\":") != NULL);
-    } else {
-        check_condition("sign_event request roundtrip", 0);
+        nsigner_client_init(&client);
+        if (nsigner_client_connect_unix(&client, SOCKET_NAME_A, 5000) == 0) {
+            if (nsigner_client_sign_event(&client,
+                                          "2",
+                                          "{\"kind\":1,\"content\":\"hello\",\"tags\":[],\"created_at\":1700000000}",
+                                          "main",
+                                          &resp) == 0) {
+                check_condition("sign_event response id", strstr(resp, "\"id\":\"2\"") != NULL);
+                check_condition("sign_event has result", strstr(resp, "\"result\":") != NULL);
+            } else {
+                check_condition("sign_event request roundtrip", 0);
+            }
+            free(resp);
+            resp = NULL;
+        } else {
+            check_condition("connect signer socket for sign_event", 0);
+        }
+        nsigner_client_close(&client);
     }
-    free(resp);
 
 
     {
         char *resp_a = NULL;
-        char *resp_b = NULL;
         char pub_a[65] = {0};
-        char pub_b[65] = {0};
         char cipher[2048] = {0};
         char req[4096];
         const char *p;
 
-        if (request_roundtrip_to(SOCKET_NAME_A, "{\"id\":\"3\",\"method\":\"get_public_key\",\"params\":[\"\"]}", &resp_a) == 0 &&
-            request_roundtrip_to(SOCKET_NAME_B, "{\"id\":\"4\",\"method\":\"get_public_key\",\"params\":[\"\"]}", &resp_b) == 0) {
+        if (request_roundtrip_to(SOCKET_NAME_A, "{\"id\":\"3\",\"method\":\"get_public_key\",\"params\":[\"\"]}", &resp_a) == 0) {
             p = strstr(resp_a, "\"result\":\"");
             if (p) { p += 10; strncpy(pub_a, p, 64); pub_a[64]='\0'; }
-            p = strstr(resp_b, "\"result\":\"");
-            if (p) { p += 10; strncpy(pub_b, p, 64); pub_b[64]='\0'; }
-            check_condition("multi-instance distinct sockets respond", pub_a[0] && pub_b[0]);
+            check_condition("single-instance public key request", pub_a[0] != '\0');
 
-            snprintf(req, sizeof(req), "{\"id\":\"5\",\"method\":\"nip04_encrypt\",\"params\":[\"%s\",\"hello_nip04\"]}", pub_b);
+            snprintf(req, sizeof(req), "{\"id\":\"5\",\"method\":\"nip04_encrypt\",\"params\":[\"%s\",\"hello_nip04\"]}", pub_a);
             free(resp_a); resp_a = NULL;
             if (request_roundtrip_to(SOCKET_NAME_A, req, &resp_a) == 0) {
                 p = strstr(resp_a, "\"result\":\"");
@@ -750,9 +769,9 @@ int main(void) {
                     cipher[i]='\0';
                 }
                 snprintf(req, sizeof(req), "{\"id\":\"6\",\"method\":\"nip04_decrypt\",\"params\":[\"%s\",\"%s\"]}", pub_a, cipher);
-                free(resp_b); resp_b = NULL;
-                if (request_roundtrip_to(SOCKET_NAME_B, req, &resp_b) == 0) {
-                    check_condition("nip04 round-trip plaintext recovered", strstr(resp_b, "hello_nip04") != NULL);
+                free(resp_a); resp_a = NULL;
+                if (request_roundtrip_to(SOCKET_NAME_A, req, &resp_a) == 0) {
+                    check_condition("nip04 round-trip plaintext recovered", strstr(resp_a, "hello_nip04") != NULL);
                 } else {
                     check_condition("nip04 decrypt request roundtrip", 0);
                 }
@@ -761,7 +780,7 @@ int main(void) {
             }
 
             memset(cipher, 0, sizeof(cipher));
-            snprintf(req, sizeof(req), "{\"id\":\"7\",\"method\":\"nip44_encrypt\",\"params\":[\"%s\",\"hello_nip44\"]}", pub_b);
+            snprintf(req, sizeof(req), "{\"id\":\"7\",\"method\":\"nip44_encrypt\",\"params\":[\"%s\",\"hello_nip44\"]}", pub_a);
             free(resp_a); resp_a = NULL;
             if (request_roundtrip_to(SOCKET_NAME_A, req, &resp_a) == 0) {
                 p = strstr(resp_a, "\"result\":\"");
@@ -772,9 +791,9 @@ int main(void) {
                     cipher[i]='\0';
                 }
                 snprintf(req, sizeof(req), "{\"id\":\"8\",\"method\":\"nip44_decrypt\",\"params\":[\"%s\",\"%s\"]}", pub_a, cipher);
-                free(resp_b); resp_b = NULL;
-                if (request_roundtrip_to(SOCKET_NAME_B, req, &resp_b) == 0) {
-                    check_condition("nip44 round-trip plaintext recovered", strstr(resp_b, "hello_nip44") != NULL);
+                free(resp_a); resp_a = NULL;
+                if (request_roundtrip_to(SOCKET_NAME_A, req, &resp_a) == 0) {
+                    check_condition("nip44 round-trip plaintext recovered", strstr(resp_a, "hello_nip44") != NULL);
                 } else {
                     check_condition("nip44 decrypt request roundtrip", 0);
                 }
@@ -782,10 +801,9 @@ int main(void) {
                 check_condition("nip44 encrypt request roundtrip", 0);
             }
         } else {
-            check_condition("multi-instance public key requests", 0);
+            check_condition("single-instance public key request", 0);
         }
         free(resp_a);
-        free(resp_b);
     }
 
     if (kill(child, SIGTERM) == 0) {

tests/test_mnemonic.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

tests/test_mnemonic_input.c

@@ -0,0 +1,532 @@
+#define _GNU_SOURCE
+
+#include <arpa/inet.h>
+#include <errno.h>
+#include <signal.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/socket.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <sys/wait.h>
+#include <time.h>
+#include <unistd.h>
+
+#define VALID_MNEMONIC "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
+#define LONG_INPUT_LEN 1024
+
+static int g_failures = 0;
+
+static void check_condition(const char *name, int condition) {
+    if (condition) {
+        printf("PASS: %s\n", name);
+    } else {
+        printf("FAIL: %s\n", name);
+        g_failures++;
+    }
+}
+
+static int sleep_ms(int ms) {
+    struct timespec ts;
+    ts.tv_sec = ms / 1000;
+    ts.tv_nsec = (long)(ms % 1000) * 1000000L;
+    return nanosleep(&ts, NULL);
+}
+
+static int write_full(int fd, const void *buf, size_t len) {
+    const unsigned char *p = (const unsigned char *)buf;
+    size_t off = 0;
+
+    while (off < len) {
+        ssize_t n = write(fd, p + off, len - off);
+        if (n < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            return -1;
+        }
+        off += (size_t)n;
+    }
+
+    return 0;
+}
+
+static int connect_socket_retry(const char *name, int timeout_ms) {
+    int elapsed = 0;
+
+    while (elapsed < timeout_ms) {
+        int fd;
+        struct sockaddr_un addr;
+        socklen_t addr_len;
+
+        fd = socket(AF_UNIX, SOCK_STREAM, 0);
+        if (fd < 0) {
+            return -1;
+        }
+
+        memset(&addr, 0, sizeof(addr));
+        addr.sun_family = AF_UNIX;
+        addr.sun_path[0] = '\0';
+        strncpy(&addr.sun_path[1], name, sizeof(addr.sun_path) - 2);
+        addr.sun_path[sizeof(addr.sun_path) - 1] = '\0';
+        addr_len = (socklen_t)(sizeof(sa_family_t) + 1 + strlen(name));
+
+        if (connect(fd, (struct sockaddr *)&addr, addr_len) == 0) {
+            return fd;
+        }
+
+        close(fd);
+        sleep_ms(100);
+        elapsed += 100;
+    }
+
+    return -1;
+}
+
+static pid_t spawn_with_stdin_and_fd(const char *const argv[],
+                                     const char *stdin_data,
+                                     int close_stdin_after_write,
+                                     const char *fd_data,
+                                     int fd_num,
+                                     int close_fd_after_write,
+                                     int *stdin_write_end,
+                                     int *fd_write_end,
+                                     int *capture_read_end) {
+    int stdin_pipe[2] = {-1, -1};
+    int fd_pipe[2] = {-1, -1};
+    int capture_pipe[2] = {-1, -1};
+    pid_t child;
+
+    if (pipe(stdin_pipe) != 0) {
+        return -1;
+    }
+    if (pipe(capture_pipe) != 0) {
+        close(stdin_pipe[0]);
+        close(stdin_pipe[1]);
+        return -1;
+    }
+    if (fd_data != NULL) {
+        if (pipe(fd_pipe) != 0) {
+            close(stdin_pipe[0]);
+            close(stdin_pipe[1]);
+            close(capture_pipe[0]);
+            close(capture_pipe[1]);
+            return -1;
+        }
+    }
+
+    child = fork();
+    if (child < 0) {
+        close(stdin_pipe[0]);
+        close(stdin_pipe[1]);
+        close(capture_pipe[0]);
+        close(capture_pipe[1]);
+        if (fd_pipe[0] >= 0) close(fd_pipe[0]);
+        if (fd_pipe[1] >= 0) close(fd_pipe[1]);
+        return -1;
+    }
+
+    if (child == 0) {
+        dup2(stdin_pipe[0], STDIN_FILENO);
+        dup2(capture_pipe[1], STDOUT_FILENO);
+        dup2(capture_pipe[1], STDERR_FILENO);
+
+        close(stdin_pipe[0]);
+        close(stdin_pipe[1]);
+        close(capture_pipe[0]);
+        close(capture_pipe[1]);
+
+        if (fd_data != NULL) {
+            dup2(fd_pipe[0], fd_num);
+            close(fd_pipe[0]);
+            close(fd_pipe[1]);
+        }
+
+        execv("./build/nsigner", (char *const *)argv);
+        _exit(127);
+    }
+
+    close(stdin_pipe[0]);
+    close(capture_pipe[1]);
+
+    if (fd_data != NULL) {
+        close(fd_pipe[0]);
+    }
+
+    if (stdin_data != NULL) {
+        (void)write_full(stdin_pipe[1], stdin_data, strlen(stdin_data));
+        if (close_stdin_after_write) {
+            close(stdin_pipe[1]);
+            stdin_pipe[1] = -1;
+        }
+    }
+
+    if (fd_data != NULL) {
+        (void)write_full(fd_pipe[1], fd_data, strlen(fd_data));
+        if (close_fd_after_write) {
+            close(fd_pipe[1]);
+            fd_pipe[1] = -1;
+        }
+    }
+
+    if (stdin_write_end != NULL) {
+        *stdin_write_end = stdin_pipe[1];
+    } else if (stdin_pipe[1] >= 0) {
+        close(stdin_pipe[1]);
+    }
+
+    if (fd_write_end != NULL) {
+        *fd_write_end = fd_pipe[1];
+    } else if (fd_pipe[1] >= 0) {
+        close(fd_pipe[1]);
+    }
+
+    if (capture_read_end != NULL) {
+        *capture_read_end = capture_pipe[0];
+    } else {
+        close(capture_pipe[0]);
+    }
+
+    return child;
+}
+
+static int read_capture_nonblocking(int fd, char *buf, size_t buf_sz) {
+    ssize_t n;
+    if (buf == NULL || buf_sz == 0) {
+        return -1;
+    }
+    n = read(fd, buf, buf_sz - 1);
+    if (n < 0) {
+        if (errno == EAGAIN || errno == EWOULDBLOCK) {
+            buf[0] = '\0';
+            return 0;
+        }
+        return -1;
+    }
+    buf[n] = '\0';
+    return 0;
+}
+
+static int wait_exit_timeout(pid_t pid, int timeout_ms, int *status) {
+    int elapsed = 0;
+    while (elapsed < timeout_ms) {
+        pid_t rc = waitpid(pid, status, WNOHANG);
+        if (rc == pid) {
+            return 0;
+        }
+        if (rc < 0) {
+            return -1;
+        }
+        sleep_ms(50);
+        elapsed += 50;
+    }
+    return -1;
+}
+
+static void test_stdin_happy_path(void) {
+    const char *const argv[] = {
+        "./build/nsigner", "--socket-name", "nsigner_test_mi_stdin_ok", "--mnemonic-stdin", NULL
+    };
+    int cap_fd = -1;
+    int status = 0;
+    int fd;
+    pid_t child = spawn_with_stdin_and_fd(argv,
+                                          VALID_MNEMONIC "\n",
+                                          1,
+                                          NULL,
+                                          -1,
+                                          0,
+                                          NULL,
+                                          NULL,
+                                          &cap_fd);
+
+    check_condition("spawn --mnemonic-stdin happy-path child", child > 0);
+    if (child <= 0) {
+        return;
+    }
+
+    fd = connect_socket_retry("nsigner_test_mi_stdin_ok", 5000);
+    check_condition("--mnemonic-stdin reaches running server", fd >= 0);
+    if (fd >= 0) {
+        close(fd);
+    }
+
+    (void)kill(child, SIGTERM);
+    (void)waitpid(child, &status, 0);
+    if (cap_fd >= 0) {
+        close(cap_fd);
+    }
+}
+
+static void test_stdin_eof_without_newline(void) {
+    const char *const argv[] = {
+        "./build/nsigner", "--socket-name", "nsigner_test_mi_stdin_eof", "--mnemonic-stdin", NULL
+    };
+    int cap_fd = -1;
+    int status = 0;
+    int fd;
+    pid_t child = spawn_with_stdin_and_fd(argv,
+                                          VALID_MNEMONIC,
+                                          1,
+                                          NULL,
+                                          -1,
+                                          0,
+                                          NULL,
+                                          NULL,
+                                          &cap_fd);
+
+    check_condition("spawn --mnemonic-stdin EOF-without-newline child", child > 0);
+    if (child <= 0) {
+        return;
+    }
+
+    fd = connect_socket_retry("nsigner_test_mi_stdin_eof", 5000);
+    check_condition("--mnemonic-stdin EOF without newline accepted", fd >= 0);
+    if (fd >= 0) {
+        close(fd);
+    }
+
+    (void)kill(child, SIGTERM);
+    (void)waitpid(child, &status, 0);
+    if (cap_fd >= 0) {
+        close(cap_fd);
+    }
+}
+
+static void test_stdin_invalid_mnemonic(void) {
+    const char *const argv[] = {
+        "./build/nsigner", "--mnemonic-stdin", NULL
+    };
+    int cap_fd = -1;
+    int status = 0;
+    char cap[512];
+    pid_t child = spawn_with_stdin_and_fd(argv,
+                                          "not a valid mnemonic\n",
+                                          1,
+                                          NULL,
+                                          -1,
+                                          0,
+                                          NULL,
+                                          NULL,
+                                          &cap_fd);
+
+    check_condition("spawn --mnemonic-stdin invalid child", child > 0);
+    if (child <= 0) {
+        return;
+    }
+
+    check_condition("--mnemonic-stdin invalid exits", wait_exit_timeout(child, 2000, &status) == 0);
+    check_condition("--mnemonic-stdin invalid exits non-zero", WIFEXITED(status) && WEXITSTATUS(status) != 0);
+
+    if (cap_fd >= 0) {
+        (void)read_capture_nonblocking(cap_fd, cap, sizeof(cap));
+        check_condition("--mnemonic-stdin invalid emits validation failure", strstr(cap, "mnemonic validation failed") != NULL);
+        close(cap_fd);
+    }
+}
+
+static void test_stdin_overflow(void) {
+    const char *const argv[] = {
+        "./build/nsigner", "--mnemonic-stdin", NULL
+    };
+    char long_input[LONG_INPUT_LEN + 2];
+    int i;
+    int cap_fd = -1;
+    int status = 0;
+    char cap[512];
+    pid_t child;
+
+    for (i = 0; i < LONG_INPUT_LEN; ++i) {
+        long_input[i] = 'a';
+    }
+    long_input[LONG_INPUT_LEN] = '\n';
+    long_input[LONG_INPUT_LEN + 1] = '\0';
+
+    child = spawn_with_stdin_and_fd(argv,
+                                    long_input,
+                                    1,
+                                    NULL,
+                                    -1,
+                                    0,
+                                    NULL,
+                                    NULL,
+                                    &cap_fd);
+
+    check_condition("spawn --mnemonic-stdin overflow child", child > 0);
+    if (child <= 0) {
+        return;
+    }
+
+    check_condition("--mnemonic-stdin overflow exits", wait_exit_timeout(child, 2000, &status) == 0);
+    check_condition("--mnemonic-stdin overflow exits non-zero", WIFEXITED(status) && WEXITSTATUS(status) != 0);
+
+    if (cap_fd >= 0) {
+        (void)read_capture_nonblocking(cap_fd, cap, sizeof(cap));
+        check_condition("--mnemonic-stdin overflow emits length error", strstr(cap, "exceeded maximum length") != NULL);
+        close(cap_fd);
+    }
+}
+
+static void test_fd_happy_path(void) {
+    const char *const argv[] = {
+        "./build/nsigner", "--socket-name", "nsigner_test_mi_fd_ok", "--mnemonic-fd", "3", NULL
+    };
+    int cap_fd = -1;
+    int status = 0;
+    int fd;
+    pid_t child = spawn_with_stdin_and_fd(argv,
+                                          "",
+                                          0,
+                                          VALID_MNEMONIC "\n",
+                                          3,
+                                          1,
+                                          NULL,
+                                          NULL,
+                                          &cap_fd);
+
+    check_condition("spawn --mnemonic-fd happy-path child", child > 0);
+    if (child <= 0) {
+        return;
+    }
+
+    fd = connect_socket_retry("nsigner_test_mi_fd_ok", 5000);
+    check_condition("--mnemonic-fd reaches running server", fd >= 0);
+    if (fd >= 0) {
+        close(fd);
+    }
+
+    (void)kill(child, SIGTERM);
+    (void)waitpid(child, &status, 0);
+    if (cap_fd >= 0) {
+        close(cap_fd);
+    }
+}
+
+static void test_mutual_exclusion_and_validation_errors(void) {
+    struct {
+        const char *name;
+        const char *const *argv;
+        const char *expect_substr;
+    } cases[] = {
+        {
+            "mutual exclusion stdin+fd",
+            (const char *const[]){"./build/nsigner", "--mnemonic-stdin", "--mnemonic-fd", "3", NULL},
+            "mutually exclusive"
+        },
+        {
+            "stdin with stdio listener",
+            (const char *const[]){"./build/nsigner", "--listen", "stdio", "--mnemonic-stdin", NULL},
+            "requires --listen unix or --listen tcp"
+        },
+        {
+            "mnemonic-fd 1 rejected",
+            (const char *const[]){"./build/nsigner", "--mnemonic-fd", "1", NULL},
+            "--mnemonic-fd 1 is not allowed"
+        },
+        {
+            "mnemonic-fd 0 rejected with stdio",
+            (const char *const[]){"./build/nsigner", "--listen", "stdio", "--mnemonic-fd", "0", NULL},
+            "cannot be used with --listen stdio"
+        }
+    };
+
+    size_t i;
+    for (i = 0; i < sizeof(cases) / sizeof(cases[0]); ++i) {
+        int cap_fd = -1;
+        int status = 0;
+        char cap[512];
+        pid_t child = spawn_with_stdin_and_fd(cases[i].argv,
+                                              "",
+                                              1,
+                                              NULL,
+                                              -1,
+                                              0,
+                                              NULL,
+                                              NULL,
+                                              &cap_fd);
+
+        check_condition(cases[i].name, child > 0);
+        if (child <= 0) {
+            continue;
+        }
+
+        check_condition("expected parse-time failure exits", wait_exit_timeout(child, 2000, &status) == 0);
+        check_condition("expected parse-time failure non-zero", WIFEXITED(status) && WEXITSTATUS(status) != 0);
+
+        if (cap_fd >= 0) {
+            (void)read_capture_nonblocking(cap_fd, cap, sizeof(cap));
+            check_condition("expected parse-time error message", strstr(cap, cases[i].expect_substr) != NULL);
+            close(cap_fd);
+        }
+    }
+}
+
+static void test_lock_reunlock_falls_back_to_tui_after_fd_startup(void) {
+    const char *const argv[] = {
+        "./build/nsigner", "--socket-name", "nsigner_test_mi_lock", "--mnemonic-fd", "3", NULL
+    };
+    int stdin_write = -1;
+    int cap_fd = -1;
+    int status = 0;
+    int fd;
+    pid_t child = spawn_with_stdin_and_fd(argv,
+                                          "",
+                                          0,
+                                          VALID_MNEMONIC "\n",
+                                          3,
+                                          1,
+                                          &stdin_write,
+                                          NULL,
+                                          &cap_fd);
+
+    check_condition("spawn --mnemonic-fd lock test child", child > 0);
+    if (child <= 0) {
+        return;
+    }
+
+    fd = connect_socket_retry("nsigner_test_mi_lock", 5000);
+    check_condition("--mnemonic-fd lock test initial running server", fd >= 0);
+    if (fd >= 0) {
+        close(fd);
+    }
+
+    (void)write_full(stdin_write, "l\n" VALID_MNEMONIC "\n", strlen("l\n" VALID_MNEMONIC "\n"));
+    sleep_ms(800);
+
+    fd = connect_socket_retry("nsigner_test_mi_lock", 2000);
+    check_condition("lock+reunlock via TUI keeps server alive", fd >= 0);
+    if (fd >= 0) {
+        close(fd);
+    }
+
+    if (stdin_write >= 0) {
+        close(stdin_write);
+    }
+
+    (void)kill(child, SIGTERM);
+    (void)waitpid(child, &status, 0);
+    if (cap_fd >= 0) {
+        close(cap_fd);
+    }
+}
+
+int main(void) {
+    (void)signal(SIGPIPE, SIG_IGN);
+
+    test_stdin_happy_path();
+    test_stdin_eof_without_newline();
+    test_stdin_invalid_mnemonic();
+    test_stdin_overflow();
+    test_fd_happy_path();
+    test_mutual_exclusion_and_validation_errors();
+    test_lock_reunlock_falls_back_to_tui_after_fd_startup();
+
+    if (g_failures == 0) {
+        printf("ALL TESTS PASSED\n");
+        return 0;
+    }
+
+    printf("TESTS FAILED: %d\n", g_failures);
+    return 1;
+}

tests/test_policy.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -390,7 +390,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */
@@ -527,6 +527,14 @@ int main(void) {
     check_condition("parse_preapprove_spec maps nonzero nostr_index role", strcmp(parsed.roles[0], "nostr_idx_2") == 0);
     check_condition("parse_preapprove_spec stores nonzero nostr_index", parsed_nostr_index == 2);
 
+    rc = parse_preapprove_spec("caller=qubes:personal+pubkey:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef,role=main",
+                               &parsed,
+                               &parsed_nostr_index);
+    check_condition("parse_preapprove_spec accepts composite qubes+pubkey caller", rc == 0);
+    check_condition("parse_preapprove_spec stores composite caller",
+                    strcmp(parsed.caller,
+                           "qubes:personal+pubkey:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef") == 0);
+
     rc = parse_preapprove_spec("role=main", &parsed, &parsed_nostr_index);
     check_condition("parse_preapprove_spec rejects missing caller", rc == -1);
     rc = parse_preapprove_spec("caller=uid:1000", &parsed, &parsed_nostr_index);

tests/test_qrexec_auth.c

@@ -0,0 +1,369 @@
+#define _GNU_SOURCE
+
+#include <arpa/inet.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+#include <time.h>
+#include <unistd.h>
+
+#include <cJSON.h>
+#include <nostr_core/nostr_common.h>
+
+#include "../src/auth_envelope.h"
+
+#define MAX_MSG_SIZE 65536
+
+static int g_failures = 0;
+
+static void check_condition(const char *name, int condition) {
+    if (condition) {
+        printf("PASS: %s\n", name);
+    } else {
+        printf("FAIL: %s\n", name);
+        g_failures++;
+    }
+}
+
+static int write_full(int fd, const void *buf, size_t len) {
+    const unsigned char *p = (const unsigned char *)buf;
+    size_t off = 0;
+
+    while (off < len) {
+        ssize_t n = write(fd, p + off, len - off);
+        if (n < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            return -1;
+        }
+        off += (size_t)n;
+    }
+
+    return 0;
+}
+
+static int send_framed(int fd, const char *payload) {
+    uint32_t len = (uint32_t)strlen(payload);
+    uint32_t be_len = htonl(len);
+
+    if (write_full(fd, &be_len, sizeof(be_len)) != 0) {
+        return -1;
+    }
+    if (write_full(fd, payload, len) != 0) {
+        return -1;
+    }
+    return 0;
+}
+
+static int recv_framed(int fd, char **out_payload) {
+    unsigned char *buf = NULL;
+    size_t used = 0;
+    size_t cap = 0;
+
+    if (out_payload == NULL) {
+        return -1;
+    }
+    *out_payload = NULL;
+
+    for (;;) {
+        unsigned char chunk[1024];
+        ssize_t n = read(fd, chunk, sizeof(chunk));
+        if (n == 0) {
+            break;
+        }
+        if (n < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            free(buf);
+            return -1;
+        }
+
+        if (used + (size_t)n > cap) {
+            size_t new_cap = (cap == 0) ? 2048 : cap * 2;
+            while (new_cap < used + (size_t)n) {
+                new_cap *= 2;
+            }
+            {
+                unsigned char *tmp = (unsigned char *)realloc(buf, new_cap);
+                if (tmp == NULL) {
+                    free(buf);
+                    return -1;
+                }
+                buf = tmp;
+                cap = new_cap;
+            }
+        }
+
+        memcpy(buf + used, chunk, (size_t)n);
+        used += (size_t)n;
+    }
+
+    if (used < 4) {
+        free(buf);
+        return -1;
+    }
+
+    {
+        size_t off;
+        for (off = 0; off + 4 <= used; ++off) {
+            uint32_t be_len;
+            uint32_t len;
+
+            memcpy(&be_len, buf + off, sizeof(be_len));
+            len = ntohl(be_len);
+            if (len == 0 || len > MAX_MSG_SIZE) {
+                continue;
+            }
+            if (off + 4U + (size_t)len > used) {
+                continue;
+            }
+            if (buf[off + 4] != '{') {
+                continue;
+            }
+
+            {
+                char *payload = (char *)malloc((size_t)len + 1U);
+                if (payload == NULL) {
+                    free(buf);
+                    return -1;
+                }
+                memcpy(payload, buf + off + 4, (size_t)len);
+                payload[len] = '\0';
+                *out_payload = payload;
+                free(buf);
+                return 0;
+            }
+        }
+    }
+
+    free(buf);
+    return -1;
+}
+
+static char *build_auth_request(const unsigned char privkey[32],
+                                const char *req_id,
+                                const char *method) {
+    cJSON *root = NULL;
+    cJSON *params = NULL;
+    cJSON *auth = NULL;
+    char *printed = NULL;
+
+    params = cJSON_CreateArray();
+    if (params == NULL) {
+        return NULL;
+    }
+    cJSON_AddItemToArray(params, cJSON_CreateString(""));
+
+    if (auth_envelope_build_for_request(req_id,
+                                        method,
+                                        params,
+                                        privkey,
+                                        "qrexec-test",
+                                        time(NULL),
+                                        &auth) != 0) {
+        cJSON_Delete(params);
+        return NULL;
+    }
+
+    root = cJSON_CreateObject();
+    if (root == NULL) {
+        cJSON_Delete(params);
+        cJSON_Delete(auth);
+        return NULL;
+    }
+
+    cJSON_AddStringToObject(root, "id", req_id);
+    cJSON_AddStringToObject(root, "method", method);
+    cJSON_AddItemToObject(root, "params", params);
+    cJSON_AddItemToObject(root, "auth", auth);
+
+    printed = cJSON_PrintUnformatted(root);
+    cJSON_Delete(root);
+    return printed;
+}
+
+static int run_qrexec_once(const char *request_json, char **out_response) {
+    int in_pipe[2];
+    int out_pipe[2];
+    pid_t child;
+    int status;
+    const char *mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about\n";
+
+    if (out_response == NULL || request_json == NULL) {
+        return -1;
+    }
+    *out_response = NULL;
+
+    if (pipe(in_pipe) != 0) {
+        return -1;
+    }
+    if (pipe(out_pipe) != 0) {
+        close(in_pipe[0]);
+        close(in_pipe[1]);
+        return -1;
+    }
+
+    child = fork();
+    if (child < 0) {
+        close(in_pipe[0]);
+        close(in_pipe[1]);
+        close(out_pipe[0]);
+        close(out_pipe[1]);
+        return -1;
+    }
+
+    if (child == 0) {
+        int null_fd = open("/dev/null", O_WRONLY);
+        dup2(in_pipe[0], STDIN_FILENO);
+        dup2(out_pipe[1], STDOUT_FILENO);
+        if (null_fd >= 0) {
+            dup2(null_fd, STDERR_FILENO);
+            close(null_fd);
+        }
+
+        close(in_pipe[0]);
+        close(in_pipe[1]);
+        close(out_pipe[0]);
+        close(out_pipe[1]);
+
+        (void)setenv("QREXEC_REMOTE_DOMAIN", "personal", 1);
+
+        execl("./build/nsigner",
+              "./build/nsigner",
+              "--listen", "qrexec",
+              "--auth", "optional",
+              "--preapprove", "caller=qubes:personal,role=main",
+              (char *)NULL);
+        _exit(127);
+    }
+
+    close(in_pipe[0]);
+    close(out_pipe[1]);
+
+    if (write_full(in_pipe[1], mnemonic, strlen(mnemonic)) != 0) {
+        close(in_pipe[1]);
+        close(out_pipe[0]);
+        (void)kill(child, SIGKILL);
+        (void)waitpid(child, &status, 0);
+        return -1;
+    }
+
+    /* Give prompt_load_mnemonic()/fgets() time to consume only the mnemonic line
+     * before we write framed request bytes to the same stdin stream. */
+    {
+        struct timespec ts;
+        ts.tv_sec = 0;
+        ts.tv_nsec = 250 * 1000 * 1000;
+        (void)nanosleep(&ts, NULL);
+    }
+
+    if (send_framed(in_pipe[1], request_json) != 0) {
+        close(in_pipe[1]);
+        close(out_pipe[0]);
+        (void)kill(child, SIGKILL);
+        (void)waitpid(child, &status, 0);
+        return -1;
+    }
+    close(in_pipe[1]);
+
+    if (recv_framed(out_pipe[0], out_response) != 0) {
+        close(out_pipe[0]);
+        (void)kill(child, SIGKILL);
+        (void)waitpid(child, &status, 0);
+        return -1;
+    }
+
+    close(out_pipe[0]);
+    if (waitpid(child, &status, 0) <= 0) {
+        free(*out_response);
+        *out_response = NULL;
+        return -1;
+    }
+
+    return 0;
+}
+
+int main(void) {
+    char *resp = NULL;
+    char *auth_req = NULL;
+    unsigned char privkey[32] = {
+        0x01,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+        0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+        0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+        0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00
+    };
+
+    check_condition("nostr_init for auth signing", nostr_init() == 0);
+
+    /* no auth => legacy qubes:personal preapprove should match */
+    if (run_qrexec_once("{\"id\":\"1\",\"method\":\"get_public_key\",\"params\":[\"\"]}", &resp) == 0) {
+        check_condition("qrexec optional/no-auth still allows legacy qubes caller preapprove",
+                        strstr(resp, "\"result\":") != NULL);
+        free(resp);
+        resp = NULL;
+    } else {
+        check_condition("qrexec optional/no-auth request roundtrip", 0);
+    }
+
+    auth_req = build_auth_request(privkey, "2", "get_public_key");
+    check_condition("build qrexec auth request", auth_req != NULL);
+    if (auth_req != NULL) {
+        if (run_qrexec_once(auth_req, &resp) == 0) {
+            check_condition("qrexec optional/auth request uses composite identity and misses legacy preapprove",
+                            strstr(resp, "\"code\":2001") != NULL && strstr(resp, "policy_denied") != NULL);
+            free(resp);
+            resp = NULL;
+        } else {
+            check_condition("qrexec optional/auth request roundtrip", 0);
+        }
+        free(auth_req);
+        auth_req = NULL;
+    }
+
+    auth_req = build_auth_request(privkey, "3", "get_public_key");
+    check_condition("build second qrexec auth request", auth_req != NULL);
+    if (auth_req != NULL) {
+        cJSON *root = cJSON_Parse(auth_req);
+        char *tampered = NULL;
+        cJSON *method_item;
+
+        if (root != NULL) {
+            method_item = cJSON_GetObjectItemCaseSensitive(root, "method");
+            if (cJSON_IsString(method_item)) {
+                cJSON_SetValuestring(method_item, "sign_event");
+            }
+            tampered = cJSON_PrintUnformatted(root);
+            cJSON_Delete(root);
+        }
+
+        if (tampered != NULL && run_qrexec_once(tampered, &resp) == 0) {
+            check_condition("qrexec optional/malformed-auth rejects with auth-layer code",
+                            strstr(resp, "\"code\":2015") != NULL && strstr(resp, "auth_envelope_mismatch") != NULL);
+            free(resp);
+            resp = NULL;
+        } else {
+            check_condition("qrexec optional/malformed-auth request roundtrip", 0);
+        }
+
+        free(tampered);
+        free(auth_req);
+    }
+
+    nostr_cleanup();
+
+    if (g_failures == 0) {
+        printf("ALL TESTS PASSED\n");
+        return 0;
+    }
+
+    printf("TESTS FAILED: %d\n", g_failures);
+    return 1;
+}

tests/test_role_table.c

@@ -232,7 +232,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -387,7 +387,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

tests/test_selector.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */

tests/test_socket_name.c

@@ -229,7 +229,7 @@ const char *enforce_strerror(int err);
 #define POLICY_MAX_ROLES      16
 #define POLICY_MAX_PURPOSES   8
 #define POLICY_VERB_MAX_LEN   32
-#define POLICY_CALLER_MAX_LEN 80
+#define POLICY_CALLER_MAX_LEN 160
 
 /* Prompt behavior */
 typedef enum {
@@ -384,7 +384,7 @@ typedef struct {
     uid_t uid;
     gid_t gid;
     pid_t pid;
-    char caller_id[80];  /* "uid:<n>" */
+    char caller_id[POLICY_CALLER_MAX_LEN];  /* "uid:<n>" */
 } caller_identity_t;
 
 /* Server context */