Documentation Index
Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
ArgentOS stores API keys, service credentials, and authentication tokens using AES-256-GCM encryption. Secrets are encrypted before they hit disk or database — the system never stores plaintext credentials in any persistent location. The encryption architecture has three layers:- Master key — Stored in the OS keychain (macOS Keychain, Linux secret-service, Windows Credential Vault)
- Encryption engine — AES-256-GCM with random IVs and authentication tags
- Storage backends — JSON files (legacy) and PostgreSQL tables (current)
Encryption Format
All encrypted values use a self-describing format:| Component | Description |
|---|---|
enc:v1 | Version prefix for format identification |
iv-hex | 12-byte initialization vector (hex-encoded) |
authTag-hex | GCM authentication tag (hex-encoded) |
ciphertext-hex | Encrypted payload (hex-encoded) |
The version prefix (
enc:v1) enables future format upgrades without breaking existing encrypted values.AES-256-GCM
The system uses AES-256-GCM (Galois/Counter Mode), which provides both confidentiality and authenticity:- 256-bit key — Derived from the master key stored in the OS keychain
- 12-byte random IV — Generated fresh for every encryption operation using
crypto.randomBytes() - Authentication tag — GCM produces a tag that detects any tampering with the ciphertext
- No padding needed — GCM is a stream cipher mode, so no PKCS7 padding is required
OS Keychain Integration
The 256-bit master key is stored in the operating system’s native credential store:| Platform | Backend |
|---|---|
| macOS | Keychain Services (security CLI) |
| Linux | Secret Service API (GNOME Keyring, KDE Wallet) |
| Windows | Credential Vault |
argentos. It never appears in configuration files, environment variables, or logs.
Key Generation
On first encryption operation, if no master key exists in the keychain:Key Retrieval
On subsequent operations:- Check in-memory cache
- If not cached, read from OS keychain
- Cache for process lifetime
Backward Compatibility
The decrypt function accepts both encrypted and plaintext values:PostgreSQL Secret Store
When running with PostgreSQL backend (dual-write or postgres mode), secrets are stored in two PG tables:Service Keys Table
Stores API keys and service credentials:| Field | Description |
|---|---|
variable | Environment variable name (e.g., OPENAI_API_KEY) |
encrypted_value | AES-256-GCM encrypted value |
service | Service identifier (e.g., openai, anthropic) |
category | Grouping category (e.g., llm, channel, tool) |
allowed_roles | Roles that can access this key |
allowed_agents | Agent IDs that can access this key |
allowed_teams | Team IDs that can access this key |
deny_all | If true, key is inaccessible to all agents |
Auth Credentials Table
Stores authentication profiles (OAuth tokens, API keys with metadata):encrypted_payload field contains a JSON object encrypted with AES-256-GCM. This payload includes the actual credential data (API keys, OAuth tokens, refresh tokens) along with provider-specific metadata.
Access Control
Service keys support fine-grained access control:allowed_roles— Only agents with matching roles can use the keyallowed_agents— Only specific agent IDs can use the keyallowed_teams— Only agents in specific teams can use the keydeny_all— Emergency kill switch to revoke all access
When all access control arrays are empty, the key is accessible to all agents (open access).
CRUD Operations
Service Keys
Auth Credentials
Migration from JSON
For installations migrating from JSON-file storage to PostgreSQL, Phoenix provides a one-shot migration function:- Reads the JSON files
- Decrypts any already-encrypted values (using the same master key)
- Re-encrypts for PG storage
- Upserts into the PostgreSQL tables
- Reports migration counts
ON CONFLICT ... DO UPDATE.
Key Rotation
To rotate the master key:Currently, key rotation is a manual process. The system does not support automatic key rotation.
Security Properties
| Property | Status |
|---|---|
| Encryption at rest | AES-256-GCM for all persistent secrets |
| Key management | OS keychain (not in files or env vars) |
| Authentication | GCM auth tag prevents tampering |
| IV reuse prevention | Random 12-byte IV per encryption |
| Backward compatibility | Plaintext values accepted, encrypted on next write |
| Access control | Per-key role/agent/team restrictions (PG only) |
| Audit trail | created_at / updated_at timestamps |
Key Files
| File | Description |
|---|---|
src/infra/secret-crypto.ts | AES-256-GCM encrypt/decrypt (63 LOC) |
src/infra/pg-secret-store.ts | PostgreSQL secret store (365 LOC) |
src/infra/keychain.ts | OS keychain master key management |
src/infra/service-keys.ts | JSON-file service keys (legacy) |
