phantom-secrets

# Phantom

> Open-source CLI that helps keep provider credential values out of the managed dotenv and MCP path for supported AI workflows. It replaces managed dotenv values with non-provider `phm_` tokens and proxies exact supported API routes through an authenticated local service. Unmanaged files, same-user processes, proxy-bearer theft, and provider content remain outside that boundary.

## Install

Release evidence verified on 2026-09-05. The immutable GitHub `v0.7.8` release at
https://github.com/ashlrai/phantom-secrets/releases/tag/v0.7.8 resolves to
`f065b13462f9eaf27e0443f8911f021575b7c409`. Its 19 assets were published
after all six native acceptance rows and release attestations passed in
https://github.com/ashlrai/phantom-secrets/actions/runs/33952398697.
The separately managed Homebrew formula publishes reviewed `v0.7.8`.

macOS:
```
brew tap ashlrai/phantom
brew trust --formula ashlrai/phantom/phantom
brew install ashlrai/phantom/phantom
```

For the current macOS, Linux, or Windows release, select the exact `v0.7.8`
archive for your architecture from
the release, download its adjacent `.sha256` sidecar, verify it, and put both
release executables on PATH. In the exact 2026-09-05 registry snapshot, npm `latest`
remains `0.6.0`; exact npm `0.7.4` wrappers exist only under the failed
`release-candidate` track. No MCP Registry `0.7.8` record was found; crates.io
remains on `0.5.1`.

## MCP Server

Setup (recommended, one command per AI client):
- Claude Code: `phantom setup --client claude` (writes .claude/settings.local.json)
- Cursor: `phantom setup --client cursor` (writes ~/.cursor/mcp.json)
- Windsurf: `phantom setup --client windsurf` (writes ~/.codeium/windsurf/mcp_config.json)
- Codex: `phantom setup --client codex` (writes ~/.codex/config.toml)
- Generic: `phantom setup --client claude --print` (snippet to stdout)

Install both `v0.7.8` GitHub release binaries first. Version `0.7.8` records the running
`phantom` executable with `mcp serve` when it can resolve that runtime, otherwise
it looks for a local `phantom-mcp`. Setup has no network package-runner fallback
and fails closed when neither local runtime is executable. Keep both verified
binaries installed and inspect the generated entry.

The runtime `tools/list` response is the canonical MCP parameter schema and is
checked for exact parity with `mcp-registry/server.json`. Provider/network
requests, credential retrieval/use, and persistent effects are disabled by
default. Set `PHANTOM_MCP_EFFECTS=trusted-terminal` only outside agent
authority to reach the `confirm: true` and one-use `approval_token` gates;
conditional tools expose ungated inspection separately from effectful
parameters. `phantom mcp-approve` requires attached stdin/stderr, shows the
value-blind effect and exact parameters, and requires a fresh typed challenge.
A same-user shell or agent-controlled PTY can defeat this ceremony, so leave
effects disabled unless approval command and storage are outside agent
authority. Advanced audit,
validation, rotation, and expiry tools have distinct schemas; inspect
`tools/list` rather than extrapolating these gates. `phantom_check` accepts
`runtime`; staged index scanning is a CLI-only `phantom check --staged` option.

`phantom_rotate_with_candidate` and `phantom_rotate_promote` are deprecated
hard denials retained only for schema compatibility; they mutate nothing.

Vault: phantom_list_secrets, phantom_status, phantom_init, phantom_add_secret_interactive, phantom_add_secret (deprecated; refuses plaintext), phantom_remove_secret, phantom_rotate, phantom_copy_secret

Detection: phantom_doctor, phantom_why, phantom_check, phantom_env

Cloud: phantom_wrap, phantom_unwrap, phantom_sync, phantom_cloud_push, phantom_cloud_pull, phantom_cloud_status

Teams: phantom_team_list, phantom_team_create, phantom_team_members, phantom_team_invite, phantom_team_key_publish, phantom_team_vault_push, phantom_team_vault_pull

## CLI surface (--help is grouped: Setup · Daily use · Sync & teams · Maintenance)

init (--from <file>, --empty, --all <DIR>, --dry-run, --jobs/-j N), agent (report --json / doctor / setup --dry-run|--apply), exec, start, stop, list (--json), add (--stdin; new names only; initialized project required; positional values rejected), remove (trusted-terminal exact removal), reveal, rotate, status, doctor (--fix), check (--staged, --runtime), sync (--dry-run --json, --only PATTERN), pull, env, setup (--client claude|cursor|windsurf|codex, --print), login, logout, cloud (push/pull/status), wrap, unwrap, watch, why, copy (trusted-terminal confirmation, no target overwrite), export (trusted-terminal hidden prompt only; passphrase files and plaintext disabled), import (--from doppler|infisical|dotenvx|1password|env --file <path>; trusted-terminal exact consent), audit (show [--last N] [--op OP] [--name NAME] [--json] / tail / path / verify), team (list/create/members/invite/key-publish/vault-push/vault-pull/rotate-vault), validate (live/watch/schedule/history), expiry (set/enforce/rotate), open (closed alias catalog), upgrade (managed-owner routing; force denied), completion (bash/zsh/fish/powershell/elvish)

## Dashboard

https://phm.dev/dashboard: source-backed browser design for local/pilot access
state and cloud-backed project metadata after a hosted deployment and account
entitlement are independently commissioned. The public hosted service and
billing are not currently commissioned for authenticated use, and the dashboard
does not start checkout or collect payment.

## Key Features

- Phantom token proxy — replaces managed dotenv values with `phm_` tokens and injects a matched route's real key only into its fixed authentication header
- Inert client requests — no client-controlled header or body resolves a `phm_` token; bodies are accepted under a hard size cap, a missing route credential fails before upstream contact, and only route-owned auth injection can contain a real value
- Response scrubbing — redacts configured vault values and recognized key formats from supported response paths before returning them to the caller
- Public key awareness — detects and skips publishable/public keys that don't need protection
- OS credential storage — macOS Keychain, Linux keyutils by default with explicit `phantom vault migrate-linux` support for desktop Secret Service, Windows Credential Manager, and encrypted file fallback. Linux keyutils entries do not survive a reboot. Argon2id hardened to OWASP balanced (m=64 MiB, t=3, p=1)
- Personal cloud backup — client-encrypted restore on the same keychain machine; cloud-key transfer and recovery are not shipped, and deployed service and account configuration remain separate gates
- Multi-project scanner — `phantom init --all <DIR>` processes eligible repos found within five levels, stops below the first matching repo, and supports `--dry-run` plus `--jobs N`
- Multi-IDE setup — `phantom setup --client claude|cursor|windsurf|codex` writes the right MCP config for each AI tool
- Tamper-evident audit log — `PHANTOM_AUDIT=1` writes vault events as JSONL to `~/.phantom/audit.log` (secret name only). HMAC-SHA256 chain; `phantom audit verify` detects tampering. `phantom audit show/tail/path` for access.
- Competitor import — from an attached terminal outside agent authority, `phantom import --from doppler|infisical|dotenvx|1password|env --file <path>` displays an exact value-blind source/target/name plan and requires its fresh typed challenge before storage; `--force` never bypasses consent
- Encrypted recovery — export requires attached stdin/stdout/stderr, an exact value-blind challenge, and a hidden terminal passphrase; export passphrase files, plaintext, and argv passphrases are disabled. Import has the same terminal ceremony; only non-Windows import may additionally read a bounded private passphrase file.
- Enriched diagnostics — `phantom doctor` reports install source, vault backend, audit-log status, Argon2 params, MCP wiring per client
- Script wrapping — `phantom wrap` wraps selected runtime/build scripts and deliberately skips test, lint, type, and format scripts
- Watch mode — `phantom watch` reports new unprotected secrets; legacy `--auto` hard-denies before mutation, so protection remains a reviewed transactional `phantom init`
- Secret explainer — `phantom why <KEY>` explains detection heuristics
- Cross-project copy — `phantom copy` shares secrets between project vaults
- Doctor with auto-fix — `phantom doctor --fix` repairs configuration issues
- Team vaults — fixed-membership encrypted sharing; invitation management is owner/admin-gated, vault access is member-wide, and offboarding rotation is not shipped
- Pre-commit hook — runs a bounded staged dotenv/key-prefix check when Git invokes it; pair with CI and a broader scanner
- Threat model — see THREAT_MODEL.md for assets, actors, mitigations, known gaps

## Current source boundary

- Governed project/config writers retain the acquisition-time directory,
  reject outside-root and symlink/reparse traversal, require regular single-link
  sensitive files, and compare exact identity plus bytes before replacement or
  unlink. Rename-decoy tests verify that a swapped ambient path is not mutated.
- Init retains the reviewed root and exact dotenv/config leaf identity, bytes,
  and permissions before vault provisioning, then revalidates them under the
  project lock before mutation. Byte-identical replacement leaves are drift.
- `CommittedVerifiedButDurabilityUncertain` is committed, exactly verified
  success with a value-free warning/receipt and no rollback or retry.
  `CommittedButUncertain` is the distinct **Partial** result; reconcile before
  retrying and do not infer rollback or a safe no-op.
- Operations needing both vault and project authority resolve the
  process-environment-dependent vault first, then acquire the project transaction lock,
  compare the retained root identity, and reread exact config state. This
  rejects a same-path replacement without inverting the shared lock order.
- These controls are not a same-user sandbox. They coordinate Phantom writers
  and preserve path identity while handles are retained; an equivalent
  same-user process or agent-controlled terminal remains in the threat model.
- Windows source establishes a protected current-user DACL on new private
  files/directories before bytes and preserves the reviewed exact DACL and
  inheritance state on replacement staging files before writing. Reparse,
  handle, ACL, and Credential Manager behavior still await protected native
  Windows CI acceptance. The release receipt proves exact-archive execution
  and MCP schema initialization, not native keychain, ACL, shell, or editor
  acceptance.
- Immutable `v0.7.8` release identity:
  `f065b13462f9eaf27e0443f8911f021575b7c409`. Live GitHub governance observed
  2026-09-01: the `release` environment required review and accepted only `v*`
  tags; no-bypass immutability ruleset `21903888` was separate from creation
  ruleset `21997435` with Mason-only bypass. The immutable release record is
  https://github.com/ashlrai/phantom-secrets/releases/tag/v0.7.8.
- Locus, broker, runtime, session, and externally trusted evidence remain
  inactive and fail closed. Enterprise packaging is planned/commissioned only
  through separate written and acceptance evidence.
- Rama upstream main snapshot
  https://github.com/plabayo/rama/commit/267e4790c899736e6f60d982c8a0932406d4079e
  (reviewed 2026-09-01) is a pinned
  benchmark for explicit stacks, modular crates, examples, and tiered platform
  CI. It is not a dependency or parity claim.

## How AI Should Behave

- NEVER show, log, or write real API key values into code files
- Managed dotenv values become `phm_...` placeholders rather than provider credentials. Client requests never resolve them, but keep dotenv reads denied and rotate exposed mappings because unmanaged entries remain possible and a process with the live proxy bearer can invoke configured routes.
- Use `phantom_list_secrets` to see what secrets are available (never shows values)
- Use `phantom_add_secret_interactive` to add new keys; the user types values only into the trusted terminal prompt
- Use `phantom_init` to protect an unprotected `.env` file
- Suggest `phantom exec -- <command>` to run code with real credentials injected
- Never automate CLI login/logout, cloud reads/writes, team reads/mutations, remove, live validation, schedule/expiry writes, browser open, import/export, or eligible standalone upgrade through an agent-controlled PTY; their exact terminal ceremonies must remain outside agent authority

## Links

- Website: https://phm.dev
- GitHub: https://github.com/ashlrai/phantom-secrets
- Docs: https://phm.dev/docs
- Full LLM context: https://phm.dev/llms-full.txt