mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-26 09:52:11 +03:00
Merge PR #2280: feat(cli): CLI v4 — Commander.js, 50+ commands, TUI, i18n, plugins (Phases 0-9)
Complete rewrite of the OmniRoute CLI: - Commander.js-based modular architecture (50+ command files) - Full i18n support (en + pt-BR, 1222 keys each) - TUI interactive interface (OAuthFlow, EvalWatch, ProvidersTestAll) - Plugin system (omniroute-cmd-*) - OpenAPI codegen (omniroute api <tag> <op>) - Commands: serve, combo, compression, keys, tunnel, backup, test-provider, health, memory, MCP, A2A, oauth, skills, webhooks, usage, cost, eval, context-eng, dashboard, doctor, env, files, logs, models, nodes, oneproxy, open, openapi, plugin, policy, pricing, providers, quota, registry, repl, reset-encrypted-columns, resilience, restart, runtime, sessions, setup, simulate, status, stop, stream, sync, tags, telemetry, translator, tray, update - Code review fixes: C1-C3, I1-I5, M1-M4 applied # Conflicts: # bin/cli/commands/config.mjs # bin/omniroute.mjs # package-lock.json # package.json
This commit is contained in:
43
docs/security/CLI_TOKEN_AUTH.md
Normal file
43
docs/security/CLI_TOKEN_AUTH.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# CLI Machine-ID Token Authentication
|
||||
|
||||
OmniRoute's CLI uses a **machine-derived token** to authenticate to the local server without requiring an explicit API key. This enables zero-config local use while preserving security for remote access.
|
||||
|
||||
## How it works
|
||||
|
||||
1. **CLI side** (`bin/cli/utils/cliToken.mjs`): computes `SHA-256(machineId + salt).hex[0..32]` using [`node-machine-id`](https://github.com/automation-stack/node-machine-id) and injects the result as the `x-omniroute-cli-token` header on every `apiFetch` call.
|
||||
|
||||
2. **Server side** (`src/lib/middleware/cliTokenAuth.ts`): `isCliTokenAuthValid(request)` accepts the token only if:
|
||||
- `OMNIROUTE_DISABLE_CLI_TOKEN` is not `"true"`
|
||||
- The header is present and exactly 32 hex characters
|
||||
- The originating IP is loopback (`127.0.0.1`, `::1`, `::ffff:127.0.0.1`)
|
||||
- The token matches the server's own machine-derived hash (timing-safe compare)
|
||||
|
||||
3. `requireManagementAuth` and other route guards call `isCliTokenAuthValid` before checking API keys — so the CLI gets transparent localhost access without storing any credential.
|
||||
|
||||
## Threat model
|
||||
|
||||
| Scenario | Risk | Mitigation |
|
||||
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Another user on same host | Could compute the same token | `machine-id` is per-device; on single-user desktops this is acceptable. Use `OMNIROUTE_DISABLE_CLI_TOKEN=true` in multi-user setups. |
|
||||
| Token leak via logs | Logs may reveal the token | The header value is masked in audit logs (`x-omniroute-cli-token: ***`). |
|
||||
| Replay attack | Token is static | Only accepted from `127.0.0.1`/`::1`. Rejected for any other `x-forwarded-for` IP. |
|
||||
| Reuse on another machine | Machine-bound by design | `node-machine-id` reads `/etc/machine-id` (Linux), `IOPlatformUUID` (macOS), `MachineGuid` (Windows). Different per host. |
|
||||
|
||||
## Opt-out
|
||||
|
||||
Set `OMNIROUTE_DISABLE_CLI_TOKEN=true` in `.env` or the server environment to disable this mechanism entirely. All access then requires an explicit API key.
|
||||
|
||||
## Audit logging
|
||||
|
||||
Every request authenticated via CLI token is logged with `event: "cli_token_auth"`, the source IP, user-agent, path, and the first 8 characters of the machine-id hash (non-reversible).
|
||||
|
||||
## API key precedence
|
||||
|
||||
An explicit `Authorization: Bearer <key>` header (from `--api-key` or `OMNIROUTE_API_KEY`) always takes precedence over the CLI token and is evaluated first.
|
||||
|
||||
## Related files
|
||||
|
||||
- `bin/cli/utils/cliToken.mjs` — CLI token generation
|
||||
- `src/lib/middleware/cliTokenAuth.ts` — server validation
|
||||
- `src/lib/api/requireManagementAuth.ts` — integration into auth pipeline
|
||||
- `tests/unit/cli-machine-token.test.ts` — unit tests
|
||||
Reference in New Issue
Block a user