Security Architecture
With the meta-tools working, we built the security layer that makes them safe to use. The core requirement: we cannot access your credentials, even with full database access.
Four-Tier Envelope Encryption
User credentials protected by layered encryption: (1) login cookie or bearer token encrypted with server key, (2) Key Encryption Key derived from token’s secret via HKDF, (3) Vault Data Encryption Key wrapped with KEK, (4) individual credentials encrypted with vault DEK. Without the user’s token, the chain cannot begin. Toolcog cannot decrypt credentials even with full database access.
Self-Routing Tokens
Session tokens contain their own routing information in encrypted form. The token identifies which account and session it belongs to without requiring a database lookup. Tokens are stateless—any edge node can validate and route them. Token types distinguished by prefix: tck* (API keys), tcs* (login sessions), tca* (OAuth access), tcr* (OAuth refresh), tcz_ (authorization codes).
OAuth 2.1 Authorization Server
Complete OAuth 2.1 implementation with mandatory PKCE for all flows. Supports authorization code, refresh token, and client credentials grants. Public clients require PKCE with no secret. Confidential clients require secret with basic or post auth method. Authorization endpoint handles consent, scope selection, and secure redirect validation.
Vault System
Logical data containers with unique IDs and DEKs. Multiple sessions and API keys can share the same vault by each wrapping the DEK with their own KEK. OAuth authorization codes carry wrapped vault DEK, enabling credential access from MCP clients.
X25519 Key Exchange
Organization vault recovery and session merging use X25519 elliptic curve key exchange. Each grant has an X25519 keypair: public key stored plaintext, private key wrapped with grant’s KEK. Initiator creates escrow with vault DEK wrapped using ECDH-derived key. Only the recipient can derive the same shared secret to unwrap.
Token Rotation
Sessions rotate automatically after 25% of lifetime elapsed. Successor chain: new token encrypted with HKDF-derived key from old secret. Old token continues working until natural expiration—no lockout if users don’t swap tokens immediately.
Permission Delegation
Fine-grained permissions delegate through the account hierarchy. Organizations grant permissions to members; members can delegate subsets to API keys. Callers can only grant permissions they have. Permission checks traverse the delegation chain. Revocation cascades automatically.
Rate Limiting
Per-account rate limiting with sliding window algorithm. Weighted count smooths transitions at window boundaries.
Credential Types
Five types: OAuth 2.0 (accessToken, refreshToken, tokenType, expiresAt, scope), API Key, HTTP Basic, HTTP Bearer, OpenID Connect. Credentials keyed by vault, bridge account, bridge resource, service name, and scheme name.
Automatic Token Refresh
Transparently refreshes expired OAuth tokens during credential resolution. Proactive refresh within 5-minute window before expiry.