feat(infra): AWS CDK stack for the imaging S3 bucket + CloudFront, and env-var slots for both

Adds infra/imaging-cdk/ — a CDK app provisioning exactly what
docs/IMAGING.md's "Required AWS resources" table already specified: a
private, versioned, SSE-KMS-encrypted S3 bucket; a customer-managed KMS
CMK with rotation; a CloudFront distribution fronting the bucket via
Origin Access Control (not the legacy OAI the table rules out) with a
trusted signing key group and HTTPS-only viewer policy; a separate
access-log bucket; and a least-privilege IAM role for whatever compute
runs server/ (S3 get/put/delete + the two specific KMS grants, nothing
broader). See infra/imaging-cdk/README.md for the full deploy flow.

The CloudFront signing key pair's private half is generated offline
with openssl per the README and never touches CDK/CloudFormation --
only the public key's file path is read at synth time. Verified locally
with `npm install` + `tsc --noEmit` + `cdk synth` against a fake
account/region and a throwaway test keypair (both discarded); actual
`cdk deploy` needs a real AWS account and hasn't been run from here.

Also wires the env vars docs/IMAGING.md already documented (and this
stack's own outputs feed) into compose.dev.yml, compose.prod.yml, and
.env.production.example: IMAGING_S3_*/IMAGING_CLOUDFRONT_* (opt-in --
absent by default, so local-filesystem storage keeps working
unchanged) and AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
for the AWS SDK's default credential chain S3ImagingObjectStore already
relies on. Noted in both compose files and the CDK README that real AWS
compute should prefer the stack's IAM role over static keys; the env
vars are the fallback for a plain `docker compose up` host.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: voidstackloop

.env.production.example

@@ -13,6 +13,39 @@ OIDC_ADMIN_CLIENT_ID=modelforge-admin
 IMAGING_ENCRYPTION_KEY=
 METRICS_TOKEN=replace-with-a-long-random-bearer-token
 
+# Optional: S3 imaging storage instead of the local-filesystem volume above.
+# Leave all of these blank to stay on local-filesystem storage. Provision
+# the bucket/KMS key/CloudFront distribution with infra/imaging-cdk/ (see
+# its README) rather than by hand — its stack outputs map directly onto
+# these four. All three of IMAGING_S3_BUCKET/KMS_KEY_ID/REGION must be set
+# together, or none at all; see docs/IMAGING.md's "Required AWS resources".
+IMAGING_S3_BUCKET=
+IMAGING_S3_KMS_KEY_ID=
+IMAGING_S3_REGION=
+IMAGING_S3_KEY_PREFIX=
+
+# Optional, and only meaningful once IMAGING_S3_BUCKET is set above: fronts
+# the bucket with signed CloudFront URLs instead of streaming pixel data
+# through this server process. All three required together.
+# IMAGING_CLOUDFRONT_KEY_PAIR_ID: from infra/imaging-cdk's
+#   ImagingCloudFrontKeyPairId output.
+# IMAGING_CLOUDFRONT_PRIVATE_KEY: base64 of the PEM private key generated
+#   per infra/imaging-cdk/README.md step 1 — this value never comes from
+#   CDK output; it's generated offline and never leaves this file.
+IMAGING_CLOUDFRONT_DOMAIN=
+IMAGING_CLOUDFRONT_KEY_PAIR_ID=
+IMAGING_CLOUDFRONT_PRIVATE_KEY=
+
+# Only needed when IMAGING_S3_BUCKET is set above (the AWS SDK's default
+# credential chain picks these up automatically). On real AWS compute
+# (ECS/EC2/EKS), prefer an attached IAM role instead — see
+# infra/imaging-cdk/README.md's server task role output — and leave these
+# three blank. Static keys are the fallback for a host with no AWS-native
+# identity to inherit from.
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_SESSION_TOKEN=
+
 # The included admin container is plain HTTP on this local port. Terminate
 # TLS in a real ingress/reverse proxy before exposing it to users.
 ADMIN_HTTPS_PROXY_PORT=8080

.gitignore

@@ -23,6 +23,11 @@ graphify-out/
 .env.production
 /models/
 /secrets/
+infra/imaging-cdk/cdk.out/
+# The CloudFront signing key pair generated per infra/imaging-cdk/README.md
+# — the private half must never be committed; the public half doesn't need
+# to be either (each real deployment generates its own).
+infra/imaging-cdk/*.pem
 
 # Personal AI-assistant tooling state — machine-specific absolute paths and
 # per-developer config, not portable across machines or meant to be shared.

compose.dev.yml

@@ -67,6 +67,31 @@ services:
       IMAGING_LOCAL_ROOT: /var/lib/modelforge/imaging
       # Exactly 32 bytes after base64 decoding. Development only.
       IMAGING_ENCRYPTION_KEY: MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE= # gitleaks:allow — sequential digits, dev-only placeholder
+      # Opt-in S3 imaging storage against a real bucket (see
+      # infra/imaging-cdk/README.md) — unset by default, so this container
+      # stays on local-filesystem storage above unless you export real
+      # values in your own shell before `docker compose up`. Setting
+      # IMAGING_S3_BUCKET/KMS_KEY_ID/REGION (all three, or none) switches
+      # config.ts's storage-mode detection to S3; the CLOUDFRONT_* trio is
+      # separately optional on top of that. Never put real values directly
+      # in this file — compose only reads them from the host environment.
+      IMAGING_S3_BUCKET: ${IMAGING_S3_BUCKET:-}
+      IMAGING_S3_KMS_KEY_ID: ${IMAGING_S3_KMS_KEY_ID:-}
+      IMAGING_S3_REGION: ${IMAGING_S3_REGION:-}
+      IMAGING_S3_KEY_PREFIX: ${IMAGING_S3_KEY_PREFIX:-}
+      IMAGING_CLOUDFRONT_DOMAIN: ${IMAGING_CLOUDFRONT_DOMAIN:-}
+      IMAGING_CLOUDFRONT_KEY_PAIR_ID: ${IMAGING_CLOUDFRONT_KEY_PAIR_ID:-}
+      IMAGING_CLOUDFRONT_PRIVATE_KEY: ${IMAGING_CLOUDFRONT_PRIVATE_KEY:-}
+      # The AWS SDK's default credential chain (S3ImagingObjectStore's
+      # `new S3Client({ region })`, no explicit keys in code) picks these up
+      # automatically when set. Only needed in S3 mode; harmless empty
+      # otherwise. On real AWS compute (ECS/EC2/EKS), prefer an attached
+      # IAM role instead (see infra/imaging-cdk/README.md's server task
+      # role) and leave these three unset — static keys are the fallback
+      # for a plain `docker compose up` host with no AWS-native identity.
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID:-}
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY:-}
+      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN:-}
       RATE_LIMIT_MAX: "1000"
     ports:
       - "${SERVER_PORT:-4000}:4000"

compose.prod.yml

@@ -50,6 +50,25 @@ services:
       TRUST_PROXY: "1"
       IMAGING_LOCAL_ROOT: /var/lib/modelforge/imaging
       IMAGING_ENCRYPTION_KEY: ${IMAGING_ENCRYPTION_KEY:?set IMAGING_ENCRYPTION_KEY}
+      # Opt-in S3 imaging storage (see infra/imaging-cdk/ and
+      # docs/IMAGING.md's "Required AWS resources") — leave unset to stay
+      # on the local-filesystem volume above. Setting IMAGING_S3_BUCKET/
+      # KMS_KEY_ID/REGION switches config.ts's storage-mode detection to
+      # S3; CLOUDFRONT_* is separately optional on top of that.
+      IMAGING_S3_BUCKET: ${IMAGING_S3_BUCKET:-}
+      IMAGING_S3_KMS_KEY_ID: ${IMAGING_S3_KMS_KEY_ID:-}
+      IMAGING_S3_REGION: ${IMAGING_S3_REGION:-}
+      IMAGING_S3_KEY_PREFIX: ${IMAGING_S3_KEY_PREFIX:-}
+      IMAGING_CLOUDFRONT_DOMAIN: ${IMAGING_CLOUDFRONT_DOMAIN:-}
+      IMAGING_CLOUDFRONT_KEY_PAIR_ID: ${IMAGING_CLOUDFRONT_KEY_PAIR_ID:-}
+      IMAGING_CLOUDFRONT_PRIVATE_KEY: ${IMAGING_CLOUDFRONT_PRIVATE_KEY:-}
+      # Only needed in S3 mode. On real AWS compute, prefer an attached IAM
+      # role instead (infra/imaging-cdk/README.md's server task role) and
+      # leave these unset — static keys are the fallback for a host with no
+      # AWS-native identity to inherit from.
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID:-}
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY:-}
+      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN:-}
       POOL_MAX: ${POOL_MAX:-20}
       RATE_LIMIT_MAX: ${RATE_LIMIT_MAX:-300}
       RATE_LIMIT_WINDOW_MS: ${RATE_LIMIT_WINDOW_MS:-60000}

docs/IMAGING.md

@@ -404,6 +404,13 @@ DICOM values.
 
 ### Required AWS resources
 
+`infra/imaging-cdk/` provisions everything in the table below as one CDK
+stack — see that directory's README for the signing-key-generation step,
+deploy instructions, and how its outputs map onto the env vars in
+"Configuration" below. The table itself is still the source of truth for
+*what's* required; the stack is a direct translation of it, not an
+independent design.
+
 | Resource | Requirement |
 |---|---|
 | S3 bucket | Block Public Access fully on; versioning on; default encryption SSE-KMS with the CMK below; bucket policy allowing **only** the CloudFront distribution via Origin Access Control |

infra/imaging-cdk/README.md

@@ -0,0 +1,98 @@
+# Imaging CDK stack
+
+Provisions the AWS resources `docs/IMAGING.md`'s "Required AWS resources"
+table specifies for `server/`'s `S3ImagingObjectStore`: a private,
+SSE-KMS-encrypted S3 bucket; a customer-managed KMS key; a CloudFront
+distribution fronting the bucket via Origin Access Control with a trusted
+signing key group; and a least-privilege IAM role for whatever compute runs
+`server/`. Read that table before changing anything here — this stack is a
+direct translation of it, not an independent design.
+
+**What this stack does *not* do**: it does not deploy `server/` itself (no
+ECS service/task definition, no compute). It hands back
+`ImagingServerTaskRoleArn` as an output — attach that role to whichever
+compute you actually run `server/` on (ECS task role, EC2 instance profile,
+etc.). It also does not touch anything outside this one CloudFormation
+stack — no VPC, no networking, no other ModelForge infrastructure.
+
+**Not run against a real AWS account from this repository** — `npx cdk
+synth` was used locally to confirm the stack synthesizes correctly (a fake
+account/region and a throwaway test keypair, both discarded); `cdk diff`
+and `cdk deploy` need your real AWS credentials and account, and are yours
+to run.
+
+## 1. Generate the signing key pair (offline, outside CDK)
+
+The private half of the CloudFront signing key must never be generated by,
+or pass through, CDK/CloudFormation — it goes straight from `openssl` to
+the server's own secret storage (`IMAGING_CLOUDFRONT_PRIVATE_KEY`), and
+CDK only ever sees the public half.
+
+```bash
+openssl genrsa -out imaging-signing-key.pem 2048
+openssl rsa -pubout -in imaging-signing-key.pem -out imaging-signing-key.pub.pem
+```
+
+- `imaging-signing-key.pub.pem` — passed to this stack (see below). Safe to
+  keep around; it's public.
+- `imaging-signing-key.pem` — the private half. Base64-encode it
+  (`base64 -w0 imaging-signing-key.pem`) and set that as the server's
+  `IMAGING_CLOUDFRONT_PRIVATE_KEY`. **Never commit either file** — the
+  repo's `.gitignore` already excludes `infra/imaging-cdk/*.pem`, so
+  generating them directly in this directory (as the commands above do) is
+  covered automatically; confirm with `git check-ignore -v` if you generate
+  them elsewhere instead.
+
+## 2. Install and bootstrap
+
+```bash
+npm ci
+npx cdk bootstrap aws://<account-id>/<region>   # once per account+region
+```
+
+## 3. Review and deploy
+
+```bash
+npx cdk diff \
+  -c signingPublicKeyPath=/absolute/path/to/imaging-signing-key.pub.pem \
+  -c bucketNamePrefix=modelforge-imaging-prod
+
+npx cdk deploy \
+  -c signingPublicKeyPath=/absolute/path/to/imaging-signing-key.pub.pem \
+  -c bucketNamePrefix=modelforge-imaging-prod
+```
+
+`bucketNamePrefix` defaults to `modelforge-imaging`; the stack appends
+`-<account>-<region>` to keep the final bucket name globally unique.
+`signingPublicKeyPath` defaults to `./imaging-signing-key.pub.pem` (relative
+to wherever you run the CDK CLI from).
+
+## 4. Map the outputs onto server config
+
+`cdk deploy` prints these as stack outputs; `docs/IMAGING.md`'s
+"Configuration" section names the exact env vars each one fills:
+
+| Stack output | Env var |
+|---|---|
+| `ImagingS3Bucket` | `IMAGING_S3_BUCKET` |
+| `ImagingS3KmsKeyId` | `IMAGING_S3_KMS_KEY_ID` |
+| `ImagingS3Region` | `IMAGING_S3_REGION` |
+| `ImagingCloudFrontDomain` | `IMAGING_CLOUDFRONT_DOMAIN` |
+| `ImagingCloudFrontKeyPairId` | `IMAGING_CLOUDFRONT_KEY_PAIR_ID` |
+| — (step 1's private key, base64) | `IMAGING_CLOUDFRONT_PRIVATE_KEY` |
+| `ImagingServerTaskRoleArn` | attach to server/'s compute; not an env var |
+
+`IMAGING_S3_KEY_PREFIX` isn't a stack output — it's your own choice of
+object-key namespace within the bucket, not an AWS resource.
+
+See `.env.production.example` at the repo root for where these land in a
+real deployment's environment file.
+
+## Teardown
+
+`cdk destroy` removes the CloudFront distribution and IAM role, but the S3
+bucket, log bucket, and KMS key all use `RemovalPolicy.RETAIN` deliberately
+(this stack holds PHI-bearing imaging data and its encryption key) — delete
+those by hand, deliberately, only after confirming what's actually in the
+bucket. A KMS key scheduled for deletion has a mandatory 7–30 day waiting
+window before AWS actually deletes it.

infra/imaging-cdk/bin/imaging-cdk.ts

@@ -0,0 +1,17 @@
+import * as path from "node:path";
+import { App } from "aws-cdk-lib";
+import { ImagingStack } from "../lib/imaging-stack.js";
+
+const app = new App();
+
+const signingPublicKeyPath = app.node.tryGetContext("signingPublicKeyPath") ?? path.resolve(process.cwd(), "imaging-signing-key.pub.pem");
+const bucketNamePrefix = app.node.tryGetContext("bucketNamePrefix") ?? "modelforge-imaging";
+
+new ImagingStack(app, "ModelForgeImagingStack", {
+    env: {
+        account: process.env.CDK_DEFAULT_ACCOUNT,
+        region: process.env.CDK_DEFAULT_REGION,
+    },
+    signingPublicKeyPath,
+    bucketNamePrefix,
+});

infra/imaging-cdk/cdk.json

@@ -0,0 +1,24 @@
+{
+    "app": "npx tsx bin/imaging-cdk.ts",
+    "watch": {
+        "include": ["bin/**", "lib/**"],
+        "exclude": ["README.md", "cdk*.json", "**/*.d.ts", "**/*.js", "dist/**", "node_modules/**"]
+    },
+    "context": {
+        "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+        "@aws-cdk/core:checkSecretUsage": true,
+        "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
+        "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
+        "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+        "@aws-cdk/aws-iam:minimizePolicies": true,
+        "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+        "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+        "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
+        "@aws-cdk/core:enablePartitionLiterals": true,
+        "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
+        "@aws-cdk/aws-iam:standardizedServicePrincipals": true,
+        "@aws-cdk/aws-s3:keepNotificationInImportedBucket": false,
+        "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": true,
+        "@aws-cdk/aws-apigateway:disableCloudWatchRole": true
+    }
+}