@vibelord/lanes 1.0.3 → 1.1.0

package/payload/lanes/libexec/enrold.py

@@ -0,0 +1,1264 @@
+#!/usr/bin/env python3
+"""lanes-enrold — the tailnet enrolment service (W8 A3, LNS-42).
+
+A new machine gets its SSH key into the workspace account without an admin editing authorized_keys: it redeems an
+invite code, or files a request a member approves. `lanes-enrold.service` runs this file on 127.0.0.1:8184
+(`LANES_ENROL_PORT`; `--port`), behind the loopback Caddy of `lanes-mobile.service` (`handle_path /enrol/*`, which
+strips `/enrol`) behind Tailscale Serve (`https://<host>.<tailnet>.ts.net:8443/enrol/...`). Stdlib only.
+
+Wire contract v1 (JSON; additive only — a client ignores keys it does not know). Request bodies are at most 8 KiB
+(413 above, 411 without a Content-Length):
+
+  POST /redeem   {code, pubkey, device, client_version}
+                 200 {device, owner, ssh_ready: true}       the key is in the lanes-managed block
+                 403 {error: "invalid-or-expired"}          ONE answer for an unknown, expired, revoked or used code
+                                                            and for a key that is not one ssh-ed25519 public key
+                 400 {error: "invalid-device"|"bad-request"}, 409 {error: "device-taken"|"key-taken"} (only after a
+                 valid code: nobody learns device names without one), 429 {error: "rate-limited"} + Retry-After
+                 (5 failures per source in 10 minutes; the source is the client's tailnet address, from the
+                 X-Forwarded-For Serve sets and Caddy keeps — see source_key; a 409 is not a failure: only a valid
+                 code reaches it, and its holder retries with another --device), 503 {error: "server-error"|"busy"}
+  POST /request  {pubkey, device, name?, client_version}   needs request mode, a tailnet login and an allowed domain
+                 202 {id, expires_at}                       24 h; the same login+device+key again returns the same one
+                 403 {error: "requests-disabled"|"no-identity"|"domain-not-allowed"}, 400 {error: "invalid-device"|
+                 "invalid-pubkey"|"invalid-name"|"bad-request"}, 409 device-taken|key-taken, 429 too-many-requests
+                 (3 open requests per login)
+  GET  /request/<id>  {id, state: pending|approved|denied|expired, expires_at}; 404 for another login's request
+  GET  /site     {alias, host_name, host_key, version, request_mode, caller, source}   (`caller` = the login received,
+                 `source` = the rate-limit source derived: both are the operator's live checks of the proxy chain)
+  GET|POST /pending   HTML: the open requests with Approve/Deny forms, for a caller whose login owns a member record
+                 (and passes the domain gate, in request mode; a key added by hand has no owner until `lanes keys
+                 owner <device> <login>` names one). A form carries an HMAC token bound to the caller and the
+                 request (per process: a restart asks for a reload), and a POST is decided only when its
+                 Sec-Fetch-Site is `same-origin` or `none`: cross-site, same-site and ABSENT are refused (every
+                 browser that reaches it through Serve sends the header; curl is not a way to decide —
+                 `lanes enrol approve` is).
+
+Identity is what Tailscale Serve injects for a user's device: `Tailscale-User-Login` / `Tailscale-User-Name` (a
+non-ASCII value RFC 2047-encoded). Whether Serve replaces a header a client sends is the operator's live check
+(RUNBOOK "Enrolment service"): `/site` echoes the login it received as `caller`. `request_mode` comes from, in this
+order: LANES_ENROL_REQUEST_MODE in the environment (1 on, 0 invite-only); the pin `lanes enrol mode request|invite`
+writes to STATE/enrol-mode (read on every request; a pin that cannot be read is invite-only); else the latch — on when
+the FIRST request that came through Tailscale Serve (through_serve: its X-Forwarded-For names a tailnet address) carried
+that header set. A loopback probe never decides it (DEF-1725). The operator pins the mode once the header check
+passes. Serve replaces a forged header only on the tailnet path: a process on this host that reaches loopback can
+send one itself (Caddy and this service cannot tell it from Serve), so request mode is safe only where no account but
+the workspace account and root runs in the host's network namespace (DEF-1645, open; RUNBOOK "Trust boundary").
+In request mode a redeemed invite belongs to the trusted caller: the owner's login and email are the caller's (its
+display name too), whoever the invite was minted for, and the invite's own name and email are kept beside it as the
+member's `invited_as` (invite_owner, invited_as). Without request mode a login is not trusted: /request and /pending
+refuse, and a redeemed invite takes its owner from the invite (invite_owner: its email when that is an address, else
+its name when that is itself a login — a display name never is, and then the member has no owner; no `invited_as`).
+LANES_ENROL_DOMAINS (default beyondwork.ai; comma/space separated, `*` = any) gates /request and /pending.
+
+Stores under ~/.local/state/lanes (L.STATE), every change under keys.members_lock() — the lock `lanes keys` holds for
+members/ and authorized_keys, so the CLI and this service never interleave:
+  invites/<id>.json         written by `lanes invite` (enrol.py, W8 A4): {id, code_sha256, minted_at, minted_by {device,
+                            login, unix_user}, expires_at, name, email, workspaces, redeemed_by, revoked_at};
+                            code_sha256 = sha256 of canonical_code(code); minted_by.login is null from the CLI, so the
+                            member's approved_by is too (minter_login). A redemption adds redeemed_by {device, login,
+                            pubkey_sha256} and redeemed_at; `lanes invite revoke` sets revoked_at. A redeem
+                            compares sha256(code) against EVERY live invite with hmac.compare_digest (no early exit).
+                            For an invite-only server `lanes invite` should record an `email` (or a handle as
+                            `name`): that is where a redeemed member's owner login comes from.
+  enrol-requests/<id>.json  {id, state, login, name, email, device, pubkey, pubkey_sha256, client_version,
+                            created_at, expires_at, decided_by, decided_at}; `expired` is derived, never written.
+                            The opt-in lanes-notify service (notify.py, W8 A5) reads them through load_requests and
+                            pushes one note per new pending request.
+  members/<device>.json     members.py's schema, via invite|request, written through keys.py (save_member, then
+                            write_authorized_keys) — never devices/.
+  enrol-mode                {version: 1, mode: request|invite, set_at, set_by}, written by `lanes enrol mode` (enrol.py,
+                            through write_mode; `auto` removes it); read on every request, never written here.
+  enrol.log                 append-only, one line per attempt: `<UTC> <event> <id> <device> <login> fp=<SHA256:…> <result>`
+                            (`-` for an unknown field). A code is never written anywhere, not even its id half on a miss.
+                            A redeem or approval re-renders the whole block from the members keys.load_members accepts,
+                            so a member file it cannot use loses its line (fail closed): each such file is one line
+                            `<event> <id> <its device> <login> fp=- dropped-member` before the attempt's own, and the
+                            journal names it as `lanes keys` does (report_dropped).
+"""
+import argparse
+import calendar
+import collections
+import email.errors
+import email.header
+import hashlib
+import hmac
+import html
+import ipaddress
+import itertools
+import json
+import os
+import re
+import secrets
+import shutil
+import socket
+import socketserver
+import sys
+import threading
+import time
+import traceback
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lanes_lib as L  # noqa: E402
+import keys as K  # noqa: E402
+import members as M  # noqa: E402
+
+WIRE_VERSION = 1
+DEFAULT_PORT = 8184                    # web/Caddyfile `handle_path /enrol/*` forwards here
+MAX_BODY = 8 * 1024
+DISCARD_LIMIT = 1024 * 1024            # an oversize body is read away up to this, so the 413 reaches the proxy
+CODE_ALPHABET = '23456789abcdefghjkmnpqrstuvwxyz'   # 31 characters: no 0/1/i/l/o; codes are LN-<id4>-<secret12>
+MAX_CODE = 64
+INVITE_TTL = 7 * 86400                 # what `lanes invite` mints (A4); enrold reads expires_at, never this
+REQUEST_TTL = 24 * 3600
+REQUEST_ID_LENGTH = 8
+REDEEM_FAILURES = 5
+REDEEM_WINDOW = 600
+MAX_SOURCES = 4096
+OPEN_REQUESTS = 3
+DEFAULT_DOMAINS = ('beyondwork.ai',)
+HOST_KEY = Path('/etc/ssh/ssh_host_ed25519_key.pub')
+TAILNET_TTL = 300
+INVALID = 'invalid-or-expired'
+LOGIN_HEADER = 'Tailscale-User-Login'
+NAME_HEADER = 'Tailscale-User-Name'
+STATES = ('pending', 'approved', 'denied')     # stored; `expired` is derived from expires_at
+PINNED_MODES = ('request', 'invite')           # STATE/enrol-mode (`lanes enrol mode`); no file = auto
+MODE_VERSION = 1
+ACTIONS = ('approve', 'deny')
+HTML_POLICY = "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"
+_HEX64 = re.compile(r'[0-9a-f]{64}')
+_REQUEST_ID = re.compile(r'[a-z0-9]{1,32}')
+_CLIENT_VERSION = re.compile(r'[A-Za-z0-9._+-]{1,32}')
+_STAMP = re.compile(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ', re.ASCII)
+_LOG_UNSAFE = re.compile(r'[^A-Za-z0-9_.@:+=/-]')
+_SITE_LINE = re.compile(r'^(LANES_[A-Z_]+)=([A-Za-z0-9_.:@/-]*)$')
+_ADDRESS = re.compile(r'[^@\s]+@[^@\s]+\.[^@\s]+')
+
+Caller = collections.namedtuple('Caller', 'login name present')
+NOBODY = Caller(None, None, False)
+
+
+# ------------------------------------------------------------------------------------------------------- basics
+
+def stamp(t):
+    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(t))
+
+
+def parse_stamp(value):
+    """A UTC `YYYY-MM-DDTHH:MM:SSZ` -> epoch seconds, else None (an unreadable expiry is an expired one)."""
+    if not isinstance(value, str) or not _STAMP.fullmatch(value):
+        return None
+    try:
+        return calendar.timegm(time.strptime(value, '%Y-%m-%dT%H:%M:%SZ'))
+    except ValueError:
+        return None
+
+
+def invites_dir():
+    return L.STATE / 'invites'
+
+
+def requests_dir():
+    return L.STATE / 'enrol-requests'
+
+
+def log_path():
+    return L.STATE / 'enrol.log'
+
+
+def mode_path():
+    return L.STATE / 'enrol-mode'
+
+
+# ----------------------------------------------------------------------------------------------- the pinned mode
+# `lanes enrol mode request|invite` (enrol.py) pins request mode in STATE/enrol-mode, so it no longer rests on which
+# request happens to arrive first after each start; `auto` removes the file. The service reads it on every request (a
+# change needs no restart). LANES_ENROL_REQUEST_MODE in the unit's environment still wins over it.
+
+def read_mode():
+    """-> (mode, problem): mode 'request' | 'invite' | None (no pin: auto). A pin that cannot be read as
+    {version: 1, mode: request|invite, set_at, set_by} is 'invite' with the reason — fail closed, never auto: the
+    operator pinned something, and requests stay off until `lanes enrol mode` writes it again."""
+    path = mode_path()
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        return None, None
+    except OSError as error:
+        return 'invite', f'{path} is unreadable ({error.strerror or error})'
+    document = _decoded(data)
+    if not (isinstance(document, dict) and document.get('version') == MODE_VERSION
+            and document.get('mode') in PINNED_MODES):
+        return 'invite', f'{path} is not a version {MODE_VERSION} mode pin'
+    return document['mode'], None
+
+
+def write_mode(mode, set_by, now=None):
+    """Pin `mode` ('request' | 'invite'), or remove the pin for 'auto'. -> the document written (None for auto)."""
+    if mode == 'auto':
+        mode_path().unlink(missing_ok=True)
+        return None
+    if mode not in PINNED_MODES:
+        raise L.LanesError(f'unknown mode {mode}')
+    document = {'version': MODE_VERSION, 'mode': mode, 'set_at': stamp(time.time() if now is None else now),
+                'set_by': set_by}
+    L.STATE.mkdir(parents=True, exist_ok=True)
+    L.atomic_write(mode_path(), _json_bytes(document), mode=0o600)
+    return document
+
+
+def _decoded(data):
+    try:
+        return json.loads(data.decode('utf-8'))
+    except (UnicodeDecodeError, ValueError):
+        return None
+
+
+def version():
+    try:
+        return (L.REPO / 'VERSION').read_text().strip() or 'dev'
+    except OSError:
+        return 'dev'
+
+
+def canonical_code(code):
+    """The form a code is hashed in: blanks removed, lower case (codes are case-insensitive)."""
+    return ''.join(code.split()).lower()
+
+
+def code_sha256(code):
+    """invites/<id>.json `code_sha256`: hex sha256 of canonical_code(code). `lanes invite` (A4) stores this."""
+    return hashlib.sha256(canonical_code(code).encode('utf-8')).hexdigest()
+
+
+def parse_domains(value):
+    """LANES_ENROL_DOMAINS -> a tuple of lower-case domains (`*` = any); unset or blank = DEFAULT_DOMAINS."""
+    domains = tuple(part.lower() for part in re.split(r'[,\s]+', value or '') if part)
+    return domains or DEFAULT_DOMAINS
+
+
+def through_serve(forwarded, peer):
+    """Whether a request came the Tailscale Serve way: its rate-limit source (source_key) is an address that is not
+    loopback — Serve sets X-Forwarded-For to the client's tailnet address and Caddy keeps it. A probe of 127.0.0.1:8184,
+    or of Caddy from this host, has none: it says nothing about what Serve injects, so it never decides request mode."""
+    try:
+        return not ipaddress.ip_address(source_key(forwarded, peer)).is_loopback
+    except ValueError:
+        return False
+
+
+def source_key(forwarded, peer):
+    """The rate-limit source: the last X-Forwarded-For hop before the loopback proxies, else the socket peer. Tailscale
+    Serve SETS X-Forwarded-For to the client's tailnet address and connects from 127.0.0.1; the shipped Caddyfile
+    trusts that loopback peer (`trusted_proxies 127.0.0.0/8` on the /enrol/* route), so Caddy keeps the header and
+    appends its peer — `<100.x client>, 127.0.0.1` — and each tailnet device is its own bucket. A Caddy that does not
+    trust the peer replaces the header with `127.0.0.1`: then every device shares one bucket (fail closed, DEF-1641).
+    `/site` echoes the result as `source`, the operator's live check."""
+    hops = [part.strip() for part in (forwarded or '').split(',') if part.strip()]
+    while hops:
+        try:
+            if not ipaddress.ip_address(hops[-1]).is_loopback:
+                break
+        except ValueError:
+            break
+        hops.pop()
+    return (hops[-1] if hops else peer)[:64]
+
+
+def _read_doc(path):
+    try:
+        document = json.loads(Path(path).read_bytes().decode('utf-8'))
+    except (OSError, UnicodeDecodeError, ValueError):
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def _json_bytes(document):
+    try:
+        return (json.dumps(document, indent=2, ensure_ascii=False) + '\n').encode('utf-8')
+    except UnicodeEncodeError:
+        return (json.dumps(document, indent=2) + '\n').encode('ascii')
+
+
+def _private_dir(directory):
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if directory.stat().st_mode & 0o777 != 0o700:
+        os.chmod(directory, 0o700)
+
+
+def _log_field(value):
+    return _LOG_UNSAFE.sub('?', str(value))[:128] if value else '-'
+
+
+def audit(event, ident, device, login, fingerprint, result, now=None):
+    """Append one line to enrol.log (0600). Never raises: a log that cannot be written is said on stderr."""
+    line = ' '.join((stamp(time.time() if now is None else now), _log_field(event), _log_field(ident),
+                     _log_field(device), _log_field(login), 'fp=' + _log_field(fingerprint), _log_field(result)))
+    try:
+        L.STATE.mkdir(parents=True, exist_ok=True)
+        handle = os.open(log_path(), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+        try:
+            os.write(handle, (line + '\n').encode('ascii', 'replace'))
+        finally:
+            os.close(handle)
+    except OSError as error:
+        print(f'lanes-enrold: cannot append to {log_path()}: {error.strerror or error}', file=sys.stderr, flush=True)
+
+
+def report_dropped(event, ident, login, problems, now):
+    """Before a write that re-renders the block from keys.load_members' valid members: each member file it could not
+    use (`problems`, [(file name, reason)]) is left out — fail closed, its line goes — and that is said, never silent
+    (DEF-1729): on stderr as `lanes keys` says it (keys._warn_problems), and one enrol.log line per file with its
+    device and the result `dropped-member`. The reasons are members.py's and keys.py's, which never echo a value."""
+    for name, reason in problems:
+        device = name[:-len('.json')] if name.endswith('.json') else name
+        print(f'lanes-enrold: ⚠ members/{_log_field(name)}: {reason} — NOT authorized (fix or remove the file); '
+              f'{event} {_log_field(ident)} re-rendered the lanes-managed block without it', file=sys.stderr,
+              flush=True)
+        audit(event, ident, device, login, None, 'dropped-member', now)
+
+
+# ----------------------------------------------------------------------------------------------------- identity
+
+def _header_text(raw):
+    """A header value as text: http.server hands values over as latin-1, Tailscale sends UTF-8 or RFC 2047."""
+    if raw is None:
+        return None
+    try:
+        text = raw.encode('latin-1').decode('utf-8')
+    except (UnicodeEncodeError, UnicodeDecodeError):
+        return None
+    if '=?' in text:
+        try:
+            text = str(email.header.make_header(email.header.decode_header(text)))
+        except (ValueError, LookupError, UnicodeError, email.errors.HeaderParseError):
+            return None
+    return text.strip() or None
+
+
+def _valid_name(name):
+    if name is None:
+        return None
+    try:
+        return M.validate_owner({'login': 'x', 'name': name})['name']
+    except L.LanesError:
+        return None
+
+
+def _valid_email(value):
+    """`value` when members.py would store it as an owner's email (an address, printable, no blanks), else None."""
+    if _address(value) is None:
+        return None
+    try:
+        return M.validate_owner({'login': 'x', 'email': value})['email']
+    except L.LanesError:
+        return None
+
+
+def caller_of(headers):
+    """The tailnet identity a request carries -> Caller(login, name, present). `present` = the header set Serve
+    injects (a non-empty login AND a name header, even an empty one); login/name are None when they do not validate
+    as members.py would store them."""
+    raw_login = headers.get(LOGIN_HEADER)
+    present = bool(raw_login and raw_login.strip()) and headers.get(NAME_HEADER) is not None
+    login = _header_text(raw_login)
+    try:
+        login = M.check_login(login) if login else None
+    except L.LanesError:
+        login = None
+    return Caller(login, _valid_name(_header_text(headers.get(NAME_HEADER))), present)
+
+
+def _owner(*candidates):
+    for candidate in candidates:
+        try:
+            return M.validate_owner(candidate)
+        except L.LanesError:
+            continue
+    return None
+
+
+def _address(login):
+    return login if isinstance(login, str) and _ADDRESS.fullmatch(login) else None
+
+
+def _valid_login(value):
+    try:
+        return M.check_login(value) if value is not None else None
+    except L.LanesError:
+        return None
+
+
+def _workspaces(value):
+    if not isinstance(value, list):
+        return []
+    kept = []
+    for workspace in value:
+        if isinstance(workspace, str) and L.IDENT.match(workspace) and len(workspace) <= M.MAX_ID and workspace not in kept:
+            kept.append(workspace)
+    return kept
+
+
+# ------------------------------------------------------------------------------------------------------ invites
+
+def load_invites():
+    """[(id, path, document)] for every readable invites/<id>.json whose stem is an id."""
+    found = []
+    for path in sorted(invites_dir().glob('*.json')):
+        if not L.IDENT.match(path.stem) or len(path.stem) > M.MAX_ID:
+            continue
+        document = _read_doc(path)
+        if document is not None:
+            found.append((path.stem, path, document))
+    return found
+
+
+def invite_live(document, now):
+    """Usable now: a well-formed hash, not used, not revoked, not past expires_at (an unreadable expiry is past)."""
+    expires = parse_stamp(document.get('expires_at'))
+    return (isinstance(document.get('code_sha256'), str) and _HEX64.fullmatch(document['code_sha256']) is not None
+            and document.get('redeemed_by') is None and document.get('revoked_at') is None
+            and expires is not None and now < expires)
+
+
+def match_invite(code, now):
+    """(id, path, digest) of the live invite whose hash is sha256(code), else None. The digest is compared against
+    EVERY live invite (hmac.compare_digest, the loop never stops early), so the time taken says nothing about which
+    invite, if any, matched; dead invites are never candidates, so expired/revoked/used look like unknown."""
+    presented = canonical_code(code) if isinstance(code, str) and len(code) <= MAX_CODE and code.isascii() else ''
+    digest = hashlib.sha256(presented.encode('ascii')).hexdigest()
+    found = None
+    for invite_id, path, document in load_invites():
+        if invite_live(document, now) and hmac.compare_digest(digest, document['code_sha256']) and found is None:
+            found = (invite_id, path, digest)
+    return found if presented else None
+
+
+def minter_login(invite):
+    """The login that minted `invite`, as the member's `approved_by`, or None. `lanes invite` (A4) writes `minted_by`
+    as {device, login, unix_user} with `login` null: over SSH every login is the one Unix account, so the CLI claims
+    no tailnet login, and an invite it minted yields a member approved by nobody named (DEF-1646)."""
+    minted = invite.get('minted_by')
+    return _valid_login(minted.get('login')) if isinstance(minted, dict) else None
+
+
+def invite_owner(invite, caller):
+    """The member owner a redeemed invite records, or None.
+    With a TRUSTED caller (request mode: a validated tailnet login) the member is the caller's: login, email (the login
+    when it is an address) and display name all come from the caller, never from the invite — an invite minted for
+    anna@ and redeemed by otto@ is otto@'s device, and the invite's own name and email go to `invited_as` beside it
+    (invited_as; DEF-1732). Without one, the login comes only from something that IS a login: the invite's email when
+    it is an address, else the invite's name when it is itself a login (a handle such as `anna`). A display name such
+    as "Anna Berg" is never a login (members.check_login refuses blanks), so an invite that names only that records no
+    owner: the member keeps its invite_id, the invite file keeps the name, and `lanes keys owner` names the owner later
+    (DEF-1644)."""
+    if caller.login:
+        login, email = caller.login, _address(caller.login)
+        return _owner({'login': login, 'name': caller.name, 'email': email},
+                      {'login': login, 'name': None, 'email': email}, {'login': login, 'name': None, 'email': None})
+    login = next((value for value in (_address(invite.get('email')), invite.get('name')) if _valid_login(value)), None)
+    if login is None:
+        return None
+    name = invite.get('name') or caller.name
+    email = _address(invite.get('email'))
+    return _owner({'login': login, 'name': name, 'email': email}, {'login': login, 'name': name, 'email': None},
+                  {'login': login, 'name': None, 'email': None})
+
+
+def invited_as(invite):
+    """The invite's own {name, email} as a member records it beside a trusted caller's owner (`invited_as`): each the
+    value members.py would store, else null — an invite file's text never reaches a member record unchecked."""
+    return {'name': _valid_name(invite.get('name')), 'email': _valid_email(invite.get('email'))}
+
+
+# ---------------------------------------------------------------------------------------------- shared checks
+
+def device_taken(device, data):
+    """Whether `device` already names a member, a view device, or a `lanes:<device>` line in or outside the block of
+    authorized_keys `data` (malformed markers raise L.LanesError)."""
+    if (K.members_dir() / f'{device}.json').exists() or (L.STATE / 'devices' / f'{device}.json').exists():
+        return True
+    if K.block_entries(data, device):
+        return True
+    return any(K._lanes_device(parsed) == device for _, _, parsed in K.outside_entries(data))
+
+
+def _authorized_keys():
+    """(path, bytes) of authorized_keys, its markers checked: raises L.LanesError (malformed) or OSError."""
+    path = K.authorized_keys_path()
+    data = K._read(path)
+    K.split_block(data)
+    return path, data
+
+
+def _block_lacks(path, members, device):
+    """After a failed block write: re-render without `device` (best effort) and read back whether the block is free of
+    it. True only when that is known — the caller then may drop the member file without leaving a line behind it."""
+    try:
+        K.write_authorized_keys(path, members)
+    except (OSError, L.LanesError):
+        pass
+    try:
+        return not K.block_entries(K._read(path), device)
+    except (OSError, L.LanesError):
+        return False
+
+
+# ------------------------------------------------------------------------------------------------------- redeem
+
+def redeem(fields, caller=None, now=None):
+    """POST /redeem -> (status, payload). `caller` is the TRUSTED tailnet identity (None outside request mode)."""
+    now = time.time() if now is None else now
+    caller = caller or NOBODY
+    try:
+        device = M.device_name(fields.get('device'))
+    except L.LanesError:
+        audit('redeem', None, None, caller.login, None, 'invalid-device', now)
+        return 400, {'error': 'invalid-device'}
+    try:
+        pubkey = K.parse_pubkey(fields['pubkey']) if isinstance(fields.get('pubkey'), str) else None
+    except L.LanesError:
+        pubkey = None
+    fingerprint = K.fingerprint(pubkey) if pubkey else None
+    match = match_invite(fields.get('code'), now)
+    if match is None or pubkey is None:
+        audit('redeem', None, device, caller.login, fingerprint, INVALID, now)
+        return 403, {'error': INVALID}
+    try:
+        with K.members_lock():
+            return _redeem_locked(match, device, pubkey, fingerprint, caller, now)
+    except L.LanesError:                                    # only the lock raises out of _redeem_locked
+        audit('redeem', match[0], device, caller.login, fingerprint, 'busy', now)
+        return 503, {'error': 'busy'}
+
+
+def _redeem_locked(match, device, pubkey, fingerprint, caller, now):
+    invite_id, path, digest = match
+    invite = _read_doc(path)
+    if invite is None or not invite_live(invite, now) or not hmac.compare_digest(digest, invite['code_sha256']):
+        audit('redeem', None, device, caller.login, fingerprint, INVALID, now)     # used while we waited
+        return 403, {'error': INVALID}
+    try:
+        ak, data = _authorized_keys()
+        taken = device_taken(device, data)
+        members, problems = K.load_members()
+        owner = invite_owner(invite, caller)
+        record = K.member_record(device, pubkey, via='invite', now=now, owner=owner,
+                                 approved_by=minter_login(invite), invite_id=invite_id,
+                                 workspaces=_workspaces(invite.get('workspaces')),
+                                 **({'invited_as': invited_as(invite)} if caller.login else {}))
+        original = path.read_bytes()
+    except (OSError, L.LanesError) as error:
+        print(f'lanes-enrold: redeem {invite_id}: {error}', file=sys.stderr, flush=True)
+        audit('redeem', invite_id, device, caller.login, fingerprint, 'server-error', now)
+        return 503, {'error': 'server-error'}
+    who = owner['login'] if owner else caller.login
+    if taken:
+        audit('redeem', invite_id, device, who, fingerprint, 'device-taken', now)
+        return 409, {'error': 'device-taken'}
+    if any(member['pubkey'] == pubkey for member in members):
+        audit('redeem', invite_id, device, who, fingerprint, 'key-taken', now)
+        return 409, {'error': 'key-taken'}
+    consumed = dict(invite, redeemed_by={'device': device, 'login': who, 'pubkey_sha256': fingerprint},
+                    redeemed_at=stamp(now))
+    try:
+        L.atomic_write(path, _json_bytes(consumed), mode=0o600)    # used up FIRST: a crash never leaves it reusable
+    except OSError as error:
+        print(f'lanes-enrold: cannot mark invite {invite_id} used: {error.strerror}', file=sys.stderr, flush=True)
+        audit('redeem', invite_id, device, who, fingerprint, 'server-error', now)
+        return 503, {'error': 'server-error'}
+    report_dropped('redeem', invite_id, who, problems, now)          # the writes below re-render the block
+    try:
+        K.save_member(record)                                       # the record before its line (keys.py's order)
+        K.write_authorized_keys(ak, members + [record])
+    except (OSError, L.LanesError) as error:
+        print(f'lanes-enrold: redeem {invite_id} for {device}: {error}', file=sys.stderr, flush=True)
+        if _block_lacks(ak, members, device):                       # nothing lets it in: undo the record and the use
+            try:
+                (K.members_dir() / f'{device}.json').unlink(missing_ok=True)
+                L.atomic_write(path, original, mode=0o600)
+            except OSError as undo:
+                print(f'lanes-enrold: undo of {invite_id} incomplete: {undo.strerror}', file=sys.stderr, flush=True)
+        audit('redeem', invite_id, device, who, fingerprint, 'server-error', now)
+        return 503, {'error': 'server-error'}
+    if owner is None:                                               # said, never silent (DEF-1644)
+        print(f'lanes-enrold: invite {invite_id} names no login (no trusted tailnet login, no email address, and its '
+              f'name is not a login): members/{device}.json has no owner — `lanes keys owner {device} <login>` '
+              'names one', file=sys.stderr, flush=True)
+    audit('redeem', invite_id, device, who, fingerprint, 'ok', now)
+    return 200, {'device': device, 'owner': owner, 'ssh_ready': True}
+
+
+# ----------------------------------------------------------------------------------------------------- requests
+
+def _valid_request(document, stem):
+    try:
+        return bool(document.get('id') == stem and _REQUEST_ID.fullmatch(stem) and document.get('state') in STATES
+                    and M.device_name(document.get('device'))
+                    and M.validate_owner({'login': document.get('login'), 'name': document.get('name'),
+                                          'email': document.get('email')})
+                    and isinstance(document.get('pubkey'), str)
+                    and K.parse_pubkey(document['pubkey']) == document['pubkey']
+                    and parse_stamp(document.get('expires_at')) is not None)
+    except L.LanesError:
+        return False
+
+
+def load_requests(directory=None):
+    """Every valid enrol-requests/<id>.json, oldest first (invalid files are skipped). `directory` defaults to
+    requests_dir(); notify.py (W8 A5) passes the enrol-requests/ of the STATE it watches."""
+    found = []
+    for path in sorted(Path(directory if directory is not None else requests_dir()).glob('*.json')):
+        document = _read_doc(path)
+        if document is not None and _valid_request(document, path.stem):
+            found.append(document)
+    return sorted(found, key=lambda document: (document.get('created_at') or '', document['id']))
+
+
+def read_request(request_id):
+    """The valid request `request_id` (case-insensitive), else None."""
+    if not isinstance(request_id, str):
+        return None
+    request_id = request_id.lower()
+    if not _REQUEST_ID.fullmatch(request_id):
+        return None
+    document = _read_doc(requests_dir() / f'{request_id}.json')
+    return document if document is not None and _valid_request(document, request_id) else None
+
+
+def request_state(document, now):
+    if document['state'] == 'pending' and now >= parse_stamp(document['expires_at']):
+        return 'expired'
+    return document['state']
+
+
+def _write_request(document):
+    _private_dir(requests_dir())
+    L.atomic_write(requests_dir() / f"{document['id']}.json", _json_bytes(document), mode=0o600)
+
+
+def _new_request_id():
+    while True:
+        candidate = ''.join(secrets.choice(CODE_ALPHABET) for _ in range(REQUEST_ID_LENGTH))
+        if not (requests_dir() / f'{candidate}.json').exists():
+            return candidate
+
+
+def create_request(fields, caller, now=None):
+    """POST /request -> (status, payload). `caller` is the TRUSTED identity: the HTTP layer has checked request mode,
+    the login and the domain."""
+    now = time.time() if now is None else now
+    login = caller.login
+    try:
+        device = M.device_name(fields.get('device'))
+    except L.LanesError:
+        audit('request', None, None, login, None, 'invalid-device', now)
+        return 400, {'error': 'invalid-device'}
+    try:
+        pubkey = K.parse_pubkey(fields['pubkey']) if isinstance(fields.get('pubkey'), str) else None
+    except L.LanesError:
+        pubkey = None
+    if pubkey is None:
+        audit('request', None, device, login, None, 'invalid-pubkey', now)
+        return 400, {'error': 'invalid-pubkey'}
+    fingerprint = K.fingerprint(pubkey)
+    name = fields.get('name')
+    if name is not None:
+        try:
+            name = M.validate_owner({'login': login, 'name': L._title(name)})['name']
+        except L.LanesError:
+            audit('request', None, device, login, fingerprint, 'invalid-name', now)
+            return 400, {'error': 'invalid-name'}
+    owner = _owner({'login': login, 'name': name or caller.name, 'email': _address(login)},
+                   {'login': login, 'name': None, 'email': _address(login)})
+    if owner is None:
+        return 403, {'error': 'no-identity'}
+    client = fields.get('client_version')
+    client = client if isinstance(client, str) and _CLIENT_VERSION.fullmatch(client) else None
+    try:
+        with K.members_lock():
+            pending = [r for r in load_requests() if request_state(r, now) == 'pending']
+            mine = [r for r in pending if r['login'].casefold() == login.casefold()]
+            for request in mine:
+                if request['device'] == device and request['pubkey'] == pubkey:
+                    return 202, {'id': request['id'], 'expires_at': request['expires_at']}
+            if len(mine) >= OPEN_REQUESTS:
+                audit('request', None, device, login, fingerprint, 'too-many-requests', now)
+                return 429, {'error': 'too-many-requests'}
+            try:
+                _, data = _authorized_keys()
+                taken = device_taken(device, data) or any(r['device'] == device for r in pending)
+                members, _problems = K.load_members()
+            except (OSError, L.LanesError) as error:
+                print(f'lanes-enrold: request for {device}: {error}', file=sys.stderr, flush=True)
+                audit('request', None, device, login, fingerprint, 'server-error', now)
+                return 503, {'error': 'server-error'}
+            if taken:
+                audit('request', None, device, login, fingerprint, 'device-taken', now)
+                return 409, {'error': 'device-taken'}
+            if any(m['pubkey'] == pubkey for m in members) or any(r['pubkey'] == pubkey for r in pending):
+                audit('request', None, device, login, fingerprint, 'key-taken', now)
+                return 409, {'error': 'key-taken'}
+            document = {'id': _new_request_id(), 'state': 'pending', 'login': owner['login'], 'name': owner['name'],
+                        'email': owner['email'], 'device': device, 'pubkey': pubkey, 'pubkey_sha256': fingerprint,
+                        'client_version': client, 'created_at': stamp(now), 'expires_at': stamp(now + REQUEST_TTL),
+                        'decided_by': None, 'decided_at': None}
+            try:
+                _write_request(document)
+            except OSError as error:
+                print(f'lanes-enrold: cannot write a request: {error.strerror}', file=sys.stderr, flush=True)
+                audit('request', None, device, login, fingerprint, 'server-error', now)
+                return 503, {'error': 'server-error'}
+    except L.LanesError:                                    # the lock
+        return 503, {'error': 'busy'}
+    audit('request', document['id'], device, login, fingerprint, 'pending', now)
+    return 202, {'id': document['id'], 'expires_at': document['expires_at']}
+
+
+def decide(request_id, action, approver, now=None):
+    """Approve or deny a pending request as `approver` (a login) -> the updated request document. Approval writes the
+    member (via request, approved_by) and its line through keys.py. Raises L.LanesError with a sentence on every
+    refusal: no such request, not pending, the device or key taken since, a write that failed (nothing is left
+    authorized by a failed approval). `lanes enrol approve|deny` (A4) and POST /pending both call this."""
+    now = time.time() if now is None else now
+    if action not in ACTIONS:
+        raise L.LanesError(f'unknown action {action!r}: approve or deny')
+    approver = M.check_login(approver, 'approver')
+    shown = request_id.lower() if isinstance(request_id, str) and _REQUEST_ID.fullmatch(request_id.lower()) else '?'
+    with K.members_lock():
+        document = read_request(request_id)
+        if document is None:
+            raise L.LanesError(f'no enrolment request {shown}')
+        try:
+            state = request_state(document, now)
+            if state != 'pending':
+                raise L.LanesError(f"request {document['id']} is {state}, not pending")
+            if action == 'approve':
+                _approve_locked(document, approver, now)
+            document = dict(document, state='approved' if action == 'approve' else 'denied', decided_by=approver,
+                            decided_at=stamp(now))
+            try:
+                _write_request(document)
+            except OSError as error:
+                raise L.LanesError(f"request {document['id']}: the decision could not be recorded "
+                                   f'({error.strerror}); ' + ('the key IS authorized — run the approval again to '
+                                                              'record it' if action == 'approve' else
+                                                              'run the denial again')) from None
+        except L.LanesError as error:
+            audit(action, document['id'], document['device'], approver, document['pubkey_sha256'], 'refused', now)
+            raise error
+    audit(action, document['id'], document['device'], approver, document['pubkey_sha256'], 'ok', now)
+    return document
+
+
+def _approve_locked(document, approver, now):
+    device, pubkey = document['device'], document['pubkey']
+    try:
+        ak, data = _authorized_keys()
+    except OSError as error:
+        raise L.LanesError(f'cannot read authorized_keys ({error.strerror}); nothing changed') from None
+    members, problems = K.load_members()
+    current = next((m for m in members if m['device'] == device), None)
+    if current is not None and current['pubkey'] == pubkey and current.get('request_id') == document['id']:
+        report_dropped('approve', document['id'], approver, problems, now)
+        try:
+            K.write_authorized_keys(ak, members)    # an approval interrupted after its member write: finish it
+        except OSError as error:
+            raise L.LanesError(f'cannot write {ak} ({error.strerror}); members/{device}.json is kept — the same '
+                               'approval again finishes it') from None
+        return
+    if device_taken(device, data):
+        raise L.LanesError(f'device {device} is already enrolled or in use since the request; deny it and ask for '
+                           'another device name')
+    holder = next((m['device'] for m in members if m['pubkey'] == pubkey), None)
+    if holder:
+        raise L.LanesError(f'that key is already enrolled as {holder}')
+    owner = M.validate_owner({'login': document['login'], 'name': document.get('name'),
+                              'email': document.get('email')})
+    record = K.member_record(device, pubkey, via='request', now=now, owner=owner, approved_by=approver,
+                             request_id=document['id'])
+    try:
+        K.save_member(record)
+    except OSError as error:
+        (K.members_dir() / f'{device}.json').unlink(missing_ok=True)
+        raise L.LanesError(f'cannot write members/{device}.json ({error.strerror}); nothing was authorized') from None
+    report_dropped('approve', document['id'], approver, problems, now)    # the write below re-renders the block
+    try:
+        K.write_authorized_keys(ak, members + [record])
+    except (OSError, L.LanesError) as error:
+        reason = getattr(error, 'strerror', None) or str(error)
+        if _block_lacks(ak, members, device):
+            (K.members_dir() / f'{device}.json').unlink(missing_ok=True)
+            raise L.LanesError(f'cannot write {ak} ({reason}); nothing was authorized') from None
+        raise L.LanesError(f'cannot write {ak} ({reason}); members/{device}.json is kept — `lanes keys revoke '
+                           f'{device}` or the same approval again finishes it') from None
+
+
+def member_logins():
+    """The logins (case-folded) that own a valid member record: who may see and decide requests."""
+    members, _problems = K.load_members()
+    return {m['owner']['login'].casefold() for m in members if isinstance(m.get('owner'), dict)}
+
+
+# ------------------------------------------------------------------------------------------------------- /site
+
+_TAILNET = {'at': None, 'name': None}
+_TAILNET_LOCK = threading.Lock()
+
+
+def server_site():
+    """The server's own ~/.config/lanes/site.conf LANES_* facts (the file `lanes client-config` serves)."""
+    try:
+        lines = (Path.home() / '.config/lanes/site.conf').read_text().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return {}
+    return dict(found.groups() for found in map(_SITE_LINE.match, lines) if found)
+
+
+def tailnet_name():
+    """This node's MagicDNS name from `tailscale status --json` (bounded, cached for TAILNET_TTL s), else None."""
+    with _TAILNET_LOCK:
+        if _TAILNET['at'] is not None and time.monotonic() - _TAILNET['at'] < TAILNET_TTL:
+            return _TAILNET['name']
+        name = None
+        if shutil.which('tailscale'):
+            code, out, _err = L.run_bounded(['tailscale', 'status', '--json'], 10)
+            if code == 0:
+                try:
+                    name = ((json.loads(out).get('Self') or {}).get('DNSName') or '').rstrip('.') or None
+                except (ValueError, AttributeError, TypeError):
+                    name = None
+        _TAILNET.update(at=time.monotonic(), name=name)
+        return name
+
+
+def host_key():
+    """The server's ed25519 host key as `ssh-ed25519 <base64>` (comment dropped), best effort: None when absent."""
+    try:
+        return K.parse_pubkey(HOST_KEY.read_text()[:K.MAX_PUBKEY_FILE])
+    except (OSError, UnicodeDecodeError, L.LanesError):
+        return None
+
+
+def site_facts(caller, request_mode, source=None):
+    site = server_site()
+    return {'alias': site.get('LANES_SERVER_ALIAS') or socket.gethostname().split('.')[0] or None,
+            'host_name': site.get('LANES_SERVER_NAME') or tailnet_name(),
+            'host_key': host_key(), 'version': version(), 'request_mode': request_mode, 'caller': caller.login,
+            'source': source}
+
+
+# --------------------------------------------------------------------------------------------------- the service
+
+class Service:
+    """Process-wide state: configuration, the request-mode latch, the redeem rate limiter and the form secret."""
+
+    def __init__(self, domains=None, request_mode=None, clock=time.time):
+        self.domains = tuple(domains) if domains else DEFAULT_DOMAINS
+        self.forced = request_mode
+        self.clock = clock
+        self.secret = secrets.token_bytes(32)
+        self._first = None
+        self._pin_problem = None
+        self._lock = threading.Lock()
+        self._attempts = {}
+        self._tokens = itertools.count(1)
+
+    @classmethod
+    def from_environ(cls, environ):
+        forced = {'1': True, '0': False}.get((environ.get('LANES_ENROL_REQUEST_MODE') or '').strip())
+        return cls(domains=parse_domains(environ.get('LANES_ENROL_DOMAINS')), request_mode=forced)
+
+    def observe(self, caller, via_serve=True):
+        """The auto latch: the first request that came through Serve (through_serve) decides, for the life of the
+        process, whether Serve injects identity. Anything else — a loopback probe — decides nothing."""
+        if not via_serve:
+            return
+        with self._lock:
+            if self._first is None:
+                self._first = bool(caller.present)
+
+    @property
+    def request_mode(self):
+        """The unit's LANES_ENROL_REQUEST_MODE, else the pin `lanes enrol mode` wrote, else the latch."""
+        if self.forced is not None:
+            return self.forced
+        pinned = self.pinned()
+        return pinned == 'request' if pinned is not None else bool(self._first)
+
+    def pinned(self):
+        mode, problem = read_mode()
+        if problem and problem != self._pin_problem:      # said once per new problem, not on every request
+            print(f'lanes-enrold: {problem}: requests are refused until `lanes enrol mode request|invite|auto` '
+                  'writes it again', file=sys.stderr, flush=True)
+        self._pin_problem = problem
+        return mode
+
+    def mode_source(self):
+        """How request mode is decided now, in words (the start line; `lanes enrol mode` says the same)."""
+        if self.forced is not None:
+            return f"{'on' if self.forced else 'off'} (LANES_ENROL_REQUEST_MODE in the environment)"
+        pinned = self.pinned()
+        if pinned is not None:
+            return f"{'on' if pinned == 'request' else 'off'} (pinned: {mode_path()})"
+        return {None: 'decided by the first request through Tailscale Serve', True: 'on (the first request through '
+                'Serve carried an identity)', False: 'off (the first request through Serve carried no identity)'}[
+                    self._first]
+
+    def domain_ok(self, login):
+        if '*' in self.domains:
+            return True
+        return '@' in login and login.rpartition('@')[2].lower() in self.domains
+
+    def gate(self, caller):
+        """None when `caller` may file or decide requests, else the refusal's error word."""
+        if not self.request_mode:
+            return 'requests-disabled'
+        if not caller.login:
+            return 'no-identity'
+        if not self.domain_ok(caller.login):
+            return 'domain-not-allowed'
+        return None
+
+    # The limiter counts an attempt when it STARTS (check and count are one step, so a burst cannot run five wrong
+    # codes in parallel past it) and forgets it when it succeeds or ends in a 409, which only a valid code reaches.
+    def _recent(self, source, now):
+        kept = [entry for entry in self._attempts.get(source, ()) if now - entry[1] < REDEEM_WINDOW]
+        if kept:
+            self._attempts[source] = kept
+        else:
+            self._attempts.pop(source, None)
+        return kept
+
+    def attempt(self, source):
+        """-> (token, 0) when `source` may try a code now, else (None, seconds to wait)."""
+        now = self.clock()
+        with self._lock:
+            recent = self._recent(source, now)
+            if len(recent) >= REDEEM_FAILURES:
+                return None, int(recent[0][1] + REDEEM_WINDOW - now) + 1
+            token = next(self._tokens)
+            self._attempts[source] = recent + [(token, now)]
+            if len(self._attempts) > MAX_SOURCES:
+                for other in list(self._attempts):
+                    self._recent(other, now)
+                while len(self._attempts) > MAX_SOURCES:
+                    self._attempts.pop(min(self._attempts, key=lambda key: self._attempts[key][-1][1]))
+            return token, 0
+
+    def succeeded(self, source, token):
+        with self._lock:
+            kept = [entry for entry in self._attempts.get(source, ()) if entry[0] != token]
+            if kept:
+                self._attempts[source] = kept
+            else:
+                self._attempts.pop(source, None)
+
+    def token(self, login, request_id):
+        """The form token for `login` deciding `request_id` (HMAC under this process's secret)."""
+        message = f'{login.casefold()}\0{request_id}'.encode('utf-8')
+        return hmac.new(self.secret, message, hashlib.sha256).hexdigest()[:32]
+
+
+# ---------------------------------------------------------------------------------------------------- the page
+
+def pending_page(service, caller, now, message=None):
+    rows = []
+    for request in load_requests():
+        if request_state(request, now) != 'pending':
+            continue
+        e = {key: html.escape(str(request.get(key) or '-')) for key in
+             ('id', 'login', 'name', 'device', 'pubkey_sha256', 'created_at', 'expires_at', 'client_version')}
+        rows.append(
+            f'<li><p><b>{e["name"]}</b> &lt;{e["login"]}&gt;<br>device <code>{e["device"]}</code> · key '
+            f'<code>{e["pubkey_sha256"]}</code><br><small>asked {e["created_at"]} · expires {e["expires_at"]} · '
+            f'client {e["client_version"]} · request <code>{e["id"]}</code></small></p>'
+            f'<form method="post" action="pending"><input type="hidden" name="id" value="{e["id"]}">'
+            f'<input type="hidden" name="token" value="{service.token(caller.login, request["id"])}">'
+            '<button name="action" value="approve">Approve</button> '
+            '<button name="action" value="deny">Deny</button></form></li>')
+    body = f'<ul>{"".join(rows)}</ul>' if rows else '<p>No pending requests.</p>'
+    note = f'<p class="note">{html.escape(message)}</p>' if message else ''
+    return _page('Enrolment requests', f'<p class="who">Signed in as {html.escape(caller.login)}</p>{note}{body}'
+                 '<p class="who">On the server: <code>lanes enrol list</code> · <code>lanes enrol approve '
+                 '&lt;id&gt;</code></p>')
+
+
+def _page(title, content):
+    return ('<!doctype html><html lang="en"><head><meta charset="utf-8">'
+            '<meta name="viewport" content="width=device-width, initial-scale=1">'
+            f'<title>{html.escape(title)}</title><style>'
+            ':root{color-scheme:light dark;font:16px/1.45 system-ui,sans-serif}'
+            'body{margin:0 auto;max-width:40rem;padding:1rem}ul{list-style:none;padding:0}'
+            'li{border:1px solid #8885;border-radius:.5rem;margin:.75rem 0;padding:.25rem .75rem .75rem}'
+            'code{font-size:.85em;word-break:break-all}button{font:inherit;padding:.4rem 1rem;margin-right:.5rem}'
+            '.who{opacity:.7}.note{border-left:3px solid #888;padding-left:.5rem}'
+            f'</style></head><body><h1>{html.escape(title)}</h1>{content}</body></html>').encode('utf-8')
+
+
+# -------------------------------------------------------------------------------------------------------- HTTP
+
+class _Reply(Exception):
+    def __init__(self, status, error):
+        super().__init__(error)
+        self.status, self.error = status, error
+
+
+class Handler(BaseHTTPRequestHandler):
+    server_version = 'lanes-enrold'
+    timeout = 15
+    ROUTES = {'/site': ('GET',), '/redeem': ('POST',), '/request': ('POST',), '/pending': ('GET', 'POST')}
+
+    def version_string(self):
+        return self.server_version
+
+    def log_message(self, format, *args):          # no access log: enrol.log is the record, the journal the errors
+        pass
+
+    def do_GET(self):
+        self._route('GET')
+
+    def do_POST(self):
+        self._route('POST')
+
+    # ------------------------------------------------------------------------------------------- plumbing
+
+    def _send(self, status, body, content_type, headers=()):
+        if self.command == 'POST' and not self._body_read:
+            self._discard()                        # an unread body would reset the proxy's connection
+        self.send_response(status)
+        self.send_header('Content-Type', content_type)
+        self.send_header('Content-Length', str(len(body)))
+        self.send_header('Cache-Control', 'no-store')
+        self.send_header('X-Content-Type-Options', 'nosniff')
+        for name, value in headers:
+            self.send_header(name, value)
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _json(self, status, payload, headers=()):
+        self._send(status, json.dumps(payload).encode('utf-8'), 'application/json; charset=utf-8', headers)
+
+    def _html(self, status, body):
+        self._send(status, body, 'text/html; charset=utf-8',
+                   (('Content-Security-Policy', HTML_POLICY), ('X-Frame-Options', 'DENY'),
+                    ('Referrer-Policy', 'no-referrer')))
+
+    def _discard(self):
+        self._body_read = True
+        try:
+            left = min(max(int(self.headers.get('Content-Length') or 0), 0), DISCARD_LIMIT)
+        except ValueError:
+            left = 0
+        try:
+            while left > 0:
+                chunk = self.rfile.read(min(left, 65536))
+                if not chunk:
+                    break
+                left -= len(chunk)
+        except OSError:
+            pass
+        self.close_connection = True
+
+    def _body(self):
+        if self.headers.get('Transfer-Encoding') is not None:
+            self._body_read = True                 # chunked bodies are not read: answer and close
+            raise _Reply(411, 'length-required')
+        length = self.headers.get('Content-Length')
+        if length is None:
+            raise _Reply(411, 'length-required')
+        try:
+            size = int(length)
+        except ValueError:
+            size = -1
+        if size < 0:
+            self._body_read = True
+            raise _Reply(400, 'bad-request')
+        if size > MAX_BODY:
+            self._discard()
+            raise _Reply(413, 'too-large')
+        data = self.rfile.read(size)
+        self._body_read = True
+        if len(data) != size:
+            raise _Reply(400, 'bad-request')
+        return data
+
+    def _json_body(self):
+        data = self._body()
+        try:
+            document = json.loads(data.decode('utf-8'))
+        except (UnicodeDecodeError, ValueError):
+            raise _Reply(400, 'bad-request') from None
+        if not isinstance(document, dict):
+            raise _Reply(400, 'bad-request')
+        return document
+
+    # --------------------------------------------------------------------------------------------- routes
+
+    def _route(self, method):
+        self._body_read = False
+        service = self.server.service
+        try:
+            caller = caller_of(self.headers)
+            service.observe(caller, through_serve(self.headers.get('X-Forwarded-For'), self.client_address[0]))
+            path = urllib.parse.urlsplit(self.path).path
+            request_id = path[len('/request/'):] if path.startswith('/request/') else None
+            allowed = ('GET',) if request_id is not None else self.ROUTES.get(path)
+            if allowed is None:
+                return self._json(404, {'error': 'not-found'})
+            if method not in allowed:
+                return self._json(405, {'error': 'method-not-allowed'}, (('Allow', ', '.join(allowed)),))
+            if request_id is not None:
+                return self._request_state(service, caller, request_id)
+            if path == '/site':
+                return self._json(200, site_facts(caller, service.request_mode, self._source()))
+            if path == '/redeem':
+                return self._redeem(service, caller)
+            if path == '/request':
+                return self._request(service, caller)
+            return self._pending(service, caller, method)
+        except _Reply as reply:
+            return self._json(reply.status, {'error': reply.error})
+        except Exception:                          # noqa: BLE001 — one request's bug never stops the service
+            traceback.print_exc(file=sys.stderr)
+            try:
+                self._json(500, {'error': 'server-error'})
+            except OSError:
+                pass
+
+    def _source(self):
+        """The rate-limit source of this request (source_key); `/site` echoes it."""
+        return source_key(self.headers.get('X-Forwarded-For'), self.client_address[0])
+
+    def _redeem(self, service, caller):
+        now = service.clock()
+        trusted = caller if service.request_mode else NOBODY
+        source = self._source()
+        token, wait = service.attempt(source)
+        if token is None:
+            audit('redeem', None, None, trusted.login, None, 'rate-limited', now)
+            return self._json(429, {'error': 'rate-limited'}, (('Retry-After', str(wait)),))
+        try:
+            fields = self._json_body()
+        except _Reply as reply:
+            audit('redeem', None, None, trusted.login, None, reply.error, now)
+            raise
+        status, payload = redeem(fields, trusted, now)
+        # A 409 (device-taken | key-taken) is answered only after a valid, live code: its holder is retrying with
+        # another --device, as install.sh says to, not guessing codes, so it is not charged (DEF-1731). Everything
+        # else that is not a 200 — an invalid code, a malformed body, an invalid device — still counts.
+        if status in (200, 409):
+            service.succeeded(source, token)
+        return self._json(status, payload)
+
+    def _request(self, service, caller):
+        fields = self._json_body()
+        refusal = service.gate(caller)
+        if refusal:
+            audit('request', None, None, caller.login, None, refusal, service.clock())
+            return self._json(403, {'error': refusal})
+        status, payload = create_request(fields, caller, service.clock())
+        return self._json(status, payload)
+
+    def _request_state(self, service, caller, request_id):
+        document = read_request(request_id) if service.request_mode and caller.login else None
+        if document is None or document['login'].casefold() != caller.login.casefold():
+            return self._json(404, {'error': 'not-found'})
+        return self._json(200, {'id': document['id'], 'state': request_state(document, service.clock()),
+                                'expires_at': document['expires_at']})
+
+    def _pending(self, service, caller, method):
+        form = {}
+        if method == 'POST':
+            try:
+                form = urllib.parse.parse_qs(self._body().decode('utf-8', 'replace'), max_num_fields=8)
+            except ValueError:                      # more fields than an approve/deny form carries
+                raise _Reply(400, 'bad-request') from None
+        refusal = service.gate(caller)
+        if refusal is None and caller.login.casefold() not in member_logins():
+            refusal = 'not-a-member'
+        if refusal:
+            sentence = {'requests-disabled': 'Requests are off on this server (invite-only), so nobody is signed in '
+                                             'here.',
+                        'no-identity': 'No tailnet identity reached this page: open it over the tailnet.',
+                        'domain-not-allowed': 'Your tailnet login is not in a domain this server accepts.',
+                        'not-a-member': 'Your tailnet login is not a member of this server, so you cannot approve '
+                                        'requests. A member record names its owner: on the server, run '
+                                        f'`lanes keys owner <device> {caller.login}` for a device of yours '
+                                        '(`lanes keys list` shows them).'}[refusal]
+            return self._html(403, _page('Enrolment requests', f'<p>{html.escape(sentence)}</p>'))
+        now = service.clock()
+        if method == 'GET':
+            return self._html(200, pending_page(service, caller, now))
+        # A decision is made only on the browser's own word that the form came from this page (`same-origin`) or from
+        # the user (`none`). An ABSENT header is refused too (DEF-1730): every browser that reaches /pending through
+        # Serve's HTTPS sends it, and a client that does not (curl, a script) has `lanes enrol approve` instead.
+        fetch_site = self.headers.get('Sec-Fetch-Site')
+        if fetch_site not in ('same-origin', 'none'):
+            reason = ('the form came from another site' if fetch_site else
+                      'the browser did not say where the form came from (no Sec-Fetch-Site): use a current browser, '
+                      'or on the server `lanes enrol approve <id>`')
+            return self._html(403, _page('Enrolment requests', f'<p>Refused: {html.escape(reason)}.</p>'))
+        one = {key: (form.get(key) or [''])[0] for key in ('id', 'action', 'token')}
+        request_id = one['id'].lower()
+        if (not _REQUEST_ID.fullmatch(request_id) or one['action'] not in ACTIONS
+                or not hmac.compare_digest(one['token'].encode('utf-8', 'replace'),
+                                           service.token(caller.login, request_id).encode())):
+            audit(one['action'] if one['action'] in ACTIONS else 'decide', None, None, caller.login, None,
+                  'bad-form', now)
+            return self._html(403, _page('Enrolment requests', '<p>Refused: that form is stale or was not issued '
+                                                               'here. Reload the page and try again.</p>'))
+        try:
+            document = decide(request_id, one['action'], caller.login, now)
+        except L.LanesError as error:
+            return self._html(409, pending_page(service, caller, now, f'Not done: {error}'))
+        word = 'Approved' if document['state'] == 'approved' else 'Denied'
+        message = f"{word} {document['device']} for {document['login']}."
+        return self._html(200, pending_page(service, caller, now, message))
+
+
+class Server(ThreadingHTTPServer):
+    daemon_threads = True
+    request_queue_size = 32
+
+    def __init__(self, address, service):
+        self.service = service
+        super().__init__(address, Handler)
+
+    def server_bind(self):                         # HTTPServer's getfqdn() lookup is not needed on loopback
+        socketserver.TCPServer.server_bind(self)
+        self.server_name, self.server_port = self.server_address[:2]
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='lanes-enrold', description='Lanes enrolment service (loopback only).')
+    parser.add_argument('--port', type=int, default=None, help=f'default $LANES_ENROL_PORT or {DEFAULT_PORT}')
+    args = parser.parse_args(argv)
+    port = args.port
+    if port is None:
+        try:
+            port = int(os.environ.get('LANES_ENROL_PORT') or DEFAULT_PORT)
+        except ValueError:
+            parser.error('LANES_ENROL_PORT is not a port number')
+    if not 0 <= port <= 65535:
+        parser.error(f'{port} is not a port number')
+    service = Service.from_environ(os.environ)
+    server = Server(('127.0.0.1', port), service)
+    print(f'lanes-enrold {version()}: listening on 127.0.0.1:{server.server_address[1]}; request mode '
+          f'{service.mode_source()}; '
+          f'domains {",".join(service.domains)}', file=sys.stderr, flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())