laantungir/n_signer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

v0.0.35 - Update README with qrexec bridge docs, update start_nsigner.sh to support qrexec mode and extra args

Browse Source
This commit is contained in:
Laan Tungir
2026-07-11 11:08:04 -04:00
parent d15eebb80f
commit a39baed82b
6 changed files with 205 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@@ -247,6 +247,8 @@ Discovery:
- `nsigner --listen stdio` runs one framed JSON-RPC request/response over stdin/stdout.
- `nsigner --listen qrexec` is the same stdio framing mode, but caller identity can be derived from `QREXEC_REMOTE_DOMAIN` (displayed as `qubes:<source-vm>`).
- `nsigner --listen tcp:IPv4:PORT` or `tcp:[IPv6]:PORT` enables TCP listening for non-AF_UNIX clients (for example `tcp:127.0.0.1:8080`, `tcp:[::]:8080`, or `tcp:[fd00::1234]:8080`).
- `nsigner bridge --to <socket-name>` is a stateless relay for Qubes qrexec: reads one framed request from stdin, forwards it to a persistent signer's abstract unix socket, and relays the response to stdout. Used as the `qubes.NsignerRpc` service entrypoint. See [§8.3](#83-qubes-os-qube) and [`plans/qrexec_persistent_bridge.md`](plans/qrexec_persistent_bridge.md).
- `--bridge-source-trusted` (unix listener only): marks the socket as a trusted bridge endpoint. Each connection sends a framed `{"qrexec_source":"<vm>"}` preamble before the request, and the caller identity is composed as `qubes:<vm>` — matching the native qrexec identity path. This enables a persistent signer (mnemonic in mlock'd RAM) to receive qrexec-routed requests without spawning a fresh process per call.
### 7.2 ESP32 MCU: TinyUSB composite (CDC + WebUSB)
@@ -283,7 +285,43 @@ MCU target reuses mnemonic/role/selector/enforcement/dispatcher core and swaps t
### 8.3 Qubes OS qube
Qubes deployment runs `n_signer` in a dedicated signer qube as a foreground process under explicit user session control. Transport binding is platform-specific, but lifecycle and memory-only state model are unchanged.
Qubes deployment runs `n_signer` in a dedicated signer qube (e.g. `nostr_signer`) as a foreground process under explicit user session control. The mnemonic lives only in mlock'd RAM in that qube — a compromised agent in a caller qube cannot read it (hypervisor-enforced memory isolation).
Two transport paths are supported:
**FIPS/TCP** — the signer listens on `tcp:[::]:8080` and FIPS carries traffic between qubes as an IPv6 mesh substrate. See [`documents/FIPS_DEPLOYMENT.md`](documents/FIPS_DEPLOYMENT.md).
**Qubes qrexec bridge** (recommended for no-network deployments) — a persistent signer listens on an abstract unix socket, and a stateless `nsigner bridge` relay (the `qubes.NsignerRpc` qrexec service) forwards one request per qrexec invocation. No network, no FIPS — pure intra-host IPC. Caller identity is `qubes:<source-vm>` (from `QREXEC_REMOTE_DOMAIN`), relayed via a trusted preamble. See [`plans/qrexec_persistent_bridge.md`](plans/qrexec_persistent_bridge.md) for the full design.
#### Qrexec bridge setup
**In the signer qube** (`nostr_signer`):
```bash
# Install nsigner and the qrexec service
bash setup_signer_qube.sh # from packaging/qubes/
# Start the persistent signer (mnemonic entered at terminal, in mlock'd RAM)
~/.local/bin/nsigner --listen unix --socket-name nsigner --bridge-source-trusted
```
**In dom0**:
```bash
# Install policy and tag the signer qube
bash setup_dom0.sh nostr_signer # from packaging/qubes/
```
The dom0 policy allows trusted caller qubes without a popup (memory isolation is the real security boundary) and asks for confirmation from any other qube. The signer's own approval prompt at the `nostr_signer` terminal is the operation-level gate.
**From a caller qube**:
```bash
# JavaScript example (uses qrexec-client-vm, no auth envelope needed)
node examples/n_signer_qube_example_qrexec.js nostr_signer
```
Setup scripts and policy are in [`packaging/qubes/`](packaging/qubes/). See also [`documents/QUBES_OS.md`](documents/QUBES_OS.md) and [`documents/qubes_client_examples.md`](documents/qubes_client_examples.md).
## 9. Usage
@@ -319,6 +357,18 @@ TCP transport mode (no TUI; serves requests until terminated):
nsigner --listen tcp:[::]:8080
```
Qrexec bridge mode (stateless relay to a persistent signer's unix socket; used as the `qubes.NsignerRpc` service):
```bash
nsigner bridge --to nsigner
```
Persistent signer for qrexec bridge (unix listener with trusted source-qube preamble):
```bash
nsigner --listen unix --socket-name nsigner --bridge-source-trusted
```
### 9.2 Send a request (client mode)
From another terminal, target the signer by its socket name:
@@ -414,6 +464,11 @@ These items are designed and worth doing, but are not in the current implementat
- [`documents/CLIENT_IMPLEMENTATION.md`](documents/CLIENT_IMPLEMENTATION.md): client integration contract and framing behavior
- [`documents/QUBES_OS.md`](documents/QUBES_OS.md): Qubes OS deployment/integration checklist for dedicated signer qubes
- [`documents/FIPS_DEPLOYMENT.md`](documents/FIPS_DEPLOYMENT.md): Tier-1 FIPS deployment runbook using loopback TCP listener
- [`plans/qrexec_persistent_bridge.md`](plans/qrexec_persistent_bridge.md): design for the qrexec → unix-socket bridge transport (persistent signer, no mnemonic on disk)
- [`packaging/qubes/`](packaging/qubes/): qrexec service script, dom0 policy, and setup scripts for Qubes deployment
- [`examples/n_signer_qube_example_qrexec.js`](examples/n_signer_qube_example_qrexec.js): JavaScript caller example using qrexec (no network, no auth envelope)
- [`examples/n_signer_qube_example_fips.js`](examples/n_signer_qube_example_fips.js): JavaScript caller example using FIPS/TCP with auth envelope
- [`examples/get_pubkey_tcp.c`](examples/get_pubkey_tcp.c): C caller example using TCP transport with auth envelope
- [`plans/nsigner.md`](plans/nsigner.md): implementation plan and sequencing
- [`plans/seed_phrase_uses.md`](plans/seed_phrase_uses.md): seed phrase domain/use catalog and caveats
- [`firmware/feather_s3_tft`](firmware/feather_s3_tft): Feather ESP32-S3 Reverse TFT firmware (TinyUSB composite CDC + WebUSB signer PoC)

14
install_qube_fips_nsigner.sh
View File

@@ -178,6 +178,16 @@ set -euo pipefail
export PATH="$HOME/.local/bin:$PATH"
LISTEN_TARGET="${NSIGNER_LISTEN_TARGET:-tcp:[::]:8080}"
# If first arg is "qrexec", start in unix bridge mode for Qubes qrexec.
# Otherwise, pass any extra args through to nsigner (e.g. --allow-all).
if [[ "${1:-}" == "qrexec" ]]; then
LISTEN_TARGET="unix"
EXTRA_ARGS="--socket-name nsigner --bridge-source-trusted"
shift
else
EXTRA_ARGS="$*"
fi
echo "=== n_signer startup ==="
echo "listen target: ${LISTEN_TARGET}"
@@ -208,7 +218,11 @@ fi
echo
echo "Starting signer..."
echo "On first remote request, approve in prompt with [y] or [a]."
if [[ -n "${EXTRA_ARGS}" ]]; then
exec "$HOME/.local/bin/nsigner" --listen "${LISTEN_TARGET}" ${EXTRA_ARGS}
else
exec "$HOME/.local/bin/nsigner" --listen "${LISTEN_TARGET}"
fi
EOF
chmod 0755 "${script_path}"

7
packaging/qubes/policy.d/40-nsigner.policy
View File

@@ -1,5 +1,10 @@
# Qubes OS qrexec policy for nsigner
# Syntax: service +argument source target action
# Allow specific qubes to reach the signer qube with user confirmation
#
# The ai qube is allowed without a dom0 popup (memory isolation is the
# real security boundary — the signer's own approval prompt in the
# nostr_signer terminal is the operation-level gate).
qubes.NsignerRpc * ai @tag:nsigner-signer allow target=nostr_signer
# Any other qube must get a dom0 confirmation popup.
qubes.NsignerRpc * @anyvm @tag:nsigner-signer ask default_target=nostr_signer
qubes.NsignerRpc * @anyvm @anyvm deny

58
packaging/qubes/setup_dom0.sh Executable file
View File

@@ -0,0 +1,58 @@
#!/bin/bash
#
# setup_dom0.sh — install qrexec policy and tag the signer qube in dom0.
#
# Run this in dom0. It creates /etc/qubes/policy.d/40-nsigner.policy
# and tags the nostr_signer qube with 'nsigner-signer'.
#
# Usage:
# bash setup_dom0.sh [signer_qube_name]
#
# Default signer qube name is "nostr_signer".
set -euo pipefail
SIGNER_QUBE="${1:-nostr_signer}"
echo "=== n_signer dom0 setup ==="
echo "Signer qube: ${SIGNER_QUBE}"
echo
# Create policy directory if it doesn't exist
sudo mkdir -p /etc/qubes/policy.d
# Write the qrexec policy
# The 'ai' qube is allowed without a dom0 popup (memory isolation is the
# real security boundary; the signer's own approval prompt is the gate).
# Any other qube gets a dom0 confirmation popup.
echo "Installing qrexec policy to /etc/qubes/policy.d/40-nsigner.policy..."
echo "# Qubes OS qrexec policy for nsigner" | sudo tee /etc/qubes/policy.d/40-nsigner.policy > /dev/null
echo "qubes.NsignerRpc * ai @tag:nsigner-signer allow target=${SIGNER_QUBE}" | sudo tee -a /etc/qubes/policy.d/40-nsigner.policy > /dev/null
echo "qubes.NsignerRpc * @anyvm @tag:nsigner-signer ask default_target=${SIGNER_QUBE}" | sudo tee -a /etc/qubes/policy.d/40-nsigner.policy > /dev/null
echo "qubes.NsignerRpc * @anyvm @anyvm deny" | sudo tee -a /etc/qubes/policy.d/40-nsigner.policy > /dev/null
echo "Policy installed. Contents:"
cat /etc/qubes/policy.d/40-nsigner.policy
echo
# Tag the signer qube
echo "Tagging ${SIGNER_QUBE} with 'nsigner-signer'..."
qvm-tags "${SIGNER_QUBE}" add nsigner-signer
echo "Tag added."
echo
# Verify
echo "=== Verification ==="
echo "Policy file:"
ls -l /etc/qubes/policy.d/40-nsigner.policy
echo
echo "Tags on ${SIGNER_QUBE}:"
qvm-tags "${SIGNER_QUBE}" list 2>/dev/null | grep nsigner || echo "(tag not found — check qube name)"
echo
echo "=== dom0 setup complete ==="
echo
echo "Next steps:"
echo " 1. In ${SIGNER_QUBE}: run setup_signer_qube.sh"
echo " 2. In ${SIGNER_QUBE}: start the persistent signer:"
echo " ~/.local/bin/nsigner --listen unix --socket-name nsigner --bridge-source-trusted"
echo " 3. In caller qube: node examples/n_signer_qube_example_qrexec.js ${SIGNER_QUBE}"

68
packaging/qubes/setup_signer_qube.sh Executable file
View File

@@ -0,0 +1,68 @@
#!/bin/bash
#
# setup_signer_qube.sh — install nsigner v0.0.34+ and the qrexec bridge service
# in the nostr_signer qube.
#
# Run this in the nostr_signer qube (as the regular user, not root).
# It will:
# 1. Run install_nsigner.sh to download the latest nsigner release (v0.0.34+)
# 2. Install the qubes.NsignerRpc qrexec service (bridge mode)
# 3. Print instructions for starting the persistent signer
#
# Usage:
# bash setup_signer_qube.sh
set -euo pipefail
NSIGNER_BIN="${HOME}/.local/bin/nsigner"
SERVICE_DST="/etc/qubes-rpc/qubes.NsignerRpc"
echo "=== n_signer qube setup ==="
echo
# Step 1: Update nsigner binary
if [ -f "${HOME}/install_nsigner.sh" ]; then
echo "Step 1: Running install_nsigner.sh to update nsigner..."
bash "${HOME}/install_nsigner.sh"
else
echo "Step 1: install_nsigner.sh not found in ${HOME}."
echo " Make sure install_nsigner.sh is in your home directory first."
exit 1
fi
echo
# Verify the bridge subcommand exists
echo "Verifying bridge subcommand..."
if ! "${NSIGNER_BIN}" bridge --help > /dev/null 2>&1; then
echo "ERROR: nsigner does not have the 'bridge' subcommand."
echo " The installed version may be too old. Expected v0.0.34 or later."
"${NSIGNER_BIN}" --version
exit 1
fi
echo "OK: bridge subcommand available."
"${NSIGNER_BIN}" --version
echo
# Step 2: Install the qrexec service
echo "Step 2: Installing qrexec service to ${SERVICE_DST}..."
echo '#!/bin/sh' | sudo tee "${SERVICE_DST}" > /dev/null
echo '# qubes.NsignerRpc — stateless bridge to persistent nsigner unix socket' | sudo tee -a "${SERVICE_DST}" > /dev/null
echo '# No mnemonic, no secrets. Relays QREXEC_REMOTE_DOMAIN as source-qube preamble.' | sudo tee -a "${SERVICE_DST}" > /dev/null
echo "exec ${NSIGNER_BIN} bridge --to nsigner" | sudo tee -a "${SERVICE_DST}" > /dev/null
sudo chmod 0755 "${SERVICE_DST}"
echo "Service installed. Contents:"
cat "${SERVICE_DST}"
echo
echo "=== Signer qube setup complete ==="
echo
echo "To start the persistent signer (mnemonic entered at terminal, in mlock'd RAM):"
echo
echo " ${NSIGNER_BIN} --listen unix --socket-name nsigner --bridge-source-trusted"
echo
echo "The signer will prompt you for the mnemonic. It stays running with the"
echo "mnemonic in RAM only — nothing on disk. Leave it running in a terminal."
echo
echo "Then from a caller qube (e.g. 'ai'):"
echo " node examples/n_signer_qube_example_qrexec.js nostr_signer"

4
src/main.c
View File

@@ -494,8 +494,8 @@ int socket_name_random(char *out, size_t out_len);
/* Version information (auto-updated by build/version tooling) */
#define NSIGNER_VERSION_MAJOR 0
#define NSIGNER_VERSION_MINOR 0
#define NSIGNER_VERSION_PATCH 34
#define NSIGNER_VERSION "v0.0.34"
#define NSIGNER_VERSION_PATCH 35
#define NSIGNER_VERSION "v0.0.35"
/* NSIGNER_HEADERLESS_DECLS_END */