@osqd/bothandlerjs 0.3.0

package/docs/course/15-extending.md

@@ -0,0 +1,259 @@
+# Lesson 15 — Extending it
+
+**Goal:** add a detector, a signature, an action and a browser signal of your own — and
+meet the certainty rule from the other side.
+
+← [Course](index.md) · Prev: [Scaling](14-scaling.md) · Next: [Proving it](16-proving-it.md)
+
+---
+
+## A detector of your own
+
+A detector returns **evidence**, never a verdict. It has no idea what the policy will do
+with what it finds, and that separation is what keeps the certainty model intact.
+
+Serif's checkout is being hammered. Nothing shipped knows what a checkout is:
+
+```js
+function checkoutVelocity() {
+  return {
+    id: "checkout-velocity",
+    description: "More checkout attempts in a minute than a person makes",
+    cost: "cheap",
+    stage: "always",
+    inspect(ctx) {
+      if (!ctx.facts.path.startsWith("/checkout")) return undefined;
+
+      const attempts = ctx.state.requestsWithin(60_000, ctx.facts.timestamp);
+      if (attempts < 5) return undefined;
+
+      return {
+        detector: "checkout-velocity",
+        summary: `${attempts} checkout attempts in a minute`,
+        direction: "bot",
+        certainty: "strong",     // not `certain` — a shared address explains it too
+        botClass: "automation",
+      };
+    },
+  };
+}
+
+const detector = new BotHandler({ extraDetectors: [checkoutVelocity()] });
+```
+
+### Checkpoint
+
+Six POSTs to `/checkout` from one address, 800 ms apart:
+
+```
+checkout burst: score=66 verdict=suspected-bot
+  [strong] checkout-velocity: 6 checkout attempts in a minute
+  [weak] accept-signature: Accept-Language is a single bare tag ("en-GB") with no fallback chain
+```
+
+## The certainty rule, from the inside
+
+Look again at that comment: `certainty: "strong"`, not `certain`.
+
+Six checkout attempts in a minute is a *strong* signal and it is not proof. An office
+behind one NAT address, a family sharing a connection, a customer whose payment kept
+failing — all produce it. To mark it `certain` you would have to write a
+`deterministicBasis` sentence explaining why no benign explanation exists, and you cannot,
+because one does.
+
+**That is the forcing function.** If you cannot write the sentence, your evidence is
+`strong`. Outside production the library *enforces* it: `certain` evidence with no basis is
+rejected. Inside production it downgrades to a warning instead, so a third-party detector
+with a missing basis cannot take a live site down.
+
+```js
+return {
+  detector: "checkout-velocity",
+  certainty: "certain",
+  deterministicBasis: "…",     // you would have to justify it here, in writing
+  // …
+};
+```
+
+Try it without the basis and watch it get refused. That refusal is the library defending the
+one guarantee it makes.
+
+## Cost and stage, honestly
+
+Mark a detector `cost: "io"` if it touches the network or a shared store, and it runs
+concurrently under a timeout. Mislabelling one would put an unbounded await on the request
+path — so the engine times out any promise a `cheap` detector returns anyway.
+
+Use `stage: "confirming"` when your work is only worth doing if something else already found
+an identity to confirm.
+
+## Replacing a shipped detector
+
+`detectors` replaces the whole set, so map over the default list:
+
+```js
+import { defaultDetectors, probeSignatureDetector } from "@osqd/bothandlerjs";
+
+new BotHandler({
+  detectors: defaultDetectors().map((d) =>
+    d.id === "probe-signature" ? probeSignatureDetector({ ignore: ["/wp-login.php"] }) : d,
+  ),
+});
+```
+
+## A signature of your own
+
+Serif's partner sends a nightly sync. You want it recognised and allowed by name:
+
+```js
+const partner = {
+  id: "serif-partner-sync",
+  name: "Serif Partner Sync",
+  tokens: ["serifpartnersync"],     // lowercase — see below
+  category: "library",
+  benign: true,
+  verification: { kind: "none" },
+};
+
+const detector = new BotHandler({
+  extraSignatures: [partner],
+  rules: [{ id: "partner-allow", match: { identity: "serif-partner-sync" }, action: "allow",
+            reason: "Our own partner integration." }],
+});
+```
+
+### Checkpoint
+
+```
+verdict=confirmed-bot class=http-client identity=serif-partner-sync certain=true
+  [certain] self-identified: User-Agent identifies Serif Partner Sync
+decision: allow via rule "partner-allow"
+```
+
+**`tokens` must be lowercase.** Matching lowercases the User-Agent first, so an uppercase
+token silently never matches — no error, no warning, just a signature that does nothing. It
+is the single easiest mistake to make here, and it costs an afternoon.
+
+`verification` is required. Use `{ kind: "none" }` for a client with no verifiable identity,
+`{ kind: "fcrdns", domains: [...] }` where the operator publishes reverse DNS, or
+`{ kind: "ip-ranges" }` where they publish addresses.
+
+Set `conclusive: false` with a `caveat` when a token can legitimately appear on a request a
+person made. Electron is the motivating case: that User-Agent comes from VS Code's browser,
+Slack, Discord and Postman — real Chromium instances with a human driving them.
+
+## An action of your own
+
+```js
+import { defineHandler } from "@osqd/bothandlerjs";
+
+const emptyResults = defineHandler({
+  id: "empty-results",
+  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: [emptyResults],
+  rules: [{ id: "shadow", match: { botClass: "scraper" }, action: "custom",
+            params: { handler: "empty-results" } }],
+});
+```
+
+Return `{ kind: "continue" }` — optionally with `requestHeaders`, `responseHeaders` or
+`delayMs` — or `{ kind: "respond", status, headers, body }`, or `{ kind: "drop" }`. It may
+be async.
+
+**Remember the guard does not apply here.** It cannot know what your handler does. A handler
+that denies service is a decision you own entirely — which is fine, as long as you know you
+are making it.
+
+A handler named in a rule but not registered serves the request and warns.
+
+## Browser signals
+
+An optional page script reports what only the browser can see — `navigator.webdriver`,
+automation properties, timing:
+
+```js
+import { renderClientScript } from "@osqd/bothandlerjs/client";
+
+// `endpoint` is required: it is your route, and it should be cheap and rate-limited.
+app.get("/", (req, res) =>
+  res.send(`<body>…${renderClientScript({ endpoint: "/__signals", nonce: res.locals.nonce })}</body>`),
+);
+```
+
+It posts back to that endpoint, and the `client-signals` detector reads what arrives. Supply
+the `nonce` if your Content-Security-Policy needs one.
+
+**It is capped at `moderate`, permanently, whatever it reports.** The browser is the one
+place an adversary has complete control: `navigator.webdriver` proves what the client *chose
+to report*, and a scraper that wants to lie about it has already won that argument. Treating
+it as conclusive would move the whole guarantee inside the attacker's process.
+
+So it is real evidence, weighted honestly, and it can never on its own deny anybody.
+
+## Exercise
+
+Serif wants to catch scripted gift-card redemption: many distinct codes tried from one
+actor, few succeeding. Write the detector, and decide its tier.
+
+<details>
+<summary>Answer</summary>
+
+```js
+function giftCardProbing(redemptions) {
+  return {
+    id: "gift-card-probing",
+    description: "Many distinct gift-card codes tried from one actor",
+    cost: "cheap",
+    stage: "always",
+    inspect(ctx) {
+      if (ctx.facts.path !== "/gift-cards/redeem") return undefined;
+      const tried = redemptions.recentFailures(ctx.actorKey, 10 * 60_000);
+      if (tried < 12) return undefined;
+      return {
+        detector: "gift-card-probing",
+        summary: `${tried} failed gift-card redemptions in ten minutes`,
+        direction: "bot",
+        certainty: "strong",
+        botClass: "automation",
+      };
+    },
+  };
+}
+```
+
+**`strong`, not `certain`.** Twelve failed redemptions is a strong signal about a *shared
+address* as much as about a script — a busy office at Christmas produces it. You cannot
+write the basis sentence, so it is not certain.
+
+**`cheap`, only if `redemptions` is in memory.** If it queries a database, it is `io` — and
+mislabelling it would put a database round trip on the request path of every checkout.
+
+And note that a `strong` signal is enough to challenge or rate-limit, which is the right
+response to card probing anyway. You lose nothing by being honest about the tier.
+</details>
+
+## What you learned
+
+- A detector returns evidence, never a verdict
+- The `deterministicBasis` requirement is a forcing function: if you cannot write it, it is
+  `strong`
+- `cost` must be honest, or you put an await on the request path
+- Signature `tokens` must be lowercase, and the failure is silent
+- Custom handlers sit outside the guard, deliberately
+- Browser signals are capped at `moderate` for ever, because that is the attacker's process
+
+## Reference
+
+- [Writing a detector](../detection/writing-a-detector.md) · [Signatures](../detection/signatures.md)
+- [Browser signals](../detection/client-signals.md) · [Actions](../policy/actions.md)
+
+Next: [Proving it, and the capstone](16-proving-it.md).

package/docs/course/16-proving-it.md

@@ -0,0 +1,266 @@
+# Lesson 16 — Proving it, and the capstone
+
+**Goal:** find out who your policy would hurt *before* it hurts them, then assemble
+everything into a Serif you can defend.
+
+← [Course](index.md) · Prev: [Extending it](15-extending.md)
+
+---
+
+## The question this library is organised around
+
+*If I point this configuration at the actual internet, who gets hurt?*
+
+Three tools answer it, and they answer different halves.
+
+## `check` — against 526 shapes of real traffic
+
+```bash
+npx @osqd/bothandlerjs check --preset protect-content
+```
+
+```
+  protect-content against 522 shapes of real traffic
+
+  human            181 cases   3 tag, 175 allow, 3 challenge
+  benign-bot       144 cases   6 allow, 86 tag, 48 block, 2 challenge, 2 rate-limit
+  declared-bot      32 cases   18 tag, 2 rate-limit, 3 allow, 9 block
+  unwanted-bot     105 cases   8 tag, 11 rate-limit, 3 block, 70 challenge, 13 allow
+  hostile           27 cases   6 challenge, 17 block, 4 allow
+  infrastructure    33 cases   7 allow, 12 tag, 14 challenge
+
+  No case marked as a person was denied service.
+```
+
+**It exits non-zero if any case marked `human` is denied**, which is what makes it a CI step
+rather than a report.
+
+The corpus is 526 cases with provenance: 182 of them people — 30 browser profiles, 40 in-app
+WebViews, Tor, screen readers, IE11, a car's infotainment screen, corporate proxies, CGNAT,
+an author signing in at `/wp-login.php`. Header order is reproduced rather than invented, and
+DNS is controlled rather than mocked away, so *"the operator's DNS disproves this"* and
+*"our resolver was unhappy"* can be told apart.
+
+`--audience human` shows only the part that matters. `--strict` also fails on differing
+actions.
+
+### Against *your* configuration
+
+The corpus is a published entry point, not a test fixture:
+
+```js
+import { runCorpus } from "@osqd/bothandlerjs/corpus";
+
+const scorecard = await runCorpus({
+  create: ({ resolver, clock }) => new BotHandler({ ...serifConfig, resolver, clock }),
+  assertActions: false,   // your actions are yours; the invariants are not
+});
+
+if (scorecard.falsePositives.length > 0) {
+  throw new Error(`Serif's policy denies ${scorecard.falsePositives.length} people`);
+}
+```
+
+Put that in your test suite. It runs offline and deterministically.
+
+## `replay` — against traffic that is actually yours
+
+The corpus knows what the internet looks like. Only your logs know what *your* visitors look
+like.
+
+```bash
+npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
+```
+
+```
+  116 request(s) would have been DENIED, in 1 distinct kind(s). Read them.
+  ─────────────────────────────────────────────────────────────────────
+     116x  block by rule "scanner-block" — confirmed-bot, proven
+          sqlmap/1.7.2#stable (https://sqlmap.org)
+          [certain] self-identified: User-Agent identifies sqlmap
+```
+
+That block is the point of the exercise. If any of those is a person, the policy is wrong —
+and you found out from a log file rather than from a support ticket.
+
+**Prefer JSON Lines over CLF**, and the reason is the rule from [lesson 2](02-proof-and-suspicion.md):
+
+> A header missing from a *record* is not a header missing from the *request*.
+
+An nginx line carries the User-Agent and the Referer and nothing else. Detectors that reason
+from absence would fire on everything, so `partialHeaders` marks a header-poor source and
+they stand down. A CLF replay therefore **under-reports**, and its silence is not a clean
+bill of health.
+
+```js
+createFacts({ method, url, headers, ip, partialHeaders: true });
+```
+
+## `explain` — one request, by ticket
+
+```bash
+npx @osqd/bothandlerjs explain "curl/8.4.0"
+pbpaste | npx @osqd/bothandlerjs explain --preset protect-data
+```
+
+A User-Agent, a curl command out of devtools, or a raw header block. It runs as a **dry
+run** — nothing recorded, so asking does not change the answer:
+
+```js
+const assessment = await detector.assess(facts, { record: false });
+```
+
+No counter moves, no actor state changes, no event fires. It has no history by construction,
+so what it answers is *what would this look like as a first request* — which is what a
+ticket is asking anyway.
+
+## The order to use them in
+
+1. **`explain`** — one request, when somebody complains
+2. **`check`** — in CI, on every change
+3. **`replay`** — before enforcing anything, over a real week
+4. **`monitor-only` in production** — for a week, watching the dashboard
+
+Step 4 is not optional and the first three do not replace it.
+
+---
+
+# Capstone: Serif
+
+Everything from sixteen lessons, in one configuration.
+
+```js
+import express from "express";
+import { BotHandler, RedisStore, declineAiTraining, robotsFromRules, renderTrapLink } from "@osqd/bothandlerjs";
+import { botHandler } from "@osqd/bothandlerjs/adapters";
+
+const store = new RedisStore(redis);
+const proxy = { trustProxy: true, trustedProxies: ["10.0.0.0/8"] };   // lesson 12
+
+const site = new BotHandler({
+  preset: "decline-ai-training",            // lesson 10 — the business decision
+  proxy,                                    // lesson 12 — the dangerous setting
+  store,                                    // lesson 14 — nonces and rate limits
+  shareConfirmations: true,                 // lesson 14 — proof travels
+  actorKey: (facts) => facts.session ?? facts.ip,          // lesson 7
+  isHuman: (facts) => Boolean(sessions.get(facts.session ?? "")?.authenticated),   // lesson 12
+  allowlist: ["10.0.0.0/8"],                // monitors and CI
+  ignorePaths: ["/healthz", "/metrics"],
+  extraDetectors: [checkoutVelocity()],     // lesson 15
+  extraSignatures: [partner],               // lesson 15
+  challenge: {                              // lesson 11
+    secrets: [process.env.SERIF_CHALLENGE_SECRET, process.env.SERIF_CHALLENGE_SECRET_PREVIOUS].filter(Boolean),
+    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" }, ja: { lang: "ja", title: "ブラウザーを確認しています" } },
+  },
+  rules: [                                  // lesson 9 — yours run before the preset's
+    { id: "partner-allow", match: { identity: "serif-partner-sync" }, action: "allow",
+      reason: "Our own nightly partner sync." },
+    { id: "persistent-refusal", match: { minUnsolvedChallenges: 5 }, action: "block",
+      reason: "Issued five challenges, finished none." },
+  ],
+  audit: { windowMs: 5 * 60_000, baselineMs: 60 * 60_000, minSamples: 50 },   // lesson 13
+  onAnomaly: (a) => pager.send(a.severity, a.summary),
+  onDowngrade: ({ decision }) => metrics.increment("bot.downgrade", { rule: decision.rule }),
+  onWarning: (message) => log.warn({ message }, "bothandler"),
+});
+
+// Auth routes get their own policy, mounted only there.        lesson 10
+const auth = new BotHandler({ preset: "protect-auth", proxy, store });
+
+const app = express();
+app.use(botHandler(site));
+app.use("/login", botHandler(auth));
+app.use("/checkout", botHandler(auth));
+
+// Say out loud what the policy does.                            lesson 10
+const { robotsTxt, unreadable } = robotsFromRules(declineAiTraining(), {
+  disallowPaths: ["/internal/export.csv"],
+  sitemap: "https://serif.example/sitemap.xml",
+});
+if (unreadable.length > 0) log.warn({ unreadable }, "not reflected in robots.txt");
+app.get("/robots.txt", (_req, res) => res.type("text/plain").send(robotsTxt));
+
+// A trap no person can reach.                                   lesson 8
+app.get("/", (_req, res) => res.send(`<main>…</main>${renderTrapLink("/internal/export.csv")}`));
+
+// Watch it.                                                     lesson 13
+app.get("/internal/metrics", (_req, res) => res.type("text/plain").send(site.prometheus()));
+await site.serveDashboard({ port: 9674, title: "serif", auth: { username: "ops", password: process.env.DASHBOARD_PASSWORD } });
+```
+
+And the test that stops it hurting anybody:
+
+```js
+import { runCorpus } from "@osqd/bothandlerjs/corpus";
+
+it("never denies a person", async () => {
+  const scorecard = await runCorpus({
+    create: ({ resolver, clock }) => new BotHandler({ ...serifConfig, resolver, clock }),
+    assertActions: false,
+  });
+  expect(scorecard.falsePositives).toEqual([]);
+});
+```
+
+## Final exercise
+
+Answer these without looking anything up. They are the whole course.
+
+1. A client scores 99 from probabilistic signals. Can a rule block it? Why?
+2. Your policy denies 4% of traffic. What do you check first?
+3. `bothandler_downgrades_total` doubled after a deploy. What happened?
+4. `challenge-solve-rate` is 96%. Is that good?
+5. You add a detector that catches a scraper perfectly. What tier is its evidence?
+
+<details>
+<summary>Answers</summary>
+
+1. **No.** The score is not what gates a terminal action — `certain` is. Ninety-nine
+   probabilistic points are ninety-nine things a real person can trip, and the guard
+   substitutes something recoverable. [Lesson 4](04-the-guard.md).
+
+2. **Who the 4% are.** Run `replay` over the log and read every denial. A `denial-spike`
+   anomaly is not evidence they were bots — it is evidence that something changed, and the
+   expensive possibility is that it changed about people. [Lesson 13](13-operating-it.md).
+
+3. **Your policy now asks for more than the evidence supports.** Either a rule changed, or
+   the traffic did. The guard absorbed the difference, which is why nobody was wrongly
+   refused — but the two have drifted apart and the number is telling you so.
+   [Lesson 4](04-the-guard.md).
+
+4. **No — it is the bad direction.** A proof of work is trivial for a browser and trivial
+   for a competent scraper. When nearly everything challenged passes, the challenges are not
+   filtering bots out, they are taxing people. [Lesson 13](13-operating-it.md).
+
+5. **`strong`, almost certainly.** Ask whether you can write a `deterministicBasis`
+   sentence explaining why no benign explanation exists. Unless the client *declared*
+   itself, *contradicted* itself, walked into a *trap*, was *refuted by an external
+   authority*, or committed a *protocol violation* — you cannot, and it is not certain.
+   [Lesson 15](15-extending.md).
+</details>
+
+## Where to go now
+
+- **[The threat model](../concepts/threat-model.md).** Read it before you promise anybody
+  anything. It names the two rungs of the evasion ladder that defeat this library, and it is
+  the most useful page in the documentation once you know how everything works.
+- **[Design decisions](../design/decisions.md).** Fifteen choices with what each one cost.
+- **[The reference](../index.md).** Thirty pages, one per question.
+
+## What you learned in this course
+
+- Proof and suspicion are different things, and only one of them may close a door
+- Twenty detectors, each with a ceiling it may not exceed
+- A name is a claim until an external authority confirms it
+- Behaviour over time catches what a single request cannot, and stops at a paced scraper
+- First match wins, and order is the policy
+- Rank actions by what they cost somebody who did nothing wrong
+- The challenge imposes cost; it proves neither identity nor humanity
+- The client IP is the setting that is silent when it is wrong
+- Alert on downgrades; read the score histogram before moving a threshold
+- Proof travels between replicas; suspicion stays home
+- If you cannot write why it admits no benign explanation, it is not certain
+- Find out who your policy hurts before it hurts them
+
+← [Back to the course](index.md)

package/docs/course/index.md

@@ -0,0 +1,112 @@
+# The BotHandler course
+
+Sixteen lessons that build one real integration, from a first assessment to a policy you
+can defend.
+
+← [Documentation](../index.md)
+
+---
+
+## What this is
+
+The [reference documentation](../index.md) answers *"how does X work?"*. This answers
+*"what do I do, and in what order?"* — every capability of the library, taught in the
+order that makes each one make sense, with something to run at every step.
+
+It is written to be worked through rather than read. Every lesson has code you paste and
+output you can check yours against, and every checkpoint in it was produced by actually
+running the code rather than by imagining what it would print.
+
+**Time:** about four hours to do properly. Lessons 1–4 are the foundation and are worth
+slowing down for; everything after them assumes you have those.
+
+## Who it is for
+
+A TypeScript or JavaScript developer who has a site or an API and a bot problem — or who
+suspects they are about to have one. You need no background in bot detection. You do need
+to be comfortable running `node` and reading a stack trace.
+
+## The running example
+
+You are building **Serif**, an online bookshop. It has a catalogue worth scraping, a
+checkout worth attacking, and readers worth not annoying. Every lesson adds one thing to
+Serif, and by lesson 16 you have a complete, tested, production-shaped configuration.
+
+## Set up once
+
+```bash
+mkdir serif && cd serif
+npm init -y && npm pkg set type=module
+npm install @osqd/bothandlerjs
+```
+
+Every lesson's code goes in a file you run with `node`. Nothing needs a server until
+lesson 11.
+
+---
+
+## Part 1 — The ideas everything rests on
+
+| | | |
+|-|-|-|
+| 1 | [Your first assessment](01-first-assessment.md) | Turn a request into a verdict, and read what comes back. |
+| 2 | [Proof and suspicion](02-proof-and-suspicion.md) | The distinction the whole library is built on. **The most important lesson here.** |
+| 3 | [Verdicts, classes and scores](03-verdicts-and-scores.md) | Four fields describe a client. Which one should you act on? |
+| 4 | [The safety guard](04-the-guard.md) | The mechanism that stops a guess closing a door. |
+
+## Part 2 — Detection
+
+| | | |
+|-|-|-|
+| 5 | [The detectors](05-detectors.md) | All twenty: what each reads, what each costs, what each may conclude. |
+| 6 | [Identity and verification](06-identity.md) | Recognising a crawler by name — and proving or refuting the claim. |
+| 7 | [Actors and behaviour](07-actors.md) | Who "the same client" is, and what watching one over time tells you. |
+| 8 | [Traps](08-traps.md) | The one detector that needs no statistics, and how to lay one properly. |
+
+## Part 3 — Deciding what to do
+
+| | | |
+|-|-|-|
+| 9 | [Rules](09-rules.md) | Matching requests, in first-match-wins order. |
+| 10 | [Actions and presets](10-actions-and-presets.md) | Ten responses, ordered by what each costs a person who did nothing wrong. |
+| 11 | [The challenge](11-the-challenge.md) | Proof of work: what it buys, what it cannot, and who it must not exclude. |
+
+## Part 4 — Production
+
+| | | |
+|-|-|-|
+| 12 | [Going live](12-going-live.md) | Adapters, and the one setting that is dangerous to get wrong. |
+| 13 | [Operating it](13-operating-it.md) | The dashboard, metrics, the traffic audit, notifications. |
+| 14 | [Scaling and changing it live](14-scaling.md) | Several replicas, shared state, and editing policy without a deploy. |
+
+## Part 5 — Making it yours, and proving it
+
+| | | |
+|-|-|-|
+| 15 | [Extending it](15-extending.md) | Your own detector, action, signatures and browser signals. |
+| 16 | [Proving it, and the capstone](16-proving-it.md) | The corpus, log replay, and a finished Serif you can defend. |
+
+---
+
+## How to get the most out of it
+
+**Type the code, do not paste it.** The examples are short on purpose.
+
+**Do the exercises before reading the answer.** Each one has a checkpoint so you know
+whether you got it.
+
+**When something surprises you, chase it.** Every lesson ends with links into the
+reference documentation for the thing you just used. The surprises are usually where the
+library is protecting you from something.
+
+## A promise, and its consequence
+
+One sentence holds this library together, and it will explain most of what surprises you:
+
+> **Nothing is ever denied service on the strength of a guess.**
+
+You will meet it first in [lesson 4](04-the-guard.md), where a rule you wrote asking to
+block somebody quietly does something gentler instead. That is not a bug, and the lesson
+explains why it is the most valuable behaviour here.
+
+Start with [lesson 1](01-first-assessment.md).