Server Overview

agentsecrets-server is the asynchronous coordination backend for the AgentSecrets ecosystem. It coordinates multi-client secret synchronization, team key exchange, and platform telemetry without ever holding, seeing, or processing plaintext credentials.

The server operates as an untrusted coordinator: it stores ciphertext blobs, verifies workspace memberships, and routes encrypted payloads between authorized clients.

Core Responsibilities

┌──────────────────────────────────────┐
│        CLI / SDK / ZK MCP            │  <- Local Machine (Encrypts / Decrypts)
└──────────────────┬───────────────────┘
                   │
                   │ HTTPS REST API (Ciphertext Only)
                   ▼
┌──────────────────────────────────────┐
│         agentsecrets-server          │  <- Blind Coordinator & Ciphertext Host
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│      PostgreSQL / Redis Cache        │  <- Double-Envelope Encrypted At Rest
└──────────────────────────────────────┘

The server manages five core domains:

Domain	Responsibility	Security Invariant
Ciphertext Storage	Bulk secret upsert, versioning, and environment-scoped retrieval	Ciphertext is encrypted client-side (AES-256-GCM) and double-wrapped at rest (Fernet). The server holds no decryption keys.
Workspaces & Access	Workspace membership, role enforcement (Owner, Admin, Member), and domain allowlists	Membership updates exchange workspace keys encrypted under recipients' X25519 public keys.
Agent Identity	Agent registration, token issuance, and capability allowlist scoping	Enforces granular HTTP method and domain bounds per agent token.
Audit Log Ingestion	Centralized collection of client proxy access logs	Ingests SHA-256 hash-chained records with redacted credential fields.
Telemetry & Metrics	Daily anonymous client snapshot ingestion and platform analytics	Regex sanitization strips all file paths, usernames, and binary names from execution logs.

The Zero-Knowledge Guarantee

Traditional secrets managers operate as trusted vaults: the server receives plaintext over TLS, holds master decryption keys, and logs access. A server compromise exposes every secret in storage.

agentsecrets-server is architecturally blind:

Client-Side Encryption: Secrets are encrypted locally via AES-256-GCM before transmission. The server receives base64-encoded ciphertext blobs.
Asymmetric Key Wrapping: Workspace encryption keys are wrapped using recipients' public keys (X25519 / NaCl SealedBox). The server stores sealed envelopes it cannot decrypt.
Double-Envelope Protection: When persisting records to PostgreSQL, the server applies an outer Fernet encryption layer (ENCRYPTION_KEY). Decrypting this database layer only yields the client-side AES ciphertext.

Architecture at a Glance

The backend is built in Python with a strict 5-layer separation:

Controllers (views.py): Thin HTTP adapters (< 25 LOC per route) handling validation and serialization.
Selectors (selectors.py): Pure read queries, prefetching, and in-memory caching with zero side effects.
Services (services.py): Atomic business operations wrapped in database transactions (transaction.atomic()).
Schemas (schemas.py): Strict Pydantic v2 data models with extra="forbid".
Models (models.py): PostgreSQL tables with UUID primary keys and composite indexing.

For a deep dive into the implementation details, see 5-Layer Architecture.