feat: first-class secrets — a forwardable slot with SecretBox (TML-3018)

[wmadden-electric]

First-class secrets — a forwardable slot

A secret is its own slot kind — not a config param, not a dependency. A service/module declares a nameless need; the application root binds it to a platform env-var name and forwards it down the module boundary; it reads back as a redacting SecretBox. The framework only ever handles the name — the value never touches the deploy machine, deploy state, the generated stack, or a log.

// A reusable module declares a need — it never learns the platform var name:
const auth = compute({ name: 'auth', secrets: { signingKey: secret() }, build: … });
const { signingKey } = auth.secrets();     // SecretBox<string>
signingKey.expose();                        // the sole reader; everything else redacts

// The root owns the binding and forwards it in:
module('app', ({ provision }) => {
  provision(auth, { secrets: { signingKey: envSecret('AUTH_SIGNING_KEY') } });
});

Design of record: ADR-0029 (+ config-params.md § Secrets).

How a name (never a value) crosses the system

1. Declare + forward. secret() is the need; envSecret('NAME') is the source the root binds; a module forwards its need through ctx.secrets, on the same rail Load already validates for inputs (ADR-0016). Load records each resolved binding { serviceAddress, slot, name } on the graph.
2. Pointer serialization. The deploy target writes a pointer row COMPOSE_<addr>_<slot> = NAME — the platform name, never a value. Every generated key carries a reserved COMPOSE_ prefix so it can't collide with a user-provisioned variable.
3. Boot double-lookup. The service reads the pointer row for the name, then process.env[NAME], and wraps it in a SecretBox — surfaced through a secrets() accessor beside load()/config() (ADR-0021).
4. Deploy preflight. Before provisioning, verify every bound name exists on the platform for the stage's class/branch. A name absent from the platform but present in the deploy shell is provisioned with a direct write-only POST (never an Alchemy resource, so no value reaches deploy state) — single-step CI. A name absent from both fails the deploy, naming exactly what's missing.

SecretBox (copied into @internal/foundation, matching the platform's own secrecy type) redacts on toString/toJSON/valueOf/Symbol.toPrimitive/util.inspect, so an accidental log or serialize prints [REDACTED]; expose() is the one explicit door. Sensitivity is structural — carried by the type, not a flag every sink must remember.

What's here

Area	Change
Core (@prisma/compose)	secret() need; secrets on compute()/module(); ctx.secrets forwarding + Load validation; secrets() accessor; opaque SecretSource + secretSource() SPI (core never reads a source's payload); provisionManifest introspection; param↔secret name-collision guard
Foundation	SecretBox
Pack (@prisma/compose-prisma-cloud)	envSecret('NAME') — the target's source constructor (the env-var name + COMPOSE_/DATABASE_URL rules live here, not core); pointer rows + boot double-lookup keyed on the secret slot; preflight (per-stage verify + shell fill-missing); restricted EnvironmentVariable adoption
Example / E2E	examples/storefront-auth — the auth module declares a need, the root binds (envSecret) + forwards it; non-leaking boolean round-trip proof + a committed Load test pinning the forwarding

Layering (ADR-0018/0019, applied to secrets): core owns the need (secret()) and forwards an opaque source it never inspects; the target owns the source constructor and provisioning. Prisma Cloud ships envSecret('NAME') (env vars); another target would ship vaultSecret({ path, key, version }) — no core change. import { secret } from '@prisma/compose' + import { envSecret } from '@prisma/compose-prisma-cloud'.

Evidence

Workspace green: core / pack / lowering / cron / storefront-auth typecheck + tests, lint:casts delta 0. The live proof runs in CI's e2e-deploy.yml: a real ephemeral Prisma Cloud deploy where the secret value exists only in the runner env, fill-missing provisions it, and the deployed service renders Secret /check says: true, then destroys everything.

History

The first pass (commits through 3ec8636) shipped a leaf-bound param-facet design; operator review corrected it to the forwardable-slot model (f3391d7…da64506), then to the properly-layered opaque-source split (507ace6, moving envSecret to the target). Both earlier shapes are on the branch; the ADR and code reflect only the final design.

Next.js port fix (included)

The COMPOSE_ prefix renamed every generated env key, including a service's port, which would have left a Next.js service on a non-default port misbinding (Next binds process.env.PORT, which nothing set post-rename; dormant at the default 3000). Fixed here: run() exposes the resolved service port as process.env.PORT before boot — the universal port convention, so Next binds the port Compute routes to. Harmless to services that read config().port explicitly (the Bun auth service ignores PORT).

Closes TML-3018.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/compose@70

npm i https://pkg.pr.new/@prisma/compose-prisma-cloud@70

commit: 3a1a58f

[wmadden]

OK first, you can't put transient project IDs in ADRs. Second: build the damn secret forwarding.

[wmadden]

This is way too long and carries inappropriate material for an ADR

[wmadden]

Cut this down to 2-3 lines. NO MORE

[wmadden]

WHY IS THIS SO LONG

[wmadden]

Centrtalize with other errors

[wmadden]

I notice this in framework. Secrets are passed as env vars in Prisma Cloud - not necessarily other implementations. Are we coupling to deployment target implementation details?