The credential broker that other tools wish they were. While some projects (cough, OpenClaw, cough) think "security" means printing your API key to stdout and hoping for the best, we built session-authenticated, PBKDF2-encrypted, HMAC-verified, rate-limited, scoped, logged, and revocable credential management. You know — actual security.

  ╔══════════════════════════════════════════════════════════════╗
  ║                                                              ║
  ║   🔐  Encrypted vault (PBKDF2 · 200K iterations · HMAC)     ║
  ║   🤖  AI agent broker (scoped · logged · revocable)         ║
  ║   🔍  16-provider audit pipeline (live API validation)       ║
  ║   🖥️  6 interfaces (CLI · TUI · Web · Desktop · API · MCP)  ║
  ║   🛡️  Hostile security audit: PASSED                        ║
  ║                                                              ║
  ╚══════════════════════════════════════════════════════════════╝

---

⚡ 30-Second Setup

git clone https://github.com/Senpai-Sama7/check-please.git
cd check-please
./start.sh --web    # opens browser UI

That's it. No config files. No Docker. No 47-step setup guide. No "please install our custom CLI tool first."

💡 Some tools require you to read a novel before you can validate a single key. We respect your time.

---

🤖 Connect Your AI Agent

Agent	Command	Setup Time
	./start.sh --agent-env codex	~5s
	MCP config (see below)	~15s
	eval $(./start.sh --agent-export)	~5s
	eval $(./start.sh --agent-export)	~5s
	./start.sh --agent-env interpreter	~5s
	HTTP API / env inject / MCP	~10s

📋 Step 1: Set permissions (click to expand)

Create .check_please_agent_permissions.json in your project root:

{
  "allowed": [
    "OPENAI_API_KEY",
    "ANTHROPIC_API_KEY",
    "GITHUB_TOKEN"
  ],
  "token_ttl": "1h"
}

🔌 Step 2: Connect your agent (click to expand)

Claude Code (MCP): Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "credentials": {
      "command": "python",
      "args": ["/absolute/path/to/check_please/agent_api.py", "--mcp"]
    }
  }
}

Any agent (4 options):

./start.sh --agent-env <command>          # inject env vars
eval $(./start.sh --agent-export)         # export to shell
./start.sh --agent-write-env /tmp/.env    # write .env file
./start.sh --agent-api                    # HTTP API + bearer token

---

🔒 Scoped Permissions — Because "Allow All" Is Not a Security Model

Unlike certain tools that give agents a skeleton key to your entire .env and call it a feature...

{
  "allowed": [
    "OPENAI_API_KEY",
    {"name": "ANTHROPIC_API_KEY", "max_uses": 50, "expires": "2h", "rpm_limit": 60},
    {"name": "GITHUB_TOKEN", "max_uses": 10, "expires": "30m"}
  ],
  "token_ttl": "1h",
  "alerts": {
    "token_threshold": 100000,
    "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  }
}

Feature	check_please	"Other tools"
Per-credential max uses	✅	❌
Time-based expiry	✅	❌
RPM rate limiting	✅	❌
Bearer token TTL	✅	❌
Slack/Discord alerts	✅	❌
Per-agent usage tracking	✅	❌
Session-authenticated API	✅	😬
Encrypted vault	✅ PBKDF2 200K	🤷 plaintext?

---

📊 Usage Tracking & Alerts

Every credential request is counted. Every token is tracked. Every agent is logged.

# Real-time monitoring
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8458/usage

# Per-key breakdown
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8458/usage/OPENAI_API_KEY

Alerts fire automatically:

• 🚨 Agent exceeds RPM limit → 429 + terminal warning + webhook
• 💰 Token threshold exceeded → terminal warning + webhook
• 📝 All access logged to agent_usage.log (append-only JSON)

---

🖥️ Interfaces

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   CLI ──── check-please --env .env        (table output)    │
│   TUI ──── ./start.sh --tui              (rich terminal)    │
│   Web ──── ./start.sh --web              (browser SPA)      │
│   Desktop  ./start.sh --desktop          (native GTK app)   │
│   API ──── ./start.sh --agent-api        (HTTP broker)      │
│   MCP ──── ./start.sh --agent-mcp        (Claude/Copilot)   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Lock Screen	Dashboard	Audit Results

Password Vault	Settings	Build .env

📸 Screenshots coming soon. Run ./start.sh --web to see the live UI.

---

🔍 Providers (16)

Provider	Key Pattern	Provider	Key Pattern
	sk-*		sk-ant-*
	AIza*		ghp_* gho_*
	sk_live_*		xox[bpas]-*
	hf_*		gsk_*
	alphanumeric		nvapi-*
	sk-* (hex)		hex (64)
	sk-or-v1-*		csk-*
	SG.*.*		hex (32)

Adding a provider? Drop a single file in credential_auditor/providers/. Auto-discovered. Zero config. No registration. Some frameworks make you write a plugin manifest, register a factory, and sacrifice a goat. We don't.

---

🛡️ Security

  ┌──────────────────────────────────────────────────────────┐
  │                    SECURITY LAYERS                       │
  ├──────────────────────────────────────────────────────────┤
  │                                                          │
  │  🔑  PBKDF2-HMAC-SHA256 · 200,000 iterations            │
  │  🧂  16-byte random salt per account                     │
  │  ✅  HMAC-SHA256 integrity verification                  │
  │  🍪  HttpOnly + SameSite=Strict session cookies          │
  │  🚫  Exponential backoff (1s → 2s → 4s → ... → 30s)     │
  │  📏  Content-Security-Policy enforced                    │
  │  🔒  chmod 600 on all vault/account files                │
  │  🛑  10MB request body limit (anti-DoS)                  │
  │  🏠  localhost-only binding                              │
  │  📝  All access logged (append-only)                     │
  │  🔗  Symlink/hardlink attack detection                   │
  │  🚫  No raw keys in any output — ever                    │
  │                                                          │
  └──────────────────────────────────────────────────────────┘

🔴 Hostile security audit: PASSED — 10-part adversarial audit covering crypto, auth, input validation, network security, file system, and dependencies. All critical findings fixed. Read the full report →

Security Headers

Every response includes:

• X-Frame-Options: DENY — clickjacking protection
• X-Content-Type-Options: nosniff — MIME sniffing prevention
• Content-Security-Policy — script/style source restrictions
• Referrer-Policy: no-referrer — zero URL leakage
• X-XSS-Protection: 1; mode=block — legacy XSS filter

Brute Force Protection

Attempt 1 → 1s lockout
Attempt 2 → 2s lockout
Attempt 3 → 4s lockout
Attempt 4 → 8s lockout
Attempt 5 → 16s lockout
Attempt 6+ → 30s lockout (capped)

---

🔐 Password Vault

Your vault stores passwords, API keys, and credentials — all encrypted locally.

• ✅ Add/edit/delete entries with site, username, password, notes
• ✅ Password generator with configurable length and complexity
• ✅ Import CSV from Chrome, 1Password, Bitwarden, LastPass, etc.
• ✅ Export CSV for portability
• ✅ Biometric unlock via phone (FIDO2/WebAuthn)
• ✅ Encrypted backups (.cpbackup files)
• ✅ Emergency recovery sheet (printable)
• ✅ Multi-account support

Your data never leaves your machine. No cloud sync. No telemetry. No "anonymous" analytics. Just your secrets, encrypted, on your disk. Revolutionary concept, apparently.

---

📡 HTTP API Reference

Method	Path	Description
GET	/providers	List providers and env var names (no values)
GET	/credentials	List allowed credential names (no values)
POST	/credentials/{VAR}	Get credential value (if permitted)
GET	/health	Server status
GET	/usage	Usage summary for all credentials
GET	/usage/{VAR}	Per-credential usage stats
POST	/usage	Agent reports token consumption

All requests require Authorization: Bearer <token>. Token displayed on startup.

---

🧪 Self-Healing & Error Handling

💪 What auto-recovers (click to expand)

Scenario	What Happens
Corrupt vault file	Returns empty vault — no crash
Corrupt account file	Returns "not found" — others unaffected
Missing data directory	Auto-created on startup
Wrong backup password	Clear error — file untouched
Invalid JSON in data	Safe default returned
Legacy single-account data	Auto-migrated to multi-account
WebAuthn not supported	Falls back to browser
Downloads folder missing	Auto-created

🚫 What doesn't recover (by design) (click to expand)

• Lost password + lost recovery key + no backup = data is gone. No backdoors. That's the point.
• Deleted data files = gone without backup. No shadow copies.
• Corrupted encrypted backup = unrecoverable. Keep multiple backups.

---

🏗️ Adding a Provider

# credential_auditor/providers/myprovider_p.py — that's it. One file.
class MyProvider(Provider):
    name: ClassVar[str] = "myprovider"
    env_patterns: ClassVar[list[re.Pattern]] = [re.compile(r"^MY_API_KEY$")]
    key_format: ClassVar[re.Pattern] = re.compile(r"^mk-[a-z0-9]{32}$")

    async def validate(self, key, client):
        resp = await client.get("https://api.example.com/me",
                                headers={"Authorization": f"Bearer {key}"})
        if resp.status_code == 200:
            return "valid", "account info", None, None, None, None
        return "auth_failed", None, None, None, None, "Invalid key"

Drop the file. Run the tool. Provider auto-discovered. Zero registration, zero config, zero boilerplate.

---

📦 Install

pip install .           # core (3 deps: httpx, rich, python-dotenv)
pip install ".[tui]"    # + Textual TUI

Or just run ./start.sh — handles venv, deps, and launch automatically.

---

🏆 Why check_please?

	check_please	OpenClaw	"Just use .env"
Encrypted vault	✅ PBKDF2 200K	❌	❌
Session authentication	✅ HttpOnly cookies	❌ global state	N/A
Per-credential scoping	✅ max_uses + TTL + RPM	❌	❌
Brute force protection	✅ exponential backoff	❌	N/A
16 provider validation	✅ live API checks	partial	❌
MCP support	✅ native	❌	❌
Biometric unlock	✅ FIDO2/WebAuthn	❌	❌
Security audit	✅ hostile audit passed	🤷	🤷
Request body limits	✅ 10MB cap	❌ OOM me	N/A
Security headers	✅ CSP + HSTS + XFO	❌	N/A
Setup time	~30 seconds	???	instant (insecure)
Dependencies	3	🤷	0

We're not saying other tools are bad. We're saying we tested ours with a hostile security audit and published the results. Can they say the same? 🫖