When you connect Toolcog to external services—GitHub, Stripe, Google—your credentials are encrypted with keys derived from secrets only you possess. Toolcog cannot decrypt your credentials. Not “we promise not to.” Cannot. The cryptography makes it impossible.
Think of a bank’s safety deposit box. The bank provides the vault (secure storage), but opening a box requires two keys: the bank’s master key and your personal key. Neither party can open the box alone.
Toolcog’s credential protection works similarly, but goes further. Your credentials are encrypted with keys derived from your session token. Without a valid token—which only you possess—the encrypted data is indecipherable noise.
The result: even if someone compromises Toolcog’s database, they get encrypted blobs they cannot open. Even Toolcog’s operators cannot decrypt your credentials without your active session.
Toolcog implements envelope encryption across four cryptographic tiers. Each tier protects the next, creating a chain where your credentials can only be unlocked by presenting a valid authentication token.
When you sign in, Toolcog creates an encrypted token containing:
This token lives in your browser as an HTTP-only cookie. It’s encrypted with Toolcog’s server key, but that only proves authenticity—the secret inside is what matters.
The secret is random, generated fresh for each session. It’s never stored in any database. It exists only inside your encrypted token.
When you perform an operation that needs credentials, your auth secret is used to derive a Key Encryption Key using HKDF (a cryptographic key derivation function).
The KEK is never stored. It’s derived fresh on each request, lives only in memory during that request, and is discarded immediately after. Different session types (browser, API key, OAuth) derive different KEKs even from the same secret, providing cryptographic isolation.
Each user has a vault with a single Data Encryption Key. This DEK encrypts all your credentials. The DEK itself is encrypted (“wrapped”) with your KEK before storage.
The wrapped DEK is stored in the database, but it’s useless without your KEK—which can only be derived from your auth secret—which only exists inside your encrypted token—which only you possess.
Finally, your actual credentials (OAuth tokens, API keys) are encrypted with the vault DEK.
Each credential is encrypted with AES-256-GCM, which provides both confidentiality (encryption) and integrity (tampering detection).
| Tier | What | Where |
|---|---|---|
| 1 | Auth token (account ID + secret) | Your browser cookie |
| 2 | Key Encryption Key (KEK) | Derived in memory, never stored |
| 3 | Vault Data Encryption Key (DEK) | Stored wrapped, unwrapped with KEK |
| 4 | Credentials | Stored encrypted, decrypted with DEK |
Each tier protects the next. The chain only completes when you present a valid token.
When AI executes an API call that needs credentials, here’s what happens:
Credentials exist in plaintext only transiently, during the moment of execution, then immediately discarded. They’re never logged, never cached, never persisted unencrypted.
If an attacker gains access to Toolcog’s database, they get:
Without valid auth tokens, the entire vault is cryptographically sealed.
If an attacker gains access to Toolcog’s servers, including the server key used to decrypt tokens, they still can’t access credentials at rest. They would need to intercept a valid token during an active session—and even then, they could only access that one user’s vault, not everyone’s.
Toolcog’s operators cannot decrypt your credentials. There’s no admin backdoor, no master key, no “break glass” procedure. The cryptographic design makes it impossible, not just prohibited.
Each session (browser login, API key, MCP connection) has its own wrapped copy of your vault DEK. This enables:
When you sign out or revoke a session, that session’s ability to derive the KEK is destroyed. The vault DEK remains safely encrypted, accessible only through your other active sessions.
Important: If you sign out or let a session expire and no other session shares the vault, the vault becomes permanently inaccessible. This is intentional—credentials are easy to re-authorize. See Vault Linking to keep vault access across sessions.
By default, each login creates its own vault. If you log in on your laptop and separately on your phone, each session has an independent vault with independent credentials. This provides isolation but means credentials don’t automatically synchronize.
When you create an API key or authorize an MCP client from an existing session, the new grant automatically shares your vault. The creating session wraps its vault DEK with a key the new grant can derive, and passes it through the authorization flow. No separate key exchange is needed—vault access is embedded in the authorization itself.
This is why connecting an MCP client from a logged-in browser gives the client access to your existing credentials. The browser session’s vault DEK flows to the new grant as part of the OAuth authorization.
For sessions created independently (different browsers, different devices), X25519 key escrow enables after-the-fact unification.
Each grant has a persistent X25519 keypair. To merge vaults:
Each escrow uses a fresh ECDH derivation, providing forward secrecy. Escrows expire after 24 hours.
When you claim a vault escrow, credentials from your old vault are migrated:
If both vaults have the same credential (same service and scheme), the more recently created one is kept. Nothing is lost—your credentials consolidate into the shared vault.
Most services store credentials in a database with application-level encryption:
| Component | Algorithm | Key Size |
|---|---|---|
| Token encryption | AES-256-GCM | 256-bit |
| Key derivation | HKDF-SHA-256 | 256-bit |
| Key wrapping | AES-KW (RFC 3394) | 256-bit |
| Credential encryption | AES-256-GCM | 256-bit |
| Key agreement | X25519 | 256-bit |
Every layer includes integrity verification:
Any tampering at any layer causes immediate, obvious failure—not silent corruption.
When sessions end:
Even if a future compromise exposed everything, past sessions’ credentials remain protected.
This architecture supports compliance requirements that mandate:
