Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions docs/helix/02-design/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/helix/02-design/contracts/CONTRACT-001-first-slices.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
6 changes: 6 additions & 0 deletions docs/helix/05-deploy/first-slices.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions infra/cloudflare/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
14 changes: 13 additions & 1 deletion infra/protected-publication/README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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.
5 changes: 4 additions & 1 deletion infra/protected-publication/main.tf
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions scripts/check-publication-order.py
Original file line number Diff line number Diff line change
@@ -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")
2 changes: 1 addition & 1 deletion tests/protection.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 () => {
Expand Down
Loading