site: add Fathom analytics, and fix the caching rule it sits beside
Two changes to what the live site sends. Analytics: Fathom's tag goes in every template's <head>, deferred. It is cookieless and collects nothing about a person, so no consent banner — but it is a third party, so the CSP names cdn.usefathom.com for script and connect rather than opening the door generally, and the tests that said 'no script at all' now say 'no script this site depends on, and no origin nobody chose'. Caching: the host concatenates a header two matching rules both set rather than overriding, so /* and /static/* each setting Cache-Control sent 'max-age=0, must-revalidate, max-age=31536000, immutable' on the stylesheet — first max-age wins, and the year-long cache never happened. Measured on the live site, which is where the from-memory assumption in task 32 said to check it. Now /static/* is the only rule that sets it and HTML takes the host's revalidating default; the post-deploy checks in site/README.md verify both ends.
This commit is contained in:
+27
-12
@@ -77,6 +77,7 @@ widening the page, and that the site still ships no JavaScript.
|
||||
| Worker | `bench-site` |
|
||||
| Route | `bench.12vectors.com`, a **custom domain** — Cloudflare owns the hostname at the zone level and creates the DNS record itself |
|
||||
| Served from | `site/dist/`, uploaded whole on every deploy |
|
||||
| Analytics | [Fathom](https://usefathom.com), site `ZPKDEHCV` — cookieless, no personal data, no consent banner. The only third party the pages touch |
|
||||
| Config | `site/wrangler.jsonc` (routing) and `site/root/_headers` (caching, security) |
|
||||
|
||||
Deploys are run by hand, by a person, exactly as releases are
|
||||
@@ -129,7 +130,12 @@ answers rather than files:
|
||||
page **with a 404 status**, not the landing page with a 200.
|
||||
4. `curl -sI https://bench.12vectors.com/` shows
|
||||
`x-content-type-options`, `referrer-policy`,
|
||||
`strict-transport-security` and a `cache-control` that revalidates.
|
||||
`strict-transport-security` and a `cache-control` that revalidates —
|
||||
the last one coming from the host's default now, not from `_headers`,
|
||||
which is exactly why it is checked rather than assumed. Then
|
||||
`curl -sI https://bench.12vectors.com/static/site.css` must show
|
||||
`max-age=31536000, immutable` **once**, with no second `max-age`
|
||||
beside it.
|
||||
|
||||
## How it is served
|
||||
|
||||
@@ -141,17 +147,26 @@ answers rather than files:
|
||||
with a 404 status. That page is a normal manifest entry (`/404.html`,
|
||||
layout `notfound`) — the site's own design, its own nav, and a link
|
||||
back to the landing page.
|
||||
- **Two caching policies, because there are two kinds of file.** HTML
|
||||
revalidates on every view, so a deploy is visible on the next reload
|
||||
with nobody clearing anything. Everything under `/static/` is kept for
|
||||
a year and never re-checked, which is only safe because the stylesheet
|
||||
and the icon are linked with a `?v=<hash>` of their own contents:
|
||||
change the file and the url changes with it.
|
||||
- **Baseline headers, no third parties.** `nosniff`, a referrer policy,
|
||||
a year of HSTS, `X-Frame-Options`, and a Content-Security-Policy of
|
||||
`default-src 'none'` with `'self'` for styles, fonts and images. The
|
||||
site collects nothing and loads nothing from anywhere else; the CSP is
|
||||
that promise in a form the browser enforces.
|
||||
- **One rule sets `Cache-Control`, and it is `/static/*`.** The host
|
||||
*concatenates* a header two matching rules both set — it does not
|
||||
override, whatever the ordering suggests. Measured live: `/*` and
|
||||
`/static/*` each setting `Cache-Control` produced
|
||||
`max-age=0, must-revalidate, max-age=31536000, immutable` on the
|
||||
stylesheet, and the first `max-age` wins in every browser, so the
|
||||
year-long cache never happened. Now only `/static/*` sets it — safe
|
||||
because the stylesheet and the icon are linked with a `?v=<hash>` of
|
||||
their own contents — and HTML takes the host's own revalidating
|
||||
default, which check 4 below confirms after every deploy.
|
||||
- **Baseline headers, and one third party by choice.** `nosniff`, a
|
||||
referrer policy, a year of HSTS, `X-Frame-Options`, and a
|
||||
Content-Security-Policy of `default-src 'none'` with `'self'` for
|
||||
styles, fonts and images. The one origin named besides this one is
|
||||
`cdn.usefathom.com`: Fathom serves the analytics script and receives
|
||||
its pageviews. It sets no cookie and collects nothing about a person,
|
||||
which is why the site still needs no consent banner — but it is a
|
||||
third party, and the policy names it rather than opening the door
|
||||
generally. A second one would fail
|
||||
`tests/test_site_deploy.py` rather than slip in.
|
||||
|
||||
## What is where
|
||||
|
||||
|
||||
+26
-13
@@ -5,9 +5,18 @@
|
||||
# site/build.py, because the host looks for it at the root of the build
|
||||
# and nowhere else.
|
||||
#
|
||||
# Rules apply in order and a later rule wins on a header it repeats. The
|
||||
# two blocks below are written so that even a host that merged them
|
||||
# instead would land on the safe side: HTML would still revalidate.
|
||||
# Rules do NOT override each other: a header two matching rules both set
|
||||
# arrives concatenated. Measured on the live site, not assumed —
|
||||
# /* and /static/* both setting Cache-Control produced
|
||||
#
|
||||
# cache-control: public, max-age=0, must-revalidate, public,
|
||||
# max-age=31536000, immutable
|
||||
#
|
||||
# on the stylesheet, and the first max-age wins in every browser, so the
|
||||
# year-long cache never happened. So exactly one rule may set a given
|
||||
# header: Cache-Control is set on /static/* alone, and HTML is left to
|
||||
# the host's own default, which is the revalidating one. Check #4 after a
|
||||
# deploy is what keeps that honest.
|
||||
|
||||
# Everything, so that no page can ever forget one of these.
|
||||
#
|
||||
@@ -17,26 +26,30 @@
|
||||
# `preload`: that is a submission to browser
|
||||
# vendors and a commitment this card did not make
|
||||
# X-Frame-Options nothing here is meant to be framed
|
||||
# CSP the runtime form of the site's own promise —
|
||||
# no analytics, no font CDN, no third-party
|
||||
# anything. `default-src 'none'` means an asset
|
||||
# must be named below to load at all, and no
|
||||
# CSP the runtime form of the site's own promise.
|
||||
# `default-src 'none'` means an asset must be
|
||||
# named below to load at all, and no
|
||||
# 'unsafe-inline' anywhere means an injected
|
||||
# <script> does not run
|
||||
# Cache-Control HTML revalidates on every view, so a deploy is
|
||||
# visible on the next reload. The ETag makes that
|
||||
# a 304 rather than a re-download
|
||||
# <script> does not run. One origin besides
|
||||
# 'self' is named: cdn.usefathom.com, which
|
||||
# serves the analytics script and receives its
|
||||
# pageviews. Fathom sets no cookie and collects
|
||||
# nothing about a person, which is why it needs
|
||||
# no banner — but it is a third party, and the
|
||||
# policy says so out loud rather than quietly
|
||||
# allowing everything
|
||||
/*
|
||||
X-Content-Type-Options: nosniff
|
||||
Referrer-Policy: strict-origin-when-cross-origin
|
||||
Strict-Transport-Security: max-age=31536000; includeSubDomains
|
||||
X-Frame-Options: DENY
|
||||
Content-Security-Policy: default-src 'none'; style-src 'self'; font-src 'self'; img-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
|
||||
Cache-Control: public, max-age=0, must-revalidate
|
||||
Content-Security-Policy: default-src 'none'; style-src 'self'; font-src 'self'; img-src 'self'; script-src https://cdn.usefathom.com; connect-src https://cdn.usefathom.com; base-uri 'none'; form-action 'none'; frame-ancestors 'none'
|
||||
|
||||
# The stylesheet and the icon are linked with a ?v=<hash> of their own
|
||||
# contents (site/build.py, stamp()), and the fonts never change under a
|
||||
# given filename. All of it is safe to keep for a year and never check:
|
||||
# a deploy that changes the stylesheet changes the url that asks for it.
|
||||
# The only rule in this file that sets Cache-Control, for the reason at
|
||||
# the top — a second one would concatenate rather than lose.
|
||||
/static/*
|
||||
Cache-Control: public, max-age=31536000, immutable
|
||||
|
||||
@@ -21,6 +21,10 @@
|
||||
<link rel="canonical" href="$canonical">
|
||||
<link rel="icon" href="$icon">
|
||||
<link rel="stylesheet" href="$stylesheet">
|
||||
<!-- Fathom — cookieless analytics: pageviews only, nothing about a
|
||||
person, so no banner. The one third-party request this site makes;
|
||||
root/_headers names cdn.usefathom.com in the CSP for exactly it. -->
|
||||
<script src="https://cdn.usefathom.com/script.js" data-site="ZPKDEHCV" defer></script>
|
||||
</head>
|
||||
<body class="page-article">
|
||||
|
||||
|
||||
@@ -35,6 +35,10 @@
|
||||
<meta name="twitter:card" content="summary">
|
||||
<link rel="icon" href="$icon">
|
||||
<link rel="stylesheet" href="$stylesheet">
|
||||
<!-- Fathom — cookieless analytics: pageviews only, nothing about a
|
||||
person, so no banner. The one third-party request this site makes;
|
||||
root/_headers names cdn.usefathom.com in the CSP for exactly it. -->
|
||||
<script src="https://cdn.usefathom.com/script.js" data-site="ZPKDEHCV" defer></script>
|
||||
</head>
|
||||
<body class="page-home">
|
||||
|
||||
|
||||
@@ -20,6 +20,10 @@
|
||||
<meta name="robots" content="noindex">
|
||||
<link rel="icon" href="$icon">
|
||||
<link rel="stylesheet" href="$stylesheet">
|
||||
<!-- Fathom — cookieless analytics: pageviews only, nothing about a
|
||||
person, so no banner. The one third-party request this site makes;
|
||||
root/_headers names cdn.usefathom.com in the CSP for exactly it. -->
|
||||
<script src="https://cdn.usefathom.com/script.js" data-site="ZPKDEHCV" defer></script>
|
||||
</head>
|
||||
<body class="page-notfound">
|
||||
|
||||
|
||||
@@ -194,12 +194,15 @@ class TheRealSiteBuilds(unittest.TestCase):
|
||||
self.assertIn('href="/concepts/claiming-a-card/"', article)
|
||||
self.assertIn("Concepts", article)
|
||||
|
||||
def test_nothing_the_pages_load_is_third_party(self):
|
||||
"""The acceptance criterion, mechanised: every asset a browser
|
||||
would fetch — stylesheet, icon, script, font — is same-origin,
|
||||
and nothing preconnects anywhere. A <link rel=canonical> is a
|
||||
statement about this page, not a fetch, so it is not one of
|
||||
these; anything that makes the browser open a connection is."""
|
||||
def test_the_only_third_party_is_the_one_that_was_chosen(self):
|
||||
"""Every asset a browser would fetch — stylesheet, icon, font —
|
||||
is same-origin, and nothing preconnects anywhere. The single
|
||||
exception is the analytics script, named here and in the CSP, so
|
||||
a second third party has to be a deliberate edit to this list
|
||||
rather than something that slipped into a template. A <link
|
||||
rel=canonical> is a statement about this page, not a fetch, so it
|
||||
is not one of these; anything that opens a connection is."""
|
||||
chosen = ("https://cdn.usefathom.com/",)
|
||||
fetching = {"stylesheet", "icon", "shortcut icon", "preload",
|
||||
"prefetch", "preconnect", "dns-prefetch", "manifest",
|
||||
"modulepreload"}
|
||||
@@ -217,7 +220,7 @@ class TheRealSiteBuilds(unittest.TestCase):
|
||||
r"""<(?:script|img|iframe)\b[^>]*\bsrc=["']([^"']+)""",
|
||||
html, re.IGNORECASE):
|
||||
self.assertTrue(
|
||||
url.startswith("/"),
|
||||
url.startswith("/") or url.startswith(chosen),
|
||||
f'{entry["path"]} loads {url} from somewhere else')
|
||||
|
||||
css = (self.out / "static" / "site.css").read_text("utf-8")
|
||||
|
||||
+35
-21
@@ -242,13 +242,22 @@ class TheHeaderPolicyTravelsWithTheBuild(Built):
|
||||
def test_no_page_needs_what_the_policy_forbids(self):
|
||||
"""The CSP carries no 'unsafe-inline', so an inline <script> or a
|
||||
style="" attribute is a page that renders right in every test
|
||||
here and wrong in production. The only place that can be caught
|
||||
before a deploy is the build output."""
|
||||
here and wrong in production. A script with a src is fine only
|
||||
if the policy names where it comes from. The only place that can
|
||||
be caught before a deploy is the build output."""
|
||||
allowed = re.findall(r"https://[^\s;]+",
|
||||
rule("/*")["Content-Security-Policy"])
|
||||
for path in sorted(self.out.rglob("*.html")):
|
||||
html = path.read_text("utf-8")
|
||||
where = path.relative_to(self.out)
|
||||
self.assertNotIn("<script", html.lower(),
|
||||
f"{where} has a script the CSP would block")
|
||||
for tag in re.findall(r"<script[^>]*>", html, re.I):
|
||||
src = re.search(r'src="([^"]+)"', tag)
|
||||
self.assertIsNotNone(
|
||||
src, f"{where} has an inline script the CSP would block")
|
||||
self.assertTrue(
|
||||
src.group(1).startswith("/")
|
||||
or any(src.group(1).startswith(o) for o in allowed),
|
||||
f"{where} loads {src.group(1)}, which the CSP forbids")
|
||||
self.assertNotRegex(
|
||||
html, r"""\sstyle\s*=\s*["']""",
|
||||
f"{where} has an inline style the CSP would block")
|
||||
@@ -270,39 +279,44 @@ class EveryResponseCarriesTheBaseline(unittest.TestCase):
|
||||
"preload is a submission to browser vendors, "
|
||||
"not a header to set in passing")
|
||||
|
||||
def test_nothing_third_party_can_load(self):
|
||||
"""The site's promise — no analytics, no font CDN — as something
|
||||
the browser enforces rather than something a test asserted once
|
||||
at build time."""
|
||||
def test_only_the_analytics_origin_can_load(self):
|
||||
"""The site's promise as something the browser enforces rather
|
||||
than something a test asserted once at build time. Exactly one
|
||||
third party is named — the cookieless analytics — and the day a
|
||||
second one appears, this fails rather than shrugging."""
|
||||
policy = self.everything["Content-Security-Policy"]
|
||||
self.assertIn("default-src 'none'", policy)
|
||||
self.assertNotIn("unsafe-inline", policy)
|
||||
self.assertNotIn("unsafe-eval", policy)
|
||||
self.assertNotIn("*", policy)
|
||||
self.assertNotIn("//", policy, "the policy names another origin")
|
||||
self.assertEqual({"https://cdn.usefathom.com"},
|
||||
set(re.findall(r"https://[^\s;]+", policy)),
|
||||
"the policy names an origin nobody decided on")
|
||||
self.assertNotIn("font-src https", policy,
|
||||
"the fonts are self-hosted and stay that way")
|
||||
|
||||
|
||||
class TheTwoKindsOfFileAreCachedDifferently(unittest.TestCase):
|
||||
"""The edge case in the task: a stale HTML page must not survive a
|
||||
deploy, while the assets it links may live for a year."""
|
||||
|
||||
def test_html_revalidates_on_every_view(self):
|
||||
value = rule("/*")["Cache-Control"]
|
||||
self.assertIn("max-age=0", value)
|
||||
self.assertIn("must-revalidate", value)
|
||||
self.assertNotIn("immutable", value)
|
||||
|
||||
def test_fingerprinted_assets_are_kept_for_a_year(self):
|
||||
value = rule("/static/*")["Cache-Control"]
|
||||
self.assertIn("max-age=31536000", value)
|
||||
self.assertIn("immutable", value)
|
||||
|
||||
def test_the_general_rule_comes_first(self):
|
||||
"""Order is the whole argument: /static/* overrides /* on
|
||||
Cache-Control, and a host that merged them instead of overriding
|
||||
would land on max-age=0 — the safe side."""
|
||||
patterns = [pattern for pattern, _ in read_headers(HEADERS)]
|
||||
self.assertLess(patterns.index("/*"), patterns.index("/static/*"))
|
||||
def test_exactly_one_rule_sets_cache_control(self):
|
||||
"""The host concatenates a header two matching rules both set,
|
||||
it does not override — measured on the live site, where /* and
|
||||
/static/* together produced 'max-age=0, must-revalidate,
|
||||
max-age=31536000, immutable' and the first max-age won. So the
|
||||
year-long rule must be the only one, and HTML takes the host's
|
||||
own revalidating default."""
|
||||
setters = [pattern for pattern, headers in read_headers(HEADERS)
|
||||
if "Cache-Control" in headers]
|
||||
self.assertEqual(["/static/*"], setters,
|
||||
"a second Cache-Control rule would concatenate "
|
||||
"with this one rather than lose to it")
|
||||
|
||||
|
||||
# ── fingerprinting ────────────────────────────────────────────────────
|
||||
|
||||
@@ -190,7 +190,15 @@ class WhatThePageMayNotSay(LandingCase):
|
||||
for page in self.manifest["pages"]:
|
||||
html_text = text_of(BUILDER.target_for(self.out, page["path"]))
|
||||
with self.subTest(page=page["path"]):
|
||||
self.assertNotIn("<script", html_text.lower())
|
||||
# The analytics tag is deferred and nothing reads it back:
|
||||
# every word, link and menu works with scripting off. Any
|
||||
# *other* script would be the page needing one.
|
||||
scripts = re.findall(r"<script\b[^>]*>", html_text, re.I)
|
||||
for tag in scripts:
|
||||
self.assertIn("cdn.usefathom.com", tag,
|
||||
"a script the page would depend on")
|
||||
self.assertIn("defer", tag,
|
||||
"even analytics waits for the page")
|
||||
self.assertNotIn("<noscript", html_text.lower())
|
||||
self.assertIsNone(
|
||||
re.search(r"\son[a-z]+=", html_text, re.IGNORECASE),
|
||||
|
||||
@@ -324,15 +324,17 @@ class TheBuiltPagesCarryTheMenus(unittest.TestCase):
|
||||
if "toc-link" in self.CONTENTS.search(html).group(1)]
|
||||
self.assertTrue(filled, "no article page's contents strip has links")
|
||||
|
||||
def test_the_site_ships_no_script(self):
|
||||
"""One menu that opens and closes is a <details>. Nothing on this
|
||||
site justifies the first line of JavaScript on it — and the
|
||||
Content-Security-Policy in site/root/_headers forbids one."""
|
||||
def test_the_menus_need_no_script(self):
|
||||
"""One menu that opens and closes is a <details>. The site ships
|
||||
no JavaScript of its own — the only script on a page is the
|
||||
third-party analytics tag, which no menu, link or word depends
|
||||
on, and the CSP in site/root/_headers names it explicitly."""
|
||||
self.assertEqual([], sorted(self.out.rglob("*.js")))
|
||||
for entry in self.manifest["pages"]:
|
||||
html = BUILDER.target_for(self.out, entry["path"]).read_text("utf-8")
|
||||
self.assertNotIn("<script", html.lower(),
|
||||
f'{entry["path"]} loads a script')
|
||||
for tag in re.findall(r"<script\b[^>]*>", html, re.I):
|
||||
self.assertIn("cdn.usefathom.com", tag,
|
||||
f'{entry["path"]} loads a script of its own')
|
||||
|
||||
def test_every_built_page_declares_the_viewport(self):
|
||||
for entry in self.manifest["pages"]:
|
||||
|
||||
Reference in New Issue
Block a user