Credential broker for Molecules AI. Single ingress for get / set / roll against Infisical (primary) + AWS Secrets Manager (mirror) with structured audit logging.

See RFC #315 in molecule-ai/internal for the full design.

Status

v0.1.0 — PR-1 skeleton. No business logic. This release provides:

Repo + package skeleton (Python 3.12, FastAPI, psycopg3)
Postgres state store with StateStore Protocol indirection
/healthz endpoint (Postgres probe; Infisical probe is hardcoded true in v0.1.0)
LeaderLock no-op stand-in (v2 will swap to pg_advisory_xact_lock)
BrokerClient SDK with BROKER_URL env-var endpoint resolution
mol_secret_v3 CLI (version and healthcheck verbs only)
Structured JSON audit logger (stdout → Vector → Loki)
50+ unit tests covering the seams above

get / set / roll arrive in PR-2 — PR-9 per RFC#315 §12.

v1.0 vs v2 (HA)

v1.0 is single-node. The five seams below were designed up-front so v2 (HA, multi-node) is a one-or-two-file swap, not a rewrite.

Seam	v1.0	v2 (HA)
`StateStore` Protocol	`PostgresStore`	same `PostgresStore`, sharded reads
`LeaderLock`	no-op (always acquired)	`pg_advisory_xact_lock(hash(key))`
Idempotent upsert	`INSERT … ON CONFLICT … DO UPDATE`	unchanged
`BrokerClient` resolution	`BROKER_URL` env or DNS	DNS-based service discovery
`/healthz`	postgres probe + hardcoded infisical	postgres + infisical + leader status

Quickstart

uv sync
uv run pytest -v
uv run mol_secret_v3 version
uv run mol_secret_v3 healthcheck

Running locally

# Start a Postgres for the broker:
docker run -d --name mol-secret-broker-pg -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:16

# Apply schema (the broker auto-applies on start, but you can pre-apply via psql):
PGPASSWORD=dev psql -h localhost -U postgres -d postgres -f mol_secret_broker/store/migrations/0001_init.sql

# Run the broker:
MOL_SECRET_BROKER_DSN="postgresql://postgres:dev@localhost:5432/postgres" \
  uv run uvicorn mol_secret_broker.server:app --host 127.0.0.1 --port 8080

# Probe:
curl -s http://127.0.0.1:8080/healthz | jq .

Tests

The Postgres-backed tests use the testcontainers Python library, which spins up a real Postgres container per test session. They are skipped when:

Docker is not available, or
MOL_SECRET_BROKER_TEST_DB=skip is set.

When skipped, an in-memory MemoryStore fallback exercises the StateStore Protocol so the seam contract still gets test coverage.

Run the full suite:

uv run pytest -v

Run only the testcontainer-backed integration tests:

uv run pytest -v -m integration

Layout

mol_secret_broker/
├── __init__.py          # __version__
├── config.py            # BrokerConfig — YAML + env loader
├── store/
│   ├── __init__.py      # StateStore Protocol + MemoryStore for tests
│   ├── postgres.py      # PostgresStore implementation
│   └── migrations/
│       └── 0001_init.sql
├── leader.py            # LeaderLock context manager (v1.0 no-op)
├── audit.py             # AuditLogger — JSON to stdout
├── context.py           # BrokerContext dataclass
├── server.py            # FastAPI app + /healthz
├── client.py            # BrokerClient SDK
├── cli.py               # mol_secret_v3 CLI
└── tests/               # 50+ unit + integration tests

License

MIT. See LICENSE.