serverless-ircd 0.9.0 → 0.11.0

package/tools/ci-hardening/src/env-var-drift.ts

@@ -0,0 +1,192 @@
+/**
+ * Env-var / secret documentation drift guard.
+ *
+ * The Cloudflare Worker consumes a growing set of env vars via the
+ * cf-adapter config loader (`CfConfigEnv`). Credential material
+ * (`SERVER_PASSWORD`, `OPER_PASSWORD` / `OPER_SALT` / `OPER_HASH`,
+ * `SASL_ACCOUNTS`) MUST be Workers secrets (`wrangler secret put`),
+ * never plaintext `[vars]` entries; everything else is a normal
+ * `[vars]` knob. Historically `apps/cf-worker/wrangler.toml` carried a
+ * stale "no secret bindings consumed" comment, so an operator relying
+ * on it could paste oper passwords into `[vars]` and leak them into
+ * the repo / bundle.
+ *
+ * This guard parses the wrangler.toml `consumed-env-vars` comment
+ * block and asserts it stays in sync with the config loader:
+ *
+ *   1. every `CfConfigEnv` member is enumerated in the block
+ *      (classified `[vars]` or `[secret]`),
+ *   2. every block entry is still consumed (no stale names),
+ *   3. no `[secret]`-classified var ships as a plaintext `[vars]` key,
+ *   4. the ticket-mandated sensitive vars (`OPER_PASSWORD`,
+ *      `SERVER_PASSWORD`, `SASL_ACCOUNTS`) are classified `[secret]`.
+ *
+ * The contract is enforced by `tests/env-var-drift.test.ts` against
+ * the real repo files on every CI run.
+ */
+
+/**
+ * Env vars documented in the wrangler.toml block but consumed
+ * OUTSIDE the cf-adapter config loader. `WEB_ORIGINS` is read
+ * directly by the worker edge (`origin-allowlist.ts`), so it is a
+ * legitimate block entry the loader-source scan cannot see.
+ */
+export const EXTRA_DOCUMENTED_ENV_VARS: ReadonlySet<string> = new Set(['WEB_ORIGINS']);
+
+/**
+ * Vars that are credential material per the drift-guard ticket.
+ * Each MUST be classified `[secret]` in the wrangler.toml block
+ * (when documented). `OPER_SALT` / `OPER_HASH` are also stored as
+ * secrets in practice, but only these three are hard-pinned so the
+ * pinned set matches the ticket's acceptance criteria exactly.
+ */
+export const REQUIRED_SECRET_ENV_VARS: ReadonlySet<string> = new Set([
+  'OPER_PASSWORD',
+  'SERVER_PASSWORD',
+  'SASL_ACCOUNTS',
+]);
+
+/** Marker lines bounding the machine-parsed block in wrangler.toml. */
+const BLOCK_BEGIN = '## BEGIN consumed-env-vars';
+const BLOCK_END = '## END consumed-env-vars';
+
+/**
+ * A documented block entry: `## [vars] NAME — description` or
+ * `## [secret] NAME — description`.
+ */
+const BLOCK_LINE_RE = /^##\s*\[(vars|secret)\]\s+([A-Z][A-Z0-9_]+)\b/;
+
+/** One documented env var with its sensitivity classification. */
+export interface DocumentedEnvVar {
+  readonly name: string;
+  readonly classification: 'vars' | 'secret';
+}
+
+/**
+ * Extract the env-var member names of `CfConfigEnv` from the config
+ * loader source. Members are `NAME?:` / `NAME:` interface lines;
+ * doc-comment prose and module-level constants do not match. Returns
+ * a sorted, de-duplicated list. Empty when the interface is absent
+ * (e.g. the file was renamed — the contract test surfaces that as a
+ * loud all-vars-missing failure).
+ */
+export function extractLoaderEnvVars(configLoaderSource: string): string[] {
+  const start = configLoaderSource.indexOf('export interface CfConfigEnv {');
+  if (start === -1) return [];
+  const body = configLoaderSource.slice(start);
+  const end = body.indexOf('\n}');
+  const scope = end === -1 ? body : body.slice(0, end);
+  const names = new Set<string>();
+  for (const line of scope.split('\n')) {
+    const name = line.match(/^\s+([A-Z][A-Z0-9_]+)\??:\s/u)?.[1];
+    if (name !== undefined) names.add(name);
+  }
+  return [...names].sort();
+}
+
+/**
+ * Parse the `consumed-env-vars` block from wrangler.toml text.
+ * Non-conforming lines inside the block (prose, blank lines) are
+ * ignored. Returns an empty list when the block markers are absent.
+ */
+export function parseConsumedEnvBlock(tomlSource: string): DocumentedEnvVar[] {
+  const beginIdx = tomlSource.indexOf(BLOCK_BEGIN);
+  if (beginIdx === -1) return [];
+  const afterBegin = tomlSource.slice(beginIdx + BLOCK_BEGIN.length);
+  const endIdx = afterBegin.indexOf(BLOCK_END);
+  const block = endIdx === -1 ? afterBegin : afterBegin.slice(0, endIdx);
+  const out: DocumentedEnvVar[] = [];
+  for (const line of block.split('\n')) {
+    const match = line.match(BLOCK_LINE_RE);
+    if (match === null) continue;
+    // Both capture groups are unconditional participants of
+    // BLOCK_LINE_RE, so they are defined whenever the regex matches;
+    // the tuple cast only satisfies noUncheckedIndexedAccess.
+    const [classification, name] = match.slice(1) as ['vars' | 'secret', string];
+    out.push({ name, classification });
+  }
+  return out;
+}
+
+/**
+ * Extract the plaintext keys of the wrangler.toml `[vars]` table.
+ * Commented-out assignments (`# KEY = ...`) and other tables do not
+ * contribute.
+ */
+export function extractVarsTableKeys(tomlSource: string): Set<string> {
+  const keys = new Set<string>();
+  let inVars = false;
+  for (const line of tomlSource.split('\n')) {
+    if (/^\[vars\]/u.test(line)) {
+      inVars = true;
+      continue;
+    }
+    if (/^\[/u.test(line)) {
+      inVars = false;
+      continue;
+    }
+    if (!inVars) continue;
+    const key = line.match(/^([A-Za-z0-9_]+)\s*=/u)?.[1];
+    if (key !== undefined) keys.add(key);
+  }
+  return keys;
+}
+
+/** Result of the drift check: all-clear or a list of drift findings. */
+export type EnvVarDriftResult =
+  | { ok: true; documentedCount: number }
+  | { ok: false; errors: string[] };
+
+/**
+ * Compare the config loader's consumed env vars against the
+ * wrangler.toml `consumed-env-vars` documentation block. Pure —
+ * `tests/env-var-drift.test.ts` wires the real repo files.
+ */
+export function checkEnvVarDrift(
+  configLoaderSource: string,
+  tomlSource: string,
+): EnvVarDriftResult {
+  const loaderVars = extractLoaderEnvVars(configLoaderSource);
+  const loaderSet = new Set(loaderVars);
+  const documented = parseConsumedEnvBlock(tomlSource);
+  const byName = new Map(documented.map((entry) => [entry.name, entry]));
+  const varsKeys = extractVarsTableKeys(tomlSource);
+  const errors: string[] = [];
+
+  for (const name of loaderVars) {
+    if (!byName.has(name)) {
+      errors.push(
+        `${name} is consumed by packages/cf-adapter/src/config-loader.ts (CfConfigEnv) but is not documented in the apps/cf-worker/wrangler.toml consumed-env-vars block`,
+      );
+    }
+  }
+
+  for (const entry of documented) {
+    if (!loaderSet.has(entry.name) && !EXTRA_DOCUMENTED_ENV_VARS.has(entry.name)) {
+      errors.push(
+        `${entry.name} is documented in the wrangler.toml consumed-env-vars block but is no longer consumed (stale entry — remove it, or add it to EXTRA_DOCUMENTED_ENV_VARS if it moved outside the config loader)`,
+      );
+    }
+  }
+
+  for (const name of REQUIRED_SECRET_ENV_VARS) {
+    const entry = byName.get(name);
+    if (entry !== undefined && entry.classification !== 'secret') {
+      errors.push(
+        `${name} is credential material but is classified [vars] in the wrangler.toml consumed-env-vars block — classify it [secret] and set it with \`wrangler secret put ${name}\``,
+      );
+    }
+  }
+
+  for (const entry of documented) {
+    if (entry.classification === 'secret' && varsKeys.has(entry.name)) {
+      errors.push(
+        `${entry.name} is classified [secret] but appears as a plaintext key in the wrangler.toml [vars] table — set it with \`wrangler secret put ${entry.name}\` instead`,
+      );
+    }
+  }
+
+  return errors.length === 0
+    ? { ok: true, documentedCount: documented.length }
+    : { ok: false, errors };
+}

package/tools/ci-hardening/src/hostname-guard.ts

@@ -0,0 +1,11 @@
+import { runHostnameGuard } from './deploy-hostname.js';
+
+const result = runHostnameGuard(process.argv.slice(2), process.env);
+
+if (result.exitCode === 0) {
+  console.log(result.message);
+} else {
+  console.error(result.message);
+}
+
+process.exit(result.exitCode);

package/tools/ci-hardening/src/index.ts

@@ -1,6 +1,25 @@
 export {
   MUTATION_SCORE_THRESHOLD,
+  findAwsCredentialSteps,
   readCoverageThresholds,
   readStrykerConfig,
   readWorkflowJob,
+  readWorkflowPermissions,
 } from './validate.js';
+export {
+  EXTRA_DOCUMENTED_ENV_VARS,
+  REQUIRED_SECRET_ENV_VARS,
+  checkEnvVarDrift,
+  extractLoaderEnvVars,
+  extractVarsTableKeys,
+  parseConsumedEnvBlock,
+} from './env-var-drift.js';
+export type { DocumentedEnvVar, EnvVarDriftResult } from './env-var-drift.js';
+export {
+  PLACEHOLDER_HOSTNAMES,
+  checkDeployHostname,
+  isPlaceholderHostname,
+  readServerNameFromWranglerToml,
+  runHostnameGuard,
+} from './deploy-hostname.js';
+export type { HostnameCheck, HostnameGuardResult } from './deploy-hostname.js';

package/tools/ci-hardening/src/validate.ts

@@ -37,9 +37,66 @@ interface WorkflowJob {
 }
 
 interface ParsedWorkflow {
+  permissions?: Record<string, string> | string;
   jobs?: Record<string, WorkflowJob>;
 }
 
+/**
+ * Parse a GitHub Actions YAML file and return the top-level
+ * `permissions:` block as a `Record<string, string>` (e.g.
+ * `{ 'id-token': 'write', contents: 'read' }`).
+ *
+ * Throws if the workflow has no top-level `permissions:` block.
+ * The literal `'read-all'` / `'write-all'` shapes are returned
+ * verbatim as a single key so callers can flag them.
+ *
+ * @param yamlText raw YAML source of a workflow file.
+ */
+export function readWorkflowPermissions(yamlText: string): Record<string, string> {
+  const parsed = load(yamlText) as ParsedWorkflow;
+  if (parsed.permissions === undefined || parsed.permissions === null) {
+    throw new Error('Workflow has no top-level permissions: block');
+  }
+  if (typeof parsed.permissions === 'string') {
+    return { [parsed.permissions]: parsed.permissions };
+  }
+  return parsed.permissions;
+}
+
+/**
+ * Return every step in the workflow that uses `configure-aws-credentials`,
+ * keyed by `"<job>.<index>"`. Each value is the step's `with:` mapping
+ * (an empty object if the step has no `with:`).
+ *
+ * Used by the OIDC-only lint to assert no static-key inputs survive.
+ *
+ * @param yamlText raw YAML source of a workflow file.
+ */
+export function findAwsCredentialSteps(
+  yamlText: string,
+): Array<{ job: string; index: number; with: Record<string, unknown> }> {
+  const parsed = load(yamlText) as ParsedWorkflow;
+  const out: Array<{ job: string; index: number; with: Record<string, unknown> }> = [];
+  for (const [jobName, job] of Object.entries(parsed.jobs ?? {})) {
+    const steps = job?.steps ?? [];
+    steps.forEach((step, index) => {
+      const uses = step.uses;
+      if (typeof uses === 'string' && uses.includes('configure-aws-credentials')) {
+        const withBlock = step.with;
+        out.push({
+          job: jobName,
+          index,
+          with:
+            withBlock && typeof withBlock === 'object'
+              ? (withBlock as Record<string, unknown>)
+              : {},
+        });
+      }
+    });
+  }
+  return out;
+}
+
 /**
  * Extract the `coverage.thresholds` block from a vitest config file.
  *

package/tools/ci-hardening/tests/__wrangler_missing__.toml

@@ -0,0 +1,2 @@
+[vars]
+NETWORK_NAME = "ServerlessIRCd"

package/tools/ci-hardening/tests/__wrangler_placeholder__.toml

@@ -0,0 +1,3 @@
+[vars]
+SERVER_NAME = "irc.your-domain.invalid"
+NETWORK_NAME = "ServerlessIRCd"

package/tools/ci-hardening/tests/__wrangler_real__.toml

@@ -0,0 +1,3 @@
+[vars]
+SERVER_NAME = "irc.example.net"
+NETWORK_NAME = "ServerlessIRCd"

package/tools/ci-hardening/tests/cf-deploy.test.ts

@@ -0,0 +1,200 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  buildWranglerDeployArgs,
+  parseWrapperArgv,
+  resolveGuardedHostname,
+  runDeploy,
+} from '../src/cf-deploy.js';
+
+const tmpDirs: string[] = [];
+function writeTempWranglerToml(serverName: string | undefined): string {
+  const dir = mkdtempSync(join(tmpdir(), 'cf-deploy-test-'));
+  tmpDirs.push(dir);
+  const vars = serverName === undefined ? '' : `[vars]\nSERVER_NAME = "${serverName}"\n`;
+  writeFileSync(join(dir, 'wrangler.toml'), vars);
+  return join(dir, 'wrangler.toml');
+}
+
+afterEach(() => {
+  for (const dir of tmpDirs.splice(0)) {
+    // Best-effort cleanup; tmpdir is OS-swept anyway.
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+});
+
+describe('parseWrapperArgv', () => {
+  it('returns the config path and passthrough args after a -- separator', () => {
+    expect(parseWrapperArgv(['wrangler.toml', '--', '--dry-run', '--x=1'])).toEqual({
+      configPath: 'wrangler.toml',
+      passthrough: ['--dry-run', '--x=1'],
+    });
+  });
+
+  it('strips repeated leading -- separators (pnpm double-forwarding)', () => {
+    expect(parseWrapperArgv(['wrangler.toml', '--', '--', '--dry-run'])).toEqual({
+      configPath: 'wrangler.toml',
+      passthrough: ['--dry-run'],
+    });
+  });
+
+  it('treats non-flag args after the config path as passthrough without a separator', () => {
+    expect(parseWrapperArgv(['wrangler.toml', '--dry-run'])).toEqual({
+      configPath: 'wrangler.toml',
+      passthrough: ['--dry-run'],
+    });
+  });
+
+  it('rejects an empty argv (usage error)', () => {
+    expect(parseWrapperArgv([])).toEqual({ configPath: '', passthrough: [] });
+  });
+});
+
+describe('resolveGuardedHostname', () => {
+  it('prefers a non-blank SERVER_NAME env override over the config value', () => {
+    const configPath = writeTempWranglerToml('irc.your-domain.invalid');
+    const result = resolveGuardedHostname(configPath, { SERVER_NAME: 'irc.fowl.cloud' });
+    expect(result).toEqual({ ok: true, hostname: 'irc.fowl.cloud' });
+  });
+
+  it('falls back to the config SERVER_NAME when the env override is unset', () => {
+    const configPath = writeTempWranglerToml('irc.fowl.cloud');
+    const result = resolveGuardedHostname(configPath, {});
+    expect(result).toEqual({ ok: true, hostname: 'irc.fowl.cloud' });
+  });
+
+  it('rejects the placeholder config value when no override is set', () => {
+    const configPath = writeTempWranglerToml('irc.your-domain.invalid');
+    const result = resolveGuardedHostname(configPath, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.message).toContain('placeholder');
+  });
+
+  it('rejects a blank env override falling back to a placeholder config', () => {
+    const configPath = writeTempWranglerToml('irc.example.com');
+    const result = resolveGuardedHostname(configPath, { SERVER_NAME: '   ' });
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects when SERVER_NAME is set nowhere (no env override, none in config)', () => {
+    const configPath = writeTempWranglerToml(undefined);
+    const result = resolveGuardedHostname(configPath, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.message).toContain('SERVER_NAME is not set');
+  });
+});
+
+describe('buildWranglerDeployArgs', () => {
+  it('injects the resolved hostname as a --var override before passthrough args', () => {
+    expect(buildWranglerDeployArgs('irc.fowl.cloud', ['--dry-run'])).toEqual([
+      'deploy',
+      '--var',
+      'SERVER_NAME:irc.fowl.cloud',
+      '--dry-run',
+    ]);
+  });
+
+  it('works with no passthrough args', () => {
+    expect(buildWranglerDeployArgs('irc.example.org', [])).toEqual([
+      'deploy',
+      '--var',
+      'SERVER_NAME:irc.example.org',
+    ]);
+  });
+});
+
+describe('runDeploy', () => {
+  /** Writes a PATH-resolvable `wrangler` shim that records its argv. */
+  function writeWranglerShim(): { binDir: string; argsFile: string } {
+    const dir = mkdtempSync(join(tmpdir(), 'cf-deploy-shim-'));
+    tmpDirs.push(dir);
+    const argsFile = join(dir, 'args.txt');
+    const shim = ['#!/bin/sh', `printf '%s\\n' "$@" > ${JSON.stringify(argsFile)}`, 'exit 0'].join(
+      '\n',
+    );
+    const bin = join(dir, 'wrangler');
+    writeFileSync(bin, shim, { mode: 0o755 });
+    return { binDir: dir, argsFile };
+  }
+
+  it('invokes wrangler with the injected --var and passthrough args (exit 0)', () => {
+    const { binDir, argsFile } = writeWranglerShim();
+    const configPath = writeTempWranglerToml('irc.your-domain.invalid');
+    const prevPath = process.env.PATH;
+    process.env.PATH = `${binDir}:${prevPath ?? ''}`;
+    try {
+      const code = runDeploy([configPath, '--', '--dry-run'], {
+        SERVER_NAME: 'irc.fowl.cloud',
+      });
+      expect(code).toBe(0);
+      expect(readFileSync(argsFile, 'utf8')).toBe(
+        ['deploy', '--var', 'SERVER_NAME:irc.fowl.cloud', '--dry-run', ''].join('\n'),
+      );
+    } finally {
+      process.env.PATH = prevPath;
+    }
+  });
+
+  it('returns 1 without invoking wrangler when the resolved hostname is a placeholder', () => {
+    const { binDir, argsFile } = writeWranglerShim();
+    const configPath = writeTempWranglerToml('irc.example.com');
+    const prevPath = process.env.PATH;
+    process.env.PATH = `${binDir}:${prevPath ?? ''}`;
+    try {
+      const code = runDeploy([configPath], {});
+      expect(code).toBe(1);
+      expect(existsSync(argsFile)).toBe(false);
+    } finally {
+      process.env.PATH = prevPath;
+    }
+  });
+
+  it('returns 2 on a usage error (no config path)', () => {
+    expect(runDeploy([], {})).toBe(2);
+  });
+
+  it('returns 1 when wrangler cannot be spawned (missing from PATH)', () => {
+    const configPath = writeTempWranglerToml('irc.fowl.cloud');
+    const prevPath = process.env.PATH;
+    process.env.PATH = '';
+    try {
+      expect(runDeploy([configPath], {})).toBe(1);
+    } finally {
+      process.env.PATH = prevPath;
+    }
+  });
+
+  it('propagates a non-zero wrangler exit code', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'cf-deploy-failshim-'));
+    tmpDirs.push(dir);
+    writeFileSync(join(dir, 'wrangler'), '#!/bin/sh\nexit 3\n', { mode: 0o755 });
+    const configPath = writeTempWranglerToml('irc.fowl.cloud');
+    const prevPath = process.env.PATH;
+    process.env.PATH = `${dir}:${prevPath ?? ''}`;
+    try {
+      expect(runDeploy([configPath], {})).toBe(3);
+    } finally {
+      process.env.PATH = prevPath;
+    }
+  });
+
+  it('returns 1 when wrangler dies to a signal (null status fallback)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'cf-deploy-sigshim-'));
+    tmpDirs.push(dir);
+    writeFileSync(join(dir, 'wrangler'), '#!/bin/sh\nkill -TERM $$\n', { mode: 0o755 });
+    const configPath = writeTempWranglerToml('irc.fowl.cloud');
+    const prevPath = process.env.PATH;
+    process.env.PATH = `${dir}:${prevPath ?? ''}`;
+    try {
+      expect(runDeploy([configPath], {})).toBe(1);
+    } finally {
+      process.env.PATH = prevPath;
+    }
+  });
+});

package/tools/ci-hardening/tests/deploy-aws-oidc.test.ts

@@ -0,0 +1,96 @@
+/**
+ * OIDC-only AWS deploy enforcement.
+ *
+ * The deploy workflow (`.github/workflows/deploy-aws.yml`) must NOT
+ * accept long-lived access keys. It must require an OIDC web-identity
+ * role (`AWS_DEPLOY_ROLE_ARN`), grant `id-token: write`, fail fast when
+ * the role ARN is missing, and assert that `aws sts get-caller-identity`
+ * returns the configured role before any `cdk deploy` / `cdk synth` —
+ * so a silent fallback to ambient static credentials cannot ship a
+ * deploy.
+ *
+ * These assertions run as part of the CI-hardening suite on every PR,
+ * the same way the coverage-gate and mutation-testing contracts do.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  findAwsCredentialSteps,
+  readWorkflowJob,
+  readWorkflowPermissions,
+} from '../src/validate.js';
+
+const REPO_ROOT = resolve(import.meta.dirname, '..', '..', '..');
+const WORKFLOW_PATH = resolve(REPO_ROOT, '.github/workflows/deploy-aws.yml');
+const WORKFLOW = readFileSync(WORKFLOW_PATH, 'utf8');
+
+describe('deploy-aws.yml: OIDC is the only accepted AWS credential source', () => {
+  it('does NOT pass aws-access-key-id / aws-secret-access-key to configure-aws-credentials', () => {
+    const steps = findAwsCredentialSteps(WORKFLOW);
+    expect(steps.length).toBeGreaterThan(0);
+    for (const step of steps) {
+      expect(step.with).not.toHaveProperty('aws-access-key-id');
+      expect(step.with).not.toHaveProperty('aws-secret-access-key');
+    }
+  });
+
+  it('configures a role-to-assume on every configure-aws-credentials step', () => {
+    const steps = findAwsCredentialSteps(WORKFLOW);
+    expect(steps.length).toBeGreaterThan(0);
+    for (const step of steps) {
+      expect(step.with['role-to-assume']).toBeDefined();
+    }
+  });
+
+  it('grants id-token: write at the top level (OIDC minting requires it)', () => {
+    const permissions = readWorkflowPermissions(WORKFLOW);
+    expect(permissions['id-token']).toBe('write');
+  });
+
+  it('keeps the permissions block least-privilege (only id-token + contents)', () => {
+    const permissions = readWorkflowPermissions(WORKFLOW);
+    expect(permissions.contents).toBe('read');
+    const keys = Object.keys(permissions).sort();
+    expect(keys).toEqual(['contents', 'id-token']);
+  });
+
+  it('fails fast when AWS_DEPLOY_ROLE_ARN is empty (guard step exists in every AWS-touching job)', () => {
+    // The "deploy" job runs `pnpm deploy:aws` (cdk deploy) and the
+    // "deploy-web" job runs `node scripts/deploy-web-aws.mjs`. Both
+    // must abort before any AWS call if the role ARN secret is unset.
+    for (const jobName of ['deploy', 'deploy-web']) {
+      const job = readWorkflowJob(WORKFLOW, jobName);
+      const hasGuard = job.steps.some((step) => {
+        const ifExpr = typeof step.if === 'string' ? step.if : '';
+        const env = step.env as Record<string, string> | undefined;
+        return (
+          ifExpr.includes('AWS_DEPLOY_ROLE_ARN') &&
+          ifExpr.includes("== ''") &&
+          env !== undefined &&
+          typeof env.AWS_DEPLOY_ROLE_ARN === 'string' &&
+          typeof step.run === 'string' &&
+          step.run.includes('exit 1')
+        );
+      });
+      expect(hasGuard).toBe(true);
+    }
+  });
+
+  it('asserts the sts get-caller-identity ARN matches the configured role before any CDK call', () => {
+    // The "deploy" job gates `cdk deploy`. It must, after
+    // configure-aws-credentials and before `pnpm deploy:aws`, run
+    // `aws sts get-caller-identity` and reject anything that is not
+    // the configured role ARN. This catches silent fallbacks to
+    // ambient static credentials.
+    const job = readWorkflowJob(WORKFLOW, 'deploy');
+    const runSteps = job.steps
+      .filter((s) => typeof s.run === 'string')
+      .map((s) => (s.run as string).trim());
+    const hasStsGuard = runSteps.some(
+      (r) => r.includes('aws sts get-caller-identity') && r.includes('AWS_DEPLOY_ROLE_ARN'),
+    );
+    expect(hasStsGuard).toBe(true);
+  });
+});