headroom-cms 0.1.11 → 0.2.0

package/dist/webhooks.js

@@ -1,8 +1,9 @@
 /**
  * Webhook Infrastructure
  *
- * 2 DynamoDB tables + 2 SQS queues + webhook worker Lambda.
- * Supports dev mode (Go source) and package mode (pre-compiled binary).
+ * 2 DynamoDB tables + webhook worker Lambda (async-invoked by the API) + DLQ
+ * (Lambda async on-failure destination). The API directly invokes the worker
+ * via lambda:InvokeFunction; there is no SQS queue between them.
  */
 import path from "path";
 export function createWebhooks(name, args) {
@@ -21,6 +22,9 @@ export function createWebhooks(name, args) {
         primaryIndex: { hashKey: "pk", rangeKey: "sk" },
         ttl: "ttl",
     });
+    // DLQ retained as Lambda async OnFailure destination. Lambda writes a
+    // failure envelope (not the original payload verbatim) when retries are
+    // exhausted. No consumer polls this queue — it's a sink only.
     const webhookDeliveryDLQ = new sst.aws.Queue(`${name}WebhookDeliveryDLQ`, {
         transform: {
             queue: (queueArgs) => {
@@ -28,22 +32,6 @@ export function createWebhooks(name, args) {
             },
         },
     });
-    const webhookDeliveryQueue = new sst.aws.Queue(`${name}WebhookDeliveryQueue`, {
-        dlq: {
-            queue: webhookDeliveryDLQ.arn,
-            retry: 5,
-        },
-        transform: {
-            queue: (queueArgs) => {
-                queueArgs.visibilityTimeoutSeconds = 60;
-                queueArgs.messageRetentionSeconds = 4 * 24 * 60 * 60; // 4 days
-            },
-        },
-    });
-    // Webhook worker Lambda: processes SQS messages and delivers webhooks.
-    // Note: We use a manual Function + EventSourceMapping instead of
-    // queue.subscribe() to avoid a duplicate LambdaEncryptionKey issue
-    // caused by SST's dynamic import creating a separate Function class instance.
     const workerConfig = args.dev
         ? {
             handler: args.dev.handler,
@@ -61,30 +49,29 @@ export function createWebhooks(name, args) {
         timeout: "30 seconds",
         environment: {
             WEBHOOK_DELIVERIES_TABLE: webhookDeliveries.name,
-            WEBHOOKS_TABLE: webhooks.name,
-            SITES_TABLE: args.sites.name,
         },
-        link: [webhookDeliveries, webhooks, args.sites],
-        permissions: [
-            {
-                actions: [
-                    "sqs:ReceiveMessage",
-                    "sqs:DeleteMessage",
-                    "sqs:GetQueueAttributes",
-                ],
-                resources: [webhookDeliveryQueue.arn],
-            },
-        ],
+        // webhookDeliveryDLQ is linked so SST auto-grants sqs:SendMessage on the
+        // worker's execution role. Lambda async OnFailure delivery uses the
+        // function's own role to write the failure envelope to the DLQ — without
+        // this grant, AWS accepts the FunctionEventInvokeConfig at deploy time but
+        // silently drops failure envelopes at runtime.
+        link: [webhookDeliveries, webhookDeliveryDLQ],
     });
-    new aws.lambda.EventSourceMapping(`${name}WebhookWorkerEventSource`, {
-        eventSourceArn: webhookDeliveryQueue.arn,
+    // Lambda async retry + DLQ on terminal failure. MaximumRetryAttempts is
+    // 0–2 (industry standard for webhook delivery — Stripe/GitHub publish
+    // similar caps). Total attempts = initial + 2 retries = 3.
+    new aws.lambda.FunctionEventInvokeConfig(`${name}WebhookWorkerAsyncConfig`, {
         functionName: webhookWorker.name,
-        batchSize: 1,
+        maximumRetryAttempts: 2,
+        maximumEventAgeInSeconds: 6 * 60 * 60, // 6 hours
+        destinationConfig: {
+            onFailure: { destination: webhookDeliveryDLQ.arn },
+        },
     });
     return {
         webhooks,
         webhookDeliveries,
-        webhookDeliveryQueue,
+        webhookWorker,
         webhookDeliveryDLQ,
     };
 }

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAYxB,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAiB;IAC5D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE;QACrD,MAAM,EAAE;YACN,EAAE,EAAE,QAAQ;YACZ,EAAE,EAAE,QAAQ;SACb;QACD,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;KAChD,CAAC,CAAC;IAEH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,mBAAmB,EAAE;QACvE,MAAM,EAAE;YACN,EAAE,EAAE,QAAQ;YACZ,EAAE,EAAE,QAAQ;SACb;QACD,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC/C,GAAG,EAAE,KAAK;KACX,CAAC,CAAC;IAEH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,oBAAoB,EAAE;QACxE,SAAS,EAAE;YACT,KAAK,EAAE,CAAC,SAAc,EAAE,EAAE;gBACxB,SAAS,CAAC,uBAAuB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU;YACnE,CAAC;SACF;KACF,CAAC,CAAC;IAEH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAC5C,GAAG,IAAI,sBAAsB,EAC7B;QACE,GAAG,EAAE;YACH,KAAK,EAAE,kBAAkB,CAAC,GAAG;YAC7B,KAAK,EAAE,CAAC;SACT;QACD,SAAS,EAAE;YACT,KAAK,EAAE,CAAC,SAAc,EAAE,EAAE;gBACxB,SAAS,CAAC,wBAAwB,GAAG,EAAE,CAAC;gBACxC,SAAS,CAAC,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,SAAS;YACjE,CAAC;SACF;KACF,CACF,CAAC;IAEF,uEAAuE;IACvE,iEAAiE;IACjE,mEAAmE;IACnE,8EAA8E;IAC9E,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG;QAC3B,CAAC,CAAC;YACE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO;YACzB,OAAO,EAAE,IAAa;SACvB;QACH,CAAC,CAAC;YACE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,uBAAuB,CAAC;YACxD,OAAO,EAAE,WAAW;YACpB,OAAO,EAAE,iBAA0B;YACnC,YAAY,EAAE,OAAgB;SAC/B,CAAC;IAEN,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,eAAe,EAAE;QACjE,GAAG,YAAY;QACf,MAAM,EAAE,QAAQ;QAChB,OAAO,EAAE,YAAY;QACrB,WAAW,EAAE;YACX,wBAAwB,EAAE,iBAAiB,CAAC,IAAI;YAChD,cAAc,EAAE,QAAQ,CAAC,IAAI;YAC7B,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;SAC7B;QACD,IAAI,EAAE,CAAC,iBAAiB,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC;QAC/C,WAAW,EAAE;YACX;gBACE,OAAO,EAAE;oBACP,oBAAoB;oBACpB,mBAAmB;oBACnB,wBAAwB;iBACzB;gBACD,SAAS,EAAE,CAAC,oBAAoB,CAAC,GAAG,CAAC;aACtC;SACF;KACF,CAAC,CAAC;IAEH,IAAI,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,GAAG,IAAI,0BAA0B,EAAE;QACnE,cAAc,EAAE,oBAAoB,CAAC,GAAG;QACxC,YAAY,EAAE,aAAa,CAAC,IAAI;QAChC,SAAS,EAAE,CAAC;KACb,CAAC,CAAC;IAEH,OAAO;QACL,QAAQ;QACR,iBAAiB;QACjB,oBAAoB;QACpB,kBAAkB;KACnB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAYxB,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAiB;IAC5D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE;QACrD,MAAM,EAAE;YACN,EAAE,EAAE,QAAQ;YACZ,EAAE,EAAE,QAAQ;SACb;QACD,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;KAChD,CAAC,CAAC;IAEH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,mBAAmB,EAAE;QACvE,MAAM,EAAE;YACN,EAAE,EAAE,QAAQ;YACZ,EAAE,EAAE,QAAQ;SACb;QACD,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC/C,GAAG,EAAE,KAAK;KACX,CAAC,CAAC;IAEH,sEAAsE;IACtE,wEAAwE;IACxE,8DAA8D;IAC9D,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,oBAAoB,EAAE;QACxE,SAAS,EAAE;YACT,KAAK,EAAE,CAAC,SAAc,EAAE,EAAE;gBACxB,SAAS,CAAC,uBAAuB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU;YACnE,CAAC;SACF;KACF,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG;QAC3B,CAAC,CAAC;YACE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO;YACzB,OAAO,EAAE,IAAa;SACvB;QACH,CAAC,CAAC;YACE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,uBAAuB,CAAC;YACxD,OAAO,EAAE,WAAW;YACpB,OAAO,EAAE,iBAA0B;YACnC,YAAY,EAAE,OAAgB;SAC/B,CAAC;IAEN,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,eAAe,EAAE;QACjE,GAAG,YAAY;QACf,MAAM,EAAE,QAAQ;QAChB,OAAO,EAAE,YAAY;QACrB,WAAW,EAAE;YACX,wBAAwB,EAAE,iBAAiB,CAAC,IAAI;SACjD;QACD,yEAAyE;QACzE,oEAAoE;QACpE,yEAAyE;QACzE,2EAA2E;QAC3E,+CAA+C;QAC/C,IAAI,EAAE,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;KAC9C,CAAC,CAAC;IAEH,wEAAwE;IACxE,sEAAsE;IACtE,2DAA2D;IAC3D,IAAI,GAAG,CAAC,MAAM,CAAC,yBAAyB,CAAC,GAAG,IAAI,0BAA0B,EAAE;QAC1E,YAAY,EAAE,aAAa,CAAC,IAAI;QAChC,oBAAoB,EAAE,CAAC;QACvB,wBAAwB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,UAAU;QACjD,iBAAiB,EAAE;YACjB,SAAS,EAAE,EAAE,WAAW,EAAE,kBAAkB,CAAC,GAAG,EAAE;SACnD;KACF,CAAC,CAAC;IAEH,OAAO;QACL,QAAQ;QACR,iBAAiB;QACjB,aAAa;QACb,kBAAkB;KACnB,CAAC;AACJ,CAAC"}

package/lambda/image-lambda/index.mjs

@@ -4,7 +4,17 @@ import { S3Client, GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3
 import { createHmac, timingSafeEqual } from "crypto";
 var s3 = new S3Client({});
 var BUCKET = process.env.CONTENT_BUCKET;
-var SIGNING_SECRET = process.env.IMAGE_SIGNING_SECRET;
+var MASTER_SECRET = process.env.IMAGE_SIGNING_MASTER_SECRET;
+var MASTER_SECRET_OLD = process.env.IMAGE_SIGNING_MASTER_SECRET_OLD;
+var _timingSafeEqualCallCount = { count: 0 };
+function _timingSafeEqual(a, b) {
+  _timingSafeEqualCallCount.count++;
+  return timingSafeEqual(a, b);
+}
+function deriveSiteSecret(master, siteHost) {
+  if (!master) return null;
+  return createHmac("sha256", master).update(siteHost).digest("hex").substring(0, 32);
+}
 var MAX_WIDTH = 2048;
 var MAX_HEIGHT = 2048;
 var MAX_PIXELS = 4e6;
@@ -31,6 +41,11 @@ async function handler(event) {
   if (!match) {
     return { statusCode: 400, body: "Invalid image path" };
   }
+  const [, site, mediaId, ext] = match;
+  const sitePrimary = deriveSiteSecret(MASTER_SECRET, site);
+  if (!sitePrimary) {
+    return { statusCode: 503, body: "Image transforms not configured" };
+  }
   const params = new URLSearchParams(rawQuery);
   const sig = params.get("sig");
   if (!sig) {
@@ -44,11 +59,18 @@ async function handler(event) {
   if (!hasTransform) {
     return { statusCode: 400, body: "No transform requested. Use /media/ path for originals." };
   }
-  const expectedSig = computeSignature(rawPath, params);
-  if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) {
+  const siteOld = deriveSiteSecret(MASTER_SECRET_OLD, site);
+  const sigBuf = Buffer.from(sig);
+  const expectedPrimary = computeSignature(rawPath, params, sitePrimary);
+  const primaryMatch = _timingSafeEqual(sigBuf, Buffer.from(expectedPrimary));
+  let oldMatch = false;
+  if (siteOld) {
+    const expectedOld = computeSignature(rawPath, params, siteOld);
+    oldMatch = _timingSafeEqual(sigBuf, Buffer.from(expectedOld));
+  }
+  if (!primaryMatch && !oldMatch) {
     return { statusCode: 403, body: "Invalid signature" };
   }
-  const [, site, mediaId, ext] = match;
   const s3Key = `sites/${site}/media/${mediaId}/original${ext}`;
   const w = clamp(parseInt(params.get("w")) || null, 1, MAX_WIDTH);
   const h = clamp(parseInt(params.get("h")) || null, 1, MAX_HEIGHT);
@@ -139,11 +161,11 @@ async function handler(event) {
     return { statusCode: 500, body: "Image processing failed" };
   }
 }
-function computeSignature(path, params) {
+function computeSignature(path, params, key) {
   const sorted = new URLSearchParams([...params.entries()].sort());
   const qs = sorted.toString();
   const canonical = qs ? `${path}?${qs}` : path;
-  return createHmac("sha256", SIGNING_SECRET).update(canonical).digest("hex").substring(0, 32);
+  return createHmac("sha256", key).update(canonical).digest("hex").substring(0, 32);
 }
 function clamp(val, min, max) {
   if (val == null) return null;
@@ -180,8 +202,10 @@ export {
   MAX_WIDTH,
   PATH_REGEX,
   SHARP_MIME_TYPES,
+  _timingSafeEqualCallCount,
   clamp,
   computeSignature,
+  deriveSiteSecret,
   extToFormat,
   formatToMime,
   handler

package/lambda/image-lambda/node_modules/.package-lock.json

@@ -97,9 +97,9 @@
       "license": "MIT"
     },
     "node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
+      "version": "7.8.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.1.tgz",
+      "integrity": "sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"

package/lambda/image-lambda/node_modules/semver/classes/range.js

@@ -98,6 +98,9 @@ class Range {
   }
 
   parseRange (range) {
+    // strip build metadata so it can't bleed into the version
+    range = range.replace(BUILDSTRIPRE, '')
+
     // memoize range parsing for performance.
     // this is a very hot path, and fully deterministic.
     const memoOpts =
@@ -223,6 +226,7 @@ const debug = require('../internal/debug')
 const SemVer = require('./semver')
 const {
   safeRe: re,
+  src,
   t,
   comparatorTrimReplace,
   tildeTrimReplace,
@@ -230,6 +234,9 @@ const {
 } = require('../internal/re')
 const { FLAG_INCLUDE_PRERELEASE, FLAG_LOOSE } = require('../internal/constants')
 
+// unbounded global build-metadata stripper used by parseRange
+const BUILDSTRIPRE = new RegExp(src[t.BUILD], 'g')
+
 const isNullSet = c => c.value === '<0.0.0-0'
 const isAny = c => c.value === ''
 

package/lambda/image-lambda/node_modules/semver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semver",
-  "version": "7.8.0",
+  "version": "7.8.1",
   "description": "The semantic version parser used by npm.",
   "main": "index.js",
   "scripts": {

package/lambda/image-lambda/node_modules/semver/ranges/subset.js

@@ -174,7 +174,7 @@ const simpleSubset = (sub, dom, options) => {
         if (higher === c && higher !== gt) {
           return false
         }
-      } else if (gt.operator === '>=' && !satisfies(gt.semver, String(c), options)) {
+      } else if (gt.operator === '>=' && !c.test(gt.semver)) {
         return false
       }
     }
@@ -192,7 +192,7 @@ const simpleSubset = (sub, dom, options) => {
         if (lower === c && lower !== lt) {
           return false
         }
-      } else if (lt.operator === '<=' && !satisfies(lt.semver, String(c), options)) {
+      } else if (lt.operator === '<=' && !c.test(lt.semver)) {
         return false
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "headroom-cms",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Headroom CMS — Serverless headless CMS for AWS, deployed with SST",
   "type": "module",
   "main": "dist/index.js",

package/src/admin-site.ts

@@ -55,7 +55,18 @@ export function createAdminSite(name: string, args: AdminSiteArgs) {
     : undefined;
 
   if (args.dev) {
-    // Dev mode: standard StaticSite with Vite build
+    // Dev mode: standard StaticSite with Vite build.
+    //
+    // VITE_ADMIN_URL is set from the configured custom domain when present
+    // (we know it before the StaticSite is constructed). Without a custom
+    // domain the admin URL is only known *after* the StaticSite resolves —
+    // which would be circular at the `environment` map. In that case we
+    // leave VITE_ADMIN_URL empty; the discovery doc emits adminUrl: "" and
+    // the CLI tolerates the empty value. See:
+    //   steering/CLI_BOOSTRAP_DESIGN.md §1.2 (env-injection circularity)
+    const viteAdminUrl = args.domain
+      ? `https://${args.domain.name}`
+      : "";
     const site = new sst.aws.StaticSite(`${name}Admin`, {
       path: args.dev.adminPath,
       dev: {
@@ -73,6 +84,7 @@ export function createAdminSite(name: string, args: AdminSiteArgs) {
         VITE_AWS_REGION: aws.getRegionOutput().name,
         VITE_COLLAB_WS_URL: collab.wsUrl,
         VITE_COLLAB_ENABLED: collabEnabledStr,
+        VITE_ADMIN_URL: viteAdminUrl,
       },
       domain: domainConfig,
     });
@@ -90,10 +102,22 @@ export function createAdminSite(name: string, args: AdminSiteArgs) {
   fs.mkdirSync(workDir, { recursive: true });
   fs.cpSync(adminSrc, workDir, { recursive: true });
 
+  // Compute the admin URL for placeholder substitution. When a custom domain
+  // is configured, use it directly; otherwise fall back to the CloudFront-
+  // distribution URL the StaticSite resolves to. Using `$interpolate` keeps
+  // the value as an SST Output until deploy time, where it's safely inlined
+  // into the node script via the existing $-interpolated template.
+  const adminUrlForSubstitution = args.domain
+    ? `https://${args.domain.name}`
+    : "";
   const site = new sst.aws.StaticSite(`${name}Admin`, {
     path: workDir,
     build: {
-      // Replace placeholder env vars in the pre-built JS/HTML files
+      // Replace placeholder env vars in the pre-built JS/HTML/discovery files.
+      //
+      // The walk filter intentionally only matches the exact path
+      // `.well-known/headroom.json` (not any *.json) so we don't touch
+      // manifest.webmanifest, asset manifests, or other runtime JSON files.
       command: $interpolate`node -e "
         const fs = require('fs');
         const path = require('path');
@@ -105,12 +129,18 @@ export function createAdminSite(name: string, args: AdminSiteArgs) {
           '__HEADROOM_AWS_REGION__': '${aws.getRegionOutput().name}',
           '__HEADROOM_COLLAB_WS_URL__': '${collab.wsUrl}',
           '__HEADROOM_COLLAB_ENABLED__': '${collabEnabledStr}',
+          '__HEADROOM_ADMIN_URL__': '${adminUrlForSubstitution}',
         };
+        const discoveryFile = path.join('.well-known', 'headroom.json');
         function walk(d) {
           for (const f of fs.readdirSync(d)) {
             const full = path.join(d, f);
             if (fs.statSync(full).isDirectory()) walk(full);
-            else if (f.endsWith('.js') || f.endsWith('.html')) {
+            else {
+              const isSubstitutable = f.endsWith('.js')
+                || f.endsWith('.html')
+                || full.endsWith(discoveryFile);
+              if (!isSubstitutable) continue;
               let content = fs.readFileSync(full, 'utf8');
               for (const [k, v] of Object.entries(replacements)) {
                 content = content.replaceAll(k, v);
@@ -120,6 +150,19 @@ export function createAdminSite(name: string, args: AdminSiteArgs) {
           }
         }
         walk('.');
+        // Regression guard: the discovery doc must have all placeholders
+        // substituted by now. A surviving __HEADROOM_*__ would indicate a
+        // mismatch between the Vite-emitted file and the replacements map.
+        try {
+          const body = fs.readFileSync(discoveryFile, 'utf8');
+          if (/__HEADROOM_[A-Z_]+__/.test(body)) {
+            console.error('headroom: unsubstituted placeholders survive in ' + discoveryFile);
+            console.error(body);
+            process.exit(1);
+          }
+        } catch (e) {
+          if (e && e.code !== 'ENOENT') throw e;
+        }
       "`,
       output: ".",
     },

package/src/api.ts

@@ -6,16 +6,40 @@
  */
 
 import path from "path";
+import { execSync } from "child_process";
 import type { StorageResources } from "./storage.js";
 import type { AuthResources } from "./auth.js";
 import type { WebhookResources } from "./webhooks.js";
+import type { BackupResources } from "./backup.js";
 import type { ImageResources } from "./image.js";
 import type { CollabTableResources } from "./collaboration.js";
 
+/**
+ * Capture the deploying commit SHA so the API can self-report which build is
+ * running. Read at infra-eval time (once per `sst deploy` / `sst dev`) and
+ * baked into the Lambda's env. Falls back to "unknown" outside a git repo —
+ * never throws, since failing the deploy over a missing SHA would be hostile.
+ */
+function captureGitSha(): string {
+  // Allow CI to inject a specific SHA — useful when builds happen on a
+  // detached checkout where `git rev-parse HEAD` returns the wrong value.
+  const fromEnv = process.env.HEADROOM_GIT_SHA;
+  if (fromEnv) return fromEnv.trim();
+  try {
+    return execSync("git rev-parse HEAD", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+
 export interface ApiArgs {
   storage: StorageResources;
   auth: AuthResources;
   webhooks: WebhookResources;
+  backup: BackupResources;
   image: ImageResources;
   /**
    * Just the collab DynamoDB table — the API Lambda only links the table
@@ -32,7 +56,7 @@ export interface ApiArgs {
 }
 
 export function createApi(name: string, args: ApiArgs) {
-  const { storage, auth, webhooks, image, collab } = args;
+  const { storage, auth, webhooks, backup, image, collab } = args;
 
   const handlerConfig = args.dev
     ? {
@@ -68,8 +92,17 @@ export function createApi(name: string, args: ApiArgs) {
       AWS_REGION_NAME: aws.getRegionOutput().name,
       WEBHOOKS_TABLE: webhooks.webhooks.name,
       WEBHOOK_DELIVERIES_TABLE: webhooks.webhookDeliveries.name,
-      WEBHOOK_QUEUE_URL: webhooks.webhookDeliveryQueue.url,
-      IMAGE_SIGNING_SECRET: image.imageSigningSecret.value,
+      WEBHOOK_WORKER_FUNCTION_NAME: webhooks.webhookWorker.name,
+      // Backup admin endpoints (Phases 3+4): the API Lambda async-invokes
+      // the backup worker and serves list/presign/delete from the backup
+      // bucket directly. Both env vars must be present for /v1/admin/...
+      // backup endpoints to function; unset = 503 from the service layer.
+      BACKUP_BUCKET: storage.backupBucket.name,
+      BACKUP_WORKER_FUNCTION_NAME: backup.backupWorker.name,
+      // The Go API only signs with the primary master and derives the
+      // per-site key per request. It never receives the OLD master —
+      // only the Sharp Lambda's verifier needs it.
+      IMAGE_SIGNING_MASTER_SECRET: image.imageSigningMasterSecret.value,
       IMAGE_LAMBDA_NAME: image.imageLambda.name,
       RELATIONSHIPS_TABLE: storage.relationships.name,
       SITE_USERS_TABLE: storage.siteUsers.name,
@@ -79,6 +112,9 @@ export function createApi(name: string, args: ApiArgs) {
       // `X-Headroom-Internal` against this on internal service calls
       // (collab → draft snapshot). See packages/api/internal/middleware/jwt.go.
       INTERNAL_SECRET: storage.internalSecret.value,
+      // Commit SHA of the source tree at infra-eval time. Surfaced on
+      // /health so operators can map deploys → commits without tagging.
+      GIT_SHA: captureGitSha(),
     },
     link: [
       storage.sites,
@@ -92,12 +128,16 @@ export function createApi(name: string, args: ApiArgs) {
       storage.contentBucket,
       webhooks.webhooks,
       webhooks.webhookDeliveries,
-      webhooks.webhookDeliveryQueue,
-      image.imageSigningSecret,
+      image.imageSigningMasterSecret,
       storage.relationships,
       storage.siteUsers,
       collab.collabTable,
       storage.internalSecret,
+      // Backup bucket — admin endpoints list/presign-get/delete here. The
+      // worker writes here (already linked via backup.ts); the API only
+      // needs read + delete + presign-get + list-bucket, which are all
+      // covered by the SST `link` IAM grant for the bucket.
+      storage.backupBucket,
     ],
     permissions: [
       {
@@ -123,6 +163,19 @@ export function createApi(name: string, args: ApiArgs) {
         actions: ["lambda:InvokeFunction"],
         resources: [image.imageLambda.arn],
       },
+      {
+        // Async invoke of the webhook worker. Replaces the old SQS
+        // SendMessage permission that was previously auto-derived from
+        // linking the queue.
+        actions: ["lambda:InvokeFunction"],
+        resources: [webhooks.webhookWorker.arn],
+      },
+      {
+        // Async invoke of the backup worker — admin endpoints for trigger
+        // backup / restore call lambda:Invoke with InvocationType=Event.
+        actions: ["lambda:InvokeFunction"],
+        resources: [backup.backupWorker.arn],
+      },
       {
         actions: ["ses:SendEmail", "ses:SendRawEmail"],
         resources: ["*"],

package/src/backup.ts

@@ -0,0 +1,114 @@
+/**
+ * Backup Infrastructure
+ *
+ * A single Go Lambda that handles both backup export and restore import.
+ * The API service invokes it synchronously via lambda:InvokeFunction for the
+ * "scheduled" entry point this will gain a daily EventBridge cron (Phase 4).
+ *
+ * The Lambda links every site-scoped table plus the content + backup buckets.
+ * Deliberately NOT linked: Collab, collabStateBucket, SchedulerLock,
+ * WebhookDeliveries — these are transient / operational and excluded from
+ * backup payloads (see steering doc "What's in scope vs. out of scope").
+ */
+
+import path from "path";
+import type { StorageResources } from "./storage.js";
+import type { WebhookResources } from "./webhooks.js";
+
+export interface BackupArgs {
+  storage: StorageResources;
+  webhooks: WebhookResources;
+  pkgRoot: string;
+  dev?: {
+    /** Go source path, e.g. "packages/backup-worker" */
+    handler: string;
+  };
+}
+
+export function createBackup(name: string, args: BackupArgs) {
+  const { storage, webhooks } = args;
+
+  const workerConfig = args.dev
+    ? {
+        handler: args.dev.handler,
+        runtime: "go" as const,
+      }
+    : {
+        bundle: path.join(args.pkgRoot, "lambda/backup-worker"),
+        handler: "bootstrap",
+        runtime: "provided.al2023" as const,
+        architecture: "arm64" as const,
+      };
+
+  const backupWorker = new sst.aws.Function(`${name}BackupWorker`, {
+    ...workerConfig,
+    // 15-minute Lambda budget. Large sites with many media files may bump up
+    // against this; see Deferred "Step Functions for very large sites" for
+    // the escape hatch.
+    timeout: "15 minutes",
+    // Higher than default — the worker holds tar/gzip pipes, an in-memory
+    // 25-row BatchWriteItem buffer, and parallel S3 GetObject buffers.
+    memory: "1024 MB",
+    environment: {
+      SITES_TABLE: storage.sites.name,
+      CONTENT_TABLE: storage.content.name,
+      DRAFT_CONTENT_TABLE: storage.draftContent.name,
+      BLOCKS_TABLE: storage.blocks.name,
+      MEDIA_TABLE: storage.media.name,
+      COLLECTIONS_TABLE: storage.collections.name,
+      BLOCK_TYPES_TABLE: storage.blockTypes.name,
+      ADMIN_AUDIT_TABLE: storage.adminAudit.name,
+      RELATIONSHIPS_TABLE: storage.relationships.name,
+      SITE_USERS_TABLE: storage.siteUsers.name,
+      WEBHOOKS_TABLE: webhooks.webhooks.name,
+      CONTENT_BUCKET: storage.contentBucket.name,
+      BACKUP_BUCKET: storage.backupBucket.name,
+      KVS_ARN: storage.kvs.arn,
+      AWS_REGION_NAME: aws.getRegionOutput().name,
+    },
+    link: [
+      storage.sites,
+      storage.content,
+      storage.draftContent,
+      storage.blocks,
+      storage.media,
+      storage.collections,
+      storage.blockTypes,
+      storage.adminAudit,
+      storage.relationships,
+      storage.siteUsers,
+      webhooks.webhooks,
+      storage.contentBucket,
+      storage.backupBucket,
+    ],
+    permissions: [
+      {
+        // CloudFront KVS resync on restore: re-publish API key hashes so the
+        // edge function recognizes them. Fail-loud per steering §2.1 step 18.
+        actions: [
+          "cloudfront-keyvaluestore:DescribeKeyValueStore",
+          "cloudfront-keyvaluestore:PutKey",
+          "cloudfront-keyvaluestore:DeleteKey",
+          "cloudfront-keyvaluestore:GetKey",
+        ],
+        resources: [storage.kvs.arn],
+      },
+    ],
+  });
+
+  // Phase 4 — daily EventBridge cron that invokes the worker with a
+  // "scheduled" event. The handler scans the Sites table, runs backup +
+  // retention cleanup for every site with backupSchedule.enabled. 02:00
+  // UTC is a low-traffic window for most public sites; tune in the
+  // steering doc if needed. Cost is one Lambda invocation per day per
+  // stack, regardless of site count.
+  const backupCron = new sst.aws.Cron(`${name}BackupSchedule`, {
+    schedule: "cron(0 2 * * ? *)",
+    function: backupWorker.arn,
+    event: { type: "scheduled" },
+  });
+
+  return { backupWorker, backupCron };
+}
+
+export type BackupResources = ReturnType<typeof createBackup>;

package/src/cdn-api.ts

@@ -143,23 +143,14 @@ export function createApiCdn(name: string, args: ApiCdnArgs) {
     },
   );
 
-  const versionCachePolicy = new aws.cloudfront.CachePolicy(
-    `${name}VersionCachePolicy`,
-    {
-      name: $interpolate`${$app.name}-${$app.stage}-version-cache`,
-      comment: "Short-TTL cache for /version to absorb client polling",
-      minTtl: 0,
-      defaultTtl: 2,
-      maxTtl: 2,
-      parametersInCacheKeyAndForwardedToOrigin: {
-        cookiesConfig: { cookieBehavior: "none" },
-        headersConfig: { headerBehavior: "none" },
-        queryStringsConfig: { queryStringBehavior: "none" },
-        enableAcceptEncodingBrotli: true,
-        enableAcceptEncodingGzip: true,
-      },
-    },
-  );
+  // NOTE: the old `versionCachePolicy` (custom 2-second TTL) was deleted
+  // when /version began returning the per-site image signing secret.
+  // CloudFront custom cache policies do not honor `Cache-Control: private`
+  // from the origin — the explicit TTLs would win and the response (with
+  // the secret) would be edge-cached for 2s. We now use the AWS-managed
+  // `CachingDisabled` policy below for /v1/*/version, so the origin's
+  // `Cache-Control: private, max-age=2` is what reaches the browser
+  // (short-window in-browser cache) while the edge bypasses caching.
 
   // =========================================================================
   // Origin Request Policy
@@ -321,10 +312,17 @@ export function createApiCdn(name: string, args: ApiCdnArgs) {
             },
           ],
         },
-        // Version endpoint: short-TTL cache (2s) shared across all consumers
-        // for a given site. The edge function still runs for API key
-        // validation. Placed before /v1/*/users/* and the default behavior
-        // because CloudFront evaluates path patterns in order, first match wins.
+        // Version endpoint: caching DISABLED at the edge. /version now
+        // carries a per-site image signing secret in the body, so the
+        // shared edge cache must not hold it. The origin sets
+        // `Cache-Control: private, max-age=2` so browsers may still cache
+        // for the 2-second window — that absorbs single-flight contention
+        // from the same client without exposing the secret to any other
+        // viewer.
+        //
+        // Tradeoff: origin Lambda invocations on /version are now one per
+        // client poll instead of one per 2-second edge window. The SDK
+        // polls every 10s by default, so the impact is bounded.
         //
         // NOTE: pathPattern "/v1/*/version" matches exact "/version" only.
         // CloudFront's `*` wildcard does not span path segments, so any
@@ -336,7 +334,7 @@ export function createApiCdn(name: string, args: ApiCdnArgs) {
           allowedMethods: ["GET", "HEAD", "OPTIONS"],
           cachedMethods: ["GET", "HEAD", "OPTIONS"],
           compress: true,
-          cachePolicyId: versionCachePolicy.id,
+          cachePolicyId: cachingDisabledPolicyId,
           originRequestPolicyId: originRequestPolicy.id,
           functionAssociations: [
             {