@marcusrbrown/infra 0.12.1 → 0.12.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcusrbrown/infra",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
   "keywords": [
     "infra",

package/src/commands/dashboard/deploy.test.ts

@@ -11,7 +11,6 @@ const envKeys = [
   'SSH_AUTH_SOCK',
   'DASHBOARD_DOMAIN',
   'DASHBOARD_SSH_KEY',
-  'DASHBOARD_IMAGE_DIGEST',
   'DASHBOARD_GITHUB_APP_ID',
   'DASHBOARD_GITHUB_APP_KEY',
   'DASHBOARD_OAUTH_CLIENT_ID',
@@ -135,7 +134,6 @@ describe('getDashboardDeployEnv', () => {
       HOME: '/home/user',
       SSH_AUTH_SOCK: '/tmp/ssh-agent.sock',
       DASHBOARD_DOMAIN: 'dashboard.fro.bot',
-      DASHBOARD_IMAGE_DIGEST: `sha256:${'a'.repeat(64)}`,
       DASHBOARD_GITHUB_APP_ID: '123456',
       DASHBOARD_GITHUB_APP_KEY: '-----BEGIN RSA PRIVATE KEY-----\nfake\n-----END RSA PRIVATE KEY-----',
       DASHBOARD_OAUTH_CLIENT_ID: 'Iv1.abc123',
@@ -148,7 +146,6 @@ describe('getDashboardDeployEnv', () => {
 
     // All DASHBOARD_* vars must be present in the returned env
     expect(env.DASHBOARD_DOMAIN).toBe('dashboard.fro.bot')
-    expect(env.DASHBOARD_IMAGE_DIGEST).toBe(`sha256:${'a'.repeat(64)}`)
     expect(env.DASHBOARD_GITHUB_APP_ID).toBe('123456')
     expect(env.DASHBOARD_OAUTH_CLIENT_ID).toBe('Iv1.abc123')
     expect(env.DASHBOARD_OAUTH_CLIENT_SECRET).toBe('oauthsecret')

package/src/commands/dashboard/deploy.ts

@@ -35,9 +35,9 @@ export function getDashboardDeployEnv(): Record<string, string> {
     )
   }
 
-  // Spread all of process.env so DASHBOARD_* vars (IMAGE_DIGEST, GITHUB_APP_ID, etc.)
+  // Spread all of process.env so DASHBOARD_* vars (GITHUB_APP_ID, OAUTH_CLIENT_ID, etc.)
   // are forwarded to the spawned deploy.ts process. validateEnv in deploy.ts requires
-  // all DASHBOARD_* vars to be present — a selective subset would cause it to fail.
+  // all DASHBOARD_* credential vars to be present — a selective subset would cause it to fail.
   // Filter out undefined values (Record<string, string> does not allow undefined).
   const fullEnv: Record<string, string> = {}
   for (const [k, v] of Object.entries(process.env)) {

package/src/commands/gateway/deploy.ts

@@ -58,6 +58,20 @@ export function getGatewayDeployEnv(): Record<string, string> {
     GATEWAY_TRIGGER_ROLE_ID: process.env.GATEWAY_TRIGGER_ROLE_ID ?? '',
     GATEWAY_WEBHOOK_SECRET: process.env.GATEWAY_WEBHOOK_SECRET ?? '',
     GATEWAY_PRESENCE_CHANNEL_ID: process.env.GATEWAY_PRESENCE_CHANNEL_ID ?? '',
+    GATEWAY_OPERATOR_BIND_HOST: process.env.GATEWAY_OPERATOR_BIND_HOST ?? '',
+    GATEWAY_OPERATOR_BIND_PORT: process.env.GATEWAY_OPERATOR_BIND_PORT ?? '',
+    GATEWAY_OPERATOR_PUBLIC_ORIGIN: process.env.GATEWAY_OPERATOR_PUBLIC_ORIGIN ?? '',
+    GATEWAY_OPERATOR_GITHUB_CLIENT_ID: process.env.GATEWAY_OPERATOR_GITHUB_CLIENT_ID ?? '',
+    GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET: process.env.GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET ?? '',
+    GATEWAY_OPERATOR_CSRF_SECRET: process.env.GATEWAY_OPERATOR_CSRF_SECRET ?? '',
+    GATEWAY_OPERATOR_ALLOWLIST: process.env.GATEWAY_OPERATOR_ALLOWLIST ?? '',
+    GATEWAY_OPERATOR_OAUTH_ALLOWED_RETURN_PATHS: process.env.GATEWAY_OPERATOR_OAUTH_ALLOWED_RETURN_PATHS ?? '',
+    GATEWAY_OPERATOR_OAUTH_STATE_TTL_MS: process.env.GATEWAY_OPERATOR_OAUTH_STATE_TTL_MS ?? '',
+    GATEWAY_OPERATOR_OAUTH_MAX_OUTSTANDING_ATTEMPTS: process.env.GATEWAY_OPERATOR_OAUTH_MAX_OUTSTANDING_ATTEMPTS ?? '',
+    GATEWAY_VPC_IP: process.env.GATEWAY_VPC_IP ?? '',
+    DASHBOARD_VPC_IP: process.env.DASHBOARD_VPC_IP ?? '',
+    GATEWAY_IMAGE_DIGEST: process.env.GATEWAY_IMAGE_DIGEST ?? '',
+    WORKSPACE_IMAGE_DIGEST: process.env.WORKSPACE_IMAGE_DIGEST ?? '',
   }
 }
 

package/src/conventions.test.ts

@@ -440,6 +440,35 @@ describe('per-app invariants', () => {
     // SHA verification is wired in and was not accidentally stripped.
     expect(buildTs).toMatch(/const\s+EXPECTED_SHA256\s*=/)
   })
+
+  it('deploy-gateway.yaml does NOT install doctl (firewall is provisioning-only, not deploy-time)', async () => {
+    const text = await Bun.file(resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')).text()
+    // The DO Cloud Firewall is created in provisioning (provision-droplet.ts), not in the deploy hot path.
+    // The deploy job must NOT install doctl — it no longer needs it.
+    expect(text).not.toMatch(/uses:\s+digitalocean\/action-doctl@[a-f0-9]{40}/)
+    expect(text).not.toContain('digitalocean/action-doctl')
+  })
+
+  it('deploy-gateway.yaml does NOT forward DIGITALOCEAN_ACCESS_TOKEN to the deploy step', async () => {
+    const text = await Bun.file(resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')).text()
+    // DIGITALOCEAN_ACCESS_TOKEN is only needed for provisioning, not for the deploy hot path.
+    // Verify it is not forwarded to the deploy step env block.
+    const deployStepIndex = text.indexOf('name: Deploy gateway')
+    expect(deployStepIndex).toBeGreaterThan(-1)
+    const afterDeployStep = text.slice(deployStepIndex)
+    expect(afterDeployStep).not.toContain('DIGITALOCEAN_ACCESS_TOKEN')
+  })
+
+  it('deploy-gateway.yaml still forwards GATEWAY_VPC_IP and DASHBOARD_VPC_IP to the deploy step', async () => {
+    const text = await Bun.file(resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')).text()
+    // GATEWAY_VPC_IP and DASHBOARD_VPC_IP are still needed by deploy.ts for the compose VPC-IP
+    // publish and the DOCKER-USER iptables rule.
+    const deployStepIndex = text.indexOf('name: Deploy gateway')
+    expect(deployStepIndex).toBeGreaterThan(-1)
+    const afterDeployStep = text.slice(deployStepIndex)
+    expect(afterDeployStep).toContain('GATEWAY_VPC_IP')
+    expect(afterDeployStep).toContain('DASHBOARD_VPC_IP')
+  })
 })
 
 describe('findCrossOrgSecretsInherit', () => {
@@ -644,3 +673,508 @@ describe('dorny/paths-filter quantifier guard', () => {
     expect(violations).toEqual([])
   })
 })
+
+// ─── operator auth/config secrets and tuning vars ────────────────────────────
+//
+// These assert the four operator auth/config secrets and three optional tuning vars are
+// wired through deploy-gateway.yaml (workflow_call.secrets + inputs + deploy step env),
+// deploy.yaml (fan-out secrets + with inputs), and the CLI passthrough.
+
+const OPERATOR_AUTH_SECRETS = [
+  'GATEWAY_OPERATOR_GITHUB_CLIENT_ID',
+  'GATEWAY_OPERATOR_GITHUB_CLIENT_SECRET',
+  'GATEWAY_OPERATOR_CSRF_SECRET',
+  'GATEWAY_OPERATOR_ALLOWLIST',
+] as const
+
+const OPERATOR_TUNING_SECRETS = [
+  'GATEWAY_OPERATOR_OAUTH_ALLOWED_RETURN_PATHS',
+  'GATEWAY_OPERATOR_OAUTH_STATE_TTL_MS',
+  'GATEWAY_OPERATOR_OAUTH_MAX_OUTSTANDING_ATTEMPTS',
+] as const
+
+describe('deploy-gateway.yaml: operator auth/config secrets in workflow_call.secrets', () => {
+  const DEPLOY_GATEWAY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')
+
+  for (const secret of OPERATOR_AUTH_SECRETS) {
+    it(`workflow_call.secrets declares ${secret} as optional (required: false)`, async () => {
+      const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+      const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]?.required).toBe(false)
+    })
+  }
+})
+
+describe('deploy-gateway.yaml: operator tuning vars in workflow_call.secrets', () => {
+  const DEPLOY_GATEWAY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')
+
+  for (const secret of OPERATOR_TUNING_SECRETS) {
+    it(`workflow_call.secrets declares ${secret} as optional (required: false)`, async () => {
+      const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+      const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]?.required).toBe(false)
+    })
+  }
+
+  it('workflow_call.inputs does NOT declare any GATEWAY_OPERATOR_OAUTH_ tuning vars', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {on?: {workflow_call?: {inputs?: Record<string, unknown>}}}
+    const inputs = parsed?.on?.workflow_call?.inputs ?? {}
+    for (const secret of OPERATOR_TUNING_SECRETS) {
+      expect(inputs).not.toHaveProperty(secret)
+    }
+  })
+})
+
+describe('deploy-gateway.yaml: deploy step env forwards operator auth/config vars', () => {
+  const DEPLOY_GATEWAY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')
+
+  for (const secret of OPERATOR_AUTH_SECRETS) {
+    it(`Deploy gateway step env forwards ${secret}`, async () => {
+      const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-gateway'?: {steps?: {name?: string; env?: Record<string, string>}[]}}
+      }
+      const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+      const deployStep = steps.find(s => s.name === 'Deploy gateway')
+      expect(deployStep).toBeDefined()
+      expect(deployStep?.env).toHaveProperty(secret)
+      expect(deployStep?.env?.[secret]).toContain(secret)
+    })
+  }
+
+  for (const secret of OPERATOR_TUNING_SECRETS) {
+    it(`Deploy gateway step env forwards ${secret} from secrets context (not inputs)`, async () => {
+      const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-gateway'?: {steps?: {name?: string; env?: Record<string, string>}[]}}
+      }
+      const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+      const deployStep = steps.find(s => s.name === 'Deploy gateway')
+      expect(deployStep).toBeDefined()
+      expect(deployStep?.env).toHaveProperty(secret)
+      // Must source from secrets context, not inputs context
+      expect(deployStep?.env?.[secret]).toMatch(/\$\{\{\s*secrets\./)
+    })
+  }
+})
+
+describe('deploy.yaml: fan-out passes operator auth/config secrets to deploy-gateway job', () => {
+  const DEPLOY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy.yaml')
+
+  for (const secret of OPERATOR_AUTH_SECRETS) {
+    it(`deploy-gateway job secrets block passes ${secret}`, async () => {
+      const text = await Bun.file(DEPLOY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-gateway'?: {secrets?: Record<string, string>}}
+      }
+      const secrets = parsed?.jobs?.['deploy-gateway']?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]).toContain(secret)
+    })
+  }
+})
+
+describe('deploy.yaml: fan-out passes operator tuning vars via secrets: to deploy-gateway job', () => {
+  const DEPLOY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy.yaml')
+
+  for (const secret of OPERATOR_TUNING_SECRETS) {
+    it(`deploy-gateway job secrets block passes ${secret}`, async () => {
+      const text = await Bun.file(DEPLOY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-gateway'?: {secrets?: Record<string, string>}}
+      }
+      const secrets = parsed?.jobs?.['deploy-gateway']?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]).toContain(secret)
+    })
+  }
+
+  it('deploy-gateway job does NOT have a with: block for GATEWAY_OPERATOR_OAUTH_ tuning vars', async () => {
+    const text = await Bun.file(DEPLOY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {'deploy-gateway'?: {with?: Record<string, unknown>}}
+    }
+    const withBlock = parsed?.jobs?.['deploy-gateway']?.with ?? {}
+    for (const secret of OPERATOR_TUNING_SECRETS) {
+      expect(withBlock).not.toHaveProperty(secret)
+    }
+  })
+})
+
+describe('CLI getGatewayDeployEnv: operator auth/config passthrough', () => {
+  it('getGatewayDeployEnv includes all four operator auth/config secret vars', async () => {
+    const {getGatewayDeployEnv} = await import('./commands/gateway/deploy')
+    // Provide required env vars
+    const origEnv = {...process.env}
+    process.env.PATH = '/usr/bin'
+    process.env.HOME = '/home/test'
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh.sock'
+    try {
+      const env = getGatewayDeployEnv()
+      for (const secret of OPERATOR_AUTH_SECRETS) {
+        expect(env).toHaveProperty(secret)
+      }
+    } finally {
+      Object.assign(process.env, origEnv)
+    }
+  })
+
+  it('getGatewayDeployEnv includes all three operator tuning vars', async () => {
+    const {getGatewayDeployEnv} = await import('./commands/gateway/deploy')
+    const origEnv = {...process.env}
+    process.env.PATH = '/usr/bin'
+    process.env.HOME = '/home/test'
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh.sock'
+    try {
+      const env = getGatewayDeployEnv()
+      for (const secret of OPERATOR_TUNING_SECRETS) {
+        expect(env).toHaveProperty(secret)
+      }
+    } finally {
+      Object.assign(process.env, origEnv)
+    }
+  })
+
+  it('getGatewayDeployEnv includes GATEWAY_IMAGE_DIGEST', async () => {
+    const {getGatewayDeployEnv} = await import('./commands/gateway/deploy')
+    const origEnv = {...process.env}
+    process.env.PATH = '/usr/bin'
+    process.env.HOME = '/home/test'
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh.sock'
+    process.env.GATEWAY_IMAGE_DIGEST = 'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
+    try {
+      const env = getGatewayDeployEnv()
+      expect(env).toHaveProperty('GATEWAY_IMAGE_DIGEST')
+      expect(env.GATEWAY_IMAGE_DIGEST).toBe('sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')
+    } finally {
+      Object.assign(process.env, origEnv)
+    }
+  })
+
+  it('getGatewayDeployEnv includes WORKSPACE_IMAGE_DIGEST', async () => {
+    const {getGatewayDeployEnv} = await import('./commands/gateway/deploy')
+    const origEnv = {...process.env}
+    process.env.PATH = '/usr/bin'
+    process.env.HOME = '/home/test'
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh.sock'
+    process.env.WORKSPACE_IMAGE_DIGEST = 'sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
+    try {
+      const env = getGatewayDeployEnv()
+      expect(env).toHaveProperty('WORKSPACE_IMAGE_DIGEST')
+      expect(env.WORKSPACE_IMAGE_DIGEST).toBe('sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb')
+    } finally {
+      Object.assign(process.env, origEnv)
+    }
+  })
+
+  it('getGatewayDeployEnv includes GATEWAY_VPC_IP and DASHBOARD_VPC_IP (but NOT DIGITALOCEAN_ACCESS_TOKEN)', async () => {
+    const {getGatewayDeployEnv} = await import('./commands/gateway/deploy')
+    const origEnv = {...process.env}
+    process.env.PATH = '/usr/bin'
+    process.env.HOME = '/home/test'
+    process.env.SSH_AUTH_SOCK = '/tmp/ssh.sock'
+    try {
+      const env = getGatewayDeployEnv()
+      // VPC IPs are still needed by deploy.ts for compose publish + DOCKER-USER rule
+      expect(env).toHaveProperty('GATEWAY_VPC_IP')
+      expect(env).toHaveProperty('DASHBOARD_VPC_IP')
+      // DIGITALOCEAN_ACCESS_TOKEN is provisioning-only — must NOT be in the deploy env
+      expect(env).not.toHaveProperty('DIGITALOCEAN_ACCESS_TOKEN')
+    } finally {
+      Object.assign(process.env, origEnv)
+    }
+  })
+})
+
+// ─── deploy.yaml: aggregate router passes operator secrets to deploy-gateway ──
+
+describe('deploy.yaml: aggregate router forwards operator secrets to deploy-gateway job', () => {
+  const DEPLOY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy.yaml')
+
+  it('deploy-gateway job secrets block passes GATEWAY_OPERATOR_BIND_HOST', async () => {
+    const text = await Bun.file(DEPLOY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          secrets?: Record<string, string>
+        }
+      }
+    }
+    const secrets = parsed?.jobs?.['deploy-gateway']?.secrets ?? {}
+    expect(secrets).toHaveProperty('GATEWAY_OPERATOR_BIND_HOST')
+    expect(secrets.GATEWAY_OPERATOR_BIND_HOST).toContain('GATEWAY_OPERATOR_BIND_HOST')
+  })
+
+  it('deploy-gateway job secrets block passes GATEWAY_OPERATOR_BIND_PORT', async () => {
+    const text = await Bun.file(DEPLOY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          secrets?: Record<string, string>
+        }
+      }
+    }
+    const secrets = parsed?.jobs?.['deploy-gateway']?.secrets ?? {}
+    expect(secrets).toHaveProperty('GATEWAY_OPERATOR_BIND_PORT')
+    expect(secrets.GATEWAY_OPERATOR_BIND_PORT).toContain('GATEWAY_OPERATOR_BIND_PORT')
+  })
+
+  it('deploy-gateway job secrets block passes GATEWAY_OPERATOR_PUBLIC_ORIGIN', async () => {
+    const text = await Bun.file(DEPLOY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          secrets?: Record<string, string>
+        }
+      }
+    }
+    const secrets = parsed?.jobs?.['deploy-gateway']?.secrets ?? {}
+    expect(secrets).toHaveProperty('GATEWAY_OPERATOR_PUBLIC_ORIGIN')
+    expect(secrets.GATEWAY_OPERATOR_PUBLIC_ORIGIN).toContain('GATEWAY_OPERATOR_PUBLIC_ORIGIN')
+  })
+})
+
+// ─── deploy-gateway.yaml: optional operator secret declarations ───────────────
+
+describe('deploy-gateway.yaml: optional operator secret declarations (issue 1)', () => {
+  const DEPLOY_GATEWAY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')
+
+  it('workflow_call.secrets declares GATEWAY_OPERATOR_BIND_HOST as optional', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+    const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+    expect(secrets).toHaveProperty('GATEWAY_OPERATOR_BIND_HOST')
+    expect(secrets.GATEWAY_OPERATOR_BIND_HOST?.required).toBe(false)
+  })
+
+  it('workflow_call.secrets declares GATEWAY_OPERATOR_BIND_PORT as optional', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+    const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+    expect(secrets).toHaveProperty('GATEWAY_OPERATOR_BIND_PORT')
+    expect(secrets.GATEWAY_OPERATOR_BIND_PORT?.required).toBe(false)
+  })
+
+  it('workflow_call.secrets declares GATEWAY_OPERATOR_PUBLIC_ORIGIN as optional', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+    const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+    expect(secrets).toHaveProperty('GATEWAY_OPERATOR_PUBLIC_ORIGIN')
+    expect(secrets.GATEWAY_OPERATOR_PUBLIC_ORIGIN?.required).toBe(false)
+  })
+
+  it('Deploy gateway step env forwards GATEWAY_OPERATOR_BIND_HOST', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          steps?: {name?: string; env?: Record<string, string>}[]
+        }
+      }
+    }
+    const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+    const deployStep = steps.find(s => s.name === 'Deploy gateway')
+    expect(deployStep).toBeDefined()
+    expect(deployStep?.env).toHaveProperty('GATEWAY_OPERATOR_BIND_HOST')
+    expect(deployStep?.env?.GATEWAY_OPERATOR_BIND_HOST).toContain('GATEWAY_OPERATOR_BIND_HOST')
+  })
+
+  it('Deploy gateway step env forwards GATEWAY_OPERATOR_BIND_PORT', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          steps?: {name?: string; env?: Record<string, string>}[]
+        }
+      }
+    }
+    const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+    const deployStep = steps.find(s => s.name === 'Deploy gateway')
+    expect(deployStep).toBeDefined()
+    expect(deployStep?.env).toHaveProperty('GATEWAY_OPERATOR_BIND_PORT')
+    expect(deployStep?.env?.GATEWAY_OPERATOR_BIND_PORT).toContain('GATEWAY_OPERATOR_BIND_PORT')
+  })
+
+  it('Deploy gateway step env forwards GATEWAY_OPERATOR_PUBLIC_ORIGIN', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          steps?: {name?: string; env?: Record<string, string>}[]
+        }
+      }
+    }
+    const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+    const deployStep = steps.find(s => s.name === 'Deploy gateway')
+    expect(deployStep).toBeDefined()
+    expect(deployStep?.env).toHaveProperty('GATEWAY_OPERATOR_PUBLIC_ORIGIN')
+    expect(deployStep?.env?.GATEWAY_OPERATOR_PUBLIC_ORIGIN).toContain('GATEWAY_OPERATOR_PUBLIC_ORIGIN')
+  })
+
+  it('operator vars are NOT in the required-secret validation step env', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {
+        'deploy-gateway'?: {
+          steps?: {name?: string; env?: Record<string, string>; run?: string}[]
+        }
+      }
+    }
+    const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+    const validateStep = steps.find(s => s.name === 'Validate required secrets')
+    expect(validateStep).toBeDefined()
+    // Operator vars must NOT be in the validation step env (deploy script enforces all-or-none)
+    expect(validateStep?.env ?? {}).not.toHaveProperty('GATEWAY_OPERATOR_BIND_HOST')
+    expect(validateStep?.env ?? {}).not.toHaveProperty('GATEWAY_OPERATOR_BIND_PORT')
+    expect(validateStep?.env ?? {}).not.toHaveProperty('GATEWAY_OPERATOR_PUBLIC_ORIGIN')
+  })
+})
+
+// ─── VPC bridge secrets: CI-vs-local parity ──────────────────────────────────
+//
+// GATEWAY_VPC_IP and DASHBOARD_VPC_IP are optional (all-or-none via getOperatorVpcState)
+// but must be forwarded through CI so the operator VPC bridge is not silently disabled
+// when the secrets are set. DIGITALOCEAN_ACCESS_TOKEN is provisioning-only and must NOT
+// be forwarded to the deploy step.
+// These tests assert the end-to-end wiring without adding them to the required
+// validation preflight (they are opt-in, like the operator listener vars).
+
+const VPC_GATEWAY_SECRETS = ['GATEWAY_VPC_IP', 'DASHBOARD_VPC_IP'] as const
+const VPC_DASHBOARD_SECRETS = ['GATEWAY_VPC_IP'] as const
+
+describe('deploy-gateway.yaml: VPC bridge secrets wired end-to-end', () => {
+  const DEPLOY_GATEWAY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy-gateway.yaml')
+
+  for (const secret of VPC_GATEWAY_SECRETS) {
+    it(`workflow_call.secrets declares ${secret} as optional (required: false)`, async () => {
+      const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+      const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]?.required).toBe(false)
+    })
+
+    it(`Deploy gateway step env forwards ${secret} from secrets context`, async () => {
+      const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-gateway'?: {steps?: {name?: string; env?: Record<string, string>}[]}}
+      }
+      const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+      const deployStep = steps.find(s => s.name === 'Deploy gateway')
+      expect(deployStep).toBeDefined()
+      expect(deployStep?.env).toHaveProperty(secret)
+      expect(deployStep?.env?.[secret]).toMatch(/\$\{\{\s*secrets\./)
+    })
+  }
+
+  it('VPC bridge secrets are NOT in the required-secret validation step env', async () => {
+    const text = await Bun.file(DEPLOY_GATEWAY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {'deploy-gateway'?: {steps?: {name?: string; env?: Record<string, string>; run?: string}[]}}
+    }
+    const steps = parsed?.jobs?.['deploy-gateway']?.steps ?? []
+    const validateStep = steps.find(s => s.name === 'Validate required secrets')
+    expect(validateStep).toBeDefined()
+    for (const secret of VPC_GATEWAY_SECRETS) {
+      expect(validateStep?.env ?? {}).not.toHaveProperty(secret)
+    }
+  })
+})
+
+describe('deploy-dashboard.yaml: VPC bridge secret wired end-to-end', () => {
+  const DEPLOY_DASHBOARD_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy-dashboard.yaml')
+
+  for (const secret of VPC_DASHBOARD_SECRETS) {
+    it(`workflow_call.secrets declares ${secret} as optional (required: false)`, async () => {
+      const text = await Bun.file(DEPLOY_DASHBOARD_WORKFLOW).text()
+      const parsed = parseYaml(text) as {on?: {workflow_call?: {secrets?: Record<string, {required?: boolean}>}}}
+      const secrets = parsed?.on?.workflow_call?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]?.required).toBe(false)
+    })
+
+    it(`Deploy step env forwards ${secret} from secrets context`, async () => {
+      const text = await Bun.file(DEPLOY_DASHBOARD_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-dashboard'?: {steps?: {name?: string; env?: Record<string, string>}[]}}
+      }
+      const steps = parsed?.jobs?.['deploy-dashboard']?.steps ?? []
+      const deployStep = steps.find(s => s.name === 'Deploy')
+      expect(deployStep).toBeDefined()
+      expect(deployStep?.env).toHaveProperty(secret)
+      expect(deployStep?.env?.[secret]).toMatch(/\$\{\{\s*secrets\./)
+    })
+  }
+
+  it('GATEWAY_VPC_IP is NOT in the required-secret validation step env', async () => {
+    const text = await Bun.file(DEPLOY_DASHBOARD_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {'deploy-dashboard'?: {steps?: {name?: string; env?: Record<string, string>; run?: string}[]}}
+    }
+    const steps = parsed?.jobs?.['deploy-dashboard']?.steps ?? []
+    const validateStep = steps.find(s => s.name === 'Validate required secrets')
+    expect(validateStep).toBeDefined()
+    expect(validateStep?.env ?? {}).not.toHaveProperty('GATEWAY_VPC_IP')
+  })
+})
+
+describe('deploy.yaml: aggregate router forwards VPC bridge secrets', () => {
+  const DEPLOY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy.yaml')
+
+  for (const secret of VPC_GATEWAY_SECRETS) {
+    it(`deploy-gateway job secrets block passes ${secret}`, async () => {
+      const text = await Bun.file(DEPLOY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-gateway'?: {secrets?: Record<string, string>}}
+      }
+      const secrets = parsed?.jobs?.['deploy-gateway']?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]).toContain(secret)
+    })
+  }
+
+  for (const secret of VPC_DASHBOARD_SECRETS) {
+    it(`deploy-dashboard job secrets block passes ${secret}`, async () => {
+      const text = await Bun.file(DEPLOY_WORKFLOW).text()
+      const parsed = parseYaml(text) as {
+        jobs?: {'deploy-dashboard'?: {secrets?: Record<string, string>}}
+      }
+      const secrets = parsed?.jobs?.['deploy-dashboard']?.secrets ?? {}
+      expect(secrets).toHaveProperty(secret)
+      expect(secrets[secret]).toContain(secret)
+    })
+  }
+})
+
+// ─── deploy.yaml: deploy-dashboard is decoupled from deploy-gateway ──────────
+//
+// The dashboard is a standalone deployment. A gateway failure or slowness must
+// not block dashboard deploys. deploy-dashboard must NOT declare needs: deploy-gateway,
+// and its if: must NOT reference needs.deploy-gateway — locking in the decoupling
+// so it cannot silently regress.
+
+describe('deploy.yaml: deploy-dashboard is decoupled from deploy-gateway', () => {
+  const DEPLOY_WORKFLOW = resolve(REPO_ROOT, '.github/workflows/deploy.yaml')
+
+  it('deploy-dashboard needs: does NOT include deploy-gateway (standalone job)', async () => {
+    const text = await Bun.file(DEPLOY_WORKFLOW).text()
+    const parsed = parseYaml(text) as {
+      jobs?: {'deploy-dashboard'?: {needs?: string | string[]}}
+    }
+    const needs = parsed?.jobs?.['deploy-dashboard']?.needs ?? []
+    const needsArr = Array.isArray(needs) ? needs : [needs]
+    expect(needsArr).not.toContain('deploy-gateway')
+  })
+
+  it('deploy-dashboard if: does NOT reference needs.deploy-gateway (no gateway coupling)', async () => {
+    const text = await Bun.file(DEPLOY_WORKFLOW).text()
+    // The if: expression must not reference needs.deploy-gateway in any form —
+    // gateway state must not gate the dashboard deploy.
+    expect(text).not.toMatch(/needs\.deploy-gateway/)
+  })
+})