diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 1c61d8b..bca742a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,6 +18,7 @@ jobs: - run: tofu init -backend=false -input=false - run: tofu fmt -check -recursive - run: tofu validate + - run: python3 ../../scripts/check-publication-order.py - run: tofu test verify: runs-on: ubuntu-24.04 diff --git a/docs/helix/02-design/architecture.md b/docs/helix/02-design/architecture.md index dfb6c89..1c5e898 100644 --- a/docs/helix/02-design/architecture.md +++ b/docs/helix/02-design/architecture.md @@ -81,6 +81,15 @@ publish static content. Its summary is desired configuration, not a cloud-state diff; an initial infrastructure plan and live protection checks remain required. The consumer's existing static build/sign/upload pipeline owns content releases. +For a new Cloudflare publication, the empty Pages project precedes Access: +Cloudflare requires that project before accepting its pages.dev destinations. +The domain still waits for Access, and DNS waits for the domain. Content upload +must wait for verified admission across custom, production and preview hosts; +resource ordering alone does not gate an independently running content pipeline. +`python3 scripts/check-publication-order.py` checks the actual provider graph. +Consumers may vendor the sibling modules inside their root for reviewed, +self-contained read-only plans; the reusable code stays owned by Concourse. + Databricks Apps/Batten is an additional required hosting profile, with separate backend and volume publication plugins. Cloudflare tooling does not establish that profile's identity, storage or proxy guarantees and is not a portable diff --git a/docs/helix/02-design/contracts/CONTRACT-001-first-slices.md b/docs/helix/02-design/contracts/CONTRACT-001-first-slices.md index 1f0ce32..e3089fe 100644 --- a/docs/helix/02-design/contracts/CONTRACT-001-first-slices.md +++ b/docs/helix/02-design/contracts/CONTRACT-001-first-slices.md @@ -77,6 +77,12 @@ pages_project, hostname, zone_id, allowed_idps, allowed_email_domains, allowed_emails, session_duration (default 24h). Outputs: access_application_id, audience, hostname. It MUST cover Pages production, wildcard previews and custom hostname before DNS/domain activation. Empty identity/policy lists are invalid. +For new projects, creation precedes Access because Cloudflare requires the +Pages destination to exist. The project MUST remain empty until Access is +active and production/preview admission has been verified. Project creation +alone MUST NOT trigger a protected content upload. The domain depends on Access, +and DNS depends on the domain. Existing projects require the same admission +checks before further private uploads; this module cannot undo prior exposure. The consumer supplies site-specific values; shared source MUST have no site-name branches. Moved blocks preserve existing resource identities during adoption. diff --git a/docs/helix/05-deploy/first-slices.md b/docs/helix/05-deploy/first-slices.md index a216953..23ea413 100644 --- a/docs/helix/05-deploy/first-slices.md +++ b/docs/helix/05-deploy/first-slices.md @@ -37,6 +37,12 @@ New empty Pages origins can exist before upload; do not upload private bytes until the production, wildcard-preview and custom origins are protected. A successful plan/apply is not proof of admission behavior. +The project is intentionally created before Access: Cloudflare rejects its +pages.dev destinations until the project exists. Wait for Access and admission +checks before the first content deployment. The custom-domain and DNS resources +remain ordered after Access. Consumers may vendor both sibling modules beneath +the root they stage for planning; retain provenance and review each local update. + ## 2. Keep one explicit installation profile Copy `deploy/cloudflare/profile.example.json` to an installation file, such as diff --git a/infra/cloudflare/README.md b/infra/cloudflare/README.md index 94c1bbe..d441ccf 100644 --- a/infra/cloudflare/README.md +++ b/infra/cloudflare/README.md @@ -30,6 +30,12 @@ configuration. Replace the source ref with a reviewed immutable commit. No provider or backend configuration is embedded. Use the consuming repository's Cloudflare v5 provider and its normal credentials and saved-plan/apply process. +Alternatively, vendor both `infra/cloudflare` and its sibling +`infra/protected-publication` beneath the consuming root, preserving their +relative layout. Record the reviewed upstream commit and review each update. +This works with plan runners that stage only the root directory and avoids +fetching external module code during apply. + The default protects the entire site, including production and wildcard preview Pages origins. `access_path = "/__concourse"` deliberately leaves static content public and protects collaboration only. Do not use it for private publications. diff --git a/infra/protected-publication/README.md b/infra/protected-publication/README.md index 667cca0..a04daeb 100644 --- a/infra/protected-publication/README.md +++ b/infra/protected-publication/README.md @@ -1,7 +1,12 @@ # Protected publication module Generic Cloudflare v5 Pages custom-domain, DNS and Access composition. The Pages -project may already exist or be created with `create_project = true`. Infrastructure owns this module's deployment; content +project may already exist or be created with `create_project = true`. A new +project must exist before Access can reference its `pages.dev` destinations. +Keep that project empty until Access is active and admission checks pass; do +not start a content upload just because project creation succeeded. The custom +domain waits for Access and DNS waits for the custom domain. +Infrastructure owns this module's deployment; content pipelines upload build output. No caller-specific defaults, cloud credentials, provider registration or deployment is embedded. @@ -19,6 +24,13 @@ custom/Pages/preview hosts and representative asset/index/download routes. Pin the module source to an immutable Concourse revision. Do not use a developer checkout path in production infrastructure. +Consumers that require reviewed vendored code may copy both sibling directories +`infra/cloudflare` and `infra/protected-publication` beneath their root module. +Preserve their relative layout and record the reviewed source commit and local +changes. Keeping the copy inside the root also supports read-only plan runners +that stage only that directory. Review module updates as infrastructure code; +do not fetch or update them implicitly during an apply. + For a complete collaboration foundation including D1, prefer the small [`infra/cloudflare`](../cloudflare/README.md) wrapper and its Wrangler release profile. This lower-level module remains useful for publication-only adoption. diff --git a/infra/protected-publication/main.tf b/infra/protected-publication/main.tf index 4634949..bc17635 100644 --- a/infra/protected-publication/main.tf +++ b/infra/protected-publication/main.tf @@ -31,13 +31,16 @@ resource "cloudflare_zero_trust_access_application" "site" { error_message = "An explicit nonempty publication membership policy is required." } } + # Cloudflare rejects a pages.dev destination if its project does not exist. + # Keep new projects empty until Access is active and admission is verified; + # the content pipeline must not upload protected bytes during bootstrap. + depends_on = [cloudflare_pages_project.site] } resource "cloudflare_pages_project" "site" { count = var.create_project ? 1 : 0 account_id = var.account_id name = var.pages_project production_branch = "main" - depends_on = [cloudflare_zero_trust_access_application.site] } resource "cloudflare_pages_domain" "site" { account_id = var.account_id diff --git a/scripts/check-publication-order.py b/scripts/check-publication-order.py new file mode 100644 index 0000000..f11e21d --- /dev/null +++ b/scripts/check-publication-order.py @@ -0,0 +1,22 @@ +"""Verify bootstrap ordering in OpenTofu's actual local dependency graph.""" +from pathlib import Path +import subprocess + +root = Path(__file__).resolve().parents[1] +graph = subprocess.check_output( + ["tofu", "graph", "-type=plan"], cwd=root / "infra/cloudflare", text=True +) +resources = [ + "cloudflare_dns_record.site", + "cloudflare_pages_domain.site", + "cloudflare_zero_trust_access_application.site", + "cloudflare_pages_project.site", +] +for dependent, prerequisite in zip(resources, resources[1:]): + edge = ( + f'"[root] module.publication.{dependent} (expand)" -> ' + f'"[root] module.publication.{prerequisite} (expand)"' + ) + if edge not in graph: + raise SystemExit(f"Missing publication dependency: {dependent} -> {prerequisite}") +print("Publication graph verified: empty project -> Access -> domain -> DNS") diff --git a/tests/protection.test.ts b/tests/protection.test.ts index c6a518f..ea948c4 100644 --- a/tests/protection.test.ts +++ b/tests/protection.test.ts @@ -14,7 +14,7 @@ test('challenge requires an actual Access HTTPS login host, not a substring @cov test('generic protection covers origin wildcard and custom domain with no incumbent names @covers US-001-AC2', async () => { const source = await Bun.file('infra/protected-publication/main.tf').text(); expect(source).toContain('*.${var.pages_project}.pages.dev'); expect(source).toContain('${var.hostname}'); - expect(source).toMatch(/depends_on\s*=\s*\[cloudflare_zero_trust_access_application.site\]/); + expect(source).toMatch(/depends_on\s*=\s*\[cloudflare_zero_trust_access_application.site, cloudflare_pages_project.site\]/); expect(source.toLowerCase()).not.toMatch(/entropy|synaptiq|playbooks/); }); test('module boundary gate rejects a real forbidden import negative control', async () => {