codetrail-cli 1.4.1__py3-none-any.whl

codetrail/web/navigation.py

@@ -0,0 +1,127 @@
+"""What the page's shell shows around every page (design section 16.1): the sidebar, a page's neighbours in its path,
+and where to continue reading. Built from the guide's pages and the reader's learning states; malformed front matter
+never breaks it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+
+from codetrail.guide import Page
+
+SIDEBAR_ANSWERS = 5
+PINNABLE = ("path", "area", "concept", "answer")  # the guide pages the sidebar lists, which can be pinned
+WORD = re.compile(r"[^\W_]+")
+
+
+@dataclass(frozen=True)
+class Navigation:
+    paths: list[tuple[Page, int, int]] = field(default_factory=list)  # path, steps learned, steps
+    areas: list[Page] = field(default_factory=list)
+    concepts: list[Page] = field(default_factory=list)
+    answers: list[Page] = field(default_factory=list)  # the newest few
+    answer_count: int = 0
+    statuses: Mapping[str, str] = field(default_factory=dict)  # page id -> learning state
+    unread_digests: bool = False
+    branch: str = ""
+    commit: str = ""
+    pins: list[Page] = field(default_factory=list)  # pinned pages, in the order they were pinned
+
+
+def initials(title: str) -> str:
+    """A pinned tile's letters: the first letters of the title's first two words, or one word's first two."""
+    words: list[str] = WORD.findall(title)
+    if not words:
+        return "·"
+    if len(words) == 1:
+        return words[0][:1].upper() + words[0][1:2]
+    return (words[0][:1] + words[1][:1]).upper()
+
+
+def read_pins(value: str | None) -> list[str]:
+    """The pinned page ids as stored, a JSON list of strings; anything else reads as no pins."""
+    try:
+        loaded = json.loads(value) if value else []
+    except ValueError:
+        return []
+    return [item for item in loaded if isinstance(item, str)] if isinstance(loaded, list) else []
+
+
+def steps_of(path: Page) -> list[str]:
+    steps = path.meta.get("steps")
+    return [str(step) for step in steps] if isinstance(steps, list) else []
+
+
+def _by_title(pages: Iterable[Page]) -> list[Page]:
+    return sorted(pages, key=lambda page: (page.title.casefold(), page.id))
+
+
+def answers_newest_first(pages: Iterable[Page]) -> list[Page]:
+    """Saved answers, newest first by when they were asked; one with no usable date sorts last."""
+
+    def asked(page: Page) -> str:
+        value = page.meta.get("asked_at")
+        return value if isinstance(value, str) else ""
+
+    listed = list(pages)  # read once: callers may pass a generator
+    dated = sorted((page for page in listed if asked(page)), key=asked, reverse=True)
+    return dated + sorted((page for page in listed if not asked(page)), key=lambda page: page.id)
+
+
+def build_navigation(
+    pages: Sequence[Page], statuses: Mapping[str, str], unread_digests: Sequence[str], branch: str = "",
+    commit: str = "", pinned: Sequence[str] = (),
+) -> Navigation:  # fmt: skip
+    pinnable = {page.id: page for page in pages if page.kind in PINNABLE}
+    paths = [
+        (path, sum(1 for step in steps_of(path) if statuses.get(step) == "learned"), len(steps_of(path)))
+        for path in _by_title(page for page in pages if page.kind == "path")
+    ]
+    answers = answers_newest_first(page for page in pages if page.kind == "answer")
+    return Navigation(
+        paths=paths,
+        areas=_by_title(page for page in pages if page.kind == "area"),
+        concepts=_by_title(page for page in pages if page.kind == "concept"),
+        answers=answers[:SIDEBAR_ANSWERS],
+        answer_count=len(answers),
+        statuses=dict(statuses),
+        unread_digests=bool(unread_digests),
+        branch=branch,
+        commit=commit,
+        pins=[pinnable[page_id] for page_id in pinned if page_id in pinnable],
+    )
+
+
+def path_neighbours(
+    pages: Sequence[Page], page_id: str, path_hint: str | None
+) -> tuple[Page | None, Page | None, Page | None]:
+    """The path a page is read in, and its previous and next steps there.
+
+    The path is the one the reader came from when it really holds the page, otherwise the first one that does (by
+    title); a page in no path has none.
+    """
+    by_id = {page.id: page for page in pages}
+    holding = [path for path in _by_title(page for page in pages if page.kind == "path") if page_id in steps_of(path)]
+    if not holding:
+        return None, None, None
+    path = next((candidate for candidate in holding if candidate.id == path_hint), holding[0])
+    steps = steps_of(path)
+    position = steps.index(page_id)
+    previous = by_id.get(steps[position - 1]) if position > 0 else None
+    following = by_id.get(steps[position + 1]) if position + 1 < len(steps) else None
+    return path, previous, following
+
+
+def continue_reading(pages: Sequence[Page], statuses: Mapping[str, str]) -> tuple[Page, Page, int, int] | None:
+    """The first path (by title) with a step not yet learned: the path, that step, steps learned, and steps."""
+    by_id = {page.id: page for page in pages}
+    for path in _by_title(page for page in pages if page.kind == "path"):
+        steps = [step for step in steps_of(path) if step in by_id]
+        learned = sum(1 for step in steps if statuses.get(step) == "learned")
+        for step in steps:
+            if statuses.get(step) != "learned":
+                return path, by_id[step], learned, len(steps)
+    return None

codetrail/web/render.py

@@ -0,0 +1,126 @@
+"""Rendering a guide page (design sections 6.4 and 7.4).
+
+Markdown is rendered by markdown-it-py with raw HTML disabled and its link validation on (no `javascript:`,
+`vbscript:`, `file:` or `data:` links). Rationale blocks become labelled boxes, `[[fact]]` links point at the fact's
+view, and diagram placeholders are replaced by diagrams drawn from facts.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+from markdown_it import MarkdownIt
+from markdown_it.renderer import RendererHTML
+from markdown_it.token import Token
+from markdown_it.utils import EnvType, OptionsDict
+from markupsafe import Markup
+
+from codetrail.facts.store import FactStore
+from codetrail.generate.validate import DIAGRAM, FILE_CITATION, MARKER
+from codetrail.web.diagrams import (
+    Diagram,
+    dependencies_diagram,
+    imports_diagram,
+    resources_diagram,
+    system_diagram,
+)
+
+FACT_LINK = re.compile(r"\[\[([a-z_]+:[^\]\s]+)\]\]")
+MARKDOWN = MarkdownIt("commonmark", {"html": False, "linkify": False}).enable("table")
+
+
+def _aligned_cell(
+    renderer: RendererHTML, tokens: Sequence[Token], index: int, options: OptionsDict, env: EnvType
+) -> str:
+    """A table column's alignment as a class, where markdown-it writes an inline style: the page's policy allows no
+    inline styles (ADR 0016)."""
+    token = tokens[index]
+    style = token.attrs.pop("style", None)
+    if isinstance(style, str) and style.startswith("text-align:"):
+        token.attrSet("class", "align-" + style.removeprefix("text-align:"))
+    return renderer.renderToken(tokens, index, options, env)
+
+
+for cell in ("th_open", "td_open"):
+    MARKDOWN.add_render_rule(cell, _aligned_cell)
+
+
+@dataclass(frozen=True)
+class Segment:
+    kind: str  # "html", "rationale" or "diagram"
+    html: Markup = field(default_factory=Markup)
+    label: str = ""
+    citation: str | None = None
+    link: str | None = None
+    diagram: Diagram | None = None
+
+
+def render_markdown(text: str) -> Markup:
+    linked = FACT_LINK.sub(lambda match: f"[{match.group(1)}](</facts/{quote(match.group(1), safe='')}>)", text)
+    # Raw HTML is off and links are validated, so the output holds only markdown-it's own markup.
+    return Markup(MARKDOWN.render(linked))  # noqa: S704
+
+
+def render_body(body: str, store: FactStore, max_nodes: int) -> list[Segment]:
+    segments: list[Segment] = []
+    pending: list[str] = []
+
+    def flush() -> None:
+        if "".join(pending).strip():
+            segments.append(Segment("html", render_markdown("\n".join(pending))))
+        pending.clear()
+
+    lines = body.splitlines()
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        marker = MARKER.match(line)
+        diagram = DIAGRAM.match(line.strip())
+        if marker:
+            flush()
+            index += 1
+            content = []
+            while index < len(lines) and lines[index].startswith(">") and not MARKER.match(lines[index]):
+                content.append(lines[index][1:].removeprefix(" "))
+                index += 1
+            citation = marker.group(2) or None
+            segments.append(
+                Segment("rationale", render_markdown("\n".join(content)), marker.group(1), citation, _link(citation))
+            )
+            continue
+        if diagram:
+            flush()
+            drawn = _diagram(diagram.group(1), store, max_nodes)
+            if drawn is not None and drawn.nodes:  # a diagram with nothing to draw is left out, not shown empty
+                segments.append(Segment("diagram", diagram=drawn))
+        else:
+            pending.append(line)
+        index += 1
+    flush()
+    return segments
+
+
+def _link(citation: str | None) -> str | None:
+    match = FILE_CITATION.match(citation or "")
+    return f"/source/{quote(match.group('path'))}#L{match.group('start')}" if match else None
+
+
+def _diagram(arguments: str, store: FactStore, max_nodes: int) -> Diagram | None:
+    parts = arguments.split()
+    if parts == ["system"]:
+        return system_diagram(store, None, max_nodes)
+    if len(parts) != 2 or "=" not in parts[1]:
+        return None
+    kind, value = parts[0], parts[1].split("=", 1)[1]
+    if kind == "imports":
+        return imports_diagram(store, value, max_nodes)
+    if kind == "dependencies":
+        return dependencies_diagram(store, value)
+    if kind == "resources":
+        return resources_diagram(store, value, max_nodes)
+    if kind == "system" and parts[1].startswith("focus="):
+        return system_diagram(store, value, max_nodes)
+    return None

codetrail/web/repository_view.py

@@ -0,0 +1,230 @@
+"""The Repository page's chart data: what `static/js/repository.js` draws, with its labels translated (design 20.3).
+
+The document goes into the page as a JSON block the browser never runs, escaped so no text in it can end the block.
+Counted phrases come from the catalog for a few sample numbers that between them reach every plural category of every
+language; the script finds the sample in the same `Intl.PluralRules` category as its number. Placeholders are written
+`{name}` for the script to fill. Babel is a development tool only (ADR 0005), so nothing here uses it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Mapping, Sequence
+from datetime import UTC, date, datetime, timedelta
+from typing import Any
+from urllib.parse import quote
+
+from codetrail.metrics.activity import Activity
+from codetrail.metrics.churn import Churn, HotSpot, folder_of
+from codetrail.metrics.repository import RepositoryReport
+from codetrail.metrics.size import LanguageSize
+from codetrail.web.i18n import Language
+
+PLACEHOLDER = re.compile(r"%\((\w+)\)s")
+LISTED_FILES = 5  # files a tile's panel lists
+# Characters that could end the JSON block or break a script, written as JSON's \u escapes instead.
+ESCAPES = {character: f"\\u{ord(character):04x}" for character in ("<", ">", "&", chr(0x2028), chr(0x2029))}
+
+
+def _template(text: str) -> str:
+    return PLACEHOLDER.sub(r"{\1}", text)
+
+
+# Numbers that between them fall in every plural category CLDR gives any language (zero, one, two, few, many, other).
+PLURAL_SAMPLES = (0, 1, 2, 3, 4, 5, 6, 7, 11, 12, 21, 22, 100, 101, 102, 1_000_000)
+
+
+def plural_templates(choose: Callable[[int], str]) -> dict[str, str]:
+    """`choose(n)` is an ngettext call; its template for each sample number, keyed by the number."""
+    return {str(number): _template(choose(number)) for number in PLURAL_SAMPLES}
+
+
+def month_names(language: Language) -> list[str]:
+    """The months' short names, January first, from the catalog."""
+    t = language.translations
+    return [t.pgettext("month", "Jan"), t.pgettext("month", "Feb"), t.pgettext("month", "Mar"),
+            t.pgettext("month", "Apr"), t.pgettext("month", "May"), t.pgettext("month", "Jun"),
+            t.pgettext("month", "Jul"), t.pgettext("month", "Aug"), t.pgettext("month", "Sep"),
+            t.pgettext("month", "Oct"), t.pgettext("month", "Nov"), t.pgettext("month", "Dec")]  # fmt: skip
+
+
+def weekday_names(language: Language) -> list[str]:
+    """The weekdays' short names, Monday first, from the catalog."""
+    t = language.translations
+    return [t.pgettext("weekday", "Mon"), t.pgettext("weekday", "Tue"), t.pgettext("weekday", "Wed"),
+            t.pgettext("weekday", "Thu"), t.pgettext("weekday", "Fri"), t.pgettext("weekday", "Sat"),
+            t.pgettext("weekday", "Sun")]  # fmt: skip
+
+
+def weekday_full_names(language: Language) -> list[str]:
+    """The weekdays' names, Monday first, from the catalog."""
+    t = language.translations
+    return [t.gettext("Monday"), t.gettext("Tuesday"), t.gettext("Wednesday"), t.gettext("Thursday"),
+            t.gettext("Friday"), t.gettext("Saturday"), t.gettext("Sunday")]  # fmt: skip
+
+
+def script_json(document: Mapping[str, object]) -> str:
+    """The document as JSON safe inside `<script type="application/json">`: no `<`, `>` or `&` left to end it."""
+    text = json.dumps(document, ensure_ascii=False, separators=(",", ":"))
+    return "".join(ESCAPES.get(character, character) for character in text)
+
+
+def _labels(language: Language) -> dict[str, object]:
+    t = language.translations
+
+    plural = plural_templates
+
+    return {
+        "months": month_names(language),
+        "commits": plural(lambda n: t.ngettext("%(count)s commit", "%(count)s commits", n)),
+        "lines": plural(lambda n: t.ngettext("%(count)s line", "%(count)s lines", n)),
+        "commitsSince": plural(
+            lambda n: t.ngettext("%(count)s commit since %(name)s", "%(count)s commits since %(name)s", n)
+        ),
+        "daysAfter": plural(lambda n: t.ngettext("%(count)s day after it", "%(count)s days after it", n)),
+        "perMonth": t.gettext("Commits per month"),
+        "perWeek": t.gettext("Commits per week"),
+        "perDay": t.gettext("Commits per day"),
+        "weekOf": _template(t.gettext("Week of %(date)s")),
+        "window": _template(t.gettext("From %(start)s to %(end)s")),
+        "firstRelease": t.gettext("The first release"),
+        "arrived": _template(t.gettext("Arrived: %(name)s")),
+        "left": _template(t.gettext("Left: %(name)s")),
+        "watched": _template(t.gettext("Watched by Codetrail since %(date)s")),
+        "noReleases": t.gettext("No releases in this window."),
+        "noDeps": t.gettext("No dependency changes in this window."),
+        "notRead": t.gettext("not read"),
+        "area": t.gettext("Guide area"),
+        "folder": t.gettext("Folder"),
+        "file": t.gettext("File"),
+        "mostlyInferred": t.gettext("mostly inferred rationale"),
+        "openArea": t.gettext("Open the area page"),
+        "openFile": t.gettext("Open the file"),
+        "noFiles": t.gettext("No file in it changed in the commits read."),
+        "releases": t.gettext("Releases"),
+        "dependencies": t.gettext("Dependencies"),
+        "wholeHistory": t.gettext("Whole history"),
+        "plotHelp": t.gettext("Use the left and right arrow keys to read each bar."),
+        "calendarHelp": t.gettext(
+            "Commits per day over the last 53 weeks; the numbers by month are in the timeline's table."
+        ),
+        "noAreas": t.gettext("Areas are counted once your assistant has written the guide's area pages."),
+        "noCode": t.gettext("No code to draw yet."),
+        "weekdays": weekday_names(language),
+    }  # fmt: skip
+
+
+def _day(seconds: int) -> str:
+    """The UTC day of a time, or "" for one Python's dates can't hold (past the year 9999)."""
+    try:
+        return datetime.fromtimestamp(seconds, UTC).date().isoformat()
+    except ValueError, OverflowError, OSError:
+        return ""
+
+
+def _top(files: list[HotSpot], keep: Callable[[str], bool]) -> list[list[object]]:
+    return [[spot.name, spot.count] for spot in files if keep(spot.name)][:LISTED_FILES]
+
+
+def _heat(churn: Churn) -> dict[str, Any]:
+    def in_folder(folder: str) -> Callable[[str], bool]:
+        return lambda path: folder_of(path, churn.folder_depth) == folder
+
+    def in_scope(scope: tuple[str, ...]) -> Callable[[str], bool]:
+        prefixes = [part.strip("/") for part in scope]
+        return lambda path: any(not part or path == part or path.startswith(part + "/") for part in prefixes)
+
+    largest_areas = sorted(churn.areas, key=lambda spot: (-spot.lines, spot.page.title))[: churn.tile_cap]
+    areas = [
+        {"name": spot.page.title, "path": spot.page.id, "href": "/pages/" + quote(spot.page.id), "lines": spot.lines,
+         "commits": spot.commits, "documented": spot.documented, "inferred": spot.inferred,
+         "mostlyInferred": spot.inferred > spot.documented * 2, "files": _top(churn.files, in_scope(spot.scope))}
+        for spot in largest_areas
+    ]  # fmt: skip
+    folders = [{"name": tile.name, "path": tile.path, "href": None, "lines": tile.lines, "commits": tile.commits,
+                "files": _top(churn.files, in_folder(tile.path))} for tile in churn.folder_tiles]  # fmt: skip
+    files = [{"name": tile.name, "path": tile.path, "href": "/source/" + quote(tile.path), "lines": tile.lines,
+              "commits": tile.commits} for tile in churn.file_tiles]  # fmt: skip
+    # A tile with no lines of code has no size to draw: it is left out and counted, like the tiles past the cap.
+    levels: dict[str, list[dict[str, Any]]] = {"areas": areas, "folders": folders, "files": files}
+    left_out = dict(churn.left_out)
+    for level, tiles in levels.items():
+        drawn = [tile for tile in tiles if tile["lines"]]
+        left_out[level] = left_out.get(level, 0) + len(tiles) - len(drawn)
+        levels[level] = drawn
+    return {**levels, "leftOut": left_out}
+
+
+def chart_document(report: RepositoryReport, language: Language, today: date) -> dict[str, Any]:
+    """Everything the page's script draws: the timeline, the calendar, the heat map and the area-by-month grid."""
+    activity, releases, churn, inventory = report.activity, report.releases, report.churn, report.inventory
+    days = None
+    if activity is not None and activity.days_start is not None:
+        days = {"start": activity.days_start.isoformat(), "counts": list(activity.days)}
+    release_list = None
+    if releases is not None:
+        release_list = [{"name": tag.name, "date": _day(tag.date), "commit": tag.commit[:7], "notes": tag.message}
+                        for tag in sorted(releases.tags, key=lambda tag: (tag.date, tag.name))]  # fmt: skip
+    deps = [{"name": change.package.split(":", 1)[-1], "sign": sign, "date": change.snapshot.taken_at[:10]}
+            for sign, changes in (("+", inventory.arrived), ("-", inventory.left)) for change in changes]  # fmt: skip
+    grid = None
+    if churn is not None:
+        titles = {spot.page.id: spot.page.title for spot in churn.areas}
+        rows = [{"name": titles.get(page_id, page_id), "cells": list(cells)} for page_id, cells in churn.area_months]
+        grid = {"months": list(churn.months), "rows": rows}
+    return {
+        "lang": language.code,
+        "today": today.isoformat(),
+        "days": days,
+        "releases": release_list,
+        "watchStart": inventory.since.taken_at[:10] if inventory.since else None,
+        "deps": deps,
+        "heat": _heat(churn) if churn is not None else None,
+        "grid": grid,
+        "labels": _labels(language),
+    }
+
+
+def months_table(activity: Activity | None) -> list[tuple[str, int]]:
+    """Commits per month ("YYYY-MM"), oldest first, from the commits per day."""
+    if activity is None or activity.days_start is None:
+        return []
+    months: dict[str, int] = {}
+    for offset, count in enumerate(activity.days):
+        key = (activity.days_start + timedelta(days=offset)).strftime("%Y-%m")
+        months[key] = months.get(key, 0) + count
+    return list(months.items())
+
+
+def bar_heights(values: Sequence[float]) -> list[int]:
+    """Each value as a percent of the highest, for the bars the page draws on the server."""
+    highest = max(values, default=0)
+    return [round(value / highest * 100) if highest else 0 for value in values]
+
+
+def ramp_step(count: int, highest: int) -> int:
+    """The step of the five-step ramp a count falls in: 0 for nothing, then quarters of the highest."""
+    if count <= 0 or highest <= 0:
+        return 0
+    return min(4, 1 + (count * 4 - 1) // highest)
+
+
+def language_segments(languages: Sequence[LanguageSize], keep: int = 4) -> list[tuple[str, int, int, int]]:
+    """The largest languages by lines with their color slot and rounded percent, then the rest as Other."""
+    total = sum(size.lines for size in languages)
+    segments = [(size.language, size.lines, slot) for slot, size in enumerate(languages[:keep], start=1)]
+    rest = sum(size.lines for size in languages[keep:])
+    if rest:
+        segments.append(("Other", rest, keep + 1))
+    return [(name, lines, slot, round(lines / total * 100) if total else 0) for name, lines, slot in segments]
+
+
+def busiest_weekday(activity: Activity | None) -> int | None:
+    """The weekday (0 for Monday) with the most commits, or None without any."""
+    if activity is None or activity.days_start is None or not any(activity.days):
+        return None
+    totals = [0] * 7
+    for offset, count in enumerate(activity.days):
+        totals[(activity.days_start + timedelta(days=offset)).weekday()] += count
+    return totals.index(max(totals))

codetrail/web/security.py

@@ -0,0 +1,171 @@
+"""The page's security model (design section 7.4).
+
+- Only requests whose Host is `127.0.0.1:<port>` or `localhost:<port>` are served (DNS rebinding).
+- Every route but `/login` and `/static/` needs the session cookie, set once from a single-use login code that
+  `codetrail serve` prints; the code expires.
+- Every write (any method but GET and HEAD) needs an Origin equal to the served origin and the per-session token in
+  the `X-Codetrail-Token` header (cross-site request forgery).
+- A request a browser marks as coming from another site or another port (`Sec-Fetch-Site`) is refused.
+- Every response, refusals included, carries the security headers and `Cache-Control: no-store`, unless its route
+  sets its own; static files carry `no-cache`, so the browser revalidates them.
+- The worker that runs D2's WebAssembly build alone gets another Content-Security-Policy: its layout evaluates
+  JavaScript, so it may, but it can import nothing but Go's loader and the ELK layout, reach nothing but its wasm
+  file, and has no DOM (ADRs 0016, 0018).
+Sessions live in memory and end with the process.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+import time
+from collections.abc import Callable
+from http.cookies import SimpleCookie
+
+from starlette.responses import PlainTextResponse, RedirectResponse, Response
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+SESSION_COOKIE = "codetrail_session"
+TOKEN_HEADER = "x-codetrail-token"  # noqa: S105 - a header name, not a secret
+CONTENT_SECURITY_POLICY = (
+    "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; "
+    "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"
+)
+D2_WORKER = "/static/js/d2-worker.js"
+SECURITY_HEADERS = [
+    (b"content-security-policy", CONTENT_SECURITY_POLICY.encode()),
+    (b"x-content-type-options", b"nosniff"),
+    (b"referrer-policy", b"no-referrer"),
+    (b"x-frame-options", b"DENY"),
+    (b"cross-origin-resource-policy", b"same-origin"),
+]
+READ_METHODS = {"GET", "HEAD"}
+OPEN_PATHS = ("/login", "/static/")
+# Reads that return JSON for the page's script also need the token, as defence in depth (design 16.3).
+TOKEN_READS = ("/search/results", "/bridge/answers")
+
+
+class SessionState:
+    """The one reader's session: a single-use login code, the session cookie's value and the write token."""
+
+    def __init__(
+        self, login_code_ttl_seconds: int, clock: Callable[[], float] = time.monotonic, session_minutes: int = 480
+    ) -> None:
+        self._ttl = login_code_ttl_seconds
+        self._clock = clock
+        # Browsers send a cookie to every port of a host, so a session must not outlive its use (design 7.4).
+        self._session_expires = clock() + session_minutes * 60
+        self._code: str | None = None
+        self._code_expires = 0.0
+        self.session_id = secrets.token_urlsafe(32)
+        self.token = secrets.token_urlsafe(32)
+
+    def issue_login_code(self) -> str:
+        self._code = secrets.token_urlsafe(32)
+        self._code_expires = self._clock() + self._ttl
+        return self._code
+
+    def redeem(self, code: str) -> bool:
+        """True once for the issued code, before it expires; the code can't be used again."""
+        expected = self._code
+        if expected is None or not _equal(code, expected):
+            return False
+        self._code = None
+        return self._clock() <= self._code_expires
+
+    def is_session(self, cookie: str | None) -> bool:
+        return cookie is not None and _equal(cookie, self.session_id) and self._clock() <= self._session_expires
+
+    def is_token(self, token: str | None) -> bool:
+        return token is not None and _equal(token, self.token)
+
+
+def _equal(given: str, expected: str) -> bool:
+    return hmac.compare_digest(given.encode(), expected.encode())
+
+
+def login_response(session: SessionState, code: str) -> Response:
+    if not session.redeem(code):
+        return PlainTextResponse("This sign-in link has expired or was already used. Run codetrail serve again.", 403)
+    response = RedirectResponse("/", status_code=303)
+    response.set_cookie(SESSION_COOKIE, session.session_id, httponly=True, samesite="strict", path="/")
+    return response
+
+
+class SecurityMiddleware:
+    def __init__(self, app: ASGIApp, session: SessionState, port: int) -> None:
+        self.app = app
+        self.session = session
+        self.hosts = {f"127.0.0.1:{port}", f"localhost:{port}"}
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            await self.app(scope, receive, send)
+            return
+        if scope["type"] != "http":
+            return  # no websockets
+        refusal = self._refusal(scope)
+        # Static files are revalidated on every load (cheap on 127.0.0.1), so after an upgrade the browser never mixes
+        # last version's styles or script with this version's pages. Everything else may carry the write token or the
+        # guide, so the browser never stores it, unless its route set its own policy (ASVS 14.3.2).
+        is_static = scope["path"].startswith("/static/")
+        replaced = {name for name, _ in SECURITY_HEADERS} | ({b"cache-control"} if is_static else set())
+        security_headers = SECURITY_HEADERS
+        if scope["path"] == D2_WORKER and refusal is None:  # the Host was checked, so it can name the wasm's origin
+            policy = _worker_policy(_headers(scope)["host"]).encode()
+            security_headers = [(name, policy if name == b"content-security-policy" else value)
+                                for name, value in SECURITY_HEADERS]  # fmt: skip
+
+        async def send_with_headers(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                headers = [(name, value) for name, value in message.get("headers", []) if name not in replaced]
+                if not any(name == b"cache-control" for name, _ in headers):
+                    headers.append((b"cache-control", b"no-cache" if is_static else b"no-store"))
+                message["headers"] = headers + security_headers
+            await send(message)
+
+        if refusal is not None:
+            await refusal(scope, receive, send_with_headers)
+            return
+        await self.app(scope, receive, send_with_headers)
+
+    def _refusal(self, scope: Scope) -> Response | None:
+        headers = _headers(scope)
+        host = headers.get("host", "")
+        if host not in self.hosts:
+            return PlainTextResponse("This page is only served at 127.0.0.1 or localhost.", 400)
+        path = scope["path"]
+        if path.startswith("/static/"):
+            return None
+        # Browsers say where a request came from. Only the page itself or the address bar may reach Codetrail, so
+        # another site, or a server on another 127.0.0.1 port (same-site), can't time or drive it (ASVS 3.5.8).
+        if headers.get("sec-fetch-site", "same-origin") not in ("same-origin", "none"):
+            return PlainTextResponse("This request didn't come from Codetrail's page.", 403)
+        if path == "/login":
+            return None
+        cookies = SimpleCookie(headers.get("cookie", ""))
+        cookie = cookies[SESSION_COOKIE].value if SESSION_COOKIE in cookies else None
+        if not self.session.is_session(cookie):
+            return PlainTextResponse("Sign in with the link codetrail serve printed.", 403)
+        if path in TOKEN_READS and not self.session.is_token(headers.get(TOKEN_HEADER)):
+            return PlainTextResponse("This request didn't come from Codetrail's page.", 403)
+        writes = scope["method"] not in READ_METHODS
+        if writes and (
+            headers.get("origin") != f"http://{host}" or not self.session.is_token(headers.get(TOKEN_HEADER))
+        ):
+            return PlainTextResponse("This request didn't come from Codetrail's page.", 403)
+        return None
+
+
+def _headers(scope: Scope) -> dict[str, str]:
+    return {name.decode("latin-1"): value.decode("latin-1") for name, value in scope["headers"]}
+
+
+def _worker_policy(host: str) -> str:
+    """Eval, but only Go's loader and the ELK layout to import, only the wasm file to fetch and no nested workers (which
+    would otherwise fall back to script-src), at the Host already checked."""
+    vendor = f"http://{host}/static/vendor/d2"
+    return (
+        f"default-src 'none'; script-src {vendor}/wasm_exec.js {vendor}/elk.js 'unsafe-eval' 'wasm-unsafe-eval'; "
+        f"connect-src {vendor}/d2.wasm; worker-src 'none'"
+    )

codetrail/web/static/brand/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" role="img" aria-label="codetrail"><title>codetrail</title><rect width="32" height="32" rx="7" fill="#5b5bd6"/><path d="M7 10L13 16L7 22" fill="none" stroke="#fff" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round"/><circle cx="17" cy="22" r="2.5" fill="#fff" fill-opacity=".6"/><circle cx="21" cy="18" r="2.5" fill="#fff" fill-opacity=".85"/><circle cx="25" cy="14" r="2.5" fill="#fff"/></svg>

codetrail/web/static/brand/mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" role="img" aria-label="codetrail"><title>codetrail</title><rect width="32" height="32" rx="7" fill="#5b5bd6"/><path d="M7 10.5L12.5 16L7 21.5" fill="none" stroke="#fff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/><circle cx="16.5" cy="21.5" r="2.25" fill="#fff" fill-opacity=".55"/><circle cx="20.5" cy="17.5" r="2.25" fill="#fff" fill-opacity=".8"/><circle cx="24.5" cy="13.5" r="2.25" fill="#fff"/></svg>