create-headroom 0.1.10 → 0.2.0

package/dist/index.js

@@ -80,7 +80,11 @@ async function main() {
 
   Next steps:
     cd ${projectName}
-    ./scripts/setup.sh <stage>  # First-time setup (sets secrets + deploys)
+    ./scripts/setup.sh <stage>  # First-time setup: sets the three SST secrets
+                                # (image-signing master + rotation fallback +
+                                # internal service-to-service) and deploys.
+                                # Re-running is idempotent — already-set
+                                # secrets are left alone.
 
   For subsequent deploys:
     npx sst deploy --stage <stage>
@@ -88,6 +92,10 @@ async function main() {
   After deploying, create your first admin user:
     ./scripts/create-admin.sh admin@example.com 'YourPassword123!'
 
+  To rotate the image-signing master (preserving the grace window for
+  already-signed URLs):
+    ./scripts/setup.sh <stage> --force-rotate
+
   Documentation: https://github.com/cykod/headroom
 `);
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-headroom",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Create a new Headroom CMS project",
   "type": "module",
   "bin": {

package/template/README.md

@@ -0,0 +1,74 @@
+# Headroom CMS Deployment
+
+This project deploys a Headroom CMS instance to AWS via SST.
+
+## First-time setup
+
+```bash
+./scripts/setup.sh <stage>
+```
+
+This generates the three SST secrets required by the stack and then runs
+`npx sst deploy`. Re-running the script is idempotent: already-set secrets
+are left alone.
+
+### Required SST secrets
+
+The instance name `CMS` (the first argument to `new HeadroomCMS(...)` in
+`sst.config.ts`) is prepended to each secret name. If you change that
+instance name, also update `INSTANCE` at the top of `scripts/setup.sh`.
+
+| Secret | Required? | What breaks if missing |
+|--------|-----------|------------------------|
+| `CMSImageSigningMasterSecret` | **Yes** | All `/img/*` image-transform requests return 403. Per-site signing keys are derived from this master via HMAC-SHA256. |
+| `CMSImageSigningMasterSecretOld` | Optional (set to empty by default) | Rotation fallback. The Sharp Lambda accepts URLs signed with either master, so populating this lets you rotate the primary without invalidating already-issued URLs. Empty disables the fallback path. |
+| `CMSInternalSecret` | **Yes** (if collaboration is enabled) | The collaboration Lambda's calls to the Go API (via the `X-Headroom-Internal` header) are rejected, breaking real-time editing. |
+
+## Rotating the image signing master
+
+To rotate while preserving signed URLs that may still be in CDN / browser
+caches:
+
+```bash
+./scripts/setup.sh <stage> --force-rotate
+```
+
+This moves the current `CMSImageSigningMasterSecret` value to
+`CMSImageSigningMasterSecretOld`, generates a new primary, and redeploys.
+`CMSInternalSecret` is **not** rotated by this flag — it has no OLD-fallback
+pair and rotating it would reject every in-flight collab Lambda → Go API
+request until the new deploy completes.
+
+Manual equivalent:
+
+```bash
+npx sst secret set CMSImageSigningMasterSecretOld <current-value> --stage <stage>
+npx sst secret set CMSImageSigningMasterSecret    <new-value>    --stage <stage>
+npx sst deploy --stage <stage>
+```
+
+See the root project's `CLAUDE.md` "Rotating the image signing master"
+section for guidance on how long to leave `MasterSecretOld` populated.
+
+## Rotating the internal secret
+
+`CMSInternalSecret` has no rotation grace window — rotating it causes a
+brief collab outage until the next deploy completes. Plan a deploy window,
+then rotate manually:
+
+```bash
+npx sst secret set CMSInternalSecret "$(openssl rand -hex 32)" --stage <stage>
+npx sst deploy --stage <stage>
+```
+
+## Subsequent deploys
+
+```bash
+npx sst deploy --stage <stage>
+```
+
+## Creating an admin user
+
+```bash
+./scripts/create-admin.sh admin@example.com 'YourPassword123!'
+```

package/template/package.json

@@ -9,7 +9,7 @@
     "remove": "sst remove"
   },
   "dependencies": {
-    "headroom-cms": "^0.1.10"
+    "headroom-cms": "^0.2.0"
   },
   "devDependencies": {
     "sst": "^3.17.0",

package/template/scripts/setup.sh

@@ -1,37 +1,209 @@
 #!/bin/bash
 # First-time setup for a Headroom CMS deployment stage.
 #
-# Generates and sets required secrets, then deploys.
+# Sets the three SST secrets required by Headroom and then deploys.
+#
+# The instance name (INSTANCE below) MUST match the first argument passed
+# to `new HeadroomCMS(...)` in sst.config.ts — the secret resources are
+# named `${INSTANCE}ImageSigningMasterSecret`, etc.
+#
+# Secrets set:
+#   1. ${INSTANCE}ImageSigningMasterSecret      — REQUIRED. Master KDF input
+#      used to derive per-site image signing keys. Without it, every
+#      /img/* request 403s.
+#   2. ${INSTANCE}ImageSigningMasterSecretOld   — OPTIONAL fallback master,
+#      initialised empty. The Sharp Lambda accepts URLs signed with either
+#      master, so populating this lets you rotate the primary without
+#      invalidating already-issued URLs.
+#   3. ${INSTANCE}InternalSecret                — REQUIRED for collaboration.
+#      Shared secret on the X-Headroom-Internal header between the collab
+#      Lambda and the Go API.
+#
+# Idempotency: re-running the script does NOT overwrite already-set
+# secrets. Pass --force-rotate to rotate the image-signing master only
+# (moves the current value to MasterSecretOld before generating a new
+# primary, preserving the rotation grace window for in-the-wild signed
+# URLs). InternalSecret rotation is NOT covered by --force-rotate — it
+# has no OLD-fallback and rotating it breaks in-flight collab connections
+# without grace. Rotate InternalSecret manually if needed:
+#   npx sst secret set CMSInternalSecret <new-value> --stage <stage>
 #
 # Usage:
 #   ./scripts/setup.sh <stage>
+#   ./scripts/setup.sh <stage> --force-rotate
 #
 # Example:
 #   ./scripts/setup.sh production
 
 set -euo pipefail
 
-STAGE="${1:-}"
+INSTANCE="CMS"   # Must match the instance name in sst.config.ts
+
+FORCE_ROTATE=0
+STAGE=""
+for arg in "$@"; do
+  case "$arg" in
+    --force-rotate|--rotate)
+      FORCE_ROTATE=1
+      ;;
+    -*)
+      echo "Unknown flag: $arg" >&2
+      echo "Usage: $0 <stage> [--force-rotate]" >&2
+      exit 1
+      ;;
+    *)
+      if [ -z "$STAGE" ]; then
+        STAGE="$arg"
+      else
+        echo "Unexpected positional argument: $arg" >&2
+        echo "Usage: $0 <stage> [--force-rotate]" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
 
 if [ -z "$STAGE" ]; then
-  echo "Usage: $0 <stage>" >&2
+  echo "Usage: $0 <stage> [--force-rotate]" >&2
   echo "" >&2
   echo "Run this once per stage before your first deploy." >&2
   echo "Example: $0 production" >&2
   exit 1
 fi
 
+# Sanity-check: INSTANCE here must match `new HeadroomCMS("...", ...)` in
+# sst.config.ts. If they disagree, the script would set secrets under the
+# wrong name and the deploy would fail at apply time with an opaque "secret
+# not set" error. Catch the mismatch up front with a helpful message.
+if [ -f sst.config.ts ]; then
+  ACTUAL_INSTANCE=$(grep -oE 'new HeadroomCMS\("[^"]+"' sst.config.ts | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || true)
+  if [ -n "$ACTUAL_INSTANCE" ] && [ "$ACTUAL_INSTANCE" != "$INSTANCE" ]; then
+    echo "ERROR: sst.config.ts uses 'new HeadroomCMS(\"$ACTUAL_INSTANCE\", ...)' but INSTANCE=\"$INSTANCE\" in this script." >&2
+    echo "  Edit the INSTANCE= line at the top of this script to match \"$ACTUAL_INSTANCE\"." >&2
+    echo "  (Or rename the instance in sst.config.ts back to \"$INSTANCE\".)" >&2
+    exit 1
+  fi
+fi
+
 echo "==> Setting up stage: $STAGE"
+if [ "$FORCE_ROTATE" -eq 1 ]; then
+  echo "    (--force-rotate: image-signing master will be rotated)"
+fi
+
+# secret_get <name> — print the current value of an SST secret to stdout, or
+# empty string if the secret has never been set.
+#
+# This must distinguish two failure modes:
+#   (A) secret unset → expected on first run; treat as empty result.
+#   (B) any other SST/AWS failure (wrong stage, missing creds, transient
+#       error, etc.) → hard-fail. We MUST NOT proceed: a silent failure
+#       here on a real stage would regenerate the image-signing master
+#       and destroy every signed /img/* URL in the wild.
+#
+# SST exits non-zero with a "not set" / "not found" / "does not exist"
+# message on (A); other failures produce different stderr. We match
+# substrings as a defensible-but-imperfect proxy for distinct exit codes
+# (SST does not document distinct codes per failure class).
+secret_get() {
+  local name="$1"
+  local err_file out
+  err_file=$(mktemp 2>/dev/null || echo "/tmp/setup-sst-err.$$")
+  if out=$(npx sst secret get "$name" --stage "$STAGE" 2>"$err_file"); then
+    rm -f "$err_file"
+    printf '%s' "$out"
+    return 0
+  fi
+  # Non-zero exit. Classify.
+  local err
+  err=$(cat "$err_file" 2>/dev/null || true)
+  rm -f "$err_file"
+  if echo "$err" | grep -qiE "(not (set|found)|does not exist|no such secret)"; then
+    # (A) Secret has never been set — return empty stdout, exit 0.
+    return 0
+  fi
+  # (B) Anything else — surface and abort. Refusing to proceed prevents
+  # destroying production secrets when the user typed the wrong --stage
+  # or AWS credentials have expired.
+  echo "ERROR: querying ${name} (stage=${STAGE}) failed:" >&2
+  if [ -n "$err" ]; then
+    echo "$err" | sed 's/^/  /' >&2
+  fi
+  echo "" >&2
+  echo "  Refusing to proceed — re-run with the correct --stage, or fix" >&2
+  echo "  AWS credentials. If you believe this is a transient SST error," >&2
+  echo "  re-run the script." >&2
+  exit 1
+}
+
+# 1. Image signing master (REQUIRED)
+EXISTING_MASTER=$(secret_get "${INSTANCE}ImageSigningMasterSecret")
+if [ "$FORCE_ROTATE" -eq 1 ]; then
+  if [ -n "$EXISTING_MASTER" ]; then
+    echo "==> Rotating ${INSTANCE}ImageSigningMasterSecret — moving current value to ${INSTANCE}ImageSigningMasterSecretOld"
+    npx sst secret set "${INSTANCE}ImageSigningMasterSecretOld" "$EXISTING_MASTER" --stage "$STAGE"
+  fi
+  SECRET=$(openssl rand -hex 32)
+  echo "==> Setting new ${INSTANCE}ImageSigningMasterSecret..."
+  npx sst secret set "${INSTANCE}ImageSigningMasterSecret" "$SECRET" --stage "$STAGE"
+elif [ -n "$EXISTING_MASTER" ]; then
+  echo "==> ${INSTANCE}ImageSigningMasterSecret already set, leaving alone (pass --force-rotate to rotate)"
+else
+  SECRET=$(openssl rand -hex 32)
+  echo "==> Setting ${INSTANCE}ImageSigningMasterSecret..."
+  npx sst secret set "${INSTANCE}ImageSigningMasterSecret" "$SECRET" --stage "$STAGE"
+fi
 
-# Generate a random image signing secret
-SECRET=$(openssl rand -hex 32)
-echo "==> Setting HeadroomImageSigningSecret..."
-npx sst secret set HeadroomImageSigningSecret "$SECRET" --stage "$STAGE"
+# 2. Image signing master OLD (rotation fallback; empty disables it)
+#
+# We always touch this secret on first setup so the resource exists in SST
+# state — that way the eventual rotation step ("move current to OLD before
+# setting a new primary") is a single command rather than a create-or-update
+# branch. Force-rotate above may have populated it with the previous master;
+# only initialize to empty if no prior value (and no rotation) set it.
+if [ "$FORCE_ROTATE" -eq 0 ]; then
+  EXISTING_OLD=$(secret_get "${INSTANCE}ImageSigningMasterSecretOld")
+  # `sst secret get` returns empty for both "never set" and "set to empty
+  # string". That's fine — setting it to empty again is a no-op-ish call
+  # that ensures the resource exists. We only call it when nothing else
+  # has populated it in this run.
+  if [ -z "$EXISTING_OLD" ]; then
+    echo "==> Initializing ${INSTANCE}ImageSigningMasterSecretOld (empty)..."
+    npx sst secret set "${INSTANCE}ImageSigningMasterSecretOld" "" --stage "$STAGE"
+  else
+    echo "==> ${INSTANCE}ImageSigningMasterSecretOld already set, leaving alone"
+  fi
+fi
+
+# 3. Internal service-to-service secret (REQUIRED if collab is enabled)
+#
+# NOT rotated by --force-rotate: it has no OLD-fallback pair, so rotating
+# it would reject every in-flight collab Lambda → Go API request with 401
+# until the new deploy completes. Rotate manually only when you can tolerate
+# a brief collab outage:
+#   npx sst secret set ${INSTANCE}InternalSecret <new> --stage <stage>
+EXISTING_INTERNAL=$(secret_get "${INSTANCE}InternalSecret")
+if [ -z "$EXISTING_INTERNAL" ]; then
+  INTERNAL=$(openssl rand -hex 32)
+  echo "==> Setting ${INSTANCE}InternalSecret..."
+  npx sst secret set "${INSTANCE}InternalSecret" "$INTERNAL" --stage "$STAGE"
+else
+  echo "==> ${INSTANCE}InternalSecret already set, leaving alone"
+fi
 
 echo ""
 echo "==> Deploying stage: $STAGE"
 npx sst deploy --stage "$STAGE"
 
 echo ""
-echo "==> Setup complete! Next steps:"
-echo "  ./scripts/create-admin.sh admin@example.com 'YourPassword123!'"
+echo "==> Setup complete!"
+echo ""
+echo "    To rotate the image-signing master later, preserving the grace"
+echo "    window for already-issued signed URLs:"
+echo "        ./scripts/setup.sh $STAGE --force-rotate"
+echo ""
+echo "    Or manually:"
+echo "        npx sst secret set ${INSTANCE}ImageSigningMasterSecretOld <current> --stage $STAGE"
+echo "        npx sst secret set ${INSTANCE}ImageSigningMasterSecret <new> --stage $STAGE"
+echo ""
+echo "    Next: create your first admin user"
+echo "        ./scripts/create-admin.sh admin@example.com 'YourPassword123!'"