n_signer/plans/legacy_verb_aliases.md

# Plan: Legacy Verb Aliases (Migration Path) — COMPLETED

> **Status: Done.** All steps below have been executed. The legacy verb names are gone from the wire protocol, the implementation, the tests, the clients, and the documentation. `make dev` builds clean and `make test` passes (all 10 test binaries, 230+ assertions).

## Context

`n_signer` is being moved to a clean, unified API (see [`api.md`](../api.md)). The current implementation in [`src/dispatcher.c`](../src/dispatcher.c) still uses the legacy unprefixed verb names. This document captures the old → new mapping so the implementation can be updated in one pass. Since this is a new project, there are no external clients to migrate — the legacy names are an internal cleanup item, not a long-term compatibility surface.

## Goal

Rename the verbs in [`src/dispatcher.c`](../src/dispatcher.c) to match [`api.md`](../api.md), remove the legacy aliases, and delete the alias-routing logic. No backward-compatibility shim is needed.

## Old → New Verb Mapping

### Nostr protocol verbs (add `nostr_` prefix)

| Legacy verb         | New verb                  |
|---------------------|---------------------------|
| `sign_event`        | `nostr_sign_event`        |
| `mine_event`        | `nostr_mine_event`        |
| `nip04_encrypt`     | `nostr_nip04_encrypt`     |
| `nip04_decrypt`     | `nostr_nip04_decrypt`     |
| `nip44_encrypt`     | `nostr_nip44_encrypt`     |
| `nip44_decrypt`     | `nostr_nip44_decrypt`     |

The role-based `get_public_key` (with `nostr_index`/`role`/`role_path` selector) becomes `nostr_get_public_key`. The algorithm-based `get_public_key` (with `algorithm` option) stays `get_public_key`.

### Algorithm-based verb aliases (collapse into canonical names)

| Legacy verb         | Canonical verb     | Default algorithm (when `algorithm` omitted) |
|---------------------|--------------------|----------------------------------------------|
| `sign_data`         | `sign`             | (from role)                                  |
| `ssh_sign`          | `sign`             | `ed25519`                                    |
| `verify_signature`  | `verify`           | (from role)                                  |
| `kem_encapsulate`   | `encapsulate`      | `ml-kem-768`                                 |
| `kem_decapsulate`   | `decapsulate`      | `ml-kem-768`                                 |

After the rename, callers must always supply `algorithm` explicitly — the "default algorithm" fallbacks are removed. This makes the algorithm-based verbs uniform: every call specifies its algorithm.

### OTP verb aliases (collapse into `encrypt`/`decrypt`)

| Legacy verb     | Canonical verb | Required option          |
|-----------------|----------------|--------------------------|
| `otp_encrypt`   | `encrypt`      | `{"algorithm":"otp"}`    |
| `otp_decrypt`   | `decrypt`      | `{"algorithm":"otp"}`    |

The general `encrypt`/`decrypt` with `curve:"otp"` routing is replaced by `algorithm:"otp"`.

## Implementation Steps

1. **[`src/dispatcher.c`](../src/dispatcher.c)** — rename the `VERB_*` string constants:
   - `VERB_SIGN_EVENT` → `"nostr_sign_event"`
   - `VERB_MINE_EVENT` → `"nostr_mine_event"`
   - `VERB_NIP04_ENCRYPT` → `"nostr_nip04_encrypt"`
   - `VERB_NIP04_DECRYPT` → `"nostr_nip04_decrypt"`
   - `VERB_NIP44_ENCRYPT` → `"nostr_nip44_encrypt"`
   - `VERB_NIP44_DECRYPT` → `"nostr_nip44_decrypt"`
   - Add `VERB_NOSTR_GET_PUBLIC_KEY` = `"nostr_get_public_key"`; split the current `get_public_key` handler into two branches based on whether `algorithm` is present (algorithm-based) or `nostr_index`/`role`/`role_path` is present (Nostr).

2. **Remove alias routing** — delete [`is_algorithm_verb()`](../src/dispatcher.c:829), [`canonical_alg_verb()`](../src/dispatcher.c:846), and the alias-fallthrough logic in [`dispatcher_handle_request()`](../src/dispatcher.c:1559). The verbs `sign_data`, `ssh_sign`, `verify_signature`, `kem_encapsulate`, `kem_decapsulate`, `otp_encrypt`, `otp_decrypt` are no longer recognized.

3. **Remove `curve:"otp"` routing** — the `encrypt`/`decrypt` handler no longer special-cases `curve:"otp"`; OTP is selected via `algorithm:"otp"` like every other algorithm.

4. **Update tests** — [`tests/test_dispatcher.c`](../tests/test_dispatcher.c), [`tests/test_integration.c`](../tests/test_integration.c), [`tests/test_algorithm_api.c`](../tests/test_algorithm_api.c), and any other test that uses the legacy verb names. Rename all call sites to the new verbs and add `algorithm` explicitly where it was previously defaulted.

5. **Update examples and clients**:
   - [`client/demo_c99.c`](../client/demo_c99.c)
   - [`client/demo_javascript.js`](../client/demo_javascript.js)
   - [`client/demo_python.py`](../client/demo_python.py)
   - [`examples/`](../examples/) — all example files using legacy verb names
   - [`README.md`](../README.md) — the §5 summary and any inline examples

6. **Update policy/preapprove** — [`src/policy.c`](../src/policy.c) and the `--preapprove` CLI parsing in [`src/main.c`](../src/main.c) should accept the new verb names. The role-based preapprove examples in [`api.md`](../api.md) §6 already use the `nostr_` prefix.

## Verification

- `make dev && ./build/nsigner --version` builds clean.
- `make test` — all tests pass with the new verb names.
- Manual smoke test over HTTP: each verb in [`api.md`](../api.md) §3 responds as documented.
- `grep -rn "sign_event\|mine_event\|nip04_\|nip44_\|sign_data\|ssh_sign\|verify_signature\|kem_encapsulate\|kem_decapsulate\|otp_encrypt\|otp_decrypt" src/ tests/ client/ examples/` returns no matches (all legacy names gone).