@smoothbricks/cli 0.11.17 → 0.11.18

package/src/wrangler/deploy-stage.test.ts

@@ -3,15 +3,16 @@ import { existsSync, mkdtempSync, readFileSync, statSync } from 'node:fs';
 import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import type {
-  CloudflareClient,
-  CloudflareZone,
-  D1DatabaseRecord,
-  DnsRecord,
-  R2Bucket,
-  WorkerDomain,
-  WorkerRoute,
-  WorkerScript,
+import {
+  CloudflareApiError,
+  type CloudflareClient,
+  type CloudflareZone,
+  type D1DatabaseRecord,
+  type DnsRecord,
+  type R2Bucket,
+  type WorkerDomain,
+  type WorkerRoute,
+  type WorkerScript,
 } from './cloudflare.js';
 import {
   childEnvironment,
@@ -144,6 +145,10 @@ class FakeCloudflare implements CloudflareClient {
   namespaces: LiveKvNamespace[] = [];
   buckets: R2Bucket[] = [];
   scripts: WorkerScript[] = [{ id: 'fixture-worker-pr123' }];
+  /** Secret names each Worker already holds, by Worker name. */
+  secrets: Record<string, string[]> = {};
+  /** Every Worker whose secrets were queried, in order, so a test can prove one was never asked. */
+  secretQueries: string[] = [];
   domains: WorkerDomain[] = [];
   zones: CloudflareZone[] = [];
   routes: Record<string, WorkerRoute[]> = {};
@@ -183,6 +188,20 @@ class FakeCloudflare implements CloudflareClient {
   async listWorkerScripts(): Promise<WorkerScript[]> {
     return this.scripts;
   }
+  async listWorkerSecrets(workerName: string): Promise<string[]> {
+    this.secretQueries.push(workerName);
+    // Cloudflare answers 404 for a Worker that is not there. Wrangler used to hand that back as an
+    // empty list; it no longer does, and code that reads the failure as "no secrets" inverts the
+    // one check a first deployment depends on.
+    if (!this.scripts.some((script) => script.id === workerName)) {
+      throw new CloudflareApiError(
+        `Cloudflare API /workers/scripts/${workerName}/secrets failed: not found`,
+        404,
+        [10007],
+      );
+    }
+    return this.secrets[workerName] ?? [];
+  }
   async deleteWorkerScript(name: string): Promise<void> {
     this.mutations.push(`delete-worker:${name}`);
   }
@@ -397,11 +416,13 @@ describe('deploy-stage against live state', () => {
     expect(existsSync(requiredTestValue(runner.secretsPathSeen, 'secrets path'))).toBe(false);
   });
 
-  it('passes only present manifest values for fixed stages and preserves absent remote secrets', async () => {
+  it('sends only the values it has and leaves a secret the Worker already holds untouched', async () => {
     const root = await fixtureRoot();
     await writeFile(join(root, '.dev.vars.example'), 'FIXTURE_SECRET=""\nFIXTURE_TOKEN=""\n');
     const runner = new FakeRunner([], {});
     const cloudflare = new FakeCloudflare();
+    cloudflare.scripts = [{ id: 'fixture-worker-staging' }];
+    cloudflare.secrets['fixture-worker-staging'] = ['FIXTURE_TOKEN'];
 
     const result = await deployStage(
       root,
@@ -417,6 +438,8 @@ describe('deploy-stage against live state', () => {
       },
     );
 
+    // `--secrets-file` applies additively, so naming only what this shell has leaves FIXTURE_TOKEN
+    // exactly as the Worker holds it. That silence is only safe because the gate proved it is held.
     expect(result.action).toBe('deployed');
     expect(JSON.parse(requiredTestValue(runner.secretsJson, 'secrets JSON'))).toEqual({
       FIXTURE_SECRET: 'shared-secret',
@@ -467,6 +490,230 @@ describe('deploy-stage against live state', () => {
   });
 });
 
+/**
+ * `smoo.wrangler.secretStages` answers two questions from one declaration, and both are load
+ * bearing: which secrets a stage must have before it may deploy, and which secrets it is allowed
+ * to receive at all. The second direction is the security-relevant one — a capability CI exports
+ * for preview stages must not ride a production deploy just because the variable is set.
+ */
+describe('stage-scoped deployment secrets', () => {
+  const STAGED_FIXTURE = `${FIXTURE}
+[env.production]
+name = "fixture-worker-production"
+workers_dev = false
+
+[env.production.vars]
+ENVIRONMENT = "production"
+`;
+
+  async function scopedRoot(secrets: string[], secretStages?: Record<string, string[]>): Promise<string> {
+    const root = await fixtureRoot(STAGED_FIXTURE);
+    await writeFile(join(root, '.dev.vars.example'), secrets.map((name) => `${name}=""\n`).join(''));
+    if (secretStages) {
+      await writeFile(
+        join(root, 'package.json'),
+        `${JSON.stringify({ name: '@acme/api', smoo: { wrangler: { secretStages } } }, null, 2)}\n`,
+      );
+    }
+    return root;
+  }
+
+  function environment(values: Record<string, string> = {}): NodeJS.ProcessEnv {
+    return { CLOUDFLARE_ACCOUNT_ID: 'account-1', CLOUDFLARE_API_TOKEN: 'token', ...values };
+  }
+
+  it('refuses a first deploy whose stage-required secret is exported nowhere, naming every one', async () => {
+    const root = await scopedRoot(['SESSION_SECRET', 'OAUTH_STATE_KEY'], {
+      OAUTH_STATE_KEY: ['staging', 'production'],
+    });
+    const runner = new FakeRunner([], {});
+    const cloudflare = new FakeCloudflare();
+
+    await expect(
+      deployStage(root, { stage: 'production' }, { runner, cloudflare, processEnv: environment() }),
+    ).rejects.toThrow(
+      /Refusing to deploy fixture-worker-production to production[\s\S]*SESSION_SECRET[\s\S]*OAUTH_STATE_KEY/,
+    );
+    expect(cloudflare.mutations).toEqual([]);
+    expect(runner.calls).toEqual([]);
+  });
+
+  it('treats a Worker that is not there as holding nothing, never as needing nothing', async () => {
+    const root = await scopedRoot(['OAUTH_STATE_KEY']);
+    const cloudflare = new FakeCloudflare();
+
+    // The double answers 404 for an absent Worker, exactly as Cloudflare does. Reading that error
+    // as "no secrets" would let this deploy through; asking at all would surface the 404 instead
+    // of the refusal. Neither happens: the script listing already said the Worker holds nothing.
+    await expect(
+      deployStage(
+        root,
+        { stage: 'production' },
+        { runner: new FakeRunner([], {}), cloudflare, processEnv: environment() },
+      ),
+    ).rejects.toThrow(/Refusing to deploy fixture-worker-production to production[\s\S]*OAUTH_STATE_KEY/);
+    expect(cloudflare.secretQueries).toEqual([]);
+    expect(cloudflare.mutations).toEqual([]);
+  });
+
+  it('requires an unscoped secret of every stage, including a pull-request stage', async () => {
+    const root = await scopedRoot(['SESSION_SECRET'], { OTHER_SECRET: ['staging'] });
+    await writeFile(join(root, '.dev.vars.example'), 'SESSION_SECRET=""\nOTHER_SECRET=""\n');
+    const cloudflare = new FakeCloudflare();
+
+    await expect(
+      deployStage(root, { stage: 'pr77' }, dependencies(new FakeRunner([], {}), cloudflare)),
+    ).rejects.toThrow(/fixture-worker-pr77[\s\S]*SESSION_SECRET — unscoped, so every stage requires it/);
+    expect(cloudflare.mutations).toEqual([]);
+  });
+
+  it('does not require a preview-scoped secret of production', async () => {
+    const root = await scopedRoot(['E2E_CONTROL_TOKEN'], { E2E_CONTROL_TOKEN: ['staging', 'preview'] });
+    const runner = new FakeRunner([], {});
+    const cloudflare = new FakeCloudflare();
+
+    const result = await deployStage(root, { stage: 'production' }, { runner, cloudflare, processEnv: environment() });
+
+    expect(result).toMatchObject({ action: 'deployed', workerName: 'fixture-worker-production' });
+    expect(runner.secretsPathSeen).toBeUndefined();
+  });
+
+  it('withholds a preview-scoped secret from production even when the deploying shell exports it', async () => {
+    const root = await scopedRoot(['API_TOKEN', 'E2E_CONTROL_TOKEN'], { E2E_CONTROL_TOKEN: ['staging', 'preview'] });
+    const runner = new FakeRunner([], {});
+    const cloudflare = new FakeCloudflare();
+    // The real environment, because that is what a child process inherits and what the shell of a
+    // laptop deploy actually looks like when CI has exported a preview capability.
+    process.env.E2E_CONTROL_TOKEN = 'teardown-value';
+
+    try {
+      const result = await deployStage(
+        root,
+        { stage: 'production' },
+        {
+          runner,
+          cloudflare,
+          processEnv: environment({ API_TOKEN: 'api-value', E2E_CONTROL_TOKEN: 'teardown-value' }),
+        },
+      );
+
+      expect(result.action).toBe('deployed');
+      expect(JSON.parse(requiredTestValue(runner.secretsJson, 'secrets JSON'))).toEqual({ API_TOKEN: 'api-value' });
+      // Not in the payload, and not readable by the deploy either: the capability is absent from
+      // this stage at the process boundary, not merely left out of a file.
+      for (const call of runner.calls) {
+        expect(call.env.E2E_CONTROL_TOKEN).toBeUndefined();
+      }
+      expect(runner.calls.length).toBeGreaterThan(0);
+    } finally {
+      delete process.env.E2E_CONTROL_TOKEN;
+    }
+  });
+
+  it('sends a preview-scoped secret to the stages it is scoped to', async () => {
+    const scopes = { E2E_CONTROL_TOKEN: ['staging', 'preview'] };
+    const values = { API_TOKEN: 'api-value', E2E_CONTROL_TOKEN: 'teardown-value' };
+
+    for (const stage of ['staging', 'pr77'] as const) {
+      const root = await scopedRoot(['API_TOKEN', 'E2E_CONTROL_TOKEN'], scopes);
+      const runner = new FakeRunner([], {});
+
+      await deployStage(root, { stage }, { runner, cloudflare: new FakeCloudflare(), processEnv: environment(values) });
+
+      expect(JSON.parse(requiredTestValue(runner.secretsJson, `secrets JSON for ${stage}`))).toEqual(values);
+    }
+  });
+
+  it('treats an empty scope as no stage at all, not as every stage', async () => {
+    const root = await scopedRoot(['API_TOKEN', 'LOCAL_ONLY_KEY'], { LOCAL_ONLY_KEY: [] });
+    const runner = new FakeRunner([], {});
+
+    // `[]` and "absent from the map" are opposite declarations. A check written as
+    // `!scope?.length` would collapse them and ship a local-development value to every stage.
+    const result = await deployStage(
+      root,
+      { stage: 'production' },
+      {
+        runner,
+        cloudflare: new FakeCloudflare(),
+        processEnv: environment({ API_TOKEN: 'api-value', LOCAL_ONLY_KEY: 'laptop-value' }),
+      },
+    );
+
+    expect(result.action).toBe('deployed');
+    expect(JSON.parse(requiredTestValue(runner.secretsJson, 'secrets JSON'))).toEqual({ API_TOKEN: 'api-value' });
+  });
+
+  it('refuses when the Worker holds a secret this stage is scoped out of, since a deploy cannot remove it', async () => {
+    const root = await scopedRoot(['E2E_CONTROL_TOKEN'], { E2E_CONTROL_TOKEN: ['staging', 'preview'] });
+    const cloudflare = new FakeCloudflare();
+    cloudflare.scripts = [{ id: 'fixture-worker-production' }];
+    cloudflare.secrets['fixture-worker-production'] = ['E2E_CONTROL_TOKEN'];
+
+    await expect(
+      deployStage(
+        root,
+        { stage: 'production' },
+        { runner: new FakeRunner([], {}), cloudflare, processEnv: environment() },
+      ),
+    ).rejects.toThrow(/keeps out of production[\s\S]*E2E_CONTROL_TOKEN — scoped to staging, preview/);
+    expect(cloudflare.mutations).toEqual([]);
+  });
+
+  it('refuses a scope written against a name no secret has, rather than scoping nothing', async () => {
+    const root = await scopedRoot(['E2E_CONTROL_TOKEN'], { E2E_CONTROL_TOEKN: ['staging'] });
+
+    await expect(
+      deployStage(
+        root,
+        { stage: 'production' },
+        { runner: new FakeRunner([], {}), cloudflare: new FakeCloudflare(), processEnv: environment() },
+      ),
+    ).rejects.toThrow(/secretStages scopes E2E_CONTROL_TOEKN, which .dev.vars.example does not declare/);
+  });
+
+  it('names a malformed scope declaration by its path in the manifest', async () => {
+    const root = await scopedRoot(['E2E_CONTROL_TOKEN'], { E2E_CONTROL_TOKEN: ['pr7'] });
+
+    await expect(
+      deployStage(
+        root,
+        { stage: 'production' },
+        { runner: new FakeRunner([], {}), cloudflare: new FakeCloudflare(), processEnv: environment() },
+      ),
+    ).rejects.toThrow(
+      /package\.json declares an invalid smoo\.wrangler block: smoo\.wrangler\.secretStages\.E2E_CONTROL_TOKEN\[0\]/,
+    );
+  });
+
+  it('keeps every secret value out of the refusal and off every command line', async () => {
+    const root = await scopedRoot(['API_TOKEN', 'SESSION_SECRET']);
+    const runner = new FakeRunner([], {});
+    const cloudflare = new FakeCloudflare();
+
+    const refused = await deployStage(
+      root,
+      { stage: 'production' },
+      { runner, cloudflare, processEnv: environment({ API_TOKEN: 'api-value' }) },
+    ).catch((error: unknown) => (error instanceof Error ? error.message : String(error)));
+
+    expect(refused).toContain('SESSION_SECRET');
+    expect(refused).not.toContain('api-value');
+
+    // And the same on the path that does deploy: values reach wrangler through a 0600 file only.
+    cloudflare.scripts = [{ id: 'fixture-worker-production' }];
+    cloudflare.secrets['fixture-worker-production'] = ['SESSION_SECRET'];
+    await deployStage(
+      root,
+      { stage: 'production' },
+      { runner, cloudflare, processEnv: environment({ API_TOKEN: 'api-value' }) },
+    );
+
+    expect(runner.calls.flatMap((call) => call.args).join('\u0000')).not.toContain('api-value');
+    expect(JSON.parse(requiredTestValue(runner.secretsJson, 'secrets JSON'))).toEqual({ API_TOKEN: 'api-value' });
+  });
+});
+
 describe('cleanup-pr exact stage matching', () => {
   it('rejects an invalid PR before touching the client', async () => {
     const cloudflare = new FakeCloudflare();
@@ -837,7 +1084,7 @@ describe('deployStage with a flat JSON config', () => {
 
     await expect(
       deployStage(root, { stage: 'pr7', config: configPath }, dependencies(new FakeRunner(), cloudflare)),
-    ).rejects.toThrow(/requires process environment values/);
+    ).rejects.toThrow(/Refusing to deploy fixture-website-preview-pr7 to pr7[\s\S]*FIXTURE_SECRET/);
     expect(cloudflare.mutations).toEqual([]);
   });
 

package/src/wrangler/deploy-stage.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
 import { readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { parseJsonFileText } from '../lib/json.js';
@@ -16,7 +15,6 @@ import {
   type VersionEndpointWaitOptions,
   writeCachedLiveVersion,
 } from './live-version.js';
-import { parseDevVarsExample } from './prepare-env.js';
 import {
   type ConfiguredStageResourcePlan,
   type DeploymentStage,
@@ -32,6 +30,13 @@ import {
   planPullRequestResources,
   pullRequestStage,
 } from './stage.js';
+import {
+  planStageSecrets,
+  readDeclaredSecretNames,
+  readSecretStageMap,
+  type StageSecretPlan,
+  stageSecretRefusal,
+} from './stage-secrets.js';
 
 export interface ProcessResult {
   exitCode: number;
@@ -118,20 +123,25 @@ export async function deployStage(
     dependencies.cloudflare ??
     new CloudflareRestClient(accountId, requiredEnvironmentValue(apiToken, 'CLOUDFLARE_API_TOKEN'));
   const runner = dependencies.runner ?? new BunProcessRunner();
-  const secretNames = readSecretNames(cwd);
+  const secretPlan = planStageSecrets(readDeclaredSecretNames(cwd), stage, readSecretStageMap(cwd));
+  // Only the stage's own secrets, and only the ones a value exists for. A secret scoped to other
+  // stages is dropped here even when this shell exports it: that is the whole permission rule.
   const secretValues: Record<string, string> = {};
-  for (const name of secretNames) {
+  for (const name of secretPlan.required) {
     const value = processEnv[name];
     if (value) secretValues[name] = value;
   }
-  const missingSecrets = secretNames.filter((name) => !processEnv[name]);
+  const gate = stageSecretGate(secretPlan, new Set(Object.keys(secretValues)), cloudflare);
   let temporaryConfigPath: string | undefined;
   let temporarySecretsPath: string | undefined;
   try {
     const prepared = options.config
-      ? await prepareFlatConfig(options.config, stage, accountId, missingSecrets, cloudflare)
-      : await prepareTomlConfig(cwd, stage, accountId, missingSecrets, cloudflare);
+      ? await prepareFlatConfig(options.config, stage, accountId, gate, cloudflare)
+      : await prepareTomlConfig(cwd, stage, accountId, gate, cloudflare);
     temporaryConfigPath = prepared.temporaryConfigPath;
+    // The pull-request path already ran this before provisioning; the gate answers once per Worker.
+    // Everything below here writes to Cloudflare.
+    await gate(prepared.plan.workerName);
     const workerExists = await reconcileStageResources(prepared.plan, cloudflare);
     const versionTag = nxTaskVersionTag(processEnv);
     const envArgs = prepared.envFlag ? ['--env', prepared.envFlag] : [];
@@ -139,7 +149,13 @@ export async function deployStage(
     // renames the worker `<name>-<CLOUDFLARE_ENV>`. The build that produced the flat config is the
     // caller that sets the variable, so the deploy would silently succeed under a name neither
     // `reconcileStageResources` nor `versions list` looks at.
-    const run: ProcessRunOptions = prepared.envFlag ? { cwd } : { cwd, unsetEnv: ['CLOUDFLARE_ENV'] };
+    //
+    // A secret this stage is scoped out of goes with it. Leaving it out of the secrets payload is
+    // what stops it being installed; withholding it from the child as well means the deploy cannot
+    // read it at all, so "this stage never sees that capability" holds at the process boundary and
+    // not merely in the file we happen to write.
+    const unsetEnv = [...(prepared.envFlag ? [] : ['CLOUDFLARE_ENV']), ...secretPlan.withheld];
+    const run: ProcessRunOptions = unsetEnv.length > 0 ? { cwd, unsetEnv } : { cwd };
     const workerName = prepared.plan.workerName;
     const probe: LiveVersionProbe = {
       deployments: () => wranglerJson(runner, ['deployments', 'status', '--name', workerName, '--json'], run),
@@ -228,7 +244,7 @@ async function prepareTomlConfig(
   cwd: string,
   stage: DeploymentStage,
   accountId: string,
-  missingSecrets: string[],
+  gate: SecretGate,
   cloudflare: CloudflareClient,
 ): Promise<PreparedConfig> {
   const committedConfigPath = join(cwd, 'wrangler.toml');
@@ -243,12 +259,7 @@ async function prepareTomlConfig(
   }
   const liveNamespaces = await cloudflare.listKvNamespaces();
   const plan = planPullRequestResources(committedToml, stage, liveNamespaces);
-  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(
-    plan,
-    missingSecrets,
-    cloudflare,
-    liveNamespaces,
-  );
+  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(plan, gate, cloudflare, liveNamespaces);
   const derivedToml = derivePullRequestWranglerConfig(committedToml, {
     stage,
     accountId,
@@ -270,7 +281,7 @@ async function prepareFlatConfig(
   configPath: string,
   stage: DeploymentStage,
   accountId: string,
-  missingSecrets: string[],
+  gate: SecretGate,
   cloudflare: CloudflareClient,
 ): Promise<PreparedConfig> {
   const flat = parseJsonFileText(configPath, await readFile(configPath, 'utf8'), parseFlatWranglerConfig);
@@ -283,12 +294,7 @@ async function prepareFlatConfig(
   }
   const liveNamespaces = await cloudflare.listKvNamespaces();
   const plan = planPullRequestBindings(flat, stage, liveNamespaces);
-  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(
-    plan,
-    missingSecrets,
-    cloudflare,
-    liveNamespaces,
-  );
+  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(plan, gate, cloudflare, liveNamespaces);
   const derived = derivePullRequestStageConfig(flat, { stage, accountId, kvNamespaceIds, d1DatabaseIds });
   // Beside the original: its main/assets/migrations paths are relative to the file.
   const temporaryConfigPath = join(dirname(configPath), `.wrangler.smoo-${process.pid}-${randomUUID()}.json`);
@@ -322,27 +328,58 @@ function migrationBindings(config: FlatWranglerConfig): string[] {
     .map((database) => database.binding);
 }
 
-async function refuseFirstDeploymentWithoutSecrets(
+/**
+ * Asks, of one Worker, whether this stage may deploy at all. Called at each path's last read
+ * before its first write, so a refusal costs nothing: the pull-request path provisions KV and D1
+ * inside config preparation, and every path reconciles buckets, routes and DNS after it. A
+ * refusal arriving later would strand resources created for a deploy that was never allowed.
+ */
+type SecretGate = (workerName: string) => Promise<void>;
+
+/**
+ * One answer per Worker, reused by both call sites so the read costs one round trip.
+ *
+ * What the Worker holds comes from the account's script listing first. A Worker absent from it
+ * holds nothing — exactly the first-deployment case — and Cloudflare answers 404 rather than an
+ * empty list when asked for a missing Worker's secrets. Reading that failure as "then nothing is
+ * needed" would disarm the check at the one moment it matters most, so it is never asked.
+ */
+function stageSecretGate(
+  plan: StageSecretPlan,
+  exported: ReadonlySet<string>,
+  cloudflare: CloudflareClient,
+): SecretGate {
+  const answered = new Map<string, Promise<void>>();
+  return (workerName) => {
+    let pending = answered.get(workerName);
+    if (!pending) {
+      pending = assertStageSecrets(plan, exported, cloudflare, workerName);
+      answered.set(workerName, pending);
+    }
+    return pending;
+  };
+}
+
+async function assertStageSecrets(
+  plan: StageSecretPlan,
+  exported: ReadonlySet<string>,
   cloudflare: CloudflareClient,
   workerName: string,
-  missingSecrets: string[],
 ): Promise<void> {
-  const firstDeployment = !(await cloudflare.listWorkerScripts()).some((script) => script.id === workerName);
-  if (firstDeployment && missingSecrets.length > 0) {
-    throw new Error(
-      `First deployment of ${workerName} requires process environment values for: ${missingSecrets.join(', ')}.`,
-    );
-  }
+  const live = (await cloudflare.listWorkerScripts()).some((script) => script.id === workerName);
+  const held = new Set(live ? await cloudflare.listWorkerSecrets(workerName) : []);
+  const refusal = stageSecretRefusal(plan, exported, held, workerName);
+  if (refusal) throw new Error(refusal);
 }
 
-/** Isolation refusals already ran in the plan; this is the first Cloudflare write. */
+/** Isolation refusals already ran in the plan; the gate below is the last one before the first write. */
 async function provisionPullRequestResources(
   plan: PullRequestResourcePlan,
-  missingSecrets: string[],
+  gate: SecretGate,
   cloudflare: CloudflareClient,
   liveNamespaces: LiveKvNamespace[],
 ): Promise<{ kvNamespaceIds: Map<string, string>; d1DatabaseIds: Map<string, string> }> {
-  await refuseFirstDeploymentWithoutSecrets(cloudflare, plan.workerName, missingSecrets);
+  await gate(plan.workerName);
   const kvNamespaceIds = await ensureKvNamespaces(plan.kvNamespaces, liveNamespaces, cloudflare);
   const d1DatabaseIds =
     plan.d1Databases.length === 0
@@ -669,8 +706,3 @@ function requiredEnvironmentValue(value: string | undefined, name: string): stri
   if (!value) throw new Error(`${name} is required.`);
   return value;
 }
-
-function readSecretNames(cwd: string): string[] {
-  const path = join(cwd, '.dev.vars.example');
-  return existsSync(path) ? parseDevVarsExample(readFileSync(path, 'utf8')) : [];
-}

package/src/wrangler/stage-secrets.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import typia from 'typia';
+import { formatValidationErrors, parseJsonFileText } from '../lib/json.js';
+import { parseDevVarsExample } from './prepare-env.js';
+import { type DeploymentStage, isPullRequestStage } from './stage.js';
+
+/**
+ * How a declaration names a stage. The fixed stages go by their own name; every `prN` stage is
+ * `preview`, because a scope is written once and pull-request numbers are not knowable in advance.
+ */
+export type SecretStageScope = 'staging' | 'production' | 'preview';
+
+/**
+ * `smoo.wrangler.secretStages`: a declared secret name mapped to the stages it belongs to. The map
+ * answers two questions with one declaration, and both directions matter:
+ *
+ * - requirement — a stage the secret belongs to refuses to deploy without a value for it;
+ * - permission — a stage the secret does *not* belong to never receives it, however loudly the
+ *   deploying shell exports it. A test-only capability exported by CI for preview stages must not
+ *   ride along into production just because the variable happens to be set.
+ *
+ * A declared name absent from the map belongs to every stage. A name mapped to `[]` belongs to no
+ * stage, which is how a value that exists only for local development is declared.
+ */
+export type SecretStageMap = Record<string, SecretStageScope[]>;
+
+/** The one block of a project's package.json this reader needs; every other field is ignored. */
+interface WranglerPackageManifest {
+  smoo?: {
+    wrangler?: {
+      secretStages?: SecretStageMap;
+    };
+  };
+}
+
+const validateWranglerManifest = typia.json.createValidateParse<WranglerPackageManifest>();
+
+/** Secret NAMES the project declares. Values live on the Worker; the repo only ever holds the keys. */
+export function readDeclaredSecretNames(cwd: string): string[] {
+  const path = join(cwd, '.dev.vars.example');
+  return existsSync(path) ? parseDevVarsExample(readFileSync(path, 'utf8')) : [];
+}
+
+/** `smoo.wrangler.secretStages` from the project's package.json; no file and no block scope nothing. */
+export function readSecretStageMap(cwd: string): SecretStageMap {
+  const path = join(cwd, 'package.json');
+  if (!existsSync(path)) return {};
+  const result = parseJsonFileText(path, readFileSync(path, 'utf8'), validateWranglerManifest);
+  if (!result.success) {
+    throw new Error(`${path} declares an invalid smoo.wrangler block: ${formatValidationErrors(result.errors)}`);
+  }
+  return result.data.smoo?.wrangler?.secretStages ?? {};
+}
+
+/** Which of a project's declared secrets one stage may see, and which belong to other stages. */
+export interface StageSecretPlan {
+  stage: DeploymentStage;
+  /** Declared names this stage requires — and the only ones a deploy of it may carry. */
+  required: string[];
+  /** Declared names scoped to other stages: withheld from this deploy even when a value is exported. */
+  withheld: string[];
+  /** The declaration itself, so a refusal can say why each name is where it is. */
+  scopes: SecretStageMap;
+}
+
+/**
+ * Splits the declared secrets by whether `stage` is in scope for each.
+ *
+ * A scope on an undeclared name is refused rather than ignored: it is almost always a typo of a
+ * real secret's name, and its effect is the dangerous direction — the misspelt entry scopes
+ * nothing while the real secret, still absent from the map, reaches every stage.
+ */
+export function planStageSecrets(declared: string[], stage: DeploymentStage, scopes: SecretStageMap): StageSecretPlan {
+  const declaredNames = new Set(declared);
+  const undeclared = Object.keys(scopes).filter((name) => !declaredNames.has(name));
+  if (undeclared.length > 0) {
+    throw new Error(
+      `smoo.wrangler.secretStages scopes ${undeclared.join(', ')}, which .dev.vars.example does not declare. ` +
+        'A scope on a name no secret has leaves the secret it was meant for unscoped, so that secret reaches every stage.',
+    );
+  }
+  // Every `prN` stage answers to one written token: a scope cannot name pull requests in advance.
+  const scope: SecretStageScope = isPullRequestStage(stage) ? 'preview' : stage;
+  const required: string[] = [];
+  const withheld: string[] = [];
+  for (const name of declared) {
+    const declaredScope = scopes[name];
+    if (declaredScope === undefined || declaredScope.includes(scope)) {
+      required.push(name);
+    } else {
+      withheld.push(name);
+    }
+  }
+  return { stage, required, withheld, scopes };
+}
+
+/**
+ * Why this deploy must not proceed, or nothing when it may.
+ *
+ * Two refusals, reported together so one run names every problem:
+ *
+ * - a required secret with no value anywhere. `--secrets-file` applies additively, so a deploy
+ *   that never mentions a secret leaves whatever the Worker already holds — silence that reads as
+ *   success while a secret introduced after the first deploy never arrives, and the code that
+ *   needs it fails at runtime instead of here.
+ * - a withheld secret the Worker already holds. Filtering it out of this deploy's payload cannot
+ *   remove it, so the scope would be nominal rather than enforced until someone deletes it.
+ *
+ * A value is never read, never formatted, and never named beyond its key.
+ */
+export function stageSecretRefusal(
+  plan: StageSecretPlan,
+  exported: ReadonlySet<string>,
+  held: ReadonlySet<string>,
+  workerName: string,
+): string | undefined {
+  const unavailable = plan.required.filter((name) => !exported.has(name) && !held.has(name));
+  const installed = plan.withheld.filter((name) => held.has(name));
+  if (unavailable.length === 0 && installed.length === 0) return undefined;
+  const lines = [`Refusing to deploy ${workerName} to ${plan.stage}.`];
+  if (unavailable.length > 0) {
+    lines.push(
+      `Stage ${plan.stage} requires these secrets and no value exists for them, neither in this environment nor on the Worker:`,
+      ...unavailable.map((name) => `  ${name} — ${scopeDescription(name, plan.scopes)}`),
+      'Export each one in the deploying shell before the deploy. Once the Worker exists,',
+      `\`wrangler secret put <NAME> --name ${workerName}\` supplies it too.`,
+    );
+  }
+  if (installed.length > 0) {
+    lines.push(
+      `The Worker holds these secrets, which smoo.wrangler.secretStages keeps out of ${plan.stage}:`,
+      ...installed.map((name) => `  ${name} — ${scopeDescription(name, plan.scopes)}`),
+      `Delete each one with \`wrangler secret delete <NAME> --name ${workerName}\`. A deploy of this stage`,
+      'never sends them, so leaving them installed would keep the scope nominal.',
+    );
+  }
+  return lines.join('\n');
+}
+
+function scopeDescription(name: string, scopes: SecretStageMap): string {
+  const scope = scopes[name];
+  if (scope === undefined) return 'unscoped, so every stage requires it';
+  if (scope.length === 0) return 'scoped to no stage (local development only)';
+  return `scoped to ${scope.join(', ')}`;
+}