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

package/README.md

@@ -74,10 +74,16 @@ 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.
+After assuming the generated GitHub deploy role, run the canonical blocking consistency check before
+packaging or deployment:
+
+```sh
+npm exec -- ze-great-dashboard-aws bootstrap check \
+  --config dashboard-bootstrap.json --format text
+```
+
+Add `--resource-drift` only for a slower scheduled or manually dispatched CloudFormation drift
+audit. Neither form updates stack resources.
 
 Package the release. This validates the board and writes `lambda.zip`, `release.json`, and
 `template.yml` to the output directory:
@@ -127,7 +133,7 @@ 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).
+After upgrading, also check the [bootstrap consistency guidance](https://github.com/robertfmurdock/ze-great-dashboard/blob/main/docs/aws-bootstrap.md#check-bootstrap-consistency-on-every-deployment).
 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
@@ -144,7 +150,7 @@ for the supported secret reference and integration boundary.
 | `doctor` | Read-only preflight for an existing parameter file. |
 | `parameters` | Generate or update application CloudFormation parameters. |
 | `package` | Validate board YAML and build a deployable Lambda release. |
-| `bootstrap` | Produce bootstrap templates, parameters, preflight, and guidance; administrators run AWS commands explicitly. |
+| `bootstrap` | Plan and guide administrator bootstrap work; `bootstrap check` is the explicit live diagnostic used by CI. |
 | `publish-assets` | Provider-only: publish immutable client assets. Normal consumers use the hosted client. |
 | `deploy` | Provider-only: automation helper for a provider-managed asset and Lambda deployment. |
 

package/bootstrap/core-v1.yml

@@ -105,6 +105,7 @@ Resources:
 
 Outputs:
   BootstrapContractVersion: { Value: '1' }
+  BootstrapTemplateRevision: { Value: '1.1' }
   ArtifactBucketName: { Value: !Ref ArtifactBucket }
   ArtifactBucketArn: { Value: !GetAtt ArtifactBucket.Arn }
   CloudFormationExecutionRoleArn: { Value: !GetAtt CloudFormationExecutionRole.Arn }

package/bootstrap/github-oidc-v2.yml

@@ -7,6 +7,7 @@ Parameters:
   GitHubOwnerId: { Type: String, Description: Immutable numeric GitHub owner id }
   GitHubRepositoryId: { Type: String, Description: Immutable numeric GitHub repository id }
   GitHubEnvironment: { Type: String, Description: Protected GitHub Environment name }
+  CoreBootstrapStackName: { Type: String }
   ApplicationStackName: { Type: String }
   ConsumerGatewayStackName:
     Type: String
@@ -56,6 +57,31 @@ 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}/*'
+              - Sid: InspectBootstrapStacks
+                Effect: Allow
+                Action: [cloudformation:DescribeStacks, cloudformation:DetectStackDrift, cloudformation:DescribeStackResourceDrifts]
+                Resource:
+                  - !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${CoreBootstrapStackName}/*'
+                  - !Sub 'arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:stack/${AWS::StackName}/*'
+              # Detection-status requests are keyed by an opaque detection id, so AWS does not
+              # support scoping this one read action to a stack ARN.
+              - Sid: ReadBootstrapDriftDetectionStatus
+                Effect: Allow
+                Action: cloudformation:DescribeStackDriftDetectionStatus
+                Resource: '*'
+              # CloudFormation uses the caller's read permissions when these administrator-created
+              # stacks have no service role. Keep resource inspection on the exact bootstrap bucket
+              # and roles whose properties drift detection evaluates.
+              - Sid: InspectBootstrapBucketConfiguration
+                Effect: Allow
+                Action: [s3:GetBucketAcl, s3:GetBucketPolicy, s3:GetBucketPublicAccessBlock, s3:GetEncryptionConfiguration, s3:GetBucketOwnershipControls, s3:GetBucketTagging]
+                Resource: !Sub 'arn:${AWS::Partition}:s3:::${ArtifactBucketName}'
+              - Sid: InspectBootstrapRoleConfiguration
+                Effect: Allow
+                Action: [iam:GetRole, iam:GetRolePolicy, iam:ListRolePolicies, iam:ListAttachedRolePolicies, iam:ListRoleTags]
+                Resource:
+                  - !Ref CloudFormationExecutionRoleArn
+                  - !Sub 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/${ApplicationStackName}-github-deploy'
               - !If
                 - HasConsumerGatewayStack
                 - Sid: ReadConsumerGatewayStack
@@ -71,5 +97,5 @@ Resources:
 
 Outputs:
   BootstrapContractVersion: { Value: '2' }
-  BootstrapTemplateRevision: { Value: '2.1' }
+  BootstrapTemplateRevision: { Value: '2.2' }
   GitHubDeployRoleArn: { Value: !GetAtt GitHubDeployRole.Arn }

package/dist/bootstrap-check.d.ts

@@ -0,0 +1,45 @@
+import { type BootstrapConfig, type BootstrapConsistency, type BootstrapKind } from './bootstrap.js';
+export type BootstrapResourceDifference = {
+    path?: string;
+    differenceType?: string;
+    expectedValue?: string;
+    actualValue?: string;
+};
+export type BootstrapResourceDrift = {
+    logicalId: string;
+    resourceType?: string;
+    status?: string;
+    differences: BootstrapResourceDifference[];
+};
+export type BootstrapResourceDriftResult = {
+    ok: boolean;
+    status: string;
+    detectionId?: string;
+    reason?: string;
+    resources: BootstrapResourceDrift[];
+};
+export type BootstrapStackCheck = {
+    kind: BootstrapKind;
+    stackName: string;
+    stackStatus?: string;
+    contractVersion: string;
+    templateRevision?: string;
+    templateSha256: string;
+    consistency: BootstrapConsistency;
+    resourceDrift?: BootstrapResourceDriftResult;
+};
+export type BootstrapCheck = {
+    ok: boolean;
+    packageVersion: string;
+    stacks: BootstrapStackCheck[];
+};
+export type BootstrapCheckDependencies = {
+    execute(command: string, args: string[]): Promise<string>;
+    sleep?(milliseconds: number): Promise<void>;
+    now?(): number;
+};
+export declare function formatBootstrapCheckText(result: BootstrapCheck): string;
+/** Runs the explicitly named live bootstrap diagnostic; it never changes stack resources. */
+export declare function checkBootstrap(config: BootstrapConfig, options: {
+    resourceDrift?: boolean;
+}, dependencies: BootstrapCheckDependencies): Promise<BootstrapCheck>;

package/dist/bootstrap.d.ts

@@ -5,6 +5,9 @@ export type CloudFormationParameterValue = {
     UsePreviousValue?: boolean;
 };
 export type DeployedBootstrapStack = {
+    StackName?: string;
+    StackId?: string;
+    StackStatus?: string;
     Parameters?: CloudFormationParameterValue[];
     Outputs?: {
         OutputKey: string;
@@ -31,10 +34,36 @@ export type BootstrapConfig = {
         consumerGatewayStackName?: string;
     };
 };
+export type BootstrapTemplateInspection = {
+    kind: BootstrapKind;
+    path: string;
+    contractVersion: string;
+    templateRevision?: string;
+    sha256: string;
+    resources: {
+        logicalId: string;
+        type: string;
+    }[];
+    iamActions: string[];
+};
+export type BootstrapPlan = {
+    packageVersion: string;
+    packageTemplates: BootstrapTemplateInspection[];
+    configuration: BootstrapConfig;
+    notes: string[];
+};
+export type BootstrapConsistency = {
+    ok: boolean;
+    mismatches: 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;
+/** Returns installed templates and a reviewable, non-secret plan without external calls. */
+export declare function bootstrapPlan(config: BootstrapConfig): Promise<BootstrapPlan>;
+/** Compares describe-stacks data with manifest and installed-template values without network access. */
+export declare function bootstrapConsistency(kind: BootstrapKind, config: BootstrapConfig, stackInput: unknown, expectedContract: string, expectedRevision?: string, coreOutputs?: Record<string, string | undefined>): BootstrapConsistency;
 /** 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. */