@osqd/bothandlerjs 0.3.0

package/docs/course/09-rules.md

@@ -0,0 +1,224 @@
+# Lesson 9 — Rules
+
+**Goal:** write the policy you designed in lesson 3, and understand why order decides
+everything.
+
+← [Course](index.md) · Prev: [Traps](08-traps.md) · Next: [Actions and presets](10-actions-and-presets.md)
+
+---
+
+## The shape
+
+```js
+{
+  id: "scraper-ratelimit",              // required, and it appears in every decision
+  match: { botClass: "scraper" },       // every field present must match
+  action: "rate-limit",
+  params: { limit: { max: 60, windowMs: 60_000 } },
+  reason: "Bulk extraction. Rate-limited rather than refused.",
+}
+```
+
+**First match wins.** Rules are evaluated in order and the first that matches decides;
+nothing accumulates. If none matches, `defaultAction` applies — `allow` unless you change
+it.
+
+**`id` is not decoration.** It comes back in `decision.rule`, in the dashboard, in every
+downgrade event and in the replay report. Name rules after what they do, not after what
+they match.
+
+**`reason` is read by people.** It appears in the dashboard and in `bothandlerjs replay`
+output. Write it for whoever is looking at a refused request at 2am.
+
+## Every field you can match on
+
+Grouped by the question each answers.
+
+**What did we conclude?**
+
+| Field | |
+| ----- | - |
+| `verdict` | one or several of `confirmed-bot`, `verified-bot`, `suspected-bot`, `human`, `unknown` |
+| `certain` | `true` to require proof |
+| `botClass` | one or several classes |
+| `minScore` / `maxScore` | inclusive score band |
+
+**Who is it?**
+
+| Field | |
+| ----- | - |
+| `identity` | a named signature — `"gptbot"`, `"googlebot"` |
+| `category` | `ai`, `search`, `seo`, `social`, `monitoring`, `feed`, `archive`, `security`, `library`, `headless`, `advertising` |
+| `detector` | fired by a named detector — `"trap"`, `"probe-signature"` |
+
+**What did they do?**
+
+| Field | |
+| ----- | - |
+| `path` | string prefix, `RegExp`, or a list of either |
+| `method` | `"POST"`, or a list |
+
+**What have they done before?**
+
+| Field | |
+| ----- | - |
+| `minPriorConfirmations` | proven a bot this many times in the window |
+| `minUnsolvedChallenges` | issued this many challenges and finished none |
+
+Every field present must match. An empty `match: {}` matches everything, which is how you
+write a catch-all last rule.
+
+## Do this: Serif's policy
+
+Take the table from [lesson 3](03-verdicts-and-scores.md) and write it out.
+
+```js
+import { BotHandler, createFacts } from "@osqd/bothandlerjs";
+
+const detector = new BotHandler({
+  rules: [
+    { id: "verified-crawler-allow", match: { verdict: "verified-bot" }, action: "allow",
+      reason: "Confirmed search or social crawler — the traffic Serif wants." },
+
+    { id: "impersonator-block", match: { botClass: "impersonator", certain: true }, action: "block",
+      reason: "Forged a verifiable crawler identity. Proven by DNS, not inferred." },
+
+    { id: "scanner-block", match: { botClass: "scanner", certain: true }, action: "block",
+      reason: "Self-identified security scanner." },
+
+    { id: "trap-block", match: { detector: "trap", certain: true }, action: "block",
+      reason: "Followed a link no person can reach." },
+
+    { id: "scraper-ratelimit", match: { botClass: "scraper" }, action: "rate-limit",
+      params: { limit: { max: 60, windowMs: 60_000 } },
+      reason: "Behaves like bulk extraction. Slowed rather than refused." },
+
+    { id: "http-client-challenge", match: { botClass: "http-client" }, action: "challenge",
+      reason: "Bare HTTP client. Challenged rather than blocked: it may be somebody's integration." },
+
+    { id: "declared-bot-tag", match: { botClass: "declared-bot" }, action: "tag",
+      reason: "Announced itself honestly. Tagged so the application can decide." },
+
+    { id: "suspected-tag", match: { verdict: "suspected-bot" }, action: "tag",
+      reason: "Some signal, not enough to act on." },
+  ],
+});
+```
+
+Run the lesson 3 cases through `decide` and check each lands on the rule you intended.
+
+## Order is the policy
+
+Move `suspected-tag` to the top and every rule below it stops mattering for anything
+suspected — including your scanner block, because a scanner is also suspected. Nothing
+warns you; the policy simply does less than it reads.
+
+Two habits that prevent it:
+
+**Allows for traffic you want, first.** A verified crawler should be decided before
+anything gets a chance to be clever about it.
+
+**Specific before general.** `{ botClass: "scanner" }` before `{ verdict: "suspected-bot" }`,
+always.
+
+## Your own rules run before a preset's
+
+```js
+new BotHandler({
+  preset: "protect-content",
+  rules: [{ id: "partner-allow", match: { path: "/api/partner" }, action: "allow" }],
+});
+```
+
+`rules` are evaluated **before** the preset's, which makes this the clean way to add
+exceptions without copying a preset. [Lesson 10](10-actions-and-presets.md) covers when to
+adopt a preset wholesale instead.
+
+## Predicates, and what they cost
+
+When the declarative fields cannot say it, `match` takes a function:
+
+```js
+{
+  id: "checkout-under-attack",
+  match: (assessment, facts) => facts.path.startsWith("/checkout") && assessment.score > 50 && !assessment.certain,
+  action: "delay",
+  params: { delayMs: 500 },
+}
+```
+
+Two things it costs you.
+
+**`robotsFromRules` cannot read it.** A predicate can be run but not asked which crawlers
+it is about, so it is reported as `unreadable` rather than guessed at — see
+[lesson 10](10-actions-and-presets.md).
+
+**The dashboard cannot preview it usefully.** A declarative match can be explained; a
+function can only be executed.
+
+Reach for one when you need it, and prefer the fields when you do not.
+
+## Validate before you ship
+
+```js
+import { validateRules } from "@osqd/bothandlerjs";
+const problems = validateRules(myRules);
+if (problems.length > 0) throw new Error(problems.join("\n"));
+```
+
+It catches duplicate ids, unknown actions, a `redirect` with no `location`, a `custom` with
+no registered handler, and score bands that can never match. `new BotHandler()` runs it for
+you and reports through `onWarning`; calling it yourself turns a warning into a failing
+test.
+
+## Exercise
+
+Add two rules to Serif and place them correctly:
+
+1. `/checkout` should never be served to anything proven automated.
+2. A client that has been issued five challenges and finished none should be blocked.
+
+<details>
+<summary>Answer</summary>
+
+```js
+rules: [
+  { id: "verified-crawler-allow", match: { verdict: "verified-bot" }, action: "allow" },
+
+  // Before the generic blocks: it is more specific, and it is about a path.
+  { id: "checkout-no-bots", match: { path: "/checkout", certain: true, botClass: ["http-client", "automation", "scanner", "impersonator", "declared-bot"] },
+    action: "block", reason: "Proven automation on the checkout." },
+
+  { id: "persistent-refusal", match: { minUnsolvedChallenges: 5 }, action: "block",
+    reason: "Issued five challenges, finished none." },
+
+  // …the rest as before
+]
+```
+
+Two things to notice.
+
+**`checkout-no-bots` lists classes rather than using bare `certain: true`** — which would
+also match a proven *human*, and blocking a customer you just vouched for on your own
+checkout is the worst possible outcome. This is the trap from lesson 3, in the place it
+does most damage.
+
+**`persistent-refusal` is a rule, not evidence.** One abandoned challenge is a person. What
+five of them mean is a judgement about your traffic, so the library exposes the count and
+lets you decide rather than deciding for you.
+</details>
+
+## What you learned
+
+- First match wins; order is the policy and nothing warns you when it is wrong
+- `id` and `reason` are read by people and by tools — write them properly
+- Twelve declarative fields, grouped by the question they answer
+- Your `rules` run before a preset's, which is how to add exceptions cleanly
+- A predicate costs you `robots.txt` generation and dashboard preview
+
+## Reference
+
+- [Matching requests](../policy/rules.md) — every field in detail
+- [Policy overview](../policy/index.md) — how a decision is reached
+
+Next: [Actions and presets](10-actions-and-presets.md).

package/docs/course/10-actions-and-presets.md

@@ -0,0 +1,216 @@
+# Lesson 10 — Actions and presets
+
+**Goal:** choose responses by what they cost somebody who did nothing wrong, then compare
+your hand-written policy against the eight shipped ones.
+
+← [Course](index.md) · Prev: [Rules](09-rules.md) · Next: [The challenge](11-the-challenge.md)
+
+---
+
+## Ten actions, ranked by who they hurt
+
+That ranking is the useful one. Every action here will eventually be applied to somebody it
+should not have been, so the question that matters is what that costs them.
+
+| Action | Terminal | Costs a person |
+| ------ | -------- | -------------- |
+| `allow` | | nothing |
+| `log` | | nothing |
+| `tag` | | nothing |
+| `delay` | | a moment |
+| `rate-limit` | | a retry, if they are fast |
+| `challenge` | | seconds, and a working browser |
+| `custom` | | whatever you wrote |
+| `redirect` | ✓ | their destination |
+| `block` | ✓ | the page |
+| `drop` | ✓ | the page, with no explanation |
+
+The three marked terminal are the ones [the guard](04-the-guard.md) will not let rest on a
+guess.
+
+## The ones worth dwelling on
+
+**`tag`** attaches the verdict to the **request** — `x-bot-verdict`, `x-bot-score`,
+`x-bot-class`, `x-bot-certain`, `x-bot-reason` — so your own handlers can react without
+re-running detection:
+
+```js
+app.get("/search", (req, res) => {
+  const bot = req.headers["x-bot-verdict"] !== "unknown";
+  res.json(bot ? cachedResults() : personalisedResults(req.user));
+});
+```
+
+Response-side verdict headers are **off by default**, and should stay off: an `X-Bot-Score`
+in the response is a live feedback signal for anyone tuning a scraper against you.
+
+**`delay`** costs you almost nothing and costs a scraper everything, while a person notices
+a pause and nothing else. Default 500 ms, capped at 10 s. It holds a connection open, so
+prefer `rate-limit` under heavy concurrency.
+
+**`rate-limit`** is the one action that **needs a shared store**. A limit of 100/minute
+enforced independently by four replicas is a limit of 400/minute. [Lesson 14](14-scaling.md).
+
+**`drop`** is the harshest thing here: the connection is destroyed with no response at all.
+A person who hits it gets a browser error with nothing in it, cannot tell your site from an
+outage, and has no way to contact you. **`block` with a `reason` is almost always better.**
+Reserve `drop` for traffic you have already decided about.
+
+## Custom actions
+
+```js
+import { BotHandler, defineHandler } from "@osqd/bothandlerjs";
+
+const shadowBan = defineHandler({
+  id: "shadow-ban",
+  description: "Serves an empty result set rather than an error",
+  execute: ({ assessment }) => ({
+    kind: "respond",
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ results: [] }),
+  }),
+});
+
+new BotHandler({
+  handlers: [shadowBan],
+  rules: [{ id: "shadow", match: { botClass: "scraper" }, action: "custom", params: { handler: "shadow-ban" } }],
+});
+```
+
+`execute` returns `{ kind: "continue" }` — optionally with `requestHeaders`,
+`responseHeaders` or `delayMs` — or `{ kind: "respond", status, headers, body }`, or
+`{ kind: "drop" }`. It may be async.
+
+**The guard does not apply to custom handlers.** It cannot know what yours does, so a
+handler that denies service is a decision you own entirely. That is worth reading twice: it
+is the one door out of the guarantee, and it is unlocked from the inside.
+
+## The eight presets
+
+A preset is not a black box. It is an array of the same rules you just wrote, exported and
+readable:
+
+```js
+import { protectContent } from "@osqd/bothandlerjs";
+console.log(protectContent());
+```
+
+| Preset | For | Terminal on |
+| ------ | --- | ----------- |
+| `monitor-only` | week one, always | nothing |
+| `allow-crawlers` | publishers who want to be found | impersonators, scanners, traps |
+| `protect-content` | a public content site | impersonators, scanners, traps |
+| `decline-ai-training` | keeping search, declining trainers | + declared AI crawlers |
+| `protect-data` | pricing, listings, inventory | + declared AI and SEO crawlers |
+| `protect-api` | a JSON API | impersonators, scanners, traps |
+| `protect-auth` | login, signup, checkout — **those routes only** | all proven automation |
+| `under-attack` | during an incident, then off again | all proven automation |
+
+```js
+new BotHandler({ preset: "protect-content" });
+```
+
+## Compare yours to theirs
+
+Print `protectContent()` beside your lesson 9 rules. You will find they are close — and the
+differences are worth understanding:
+
+- It has a `cleared-human-allow` rule first, which yours lacks. You will add the `isHuman`
+  it depends on in [lesson 12](12-going-live.md).
+- It challenges suspected traffic at `minScore: 70`, where yours only tags. That threshold
+  is the number to move first when tuning.
+
+## Three presets with a warning attached
+
+**`protect-auth` must be mounted on auth routes only.** Site-wide it blocks your payment
+webhooks, your own server-side renderer and every honest crawler — all proven automation,
+which is exactly what it refuses. Correct on a login form, an outage anywhere else.
+
+```js
+app.use(botHandler(siteDetector));
+app.use("/login", botHandler(authDetector));
+app.use("/checkout", botHandler(authDetector));
+```
+
+**`protect-api` deliberately never challenges.** A proof of work is solved by a browser
+running JavaScript, and an API client is not one — challenging your customers' integrations
+breaks them while an attacker solves it once in headless Chrome. The escalation ladder there
+is rate limiting.
+
+**`under-attack` is temporary.** It challenges at `minScore: 40` and rate-limits
+*everybody*, people included, because a uniform ceiling is the one mitigation that cannot
+single anybody out. It is not DDoS protection — it runs after the connection is accepted —
+and like `protect-auth` it refuses proven automation, so allowlist your webhooks *before*
+you switch it on rather than during the incident.
+
+## robots.txt, generated from the policy
+
+Declining a crawler and not saying so is the worst of both worlds: it keeps coming, and you
+get no credit for having a policy.
+
+```js
+import { declineAiTraining, robotsFromRules } from "@osqd/bothandlerjs";
+
+const { robotsTxt, declined, served, unreadable } = robotsFromRules(declineAiTraining(), {
+  disallowPaths: ["/internal/export.csv"],     // your trap paths belong here
+  sitemap: "https://serif.example/sitemap.xml",
+});
+```
+
+**Read `unreadable` before you publish.** It lists rules that could not be reflected — a
+predicate match, or a rule scoped to a path (which a named `robots.txt` group cannot
+express without turning the crawler away from the whole site). A generated file that
+silently omits something you block is worse than none at all: it tells crawlers they are
+welcome where they are not.
+
+`served` is the other one to read: crawlers a later rule would decline but an earlier rule
+serves. That is why `decline-ai-training` blocks the `ai` category yet leaves
+`ChatGPT-User` out of the file — it is served by an earlier rule, and the file agrees with
+the policy rather than contradicting it.
+
+## Exercise
+
+Serif's business decision: keep search engines, decline model trainers, and say so.
+
+<details>
+<summary>Answer</summary>
+
+```js
+import { BotHandler, declineAiTraining, robotsFromRules } from "@osqd/bothandlerjs";
+
+const detector = new BotHandler({ preset: "decline-ai-training" });
+
+const { robotsTxt, unreadable } = robotsFromRules(declineAiTraining(), {
+  disallowPaths: ["/internal/export.csv"],
+  sitemap: "https://serif.example/sitemap.xml",
+});
+if (unreadable.length > 0) console.warn("not reflected in robots.txt:", unreadable);
+
+app.get("/robots.txt", (_req, res) => res.type("text/plain").send(robotsTxt));
+```
+
+The preset serves `ChatGPT-User`, `PerplexityBot`, `OAI-SearchBot`, `ClaudeBot`,
+`Mistral-AI` and `DuckDuckBot` — a crawler fetching one page because a person asked about
+it is a citation, not a corpus — and blocks the rest of the `ai` category with a body that
+says why.
+
+**`robots.txt` is the primary mechanism, not the rules.** The crawlers named here honour
+it; the rules are what happens to the ones that do not.
+</details>
+
+## What you learned
+
+- Rank actions by what they cost a person who did nothing wrong
+- `tag` is the workhorse; `drop` is almost never right
+- Custom handlers are outside the guard, deliberately
+- Presets are readable arrays of rules, not black boxes
+- Three presets carry warnings; read them before mounting
+- Generate `robots.txt` from the policy, and read `unreadable` and `served`
+
+## Reference
+
+- [Actions](../policy/actions.md) · [Presets](../policy/presets.md) · [robots.txt](../policy/robots.md)
+- [Choosing a policy](../start/choosing-a-policy.md)
+
+Next: [The challenge](11-the-challenge.md).

package/docs/course/11-the-challenge.md

@@ -0,0 +1,227 @@
+# Lesson 11 — The challenge
+
+**Goal:** turn on proof of work, know exactly what it buys, and make sure it cannot become
+a wall for somebody who did nothing wrong.
+
+← [Course](index.md) · Prev: [Actions and presets](10-actions-and-presets.md) · Next: [Going live](12-going-live.md)
+
+---
+
+## What it actually buys
+
+The client must find a counter such that `SHA-256(nonce + ":" + counter)` begins with
+`difficulty` zero bits. Verification is one hash; solving takes about `2^difficulty` of
+them.
+
+**It does not identify anyone and it does not prove a human is present.** A headless Chrome
+solves it as readily as a person's phone, just paying for the CPU.
+
+What it does is convert a scrape from free into merely cheap, and change the *shape* of the
+attack: a stateless scraper pulling a million pages must now run a JavaScript engine and
+burn CPU on every one. Often that is enough to make bulk extraction not worth doing, and it
+costs a real visitor a fraction of a second, once.
+
+That is precisely why it sits where it does on the [action ladder](10-actions-and-presets.md).
+It is the heaviest thing the [guard](04-the-guard.md) will let a *probabilistic* verdict ask
+for, because a client wrongly suspected can pass it on its own and carry on.
+
+## Do this
+
+Remember lesson 4, where a rule asking to block got `tag` instead? That was because no
+challenge was configured. Fix it:
+
+```js
+import { BotHandler, createFacts } from "@osqd/bothandlerjs";
+
+const detector = new BotHandler({
+  challenge: {
+    secrets: [process.env.SERIF_CHALLENGE_SECRET],   // at least 32 characters
+    contactHtml: '<p>Locked out? Email <a href="mailto:help@serif.example">help@serif.example</a>.</p>',
+  },
+  rules: [
+    { id: "suspected-challenge", match: { verdict: "suspected-bot", minScore: 40 }, action: "challenge" },
+  ],
+  suspectThreshold: 40,
+});
+
+const spoof = createFacts({
+  method: "GET", url: "/books", ip: "203.0.113.55",
+  headers: { host: "serif.example", "user-agent": CHROME["user-agent"], accept: "*/*" },
+});
+
+const result = await detector.handle(spoof);
+console.log(result.outcome.kind, result.outcome.status);
+```
+
+### Checkpoint
+
+```
+respond 429
+```
+
+`handle` does assess, decide and act in one call, and returns an `ActionOutcome` for an
+adapter to apply. The interstitial is a `429` with a locked-down CSP — `default-src 'none'`
+and a nonce for its own script. No external resource of any kind appears on it.
+
+## The secret has no default, on purpose
+
+A library-supplied fallback secret is a library-supplied forgery key, and it would end up in
+production somewhere. Without `secrets`, a rule asking for a challenge degrades to `tag` and
+says so through `onWarning`. Secrets must be at least 32 characters; shorter throws at
+construction.
+
+Rotating: the **first** secret signs, **all** of them verify. Prepend a new one, keep the
+old for a token lifetime, and nobody is logged out.
+
+```js
+challenge: { secrets: [NEW_SECRET, PREVIOUS_SECRET] }
+```
+
+## `contactHtml` is the most valuable line here
+
+Everyone who sees the no-JavaScript fallback is a person your site just turned away: no
+JavaScript, no WebCrypto, or a device too slow to finish. Put a real support address, a
+phone number, or a link to a form there.
+
+The default text is honest but generic. Yours can name a human.
+
+## Difficulty
+
+In *bits*, so each step doubles the work. Default 16 — about 65,000 hashes, tens of
+milliseconds in a modern browser. Refused above 24.
+
+Past about 20 you are charging real people a visible delay, and **the oldest and slowest
+devices pay the most** — which disproportionately means the users least able to replace
+them. Raise it during an incident, not as a posture.
+
+## What a clearance proves
+
+Solving grants a signed cookie that the `clearance` detector reads afterwards. It carries a
+**level**, and the level is what a rule should key on:
+
+| Level | Demonstrated | Certainty |
+| ----- | ------------ | --------- |
+| `pow` | ran JavaScript, has WebCrypto, spent CPU | not conclusive |
+| `interaction` | a trusted input event was observed | stronger, still forgeable by a driven browser |
+| `operator` | **your application** said this is a person | `certain` |
+
+Only `operator` is conclusive, because that assertion comes from you rather than from the
+client. You grant it yourself:
+
+```js
+detector.grantClearance(facts, "operator");   // e.g. just after a successful sign-in
+```
+
+That is the only conclusive human signal that exists anywhere in this library.
+
+## The one piece of state
+
+The lifecycle is deliberately stateless until the moment of success: a challenge is a signed
+blob the client carries, so a flood of unsolved challenges costs nothing but the bytes to
+send them.
+
+Exactly one thing is written, at the one moment it is indispensable: the solved nonce is
+**claimed atomically**, so a solution cannot be replayed. That claim lives in the store —
+with the default in-memory one and several replicas, a scraper retries a solved nonce
+against other instances until one has not seen it. [Lesson 14](14-scaling.md).
+
+## Two refusals
+
+**Challenging an actor that already holds valid clearance** is refused and warned about.
+Passing a challenge cannot change a proven verdict, so re-issuing would loop for ever.
+
+**Challenging on an API** breaks your customers' integrations and stops nobody — see
+`protect-api` in [lesson 10](10-actions-and-presets.md).
+
+## Unsolved challenges as a signal
+
+Every issued-and-never-solved challenge is counted on the [actor](07-actors.md):
+
+```js
+{ id: "persistent-refusal", match: { minUnsolvedChallenges: 5 }, action: "block" }
+```
+
+It is **not evidence**, deliberately. One abandoned challenge is a person who changed their
+mind; what five of them mean is a judgement about your traffic that only you can make.
+
+## Speaking the visitor's language
+
+The interstitial is the only page this library shows to a member of the public, and they
+are seeing it because a *probabilistic* verdict went against them. Somebody who cannot read
+it cannot find the contact link on it either — which turns a check into a wall.
+
+```js
+challenge: {
+  secrets: [SECRET],
+  contactHtml: "<p>…</p>",
+  translations: {
+    ja: { title: "ブラウザーを確認しています", message: "数秒で完了します。" },
+    de: { title: "Browser wird überprüft" },
+    "pt-BR": { title: "Verificando seu navegador" },
+  },
+}
+```
+
+The library ships **no translations and will not**: a machine-translated apology on a page
+that just turned somebody away is worse than an honest English one, and only you know which
+languages your audience reads. Anything a translation omits falls back to the default, so a
+`title`-only entry is a fine first step.
+
+Matching is exact tag first, then primary subtag — and it stops there. `pt-PT` is **not**
+handed `pt-BR`. That looks unhelpful until you consider the case it protects: serving
+Simplified Chinese to somebody who asked for Traditional is a worse failure than serving
+English, and no rule can tell the two apart. Whether one regional variant stands in for
+another is decided by which keys you write.
+
+Each translation may set `lang`, which decides the voice a screen reader uses. Japanese
+announced as `lang="en"` is unintelligible; getting the copy right and the attribute wrong
+helps nobody.
+
+## Exercise
+
+Serif serves readers in Britain, Brazil and Japan. Configure the challenge so that none of
+them hits a wall, and say what happens to a Portuguese reader in Lisbon.
+
+<details>
+<summary>Answer</summary>
+
+```js
+challenge: {
+  secrets: [process.env.SERIF_CHALLENGE_SECRET],
+  contactHtml: '<p>Locked out? Email <a href="mailto:help@serif.example">help@serif.example</a>.</p>',
+  translations: {
+    "pt-BR": { lang: "pt-BR", title: "Verificando seu navegador", message: "Isso leva alguns segundos.",
+               contactHtml: '<p>Problemas? <a href="mailto:help@serif.example">Fale conosco</a>.</p>' },
+    ja: { lang: "ja", title: "ブラウザーを確認しています", message: "数秒で完了します。",
+          contactHtml: '<p>お困りですか？<a href="mailto:help@serif.example">サポート</a>へご連絡ください。</p>' },
+  },
+}
+```
+
+**The Lisbon reader gets English.** `pt-PT` matches no exact key, and the primary-subtag
+step looks for `pt`, which you did not supply — `pt-BR` is a regional variant and will not
+stand in for another.
+
+If Serif wants European Portuguese readers covered by the Brazilian copy, that is a
+judgement about the audience, and it is made by **filing the copy under `pt`** rather than
+`pt-BR`. The library will not make it for you.
+
+Note that every translation carries its own `contactHtml`. A translated "checking your
+browser" over an English "email us" is half a fix.
+</details>
+
+## What you learned
+
+- Proof of work imposes cost; it proves neither identity nor humanity
+- The secret has no default because a default secret is a forgery key
+- Difficulty is in bits, and the slowest devices pay most
+- Only `operator` clearance is conclusive, and only you can grant it
+- `minUnsolvedChallenges` is a rule, not evidence
+- The interstitial is public-facing: give it a real contact and a language people read
+
+## Reference
+
+- [The challenge](../challenge/index.md) · [Localisation](../challenge/localisation.md)
+- [Actions](../policy/actions.md) — where `challenge` sits
+
+Next: [Going live](12-going-live.md).