@keyboxed/cli 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,12 +9,18 @@ npm install -g @keyboxed/cli
9
9
  npx wrangler login
10
10
  keybox init
11
11
 
12
- keybox secrets add OPENAI_API_KEY
12
+ keybox migrate # from .env, 1Password, Bitwarden, Doppler, Infisical, Vault, sops, AWS, GCP…
13
+ keybox secrets add OPENAI_API_KEY # or type/paste one; it is never echoed
13
14
  keybox agents create writer --allow "POST api.openai.com/v1/responses"
14
15
  keybox run writer -- python agent.py
15
16
  keybox audit --follow
16
17
  ```
17
18
 
19
+ - `keybox ui` opens the dashboard on your own Worker with a one-time login link. Keys are write-only there too.
20
+ - `keybox tui` is a live console in the terminal.
21
+ - `keybox access` limits who can reach your Keybox by IP range, country or Cloudflare Access.
22
+ - `keybox skill install` teaches Claude Code, Codex and other agents to set Keybox up without ever reading a key.
23
+
18
24
  Calls that would mint a new key or grant lasting access (OpenAI admin keys, GitHub deploy keys and collaborators, Cloudflare API tokens, and others) are always blocked. See them with `keybox blocked`.
19
25
 
20
26
  Read the [security model](https://keybox.space/docs/security-model) before storing production keys. It also covers what Keybox does not protect against, such as an agent running as your user being able to read your Keybox admin token.
package/assets/schema.sql CHANGED
@@ -4,3 +4,6 @@ CREATE TABLE IF NOT EXISTS tokens (id TEXT PRIMARY KEY, agent TEXT NOT NULL, has
4
4
  CREATE INDEX IF NOT EXISTS tokens_agent ON tokens (agent);
5
5
  CREATE TABLE IF NOT EXISTS audit (id INTEGER PRIMARY KEY AUTOINCREMENT, ts INTEGER NOT NULL, agent TEXT, token_id TEXT, method TEXT NOT NULL, host TEXT, path TEXT, secret TEXT, decision TEXT NOT NULL, reason TEXT, status INTEGER NOT NULL);
6
6
  CREATE INDEX IF NOT EXISTS audit_ts ON audit (ts);
7
+ CREATE INDEX IF NOT EXISTS audit_secret ON audit (secret, ts);
8
+ CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at INTEGER NOT NULL);
9
+ CREATE TABLE IF NOT EXISTS sessions (hash TEXT PRIMARY KEY, kind TEXT NOT NULL, expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL);
@@ -0,0 +1,173 @@
1
+ ---
2
+ name: keybox
3
+ description: Set up and use Keybox, which lets AI agents call APIs without holding the API keys. Use when the user asks to set up Keybox, move or migrate API keys out of .env files or a password manager (1Password, Bitwarden, Doppler, Infisical, Vault, sops, AWS or Google secret managers), give an agent or script scoped API access, wire a project to run through `keybox run`, lock down who can reach their Keybox, or debug a Keybox error such as not_allowed, blocked or network_denied.
4
+ ---
5
+
6
+ # Keybox
7
+
8
+ Keybox is a Cloudflare Worker that the user deploys to **their own** Cloudflare account. It holds their API keys, encrypted. Agents get a Keybox token (`kb_agt_…`) instead of a key. When an agent calls `https://<keybox>/<api host>/<path>`, Keybox checks the agent's rules, attaches the real key, forwards the call, and scrubs the key from the response. Calls that would mint new keys or grant lasting access are always refused.
9
+
10
+ You are probably one of the agents Keybox exists to protect against. Act like it: the point is that **no key value ever enters your context**.
11
+
12
+ Docs: https://keybox.space/docs
13
+
14
+ ## Hard rules
15
+
16
+ 1. **Never see a key value.** Do not `cat`, `grep`, `head`, `source` or open `.env` files or anything that may hold a credential. To see what a file holds, list names only: `cut -d= -f1 .env`. Do not print environment variables (`env`, `printenv`, `echo $X`).
17
+ 2. **Never put a key on a command line.** Values go in only through `keybox migrate`, `keybox secrets add` (hidden prompt, pipe, or `--from` reference), or the dashboard. Never write `keybox secrets add X <<< "sk-…"` with a value you typed.
18
+ 3. **Never read `~/.config/keybox/config.json`.** It holds the admin token.
19
+ 4. **Ask before** you change the user's Cloudflare account, edit a file that holds secrets, delete anything, or widen access. Show the exact command first.
20
+ 5. **Do not work around a refusal.** If Keybox returns `blocked`, `not_allowed` or `network_denied`, report it and propose a narrower rule. Never suggest putting the key back in the environment to "make it work".
21
+ 6. **Do not run `keybox ui --print`** or open login links yourself. Ask the user to run `keybox ui`.
22
+ 7. Secret values are write-only by design. There is no way to read one back, and you should not look for one.
23
+
24
+ ## How to talk to the user
25
+
26
+ - Start by saying what Keybox will do in one or two sentences, and what you will need from them (a Cloudflare login in their browser, and possibly a password-manager unlock).
27
+ - Before each step that changes something, show the command and wait for a yes.
28
+ - Report key **names**, providers and hosts. Never values, never prefixes beyond what `keybox` itself prints.
29
+ - When a key is admin-grade (OpenAI `sk-admin-`, Anthropic admin, GitHub classic `ghp_`, Stripe `sk_live_`), say so and recommend a narrower key. Keybox blocks key-minting endpoints either way.
30
+ - Finish with: what changed, which keys Keybox now holds (names only), what the user must still do themselves (rotate keys that sat in plaintext, delete the old copies).
31
+
32
+ ## 1. Check
33
+
34
+ ```bash
35
+ node --version # needs 20+
36
+ keybox --version # if missing: npm install -g @keyboxed/cli
37
+ keybox status # if this reports a Keybox, skip to step 3
38
+ ```
39
+
40
+ ## 2. Deploy (once per account)
41
+
42
+ ```bash
43
+ npx wrangler whoami # if not logged in, ask the USER to run: npx wrangler login
44
+ keybox init --account <account id> --yes # creates a Worker + D1 database named "keybox"
45
+ ```
46
+
47
+ `keybox init` lists the Cloudflare accounts the login can reach. If there is more than one, **ask the user which account** and pass `--account`; never pick one yourself. Without a terminal it needs `--yes`, so show the user the command first. It ends by verifying the deployment. Tell the user the URL it prints. Do not read the config file it writes.
48
+
49
+ ## 3. Find the keys (names only)
50
+
51
+ Search the project for credentials by **name**: `.env*` (names only), `docker-compose*`, CI config, deploy config, and code reading `process.env.X`, `os.environ["X"]`, `Deno.env.get("X")`, etc. Build a table: variable, where it is used, which API host it talks to. Do not open values.
52
+
53
+ Ask the user where each key lives today.
54
+
55
+ ## 4. Migrate
56
+
57
+ Prefer `keybox migrate`. It reads values itself, shows a table of names and hosts, and never prints values. Always do a dry run first and show the user the table.
58
+
59
+ | Keys live in | Command |
60
+ | --- | --- |
61
+ | A `.env` file | `keybox migrate --from dotenv:.env --dry-run`, then without `--dry-run` |
62
+ | 1Password | `keybox migrate --from 1password --vault "<vault>" --dry-run` (uses the `op` CLI; the user may need to approve Touch ID) |
63
+ | Bitwarden | user runs `bw unlock` and exports `BW_SESSION` themselves; then `keybox migrate --from bitwarden --item <search>` |
64
+ | Bitwarden Secrets Manager | `keybox migrate --from bws --project <id>` (needs `BWS_ACCESS_TOKEN` set by the user) |
65
+ | Doppler | `keybox migrate --from doppler --project <p> --config <c>` |
66
+ | Infisical | `keybox migrate --from infisical --env <env> --path /` |
67
+ | HashiCorp Vault KV | `keybox migrate --from vault:secret/<path>` |
68
+ | sops | `keybox migrate --from sops:<file>` |
69
+ | AWS Secrets Manager | `keybox migrate --from aws:<secret-id>` |
70
+ | Google Secret Manager | `keybox migrate --from gcp --project <p>` |
71
+ | pass / macOS Keychain | `keybox migrate --from pass --item <path>` / `--from keychain --item "<service>"` |
72
+ | Current shell env | `keybox migrate --from env` |
73
+ | One key from a manager | `keybox secrets add NAME --from op://vault/item/field` (also `vault://path#field`, `doppler://project/config/NAME`, `aws-sm://id#key`, `gcp-sm://project/secret`, `bws://<id>`, `pass://path`, `keychain://service`, `sops://file#KEY`, `env://VAR`) |
74
+ | The user will type it | tell them to run `keybox secrets add NAME` in **their own** terminal |
75
+ | GitHub Actions secrets | cannot be read back by anyone. The user copies each from its source or rotates it. |
76
+
77
+ Running `keybox migrate` with no `--from` in a real terminal shows a picker of the sources it found. You usually do not have a real terminal, so pass `--from`.
78
+
79
+ Keys Keybox does not recognise are skipped with a reason. For a custom API:
80
+
81
+ ```bash
82
+ keybox secrets add NAME --host api.example.com --header authorization --format bearer # or --format raw for x-api-key style
83
+ ```
84
+
85
+ Keybox cannot proxy AWS SigV4 credentials, database URLs, or keys your own code uses for signing (JWT secrets, private keys). Leave those where they are and say so.
86
+
87
+ ## 5. Create agents with the narrowest rules
88
+
89
+ One agent per program, script or bot. Read its code to see which endpoints it really calls, then allow only those:
90
+
91
+ ```bash
92
+ keybox agents create writer \
93
+ --allow "POST api.openai.com/v1/responses" \
94
+ --allow "GET api.github.com/repos/acme/site/**" \
95
+ --deny "* api.github.com/repos/acme/site/actions/**"
96
+ ```
97
+
98
+ - Rule format: `METHOD host/path`. `*` is one path segment, `**` is any number. Methods can be `GET,POST` or `*`.
99
+ - If two keys share a host, prefix the rule: `GITHUB_BOT=GET api.github.com/**`.
100
+ - Deny rules win and ignore case. Allow rules match exactly.
101
+ - Do not use `* host/**` unless the user asks for it.
102
+ - Show the rules to the user before creating the agent.
103
+
104
+ ## 6. Wire the project
105
+
106
+ ```bash
107
+ keybox run writer -- node server.js
108
+ ```
109
+
110
+ `keybox run` mints a short-lived token, removes known key variables from the child's environment, and sets `KEYBOX_URL` and `KEYBOX_TOKEN`. For OpenAI and Anthropic it also sets `OPENAI_BASE_URL`/`OPENAI_API_KEY` and `ANTHROPIC_BASE_URL`/`ANTHROPIC_API_KEY`, so SDK code needs no change. For other APIs, point the base URL at `$KEYBOX_URL/<api host>` and send `$KEYBOX_TOKEN` where the API key used to go.
111
+
112
+ Update `package.json` scripts, Makefiles, compose files and the README to start through `keybox run`.
113
+
114
+ For servers and CI: `keybox agents token NAME --ttl 30d` prints a token once. The **user** stores it in that platform's secret store. Do not paste it into files.
115
+
116
+ ## 7. Verify
117
+
118
+ ```bash
119
+ keybox run writer -- npm test
120
+ keybox audit --limit 20
121
+ ```
122
+
123
+ Confirm the expected calls show as allowed and nothing is refused by mistake. Common refusals:
124
+
125
+ | Code | Meaning | What to do |
126
+ | --- | --- | --- |
127
+ | `not_allowed` | No rule allows this method/host/path | Propose the narrowest rule that covers it; ask first |
128
+ | `blocked` | Built-in list: the call would mint a key or grant access | Explain; there is no override |
129
+ | `network_denied` | The caller's IP or country is outside the access rules | Show `keybox access`; let the user decide |
130
+ | `ambiguous_secret` | Several keys could apply | Send header `x-keybox-secret: NAME` or prefix rules |
131
+ | `invalid_token` | Token expired or revoked | Re-run through `keybox run` or mint a new token |
132
+
133
+ ## 8. Lock it down (optional, ask first)
134
+
135
+ ```bash
136
+ keybox access # current rules and the caller's IP
137
+ keybox access set --scope proxy --allow-ip 203.0.113.0/24 # only these networks may use agent tokens
138
+ keybox access set --scope agent:ci --allow-ip <CI egress range>
139
+ keybox access set --scope admin --allow-country US --deny-country T1
140
+ keybox access cloudflare --team <team>.cloudflareaccess.com --aud <AUD tag> # SSO for the dashboard
141
+ ```
142
+
143
+ Keybox refuses an admin rule that would lock out the caller unless `--force` is given. Never pass `--force` without the user's explicit go-ahead.
144
+
145
+ ## 9. Verify and keep it current
146
+
147
+ ```bash
148
+ keybox verify # asks Cloudflare what is actually deployed and checks it is exactly this CLI's code
149
+ keybox update --check # is there a newer CLI, and does the Worker match this one?
150
+ keybox update # updates the CLI, redeploys the Worker, verifies (asks before each step)
151
+ ```
152
+
153
+ - Run `keybox verify` after setup, after every deploy or update, and whenever the user is unsure whether anyone else changed their Cloudflare account. It exits non-zero on a mismatch.
154
+ - If `verify` reports that the code does not match and the user did not just upgrade on another machine, treat it as an incident. Tell the user plainly that the stored keys may be exposed, that they should rotate them at each provider, secure the Cloudflare account, and then run `keybox deploy`. Do not run `keybox deploy` yourself to "fix" a mismatch before the user has read this.
155
+ - Never run `keybox update` or `keybox deploy` without the user's go-ahead. They replace the code that holds the keys.
156
+
157
+ ## 10. Clean up (ask first)
158
+
159
+ Only after the user confirms things work:
160
+
161
+ - Remove the migrated lines from `.env` (just those lines) and make sure `.env` is in `.gitignore`.
162
+ - Tell the user to **rotate** every key that sat in a plaintext file, since old values may have been copied elsewhere, then `keybox secrets add NAME` (or rotate in the dashboard) with the new value.
163
+ - Tell the user that any agent running as their OS user can read the Keybox admin token. For agents they do not fully trust, use a container or a separate user that only gets a `keybox agents token`.
164
+
165
+ ## What to tell the user about privacy
166
+
167
+ Keys are write-only: no Keybox API, dashboard, CLI, TUI or token returns a stored value, and keybox.space never sees them. The database holds only ciphertext; the decryption key is a Cloudflare Worker secret. The one way to read a key is to deploy different code to the user's Cloudflare account, which is what `keybox verify` checks for. Do not claim it is "impossible"; say it is write-only by design and verifiable.
168
+
169
+ ## Other entry points
170
+
171
+ - `keybox ui`: opens the web dashboard on the user's own Worker with a one-time link. Secrets are write-only there too.
172
+ - `keybox tui`: live console in the terminal (the Rust `keybox-tui` when installed).
173
+ - `keybox blocked`: the built-in list of calls Keybox never proxies.