Coffer

CI

The strongbox between your secrets and your AI.

Credential vault for LLM agents. Your AI assistant uses passwords and API keys — but never sees them.

---

The Problem

When you give Claude a password or API key, it lives in the conversation context — stored in history, visible in logs, potentially exposed. Even if you delete the chat, the credential was still processed in plaintext.

The Solution

Coffer stores your credentials encrypted on your machine and exposes MCP tools that let Claude make authenticated requests without ever seeing the actual credential. The password goes from your vault to the target server. Claude only sees the result.

You (one-time setup)
  │
  ▼
Coffer MCP Server (runs locally)
  ├── Encrypted vault (AES-256-GCM with AAD)
  ├── coffer_list         → returns aliases only
  ├── coffer_http_request → injects auth, returns clean response
  ├── coffer_test         → verifies credential works (pass/fail)
  ├── coffer_web_login    → logs into websites, caches session
  ├── coffer_web_fetch    → fetches pages as markdown
  └── coffer_audit        → tamper-proof activity log

Claude sees: { "status": "ok", "body": "..." }
Claude never sees: your password

Quickstart

1. Install

pip install coffer-mcp

2. Set up your master key

coffer init
# Enter a master passphrase — this encrypts all your credentials

3. Add a credential

coffer add
# Follow the prompts: alias, auth type, username, password, allowed URLs

# With expiry (optional):
coffer add --expires 90d           # expires in 90 days
coffer add --expires 2026-12-31    # expires on a specific date

Default deny: If you omit --allowed-urls (or leave it blank), the credential is blocked from all URLs. This is intentional — fail-closed security. You must explicitly list which URLs the credential is allowed to reach.

4. Configure Claude Desktop

Add to your claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "Coffer": {
            "command": "python",
            "args": ["-m", "coffer_mcp.server"]
        }
    }
}

5. Use in Claude

"What credentials do I have stored?" → Claude calls coffer_list → sees aliases only, plus expiry status

"Test my API credential" → Claude calls coffer_test → { test: "PASS", status_code: 200, latency_ms: 142 }

"Test my API credential against an auth-enforcing endpoint" → Claude calls coffer_test with expected_status: 200 → { test: "FAIL", status_code: 401, expected_status: 200 } — catches false positives

"Fetch the latest article from my blog" → Claude calls coffer_web_login then coffer_web_fetch → You get the article content, Claude never sees your password

MCP Tools

Tool	What it does	What Claude sees
coffer_list	List stored credentials	Aliases, types, expiry status
coffer_http_request	Authenticated API call	Response body (sanitized)
coffer_test	Verify credential works	Pass/fail, status code, latency. Optional expected_status for strict validation.
coffer_web_login	Log into a website	{ status: "ok" }
coffer_web_fetch	Fetch page content	Clean markdown
coffer_web_logout	Close web session	{ status: "ok" }
coffer_audit	View activity log	Events + chain integrity

What Claude never sees: passwords, API keys, tokens, session cookies.

CLI Commands

coffer init              # Set up master key in OS keyring
coffer add               # Add a credential (interactive)
coffer add --expires 90d # Add with 90-day expiry
coffer list              # List credentials (no secrets, shows expiry)
coffer test <alias>      # Test a credential works (HEAD request)
coffer test <alias> --url https://api.example.com/me --expected-status 200  # Strict test
coffer rotate <alias>    # Rotate the secret for a credential
coffer rekey             # Re-encrypt all credentials with a new passphrase
coffer export <file>     # Encrypted backup to file
coffer import <file>     # Restore from encrypted backup
coffer remove <alias>    # Remove a credential
coffer audit             # View audit log + verify integrity
coffer clear-key         # Remove master key from OS keyring
coffer serve             # Start MCP server (for debugging)

Security

See SECURITY.md for the full threat model.

Encryption & storage:

• AES-256-GCM encryption at rest with per-entry unique nonces
• Associated Authenticated Data (AAD) binds each ciphertext to its alias, preventing copy-paste attacks between entries
• Master key stored in OS keyring (Windows Credential Manager / macOS Keychain / Linux Secret Service)
• Random PBKDF2 salt per user (stored with key in keyring)
• Key rotation via coffer rekey — re-encrypts all credentials atomically with a new passphrase

Access control:

• URL allowlisting with strict domain matching
• Per-hop redirect checking against allowlist
• HTTP method validation (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• CSS selector validation to prevent injection in web scraping
• OAuth2 pipe-delimited format validation
• Response body size cap (10 MB) to prevent memory exhaustion

Data protection:

• Response sanitization scrubs credentials from bodies and error messages
• Expanded scrubbing catches base64-encoded secrets, Bearer tokens, and URL-embedded credentials
• Prompt injection defense (strips HTML comments, hidden elements, invisible unicode)
• Browser session auto-expiry (30 minutes)
• Credential expiry with automatic enforcement

Integrity & auditability:

• HMAC-SHA-256 audit chain (keyed to master key) — detects tampering
• Warning emitted when audit logger runs without HMAC key
• Atomic backup writes (write-to-temp + rename) prevent corruption on crash
• Audit status reflects target server response: auth_rejected when credentials are injected but the server returns 401/403, distinguishing between vault-level success and target-level failure

Concurrency:

• Cross-platform file locking (fcntl on Unix, Win32 LockFileEx on Windows) for credential store and audit log
• Thread-safe global state for sessions, token cache, and store/audit initialization

Supported Auth Types

Type	Use case	How it works
bearer_token	REST APIs with Bearer tokens	Injects Authorization: Bearer <token>
basic_auth	APIs with Basic authentication	Injects Authorization: Basic <base64>
api_key_header	APIs with custom API key headers	Injects custom header with key
web_login	Websites with form-based login	Browser automation via Playwright
oauth2_client_credentials	OAuth2 APIs (ServiceNow, etc.)	Auto-fetches and caches tokens

OAuth2 client_credentials format

The OAuth2 client_credentials flow is two calls: coffer first POSTs client_id and client_secret to a token endpoint, then uses the returned access token as Authorization: Bearer <token> on the actual API call. Because the token URL is per-tenant (e.g. uat.example.com vs app.example.com) and tokens are scoped, coffer needs both pieces at import time. They are packed into the username and secret fields using | as a delimiter:

Field	Format	Example
username	<client_id>&#124;<client_secret>	abc123&#124;s3cr3t
secret	<token_url>&#124;<scope>&#124;<auth_style>	https://auth.example.com/oauth2/token&#124;read:api&#124;body

Scope is optional (some providers ignore it). The token URL must also appear in --allowed-urls — coffer checks it against the allowlist before POSTing the credentials, so a malicious prompt can't redirect the client secret to an attacker-controlled token endpoint.

auth_style is optional and defaults to body, which sends client_id and client_secret as form-body parameters (client_secret_post). This is the most widely compatible method and is required by OneTrust, whose token endpoint reads the credentials from the body and ignores an Authorization header. Set it to basic to send the credentials in an HTTP Basic header (client_secret_basic) instead, which some IdPs require. Per RFC 6749 §2.3.1 only one method is used per request.

Credential Expiry

Credentials can have an optional expiry date. When set:

• coffer list shows EXPIRED or EXPIRING_SOON (within 7 days) status
• Expired credentials are blocked from use — Claude gets a clear error
• coffer test checks expiry before making requests

Key Rotation

If your master passphrase is compromised, rotate it without losing any credentials:

coffer rekey
# Enter current passphrase → enter new passphrase → confirm
# All credentials are re-encrypted atomically
# Old vault is untouched until migration completes

Backup & Restore

# Export all credentials to an encrypted backup file
coffer export ~/coffer-backup-2026.enc
# Enter a backup passphrase (separate from your master key)

# Restore from backup on a new machine
coffer import ~/coffer-backup-2026.enc
# --overwrite flag replaces existing credentials with same alias
coffer import ~/coffer-backup-2026.enc --overwrite

Backups are AES-256-GCM encrypted with a separate passphrase. Writes are atomic (temp file + rename) so a crash mid-export won't corrupt your backup. Safe to store in cloud storage.

File Layout

~/.coffer/
├── credentials.json    # Encrypted credentials (AES-256-GCM + AAD)
├── audit.jsonl         # Append-only audit log with HMAC chain
└── .master-key         # Auto-generated master key (fallback only)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests (142 tests)
pytest

# Lint
ruff check src/ tests/
ruff format --check src/ tests/

CI runs automatically on every push and PR — lint + test matrix across Python 3.10-3.13 on Ubuntu, Windows, and macOS.

Requirements

• Python 3.10+
• Claude Desktop (for MCP integration)
• Windows / macOS / Linux

License

Apache 2.0