canopycms-cdk 0.0.68-int.98 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  AWS CDK constructs and EC2 worker for deploying CanopyCMS.
4
4
 
5
+ What changed in each release, for all five CanopyCMS packages, is in `node_modules/canopycms/CHANGELOG.md`.
6
+
5
7
  ## What's Included
6
8
 
7
9
  ### CDK Constructs
@@ -9,10 +11,11 @@ AWS CDK constructs and EC2 worker for deploying CanopyCMS.
9
11
  **`CanopyCmsService`** — Core infrastructure (required):
10
12
 
11
13
  - VPC (2 AZs, public + private subnets, no NAT Gateway)
12
- - EFS filesystem with `/workspace` access point
14
+ - EFS filesystem with `/workspace` access point, TLS and IAM required, backed up daily (`efsBackup`)
13
15
  - Lambda function (Docker image, EFS mount, private subnet, no internet)
14
16
  - Lambda Function URL (for CloudFront origin)
15
- - EC2 Worker (t4g.nano spot in ASG, public subnet, EFS mount)
17
+ - EC2 Worker (on-demand t4g.nano in ASG, spot opt-in, public subnet, EFS mount, drained before replacement, replaced weekly, [hardened](../../docs/deploying-to-aws.md#the-worker-instance))
18
+ - `workerCode: { source: 'parameter' }`: lets CI roll the worker with a parameter-only change set; see [Rolling the worker from CI](../../docs/deploying-to-aws.md#rolling-the-worker-from-ci)
16
19
  - Security groups and IAM roles (least-privilege)
17
20
  - `attachTo(distribution)`: adds the editor's `/edit`, `/edit/*` and `/api/canopycms/*` behaviors (and, optionally, the CMS build's `assetPrefix` and the preview route) to a CloudFront distribution you already own
18
21
 
@@ -28,11 +31,12 @@ Use `CanopyCmsDistribution` when the CMS gets its own domain. To serve the edito
28
31
 
29
32
  ### EC2 Worker
30
33
 
31
- The `worker/` directory contains the EC2 worker entrypoint for AWS deployments. It:
34
+ The `worker/` directory contains the EC2 instance's entrypoint for AWS deployments, run as two services:
35
+
36
+ - the worker, with no network and no secret, starts the `CmsWorker` daemon from `canopycms` core and writes the Clerk auth cache;
37
+ - the GitHub gateway (`index.js gateway`) reads the secrets from AWS Secrets Manager and does everything the worker needs from GitHub, Clerk and AWS.
32
38
 
33
- - Reads secrets from AWS Secrets Manager
34
- - Wires up the Clerk-specific auth cache refresher
35
- - Starts the `CmsWorker` daemon from `canopycms` core
39
+ `worker/` also holds the three systemd units and `gateway.env.example`, for an install without the construct ([Installing the units by hand](../../docs/deploying-to-aws.md#installing-the-units-by-hand)).
36
40
 
37
41
  The `CmsWorker` class itself lives in `canopycms/worker/cms-worker` and is cloud-agnostic. This package re-exports it for convenience.
38
42
 
@@ -65,22 +69,25 @@ const cmsDist = new CanopyCmsDistribution(this, 'CmsDist', {
65
69
  ```
66
70
  CloudFront → Lambda Function URL → Lambda (VPC, no internet)
67
71
  ↕ EFS
68
- EC2 Worker (internet) → GitHub
72
+ EC2 worker (no network)
73
+ ↕ unix socket
74
+ GitHub gateway (internet) → GitHub
69
75
  ```
70
76
 
71
- Lambda handles all CMS operations using local EFS storage. The EC2 worker handles internet-requiring operations (GitHub push/PR, auth cache refresh). They communicate via the shared EFS filesystem.
77
+ Lambda handles all CMS operations using local EFS storage. The EC2 worker handles the operations that need GitHub or Clerk (GitHub push/PR, auth cache refresh), through the GitHub gateway beside it on the instance, which holds every secret and cannot see EFS. The Lambda and the worker communicate via the shared EFS filesystem.
72
78
 
73
79
  See [ARCHITECTURE.md](../../ARCHITECTURE.md#deployment-architecture) for details.
74
80
 
75
81
  ## Cost
76
82
 
77
- | Resource | Monthly Cost |
78
- | ----------------------------- | --------------- |
79
- | EC2 t4g.nano spot (ASG 1/1/1) | ~$1.50 |
80
- | Lambda (editors only) | ~$1-5 |
81
- | EFS (small repo) | ~$1 |
82
- | CloudFront (low traffic) | ~$1 |
83
- | **Total** | **~$5-9/month** |
83
+ | Resource | Monthly Cost |
84
+ | ---------------------------------- | ---------------- |
85
+ | EC2 t4g.nano on-demand (ASG 1/1/1) | ~$3 |
86
+ | Lambda (editors only) | ~$1-5 |
87
+ | EFS (small repo) | ~$1 |
88
+ | EFS backup (~$0.05/GB-month) | cents |
89
+ | CloudFront (low traffic) | ~$1 |
90
+ | **Total** | **~$6-10/month** |
84
91
 
85
92
  ## What Adopters Provide
86
93
 
@@ -37,9 +37,7 @@ export interface AssetSupportProps {
37
37
  * bucket) instead of creating one. The caller owns that bucket's
38
38
  * lifecycle rules and CORS configuration in this mode: `IBucket` (an
39
39
  * imported bucket reference) has no CDK-level `addLifecycleRule`/
40
- * `addCorsRule` - only a bucket this construct creates itself does. See
41
- * `.claude/future-tasks/docs-site-assets-wiring.md` for the BYO-mode
42
- * wiring this is designed for.
40
+ * `addCorsRule` - only a bucket this construct creates itself does.
43
41
  *
44
42
  * @default - a new private bucket is created (standalone mode)
45
43
  */
@@ -128,50 +126,91 @@ export interface AssetSupportProps {
128
126
  */
129
127
  readonly autoDeleteObjects?: boolean;
130
128
  /**
131
- * Require the transform Lambda's code asset to carry proof that it was
132
- * built with its native sharp binary (the `.deployable` marker written by
133
- * `build:lambda`). Leave this ON for anything that can reach a real
134
- * deploy.
129
+ * Deny every `s3:PutObject` to `assets/*`, `asset-originals/*` and `asset-meta/*` that carries
130
+ * no `If-None-Match`, so no principal can replace an object under those content-addressed
131
+ * prefixes. Standalone mode only: with a BYO `bucket` the prop is refused, and the same statement
132
+ * belongs in that bucket's own policy (see docs/deploying-to-aws.md).
135
133
  *
136
- * Set to `false` ONLY in this package's own tests, which synth against the
137
- * cheap `--skip-native` fixture bundle `build:test-fixtures` produces: the
138
- * suite never executes the handler, so the binary is irrelevant to what it
139
- * asserts, and requiring a real build would put a live `npm install sharp` in
140
- * front of every test run and price the suite out of CI.
134
+ * Opt-in because the Deny binds every writer: the CMS Lambda, which runs the `canopycms` your app
135
+ * installs, and with `lazyPublicTransforms` the transform Lambda, which bundles the `canopycms`
136
+ * this package was built with and calls S3 through the Lambda runtime's AWS SDK. Upgrade and
137
+ * deploy both to releases whose stores write create-only, then enable this. It also denies every
138
+ * unconditional write, such as a plain `aws s3 cp`, and every multipart upload (`UploadPart`
139
+ * carries no `If-None-Match`). Replication is authorized as `s3:ReplicateObject`, so it is not
140
+ * denied; a replica bucket takes the same statement.
141
141
  *
142
- * Adopters never need this: the published package's asset is built by
143
- * `prepack`'s full `build:lambda`, so the marker is always present.
142
+ * Create-only holds only as far as `s3:DeleteObject` does: a delete then a create replaces an
143
+ * object, so keep Delete on `assets/*` and `asset-originals/*` to a break-glass role. That is
144
+ * also how a bad derivative is replaced: delete it, then rerun `materialize-assets`. On a
145
+ * versioned bucket the delete writes a delete marker and the bad version stays restorable; a
146
+ * replica keeps the bad version until the rematerialized object replicates.
144
147
  *
145
- * @default true
148
+ * @default false
146
149
  */
147
- readonly requireDeployableBundle?: boolean;
150
+ readonly enforceCreateOnlyWrites?: boolean;
148
151
  /**
149
- * Retention for the transform Lambda's CloudWatch log group (default:
150
- * three months / 90 days).
152
+ * A replica of the bucket's `assets/` prefix. Both public behaviors fail over
153
+ * to it on 500, 502, 503 or 504 from the primary, never on a miss: the
154
+ * replica only holds what the primary has. With `lazyPublicTransforms`,
155
+ * `/assets/t/*`'s one fallback slot is the transform Lambda, so only
156
+ * `/assets/*` gets the replica.
157
+ *
158
+ * It is read through its own OAC, whose grant CDK writes only on a bucket it
159
+ * owns: an imported replica's policy must allow this distribution itself.
160
+ * Import one in another region with `Bucket.fromBucketAttributes({ bucketName,
161
+ * region })` so its regional domain name is right. Replication must cover
162
+ * `assets/`; `materialize-assets` writes only the primary.
163
+ *
164
+ * @default - no failover
151
165
  */
152
- readonly transformLogRetention?: logs.RetentionDays;
166
+ readonly replicaBucket?: s3.IBucket;
153
167
  /**
154
- * Concurrency cap on the transform Lambda (default: 10).
168
+ * Compute a missing `/assets/t/*` derivative on request with a transform
169
+ * Lambda, instead of serving only what `canopycms materialize-assets` wrote.
170
+ * Off, the public path computes nothing and an unmaterialized URL is a miss,
171
+ * which is also what a live preview on another origin than the editor shows
172
+ * for a draft's new crop.
173
+ *
174
+ * On, anyone can mint any allowlisted transform of a public asset - bounded
175
+ * per asset except crop, at ~10^16 rects - capped by reserved concurrency and
176
+ * an `assets/t/` expiry that applies only to objects the Lambda writes, which
177
+ * carry the tag `canopy-transform=lazy`: what `materialize-assets` writes is
178
+ * never expired. On a BYO `bucket` this construct cannot write that rule, so
179
+ * lazy mode there requires an explicit `transformOutputRetention`.
155
180
  *
156
- * This is a reservation — a CAP carved from the account's concurrency pool,
157
- * not pre-warmed capacity, so it costs nothing when idle. It bounds the
158
- * blast radius of the anonymous `/assets/t/*` path; see the default
159
- * constant's doc comment. Raise it for an unusually image-heavy site;
160
- * setting it to 0 would disable transforms entirely.
181
+ * @default false
161
182
  */
162
- readonly transformReservedConcurrency?: number;
183
+ readonly lazyPublicTransforms?: boolean;
163
184
  /**
164
- * How long generated derivatives under `assets/t/` are kept (default: 180
165
- * days). Only applies to a bucket this construct creates — in BYO-bucket
166
- * mode the caller owns lifecycle rules.
185
+ * Require the transform Lambda's code asset to carry the `.deployable`
186
+ * marker a full `build:lambda` writes, proving it has its native sharp
187
+ * binary. Checked only with `lazyPublicTransforms`. Set `false` ONLY in this
188
+ * package's own tests, which synth against the `--skip-native` fixture.
167
189
  *
168
- * These objects are regenerable; expiry is self-healing (the next request
169
- * regenerates and re-stores). Source assets under `asset-originals/` are
170
- * never affected.
190
+ * @default true
191
+ */
192
+ readonly requireDeployableBundle?: boolean;
193
+ /** Lazy mode only. Retention for the transform Lambda's log group (default 90 days). */
194
+ readonly transformLogRetention?: logs.RetentionDays;
195
+ /**
196
+ * Lazy mode only. Concurrency cap on the transform Lambda (default 10), a
197
+ * reservation that costs nothing idle. 0 disables transforms.
198
+ */
199
+ readonly transformReservedConcurrency?: number;
200
+ /**
201
+ * Lazy mode only. How long the Lambda's `assets/t/` outputs are kept
202
+ * (default 180 days), written as a lifecycle rule on a bucket this construct
203
+ * creates. On a BYO `bucket` nothing is written and the prop is required:
204
+ * passing it states that your bucket expires them itself, filtering on the
205
+ * tag `canopy-transform=lazy` so what `materialize-assets` writes survives,
206
+ * and on a versioned bucket also expiring noncurrent versions. Remove that
207
+ * rule before leaving lazy mode: a key the Lambda wrote first stays tagged
208
+ * after a build references it. A cross-account bucket's policy must also
209
+ * grant the transform role `s3:PutObjectTagging` on `assets/t/*`.
171
210
  */
172
211
  readonly transformOutputRetention?: Duration;
173
212
  /**
174
- * Execution role for the transform Lambda (default: CDK creates one).
213
+ * Lazy mode only. Execution role for the transform Lambda (default: CDK creates one).
175
214
  *
176
215
  * Set this when the role's ARN has to be computable WITHOUT a reference to
177
216
  * this construct - the motivating case is an asset bucket in a different AWS
@@ -192,11 +231,10 @@ export interface AssetSupportProps {
192
231
  */
193
232
  readonly transformRole?: iam.Role;
194
233
  /**
195
- * Name for the transform Lambda's CloudWatch log group (default:
234
+ * Lazy mode only. Name for the transform Lambda's CloudWatch log group (default:
196
235
  * `/canopycms/<stackName>/transform`). Deliberately NOT
197
- * `/aws/lambda/<function-name>` - see `transformLogGroup`'s comment in the
198
- * constructor for why a CDK-managed group must avoid that exact name once
199
- * the function has ever been deployed without one. Override to follow an
236
+ * `/aws/lambda/<function-name>` - see the log group's comment in
237
+ * `buildTransformLambda` for why. Override to follow an
200
238
  * org naming convention, or when instantiating this construct twice in one
201
239
  * stack (the default name would collide).
202
240
  */
@@ -249,10 +287,8 @@ export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "as
249
287
  * ```ts
250
288
  * const behaviors = assetSupport.assetBehaviors()
251
289
  *
252
- * // CloudFront matches path patterns in the order listed and stops at the
253
- * // first match, so the more specific '/assets/t/*' MUST come before
254
- * // '/assets/*' - otherwise the broader S3-only pattern swallows transform
255
- * // requests and they 403 with no Lambda fallback.
290
+ * // CloudFront stops at the first matching pattern, so '/assets/t/*' MUST
291
+ * // come before '/assets/*', or lazy mode's misses never reach the Lambda.
256
292
  * new cloudfront.Distribution(this, 'Dist', {
257
293
  * defaultBehavior: ...,
258
294
  * additionalBehaviors: {
@@ -264,18 +300,13 @@ export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "as
264
300
  */
265
301
  export interface AssetCloudFrontBehaviors {
266
302
  /**
267
- * `/assets/*` - static objects only (sanitized SVG/PDF the finalize
268
- * pipeline wrote, plus already-computed transform outputs under
269
- * `assets/t/...`, which also live under this prefix). S3 origin only -
270
- * nothing here is ever computed on demand.
303
+ * `/assets/*`: the S3 read origin (an origin group with `replicaBucket`).
271
304
  */
272
305
  readonly assets: cloudfront.BehaviorOptions;
273
306
  /**
274
- * `/assets/t/*` - transform outputs specifically. Origin group: the same
275
- * S3 origin as `assets` primary, falling over to the transform Lambda's
276
- * Function URL on 403 OR 404 (a signed OAC origin reports a miss as 403;
277
- * configuring both is defense-in-depth). CloudFront caches the failover
278
- * response.
307
+ * `/assets/t/*`: the same read origin as `assets`, or with
308
+ * `lazyPublicTransforms` an origin group falling over to the transform
309
+ * Lambda on 403 or 404.
279
310
  */
280
311
  readonly assetsTransform: cloudfront.BehaviorOptions;
281
312
  }
@@ -312,15 +343,8 @@ export interface AssetUploadBehaviorRouteOptions extends AssetUploadBehaviorOpti
312
343
  * ```
313
344
  *
314
345
  * Separate from `AssetSupport.uploadBehavior()` because the upload route needs
315
- * the bucket and nothing else, while that construct's CONSTRUCTOR always builds
316
- * the transform Lambda, a log group, a Function URL, a role and prefix grants.
317
- * Those grants never reach the BUCKET policy: `Grant.addToPrincipalOrResource`
318
- * stops after the identity statement for a same-account grantee, and
319
- * `addToResourcePolicy` on a bucket CDK does not own is a no-op - an owned
320
- * bucket, one imported by name, and one imported by ARN in another account all
321
- * emit zero `AWS::S3::BucketPolicy`, so a cross-account adopter writes the
322
- * resource half on the bucket's own side. Prefer the method when you already
323
- * have an `AssetSupport`; both funnel into the same builder and cannot drift.
346
+ * the bucket and nothing else. Prefer the method when you already have an
347
+ * `AssetSupport`; both funnel into the same builder and cannot drift.
324
348
  *
325
349
  * No bucket CORS rule is written and none is needed: the edge supplies
326
350
  * `Access-Control-Allow-Origin`, and S3's ACCEPTANCE of a presigned POST is
@@ -336,12 +360,12 @@ export declare function assetUploadBehavior(scope: Construct, options: AssetUplo
336
360
  * Wires:
337
361
  *
338
362
  * - The bucket's asset-prefix lifecycle rule + CORS (standalone mode only).
339
- * - The transform Lambda (`../../lambda/asset-transform/handler.ts`, built
340
- * via `pnpm run build:lambda` - see that script's doc comment for the
341
- * no-Docker sharp bundling approach), its dedicated CloudWatch log group
342
- * (custom name/retention/removal policy instead of the
343
- * CloudFormation-implicit `/aws/lambda/<function-name>` group), and its
344
- * OAC-locked Function URL.
363
+ * - The public read path: `/assets/*` and `/assets/t/*` served from S3 (plus
364
+ * `replicaBucket` on 5xx). It computes nothing; derivatives come from
365
+ * `canopycms materialize-assets`.
366
+ * - With `lazyPublicTransforms`, the transform Lambda
367
+ * (`../../lambda/asset-transform/handler.ts`, built by `build:lambda`), its
368
+ * log group and its OAC-locked Function URL, behind `/assets/t/*`.
345
369
  * - `attachTo(distribution)`, which attaches the two CloudFront behaviors a
346
370
  * consuming distribution needs in the only safe order (see its doc comment
347
371
  * for why the order is the whole point); `assetBehaviors()` is the escape
@@ -356,11 +380,12 @@ export declare function assetUploadBehavior(scope: Construct, options: AssetUplo
356
380
  export declare class AssetSupport extends Construct {
357
381
  /** The bucket in use (either created here, or the BYO `props.bucket`). */
358
382
  readonly bucket: s3.IBucket;
359
- readonly transformFunction: lambda.Function;
360
- /** The transform Lambda's CloudWatch log group (Lambda stdout/stderr). */
361
- readonly transformLogGroup: logs.LogGroup;
362
- /** The transform Lambda's Function URL - use as a CloudFront origin (see `assetBehaviors()`). */
363
- readonly transformFunctionUrl: lambda.FunctionUrl;
383
+ /** The lazy transform Lambda; undefined unless `lazyPublicTransforms`. */
384
+ readonly transformFunction: lambda.Function | undefined;
385
+ /** The transform Lambda's CloudWatch log group; undefined unless `lazyPublicTransforms`. */
386
+ readonly transformLogGroup: logs.LogGroup | undefined;
387
+ /** The transform Lambda's Function URL; undefined unless `lazyPublicTransforms`. */
388
+ readonly transformFunctionUrl: lambda.FunctionUrl | undefined;
364
389
  /** Effective advisory upload-size cap (see `AssetSupportProps.maxUploadBytes`). */
365
390
  readonly maxUploadBytes: number;
366
391
  private readonly behaviors;
@@ -388,6 +413,7 @@ export declare class AssetSupport extends Construct {
388
413
  */
389
414
  private uploadOrigin?;
390
415
  constructor(scope: Construct, id: string, props: AssetSupportProps);
416
+ private buildTransformLambda;
391
417
  private buildBehaviors;
392
418
  /**
393
419
  * The two CloudFront behavior configs this system needs.
@@ -424,9 +450,8 @@ export declare class AssetSupport extends Construct {
424
450
  * site's cookies and any cached basic-auth credential are live hazards
425
451
  * there, stripped by policy and function rather than never sent at all.
426
452
  * - NOT one shared distribution serving asset reads AND writes for every
427
- * environment. That means one `AssetSupport`, which owns the transform
428
- * Lambda shipping inside this package, so a `canopycms-cdk` bump would move
429
- * every environment's asset pipeline at once. Only the upload route moves;
453
+ * environment. That means one `AssetSupport`, so a `canopycms-cdk` bump
454
+ * would move every environment's asset pipeline at once. Only the upload route moves;
430
455
  * it depends on the bucket and nothing else, the same property that lets
431
456
  * `assetUploadBehavior` build it from a bucket alone.
432
457
  */
@@ -435,17 +460,12 @@ export declare class AssetSupport extends Construct {
435
460
  * Attach both asset behaviors to a concrete CloudFront distribution, in the
436
461
  * only safe order.
437
462
  *
438
- * THE ORDER IS THE WHOLE POINT. CloudFront matches path patterns in the order
439
- * given and stops at the first match. `/assets/*` is a broader, S3-only
440
- * pattern that also matches every `/assets/t/*` request; `/assets/t/*` is an
441
- * origin group that fails over to the transform Lambda on a miss. Attach
442
- * `/assets/*` first and every never-yet-computed transform gets a permanent
443
- * 403 (an OAC-signed S3 miss reports 403) while already-computed transforms
444
- * keep working. `'/assets/*'` also sorts BEFORE `'/assets/t/*'`
445
- * lexicographically (`*` = 0x2A, `t` = 0x74), so alphabetizing the keys
446
- * reproduces exactly this failure with no synth or deploy error to catch it -
447
- * and `assetBehaviors()` attaches no path pattern, so nothing there stops a
448
- * caller getting it wrong.
463
+ * CloudFront stops at the first matching pattern, and `/assets/*` also
464
+ * matches every `/assets/t/*` request. With `lazyPublicTransforms`, attaching
465
+ * it first means no miss ever reaches the transform Lambda, with no synth or
466
+ * deploy error; `'/assets/*'` also sorts first alphabetically. The two
467
+ * behaviors are identical otherwise, and the order is kept so that switching
468
+ * modes changes nothing else.
449
469
  *
450
470
  * `overrides` is merged into BOTH behaviors. The motivating case is a
451
471
  * distribution running a viewer-request function on every behavior - tier