foundation/documentation/contracts/CONTRACT_002_vault_path_layout.md

Contract — CONTRACT_002 — Vault Path Layout

Between: bootstrap/components/credentials.ts (writer) ↔ every service component (reader) Status: Agreed (pending implementation validation) Realizes: PLAN-002 §4 · Consistent with: ADR-002, 002_platform_architecture.md §3

Interface

2.1 Mount

• KV v2 mount: foundation (one mount for the whole egg).
• Path scheme: foundation/<service>/<type>-credentials (mirrors the proven olsicloud4 scheme olsicloud4/<project>/<stage>/<type>-credentials, dropping the stage — Layer 0 is single-stage).

2.2 Key naming — camelCase, no exceptions

Keys are produced by JSON.stringify() of TypeScript objects, so they are camelCase (e.g. postgresSuperPassword). Any future ESO remoteRef.property (Layer 1) must match exactly. This is the documented footgun in 002_platform_architecture.md §3 — honour it from day one.

2.3 Paths and keys

Path	Keys (camelCase)	Generated by
foundation/postgres/service-credentials	postgresSuperUser, postgresSuperPassword, forgejoDbUser, forgejoDbPassword	@pulumi/random
foundation/rustfs/service-credentials	rustfsAdminUser, rustfsAdminPassword, rustfsServiceKeyId, rustfsServiceKeySecret	@pulumi/random
foundation/forgejo/service-credentials	forgejoSecretKey, forgejoInternalToken, forgejoJwtSecret, forgejoOauth2JwtSecret, forgejoAdminUser, forgejoAdminPassword	@pulumi/random
foundation/forgejo/registry-credentials	ociPushToken, npmPushToken	Forgejo API post-bootstrap → Vault
foundation/runner/service-credentials	runnerRegistrationToken	Forgejo generate-runner-token → Vault
foundation/backup/backup-credentials	offsiteAccessKey, offsiteSecretKey, offsiteEndpoint, backupAgeRecipient, backupAgeIdentity	seeded once + @pulumi/random (age key)
foundation/cloudflare/api-credentials	cloudflareApiToken	seeded once (mirror of config secret)
foundation/project/project-credentials	(empty, disableRead: true)	manual one-time seed slot (ADR-002 pattern)

2.4 What is NOT in Vault (the bootstrap exception)

Vault's own rootToken and unsealKeys cannot live in Vault (chicken-egg). They live in the passphrase-encrypted Pulumi config (vaultCredentials:*, CONTRACT_001 §1.3). This is the single deliberate exception and the hinge of the whole trust chain (PLAN-002 §4.1).

2.5 Access model

• Day-zero (Layer 0): components read from Vault using the root token (from config) during pulumi up, or values are rendered into container env/app.ini directly by Pulumi. No AppRole yet.
• Steady-state / Layer 1: introduce a per-consumer AppRole + scoped policy per service (foundation/<service>/* read-only), mirroring the SecretStore vault-<project>-<stage> pattern. Policy stubs live in packages/pulumi-vault/policy.ts (vendored from olsicloud4 modules/vault).

Ownership

• Writer: credentials.ts owns generation + write. It is the only writer of *-credentials paths (single source of truth; rotation = pulumi up --replace, ADR-002).
• Readers: each service component reads only its own service path.

Assumptions

• KV v2 (versioned) — enables rotation history + rollback.
• Vault audit log enabled at init (records every read).

Validation

• After T06: assert every key above exists at the correct path with non-empty value (idempotent re-run produces no diff). A vault kv get smoke check per path.

Change Process

New credential = add a row here + flip the matching features.<x> flag (CONTRACT_001). Never add a secret to git or config that could instead be generated into Vault. Renames are breaking — version this contract and update writer + reader together.