@continuous-excellence/ze-great-dashboard-aws 0.1.32 → 0.2.0

package/dist/cli.js

@@ -892,8 +892,8 @@ function coreBootstrapOutputs(stack) {
       (output) => Boolean(output.OutputValue)
     ).map((output) => [output.OutputKey, output.OutputValue])
   );
-  const required = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
-  const missing = required.filter((key) => !values[key]);
+  const required2 = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
+  const missing = required2.filter((key) => !values[key]);
   if (missing.length) throw new Error(`Core stack JSON is missing outputs: ${missing.join(", ")}`);
   return values;
 }
@@ -914,6 +914,383 @@ function requiredBootstrapParameters(kind, values) {
   return [...keys, ...optional].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
 }
 
+// packages/aws/src/handoff.ts
+var githubSubjectKeys = [
+  "repository_owner",
+  "repository_owner_id",
+  "repository",
+  "repository_id",
+  "context"
+];
+function outputValues(stack) {
+  return Object.fromEntries(
+    (stack.Outputs ?? []).filter(
+      (entry) => typeof entry.OutputKey === "string" && typeof entry.OutputValue === "string"
+    ).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
+  );
+}
+function parameterValues(stack) {
+  return Object.fromEntries(
+    (stack.Parameters ?? []).filter(
+      (entry) => typeof entry.ParameterKey === "string" && typeof entry.ParameterValue === "string"
+    ).map(({ ParameterKey, ParameterValue }) => [ParameterKey, ParameterValue])
+  );
+}
+function capturedStackIdentity(input) {
+  const candidate = input && typeof input === "object" && "Stacks" in input ? input.Stacks?.[0] : input;
+  if (!candidate || typeof candidate !== "object") return {};
+  const { StackName, StackId } = candidate;
+  return {
+    ...typeof StackName === "string" ? { StackName } : {},
+    ...typeof StackId === "string" ? { StackId } : {}
+  };
+}
+function required(value, name) {
+  if (!value) throw new Error(`Bootstrap manifest is missing ${name}`);
+  return value;
+}
+function region(config) {
+  return required(config.region, "region");
+}
+function stackName(config, kind) {
+  return required(
+    kind === "core" ? config.core?.stackName : config.githubOidc?.stackName,
+    `${kind}.stackName`
+  );
+}
+function changeSetCommands(input) {
+  const name = `${input.kind}-initial-review`;
+  const stack = stackName(input.config, input.kind);
+  const common = ["--stack-name", stack, "--region", region(input.config)];
+  const parameters = [
+    "ze-great-dashboard-aws",
+    "bootstrap",
+    "parameters",
+    "--kind",
+    input.kind,
+    "--config",
+    input.configPath,
+    "--output",
+    input.parameterPath
+  ];
+  if (input.kind === "github-oidc")
+    parameters.push("--core-stack-json", input.coreCapturePath ?? "core-deployed-stack.json");
+  return [
+    { name: "generate-parameters", args: parameters },
+    {
+      name: "create-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "create-change-set",
+        ...common,
+        "--change-set-name",
+        name,
+        "--change-set-type",
+        "CREATE",
+        "--template-body",
+        `file://${input.templatePath}`,
+        "--parameters",
+        `file://${input.parameterPath}`,
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        "--no-cli-pager"
+      ]
+    },
+    {
+      name: "wait-for-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "wait",
+        "change-set-create-complete",
+        ...common,
+        "--change-set-name",
+        name
+      ]
+    },
+    {
+      name: "review-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "describe-change-set",
+        ...common,
+        "--change-set-name",
+        name,
+        "--no-cli-pager"
+      ]
+    },
+    {
+      name: "execute-reviewed-change-set",
+      args: ["aws", "cloudformation", "execute-change-set", ...common, "--change-set-name", name]
+    },
+    {
+      name: "wait-for-stack",
+      args: ["aws", "cloudformation", "wait", "stack-create-complete", ...common]
+    },
+    {
+      name: "capture-stack",
+      captureFile: `${input.kind}-deployed-stack.json`,
+      args: ["aws", "cloudformation", "describe-stacks", ...common, "--no-cli-pager"]
+    }
+  ];
+}
+var githubOidcProvider = {
+  name: "github-oidc",
+  async prerequisite(config, runner) {
+    const repository = config.githubOidc?.repository;
+    if (!repository)
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub repository is absent from the manifest."
+      };
+    if (!runner)
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub OIDC subject setting was not queried."
+      };
+    try {
+      const response = JSON.parse(
+        await runner.execute("gh", ["api", `repos/${repository}/actions/oidc/customization/sub`])
+      );
+      const keys = response.include_claim_keys;
+      if (response.use_default === false && Array.isArray(keys) && githubSubjectKeys.every((key) => keys.includes(key)))
+        return {
+          status: "ready",
+          blocking: false,
+          detail: "GitHub emits the immutable owner/repository-ID OIDC subject required by this adapter."
+        };
+      return {
+        status: "immutable-subject-required",
+        blocking: true,
+        detail: "Coordinate migration: inventory and temporarily make existing name-based trust policies compatible, enable immutable GitHub OIDC subjects as a separate GitHub-admin action, verify existing deployments, then retire legacy trust."
+      };
+    } catch {
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub OIDC subject setting could not be verified (gh CLI, authentication, permission, or network unavailable)."
+      };
+    }
+  }
+};
+async function contracts() {
+  return {
+    core: bootstrapContractVersion(await bootstrapTemplate("core")),
+    githubOidc: bootstrapContractVersion(await bootstrapTemplate("github-oidc"))
+  };
+}
+async function bootstrapHandoff(input) {
+  const expectedContracts = await contracts();
+  const coreCapturePath = input.coreStackPath ?? "core-deployed-stack.json";
+  const core = input.coreStack === void 0 ? void 0 : deployedBootstrapStack(input.coreStack, expectedContracts.core);
+  const oidc = input.githubOidcStack === void 0 ? void 0 : deployedBootstrapStack(input.githubOidcStack, expectedContracts.githubOidc);
+  if (!core) {
+    requiredBootstrapParameters("core", {
+      ArtifactBucketName: input.config.core?.artifactBucketName,
+      ApplicationStackName: input.config.core?.applicationStackName,
+      DashboardFunctionName: input.config.core?.dashboardFunctionName
+    });
+    const templatePath = await bootstrapTemplatePath("core");
+    return {
+      phase: "core",
+      expectedContracts,
+      templatePath,
+      parameterPath: "core-bootstrap.json",
+      requiredCapturedFiles: [],
+      reviewCheckpoints: [
+        "Review every IAM action and CAPABILITY_NAMED_IAM acknowledgement.",
+        "Do not approve retained bucket or role replacements."
+      ],
+      commands: changeSetCommands({
+        kind: "core",
+        config: input.config,
+        configPath: input.configPath,
+        templatePath,
+        parameterPath: "core-bootstrap.json"
+      })
+    };
+  }
+  coreBootstrapOutputs(core);
+  if (!oidc) {
+    requiredBootstrapParameters("github-oidc", {
+      GitHubOidcProviderArn: input.config.githubOidc?.providerArn,
+      GitHubRepository: input.config.githubOidc?.repository,
+      GitHubOwnerId: input.config.githubOidc?.ownerId,
+      GitHubRepositoryId: input.config.githubOidc?.repositoryId,
+      GitHubEnvironment: input.config.githubOidc?.environment,
+      ...coreBootstrapOutputs(core)
+    });
+    const templatePath = await bootstrapTemplatePath("github-oidc");
+    return {
+      phase: "github-oidc",
+      expectedContracts,
+      templatePath,
+      parameterPath: "github-oidc-bootstrap.json",
+      requiredCapturedFiles: [coreCapturePath],
+      reviewCheckpoints: [
+        "Review the exact immutable GitHub OIDC subject, audience, bucket lambda/* prefix, application stack, and execution role.",
+        "Do not execute until the GitHub Environment prerequisite is ready."
+      ],
+      commands: changeSetCommands({
+        kind: "github-oidc",
+        config: input.config,
+        configPath: input.configPath,
+        templatePath,
+        parameterPath: "github-oidc-bootstrap.json",
+        coreCapturePath
+      }),
+      prerequisite: await (input.provider ?? githubOidcProvider).prerequisite(
+        input.config,
+        input.runner
+      )
+    };
+  }
+  const prerequisite = await (input.provider ?? githubOidcProvider).prerequisite(
+    input.config,
+    input.runner
+  );
+  if (prerequisite.status !== "ready")
+    return {
+      phase: "github-environment",
+      expectedContracts,
+      requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+      reviewCheckpoints: [
+        "A GitHub administrator must complete and verify the immutable-subject migration before deployments."
+      ],
+      commands: [],
+      prerequisite
+    };
+  return {
+    phase: "application-gateway",
+    expectedContracts,
+    requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+    reviewCheckpoints: [
+      "Consumer owns gateway selection, private Lambda permission, authentication, and smoke tests."
+    ],
+    commands: [],
+    prerequisite
+  };
+}
+function assertEqual(actual, expected, label) {
+  if (actual !== expected)
+    throw new Error(
+      `${label} mismatch (captured: ${actual ?? "missing"}; manifest: ${expected ?? "missing"})`
+    );
+}
+async function verifyBootstrap(input) {
+  const expected = await contracts();
+  const core = deployedBootstrapStack(input.coreStack, expected.core);
+  const oidc = deployedBootstrapStack(input.githubOidcStack, expected.githubOidc);
+  for (const [kind, capture] of [
+    ["Core", capturedStackIdentity(input.coreStack)],
+    ["GitHub OIDC", capturedStackIdentity(input.githubOidcStack)]
+  ]) {
+    const expectedName = kind === "Core" ? input.config.core?.stackName : input.config.githubOidc?.stackName;
+    assertEqual(capture.StackName, expectedName, `${kind} stack name`);
+    const capturedRegion = capture.StackId?.match(/^arn:[^:]+:cloudformation:([^:]+):/)?.[1];
+    assertEqual(capturedRegion, input.config.region, `${kind} stack Region`);
+  }
+  const coreOutputs = coreBootstrapOutputs(core);
+  const coreParameters = parameterValues(core);
+  assertEqual(
+    coreParameters.ArtifactBucketName,
+    input.config.core?.artifactBucketName,
+    "Artifact bucket"
+  );
+  assertEqual(
+    coreParameters.ApplicationStackName,
+    input.config.core?.applicationStackName,
+    "Application stack"
+  );
+  assertEqual(
+    coreParameters.DashboardFunctionName,
+    input.config.core?.dashboardFunctionName,
+    "Dashboard function"
+  );
+  assertEqual(
+    coreOutputs.ArtifactBucketName,
+    input.config.core?.artifactBucketName,
+    "Core output artifact bucket"
+  );
+  assertEqual(
+    coreOutputs.ApplicationStackName,
+    input.config.core?.applicationStackName,
+    "Core output application stack"
+  );
+  const oidcParameters = parameterValues(oidc);
+  const github = input.config.githubOidc;
+  const executionRole = required(
+    coreOutputs.CloudFormationExecutionRoleArn,
+    "core CloudFormationExecutionRoleArn output"
+  );
+  for (const [key, value] of Object.entries({
+    GitHubOidcProviderArn: github?.providerArn,
+    GitHubRepository: github?.repository,
+    GitHubOwnerId: github?.ownerId,
+    GitHubRepositoryId: github?.repositoryId,
+    GitHubEnvironment: github?.environment,
+    ApplicationStackName: coreOutputs.ApplicationStackName,
+    ArtifactBucketName: coreOutputs.ArtifactBucketName,
+    CloudFormationExecutionRoleArn: executionRole
+  }))
+    assertEqual(oidcParameters[key], value, `OIDC ${key}`);
+  if (!/^\d+$/.test(github?.ownerId ?? "") || !/^\d+$/.test(github?.repositoryId ?? ""))
+    throw new Error("GitHub immutable owner and repository IDs must be numeric");
+  const [owner, repository, ...extra] = (github?.repository ?? "").split("/");
+  if (!owner || !repository || extra.length)
+    throw new Error("GitHub repository must be owner/repository");
+  const deployRole = outputValues(oidc).GitHubDeployRoleArn;
+  if (!deployRole) throw new Error("GitHub OIDC stack JSON is missing outputs: GitHubDeployRoleArn");
+  const providerArn = github?.providerArn ?? "";
+  const account = providerArn.match(/^arn:[^:]+:iam::(\d+):oidc-provider\//)?.[1];
+  const deployAccount = deployRole.match(/^arn:[^:]+:iam::(\d+):role\//)?.[1];
+  const executionAccount = executionRole.match(/^arn:[^:]+:iam::(\d+):role\//)?.[1];
+  if (!account || account !== deployAccount || account !== executionAccount)
+    throw new Error("Provider and reviewed role ARNs must belong to the same AWS account");
+  return {
+    verified: true,
+    immutableSubject: `repo:${owner}@${github?.ownerId}/${repository}@${github?.repositoryId}:environment:${github?.environment}`,
+    environmentVariables: {
+      AWS_DEPLOY_ROLE_ARN: deployRole,
+      AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN: executionRole
+    },
+    reviewedArns: {
+      githubDeployRoleArn: deployRole,
+      cloudFormationExecutionRoleArn: executionRole
+    },
+    githubEnvironmentInstructions: [
+      [
+        "gh",
+        "variable",
+        "set",
+        "AWS_DEPLOY_ROLE_ARN",
+        "--repo",
+        `${owner}/${repository}`,
+        "--env",
+        github?.environment ?? "",
+        "--body",
+        deployRole
+      ],
+      [
+        "gh",
+        "variable",
+        "set",
+        "AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN",
+        "--repo",
+        `${owner}/${repository}`,
+        "--env",
+        github?.environment ?? "",
+        "--body",
+        executionRole
+      ]
+    ]
+  };
+}
+
 // packages/aws/src/index.ts
 var run = promisify(execFile);
 function deploymentTemplate(template, values) {
@@ -1318,9 +1695,9 @@ try {
     console.log(JSON.stringify({ published: true, version, assetPath }));
   } else if (args[0] === "doctor") {
     const parametersPath = option("--parameters", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
-    const region = option("--region", process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1") ?? "us-east-1";
+    const region2 = option("--region", process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1") ?? "us-east-1";
     const checks = await runDoctor(
-      { parametersPath, region },
+      { parametersPath, region: region2 },
       {
         async execute(command, commandArgs) {
           const { execFile: execFile3 } = await import("node:child_process");
@@ -1380,9 +1757,45 @@ try {
     console.log(JSON.stringify({ output }));
   } else if (args[0] === "bootstrap") {
     const action = args[1];
-    const kind = bootstrapKind();
     const config = await bootstrapConfig();
-    if (action === "template") {
+    if (action === "handoff") {
+      const configPath = requiredOption("--config");
+      const coreStackPath = option("--core-stack-json");
+      const githubStackPath = option("--github-oidc-stack-json");
+      const runner = {
+        async execute(command, commandArgs) {
+          const { execFile: execFile3 } = await import("node:child_process");
+          const { promisify: promisify3 } = await import("node:util");
+          return (await promisify3(execFile3)(command, commandArgs)).stdout.trim();
+        }
+      };
+      console.log(
+        JSON.stringify(
+          await bootstrapHandoff({
+            config,
+            configPath,
+            coreStack: coreStackPath ? JSON.parse(await readFile5(coreStackPath, "utf8")) : void 0,
+            coreStackPath,
+            githubOidcStack: githubStackPath ? JSON.parse(await readFile5(githubStackPath, "utf8")) : void 0,
+            runner
+          })
+        )
+      );
+    } else if (action === "verify") {
+      requiredOption("--config");
+      const coreStackPath = requiredOption("--core-stack-json");
+      const githubStackPath = requiredOption("--github-oidc-stack-json");
+      console.log(
+        JSON.stringify(
+          await verifyBootstrap({
+            config,
+            coreStack: JSON.parse(await readFile5(coreStackPath, "utf8")),
+            githubOidcStack: JSON.parse(await readFile5(githubStackPath, "utf8"))
+          })
+        )
+      );
+    } else if (action === "template") {
+      const kind = bootstrapKind();
       console.log(
         JSON.stringify({
           kind,
@@ -1391,6 +1804,7 @@ try {
         })
       );
     } else if (action === "parameters") {
+      const kind = bootstrapKind();
       const output = option("--output", `aws-dashboard-bootstrap-${kind}.json`) ?? `aws-dashboard-bootstrap-${kind}.json`;
       let coreOutputs = {};
       const coreStackPath = option("--core-stack-json");
@@ -1418,15 +1832,16 @@ try {
         JSON.stringify({ output, kind, preservedDeployedValues: Boolean(deployedStackPath) })
       );
     } else if (action === "status") {
-      const stackName = requiredOption("--stack-name", bootstrapStackName(kind, config));
-      const region = option("--region", config.region);
+      const kind = bootstrapKind();
+      const stackName2 = requiredOption("--stack-name", bootstrapStackName(kind, config));
+      const region2 = option("--region", config.region);
       const awsCommand = [
         "aws",
         "cloudformation",
         "describe-stacks",
         "--stack-name",
-        stackName,
-        ...region ? ["--region", region] : [],
+        stackName2,
+        ...region2 ? ["--region", region2] : [],
         "--no-cli-pager"
       ];
       console.log(
@@ -1438,17 +1853,18 @@ try {
         })
       );
     } else if (action === "change-set") {
-      const stackName = requiredOption("--stack-name", bootstrapStackName(kind, config));
+      const kind = bootstrapKind();
+      const stackName2 = requiredOption("--stack-name", bootstrapStackName(kind, config));
       const changeSetName = requiredOption("--change-set-name");
       const parametersPath = requiredOption("--parameters");
-      const region = option("--region", config.region);
+      const region2 = option("--region", config.region);
       await existingParameters(parametersPath);
       const awsCommand = [
         "aws",
         "cloudformation",
         "create-change-set",
         "--stack-name",
-        stackName,
+        stackName2,
         "--change-set-name",
         changeSetName,
         "--change-set-type",
@@ -1459,7 +1875,7 @@ try {
         `file://${parametersPath}`,
         "--capabilities",
         "CAPABILITY_NAMED_IAM",
-        ...region ? ["--region", region] : [],
+        ...region2 ? ["--region", region2] : [],
         "--no-cli-pager"
       ];
       console.log(
@@ -1472,7 +1888,7 @@ try {
       );
     } else {
       throw new Error(
-        "Usage: ze-great-dashboard-aws bootstrap template|parameters|status|change-set --kind core|github-oidc [options]"
+        "Usage: ze-great-dashboard-aws bootstrap handoff|verify --config manifest.json [options], or bootstrap template|parameters|status|change-set --kind core|github-oidc [options]"
       );
     }
   } else if (args[0] !== "package")

package/dist/handoff.d.ts

@@ -0,0 +1,60 @@
+import { type BootstrapConfig } from './bootstrap.js';
+export type BootstrapPhase = 'core' | 'github-oidc' | 'github-environment' | 'application-gateway';
+export type CommandRunner = {
+    execute(command: string, args: string[]): Promise<string>;
+};
+export type BootstrapProvider = {
+    readonly name: string;
+    prerequisite(config: BootstrapConfig, runner?: CommandRunner): Promise<ProviderPrerequisite>;
+};
+export type ProviderPrerequisite = {
+    status: 'ready' | 'immutable-subject-required' | 'unverified';
+    blocking: boolean;
+    detail: string;
+};
+export type HandoffCommand = {
+    name: string;
+    args: string[];
+    captureFile?: string;
+};
+export type BootstrapHandoff = {
+    phase: BootstrapPhase;
+    expectedContracts: {
+        core: string;
+        githubOidc: string;
+    };
+    templatePath?: string;
+    parameterPath?: string;
+    requiredCapturedFiles: string[];
+    reviewCheckpoints: string[];
+    commands: HandoffCommand[];
+    prerequisite?: ProviderPrerequisite;
+};
+export type BootstrapVerification = {
+    verified: true;
+    immutableSubject: string;
+    environmentVariables: {
+        AWS_DEPLOY_ROLE_ARN: string;
+        AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN: string;
+    };
+    reviewedArns: {
+        githubDeployRoleArn: string;
+        cloudFormationExecutionRoleArn: string;
+    };
+    githubEnvironmentInstructions: string[][];
+};
+export declare const githubOidcProvider: BootstrapProvider;
+export declare function bootstrapHandoff(input: {
+    config: BootstrapConfig;
+    configPath: string;
+    coreStack?: unknown;
+    coreStackPath?: string;
+    githubOidcStack?: unknown;
+    provider?: BootstrapProvider;
+    runner?: CommandRunner;
+}): Promise<BootstrapHandoff>;
+export declare function verifyBootstrap(input: {
+    config: BootstrapConfig;
+    coreStack: unknown;
+    githubOidcStack: unknown;
+}): Promise<BootstrapVerification>;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { type BootstrapConfig, type BootstrapKind, bootstrapContractVersion, bootstrapTemplate, bootstrapTemplatePath, type CloudFormationParameterValue, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requiredBootstrapParameters, } from './bootstrap.js';
+export { type BootstrapHandoff, type BootstrapPhase, type BootstrapProvider, type BootstrapVerification, bootstrapHandoff, type CommandRunner, githubOidcProvider, verifyBootstrap, } from './handoff.js';
 export type ReleaseMetadata = {
     dashboardVersion: string;
     clientAssetUrl: string;

package/dist/index.js

@@ -879,8 +879,8 @@ function coreBootstrapOutputs(stack) {
       (output) => Boolean(output.OutputValue)
     ).map((output) => [output.OutputKey, output.OutputValue])
   );
-  const required = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
-  const missing = required.filter((key) => !values[key]);
+  const required2 = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
+  const missing = required2.filter((key) => !values[key]);
   if (missing.length) throw new Error(`Core stack JSON is missing outputs: ${missing.join(", ")}`);
   return values;
 }
@@ -901,6 +901,383 @@ function requiredBootstrapParameters(kind, values) {
   return [...keys, ...optional].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
 }
 
+// packages/aws/src/handoff.ts
+var githubSubjectKeys = [
+  "repository_owner",
+  "repository_owner_id",
+  "repository",
+  "repository_id",
+  "context"
+];
+function outputValues(stack) {
+  return Object.fromEntries(
+    (stack.Outputs ?? []).filter(
+      (entry) => typeof entry.OutputKey === "string" && typeof entry.OutputValue === "string"
+    ).map(({ OutputKey, OutputValue }) => [OutputKey, OutputValue])
+  );
+}
+function parameterValues(stack) {
+  return Object.fromEntries(
+    (stack.Parameters ?? []).filter(
+      (entry) => typeof entry.ParameterKey === "string" && typeof entry.ParameterValue === "string"
+    ).map(({ ParameterKey, ParameterValue }) => [ParameterKey, ParameterValue])
+  );
+}
+function capturedStackIdentity(input) {
+  const candidate = input && typeof input === "object" && "Stacks" in input ? input.Stacks?.[0] : input;
+  if (!candidate || typeof candidate !== "object") return {};
+  const { StackName, StackId } = candidate;
+  return {
+    ...typeof StackName === "string" ? { StackName } : {},
+    ...typeof StackId === "string" ? { StackId } : {}
+  };
+}
+function required(value, name) {
+  if (!value) throw new Error(`Bootstrap manifest is missing ${name}`);
+  return value;
+}
+function region(config) {
+  return required(config.region, "region");
+}
+function stackName(config, kind) {
+  return required(
+    kind === "core" ? config.core?.stackName : config.githubOidc?.stackName,
+    `${kind}.stackName`
+  );
+}
+function changeSetCommands(input) {
+  const name = `${input.kind}-initial-review`;
+  const stack = stackName(input.config, input.kind);
+  const common = ["--stack-name", stack, "--region", region(input.config)];
+  const parameters = [
+    "ze-great-dashboard-aws",
+    "bootstrap",
+    "parameters",
+    "--kind",
+    input.kind,
+    "--config",
+    input.configPath,
+    "--output",
+    input.parameterPath
+  ];
+  if (input.kind === "github-oidc")
+    parameters.push("--core-stack-json", input.coreCapturePath ?? "core-deployed-stack.json");
+  return [
+    { name: "generate-parameters", args: parameters },
+    {
+      name: "create-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "create-change-set",
+        ...common,
+        "--change-set-name",
+        name,
+        "--change-set-type",
+        "CREATE",
+        "--template-body",
+        `file://${input.templatePath}`,
+        "--parameters",
+        `file://${input.parameterPath}`,
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        "--no-cli-pager"
+      ]
+    },
+    {
+      name: "wait-for-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "wait",
+        "change-set-create-complete",
+        ...common,
+        "--change-set-name",
+        name
+      ]
+    },
+    {
+      name: "review-change-set",
+      args: [
+        "aws",
+        "cloudformation",
+        "describe-change-set",
+        ...common,
+        "--change-set-name",
+        name,
+        "--no-cli-pager"
+      ]
+    },
+    {
+      name: "execute-reviewed-change-set",
+      args: ["aws", "cloudformation", "execute-change-set", ...common, "--change-set-name", name]
+    },
+    {
+      name: "wait-for-stack",
+      args: ["aws", "cloudformation", "wait", "stack-create-complete", ...common]
+    },
+    {
+      name: "capture-stack",
+      captureFile: `${input.kind}-deployed-stack.json`,
+      args: ["aws", "cloudformation", "describe-stacks", ...common, "--no-cli-pager"]
+    }
+  ];
+}
+var githubOidcProvider = {
+  name: "github-oidc",
+  async prerequisite(config, runner) {
+    const repository = config.githubOidc?.repository;
+    if (!repository)
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub repository is absent from the manifest."
+      };
+    if (!runner)
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub OIDC subject setting was not queried."
+      };
+    try {
+      const response = JSON.parse(
+        await runner.execute("gh", ["api", `repos/${repository}/actions/oidc/customization/sub`])
+      );
+      const keys = response.include_claim_keys;
+      if (response.use_default === false && Array.isArray(keys) && githubSubjectKeys.every((key) => keys.includes(key)))
+        return {
+          status: "ready",
+          blocking: false,
+          detail: "GitHub emits the immutable owner/repository-ID OIDC subject required by this adapter."
+        };
+      return {
+        status: "immutable-subject-required",
+        blocking: true,
+        detail: "Coordinate migration: inventory and temporarily make existing name-based trust policies compatible, enable immutable GitHub OIDC subjects as a separate GitHub-admin action, verify existing deployments, then retire legacy trust."
+      };
+    } catch {
+      return {
+        status: "unverified",
+        blocking: false,
+        detail: "GitHub OIDC subject setting could not be verified (gh CLI, authentication, permission, or network unavailable)."
+      };
+    }
+  }
+};
+async function contracts() {
+  return {
+    core: bootstrapContractVersion(await bootstrapTemplate("core")),
+    githubOidc: bootstrapContractVersion(await bootstrapTemplate("github-oidc"))
+  };
+}
+async function bootstrapHandoff(input) {
+  const expectedContracts = await contracts();
+  const coreCapturePath = input.coreStackPath ?? "core-deployed-stack.json";
+  const core = input.coreStack === void 0 ? void 0 : deployedBootstrapStack(input.coreStack, expectedContracts.core);
+  const oidc = input.githubOidcStack === void 0 ? void 0 : deployedBootstrapStack(input.githubOidcStack, expectedContracts.githubOidc);
+  if (!core) {
+    requiredBootstrapParameters("core", {
+      ArtifactBucketName: input.config.core?.artifactBucketName,
+      ApplicationStackName: input.config.core?.applicationStackName,
+      DashboardFunctionName: input.config.core?.dashboardFunctionName
+    });
+    const templatePath = await bootstrapTemplatePath("core");
+    return {
+      phase: "core",
+      expectedContracts,
+      templatePath,
+      parameterPath: "core-bootstrap.json",
+      requiredCapturedFiles: [],
+      reviewCheckpoints: [
+        "Review every IAM action and CAPABILITY_NAMED_IAM acknowledgement.",
+        "Do not approve retained bucket or role replacements."
+      ],
+      commands: changeSetCommands({
+        kind: "core",
+        config: input.config,
+        configPath: input.configPath,
+        templatePath,
+        parameterPath: "core-bootstrap.json"
+      })
+    };
+  }
+  coreBootstrapOutputs(core);
+  if (!oidc) {
+    requiredBootstrapParameters("github-oidc", {
+      GitHubOidcProviderArn: input.config.githubOidc?.providerArn,
+      GitHubRepository: input.config.githubOidc?.repository,
+      GitHubOwnerId: input.config.githubOidc?.ownerId,
+      GitHubRepositoryId: input.config.githubOidc?.repositoryId,
+      GitHubEnvironment: input.config.githubOidc?.environment,
+      ...coreBootstrapOutputs(core)
+    });
+    const templatePath = await bootstrapTemplatePath("github-oidc");
+    return {
+      phase: "github-oidc",
+      expectedContracts,
+      templatePath,
+      parameterPath: "github-oidc-bootstrap.json",
+      requiredCapturedFiles: [coreCapturePath],
+      reviewCheckpoints: [
+        "Review the exact immutable GitHub OIDC subject, audience, bucket lambda/* prefix, application stack, and execution role.",
+        "Do not execute until the GitHub Environment prerequisite is ready."
+      ],
+      commands: changeSetCommands({
+        kind: "github-oidc",
+        config: input.config,
+        configPath: input.configPath,
+        templatePath,
+        parameterPath: "github-oidc-bootstrap.json",
+        coreCapturePath
+      }),
+      prerequisite: await (input.provider ?? githubOidcProvider).prerequisite(
+        input.config,
+        input.runner
+      )
+    };
+  }
+  const prerequisite = await (input.provider ?? githubOidcProvider).prerequisite(
+    input.config,
+    input.runner
+  );
+  if (prerequisite.status !== "ready")
+    return {
+      phase: "github-environment",
+      expectedContracts,
+      requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+      reviewCheckpoints: [
+        "A GitHub administrator must complete and verify the immutable-subject migration before deployments."
+      ],
+      commands: [],
+      prerequisite
+    };
+  return {
+    phase: "application-gateway",
+    expectedContracts,
+    requiredCapturedFiles: [coreCapturePath, "github-oidc-deployed-stack.json"],
+    reviewCheckpoints: [
+      "Consumer owns gateway selection, private Lambda permission, authentication, and smoke tests."
+    ],
+    commands: [],
+    prerequisite
+  };
+}
+function assertEqual(actual, expected, label) {
+  if (actual !== expected)
+    throw new Error(
+      `${label} mismatch (captured: ${actual ?? "missing"}; manifest: ${expected ?? "missing"})`
+    );
+}
+async function verifyBootstrap(input) {
+  const expected = await contracts();
+  const core = deployedBootstrapStack(input.coreStack, expected.core);
+  const oidc = deployedBootstrapStack(input.githubOidcStack, expected.githubOidc);
+  for (const [kind, capture] of [
+    ["Core", capturedStackIdentity(input.coreStack)],
+    ["GitHub OIDC", capturedStackIdentity(input.githubOidcStack)]
+  ]) {
+    const expectedName = kind === "Core" ? input.config.core?.stackName : input.config.githubOidc?.stackName;
+    assertEqual(capture.StackName, expectedName, `${kind} stack name`);
+    const capturedRegion = capture.StackId?.match(/^arn:[^:]+:cloudformation:([^:]+):/)?.[1];
+    assertEqual(capturedRegion, input.config.region, `${kind} stack Region`);
+  }
+  const coreOutputs = coreBootstrapOutputs(core);
+  const coreParameters = parameterValues(core);
+  assertEqual(
+    coreParameters.ArtifactBucketName,
+    input.config.core?.artifactBucketName,
+    "Artifact bucket"
+  );
+  assertEqual(
+    coreParameters.ApplicationStackName,
+    input.config.core?.applicationStackName,
+    "Application stack"
+  );
+  assertEqual(
+    coreParameters.DashboardFunctionName,
+    input.config.core?.dashboardFunctionName,
+    "Dashboard function"
+  );
+  assertEqual(
+    coreOutputs.ArtifactBucketName,
+    input.config.core?.artifactBucketName,
+    "Core output artifact bucket"
+  );
+  assertEqual(
+    coreOutputs.ApplicationStackName,
+    input.config.core?.applicationStackName,
+    "Core output application stack"
+  );
+  const oidcParameters = parameterValues(oidc);
+  const github = input.config.githubOidc;
+  const executionRole = required(
+    coreOutputs.CloudFormationExecutionRoleArn,
+    "core CloudFormationExecutionRoleArn output"
+  );
+  for (const [key, value] of Object.entries({
+    GitHubOidcProviderArn: github?.providerArn,
+    GitHubRepository: github?.repository,
+    GitHubOwnerId: github?.ownerId,
+    GitHubRepositoryId: github?.repositoryId,
+    GitHubEnvironment: github?.environment,
+    ApplicationStackName: coreOutputs.ApplicationStackName,
+    ArtifactBucketName: coreOutputs.ArtifactBucketName,
+    CloudFormationExecutionRoleArn: executionRole
+  }))
+    assertEqual(oidcParameters[key], value, `OIDC ${key}`);
+  if (!/^\d+$/.test(github?.ownerId ?? "") || !/^\d+$/.test(github?.repositoryId ?? ""))
+    throw new Error("GitHub immutable owner and repository IDs must be numeric");
+  const [owner, repository, ...extra] = (github?.repository ?? "").split("/");
+  if (!owner || !repository || extra.length)
+    throw new Error("GitHub repository must be owner/repository");
+  const deployRole = outputValues(oidc).GitHubDeployRoleArn;
+  if (!deployRole) throw new Error("GitHub OIDC stack JSON is missing outputs: GitHubDeployRoleArn");
+  const providerArn = github?.providerArn ?? "";
+  const account = providerArn.match(/^arn:[^:]+:iam::(\d+):oidc-provider\//)?.[1];
+  const deployAccount = deployRole.match(/^arn:[^:]+:iam::(\d+):role\//)?.[1];
+  const executionAccount = executionRole.match(/^arn:[^:]+:iam::(\d+):role\//)?.[1];
+  if (!account || account !== deployAccount || account !== executionAccount)
+    throw new Error("Provider and reviewed role ARNs must belong to the same AWS account");
+  return {
+    verified: true,
+    immutableSubject: `repo:${owner}@${github?.ownerId}/${repository}@${github?.repositoryId}:environment:${github?.environment}`,
+    environmentVariables: {
+      AWS_DEPLOY_ROLE_ARN: deployRole,
+      AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN: executionRole
+    },
+    reviewedArns: {
+      githubDeployRoleArn: deployRole,
+      cloudFormationExecutionRoleArn: executionRole
+    },
+    githubEnvironmentInstructions: [
+      [
+        "gh",
+        "variable",
+        "set",
+        "AWS_DEPLOY_ROLE_ARN",
+        "--repo",
+        `${owner}/${repository}`,
+        "--env",
+        github?.environment ?? "",
+        "--body",
+        deployRole
+      ],
+      [
+        "gh",
+        "variable",
+        "set",
+        "AWS_CLOUDFORMATION_EXECUTION_ROLE_ARN",
+        "--repo",
+        `${owner}/${repository}`,
+        "--env",
+        github?.environment ?? "",
+        "--body",
+        executionRole
+      ]
+    ]
+  };
+}
+
 // packages/aws/src/index.ts
 var run = promisify(execFile);
 function deploymentTemplate(template, values) {
@@ -1041,14 +1418,17 @@ async function cloudFormationTemplate() {
 }
 export {
   bootstrapContractVersion,
+  bootstrapHandoff,
   bootstrapTemplate,
   bootstrapTemplatePath,
   cloudFormationTemplate,
   coreBootstrapOutputs,
   deployLambda,
   deployedBootstrapStack,
+  githubOidcProvider,
   mergeBootstrapParameters,
   packageLambda,
   publishClientAssets,
-  requiredBootstrapParameters
+  requiredBootstrapParameters,
+  verifyBootstrap
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuous-excellence/ze-great-dashboard-aws",
-  "version": "0.1.32",
+  "version": "0.2.0",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
   "keywords": [