@marcusrbrown/infra 0.12.2 → 0.13.0

package/package.json

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

package/src/__snapshots__/cli.test.ts.snap

@@ -28,6 +28,7 @@ Commands:
 
     --url [url]                        Base URL for CLIProxyAPI health checks. Falls back to CLIPROXY_URL or https://cliproxy.fro.bot.
     --key [key]                        Management API key. Falls back to CLIPROXY_MANAGEMENT_KEY when omitted.
+    --api-key [key]                    Downstream API key (bearer) for the upstream provider-auth probe. Falls back to CLIPROXY_API_KEY. Skipped when absent.
     --verbose                          Enable verbose output for all commands
 
 

package/src/commands/cliproxy/status.test.ts

@@ -3,6 +3,7 @@ import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
 import {createCapturedCtx, expectCapturedToInclude, MockProcessExit} from '../../__test__/mcp-ctx-fixture'
 import {
   checkHttpReachability,
+  checkProviderAuth,
   checkUsageStats,
   checkVersion,
   cliproxyStatusAction,
@@ -839,3 +840,318 @@ describe('cliproxyStatusAction — ambient key does not follow agent-supplied UR
     expect(output).toMatch(/CLIPROXY_MANAGEMENT_KEY|no key|skipping/i)
   })
 })
+
+// ─── checkProviderAuth ────────────────────────────────────────────────────────
+
+describe('checkProviderAuth', () => {
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns ok when POST /v1/chat/completions returns 200', async () => {
+    globalThis.fetch = createFetchImplementation(
+      async () =>
+        new Response(JSON.stringify({choices: [{message: {content: 'pong'}}]}), {
+          status: 200,
+          headers: {'content-type': 'application/json'},
+        }),
+    )
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('ok')
+    expect(result.title).toBe('Upstream provider auth (anthropic)')
+    expect(result.summary).toContain('anthropic route OK')
+    expect(result.summary).toContain('claude-sonnet-4-6')
+  })
+
+  it('returns error when POST returns 401', async () => {
+    globalThis.fetch = createFetchImplementation(async () => new Response('Unauthorized', {status: 401}))
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('error')
+    expect(result.summary).toContain('401')
+    expect(result.summary).toContain('cliproxy login claude')
+  })
+
+  it('returns error when POST returns 503 with auth_unavailable body', async () => {
+    globalThis.fetch = createFetchImplementation(
+      async () => new Response('auth_unavailable: no auth available (providers=claude)', {status: 503}),
+    )
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('error')
+    expect(result.summary).toContain('503')
+    expect(result.summary).toContain('cliproxy login claude')
+  })
+
+  it('returns error when POST returns 503 with "no auth available" in body', async () => {
+    globalThis.fetch = createFetchImplementation(async () => new Response('no auth available', {status: 503}))
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('error')
+    expect(result.summary).toContain('cliproxy login claude')
+  })
+
+  it('returns error when POST returns 503 with "providers=claude" in body', async () => {
+    globalThis.fetch = createFetchImplementation(
+      async () => new Response('{"error":"providers=claude unavailable"}', {status: 503}),
+    )
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('error')
+    expect(result.summary).toContain('cliproxy login claude')
+  })
+
+  it('returns warning when POST returns 503 without auth-unavailable markers', async () => {
+    globalThis.fetch = createFetchImplementation(async () => new Response('Service Unavailable', {status: 503}))
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('warning')
+    expect(result.summary).toContain('503')
+    expect(result.summary).not.toContain('cliproxy login claude')
+  })
+
+  it('returns warning when POST returns other non-2xx (e.g. 500)', async () => {
+    globalThis.fetch = createFetchImplementation(async () => new Response('Internal Server Error', {status: 500}))
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('warning')
+    expect(result.summary).toContain('500')
+  })
+
+  it('returns warning (not error) when fetch throws (network/timeout)', async () => {
+    globalThis.fetch = createFetchImplementation(async () => {
+      throw new Error('The operation was aborted due to timeout')
+    })
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(result.level).toBe('warning')
+    expect(result.summary).toContain('Anthropic probe failed')
+    expect(result.summary).toContain('aborted')
+  })
+
+  it('never includes the apiKey in summary or details', async () => {
+    const secretKey = 'super-secret-api-key-do-not-leak'
+
+    globalThis.fetch = createFetchImplementation(async () => new Response('Unauthorized', {status: 401}))
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', secretKey)
+
+    expect(result.summary).not.toContain(secretKey)
+    const detailsText = (result.details ?? []).join('\n')
+    expect(detailsText).not.toContain(secretKey)
+  })
+
+  it('uses the default model claude-sonnet-4-6 when no model override given', async () => {
+    let capturedBody = ''
+
+    globalThis.fetch = createFetchImplementation(async (_url, init) => {
+      capturedBody = typeof init?.body === 'string' ? init.body : ''
+      return new Response(JSON.stringify({choices: []}), {
+        status: 200,
+        headers: {'content-type': 'application/json'},
+      })
+    })
+
+    await checkProviderAuth('https://cliproxy.example.com', 'test-api-key')
+
+    expect(capturedBody).toContain('claude-sonnet-4-6')
+  })
+
+  it('uses the model override when options.model is provided', async () => {
+    let capturedBody = ''
+
+    globalThis.fetch = createFetchImplementation(async (_url, init) => {
+      capturedBody = typeof init?.body === 'string' ? init.body : ''
+      return new Response(JSON.stringify({choices: []}), {
+        status: 200,
+        headers: {'content-type': 'application/json'},
+      })
+    })
+
+    await checkProviderAuth('https://cliproxy.example.com', 'test-api-key', {model: 'claude-opus-4-5'})
+
+    expect(capturedBody).toContain('claude-opus-4-5')
+    expect(capturedBody).not.toContain('claude-sonnet-4-6')
+  })
+
+  it('includes verbose details (URL, model, status) when verbose=true', async () => {
+    globalThis.fetch = createFetchImplementation(
+      async () =>
+        new Response(JSON.stringify({choices: []}), {
+          status: 200,
+          headers: {'content-type': 'application/json'},
+        }),
+    )
+
+    const result = await checkProviderAuth('https://cliproxy.example.com', 'test-api-key', {verbose: true})
+
+    expect(result.details).toBeDefined()
+    const detailsText = (result.details ?? []).join('\n')
+    expect(detailsText).toContain('https://cliproxy.example.com')
+    expect(detailsText).toContain('claude-sonnet-4-6')
+  })
+})
+
+// ─── cliproxyStatusAction — provider auth wiring ─────────────────────────────
+
+describe('cliproxyStatusAction — provider auth probe wiring', () => {
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    originalEnv = {
+      CLIPROXY_URL: process.env.CLIPROXY_URL,
+      CLIPROXY_MANAGEMENT_KEY: process.env.CLIPROXY_MANAGEMENT_KEY,
+      CLIPROXY_API_KEY: process.env.CLIPROXY_API_KEY,
+    }
+    delete process.env.CLIPROXY_URL
+    delete process.env.CLIPROXY_MANAGEMENT_KEY
+    delete process.env.CLIPROXY_API_KEY
+  })
+
+  afterEach(() => {
+    for (const [k, v] of Object.entries(originalEnv)) {
+      if (v === undefined) {
+        delete process.env[k]
+      } else {
+        process.env[k] = v
+      }
+    }
+    globalThis.fetch = originalFetch
+  })
+
+  it('shows a warning (not error) when no provider key is available', async () => {
+    globalThis.fetch = createFetchImplementation(async url => {
+      if (url.includes('/healthz')) return new Response('ok', {status: 200})
+      throw new Error(`Unexpected fetch: ${url}`)
+    })
+
+    const {ctx, captured} = createCapturedCtx()
+    await cliproxyStatusAction({url: 'https://cliproxy.example.com'}, ctx)
+
+    const output = [...captured.stdout, ...captured.stderr].join('\n')
+    expect(output).toMatch(/CLIPROXY_API_KEY|skipping upstream provider probe/i)
+    // Must be a warning, not an error — no exit(1) for missing key
+    expect(captured.exit).toBeNull()
+  })
+
+  it('runs the provider auth probe when --api-key is provided', async () => {
+    const fetchedUrls: string[] = []
+
+    globalThis.fetch = createFetchImplementation(async url => {
+      fetchedUrls.push(url)
+      if (url.includes('/healthz')) return new Response('ok', {status: 200})
+      if (url.includes('/v1/chat/completions'))
+        return new Response(JSON.stringify({choices: []}), {
+          status: 200,
+          headers: {'content-type': 'application/json'},
+        })
+      throw new Error(`Unexpected fetch: ${url}`)
+    })
+
+    const {ctx, captured} = createCapturedCtx()
+    await cliproxyStatusAction({url: 'https://cliproxy.example.com', apiKey: 'my-api-key'}, ctx)
+
+    expect(fetchedUrls.some(u => u.includes('/v1/chat/completions'))).toBe(true)
+    const output = [...captured.stdout, ...captured.stderr].join('\n')
+    expect(output).toContain('Upstream provider auth')
+  })
+
+  it('does NOT forward ambient CLIPROXY_API_KEY to an explicit --url override', async () => {
+    process.env.CLIPROXY_API_KEY = 'ambient-api-key-secret'
+
+    const capturedAuthHeaders: string[] = []
+
+    globalThis.fetch = createFetchImplementation(async (url, init) => {
+      const hdrs = init?.headers
+      let auth: string | null = null
+      if (hdrs instanceof Headers) {
+        auth = hdrs.get('authorization')
+      } else if (hdrs !== null && hdrs !== undefined && typeof hdrs === 'object') {
+        const hdrsObj = hdrs as Record<string, string>
+        auth = hdrsObj.authorization ?? hdrsObj.Authorization ?? null
+      }
+      if (auth) capturedAuthHeaders.push(auth)
+
+      if (url.includes('/healthz')) return new Response('ok', {status: 200})
+      if (url.includes('/v1/chat/completions')) return new Response(JSON.stringify({choices: []}), {status: 200})
+      return new Response('ok', {status: 200})
+    })
+
+    const {ctx} = createCapturedCtx()
+    // Explicit --url override to a non-trusted host — ambient key must NOT follow
+    await cliproxyStatusAction({url: 'https://evil.example.com'}, ctx)
+
+    // The ambient API key must not appear in any Authorization header sent to evil host
+    expect(capturedAuthHeaders.some(h => h.includes('ambient-api-key-secret'))).toBe(false)
+  })
+
+  it('uses ambient CLIPROXY_API_KEY when URL is the trusted default', async () => {
+    process.env.CLIPROXY_API_KEY = 'ambient-api-key-trusted'
+
+    const capturedAuthHeaders: string[] = []
+
+    globalThis.fetch = createFetchImplementation(async (url, init) => {
+      const hdrs = init?.headers
+      let auth: string | null = null
+      if (hdrs instanceof Headers) {
+        auth = hdrs.get('authorization')
+      } else if (hdrs !== null && hdrs !== undefined && typeof hdrs === 'object') {
+        const hdrsObj = hdrs as Record<string, string>
+        auth = hdrsObj.authorization ?? hdrsObj.Authorization ?? null
+      }
+      if (auth) capturedAuthHeaders.push(auth)
+
+      if (url.includes('/healthz')) return new Response('ok', {status: 200})
+      if (url.includes('/v1/chat/completions'))
+        return new Response(JSON.stringify({choices: []}), {
+          status: 200,
+          headers: {'content-type': 'application/json'},
+        })
+      // Management endpoints — return ok so management checks don't block
+      if (url.includes('/v0/management/config'))
+        return new Response('{}', {status: 200, headers: {'content-type': 'application/json'}})
+      if (url.includes('/v0/management/usage-queue'))
+        return new Response('[]', {status: 200, headers: {'content-type': 'application/json'}})
+      if (url.includes('/v0/management/latest-version'))
+        return new Response(JSON.stringify({'latest-version': 'v1.0.0'}), {
+          status: 200,
+          headers: {'content-type': 'application/json'},
+        })
+      return new Response('ok', {status: 200})
+    })
+
+    const {ctx} = createCapturedCtx()
+    // Default trusted URL — ambient key SHOULD be used
+    await cliproxyStatusAction({url: 'https://cliproxy.fro.bot'}, ctx)
+
+    expect(capturedAuthHeaders.some(h => h.includes('ambient-api-key-trusted'))).toBe(true)
+  })
+
+  it('provider auth error (401) causes exit(1) — dead upstream is a real error', async () => {
+    globalThis.fetch = createFetchImplementation(async url => {
+      if (url.includes('/healthz')) return new Response('ok', {status: 200})
+      if (url.includes('/v1/chat/completions')) return new Response('Unauthorized', {status: 401})
+      throw new Error(`Unexpected fetch: ${url}`)
+    })
+
+    const {ctx, captured} = createCapturedCtx()
+    let threw: unknown
+    try {
+      await cliproxyStatusAction({url: 'https://cliproxy.example.com', apiKey: 'my-api-key'}, ctx)
+    } catch (error) {
+      threw = error
+    }
+
+    expect(threw).toBeInstanceOf(MockProcessExit)
+    expect(captured.exit?.code).toBe(1)
+  })
+})

package/src/commands/cliproxy/status.ts

@@ -226,6 +226,113 @@ export async function checkVersion(baseUrl: string, key: string): Promise<CheckR
   }
 }
 
+const DEFAULT_PROVIDER_MODEL = 'claude-sonnet-4-6'
+
+export interface ProviderAuthOptions {
+  model?: string
+  verbose?: boolean
+}
+
+/**
+ * Probe the upstream provider auth by sending a minimal chat completion request.
+ * Returns a CheckResult — never throws.
+ *
+ * - 200 → ok
+ * - 401 OR (503 with auth-unavailable body markers) → error with remediation hint
+ * - other non-2xx → warning (don't fail status on unrelated upstream issues)
+ * - fetch throw (timeout/network) → warning (flaky probe should not fail status)
+ *
+ * The apiKey is NEVER included in summary or details output.
+ */
+export async function checkProviderAuth(
+  baseUrl: string,
+  apiKey: string,
+  options?: ProviderAuthOptions,
+): Promise<CheckResult> {
+  const model = options?.model ?? DEFAULT_PROVIDER_MODEL
+  const verbose = options?.verbose === true
+  const endpoint = `${baseUrl}/v1/chat/completions`
+
+  try {
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{role: 'user', content: 'ping'}],
+        max_tokens: 1,
+      }),
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    const details: string[] = []
+    if (verbose) {
+      details.push(`URL: ${endpoint}`)
+      details.push(`Model: ${model}`)
+      details.push(`Status: ${response.status}`)
+    }
+
+    if (response.ok) {
+      return {
+        title: 'Upstream provider auth (anthropic)',
+        level: 'ok',
+        summary: `anthropic route OK (${model})`,
+        details: details.length > 0 ? details : undefined,
+      }
+    }
+
+    // 401 is always an auth failure
+    if (response.status === 401) {
+      return {
+        title: 'Upstream provider auth (anthropic)',
+        level: 'error',
+        summary: `Anthropic upstream auth unavailable (${response.status}) — run: cliproxy login claude`,
+        details: details.length > 0 ? details : undefined,
+      }
+    }
+
+    // 503 may be auth_unavailable — check body for known markers
+    if (response.status === 503) {
+      let bodyText = ''
+      try {
+        bodyText = await response.text()
+      } catch {
+        // ignore body read failure
+      }
+
+      const isAuthUnavailable = /auth_unavailable|no auth available|providers=claude/i.test(bodyText)
+
+      if (isAuthUnavailable) {
+        return {
+          title: 'Upstream provider auth (anthropic)',
+          level: 'error',
+          summary: `Anthropic upstream auth unavailable (${response.status}) — run: cliproxy login claude`,
+          details: details.length > 0 ? details : undefined,
+        }
+      }
+    }
+
+    // Any other non-2xx: warning (don't fail status on unrelated upstream issues)
+    return {
+      title: 'Upstream provider auth (anthropic)',
+      level: 'warning',
+      summary: `Anthropic probe returned HTTP ${response.status}`,
+      details: details.length > 0 ? details : undefined,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      title: 'Upstream provider auth (anthropic)',
+      level: 'warning',
+      summary: `Anthropic probe failed: ${message}`,
+      details: verbose ? [`URL: ${endpoint}`, `Model: ${model}`] : undefined,
+    }
+  }
+}
+
 /**
  * Probe the management API with a cheap auth check before issuing parallel calls.
  * Returns null on success, or a CheckResult describing the auth failure.
@@ -377,6 +484,8 @@ export async function getCliproxyStatusSummary(baseUrl: string, key: string, ver
 export interface StatusOptions {
   url?: string
   key?: string
+  /** Downstream API key (bearer) for the upstream provider-auth probe. Maps from --api-key CLI flag. */
+  apiKey?: string
   verbose?: boolean
 }
 
@@ -396,6 +505,10 @@ export async function cliproxyStatusAction(options: StatusOptions, ctx: ActionCt
     // An ambient env key is only forwarded when the resolved baseUrl is trusted.
     const managementKey = options.key ?? (urlIsExplicitlyOverridden ? undefined : process.env.CLIPROXY_MANAGEMENT_KEY)
 
+    // Provider (downstream) API key for the upstream provider-auth probe.
+    // Same trusted-URL guard: ambient CLIPROXY_API_KEY only follows to the trusted URL.
+    const providerKey = options.apiKey ?? (urlIsExplicitlyOverridden ? undefined : process.env.CLIPROXY_API_KEY)
+
     ctx.console.log('CLIProxyAPI status')
     ctx.console.log('')
 
@@ -419,6 +532,17 @@ export async function cliproxyStatusAction(options: StatusOptions, ctx: ActionCt
       results.push(mgmt.usage, mgmt.version)
     }
 
+    // Upstream provider-auth probe — only when a downstream API key is available.
+    if (providerKey) {
+      results.push(await checkProviderAuth(baseUrl, providerKey, {verbose}))
+    } else {
+      results.push({
+        title: 'Upstream provider auth',
+        level: 'warning',
+        summary: 'CLIPROXY_API_KEY not set — skipping upstream provider probe.',
+      })
+    }
+
     for (const result of results) {
       printCheckResult(result, ctx)
       ctx.console.log('')
@@ -460,6 +584,14 @@ export function registerCliproxyStatus(cli: ReturnType<typeof goke>): void {
       '--key [key]',
       z.string().describe('Management API key. Falls back to CLIPROXY_MANAGEMENT_KEY when omitted.'),
     )
+    .option(
+      '--api-key [key]',
+      z
+        .string()
+        .describe(
+          'Downstream API key (bearer) for the upstream provider-auth probe. Falls back to CLIPROXY_API_KEY. Skipped when absent.',
+        ),
+    )
     .option('--verbose', 'Enable verbose output for all commands')
     .action(cliproxyStatusAction)
 }

package/src/commands/gateway/deploy.ts

@@ -68,6 +68,8 @@ export function getGatewayDeployEnv(): Record<string, string> {
     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', () => {
@@ -645,10 +674,9 @@ describe('dorny/paths-filter quantifier guard', () => {
   })
 })
 
-// ─── Unit 5: operator auth/config secrets and tuning vars ────────────────────
+// ─── operator auth/config secrets and tuning vars ────────────────────────────
 //
-// RED tests for Unit 5 of 2026-06-18-002-feat-gateway-operator-auth-config-plan.md
-// These assert the four new auth/config secrets and three optional tuning vars are
+// 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.
 
@@ -843,6 +871,24 @@ describe('CLI getGatewayDeployEnv: operator auth/config passthrough', () => {
       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 ──
@@ -988,3 +1034,147 @@ describe('deploy-gateway.yaml: optional operator secret declarations (issue 1)',
     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/)
+  })
+})