canopycms-cdk 0.0.67-int.88 → 0.0.67-int.90

package/dist/constructs/asset-support.js

@@ -755,8 +755,8 @@ export class AssetSupport extends Construct {
             code: lambda.Code.fromAsset(transformAssetDir),
             handler: 'handler.handler',
             // nodejs20.x was deprecated 2026-04-30; CDK's CloudFormation validation
-            // now fails synth on it. The esbuild bundle targets node20 and runs
-            // unchanged on the node22 runtime.
+            // now fails synth on it. The esbuild bundle (lambda/asset-transform/
+            // build.mjs) targets node22 to match; move the two together.
             runtime: lambda.Runtime.NODEJS_22_X,
             architecture: lambda.Architecture.ARM_64,
             memorySize: TRANSFORM_LAMBDA_MEMORY_MB,

package/dist/constructs/cms-service.d.ts

@@ -34,11 +34,18 @@ export interface CanopyCmsServiceProps {
     /** Lambda reserved concurrency cap (default: 10) */
     reservedConcurrency?: number;
     /**
-     * Lambda architecture (default: `Architecture.X86_64`, Lambda's own
-     * default). MUST match the platform the Docker image was built for - e.g.
-     * an image built for `Platform.LINUX_ARM64` requires
-     * `Architecture.ARM_64` here, or the function fails at invoke time with
-     * an exec format error.
+     * Lambda architecture (default: `Architecture.ARM_64`, matching the EC2
+     * worker and AssetSupport's transform Lambda).
+     *
+     * This also decides the image's architecture for
+     * `DockerImageCode.fromImageAsset`: the construct always passes a resolved
+     * architecture to the function, and CDK derives the Docker build platform
+     * from it. So omit `platform` on `fromImageAsset`. An explicit `platform`
+     * overrides the derived one, and an image built for the other architecture
+     * cannot run on the function: an arm64 image on an x86_64 function fails at
+     * invoke with `Runtime.InvalidEntrypoint` (see "Where the image is built" in
+     * docs/deploying-to-aws.md). A prebuilt image (`DockerImageCode.fromEcr`) has
+     * no build for CDK to steer, so it must already be built for this architecture.
      */
     architecture?: lambda.Architecture;
     /** EC2 spot max price (default: on-demand rate for t4g.nano) */
@@ -70,8 +77,114 @@ export interface CanopyCmsServiceProps {
     githubRepo: string;
     /** Secrets Manager ARN for the GitHub bot token */
     githubTokenSecretArn?: string;
+    /**
+     * The key within a JSON secret document at `githubTokenSecretArn`; omit when
+     * the secret's whole value is the credential.
+     *
+     * Stamped into the worker's `CANOPYCMS_GITHUB_TOKEN_SECRET_JSON_FIELD`, which
+     * `getSecret` (packages/canopycms-cdk/worker/secrets.ts) reads to pull one
+     * field out of the document instead of using the whole string. Omitting it is
+     * the default and the common case — a secret holding a bare `ghp_…` needs
+     * nothing here.
+     *
+     * This is NOT the ECS/CloudFormation `arn:…:secret:name-AbCdEf:KEY::`
+     * convention. The worker calls the `GetSecretValue` API, which does not parse
+     * that suffix; a literal ARN carrying one is refused at synth (see
+     * `assertSecretArnHasNoFieldSuffix` below, and the known limit recorded on
+     * `SECRET_ARN_WITH_EMPTY_VERSION_TAIL` for the one token spelling that gets
+     * through) and the field belongs here instead.
+     */
+    githubTokenSecretJsonField?: string;
+    /**
+     * GitHub App ID, to authenticate the worker as a GitHub App installation
+     * instead of as a personal access token.
+     *
+     * **The token is the default and stays first-class.** Registering a GitHub
+     * App under an organisation takes an owner of that organisation (or a GitHub
+     * App manager for all its Apps), which many adopters are not, so this is the
+     * "if your organisation requires it" option, not a direction of travel.
+     * Nothing about
+     * `githubTokenSecretArn` is deprecated or warned about.
+     *
+     * All three App props (`githubAppId`, `githubAppInstallationId`,
+     * `githubAppPrivateKeySecretArn`) are set together or not at all, and App
+     * auth is mutually exclusive with `githubTokenSecretArn` — both are refused
+     * at synth. That mirrors `resolveWorkerGitHubAuth` in core
+     * (packages/canopycms/src/worker/github-auth.ts), which refuses the same two
+     * shapes at boot; checking here turns a 5-second systemd restart loop into a
+     * failed `cdk synth`.
+     *
+     * Stamped into the worker's `CANOPYCMS_GITHUB_APP_ID`.
+     */
+    githubAppId?: string;
+    /**
+     * The App's installation ID on your repository — NOT the App ID above.
+     *
+     * An App can be installed on several accounts, and a token is minted per
+     * installation, so both numbers are needed. It is the trailing number in the
+     * URL of the App's install page under your organisation's settings.
+     *
+     * Stamped into the worker's `CANOPYCMS_GITHUB_APP_INSTALLATION_ID`.
+     */
+    githubAppInstallationId?: string;
+    /**
+     * Secrets Manager ARN for the App's PEM private key.
+     *
+     * **ARN-only: there is deliberately no plaintext prop for this key**, unlike
+     * every other credential the construct knows about, and the reason is
+     * mechanical rather than a matter of taste. Every value the construct puts in
+     * the worker's environment is written into a `.env` file that systemd reads
+     * as `EnvironmentFile=`, where a newline starts a new variable — so
+     * `assertEnvSafe` refuses one, and a PEM is inherently multi-line. A
+     * plaintext key could not be delivered to the worker intact by this path at
+     * all. Passing the PEM itself here is caught by name at synth (see
+     * `assertNotInlinePrivateKey`, and the note there about the generated stack
+     * reaching CDK's own ARN complaint first) rather than surfacing as a puzzling
+     * "an ARN must not contain a newline".
+     *
+     * The ARN is unioned into the worker's IAM policy alongside the other secret
+     * ARN props; you do not need to repeat it in `secretsArns`.
+     */
+    githubAppPrivateKeySecretArn?: string;
+    /**
+     * The key within a JSON secret document at `githubAppPrivateKeySecretArn`;
+     * omit when the secret's whole value is the PEM.
+     *
+     * Stamped into the worker's
+     * `CANOPYCMS_GITHUB_APP_PRIVATE_KEY_SECRET_JSON_FIELD`. See
+     * `githubTokenSecretJsonField` above — same mechanism, same non-relationship
+     * to the ECS `:KEY::` ARN suffix. This is the case that motivated the JSON
+     * field support in the first place: an App private key is exactly the kind of
+     * material an organisation keeps inside one credential document per
+     * environment.
+     *
+     * A PEM stored as a JSON string value carries its newlines as `\n` escapes,
+     * which `JSON.parse` turns back into real newlines — and the worker
+     * additionally runs whatever it reads through
+     * `normalizeGitHubAppPrivateKey`, which unescapes and base64-unwraps, so a
+     * key mangled by a single-line config field still works.
+     */
+    githubAppPrivateKeySecretJsonField?: string;
     /** Secrets Manager ARN for the Clerk secret key */
     clerkSecretKeySecretArn?: string;
+    /**
+     * The key within a JSON secret document at `clerkSecretKeySecretArn`; omit
+     * when the secret's whole value is the credential.
+     *
+     * Stamped into the worker's `CLERK_SECRET_KEY_SECRET_JSON_FIELD`. See
+     * `githubTokenSecretJsonField` above — same mechanism, same non-relationship
+     * to the ECS `:KEY::` ARN suffix.
+     *
+     * Note that this covers `CLERK_SECRET_KEY` only. A Clerk JSON document
+     * typically also holds `CLERK_JWT_KEY` and the publishable key, and NEITHER
+     * can be sourced from Secrets Manager at all: `CLERK_JWT_KEY` reaches the
+     * Lambda as a plain value through `environment`, and the publishable key is a
+     * Docker build arg inlined into the client bundle. Both are public material
+     * (docs/deploying-to-aws.md, "Security Model"), so that is by design rather
+     * than an omission — but it means pointing this prop at your document does
+     * not relieve you of supplying those two separately.
+     */
+    clerkSecretKeySecretJsonField?: string;
     /**
      * The GitHub repository's default branch name (default: 'main').
      *
@@ -227,10 +340,10 @@ export interface CanopyCmsServiceProps {
  * - Lambda function (Docker image, EFS mount, private subnet, no internet)
  * - Lambda Function URL (for CloudFront origin)
  * - EC2 Worker (t4g.nano spot in ASG, public subnet, EFS mount, systemd) -
- *   rolled on every deploy via the ASG's UpdatePolicy, so a changed worker
- *   bundle actually reaches the instance instead of sitting unused in a
- *   launch template until the next spot interruption (see the UpdatePolicy
- *   below)
+ *   rolled via the ASG's UpdatePolicy by every deploy that changes its launch
+ *   template, so a changed worker bundle reaches the instance instead of
+ *   sitting unused in a launch template until the next spot interruption (see
+ *   the UpdatePolicy below)
  * - Dedicated CloudWatch log groups for the CMS Lambda and the worker's
  *   stdout/stderr (the worker's is shipped via the amazon-cloudwatch-agent -
  *   journald is not agent-readable), each with a custom name/retention/