keysink 0.1.4 → 0.2.0

package/README.md

@@ -33,10 +33,10 @@ the others keep working.
 
 **Retries that don't double-bill.** `429`/`503`/`504` are retried twice, but a
 POST whose network call failed is never replayed, and nothing is retried once SSE
-streaming has started. Most naive proxies get this wrong and you pay for it twice.
+streaming has started. A replayed POST is a second charge on your bill.
 
-And the part it's named after: an agent that gets prompt-injected can leak
-everything in its environment — but the real key was never in there.
+And the name: a prompt-injected agent can dump everything in its environment, and
+the real key was never in it.
 
 ## Quick start
 
@@ -47,11 +47,15 @@ everything in its environment — but the real key was never in there.
    cargo install keysink      # from crates.io, needs a Rust toolchain
    ```
 
+   `cargo install` lands in `~/.cargo/bin`, which sudo can't see. So if you later
+   run `sudo keysink deploy`, use `sudo ~/.cargo/bin/keysink deploy`.
+
    Prebuilt binaries are also on
    [Releases](https://github.com/wusende/keysink/releases) — Linux / macOS /
    Windows, amd64 / arm64 — put one on your `PATH`. The npm package is a thin
-   launcher around that same binary; Linux x64 needs glibc 2.35+, and anything
-   uncovered (musl/Alpine, Windows arm64) falls back to `cargo install`.
+   launcher around that same binary; Linux x86_64 needs glibc 2.35+, arm64 needs
+   2.39+, and anything uncovered (musl/Alpine, Windows arm64) falls back to
+   `cargo install`.
 
 2. Start the gateway (standalone mode — no root, no service):
 
@@ -68,8 +72,21 @@ everything in its environment — but the real key was never in there.
    # non-interactive: printf %s "$KEY" | keysink route add claude --base-url … --auth x-api-key
    ```
 
-   It prints the two lines your agent needs. Routes hot-reload into a running
-   gateway within ~1s, so adding one never requires a restart.
+   It prints the vkey and the two lines your agent needs:
+
+   ```
+   route `claude` created (key goes in, never out: cannot be read/exported)
+   auth: x-api-key    base_url: https://api.anthropic.com
+   vkey: ks_R6OpUgxRjVnuCwISI0_BgtAi1E8FGUILJHQouA50tYc
+   (vkey is shown only this once; if lost, only `keysink route rotate claude` can issue a new one)
+   gateway: http://127.0.0.1:8787 (running)
+   agent-side config (OpenAI-compatible clients usually need /v1 in base_url):
+     BASE_URL=http://127.0.0.1:8787
+     TOKEN=ks_R6OpUgxRjVnuCwISI0_BgtAi1E8FGUILJHQouA50tYc
+   ```
+
+   Routes hot-reload into a running gateway within ~1s, so adding one never
+   requires a restart.
 
 4. Point your agent at it:
 
@@ -83,8 +100,7 @@ everything in its environment — but the real key was never in there.
 
    The vkey rides in whatever header your client already sends — `Authorization:
    Bearer`, `x-api-key`, `x-goog-api-key` or `api-key` — so for most clients this
-   is a base-URL change and nothing else. Your existing client code, SDK and auth
-   flow stay untouched.
+   is a base-URL change and nothing else.
 
 ## How routing works
 
@@ -99,9 +115,12 @@ never smuggle its own credentials through. Everything else — method, path, bod
 preserved with the auth parameter managed by the route. SSE chunks are forwarded
 as they arrive instead of being buffered into a whole response.
 
-Because the vkey picks the route, "which upstream does this agent talk to" is a
-keysink-side decision, not a client-side one. Two agents on the same port can
-talk to two different providers, or to the same provider with different keys.
+`--auth` describes keysink → upstream only. Inbound, the vkey is accepted in any
+of `Authorization: Bearer`, `x-api-key`, `x-goog-api-key` or `api-key`, so the
+client's auth style and the route's never have to match.
+
+Two agents on the same port can talk to two different providers, or to the same
+provider with different keys, without either of them knowing.
 
 ## Everyday commands
 
@@ -124,6 +143,36 @@ Route options worth knowing:
   a per-route upstream proxy, defaulting to `HTTP(S)_PROXY`
 - `--retry-on-status CODE` overrides the retryable set per route (400..=599)
 
+Common moves:
+
+```bash
+keysink route update claude --base-url https://api.openai.com     # switch upstream
+printf %s "$NEW_KEY" | keysink route update claude --route-key -   # swap the real key
+keysink route rotate claude                                       # new vkey, old one stops working
+```
+
+`status` prints the vault summary (home, schema, route count). `doctor` runs the
+integrity checks — owner, permissions, key parses, store decrypts, backup
+decrypts — and is what to run when something looks wrong.
+
+To check the gateway itself, `GET /__keysink/health` returns
+`{"ok":true,"degraded":false,"version":"0.2.0","uptime_secs":…,"routes":2}`,
+plus the state that used to be invisible: `snapshot_age_secs` (how long the
+served snapshot has been in place — the watcher only reloads on vault changes,
+so on a stable vault this grows with uptime; it reports data freshness, not
+watcher health, so don't alert on it), `reload_failures` / `reload_attempts`
+(the actual reload signals: failures climbs while the vault stays broken, e.g.
+undecryptable), `shed_connections` / `accept_errors` (connection-cap and
+per-connection accept-error counts), and `audit` / `audit_ok` /
+`audit_dropped` (a dead audit writer reports `audit_ok:false` instead of
+silently dropping every line).
+
+`--accept-degraded` covers a broken vault: when the primary store fails to
+decrypt, the gateway can start from `vault.age.bak` instead. That backup is one
+write behind, so vkeys rotated or deleted since then work again — a stopgap to
+keep agents running, not a state to stay in. `doctor` tells you which file is
+bad and how to restore it.
+
 ## Where the vault lives
 
 `~/.local/share/keysink` (Windows: `%LOCALAPPDATA%\keysink`; system installs:
@@ -133,6 +182,12 @@ The master password is only used to encrypt and restore `export` backups —
 serving, adding, rotating and disabling keys never ask for it, so a daemon
 restart can't be blocked by a forgotten password.
 
+`vault.key` is a plain age identity file (`0600`), not something the master
+password protects: the vault's protection is file mode plus a separate UID. For
+services, the identity can live outside the vault directory — `KEYSINK_MASTER_KEY`
+(inline age identity) or `KEYSINK_MASTER_KEY_FILE` (path to one), which is what
+systemd's `LoadCredential` wants.
+
 ## Linux system service
 
 ```bash
@@ -145,15 +200,23 @@ binary to `/usr/local/bin/keysink`, writes the systemd unit and the sudoers rule
 password, entered twice), then enables the service. Idempotent — re-running
 upgrades in place and restarts. Removal is symmetric: `sudo keysink uninstall`.
 
-The unit refuses to start until the vault exists (`ConditionPathExists`). Without
-a terminal, init manually:
+The unit refuses to start until the vault exists (`ConditionPathExists`). With no
+terminal on the deploy host, init manually — interactively:
 
 ```bash
-runuser -u keysink -- /usr/local/bin/keysink --home /var/lib/keysink init
+sudo -u keysink /usr/local/bin/keysink --home /var/lib/keysink init
 ```
 
-Admin commands then go through `sudo -u keysink keysink …`; each invocation
-re-authenticates (`timestamp_timeout=0`), so an agent cannot silently run them.
+or fully headless (`init` refuses to prompt without a TTY, so pipe the password):
+
+```bash
+printf '%s\n' "$MASTER_PASSWORD" | sudo -u keysink /usr/local/bin/keysink \
+  --home /var/lib/keysink init --password-stdin
+```
+
+Admin commands then go through `sudo -u keysink /usr/local/bin/keysink …`; each
+invocation re-authenticates (`timestamp_timeout=0`), so an agent cannot silently
+run them.
 
 ## Security model
 
@@ -178,11 +241,23 @@ of unauthenticated requests cannot rotate the forensic trail away.
 
 `--listen` will bind a non-loopback address if you insist, but then TLS and
 network exposure are yours to solve; the intended deployment is loopback only.
-Everything a request touches is bounded by default — body size, in-flight
-requests, connections, time — so a hung upstream or a misbehaving agent can't
-take the gateway down. Idle connections are bounded too: http1 heads must
-finish within 30s, and h2 connections that stop answering keep-alive PINGs
-are closed.
+
+Nothing is unbounded: 32 MB bodies (`--body-limit-mb`), 64 in-flight requests
+(`--max-concurrent`), a capped connection count, per-phase timeouts, and 30s to
+finish reading http1 request heads. A non-streaming response body is bounded
+both per chunk and as a whole, so an upstream that trickles a byte a minute
+cannot hold a connection forever. An h2 connection that stops answering
+keep-alive PINGs is closed. A hung upstream or a misbehaving agent can't take
+the gateway down.
+
+Shutdown is graceful and bounded: `serve` stops accepting, tells every live
+connection to finish and close (`Connection: close`, h2 `GOAWAY`), and drains
+for at most `--drain-timeout-secs` (default 10, `0` = wait forever) before
+dropping what is left with a warning. Idle keep-alive sockets close
+immediately, so a restart no longer waits out a 30s header timeout; the
+systemd unit's `TimeoutStopSec=30` is the backstop above that. The store
+watcher is supervised too: if it dies it is restarted, and if it stops ticking
+the log says so.
 
 ## What this is not
 
@@ -198,23 +273,30 @@ are closed.
 
 **Why isn't the vault in the current directory?**
 
-- **One vault per user, not per directory.** The gateway runs as a daemon while
-  the CLI is invoked from anywhere; a CWD-relative vault would mean a different
-  vault per directory, routes would "vanish", and hot reload would break. Use
-  `--home` / `KEYSINK_VAULT_HOME` when you want another location.
-- **The hardening needs a directory it controls.** `0700`/`0600`,
-  `O_NOFOLLOW` and owner checks only mean something in a dedicated directory.
-  CWD has arbitrary permissions and may well be a git repo or a synced folder
-  where `vault.key` + `vault.age` leak.
-- **It's where the OS expects app data** — XDG `$XDG_DATA_HOME`,
-  `%LOCALAPPDATA%`, `/var/lib` for services. Same convention as `~/.ssh`,
-  `~/.gnupg` or `/var/lib/docker`.
+One vault per user, not per directory. The gateway runs as a daemon while the CLI
+is invoked from anywhere, so a CWD-relative vault would mean a different vault
+per directory, routes that "vanish", and broken hot reload. The hardening needs
+a directory it controls too: `0700`/`0600`, `O_NOFOLLOW` and owner checks only
+mean something in a dedicated directory, while a CWD may well be a git repo or a
+synced folder where `vault.key` + `vault.age` leak. It is also where the OS
+expects app data (XDG `$XDG_DATA_HOME`, `%LOCALAPPDATA%`, `/var/lib` for
+services — same convention as `~/.ssh` or `/var/lib/docker`). Use `--home` /
+`KEYSINK_VAULT_HOME` when you want another location.
 
 **Is a local proxy a single point of failure?**
 
-It's a local process, so yes — if it's down, requests fail. `keysink status`
-reports the live listen address and probes reachability, and under systemd the
-unit restarts on failure. The vault is plain files, so a crash never loses keys.
+It's a local process, so yes — if it's down, requests fail. `GET
+/__keysink/health` says whether it's up and whether it's serving a stale backup;
+under systemd the unit restarts on failure. The vault is plain files, so a crash
+never loses keys.
+
+**My agent gets 401 — is the vkey wrong or the real key?**
+
+keysink's own 401 has a JSON body from keysink and an `x-keysink-request-id`
+header, e.g. `{"error":{"type":"authentication_error","message":"virtual key is
+invalid or has been rotated …"}}`. A bad *real* key comes back from the upstream
+instead — same status, but the body is the provider's own error, and the request
+never reached the vault.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keysink",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Local gateway that keeps real AI API keys out of agents (Claude Code, OpenAI, MCP): agents hold revocable virtual keys, real keys stay in an encrypted vault.",
   "license": "MIT",
   "author": "wusende",