Skip to content

Secrets Bridge

Control Plane API

Control Plane API (`api`)¶

Repo: secrets-bridge/api · Stack: Go 1.25 + Fiber v3 + pgx v5 + go-redis v9 · Container: golang:1.25-alpine build → distroless/static:nonroot

The decision-making tier. Holds metadata, owns the workflow + RBAC domain, mediates between users (via the SPA) and agents (via outbound HTTPS).

Layout¶

api/
├── cmd/api/                # main, config, server bootstrap
├── internal/
│   ├── auth/               # JWT signer + permission catalog + auth.Require
│   ├── handlers/           # HTTP layer (one file per aggregate)
│   ├── middleware/         # Auth (Bearer→X-User-Id→anon), RequestID, Logger, Recover
│   ├── observability/      # slog JSON logger
│   └── services/           # business logic (one file per aggregate)
└── pkg/
    ├── storage/            # Postgres repositories + migrations (embed.FS)
    ├── runtime/            # Redis primitives (locks, idempotency, rate limit, pub/sub)
    ├── keymgmt/            # KMS backends (local / vault-transit / aws-kms)
    ├── sealing/            # X25519 + HKDF + AES-GCM for wire envelope
    └── argocd/             # read-only ArgoCD client (BRD §26)

The internal/ boundary is closed; the pkg/ boundary is deliberately open because worker imports pkg/storage and pkg/keymgmt.

Runtime endpoints¶

Path	Purpose
`GET /healthz`	Always 200. Liveness.
`GET /readyz`	Aggregated readiness across `postgres` + `redis` checks (+ KMS at boot). 503 with per-check failure map on failure.
`GET /metrics`	Prometheus exposition.
`POST /api/v1/auth/login`	Email + password → HS256 JWT.

See HTTP API endpoints for the full surface.

Configuration¶

Env var	Required	Default	Notes
`API_ADDR`	no	`:8080`	Listen address
`DATABASE_URL`	yes	—	`postgres://...`
`REDIS_URL`	yes	—	`redis://...`
`SB_JWT_SECRET`	yes	—	32+ bytes, base64 or raw. Fails boot if missing.
`SB_JWT_TOKEN_TTL`	no	`8h`	Login session lifetime
`SB_WRAP_MASTER_KEY`	yes when `SB_KMS_BACKEND=local`	—	base64 32 bytes
`SB_KMS_BACKEND`	no	`local`	`local` / `vault-transit` / `aws-kms`
`SB_KMS_VAULT_ADDR` / `SB_KMS_VAULT_TOKEN` / `SB_KMS_VAULT_KEY`	yes for `vault-transit`	—
`SB_KMS_AWS_REGION` / `SB_KMS_AWS_KEY_ID`	yes for `aws-kms`	—	Alias OK; ARN stored in audit
`SB_BOOTSTRAP_ADMIN_EMAIL` / `SB_BOOTSTRAP_ADMIN_PASSWORD`	recommended on first boot	—	Seeds local-admin user; idempotent
`SB_GITOPS_ENABLED`	no	`false`	Mounts BRD §26 ArgoCD endpoints when true

See Configuration reference for the exhaustive list.

What's stable, what isn't¶

Area	Status
The four request lifecycles (submit / approve / reject / cancel)	Stable
Patch + read flows end-to-end against Vault + AWS SM	Stable
Single-shot wrap consumption	Stable, race-tested (6 concurrent racers)
JWT login + `auth.Require(perm)` gating on write endpoints	Stable since slice 7
OIDC	Not shipped — tracked at api#26
Per-tenant KMS scoping	Not shipped — tracked as Piece 8c
Rate limiting on auth + heartbeat	Not shipped — tracked at api#30
Tested key-rotation runbook	Not shipped — tracked at api#31