ADR-064: Repo-Committed Encrypted Secrets (SOPS + age) for the Devstack/CI Loop

The maintainer weighted cross-project workflow parity (canopy runs the same SOPS+age workflow; one identity unlocks both stores; one muscle memory) above the pure-Rust alternative’s advantages. The runner-up and the honest trade-off are recorded in Alternatives.

tools/craig-devtools/ — alpine base pinned by digest, sops/age apk versions pinned; built by direct docker build; the local tag is content-addressed (hash of the Dockerfile + inputs), so a stale or foreign :latest can never receive the key (canopy’s exists-only image check is deliberately not ported). Invocation is direct docker run: --network none, the identity mounted as an exact key-FILE read-only, workspace read-only (read-write only for encrypt targets), UID:GID, non-root. A considered-not-built alternative — a dedicated compose file — is recorded: it would reintroduce a second compose project for zero gain over docker run.

Recipients: the maintainer dev key + the CI key + an offline recovery key (a discarded CI private line is not a recovery mechanism). Identity path ~/.config/sops/age/keys.txt is deliberately shared with canopy — accepted with its threat model stated: one compromised dev key opens both projects' stores, and rotation/recovery couple across projects (ratified at gate G-A on #1031).

Two properties are stated because they are commonly misclaimed:

A neutral xtask/src/secrets_store.rs module (consumed by cmd/secrets and the field-key reconciler) enforces the v1 schema exactly: shared.field_encryption_key, a string containing valid base64 for 32 bytes — nothing else. Unknown sections, arrays, non-string leaves, duplicates, and normalized-env-name collisions are typed errors. .sops.yaml recipients must exactly equal the ciphertext’s sops.age[].recipient set (parity is linted and checked). Future store entries are explicit schema and trust-boundary changes, never drive-by additions.

Once the store exists: an identity-holding caller treats any failure — missing entry, malformed YAML, MAC failure, truncation, unsupported SOPS version, recipient/config drift, unknown sops error — as a hard failure. Only a positively classified no-identity case (and sops’s specific not-a-recipient error, for the joining-maintainer window) permits the contributor fallback; identity-present with store-absent is an integrity error.

ensure_field_key() resolves the desired key source FIRST (identity? store? local file? marker?), then materializes once. A Docker-free provision-only guard (generate-once, today’s behavior — this IS the permanent contributor path) remains the universal pre-compose step for every root-compose caller.

Store reconciliation is a separate, lifecycle-only concern returning a typed ReconcileOutcome { Unchanged, GeneratedFallback, PendingAdoption, Adopted }. Adopting a store key is a locked, durable, two-phase transition: write a pending record (.devstack/pending-adoption.v1.json — format version, store snapshot hashes, the new key’s KCV, never key material) → stop containers and wipe the encrypted volumes (the existing VolumeAction::Wipe machinery, driven by the outcome — never "overwrite the file and let the KCV marker notice") → atomically publish the new field-key.env → write the final marker → clear pending → bring-up + reseed. A crash in any window resumes idempotently from the pending record; the key value is re-derived from the store.

Only mutating lifecycle entry points consume the transition (start/reseed/refresh/ restart-with-recreate/e2e/validate’s ensure-ready); read-only commands report drift and change nothing. The warm path is gated by a versioned marker (.devstack/secrets-adoption.v1.json: format version + secrets/dev.yaml and .sops.yaml hashes + the adopted key’s KCV) — all three must match, so a replaced or regenerated local key is never silently blessed. Rotation is thereby a git commit: edit the store, commit; every identity-holding box adopts (wipe + reseed) on its next mutating command, CI picks the new value up next run.

One masked + protected variable CRAIG_CI_AGE_KEY (a single AGE-SECRET-KEY-1… line — GitLab masked variables must be single-line) replaces CRAIG_FIELD_ENCRYPTION_KEY outright. It is consumed only inside the pinned-digest container: a blocking secrets-policy job on protected refs runs the non-disclosing secrets check (decrypt
schema + recipient parity, prints no plaintext) — the only valid proof the CI keypair works — and devstack/ci/write-field-key.sh decrypts the field key the same way, with the output validated (single line, base64, 32 bytes), written atomically without following symlinks, the prior file retained on failure, and the variable unset before any unrelated tooling. ADR-048 §D5’s fail-loud property is preserved: an unset variable is a hard error naming the fix. The old variable stays inert for a bounded rollback window and is deleted only at gate G-C after one observed real scan-job success.

The synced security baseline says "no hardcoded secrets, API keys, or credentials in source code or configuration files." A SOPS ENC[…] value derives its security exclusively from the age key — the Kerckhoffs posture the baseline’s own rationale demands — but a downstream ADR cannot silently supersede a synced standard. The wording clarification is escalated upstream (claude-quickstart#27, filed 2026-08-10), and committing the store is gated on the maintainer ratifying the amendment/exception (G-A on #1031). The archived plan’s stricter reading (devstack-field-encryption §standing corrections) is superseded by that ratification, not by this document alone.