neozip-mcp 0.1.0-beta

package/docs/NEOZIP_CONNECT_CLI.md

@@ -0,0 +1,185 @@
+# NeoZip Connect CLI
+
+`neozip-connect` is published with the `neozip-mcp` npm package. It registers a NeoZip account on a Token Service, provisions a Data Wallet and X25519 identity, and writes a **connection store** under `~/.neozip/connection/`.
+
+The MCP server reads that store at startup; it does **not** shell out to the CLI during normal operation.
+
+For field-level schema details, see [NEOZIP_CONNECTION_STORE.md](./NEOZIP_CONNECTION_STORE.md). The canonical schema is in [NEOZIP_CONNECTION_FILE.md](https://github.com/neoware/neozip-token-service/blob/main/docs/NEOZIP_CONNECTION_FILE.md) (neozip-token-service).
+
+---
+
+## Connection store
+
+| Override | Default |
+|----------|---------|
+| `NEOZIP_CONNECTION_DIR` | `~/.neozip/connection/` |
+
+Each saved account is a **connection** — one email + wallet + identity bound to one Token Service deployment. You can store multiple connections on one machine.
+
+```
+~/.neozip/connection/
+├── manifest.json                          # Index + active account
+└── connections/
+    └── <connection-uuid>/
+        ├── public.json                    # Non-secret metadata (plain JSON)
+        └── secrets.enc                    # Encrypted credentials (AES-256-GCM)
+```
+
+| File | Contents |
+|------|----------|
+| `manifest.json` | Connection IDs grouped by Token Service origin; which connection is **active** for MCP |
+| `public.json` | Label, `tokenServiceOrigin`, verified email, EVM address, wallet/identity IDs, X25519 public key fingerprint, onboarding phase timestamps |
+| `secrets.enc` | Encrypted Bearer access token and EVM private key |
+
+Inspect without secrets:
+
+```bash
+neozip-connect dump
+neozip-connect status --verbose
+```
+
+A connection reaches **`phase: ready`** when email is verified, the wallet is linked, and the X25519 identity is provisioned. MCP loads the active ready connection for timestamp, tokenize, mint, stamp, and recipient encryption.
+
+### Encryption
+
+By default, `secrets.enc` is encrypted with a **machine-local key** (hostname + username). No setup step is required on a trusted machine.
+
+Optional — set a custom passphrase when you need portable encryption across machines or users:
+
+```bash
+export NEOZIP_UNLOCK_PASSPHRASE='your-secret-passphrase'
+```
+
+Use the same value for both `neozip-connect` and `neozip-mcp` when you set a custom passphrase.
+
+**Recovery phrase vs unlock passphrase:** When you create a new Data Wallet, the wizard shows your **wallet recovery phrase** once (for restoring the wallet). `NEOZIP_UNLOCK_PASSPHRASE` only encrypts files under `~/.neozip/connection/` — it is not the wallet recovery phrase.
+
+Optional Token Service default during setup:
+
+```bash
+export TOKEN_SERVICE_URL='https://testnet.token-service.neozip.io'
+```
+
+---
+
+## Interactive wizard
+
+Run **`neozip-connect`** with no subcommand (or `neozip-connect wizard`) for the interactive flow:
+
+1. Choose a Token Service deployment
+2. Register and verify email (6-digit OTP)
+3. Create or import a Data Wallet
+4. Link the wallet and provision the X25519 identity
+
+The Token Service step offers:
+
+1. NeoZip Testnet (`https://testnet.token-service.neozip.io`) — default
+2. NeoZip Production (`https://token-service.neozip.io`)
+3. Local Development (`http://localhost:14789`)
+4. Custom URL
+
+When you choose **Create new wallet**, the wizard shows your **recovery phrase once** and asks you to confirm you have saved it before continuing.
+
+After a verification code is sent, enter the **6-digit code** at the prompt. Type **`r`** to resend, **`c`** to change email, or **`a`** to abort setup.
+
+When an account is already set up, the wizard shows account status and asks whether to finish, add another account on the same or a different Token Service, delete an account, switch the active account (when multiple are saved), or **show connection JSON** (manifest + `public.json`, no secrets).
+
+If adding an account fails (e.g. local Token Service not running), the wizard **rolls back** to your previous ready account and removes the incomplete shell. If you still have an incomplete account active, the wizard offers **continue / delete / switch to ready** instead of exiting.
+
+---
+
+## Commands
+
+All subcommands support `--json` for machine-readable stdout. Errors go to stderr; exit code is non-zero on failure.
+
+| Command | Purpose |
+|---------|---------|
+| `neozip-connect` | Interactive wizard (default) |
+| `neozip-connect wizard` | Same as no subcommand |
+| `neozip-connect status [--verbose]` | Phase, paths; `--verbose` lists all saved accounts |
+| `neozip-connect select --connection-id ID` | Set active connection |
+| `neozip-connect rename --label NAME [--connection-id ID]` | Rename a saved connection |
+| `neozip-connect dump [--connection-id ID]` | Print manifest + all `public.json` files as JSON |
+| `neozip-connect register --email user@example.com [--resend]` | Send email OTP (`verificationDelivery: cli`, code only) |
+| `neozip-connect verify --email user@example.com --code 123456` | Verify email → store Bearer in `secrets.enc` |
+| `neozip-connect verify --magic-token LINK_OR_TOKEN` | Verify via pasted magic link URL, `email=…&code=…`, or opaque token |
+| `neozip-connect phone request --phone +14155551234` | Send SMS OTP (when Token Service requires phone verification) |
+| `neozip-connect phone verify --phone +14155551234 --code 123456` | Verify phone → store verified phone on connection |
+| `neozip-connect wallet create --ack-backup` | Generate EOA (requires backup acknowledgment) |
+| `neozip-connect wallet import-mnemonic --mnemonic "…"` | Import wallet from recovery phrase |
+| `neozip-connect wallet import-key --private-key 0x…` | Import wallet from private key |
+| `neozip-connect finish [--create-wallet]` | Link wallet + identity init (does not auto-create wallet unless `--create-wallet`) |
+| `neozip-connect setup --email … --code …` | Verify + finish when code is already known |
+| `neozip-connect logout` | Clear secrets for active connection |
+| `neozip-connect delete [--connection-id ID]` | Remove a saved account from disk |
+| `neozip-connect migrate` | Import legacy `~/.neozip/mcp/` profiles |
+| `neozip-connect reset --force` | Delete connection + legacy profile dirs (start over) |
+
+Reset locally:
+
+```bash
+pnpm connect:reset --force
+# or: bash scripts/connect-reset.sh --force
+```
+
+Global flags:
+
+- `--token-service-url URL` — override Token Service base URL
+- `--label NAME` — optional override for the saved connection display name (interactive wizard derives this from the deployment choice)
+- `--verbose` / `-v` — on `status`, include per-account details (label, email, phase, active marker)
+- `--resend` — on `register`, re-send the email verification code
+- `--magic-token` — on `verify`, accept a full magic link URL, `email=…&code=…` query string, or opaque exchange token
+- `--connection-id ID` — target a specific saved connection (`select`, `rename`, `delete`, `dump`)
+
+---
+
+## AI / agent flow
+
+1. `neozip-connect register --email user@example.com --json`
+2. User pastes OTP from email into chat (or full magic link via `verify --magic-token …`)
+3. `neozip-connect verify --email user@example.com --code 123456 --json`
+4. `neozip-connect wallet create --ack-backup --json` (or import-mnemonic / import-key)
+5. `neozip-connect finish --json`
+6. User reloads MCP in Cursor Settings
+
+Or single step when the code is known:
+
+```bash
+neozip-connect setup --email user@example.com --code 123456 --json
+```
+
+### JSON response shape
+
+```json
+{
+  "success": true,
+  "phase": "awaiting_code",
+  "connectionId": "uuid",
+  "tokenServiceOrigin": "https://testnet.token-service.neozip.io",
+  "nextCommand": "neozip-connect verify --email user@example.com --code 123456",
+  "message": "Verification code sent."
+}
+```
+
+No Bearer tokens or private keys appear in CLI output.
+
+---
+
+## Migration from `~/.neozip/mcp/`
+
+Legacy MCP-only profiles are imported automatically on first `neozip-connect status`, or manually:
+
+```bash
+neozip-connect migrate --json
+```
+
+---
+
+## Development
+
+```bash
+pnpm connect status --json
+pnpm connect register --email you@example.com --json
+```
+
+Interactive wizard (deprecated): `pnpm init` / `bash scripts/mcp-init.sh` (delegates to the same flow as bare `neozip-connect`).