# `nsigner_client` — Linux CLI for n_signer

A standalone Linux command-line client that connects to a running [`n_signer`](https://github.com/your-org/n_signer) process and calls its JSON-RPC verbs over stdin/stdout. Designed for pipe-to-`nak` workflows.

## Build

```bash
make clients
```

Produces `build/nsigner_client`. Links `nostr_core_lib` exactly like the existing examples.

## Usage

```
nsigner_client [global options] <verb> [verb args...]
```

### Global options

| Flag | Default | Meaning |
|------|---------|---------|
| `--socket-name`, `-n <name>` | auto-discover | Abstract socket name without `@` |
| `--timeout <ms>` | `5000` | Transport timeout |
| `--tcp <host:port>` | none | TCP transport (requires `--auth-privkey`) |
| `--serial <device>` | none | USB CDC-ACM serial transport |
| `--qrexec <qube:service>` | none | Qubes qrexec transport |
| `--auth-privkey <32-byte hex>` | none | Auth envelope privkey for TCP |
| `--auth-label <text>` | none | Auth envelope label |

### Selector options (for `nostr_*` verbs)

| Flag | Meaning | JSON emitted |
|------|---------|-------------|
| `--role <name>` | Named path-role registered in the signer | `{"role":"<name>"}` |
| `--path <path>` | Full BIP-44 derivation path | `{"role_path":"<path>"}` |

### Algorithm options (for algorithm-based verbs)

| Flag | Default | Meaning |
|------|---------|---------|
| `--algorithm <alg>` | none | `secp256k1`/`ed25519`/`x25519`/`ml-dsa-65`/`slh-dsa-128s`/`ml-kem-768`/`otp` |
| `--index <N>` | `0` | Algorithm derivation index |
| `--scheme <schnork\|ecdsa>` | `schnorr` | secp256k1 `sign`/`verify` only |
| `--encoding <base64\|hex>` | `base64` | OTP `encrypt`/`decrypt` only |
| `--format <plain\|structured>` | `plain` | `nostr_get_public_key` output shape |

### Mine-event options

| Flag | Meaning |
|------|---------|
| `--difficulty <N>` | Target leading zero bits |
| `--threads <N>` | Mining threads (default 1) |
| `--timeout-sec <N>` | Mining timeout in seconds |

## Verb reference

### Utility

| Verb | stdout |
|------|--------|
| `list` | Lists running n_signer abstract sockets (one `@name` per line) |

### Metadata

| Verb | RPC method | stdout |
|------|------------|--------|
| `get-info` | `get_info` | raw result JSON (name, version, verbs, algorithms) |

### Nostr verbs (role-based)

| Verb | RPC method | stdin/argv | stdout |
|------|------------|------------|--------|
| `get-public-key` | `nostr_get_public_key` | none | pubkey hex (or structured JSON with `--format structured`) |
| `sign-event` | `nostr_sign_event` | event JSON from argv or stdin | signed event JSON |
| `mine-event` | `nostr_mine_event` | event JSON from argv or stdin | signed mined event JSON |
| `nip04-encrypt <peer>` | `nostr_nip04_encrypt` | plaintext from argv or stdin | ciphertext |
| `nip04-decrypt <peer>` | `nostr_nip04_decrypt` | ciphertext from argv or stdin | plaintext |
| `nip44-encrypt <peer>` | `nostr_nip44_encrypt` | plaintext from argv or stdin | ciphertext |
| `nip44-decrypt <peer>` | `nostr_nip44_decrypt` | ciphertext from argv or stdin | plaintext |

### Algorithm-based verbs

| Verb | RPC method | argv | stdout |
|------|------------|------|--------|
| `get-public-key` | `get_public_key` | none | structured JSON `{"algorithm":...,"public_key":...,"key_id":...}` |
| `sign <msg-hex>` | `sign` | hex bytes | structured JSON `{"signature":...,"algorithm":...,"key_id":...}` |
| `verify <msg-hex> <sig-hex>` | `verify` | hex bytes | `valid` / `invalid` (exit 0/1) |
| `derive <data>` | `derive` | UTF-8 data (argv or stdin) | structured JSON |
| `encapsulate <peer-pubkey-hex>` | `encapsulate` | hex | structured JSON |
| `decapsulate <ciphertext-hex>` | `decapsulate` | hex | structured JSON |
| `derive-shared-secret <peer-pubkey-hex>` | `derive_shared_secret` | hex | shared secret hex |
| `encrypt <plaintext>` | `encrypt` | plaintext (base64 by default) | ciphertext |
| `decrypt <ciphertext>` | `decrypt` | ciphertext | plaintext |

### Generic escape hatch

| Verb | RPC method | input | stdout |
|------|------------|-------|--------|
| `call <method>` | `<method>` | JSON params array from stdin or argv | raw result JSON |

## Selector explanation

The `nostr_*` verbs select a key via the options object using both `--role` and `--path`:

- **`--role <name> --path <path>`** — Both are required for all `nostr_*` verbs. The role authorizes the request and determines the encryption scheme. The path selects the specific key to derive. Sends `{"role":"<name>","role_path":"<path>"}` to the server.
- **`--role` without `--path`** — Client-side error: `--path is required for nostr verbs`.
- **`--path` without `--role`** — Client-side error: `--role is required for nostr verbs`.

For algorithm verbs, `--algorithm` and `--index` populate the options object instead.

## Pipe-to-nak recipes

```bash
# Get public key
nsigner_client --role main --path "m/44'/1237'/0'/0/0" get-public-key

# Sign an event and publish via nak
echo '{"kind":1,"content":"hello nostr","tags":[],"created_at":1700000000}' \
  | nsigner_client --role main --path "m/44'/1237'/0'/0/0" sign-event \
  | nak publish

# Mine a proof-of-work event
echo '{"kind":1,"content":"pow","tags":[],"created_at":1700000000}' \
  | nsigner_client --role main --path "m/44'/1237'/0'/0/0" mine-event --difficulty 20 --threads 4

# NIP-44 encrypt
nsigner_client --role main --path "m/44'/1237'/0'/0/0" nip44-encrypt <peer-pubkey> "secret message"

# Algorithm-based signing
nsigner_client --algorithm ed25519 --index 0 sign 68656c6c6f

# Verify a signature
nsigner_client --algorithm secp256k1 verify <msg-hex> <sig-hex> && echo "valid"

# Get signer info
nsigner_client get-info
```

## Transport options

| Transport | Flag | Notes |
|-----------|------|-------|
| UNIX abstract socket | `--socket-name <name>` or auto-discover | Default. Auto-discovers if exactly one `@nsigner*` socket exists. |
| TCP | `--tcp <host:port>` | Requires `--auth-privkey` for auth envelope. |
| Serial (USB CDC-ACM) | `--serial <device>` | e.g. `--serial /dev/ttyACM0` |
| Qubes qrexec | `--qrexec <qube:service>` | e.g. `--qrexec sys-signer:qubes.NsignerRpc` |

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Invalid (verify verb only — signature is invalid) |
| 2 | Error (transport, RPC, or usage error) |

For `verify`: exit 0 = valid signature, exit 1 = invalid signature, exit 2 = error.

## stdin/stdout contract

- All payload output goes to stdout as a single line, newline-terminated.
- All diagnostics (errors, warnings) go to stderr.
- `sign-event`, `nip04-*`, `nip44-*`, `derive`, `encrypt`, `decrypt` read their payload from argv if present, otherwise from stdin (one line).
- `sign`, `verify`, `encapsulate`, `decapsulate`, `derive-shared-secret` take hex from argv only (binary payloads).
- `call` reads a JSON params array from stdin (one line) or argv.

## See also

- [`n_signer_client_PLAN.md`](n_signer_client_PLAN.md) — the full implementation plan
- [`README.md`](../README.md) — n_signer main documentation (API §4)
- [`examples/sign_event_client.c`](../examples/sign_event_client.c) — reference example