@continuous-excellence/ze-great-dashboard-aws 0.4.1 → 0.5.0

package/README.md

@@ -8,6 +8,11 @@ It does not create a public endpoint, choose an authentication policy, create a
 secret value, or own consumer AWS infrastructure. You provide the protected gateway and complete the
 administrator-owned bootstrap process first.
 
+For a deployment workflow that verifies a consumer-owned gateway stack, configure
+`--consumer-gateway-stack gateway-stack-name` during `bootstrap init`. The GitHub OIDC v2 role then
+gets only `cloudformation:DescribeStacks` for that exact stack; the package still does not create,
+invoke, or authenticate the gateway.
+
 ## Prerequisites
 
 You need Node.js 22+, npm, the AWS CLI, `jq`, and one AWS Region for the artifact bucket, Lambda,
@@ -69,6 +74,11 @@ npm exec -- ze-great-dashboard-aws doctor \
   --region us-east-1
 ```
 
+If you retain a captured GitHub OIDC stack, add `--github-oidc-stack-json
+github-oidc-deployed-stack.json` to have the doctor warn when the installed package contains a
+newer bootstrap template revision. The warning is advisory and does not make the application
+deployment perform bootstrap changes.
+
 Package the release. This validates the board and writes `lambda.zip`, `release.json`, and
 `template.yml` to the output directory:
 
@@ -117,6 +127,12 @@ does not grant public Lambda invoke permission.
 To upgrade, install a newer exact package version and repeat package, upload, and deploy. A change to
 `board.yaml` follows the same path; it does not require a package change.
 
+After upgrading, also check the [bootstrap upgrade guidance](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md#check-the-bootstrap-template-on-package-upgrades).
+Compatible releases may add optional bootstrap capabilities without changing the contract version.
+If your workflow verifies a consumer-owned gateway stack, add `githubOidc.consumerGatewayStackName`
+to the reviewed manifest and update the GitHub OIDC stack; other consumers do not need to rerun
+bootstrap.
+
 Tokens belong in runtime secret handling, never in board YAML, `aws-dashboard-parameters.json`, or
 the generated ZIP. See [runtime secrets](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-setup.md#runtime-secrets)
 for the supported secret reference and integration boundary.

package/bootstrap/github-oidc-v2.yml

@@ -8,9 +8,16 @@ Parameters:
   GitHubRepositoryId: { Type: String, Description: Immutable numeric GitHub repository id }
   GitHubEnvironment: { Type: String, Description: Protected GitHub Environment name }
   ApplicationStackName: { Type: String }
+  ConsumerGatewayStackName:
+    Type: String
+    Default: ''
+    Description: Optional consumer-owned gateway stack whose outputs the deploy role may read
   ArtifactBucketName: { Type: String }
   CloudFormationExecutionRoleArn: { Type: String }
 
+Conditions:
+  HasConsumerGatewayStack: !Not [!Equals [!Ref ConsumerGatewayStackName, '']]
+
 Resources:
   GitHubDeployRole:
     Type: AWS::IAM::Role
@@ -49,6 +56,13 @@ Resources:
                 Effect: Allow
                 Action: [cloudformation:CreateChangeSet, cloudformation:DescribeChangeSet, cloudformation:ExecuteChangeSet, cloudformation:DeleteChangeSet, cloudformation:DescribeStacks, cloudformation:DescribeStackEvents, cloudformation:GetTemplate, cloudformation:GetTemplateSummary]
                 Resource: !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${ApplicationStackName}/*'
+              - !If
+                - HasConsumerGatewayStack
+                - Sid: ReadConsumerGatewayStack
+                  Effect: Allow
+                  Action: cloudformation:DescribeStacks
+                  Resource: !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${ConsumerGatewayStackName}/*'
+                - !Ref AWS::NoValue
               - Sid: PassCoreExecutionRole
                 Effect: Allow
                 Action: iam:PassRole
@@ -57,4 +71,5 @@ Resources:
 
 Outputs:
   BootstrapContractVersion: { Value: '2' }
+  BootstrapTemplateRevision: { Value: '2.1' }
   GitHubDeployRoleArn: { Value: !GetAtt GitHubDeployRole.Arn }

package/dist/bootstrap.d.ts

@@ -28,11 +28,13 @@ export type BootstrapConfig = {
         ownerId?: string;
         repositoryId?: string;
         environment?: string;
+        consumerGatewayStackName?: string;
     };
 };
 export declare function bootstrapTemplatePath(kind: BootstrapKind): Promise<string>;
 export declare function bootstrapTemplate(kind: BootstrapKind): Promise<string>;
 export declare function bootstrapContractVersion(template: string): string;
+export declare function bootstrapTemplateRevision(template: string): string;
 /** Merges a new parameter set with deployed values without silently dropping configuration. */
 export declare function mergeBootstrapParameters(requested: CloudFormationParameterValue[], deployed: CloudFormationParameterValue[]): CloudFormationParameterValue[];
 /** Validates a caller-captured `describe-stacks` result before an upgrade merges it locally. */

package/dist/cli.js

@@ -857,6 +857,11 @@ function bootstrapContractVersion(template) {
   if (!version) throw new Error("Bootstrap template has no BootstrapContractVersion output");
   return version;
 }
+function bootstrapTemplateRevision(template) {
+  const revision = template.match(/BootstrapTemplateRevision:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
+  if (!revision) throw new Error("Bootstrap template has no BootstrapTemplateRevision output");
+  return revision;
+}
 function mergeBootstrapParameters(requested, deployed) {
   const supplied = new Map(requested.map((entry) => [entry.ParameterKey, entry.ParameterValue]));
   const duplicates = requested.map((entry) => entry.ParameterKey);
@@ -910,7 +915,7 @@ function requiredBootstrapParameters(kind, values) {
   ];
   const missing = keys.filter((key) => !values[key]);
   if (missing.length) throw new Error(`Missing required bootstrap values: ${missing.join(", ")}`);
-  const optional2 = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : [];
+  const optional2 = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : ["ConsumerGatewayStackName"];
   return [...keys, ...optional2].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
 }
 
@@ -1128,6 +1133,7 @@ async function bootstrapHandoff(input) {
       GitHubOwnerId: input.config.githubOidc?.ownerId,
       GitHubRepositoryId: input.config.githubOidc?.repositoryId,
       GitHubEnvironment: input.config.githubOidc?.environment,
+      ConsumerGatewayStackName: input.config.githubOidc?.consumerGatewayStackName,
       ...coreBootstrapOutputs(core)
     });
     const templatePath = await bootstrapTemplatePath("github-oidc");
@@ -1136,7 +1142,11 @@ async function bootstrapHandoff(input) {
       expectedContracts,
       templatePath,
       parameterPath: "github-oidc-bootstrap.json",
-      expectedOutputs: ["BootstrapContractVersion", "GitHubDeployRoleArn"],
+      expectedOutputs: [
+        "BootstrapContractVersion",
+        "BootstrapTemplateRevision",
+        "GitHubDeployRoleArn"
+      ],
       requiredCapturedFiles: [coreCapturePath],
       reviewCheckpoints: [
         "Review the exact immutable GitHub OIDC subject, audience, bucket lambda/* prefix, application stack, and execution role.",
@@ -1244,9 +1254,14 @@ async function verifyBootstrap(input) {
     GitHubEnvironment: github?.environment,
     ApplicationStackName: coreOutputs.ApplicationStackName,
     ArtifactBucketName: coreOutputs.ArtifactBucketName,
-    CloudFormationExecutionRoleArn: executionRole
+    CloudFormationExecutionRoleArn: executionRole,
+    ConsumerGatewayStackName: github?.consumerGatewayStackName ?? ""
   }))
-    assertEqual(oidcParameters[key], value2, `OIDC ${key}`);
+    assertEqual(
+      key === "ConsumerGatewayStackName" ? oidcParameters[key] ?? "" : oidcParameters[key],
+      value2,
+      `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("/");
@@ -1373,7 +1388,8 @@ async function scaffoldBootstrapManifest(input) {
       repository,
       ownerId,
       repositoryId,
-      environment
+      environment,
+      ...input.consumerGatewayStackName ? { consumerGatewayStackName: input.consumerGatewayStackName } : {}
     }
   };
 }
@@ -1832,6 +1848,29 @@ async function runDoctor(options, dependencies = actualDependencies) {
     if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`);
     return `${url} returned HTTP ${response.status}`;
   });
+  if (options.githubOidcStackPath) {
+    const stackPath = options.githubOidcStackPath;
+    const template = await bootstrapTemplate("github-oidc");
+    const expectedRevision = bootstrapTemplateRevision(template);
+    await check("Bootstrap template", async () => {
+      const raw = JSON.parse(await readFile4(stackPath, "utf8"));
+      const stack = raw && typeof raw === "object" && "Stacks" in raw ? raw.Stacks?.[0] : raw;
+      if (!stack || typeof stack !== "object")
+        throw new Error("captured stack JSON contains no stack");
+      const actualRevision = (stack.Outputs ?? []).find(({ OutputKey }) => OutputKey === "BootstrapTemplateRevision")?.OutputValue;
+      if (actualRevision !== expectedRevision)
+        throw new Error(
+          `captured bootstrap revision is ${actualRevision ?? "older or missing"}; current package is ${expectedRevision}; rerun the GitHub OIDC bootstrap review before deploying`
+        );
+      return `GitHub OIDC bootstrap revision ${expectedRevision} is current`;
+    });
+    const checkResult = checks.at(-1);
+    if (checkResult && !checkResult.ok) {
+      checkResult.ok = true;
+      checkResult.warning = true;
+      checkResult.detail = `WARNING: ${checkResult.detail}`;
+    }
+  }
   return checks;
 }
 
@@ -1907,6 +1946,10 @@ function bootstrapValues(config, coreOutputs = {}) {
     GitHubOwnerId: option("--github-owner-id", config.githubOidc?.ownerId),
     GitHubRepositoryId: option("--github-repository-id", config.githubOidc?.repositoryId),
     GitHubEnvironment: option("--github-environment", config.githubOidc?.environment),
+    ConsumerGatewayStackName: option(
+      "--consumer-gateway-stack",
+      config.githubOidc?.consumerGatewayStackName
+    ),
     CloudFormationExecutionRoleArn: option(
       "--execution-role-arn",
       coreOutputs.CloudFormationExecutionRoleArn
@@ -1968,7 +2011,11 @@ try {
     const parametersPath = option("--parameters", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
     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: region2 },
+      {
+        parametersPath,
+        region: region2,
+        githubOidcStackPath: option("--github-oidc-stack-json")
+      },
       {
         async execute(command, commandArgs) {
           const { execFile: execFile3 } = await import("node:child_process");
@@ -1983,7 +2030,9 @@ try {
       }
     );
     for (const check of checks)
-      console.log(`${check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`);
+      console.log(
+        `${check.warning ? "WARN" : check.ok ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`
+      );
     if (checks.some(({ ok }) => !ok)) process.exitCode = 1;
   } else if (args[0] === "parameters") {
     const output = option("--output", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
@@ -2053,6 +2102,7 @@ try {
         accountId: option("--account-id"),
         ownerId: option("--github-owner-id"),
         repositoryId: option("--github-repository-id"),
+        consumerGatewayStackName: option("--consumer-gateway-stack"),
         runner
       });
       await writeFile3(output, `${JSON.stringify(manifest, null, 2)}
@@ -2171,6 +2221,12 @@ try {
             JSON.parse(await readFile5(deployedStackPath, "utf8")),
             bootstrapContractVersion(await bootstrapTemplate(kind))
           );
+          if (kind === "github-oidc" && !(stack.Parameters ?? []).some(
+            ({ ParameterKey }) => ParameterKey === "ConsumerGatewayStackName"
+          ))
+            console.error(
+              option("--consumer-gateway-stack", config.githubOidc?.consumerGatewayStackName) ? "NOTICE: this GitHub OIDC stack predates optional consumer gateway-stack reads; the generated parameters will add the configured gateway stack. Review and execute the GitHub OIDC UPDATE change set." : "NOTICE: this GitHub OIDC stack predates optional consumer gateway-stack reads. If your workflow verifies a consumer-owned gateway stack, configure githubOidc.consumerGatewayStackName before reviewing the UPDATE change set; otherwise no bootstrap change is needed."
+            );
           parameters = mergeBootstrapParameters(supplied, stack.Parameters ?? []);
         }
         await writeFile3(output, `${JSON.stringify(parameters, null, 2)}

package/dist/doctor.d.ts

@@ -2,6 +2,7 @@ export type DoctorCheck = {
     name: string;
     ok: boolean;
     detail: string;
+    warning?: boolean;
 };
 export type DoctorDependencies = {
     execute(command: string, args: string[]): Promise<string>;
@@ -15,4 +16,5 @@ export type DoctorDependencies = {
 export declare function runDoctor(options: {
     parametersPath: string;
     region: string;
+    githubOidcStackPath?: string;
 }, dependencies?: DoctorDependencies): Promise<DoctorCheck[]>;

package/dist/guided.d.ts

@@ -19,6 +19,7 @@ export type BootstrapInitInput = {
     accountId?: string;
     ownerId?: string;
     repositoryId?: string;
+    consumerGatewayStackName?: string;
     runner?: CommandRunner;
 };
 /** Creates the non-secret manifest data; callers control where (and whether) it is written. */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type BootstrapConfig, type BootstrapKind, bootstrapContractVersion, bootstrapTemplate, bootstrapTemplatePath, type CloudFormationParameterValue, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requiredBootstrapParameters, } from './bootstrap.js';
+export { type BootstrapConfig, type BootstrapKind, bootstrapContractVersion, bootstrapTemplate, bootstrapTemplatePath, bootstrapTemplateRevision, type CloudFormationParameterValue, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requiredBootstrapParameters, } from './bootstrap.js';
 export { type BootstrapCheckStatus, type BootstrapInitInput, type BootstrapPreflight, type BootstrapPreflightCheck, bootstrapGuide, bootstrapPreflight, scaffoldBootstrapManifest, } from './guided.js';
 export { type BootstrapHandoff, type BootstrapPhase, type BootstrapProvider, type BootstrapVerification, bootstrapHandoff, type CommandRunner, githubOidcProvider, verifyBootstrap, } from './handoff.js';
 export type ReleaseMetadata = {

package/dist/index.js

@@ -844,6 +844,11 @@ function bootstrapContractVersion(template) {
   if (!version) throw new Error("Bootstrap template has no BootstrapContractVersion output");
   return version;
 }
+function bootstrapTemplateRevision(template) {
+  const revision = template.match(/BootstrapTemplateRevision:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
+  if (!revision) throw new Error("Bootstrap template has no BootstrapTemplateRevision output");
+  return revision;
+}
 function mergeBootstrapParameters(requested, deployed) {
   const supplied = new Map(requested.map((entry) => [entry.ParameterKey, entry.ParameterValue]));
   const duplicates = requested.map((entry) => entry.ParameterKey);
@@ -897,7 +902,7 @@ function requiredBootstrapParameters(kind, values) {
   ];
   const missing = keys.filter((key) => !values[key]);
   if (missing.length) throw new Error(`Missing required bootstrap values: ${missing.join(", ")}`);
-  const optional2 = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : [];
+  const optional2 = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : ["ConsumerGatewayStackName"];
   return [...keys, ...optional2].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
 }
 
@@ -1115,6 +1120,7 @@ async function bootstrapHandoff(input) {
       GitHubOwnerId: input.config.githubOidc?.ownerId,
       GitHubRepositoryId: input.config.githubOidc?.repositoryId,
       GitHubEnvironment: input.config.githubOidc?.environment,
+      ConsumerGatewayStackName: input.config.githubOidc?.consumerGatewayStackName,
       ...coreBootstrapOutputs(core)
     });
     const templatePath = await bootstrapTemplatePath("github-oidc");
@@ -1123,7 +1129,11 @@ async function bootstrapHandoff(input) {
       expectedContracts,
       templatePath,
       parameterPath: "github-oidc-bootstrap.json",
-      expectedOutputs: ["BootstrapContractVersion", "GitHubDeployRoleArn"],
+      expectedOutputs: [
+        "BootstrapContractVersion",
+        "BootstrapTemplateRevision",
+        "GitHubDeployRoleArn"
+      ],
       requiredCapturedFiles: [coreCapturePath],
       reviewCheckpoints: [
         "Review the exact immutable GitHub OIDC subject, audience, bucket lambda/* prefix, application stack, and execution role.",
@@ -1231,9 +1241,14 @@ async function verifyBootstrap(input) {
     GitHubEnvironment: github?.environment,
     ApplicationStackName: coreOutputs.ApplicationStackName,
     ArtifactBucketName: coreOutputs.ArtifactBucketName,
-    CloudFormationExecutionRoleArn: executionRole
+    CloudFormationExecutionRoleArn: executionRole,
+    ConsumerGatewayStackName: github?.consumerGatewayStackName ?? ""
   }))
-    assertEqual(oidcParameters[key], value2, `OIDC ${key}`);
+    assertEqual(
+      key === "ConsumerGatewayStackName" ? oidcParameters[key] ?? "" : oidcParameters[key],
+      value2,
+      `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("/");
@@ -1360,7 +1375,8 @@ async function scaffoldBootstrapManifest(input) {
       repository,
       ownerId,
       repositoryId,
-      environment
+      environment,
+      ...input.consumerGatewayStackName ? { consumerGatewayStackName: input.consumerGatewayStackName } : {}
     }
   };
 }
@@ -1694,6 +1710,7 @@ export {
   bootstrapPreflight,
   bootstrapTemplate,
   bootstrapTemplatePath,
+  bootstrapTemplateRevision,
   cloudFormationTemplate,
   coreBootstrapOutputs,
   deployLambda,

package/package.json

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