@decocms/start 2.30.0 → 2.30.1

package/.agents/skills/deco-to-tanstack-migration/references/worker-cloudflare.md

@@ -287,6 +287,16 @@ execs the real `wrangler` with that config in cwd.
   untamperable by user code) and looked up in `deploy/sites/<repo>.jsonc`.
 - A customer cannot misroute their deploy onto another site's worker
   because they can't write to `decocms/deco-start` (CODEOWNERS-protected).
+- `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` live ONLY in
+  `decocms/deco-start`'s `production` GitHub Environment. The reusable
+  workflow declares `environment: production`, which makes
+  `${{ secrets.CLOUDFLARE_* }}` resolve from the called repo's environment
+  instead of the caller's repo secrets. Storefront repos never hold the
+  Cloudflare credential.
+- Per-site runtime secrets in storefront repos are prefixed `SECRET_*` and
+  flow into the worker via the central `sync-secrets.yml`, which inherits
+  them via `secrets: inherit`, validates names, and `wrangler secret put`s
+  them under their unprefixed name.
 
 ### Common mistakes (do not do these)
 
@@ -296,9 +306,14 @@ execs the real `wrangler` with that config in cwd.
   Add it to `deco-start/.github/workflows/deploy.yml` instead so every site
   picks it up at once.
 - **Hard-coding `account_id` in a site's wrangler config.** It comes from
-  `CLOUDFLARE_ACCOUNT_ID` (org-level GitHub secret in CI; `wrangler login`
-  locally). Removing it from JSON is the one-way protection against
-  accidentally deploying to the wrong account.
+  `CLOUDFLARE_ACCOUNT_ID` (in `decocms/deco-start`'s `production`
+  Environment in CI; `wrangler login` locally). Removing it from JSON is
+  the one-way protection against accidentally deploying to the wrong
+  account.
+- **Adding `CLOUDFLARE_*` to a storefront repo's secrets.** They belong
+  in `decocms/deco-start` only, in the `production` environment. The
+  central workflow's `environment:` binding overrides anything passed
+  from the caller, so an accidental copy on a site is dead code.
 - **Setting `worker_name` to anything other than the repo name** without
   a strong reason. The 1:1 binding makes audit (and incident response)
   trivial. Exceptions today: `casaevideo-storefront` -> `casaevideo-tanstack`

package/.cursor/rules/migration-tooling-policy.mdc

@@ -88,12 +88,26 @@ boundary: the central workflow ignores caller `inputs:` for identity and
 derives the site name from `${{ github.repository }}`. `deploy/**` is
 CODEOWNERS-protected.
 
+**Cloudflare credentials live in `decocms/deco-start` only**, in the
+`production` GitHub Environment. The reusable workflows declare
+`environment: production`, which makes `${{ secrets.CLOUDFLARE_* }}`
+resolve from the called repo (deco-start) instead of the caller. A
+storefront repo only ever holds its own `SECRET_*` runtime secrets
+(pushed to its worker by the central `sync-secrets.yml` via
+`secrets: inherit`). Two-tier secret model is the second half of the
+trust boundary — even a fully compromised storefront repo has no path
+to the Cloudflare token.
+
 **Agent behavior**: when adding or migrating a site, do **not** generate a
 per-site `wrangler.jsonc` or per-site `deploy.yml` / `preview.yml` /
 `sync-secrets.yml` / `regen-blocks.yml`. The site repo gets the four
 ~5-line caller stubs only. Per-site config goes in a PR to
 `decocms/deco-start` adding `deploy/sites/<repo>.jsonc`. Do not commit
-`wrangler.jsonc` or any wrangler config to a site repo.
+`wrangler.jsonc` or any wrangler config to a site repo. Do **not** add
+`CLOUDFLARE_*` to a storefront repo's secrets — the central workflow's
+`environment:` binding overrides anything passed from the caller, so an
+accidental copy on a site is dead code at best and a credential leak
+risk at worst.
 
 ## Priority order
 

package/.github/workflows/deploy.yml

@@ -20,14 +20,16 @@ name: deploy (central)
 #     deploy:
 #       uses: decocms/deco-start/.github/workflows/deploy.yml@v2
 #       secrets: inherit
+#
+# `secrets: inherit` is intentionally tolerated but UNUSED by the deploy job:
+# `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` resolve from the
+# `production` environment in this repo (via `environment:` below), NOT from
+# the caller. That keeps the Cloudflare credential off every storefront repo
+# entirely. The same env binding is repeated in `preview.yml` and
+# `sync-secrets.yml`.
 
 on:
-  workflow_call:
-    secrets:
-      CLOUDFLARE_API_TOKEN:
-        required: true
-      CLOUDFLARE_ACCOUNT_ID:
-        required: true
+  workflow_call: {}
 
 permissions:
   contents: write
@@ -39,6 +41,11 @@ concurrency:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    # Resolves `secrets.CLOUDFLARE_*` against the `production` environment in
+    # decocms/deco-start (NOT against the caller's repo secrets). Setup:
+    # decocms/deco-start > Settings > Environments > production >
+    # CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID.
+    environment: production
     steps:
       - name: Checkout caller repo
         uses: actions/checkout@v4

package/.github/workflows/preview.yml

@@ -20,14 +20,12 @@ name: preview (central)
 #     preview:
 #       uses: decocms/deco-start/.github/workflows/preview.yml@v2
 #       secrets: inherit
+#
+# Same secret model as deploy.yml: `CLOUDFLARE_*` resolve from this repo's
+# `production` environment, not from the caller. See deploy.yml for details.
 
 on:
-  workflow_call:
-    secrets:
-      CLOUDFLARE_API_TOKEN:
-        required: true
-      CLOUDFLARE_ACCOUNT_ID:
-        required: true
+  workflow_call: {}
 
 permissions:
   contents: read
@@ -41,6 +39,7 @@ concurrency:
 jobs:
   preview:
     runs-on: ubuntu-latest
+    environment: production
     steps:
       - name: Resolve ref
         id: resolve

package/.github/workflows/sync-secrets.yml

@@ -27,6 +27,17 @@ name: sync-secrets (central)
 #       with:
 #         mode: ${{ inputs.mode }}
 #       secrets: inherit
+#
+# Two distinct secret classes flow through this job:
+#   - `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` -> resolved from this
+#     repo's `production` environment (via `environment:` below). NEVER from
+#     the caller storefront. Same model as deploy.yml / preview.yml.
+#   - `SECRET_*` -> inherited from the caller storefront via `secrets: inherit`
+#     in the caller stub. These ARE site-owned and get pushed to the worker
+#     as runtime secrets (with the `SECRET_` prefix stripped).
+# `secrets: inherit` is therefore REQUIRED on the caller side for this
+# workflow specifically (unlike deploy.yml / preview.yml where it's just
+# tolerated).
 
 on:
   workflow_call:
@@ -36,11 +47,6 @@ on:
         required: false
         type: string
         default: "dry-run"
-    secrets:
-      CLOUDFLARE_API_TOKEN:
-        required: true
-      CLOUDFLARE_ACCOUNT_ID:
-        required: true
 
 permissions:
   contents: read
@@ -52,6 +58,7 @@ concurrency:
 jobs:
   sync:
     runs-on: ubuntu-latest
+    environment: production
     steps:
       - uses: actions/checkout@v4
 

package/MIGRATION_TOOLING_PLAN.md

@@ -118,6 +118,7 @@ this plan.
 | 2026-05-01 | **D4 — Site-local apps: local by default, promote at 3** | Site-specific apps live in `src/apps/local/` until ≥3 sites use them, then promote to `@decocms/apps`. |
 | 2026-05-01 | **D5 — Failed migrations: rm -rf and re-run** | No `--restart` mode. Half-migrated sites are throwaways. Failure modes get documented in skills, not encoded as escape hatches. |
 | 2026-05-07 | **D6 — Deploy / preview / secrets pipelines: centralize in `deco-start`** | At 6 sites the "1-minute copy" of `deploy.yml` / `preview.yml` / `wrangler.jsonc` had already produced unintended drift (lebiscuit missing 2 workflows, miess missing `account_id`, casaevideo's `loadtest:tail` worker name out of sync with its wrangler config). All sites now consume reusable workflows from `decocms/deco-start@v2` and a per-site registry under [`deploy/sites/<repo>.jsonc`](./deploy/) deep-merged on top of [`deploy/wrangler-template.jsonc`](./deploy/wrangler-template.jsonc) at deploy time. Customer repos hold only ~5-line caller workflows; `wrangler.jsonc` is generated and gitignored. The repo→worker binding is the trust boundary that prevents one site's commits from misrouting onto another site's worker (the central workflow ignores caller `inputs:` for identity and derives the site name from `${{ github.repository }}`). See [`deploy/README.md`](./deploy/README.md) for the contract. |
+| 2026-05-07 | **D6.1 — Cloudflare credentials never leave `deco-start`** | Same-day refinement of D6 after the first central deploy on `baggagio-tanstack` failed with `Secret CLOUDFLARE_API_TOKEN is required, but not provided while calling`. The original D6 design used `secrets: inherit` from the storefront stub and required `CLOUDFLARE_*` to live in the `deco-sites` org, which broke the principle that *the only secrets a storefront repo holds are the secrets that go into wrangler secrets, not the ones used to deploy*. Refinement: the central `deploy.yml` / `preview.yml` / `sync-secrets.yml` jobs declare `environment: production`, which makes `${{ secrets.CLOUDFLARE_* }}` resolve from the called repo (`decocms/deco-start`'s `production` GitHub Environment) instead of the caller's repo secrets. Storefronts now hold only their own `SECRET_*` runtime secrets; `sync-secrets` inherits those via `secrets: inherit` and pushes them as worker secrets. The trust boundary becomes two-tier: even a fully compromised storefront repo has no path to the Cloudflare credential, and even a compromised storefront cannot misroute *its own* deploy onto another site's worker because `worker_name` comes from the CODEOWNERS-protected registry, not caller input. See [`deploy/README.md`](./deploy/README.md) "Where Cloudflare credentials live" section. |
 
 The full text of the constitutional rule (loaded into every agent
 session for this repo) lives at

package/deploy/README.md

@@ -28,6 +28,29 @@ no other way to identify a site.
 `deploy/**` is CODEOWNERS-protected. Only the platform team can change site
 manifests or the template.
 
+### Where Cloudflare credentials live
+
+`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` live in **this repo's
+`production` GitHub Environment**, never in any storefront repo. The reusable
+workflows declare `environment: production` on the deploy / preview /
+sync-secrets jobs, which is what GitHub uses to resolve `secrets.CLOUDFLARE_*`
+against the called repo (deco-start) instead of the caller (the storefront).
+
+This is the second half of the trust property: even if a storefront repo were
+fully compromised, the attacker has no path to the Cloudflare token. The
+storefront repo only holds its own `SECRET_*` runtime secrets, which are
+inherited by `sync-secrets.yml` and pushed to its own worker as runtime
+secrets — never reaching another site's worker because the central workflow
+resolves `worker_name` from this registry, not from caller input.
+
+| Secret class | Lives in | Reaches worker via |
+|---|---|---|
+| `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` | this repo's `production` environment | central workflow's `environment:` binding (no caller passthrough) |
+| `SECRET_*` runtime secrets (per site) | each storefront repo | `sync-secrets.yml` inherits via `secrets: inherit` and pushes via `wrangler secret put` |
+
+To rotate the Cloudflare credentials, edit the environment in this repo only.
+No storefront PR needed.
+
 ## How wrangler.jsonc is generated
 
 At deploy time, the central workflow runs
@@ -55,8 +78,11 @@ which:
    `@v2` major tag (the major-tag advance step lives inline in
    [`.github/workflows/release.yml`](../.github/workflows/release.yml)).
 3. In the new repo, add the four caller workflows from
-   [`.github/workflows/`](../.github/workflows/) and set the org-level
-   `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` GitHub secrets.
+   [`.github/workflows/`](../.github/workflows/). **Do not** add
+   `CLOUDFLARE_*` to the storefront — those live in this repo's `production`
+   environment and reach the runner via the central workflow's `environment:`
+   binding. The storefront only needs `SECRET_*` entries for its own worker
+   runtime secrets.
 4. Push to `main` and verify the deploy lands on the right worker.
 
 ## Per-site override schema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.30.0",
+  "version": "2.30.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",