subscribetome

# subscribetome

> Open-source API-key security for AI coding agents: keys live in your OS
> keychain, and a local credential broker injects them into outbound HTTP
> calls — so the agent uses your keys without ever seeing one. Distributed as
> a Claude Code plugin; the broker works with any HTTP-speaking agent.

subscribetome (CLI: `stm`) is an API-key security tool for AI-assisted coding,
built by Matterhorn Labs and distributed as a Claude Code plugin. It solves a
specific problem: an API key pasted into a chat is logged in that chat's
transcript forever. Even if you redact your copy, you cannot un-leak it from
any backup, screen-share, or shared session. Its credential broker (below) is
agent-agnostic — any client that speaks HTTP can use it, not just Claude Code.

The plugin keeps every key out of the conversation by design. Keys are entered
out-of-band in a localhost dashboard, stored in the macOS Keychain, and
referenced from chat by a placeholder like `{{stm:openai:default}}`. A Claude
Code `PreToolUse` hook substitutes the real key into the shell command the
instant before it runs — and never into the conversation.

Three other hooks back this up:
- `UserPromptSubmit` blocks any prompt that contains a raw key shape or any
  managed secret matched by exact value.
- `PostToolUse` flags command output that surfaces a managed key (e.g. a
  command that echoed its own input) so the user can rotate.
- `SessionStart` teaches every new Claude Code session how to use stm-managed
  keys, with no per-project setup.

The dashboard ships with 80+ services pre-configured (OpenAI, Anthropic,
Google Gemini, Groq, Mistral, OpenRouter, fal.ai, Replicate, ElevenLabs,
Supabase, Neon, MongoDB Atlas, Upstash Redis, Firebase, PlanetScale,
Vercel, Netlify, Railway, Cloudflare, AWS, Fly.io, DigitalOcean, Clerk,
Auth0, Stripe, Lemon Squeezy, Paddle, Resend, SendGrid, Postmark, Brevo,
Mailgun, Twilio, Slack, Telegram, Discord, Twitter/X, Typefully, Postiz,
Apollo, Clay, Tavily, Firecrawl, Exa, Parallel Web Systems, Sentry,
PostHog, GitHub, Linear, Notion) plus custom fields for anything else.
A "Browse services" card on the dashboard groups them by category
(AI, database, hosting, auth, payments, email, comms, social, sales,
search, monitoring, dev-tools) so a new user can discover what they
can wire up; clicking a tile opens that provider's API-keys page in a
new tab and pre-arms the Add keys form below.

The project is MIT-licensed, built on Bun, has zero runtime dependencies, and
runs entirely on the user's own machine. No backend. No telemetry. No
phone-home. The dashboard is bound to `127.0.0.1` with a per-run auth token
and a Host/Origin allowlist (DNS-rebinding defense).

All major desktop platforms are supported: macOS (Keychain via
security CLI), Linux desktop (Secret Service via libsecret/secret-tool),
Windows (Credential Manager via the Win32 wincred API called through
Bun FFI), and as of v0.6.0 Linux headless (tiered fallback: `pass`
+ GPG → encrypted-file with PBKDF2-SHA512 600k + AES-256-GCM, mode
0600, opt-in via STM_ALLOW_FILE_BACKEND=1). `stm doctor` reports
which tier is active and exactly what would need to change to reach
the next-stronger tier. The dashboard and `stm status` always show
which backend is active. Encrypted-file passphrase UX:
`stm vault unlock` caches it for the process, `STM_FILE_PASSPHRASE`
works in CI, non-TTY without either makes the hook fail safe (returns
null instead of leaking).

Two agents are wrapped (Claude Code and OpenAI Codex), and as of v0.7.0 Codex now has both a session-env mode (Option 1) and a higher-assurance MCP-wrapped mode (Option 2) where the key never enters the agent's process at all.
**Claude Code** gets the strong "per-command rewrite" guarantee: the
real key is substituted into one Bash command at the moment it runs
via a `PreToolUse` hook returning `updatedInput`, and the transcript
keeps the placeholder. **Codex** (the OpenAI Codex CLI) is wrapped via
`stm codex [args...]`, which exposes each key as a `STM_<TOOL>_<LABEL>`
environment variable in codex's process for the whole session — a
weaker guarantee, because a command that dumps its environment can
surface it. Codex's hook system today rejects `updatedInput` (it is
"parsed but not supported yet, fails open"), so per-command rewrite
on Codex is not yet possible; tracking openai/codex#18491. The
trade-off is shown verbatim in `stm status`, the launcher banner,
the dashboard header, and the README — never hidden.

The `UserPromptSubmit` and `SessionStart` guardrails ported to
Codex in v0.4.1 via `stm codex install-hooks`, which writes a
marker-delimited managed block to `~/.codex/config.toml` using
Codex's array-of-tables hook schema (`[[hooks.UserPromptSubmit]]`
+ `[[hooks.UserPromptSubmit.hooks]]`). The installer is idempotent
and surgical — surrounding user config is preserved. `stm codex
doctor` verifies the wiring. First launch after install prompts
the user to TRUST each hook; until approved, the hook is silently
skipped (Codex behaviour, surfaced honestly).

Codex Option 2 (MCP-wrapped) shipped in v0.7.0 via `stm codex
install-mcp`, which writes an `[mcp_servers.subscribetome]` block
to the same `~/.codex/config.toml` (separate marker pair from the
hooks block, so the two installers are independent). Codex spawns
`stm codex mcp-server` over stdio; the agent gets a discoverable
tool `stm_http_request(provider, path, method?, query?, headers?,
body?)`. The credential value never enters the agent's address
space — it is read from the local stm KeyStore at the moment of
each call and used to populate the auth header on the outbound
HTTPS request. v0.7.0 launch set: OpenAI, Anthropic, Stripe,
GitHub, Resend. Adding a provider is one entry in
`src/agents/codex-mcp-providers.ts`.

The **credential broker** removes the argv limitation for HTTP APIs.
Instead of substituting a key INTO a shell command, the agent routes
the request through STM's local daemon, which injects the real auth on
the OUTBOUND call to the provider. `stm broker [tool] [label]` prints a
base URL and a loopback-only capability token; a request is made as
`curl http://127.0.0.1:<port>/proxy/<tool>/<label>/<upstream-path> -H
"x-stm-token: <broker-token>"`. STM resolves `<tool>:<label>` from the
keychain and attaches the real auth to the request it makes to the
provider, so the key never enters the command's argv, environment, or
output. The broker token authorizes `/proxy` only (it cannot read the
inventory or open the dashboard) and resets on daemon restart. Security
invariants: an SSRF guard keeps the key on the target's own origin;
redirects are not auto-followed (`redirect: manual`); the response body
and headers are scrubbed of the key; client-supplied auth for the
injected scheme is dropped; the response size is capped (16 MiB); every
brokered call is a `broker` audit event (method, path, status — never
the key). Built-in targets: openai, anthropic, groq, openrouter,
replicate, fal, stripe (a data-driven, extensible registry). Because
`/proxy` is plain HTTP, the broker works from ANY agent or client that can
set a base URL and send a header — the OpenAI SDKs, LangChain, LlamaIndex, a
plain script, or curl — not only Claude Code. The client is handed a
throwaway api key (the broker drops client auth for the injected scheme and
attaches the real key server-side); the loopback capability token travels in
the `x-stm-token` header or a `?token=` query param. See the "use the broker
from any agent" guide for copy-paste recipes.

**STM Teams** is self-hostable, zero-knowledge credential sharing plus
usage attribution across a team. A team hosts the server with
`stm teams serve`, configured by env: `STM_TEAM_DB`, `STM_TEAM_HOST`
(bind; `0.0.0.0` only behind a TLS reverse proxy), `STM_TEAM_PORT`, and
`STM_TEAM_ADMIN_TOKEN` (required to create teams — creation is disabled
when unset). The server stores only ciphertext it cannot decrypt and
keeps team bearer tokens as SHA-256 hashes. An admin creates a team with
`stm teams init --server <url> --admin <admin-token> --name <name>`
(generates the team key, self-enrolls, prints the team token).
Credentials are encrypted on a member's machine with the team key the
server never sees (vault: AES-256-GCM keyed by PBKDF2-SHA512);
`stm teams push` uploads the ciphertext and `stm teams pull` downloads
and decrypts it locally. Public-key enrollment needs no shared
passphrase: each member has an X25519 sealing key and an Ed25519 signing
key, and `memberId = sha256(sealPub||signPub)[:32]` (128-bit,
self-certifying). Flow: `stm teams join` → `stm teams enroll-request`
(publishes only public keys) → an existing member `stm teams enroll
<member-id>` (seals the team key to that member via an X25519 sealed box:
ephemeral ECDH → HKDF-SHA256 → AES-256-GCM; the CLI verifies the key set
matches the id before sealing) → `stm teams accept` → `stm teams pull`.
`stm teams quickstart` is the guided path over this flow: `quickstart create`
= init + a copy-paste invite; `quickstart join` = join + enroll-request in one
step (prints the member-id); `quickstart finish` = accept (fingerprint-verified)
+ pull. Same primitives and cryptography, one command per side.
Usage attribution: `stm teams audit-push` sends local key-use events
(placeholder commands only, never a resolved key) SIGNED with the
member's Ed25519 key; the server verifies the signature and attributes
each event to the verified member id, so a client cannot forge who it is.
`stm teams audit` shows the combined log. Honest limits: the audit actor
is cryptographically verified, but usage metadata (tool, label, counts)
is plaintext to the self-hosted server (credentials are not), and
per-member dollar cost is an estimate (providers bill per key, not per
caller). The broker and the Teams server run anywhere Bun does; the
runtime hooks are macOS + Claude Code (other platforms experimental).

## Documentation

- [Documentation home](https://subscribetome.pro/docs.html): Overview of
  the model and an index of the technical reference pages.
- [Security architecture & threat model](https://subscribetome.pro/security.html):
  Keychain-only keys, placeholder + PreToolUse substitution, the four
  hooks, the command-policy engine, trust boundaries, the honest argv
  limitation, and the Teams cryptography — with an equal-weight list of
  what is out of scope.
- [Credential broker](https://subscribetome.pro/broker.html): The
  `stm broker` command, the `/proxy/<tool>/<label>/<path>` model with a
  curl example, the loopback capability token, the SSRF / redirect /
  scrub / size-cap invariants, and the built-in targets.
- [Use the broker from any agent](https://subscribetome.pro/agents.html):
  The one rule (base URL + `x-stm-token` capability header), getting the
  values from `stm broker`, and copy-paste recipes for curl, the OpenAI SDKs
  (Python + Node), plain requests/fetch, LangChain, and LlamaIndex — plus a
  compatibility rule and a loopback forwarder for header-less clients.
- [Self-hosting STM Teams](https://subscribetome.pro/teams.html): Run the
  zero-knowledge server (env vars), create a team, push/pull the
  encrypted vault, enroll members by public key, read the signed audit
  log, and the honest limits.
- [CLI reference](https://subscribetome.pro/cli.html): Every `stm`
  command grouped by task, each with a one-line purpose and usage
  pattern.

## Project

- [Website](https://subscribetome.pro): The landing page with the install
  prompt and product overview.
- [GitHub repository](https://github.com/matterhornso/subscribetome): Source
  code, README, security model, and changelog. MIT licensed.
- [README](https://github.com/matterhornso/subscribetome/blob/main/README.md):
  Install instructions, command reference, security model, and limitations.
- [Security model](https://github.com/matterhornso/subscribetome/blob/main/SECURITY.md):
  Threat model and reporting policy.
- [Changelog](https://github.com/matterhornso/subscribetome/blob/main/CHANGELOG.md):
  Release history.

## Install

- [Claude Code marketplace install](https://github.com/matterhornso/subscribetome#or-install-it-yourself):
  Two commands — `claude plugin marketplace add matterhornso/subscribetome`
  then `claude plugin install stm@subscribetome`.
- [Agent-driven install](https://github.com/matterhornso/subscribetome#set-it-up-for-me):
  Paste a single sentence into Claude Code and the agent installs it for you.

## Specs

- [Cross-platform & Codex roadmap](https://github.com/matterhornso/subscribetome/blob/main/specs/cross-platform-and-codex.md):
  How v2 expands beyond macOS and Claude Code.
- [Spend visibility](https://github.com/matterhornso/subscribetome/blob/main/specs/spend-visibility.md):
  The second product — real spend pulled from provider APIs, on demand.
  Shipped v0.3.0 (foundation + OpenAI + Anthropic). Network-posture
  rule: stm makes outbound calls only when you click sync, only to
  the providers you've configured. No background activity, no
  telemetry, no phone-home.
- [Per-project key scope](https://github.com/matterhornso/subscribetome/blob/main/specs/session-and-project-scope.md):
  Multi-session, multi-project key scoping.

## Optional

- [Contributing guide](https://github.com/matterhornso/subscribetome/blob/main/CONTRIBUTING.md):
  How to add a service to the catalog (a one-line, data-only contribution)
  or submit a code change.
- [TODOs / deferred scope](https://github.com/matterhornso/subscribetome/blob/main/TODOS.md):
  v1.5+ work that's scoped but not yet built.