@continuous-excellence/ze-great-dashboard-aws 0.1.26 → 0.1.28

package/bootstrap/core-v1.yml

@@ -0,0 +1,111 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Description: Ze Great Dashboard bootstrap core v1. Administrator-managed; do not grant this authority to CI.
+
+Parameters:
+  ArtifactBucketName:
+    Type: String
+    Description: Globally unique bucket for private Lambda artifacts
+  ApplicationStackName:
+    Type: String
+    Description: Stable name of the one dashboard application stack
+  DashboardFunctionName:
+    Type: String
+    Description: Stable Lambda function name used by the application stack
+  RuntimeSecretArn:
+    Type: String
+    Default: ''
+    Description: Optional explicitly configured Secrets Manager secret ARN
+  ArtifactKmsKeyArn:
+    Type: String
+    Default: ''
+    Description: Optional customer-managed KMS key ARN; SSE-S3 is used when blank
+
+Conditions:
+  HasRuntimeSecret: !Not [!Equals [!Ref RuntimeSecretArn, '']]
+  HasArtifactKmsKey: !Not [!Equals [!Ref ArtifactKmsKeyArn, '']]
+
+Resources:
+  ArtifactBucket:
+    Type: AWS::S3::Bucket
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      BucketName: !Ref ArtifactBucketName
+      BucketEncryption:
+        ServerSideEncryptionConfiguration:
+          - ServerSideEncryptionByDefault:
+              SSEAlgorithm: !If [HasArtifactKmsKey, aws:kms, AES256]
+              KMSMasterKeyID: !If [HasArtifactKmsKey, !Ref ArtifactKmsKeyArn, !Ref AWS::NoValue]
+            BucketKeyEnabled: !If [HasArtifactKmsKey, true, !Ref AWS::NoValue]
+      OwnershipControls:
+        Rules: [{ ObjectOwnership: BucketOwnerEnforced }]
+      PublicAccessBlockConfiguration:
+        BlockPublicAcls: true
+        BlockPublicPolicy: true
+        IgnorePublicAcls: true
+        RestrictPublicBuckets: true
+
+  ArtifactBucketPolicy:
+    Type: AWS::S3::BucketPolicy
+    Properties:
+      Bucket: !Ref ArtifactBucket
+      PolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+          - Sid: DenyInsecureTransport
+            Effect: Deny
+            Principal: '*'
+            Action: s3:*
+            Resource: [!GetAtt ArtifactBucket.Arn, !Sub '${ArtifactBucket.Arn}/*']
+            Condition: { Bool: { 'aws:SecureTransport': false } }
+
+  CloudFormationExecutionRole:
+    Type: AWS::IAM::Role
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      RoleName: !Sub '${ApplicationStackName}-execution'
+      Description: !Sub 'Restricted CloudFormation execution role for ${ApplicationStackName}'
+      AssumeRolePolicyDocument:
+        Version: '2012-10-17'
+        Statement: [{ Effect: Allow, Principal: { Service: cloudformation.amazonaws.com }, Action: sts:AssumeRole }]
+      Policies:
+        - PolicyName: DashboardApplicationResources
+          PolicyDocument:
+            Version: '2012-10-17'
+            Statement:
+              - Sid: DashboardLambda
+                Effect: Allow
+                Action: [lambda:CreateFunction, lambda:GetFunction, lambda:UpdateFunctionCode, lambda:UpdateFunctionConfiguration, lambda:DeleteFunction, lambda:TagResource, lambda:UntagResource]
+                Resource: !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${DashboardFunctionName}'
+              - Sid: DashboardLogs
+                Effect: Allow
+                Action: [logs:CreateLogGroup, logs:DeleteLogGroup, logs:DescribeLogGroups, logs:PutRetentionPolicy, logs:TagResource, logs:UntagResource]
+                Resource: !Sub 'arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/${DashboardFunctionName}:*'
+              - Sid: ReadLambdaArtifact
+                Effect: Allow
+                Action: s3:GetObject
+                Resource: !Sub '${ArtifactBucket.Arn}/lambda/*'
+              - Sid: ManageRuntimeRole
+                Effect: Allow
+                Action: [iam:CreateRole, iam:GetRole, iam:DeleteRole, iam:UpdateAssumeRolePolicy, iam:PutRolePolicy, iam:GetRolePolicy, iam:DeleteRolePolicy, iam:AttachRolePolicy, iam:DetachRolePolicy, iam:ListRolePolicies, iam:ListAttachedRolePolicies, iam:TagRole, iam:UntagRole]
+                Resource: !Sub 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/${DashboardFunctionName}-server'
+              - Sid: PassRuntimeRoleToLambdaOnly
+                Effect: Allow
+                Action: iam:PassRole
+                Resource: !Sub 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/${DashboardFunctionName}-server'
+                Condition: { StringEquals: { 'iam:PassedToService': lambda.amazonaws.com } }
+              - !If
+                - HasRuntimeSecret
+                - Sid: ReadConfiguredRuntimeSecret
+                  Effect: Allow
+                  Action: [secretsmanager:DescribeSecret, secretsmanager:GetSecretValue]
+                  Resource: !Ref RuntimeSecretArn
+                - !Ref AWS::NoValue
+
+Outputs:
+  BootstrapContractVersion: { Value: '1' }
+  ArtifactBucketName: { Value: !Ref ArtifactBucket }
+  ArtifactBucketArn: { Value: !GetAtt ArtifactBucket.Arn }
+  CloudFormationExecutionRoleArn: { Value: !GetAtt CloudFormationExecutionRole.Arn }
+  ApplicationStackName: { Value: !Ref ApplicationStackName }

package/bootstrap/dashboard-bootstrap.example.json

@@ -0,0 +1,15 @@
+{
+  "region": "us-east-1",
+  "core": {
+    "stackName": "team-dashboard-bootstrap",
+    "artifactBucketName": "team-dashboard-lambda-artifacts-123456789012",
+    "applicationStackName": "team-dashboard",
+    "dashboardFunctionName": "team-dashboard"
+  },
+  "githubOidc": {
+    "stackName": "team-dashboard-github-bootstrap",
+    "providerArn": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com",
+    "repository": "example/team-dashboard",
+    "environment": "production"
+  }
+}

package/bootstrap/github-oidc-v1.yml

@@ -0,0 +1,55 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Description: Ze Great Dashboard GitHub OIDC adapter v1. Administrator-managed; requires a central OIDC provider.
+
+Parameters:
+  GitHubOidcProviderArn: { Type: String }
+  GitHubRepository: { Type: String, Description: owner/repository }
+  GitHubEnvironment: { Type: String, Description: Protected GitHub Environment name }
+  ApplicationStackName: { Type: String }
+  ArtifactBucketName: { Type: String }
+  CloudFormationExecutionRoleArn: { Type: String }
+
+Resources:
+  GitHubDeployRole:
+    Type: AWS::IAM::Role
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      RoleName: !Sub '${ApplicationStackName}-github-deploy'
+      MaxSessionDuration: 3600
+      AssumeRolePolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+          - Effect: Allow
+            Principal: { Federated: !Ref GitHubOidcProviderArn }
+            Action: sts:AssumeRoleWithWebIdentity
+            Condition:
+              StringEquals:
+                'token.actions.githubusercontent.com:aud': sts.amazonaws.com
+                'token.actions.githubusercontent.com:sub': !Sub 'repo:${GitHubRepository}:environment:${GitHubEnvironment}'
+      Policies:
+        - PolicyName: DeployOneDashboard
+          PolicyDocument:
+            Version: '2012-10-17'
+            Statement:
+              - Sid: UploadLambdaArtifacts
+                Effect: Allow
+                Action: [s3:PutObject, s3:GetObject]
+                Resource: !Sub 'arn:${AWS::Partition}:s3:::${ArtifactBucketName}/lambda/*'
+              - Sid: InspectArtifactBucket
+                Effect: Allow
+                Action: [s3:GetBucketLocation, s3:ListBucket]
+                Resource: !Sub 'arn:${AWS::Partition}:s3:::${ArtifactBucketName}'
+              - Sid: OperateOneApplicationStack
+                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: PassCoreExecutionRole
+                Effect: Allow
+                Action: iam:PassRole
+                Resource: !Ref CloudFormationExecutionRoleArn
+                Condition: { StringEquals: { 'iam:PassedToService': cloudformation.amazonaws.com } }
+
+Outputs:
+  BootstrapContractVersion: { Value: '1' }
+  GitHubDeployRoleArn: { Value: !GetAtt GitHubDeployRole.Arn }

package/dist/bootstrap.d.ts

@@ -0,0 +1,40 @@
+export type BootstrapKind = 'core' | 'github-oidc';
+export type CloudFormationParameterValue = {
+    ParameterKey: string;
+    ParameterValue: string;
+    UsePreviousValue?: boolean;
+};
+export type DeployedBootstrapStack = {
+    Parameters?: CloudFormationParameterValue[];
+    Outputs?: {
+        OutputKey: string;
+        OutputValue?: string;
+    }[];
+};
+export type BootstrapConfig = {
+    region?: string;
+    core?: {
+        stackName?: string;
+        artifactBucketName?: string;
+        applicationStackName?: string;
+        dashboardFunctionName?: string;
+        runtimeSecretArn?: string;
+        artifactKmsKeyArn?: string;
+    };
+    githubOidc?: {
+        stackName?: string;
+        providerArn?: string;
+        repository?: string;
+        environment?: string;
+    };
+};
+export declare function bootstrapTemplatePath(kind: BootstrapKind): Promise<string>;
+export declare function bootstrapTemplate(kind: BootstrapKind): Promise<string>;
+export declare function bootstrapContractVersion(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. */
+export declare function deployedBootstrapStack(input: unknown, expectedContractVersion: string): DeployedBootstrapStack;
+/** Extracts the adapter contract from a caller-captured core `describe-stacks` result. */
+export declare function coreBootstrapOutputs(stack: DeployedBootstrapStack): Record<string, string>;
+export declare function requiredBootstrapParameters(kind: BootstrapKind, values: Record<string, string | undefined>): CloudFormationParameterValue[];

package/dist/cli.js

@@ -1,21 +1,21 @@
 #!/usr/bin/env node
 
 // packages/aws/src/cli.ts
-import { readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { readFile as readFile5, writeFile as writeFile3 } from "node:fs/promises";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { parse as parse3 } from "yaml";
 
 // packages/aws/src/doctor.ts
 import { execFile as execFile2 } from "node:child_process";
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile4 } from "node:fs/promises";
 import { promisify as promisify2 } from "node:util";
 import { parse as parse2 } from "yaml";
 
 // packages/aws/src/index.ts
 import { execFile } from "node:child_process";
-import { cp, mkdir as mkdir2, readFile as readFile2, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { cp, mkdir as mkdir2, readFile as readFile3, rm, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify } from "node:util";
 
 // node_modules/fflate/esm/index.mjs
@@ -838,6 +838,80 @@ function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+// packages/aws/src/bootstrap.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+var templates = {
+  core: "../bootstrap/core-v1.yml",
+  "github-oidc": "../bootstrap/github-oidc-v1.yml"
+};
+async function bootstrapTemplatePath(kind) {
+  if (!Object.hasOwn(templates, kind)) throw new Error(`Unknown bootstrap template: ${kind}`);
+  return fileURLToPath(new URL(templates[kind], import.meta.url));
+}
+async function bootstrapTemplate(kind) {
+  return readFile2(await bootstrapTemplatePath(kind), "utf8");
+}
+function bootstrapContractVersion(template) {
+  const version = template.match(/BootstrapContractVersion:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
+  if (!version) throw new Error("Bootstrap template has no BootstrapContractVersion output");
+  return version;
+}
+function mergeBootstrapParameters(requested, deployed) {
+  const supplied = new Map(requested.map((entry) => [entry.ParameterKey, entry.ParameterValue]));
+  const duplicates = requested.map((entry) => entry.ParameterKey);
+  if (new Set(duplicates).size !== duplicates.length)
+    throw new Error("Bootstrap parameter file contains duplicate parameters");
+  return deployed.map(({ ParameterKey, ParameterValue }) => ({
+    ParameterKey,
+    ParameterValue: supplied.get(ParameterKey) ?? ParameterValue
+  })).concat(
+    requested.filter(
+      ({ ParameterKey }) => !deployed.some((entry) => entry.ParameterKey === ParameterKey)
+    )
+  );
+}
+function deployedBootstrapStack(input, expectedContractVersion) {
+  const stack = input && typeof input === "object" && "Stacks" in input ? input.Stacks?.[0] : input;
+  if (!stack || typeof stack !== "object") throw new Error("Deployed stack JSON contains no stack");
+  const deployed = stack;
+  const contract = deployed.Outputs?.find(
+    (output) => output.OutputKey === "BootstrapContractVersion"
+  )?.OutputValue;
+  if (contract !== expectedContractVersion)
+    throw new Error(
+      `Bootstrap contract mismatch (deployed: ${contract ?? "missing"}; expected: ${expectedContractVersion}); follow the documented migration procedure`
+    );
+  if (deployed.Parameters && !Array.isArray(deployed.Parameters))
+    throw new Error("Deployed stack JSON has invalid Parameters");
+  return deployed;
+}
+function coreBootstrapOutputs(stack) {
+  const values = Object.fromEntries(
+    (stack.Outputs ?? []).filter(
+      (output) => Boolean(output.OutputValue)
+    ).map((output) => [output.OutputKey, output.OutputValue])
+  );
+  const required = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
+  const missing = required.filter((key) => !values[key]);
+  if (missing.length) throw new Error(`Core stack JSON is missing outputs: ${missing.join(", ")}`);
+  return values;
+}
+function requiredBootstrapParameters(kind, values) {
+  const keys = kind === "core" ? ["ArtifactBucketName", "ApplicationStackName", "DashboardFunctionName"] : [
+    "GitHubOidcProviderArn",
+    "GitHubRepository",
+    "GitHubEnvironment",
+    "ApplicationStackName",
+    "ArtifactBucketName",
+    "CloudFormationExecutionRoleArn"
+  ];
+  const missing = keys.filter((key) => !values[key]);
+  if (missing.length) throw new Error(`Missing required bootstrap values: ${missing.join(", ")}`);
+  const optional = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : [];
+  return [...keys, ...optional].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
+}
+
 // packages/aws/src/index.ts
 var run = promisify(execFile);
 function deploymentTemplate(template, values) {
@@ -867,7 +941,7 @@ async function packageLambda(options) {
   await mkdir2(outputDir, { recursive: true });
   const runtimeDir = join2(outputDir, "lambda");
   await mkdir2(runtimeDir, { recursive: true });
-  const lambdaSource = fileURLToPath(new URL("../dist/lambda.mjs", import.meta.url));
+  const lambdaSource = fileURLToPath2(new URL("../dist/lambda.mjs", import.meta.url));
   await cp(lambdaSource, join2(runtimeDir, "index.mjs"));
   const release = await assembleRelease({
     boardConfigPath: options.boardConfigPath,
@@ -880,7 +954,7 @@ async function packageLambda(options) {
     ...release.metadata,
     artifactChecksums: {
       ...release.metadata.artifactChecksums,
-      "index.mjs": sha256(await readFile2(join2(runtimeDir, "index.mjs")))
+      "index.mjs": sha256(await readFile3(join2(runtimeDir, "index.mjs")))
     }
   };
   await writeFile2(join2(runtimeDir, "release.json"), `${JSON.stringify(runtimeMetadata, null, 2)}
@@ -895,7 +969,7 @@ async function packageLambda(options) {
       archiveFiles.map(async (name) => [
         name,
         [
-          strToU8(await readFile2(join2(runtimeDir, name), "utf8")),
+          strToU8(await readFile3(join2(runtimeDir, name), "utf8")),
           { mtime: new Date(1980, 0, 1, 0, 0, 0), level: 9 }
         ]
       ])
@@ -903,7 +977,7 @@ async function packageLambda(options) {
   );
   await writeFile2(lambdaPath, zipSync(archive));
   await rm(runtimeDir, { recursive: true, force: true });
-  const lambdaChecksum = sha256(await readFile2(lambdaPath));
+  const lambdaChecksum = sha256(await readFile3(lambdaPath));
   const deploymentChecksum = sha256(JSON.stringify(runtimeMetadata));
   const packagedRelease = {
     ...runtimeMetadata,
@@ -923,7 +997,7 @@ async function packageLambda(options) {
 }
 async function publishClientAssets(options) {
   const assetsDir = resolve2(options.assetsDir);
-  await readFile2(join2(assetsDir, "index.html"));
+  await readFile3(join2(assetsDir, "index.html"));
   const assetPath = `${options.assetsBaseUrl.replace(/\/+$/, "")}/dashboard/${options.version}`;
   await run("aws", [
     "s3",
@@ -948,8 +1022,8 @@ async function publishClientAssets(options) {
 async function deployLambda(options) {
   const artifactDir = resolve2(options.artifactDir);
   const assetsDir = resolve2(options.assetsDir);
-  await readFile2(join2(artifactDir, "lambda.zip"));
-  await readFile2(join2(assetsDir, "index.html"));
+  await readFile3(join2(artifactDir, "lambda.zip"));
+  await readFile3(join2(assetsDir, "index.html"));
   if (options.dryRun) return;
   const assetPath = await publishClientAssets(options);
   await run("aws", [
@@ -974,7 +1048,7 @@ async function deployLambda(options) {
   await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
 }
 async function cloudFormationTemplate() {
-  return readFile2(fileURLToPath(new URL("../template.yml", import.meta.url)), "utf8");
+  return readFile3(fileURLToPath2(new URL("../template.yml", import.meta.url)), "utf8");
 }
 
 // packages/aws/src/doctor.ts
@@ -1073,7 +1147,7 @@ async function runDoctor(options, dependencies = actualDependencies) {
   let parameterData;
   await check("Parameters/template", async () => {
     const parameters = readParameterValues(
-      JSON.parse(await readFile3(options.parametersPath, "utf8"))
+      JSON.parse(await readFile4(options.parametersPath, "utf8"))
     );
     parameterData = await templateContract(parameters);
     return `${options.parametersPath} is compatible`;
@@ -1119,7 +1193,7 @@ var option = (name, fallback) => {
 };
 async function installedPackageVersion() {
   const packageManifest = JSON.parse(
-    await readFile4(new URL("../package.json", import.meta.url), "utf8")
+    await readFile5(new URL("../package.json", import.meta.url), "utf8")
   );
   return typeof packageManifest.version === "string" ? packageManifest.version : "";
 }
@@ -1133,7 +1207,7 @@ function parameter(key, value) {
 }
 async function existingParameters(path) {
   try {
-    const parsed = JSON.parse(await readFile4(path, "utf8"));
+    const parsed = JSON.parse(await readFile5(path, "utf8"));
     if (!Array.isArray(parsed)) throw new Error(`${path} must contain a JSON parameter array`);
     const values = parsed.map((value) => {
       if (!value || typeof value !== "object" || typeof value.ParameterKey !== "string" || typeof value.ParameterValue !== "string")
@@ -1150,6 +1224,49 @@ async function existingParameters(path) {
     throw error;
   }
 }
+function bootstrapKind() {
+  const kind = option("--kind");
+  if (kind === "core" || kind === "github-oidc") return kind;
+  throw new Error("--kind must be core or github-oidc");
+}
+async function readBootstrapConfig(path) {
+  const parsed = JSON.parse(await readFile5(path, "utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("--config must contain a JSON object");
+  return parsed;
+}
+async function bootstrapConfig() {
+  const path = option("--config");
+  return path ? readBootstrapConfig(path) : {};
+}
+function bootstrapValues(config, coreOutputs = {}) {
+  return {
+    ArtifactBucketName: option(
+      "--artifact-bucket",
+      coreOutputs.ArtifactBucketName ?? config.core?.artifactBucketName
+    ),
+    ApplicationStackName: option(
+      "--application-stack",
+      coreOutputs.ApplicationStackName ?? config.core?.applicationStackName
+    ),
+    DashboardFunctionName: option("--function-name", config.core?.dashboardFunctionName),
+    RuntimeSecretArn: option("--runtime-secret-arn", config.core?.runtimeSecretArn),
+    ArtifactKmsKeyArn: option("--artifact-kms-key-arn", config.core?.artifactKmsKeyArn),
+    GitHubOidcProviderArn: option("--github-oidc-provider-arn", config.githubOidc?.providerArn),
+    GitHubRepository: option("--github-repository", config.githubOidc?.repository),
+    GitHubEnvironment: option("--github-environment", config.githubOidc?.environment),
+    CloudFormationExecutionRoleArn: option(
+      "--execution-role-arn",
+      coreOutputs.CloudFormationExecutionRoleArn
+    )
+  };
+}
+function bootstrapStackName(kind, config) {
+  return kind === "core" ? config.core?.stackName : config.githubOidc?.stackName;
+}
+function shellCommand(command) {
+  return command.map((argument) => `'${argument.replaceAll("'", `'\\"'\\"'`)}'`).join(" ");
+}
 async function templateParameters() {
   const template = await cloudFormationTemplate();
   const block = template.match(/^Parameters:\n[\s\S]*?(?=^[A-Za-z][A-Za-z0-9]*:\s*$)/m)?.[0];
@@ -1172,7 +1289,7 @@ async function templateParameters() {
 }
 try {
   const packageVersion = await installedPackageVersion();
-  const bundledAssets = fileURLToPath2(new URL("../client", import.meta.url));
+  const bundledAssets = fileURLToPath3(new URL("../client", import.meta.url));
   if (args[0] === "deploy") {
     const artifactDir = requiredOption("--artifact-dir");
     const version = requiredOption("--version", packageVersion);
@@ -1219,10 +1336,15 @@ try {
   } else if (args[0] === "parameters") {
     const output = option("--output", "aws-dashboard-parameters.json") ?? "aws-dashboard-parameters.json";
     const existing = await existingParameters(output);
+    const consumerConfigPath = option("--bootstrap-config");
+    const consumerConfig = consumerConfigPath ? await readBootstrapConfig(consumerConfigPath) : void 0;
     const existingValues = Object.fromEntries(
       existing.map(({ ParameterKey, ParameterValue }) => [ParameterKey, ParameterValue])
     );
-    const artifactBucket = option("--artifact-bucket", existingValues.LambdaArtifactBucket);
+    const artifactBucket = option(
+      "--artifact-bucket",
+      existingValues.LambdaArtifactBucket ?? consumerConfig?.core?.artifactBucketName
+    );
     if (!artifactBucket) throw new Error("--artifact-bucket is required");
     const { definitions, packageManaged } = await templateParameters();
     const templateKeys = Object.keys(definitions);
@@ -1240,20 +1362,118 @@ try {
       );
     }
     const includeDefaults = args.includes("--include-defaults");
+    const functionName = option("--function-name", consumerConfig?.core?.dashboardFunctionName);
     const parameters = templateKeys.filter(
-      (key) => !packageManaged.has(key) && (includeDefaults || !hasDefault(key) || Object.hasOwn(existingValues, key))
+      (key) => !packageManaged.has(key) && (includeDefaults || !hasDefault(key) || Object.hasOwn(existingValues, key) || key === "Name" && Boolean(functionName))
     ).map((key) => {
       const definition = definitions[key];
-      const value = key === "LambdaArtifactBucket" ? artifactBucket : existingValues[key] ?? definition?.Default;
+      const value = key === "LambdaArtifactBucket" ? artifactBucket : key === "Name" && functionName ? functionName : existingValues[key] ?? definition?.Default;
       if (value === void 0) throw new Error(`No value for CloudFormation parameter ${key}`);
       return parameter(key, String(value));
     });
     await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
 `);
     console.log(JSON.stringify({ output }));
+  } else if (args[0] === "bootstrap") {
+    const action = args[1];
+    const kind = bootstrapKind();
+    const config = await bootstrapConfig();
+    if (action === "template") {
+      console.log(
+        JSON.stringify({
+          kind,
+          template: await bootstrapTemplatePath(kind),
+          contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind))
+        })
+      );
+    } else if (action === "parameters") {
+      const output = option("--output", `aws-dashboard-bootstrap-${kind}.json`) ?? `aws-dashboard-bootstrap-${kind}.json`;
+      let coreOutputs = {};
+      const coreStackPath = option("--core-stack-json");
+      if (kind === "github-oidc" && coreStackPath) {
+        coreOutputs = coreBootstrapOutputs(
+          deployedBootstrapStack(
+            JSON.parse(await readFile5(coreStackPath, "utf8")),
+            bootstrapContractVersion(await bootstrapTemplate("core"))
+          )
+        );
+      }
+      const supplied = requiredBootstrapParameters(kind, bootstrapValues(config, coreOutputs));
+      let parameters = supplied;
+      const deployedStackPath = option("--deployed-stack-json");
+      if (deployedStackPath) {
+        const stack = deployedBootstrapStack(
+          JSON.parse(await readFile5(deployedStackPath, "utf8")),
+          bootstrapContractVersion(await bootstrapTemplate(kind))
+        );
+        parameters = mergeBootstrapParameters(supplied, stack.Parameters ?? []);
+      }
+      await writeFile3(output, `${JSON.stringify(parameters, null, 2)}
+`);
+      console.log(
+        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 awsCommand = [
+        "aws",
+        "cloudformation",
+        "describe-stacks",
+        "--stack-name",
+        stackName,
+        ...region ? ["--region", region] : [],
+        "--no-cli-pager"
+      ];
+      console.log(
+        JSON.stringify({
+          kind,
+          contractVersion: bootstrapContractVersion(await bootstrapTemplate(kind)),
+          awsCommand,
+          shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
+        })
+      );
+    } else if (action === "change-set") {
+      const stackName = requiredOption("--stack-name", bootstrapStackName(kind, config));
+      const changeSetName = requiredOption("--change-set-name");
+      const parametersPath = requiredOption("--parameters");
+      const region = option("--region", config.region);
+      await existingParameters(parametersPath);
+      const awsCommand = [
+        "aws",
+        "cloudformation",
+        "create-change-set",
+        "--stack-name",
+        stackName,
+        "--change-set-name",
+        changeSetName,
+        "--change-set-type",
+        option("--change-set-type", "UPDATE") ?? "UPDATE",
+        "--template-body",
+        `file://${await bootstrapTemplatePath(kind)}`,
+        "--parameters",
+        `file://${parametersPath}`,
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        ...region ? ["--region", region] : [],
+        "--no-cli-pager"
+      ];
+      console.log(
+        JSON.stringify({
+          kind,
+          reviewRequired: true,
+          awsCommand,
+          shellCommand: args.includes("--format-shell") ? shellCommand(awsCommand) : void 0
+        })
+      );
+    } else {
+      throw new Error(
+        "Usage: ze-great-dashboard-aws bootstrap template|parameters|status|change-set --kind core|github-oidc [options]"
+      );
+    }
   } else if (args[0] !== "package")
     throw new Error(
-      "Usage: ze-great-dashboard-aws package|parameters|publish-assets|deploy|doctor [options]"
+      "Usage: ze-great-dashboard-aws package|parameters|bootstrap|publish-assets|deploy|doctor [options]"
     );
   else {
     const boardConfig = option("--board-config");

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { type BootstrapConfig, type BootstrapKind, bootstrapContractVersion, bootstrapTemplate, bootstrapTemplatePath, type CloudFormationParameterValue, coreBootstrapOutputs, type DeployedBootstrapStack, deployedBootstrapStack, mergeBootstrapParameters, requiredBootstrapParameters, } from './bootstrap.js';
 export type ReleaseMetadata = {
     dashboardVersion: string;
     clientAssetUrl: string;

package/dist/index.js

@@ -1,8 +1,8 @@
 // packages/aws/src/index.ts
 import { execFile } from "node:child_process";
-import { cp, mkdir as mkdir2, readFile as readFile2, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { cp, mkdir as mkdir2, readFile as readFile3, rm, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2, resolve as resolve2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify } from "node:util";
 
 // node_modules/fflate/esm/index.mjs
@@ -825,6 +825,80 @@ function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+// packages/aws/src/bootstrap.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+var templates = {
+  core: "../bootstrap/core-v1.yml",
+  "github-oidc": "../bootstrap/github-oidc-v1.yml"
+};
+async function bootstrapTemplatePath(kind) {
+  if (!Object.hasOwn(templates, kind)) throw new Error(`Unknown bootstrap template: ${kind}`);
+  return fileURLToPath(new URL(templates[kind], import.meta.url));
+}
+async function bootstrapTemplate(kind) {
+  return readFile2(await bootstrapTemplatePath(kind), "utf8");
+}
+function bootstrapContractVersion(template) {
+  const version = template.match(/BootstrapContractVersion:\s*\{\s*Value:\s*'([^']+)'\s*}/)?.[1];
+  if (!version) throw new Error("Bootstrap template has no BootstrapContractVersion output");
+  return version;
+}
+function mergeBootstrapParameters(requested, deployed) {
+  const supplied = new Map(requested.map((entry) => [entry.ParameterKey, entry.ParameterValue]));
+  const duplicates = requested.map((entry) => entry.ParameterKey);
+  if (new Set(duplicates).size !== duplicates.length)
+    throw new Error("Bootstrap parameter file contains duplicate parameters");
+  return deployed.map(({ ParameterKey, ParameterValue }) => ({
+    ParameterKey,
+    ParameterValue: supplied.get(ParameterKey) ?? ParameterValue
+  })).concat(
+    requested.filter(
+      ({ ParameterKey }) => !deployed.some((entry) => entry.ParameterKey === ParameterKey)
+    )
+  );
+}
+function deployedBootstrapStack(input, expectedContractVersion) {
+  const stack = input && typeof input === "object" && "Stacks" in input ? input.Stacks?.[0] : input;
+  if (!stack || typeof stack !== "object") throw new Error("Deployed stack JSON contains no stack");
+  const deployed = stack;
+  const contract = deployed.Outputs?.find(
+    (output) => output.OutputKey === "BootstrapContractVersion"
+  )?.OutputValue;
+  if (contract !== expectedContractVersion)
+    throw new Error(
+      `Bootstrap contract mismatch (deployed: ${contract ?? "missing"}; expected: ${expectedContractVersion}); follow the documented migration procedure`
+    );
+  if (deployed.Parameters && !Array.isArray(deployed.Parameters))
+    throw new Error("Deployed stack JSON has invalid Parameters");
+  return deployed;
+}
+function coreBootstrapOutputs(stack) {
+  const values = Object.fromEntries(
+    (stack.Outputs ?? []).filter(
+      (output) => Boolean(output.OutputValue)
+    ).map((output) => [output.OutputKey, output.OutputValue])
+  );
+  const required = ["ArtifactBucketName", "ApplicationStackName", "CloudFormationExecutionRoleArn"];
+  const missing = required.filter((key) => !values[key]);
+  if (missing.length) throw new Error(`Core stack JSON is missing outputs: ${missing.join(", ")}`);
+  return values;
+}
+function requiredBootstrapParameters(kind, values) {
+  const keys = kind === "core" ? ["ArtifactBucketName", "ApplicationStackName", "DashboardFunctionName"] : [
+    "GitHubOidcProviderArn",
+    "GitHubRepository",
+    "GitHubEnvironment",
+    "ApplicationStackName",
+    "ArtifactBucketName",
+    "CloudFormationExecutionRoleArn"
+  ];
+  const missing = keys.filter((key) => !values[key]);
+  if (missing.length) throw new Error(`Missing required bootstrap values: ${missing.join(", ")}`);
+  const optional = kind === "core" ? ["RuntimeSecretArn", "ArtifactKmsKeyArn"] : [];
+  return [...keys, ...optional].filter((key) => values[key] !== void 0).map((ParameterKey) => ({ ParameterKey, ParameterValue: values[ParameterKey] ?? "" }));
+}
+
 // packages/aws/src/index.ts
 var run = promisify(execFile);
 function deploymentTemplate(template, values) {
@@ -854,7 +928,7 @@ async function packageLambda(options) {
   await mkdir2(outputDir, { recursive: true });
   const runtimeDir = join2(outputDir, "lambda");
   await mkdir2(runtimeDir, { recursive: true });
-  const lambdaSource = fileURLToPath(new URL("../dist/lambda.mjs", import.meta.url));
+  const lambdaSource = fileURLToPath2(new URL("../dist/lambda.mjs", import.meta.url));
   await cp(lambdaSource, join2(runtimeDir, "index.mjs"));
   const release = await assembleRelease({
     boardConfigPath: options.boardConfigPath,
@@ -867,7 +941,7 @@ async function packageLambda(options) {
     ...release.metadata,
     artifactChecksums: {
       ...release.metadata.artifactChecksums,
-      "index.mjs": sha256(await readFile2(join2(runtimeDir, "index.mjs")))
+      "index.mjs": sha256(await readFile3(join2(runtimeDir, "index.mjs")))
     }
   };
   await writeFile2(join2(runtimeDir, "release.json"), `${JSON.stringify(runtimeMetadata, null, 2)}
@@ -882,7 +956,7 @@ async function packageLambda(options) {
       archiveFiles.map(async (name) => [
         name,
         [
-          strToU8(await readFile2(join2(runtimeDir, name), "utf8")),
+          strToU8(await readFile3(join2(runtimeDir, name), "utf8")),
           { mtime: new Date(1980, 0, 1, 0, 0, 0), level: 9 }
         ]
       ])
@@ -890,7 +964,7 @@ async function packageLambda(options) {
   );
   await writeFile2(lambdaPath, zipSync(archive));
   await rm(runtimeDir, { recursive: true, force: true });
-  const lambdaChecksum = sha256(await readFile2(lambdaPath));
+  const lambdaChecksum = sha256(await readFile3(lambdaPath));
   const deploymentChecksum = sha256(JSON.stringify(runtimeMetadata));
   const packagedRelease = {
     ...runtimeMetadata,
@@ -910,7 +984,7 @@ async function packageLambda(options) {
 }
 async function publishClientAssets(options) {
   const assetsDir = resolve2(options.assetsDir);
-  await readFile2(join2(assetsDir, "index.html"));
+  await readFile3(join2(assetsDir, "index.html"));
   const assetPath = `${options.assetsBaseUrl.replace(/\/+$/, "")}/dashboard/${options.version}`;
   await run("aws", [
     "s3",
@@ -935,8 +1009,8 @@ async function publishClientAssets(options) {
 async function deployLambda(options) {
   const artifactDir = resolve2(options.artifactDir);
   const assetsDir = resolve2(options.assetsDir);
-  await readFile2(join2(artifactDir, "lambda.zip"));
-  await readFile2(join2(assetsDir, "index.html"));
+  await readFile3(join2(artifactDir, "lambda.zip"));
+  await readFile3(join2(assetsDir, "index.html"));
   if (options.dryRun) return;
   const assetPath = await publishClientAssets(options);
   await run("aws", [
@@ -961,11 +1035,18 @@ async function deployLambda(options) {
   await run("aws", ["lambda", "wait", "function-updated", "--function-name", options.functionName]);
 }
 async function cloudFormationTemplate() {
-  return readFile2(fileURLToPath(new URL("../template.yml", import.meta.url)), "utf8");
+  return readFile3(fileURLToPath2(new URL("../template.yml", import.meta.url)), "utf8");
 }
 export {
+  bootstrapContractVersion,
+  bootstrapTemplate,
+  bootstrapTemplatePath,
   cloudFormationTemplate,
+  coreBootstrapOutputs,
   deployLambda,
+  deployedBootstrapStack,
+  mergeBootstrapParameters,
   packageLambda,
-  publishClientAssets
+  publishClientAssets,
+  requiredBootstrapParameters
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuous-excellence/ze-great-dashboard-aws",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
   "keywords": [
@@ -29,6 +29,7 @@
   "files": [
     "dist",
     "client",
+    "bootstrap",
     "template.yml",
     "LICENSE"
   ],

package/template.yml

@@ -1,5 +1,5 @@
 AWSTemplateFormatVersion: '2010-09-09'
-Description: Provider adapter for a Ze Great Dashboard Lambda deployment
+Description: Ze Great Dashboard private Lambda application (integrate through a customer-managed gateway)
 
 Metadata:
   PackageManagedParameters: [LambdaArtifactKey, DashboardVersion]
@@ -67,17 +67,7 @@ Resources:
           BOARD_CONFIG_URL: !Ref BoardConfigPath
           HOST: 0.0.0.0
           SECRET_REFERENCE: !If [HasSecretReference, !Ref SecretReference, !Ref AWS::NoValue]
-  ServerUrl:
-    Type: AWS::Lambda::Url
-    Properties: { TargetFunctionArn: !GetAtt ServerFunction.Arn, AuthType: NONE }
-  ServerUrlPermission:
-    Type: AWS::Lambda::Permission
-    Properties: { FunctionName: !Ref ServerFunction, Action: lambda:InvokeFunctionUrl, Principal: '*', FunctionUrlAuthType: NONE }
-  ServerInvokePermission:
-    Type: AWS::Lambda::Permission
-    Properties: { FunctionName: !Ref ServerFunction, Action: lambda:InvokeFunction, Principal: '*', InvokedViaFunctionUrl: true }
-
 Outputs:
-  ServerUrl: { Value: !GetAtt ServerUrl.FunctionUrl }
   ServerFunctionName: { Value: !Ref ServerFunction }
+  ServerFunctionArn: { Value: !GetAtt ServerFunction.Arn }
   AssetPath: { Value: !Sub '${AssetBaseUrl}/dashboard/${DashboardVersion}' }