Add secret-store config references spec

[ChristianPavilonis]

Summary

• Adds a design spec for secret-store backed config references from Add secret-store backed config references for secret values #684.
• Captures the narrowed v1 scope from the design discussion: refs plus provisioning/runtime policy, no generation or handler IDs.
• Documents local inline-secret support and production provisioning rejection of inline secrets.

Changes

File	Change
docs/superpowers/specs/2026-05-19-secret-store-config-references-design.md	Adds the proposal/spec for secret-store backed config refs, Fastly provider behavior, runtime resolution semantics, provisioning validation, and acceptance criteria.

Closes

Closes #714
Related #684

Test plan

• cargo test --workspace --exclude trusted-server-cli
• cargo test --package trusted-server-cli --target "$(rustc -vV | sed -n 's/^host: //p')"
• cargo clippy --workspace --exclude trusted-server-cli --all-targets --all-features -- -D warnings
• cargo clippy --package trusted-server-cli --target "$(rustc -vV | sed -n 's/^host: //p')" --all-targets -- -D warnings
• cargo fmt --all -- --check
• JS tests: cd crates/js/lib && npx vitest run
• JS format: cd crates/js/lib && npm run format
• Docs format: cd docs && npm run format -- superpowers/specs/2026-05-19-secret-store-config-references-design.md
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Manual testing via fastly compute serve
• Other: docs-only change; Rust/JS/runtime checks not run.

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — use expect("should ...")
• Uses log macros (not println!)
• New code has tests
• No secrets or credentials committed

[aram356]

Summary

Docs-only PR adding a v1 design spec for secret-store backed config references. The proposal is well-scoped (no auto-generation, no handlers.id, no request-signing migration) and the inline/ref dichotomy with strict production gating is a clean separation. Two correctness gaps and two open semantics questions block before merge; the rest are improvements to harden the spec against ambiguous implementation choices.

Blocking

🔧 wrench

• Hash determinism: shorthand and explicit-default refs hash differently for the same logical secret (see inline at §"Config hashing and canonicalization").
• Distinct-names validation: providers.fastly.secrets.store_name must be reconciled with the CLI's existing validate_distinct_names (see inline at §"Fastly provider configuration").

❓ question

• Production boundary: which exact code path enforces inline-secret rejection at the canonical-payload write boundary, not just the apply command boundary?
• Fail-closed HTTP semantics: 401 vs 503 (and the same for proxy_secret-backed endpoints)?

Non-blocking

📌 out of scope

• handlers.id deferral: open question #3 leaves handlers.id for a later version. Without it, the operator-chosen secret key is the only stable link between a [[handlers]] entry and its secret; reordering the TOML is fine, but renames/duplicates break the link. Worth a follow-up issue so v1.x can decide stability semantics before the user surface ossifies.

CI Status

• browser integration tests: PASS
• integration tests: PASS
• prepare integration artifacts: PASS

[aram356]

🔧 wrench — Hash determinism: shorthand and explicit-default refs resolve to the same secret but hash differently.

{ secret = "publisher/proxy_secret" } and { store = "ts_secrets", key = "publisher/proxy_secret" } both point at the same physical secret, but as written they produce different canonical TOML bytes and therefore different config_hash values. Attestation/diff tooling will report spurious config changes when an operator normalizes shorthand → explicit (or back).

Fix: either (a) require canonicalization to normalize one form to the other before hashing, or (b) state explicitly that the two forms are intentionally non-equivalent for hashing and document why. Either way, add the chosen rule to Acceptance Criteria.

[aram356]

🔧 wrench — providers.fastly.secrets.store_name must be added to the CLI's validate_distinct_names.

crates/trusted-server-cli/src/config.rs:213-226 already enforces distinct Fastly Secret Store resource names across signing_secret_store_name and runtime_api_secret_store_name. Adding a third Secret Store without extending that check lets two different runtime aliases (ts_secrets, signing_keys, api-keys) silently link the same underlying resource, collapsing the isolation contract the spec assumes between application secrets and request-signing/runtime-API secrets.

Fix: spec should require provisioning to reject overlap across all three secret-store resource names, and Acceptance Criteria should add a checkbox for it.

[aram356]

❓ question — Production boundary: where exactly is inline-secret rejection enforced?

The spec gates inline-secret rejection at ts provision fastly apply. But the canonical TOML payload is what actually lands in the Config Store. Is ts provision fastly apply the only code path that writes the canonical app config payload to a Fastly Config Store? If a future ts deploy, manual upload, or alternate CLI path can write that payload, inline plaintext can still reach production.

Clarify: is the gate at the command boundary sufficient, or should it also live at the payload-write boundary (the function that serializes + uploads canonical TOML)?

[aram356]

❓ question — Fail-closed HTTP semantics: 401 vs 503?

"Deny access or return an auth/config error" is ambiguous. Today, crates/trusted-server-core/src/auth.rs returns 401 with WWW-Authenticate for failed basic auth. A probe receiving 401 can't distinguish "route exists, wrong creds" from "route is misconfigured"; 503/500 reveals "this route is broken". The choice has security (oracle attacks) and ops (paging signal) consequences.

Same question for proxy_secret-dependent endpoints (encrypt/decrypt URL): 4xx (treat as unsigned) or 5xx (refuse to serve)?

Lock specific status codes / failure modes into the spec; downstream callers will rely on them.

[aram356]

♻️ refactor — Alias naming inconsistency: ts_secrets vs ts_config_store.

Existing aliases: ts_config_store (crates/trusted-server-core/src/runtime_config.rs:22) for the application Config Store; signing_keys/api-keys for the existing Secret Stores. The new alias breaks both patterns: it's neither ts_<resource>_store (which would be ts_secret_store) nor an unprefixed purpose-name (which would be app_secrets/application_secrets).

Pick one convention and justify in the spec. ts_secret_store would parallel ts_config_store cleanly.

[aram356]

🤔 thinking — "Eager but non-fatal" + no retry = persistent fail-closed until next snapshot.

The runtime section reads as decisive ("eager per loaded config snapshot"); open question #6 punts retry. Operationally this is "affected feature stays fail-closed indefinitely until the next config refresh / cold start." That's defensible for v1, but the spec should state this explicitly here instead of leaving it to readers to infer from the open question list.

[aram356]

📝 note — Debug/Display semantics for SecretRef.

Redacted<T> redacts in Debug/Display. SecretRef carries store/key strings, which are operational metadata, not secret material — but readers will reasonably wonder whether they leak in logs. Spec should state explicitly that SecretRef Debug/Display is non-redacting (paths only), and ResolvedSecretString::Unavailable { reference } is safe to log.

[aram356]

📝 note — Tie SecretString validation into the existing validator::Validate pattern.

Existing fields use validator::Validate with custom validators like validate_redacted_not_empty (crates/trusted-server-core/src/settings.rs:332-335) and EdgeCookie::validate_secret_key (crates/trusted-server-core/src/settings.rs:282-286). The spec should note that SecretString validation slots into this pattern (custom validator for SecretString::Inline empty-check, parse-time rejection for ref shape errors) rather than introducing a parallel validation framework.

[aram356]

⛏ nitpick — "may warn" should be "warns".

Production rejects inline v1 secrets; local may warn is too soft. Make the local-dev contract a definite warning (still permitting the inline value) so the two layers tell the same story.

[aram356]

⛏ nitpick — Acceptance Criteria gaps.

Add checkboxes for:

• the ref canonicalization rule (matches the hash-determinism wrench)
• extending validate_distinct_names to include providers.fastly.secrets.store_name
• rejecting refs whose explicit store alias has not been provisioned (mentioned in §"Provisioning validation" body, missing from criteria)