Secrets - Stackra

Two kinds, two mechanisms

Kind	Where the value lives	Who sets it	How code reads it
Application secret (payment keys, OAuth client secrets, webhook signing secrets, provider API keys)	The runtime’s secret store, per environment	A human	By name at runtime through the runtime’s binding, for example `secret("NAME")` once Encore lands. Never from a file.
Developer or CI token (MCP server tokens, CI vendor tokens)	The Infisical vault. `/agents` for developer tokens, `/ci` for CI. Nowhere else.	A human, in Infisical	Developers: `tools/scripts/mcp.sh` injects a token for the server process. CI: OIDC login, then `infisical run` for one step.

There is no third mechanism. There is no .env file, no .env.example, and no second vault. A local override for development goes in a gitignored file that holds no value anyone else needs. Rationale: ADR 0009. Procedures: secrets runbook.

Stackra has no deployed runtime yet, so only the developer-token mechanism and the repository checks are live. The application-secret rules apply from the first service that declares a secret.

What an agent may do

An agent may	An agent may not
Declare `secret("NAME")` in code and name the key and its purpose in its report.	Set, rotate or delete a value.
Reference a developer token in `.mcp.json` as a bare `$KEY`. Not `${KEY}`: Claude Code expands that form itself and disables the server when the variable is unset.	Read a value, in any form, into the transcript.
Run `tools/scripts/secrets-doctor.mjs` once it exists. It reports names only.	Write a value into a file, test, fixture, log, comment, commit message or chat message.
Use sentinel test values such as `sentinel-<topic>-never-printed`.	Add a `.env` file, a second vault, or a sync into the code host.

Articles

Each article names the check that enforces it.

#	Article	Enforcement
S1	No secret value in any file in git: source, test, fixture, doc, comment, workflow, lockfile.	Enforced. gitleaks (`.gitleaks.toml`) at pre-commit through lefthook and `pnpm secrets:scan`. CI scan arrives with ADR 0012.
S2	Manifests and config carry names only.	Planned. Covered by S1 today; a name-pattern check comes with the first manifest that lists secrets.
S3	No static credential stored in the code host. Vendor tokens come from Infisical through OIDC.	Planned. A CI workflow allowlist check (`secrets-workflow-allowlist`) lands with the CI pipeline.
S4	CI authenticates by OIDC only, with one machine identity per environment. Pull-request jobs can never read production.	Planned. A `vault-oidc` composite step plus an OIDC-permissions check, built with the CI pipeline.
S5	A secret is process environment for one step. Never written to a CI env or output file, an artifact, a cache, a log or a comment.	Partial. `infisical login --silent` in the steps; the agent hook denies `printenv`. The CI write check is planned.
S6	No `.env`, no `.env.example`, no second vault in any repository.	Planned. `secrets-no-dotenv` check in the validator. The agent hook already denies reading `.env` and `.dev.vars`.
S7	An agent never reads a secret value. Agents see names, never values.	Partial. `.agents/hooks/guard-bash.mjs` denies `.env`/`.dev.vars` reads, `printenv` and bare `env`, `encore secret set`, and `wrangler secret put`. It does not yet deny `infisical export`, `infisical secrets get` without `--silent`, or `encore secret get`. Adding those rules, with a hook test, is planned. Until then an agent must never run them.
S8	Setting, rotating and deleting a value is a human act, in the vault or store. Production changes need a second person once a second maintainer exists.	Planned. Vault configuration; CODEOWNERS now.
S9	A test needs zero secrets. `verify` and every test run with no credential. A test that needs a real one is a design finding.	Partial. `pnpm verify` takes no secret. gitleaks scans fixtures.
S10	Test values that look like credentials are built at runtime from fragments, so the scanner sees nothing in the diff.	Enforced by S1: gitleaks blocks anything else.
S11	The image never bakes a value.	Planned, with the first deployable image.

When a secret leaks

Rotate first, investigate second. The value is compromised the moment it is pushed. Rewriting history does not un-leak it.
Record what, when and when it was rotated. Never paste the value.
If gitleaks missed the pattern, add it to .gitleaks.toml.

Not allowed

A third mechanism “just for this one case”.
A ${KEY} placeholder that a tool or shell expands into a file.
A secret in a commit message, PR description, chat message, issue or AI prompt.
Lowering an article so a gate passes. Change the law through an ADR, or fix the code.

​Two kinds, two mechanisms

​What an agent may do

​Articles

​When a secret leaks

​Not allowed

Two kinds, two mechanisms

What an agent may do

Articles

When a secret leaks

Not allowed