chore(framework): canonize Vault-as-SSOT + ESO-default secrets policy
Some checks failed
ci/woodpecker/push/ci Pipeline failed
ci/woodpecker/pr/ci Pipeline failed

Encodes operator-approved (Jason, 2026-05-22) secrets policy as binding
framework rules across all Mosaic agent sessions and projects.

Changes:
- STANDARDS.md: add "Secrets handling (HARD RULE)" subsection under
  Non-Negotiables — Vault as SSOT, ESO bridge as default, Direct-Vault
  opt-in only, forbidden ${VAR:-default} for required values, forbidden
  .env in prod, required startup schema validation
- VAULT-SECRETS.md: add four new sections — architecture decision matrix
  (ESO vs Direct-Vault), full ESO bridge worked example (Vault path +
  ExternalSecret + Deployment YAML + zod/pydantic/Go validators),
  Direct-Vault opt-in pattern (AppRole provisioning + ESO bootstrap
  for chicken-and-egg), and forbidden patterns CI lint targets
- BOOTSTRAP.md: add "Secrets Bootstrap" required subsection with
  checklist for new apps (Vault path, README docs, ExternalSecret,
  secretKeyRef, schema validator, Direct-Vault justification)

All duplicate file paths kept in sync (md5-equal pairs):
  guides/ <-> packages/mosaic/framework/guides/
  packages/mosaic/framework/defaults/STANDARDS.md (single copy in repo)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Hermes Agent
2026-05-22 11:58:27 -05:00
parent 755df9079e
commit 373e4558a3
5 changed files with 772 additions and 0 deletions

View File

@@ -453,6 +453,26 @@ Initialize standard labels and the first pre-MVP milestone:
---
## Secrets Bootstrap (Required for Every New App)
Every new application MUST complete the following secrets bootstrap before deploying to any non-local environment. This is a hard gate — deployment without completed secrets bootstrap is forbidden.
### Secrets bootstrap checklist
- [ ] Vault path created: `vault kv put secret/k3s/<app>/ ...` with all required secret fields
- [ ] Required secrets listed in project README under a "Secrets architecture" section, including:
- Vault path(s) used
- All required secret keys and their purpose
- Whether the app uses ESO bridge (default) or Direct-Vault (opt-in, with justification)
- [ ] `external-secret.yaml` manifest committed to repo's `deploy/` or `k8s/` directory
- [ ] Deployment YAML references the synced k8s Secret via `secretKeyRef` (not raw env vars or `.env` files)
- [ ] App startup has schema-based validation for all required env vars (zod / pydantic / envconfig equivalent) that exits non-zero on missing required values
- [ ] Direct-Vault opt-in (if applicable): justification documented in README + AppRole provisioned + bootstrap credentials stored in Vault and synced via a separate `ExternalSecret`
See `~/.config/mosaic/guides/VAULT-SECRETS.md` for full worked examples of the ESO bridge pattern, the Direct-Vault opt-in pattern, and the forbidden antipatterns.
---
## Checklist
After bootstrapping, verify: