Implementation report

This page summarizes what has been built across the DevOps Secrets programme — the platform, the validation subsystem, the tooling, and the assurance behind them. It's the "what did we ship" overview; the other pages in this section are the how-to.

At a glance#

Area	Status	What it delivers
Secrets core	✅ shipped	Environments, namespaces, service accounts, API keys, policies, versioning, envelope encryption, seal/unseal
Machine data-plane	✅ shipped	/api/v1/secrets/** read/write/list/versions/bulk with API-key auth, optimistic locking, rate limits
Credential validation	✅ shipped	5 probes, scheduler, alert state machine, history, alert routes (email/Slack/webhook)
Console UI	✅ shipped	Full management surface + validation config, alerts page, and settings
CLI	✅ shipped	pulsvault single binary — profiles, safe reveal, gen/cp/diff/bulk-get, validate, completion
Pipelines	✅ shipped	GitHub Action + GitLab CI template over the data-plane
Documentation	✅ shipped	This section (15 pages)

Secrets management#

The store follows the industry-standard model (paths, versioned KV, path-pattern policies, seal, audit) where that model is the right answer, and differs deliberately where it counts:

• Environment is a first-class, validated vocabulary — the top path segment, not a naming convention. See Paths, plans & roles.
• Three-layer envelope encryption (master → per-namespace KEK → per-version DEK) with the full path bound as authenticated data. See Encryption & sealing.
• Dual-space ownership — the same feature serves a solo Developer's personal space and a Team/Business/Enterprise organization.

Access is separated into two planes: humans manage access in the console; only machines read values over the API. Every mutation is written to the tamper-evident, hash-chained audit log under the SECRETS_OPS stream, filterable in the Trace Explorer.

Credential validation — the differentiator#

The headline capability: stored secrets are continuously tested, so a credential is known-working, not just stored.

• Probes: PostgreSQL, MySQL/MariaDB, GitHub PAT, and two user-configurable HTTP probes (Bearer and Basic) that validate any API — e.g. a Gemini/OpenAI key. See Probes.
• Scheduler + worker pool run due validations every 60 seconds; results feed an alert state machine (Healthy → Degraded → Firing → Suppressed → Escalated → Resolved) with a consecutive- failure threshold so alerts stay trustworthy.
• Validate-on-change: writing a new secret version auto-validates it, so a rotation is immediately confirmed working or broken.
• On-demand: pulsvault validate <path> checks a credential now, and pulsvault validation-status <path> reports whether a path is validated at all without touching it. Both exit with a code that names the outcome — a revoked credential, a check that could not be completed, and a path nobody configured are each distinguishable, so a CI gate can treat them differently. Ready-made GitHub Action and GitLab CI integrations wrap them.
• Routing: alerts deliver to email, Slack, and signed webhooks per configurable alert routes.

Tooling#

• The pulsvault CLI — a dependency-light static binary with profiles (local/dev/prod), safe-by-default reads (masked on a terminal, raw when piped, explicit --reveal/--copy), and utility commands (gen, cp, diff, bulk-get, envs, namespaces, whoami, config, completion).
• Pipeline integrations — for loading, a GitHub Action that masks values in logs and a GitLab CI template; for gating, a second Action and template that fail a deploy on a broken credential while letting a check that merely could not be completed pass with a warning. Both over the live data-plane.

Security hardening#

Assurance#

• The backend runs a full automated test suite (~800 tests, H2 in-memory), including end-to-end machine-plane flows (write → validate → history), the alert path, _whoami/_environments/ _namespaces listing, and SSRF-guard unit tests.
• The CLI has its own unit + fake-server tests covering masking, flag parsing, the command registry and help, profiles, and each utility command.
• The console builds and prerenders cleanly with the management and validation UIs.

Deferred (roadmap)#

• Custom user-defined probe templates (beyond the configurable HTTP probes).
• Additional probe coverage (Redis, MongoDB, cloud IAM, JWT, TLS-certificate expiry).
• Namespace/organization-level validation-interval overrides, latency-degradation alerts, maintenance windows.
• Real email delivery (currently a platform-wide stub; Slack/webhook delivery is live).

Related#

• Overview
• Credential validation overview