Merge pull request 'Upgrade every node's packages on a Saturday 04:00 timer and make its outcome the pacman module's health, so the nodes stay on the same versions (issue 1574, ADR 0477)' (#404) from fix/1574-weekly-upgrade into main

mesh-config refused every owners proposal as carrying a secret, because the SDK's CheckSecret took
modules/asus-zephyrus-g14, i3status-rust and powerlevel10k for random strings. The SDK at
feat/1439-name-runs judges such a lowercase name piece by piece; this moves mesh-config to it and
proves the catalogue's own owners list plus okioki is put to the operator.

.gitignore

@@ -8,13 +8,11 @@ modules/messenger/cmd/messenger/messenger
 modules/mesh-watcher/cmd/mesh-watcher/mesh-watcher
 modules/claude-code/cmd/claude-code/claude-code
 modules/dnsmasq/cmd/dnsmasq-tools/dnsmasq-tools
-modules/mesh-delivery/cmd/mesh-delivery/mesh-delivery
 # ...and the same built from the module's root (go build ./cmd/<name>), which names it after the module.
 modules/messenger/messenger
 modules/claude-code/claude-code
 modules/mesh-watcher/mesh-watcher
 modules/dnsmasq/dnsmasq
-modules/mesh-delivery/mesh-delivery
 modules/mesh-issues/cmd/mesh-issues/mesh-issues
 modules/mounts/cmd/mounts/mounts
 modules/mesh-knowledge/cmd/mesh-knowledge/mesh-knowledge
@@ -26,3 +24,6 @@ modules/mesh-files/cmd/mesh-files/mesh-files
 
 # The provisioner client built in place (issue 671).
 modules/mesh-provisioner-client/cmd/mesh-provisioner-client/mesh-provisioner-client
+modules/brother/cmd/brother/brother
+modules/mesh-build-go/cmd/mesh-build-go/mesh-build-go
+modules/mesh-config/mesh-config

checks/owned/main.go

@@ -160,8 +160,14 @@ func Check(root string) ([]Finding, error) {
 		}
 		dirs := map[string]string{}
 		for _, r := range m.Resources {
-			if r.ID != "" && r.Path != "" {
+			switch {
+			case r.ID != "" && r.Path != "":
 				dirs[r.ID] = r.Path
+			case r.ID != "" && r.Type == "directory":
+				// A directory the mesh places for the module (`place`): where it lies is the node-engine's, but it is
+				// the module's own, so a path under it belongs to this module and to no other's directory of the same
+				// id (issue 1484: two runs-as modules each keep a .ssh in their own state directory).
+				dirs[r.ID] = "/placed/" + m.Module + "/" + r.ID
 			}
 		}
 		for _, r := range m.Resources {

checks/owned/main_test.go

@@ -130,3 +130,18 @@ func TestAnArchiveIsNotAContainerAndSameModuleIsFine(t *testing.T) {
 		t.Fatalf("refused %+v", found)
 	}
 }
+
+// Issue 1484: a directory the mesh places for a module (no path, `place`) is that module's own: another module's
+// directory of the same id, and a path under it, are not inside it.
+func TestPlacedDirectoriesOfTwoModulesAreTheirOwn(t *testing.T) {
+	root := t.TempDir()
+	for _, name := range []string{"first", "second"} {
+		manifest(t, root, name, mod(name,
+			`{"id":"state","type":"directory","place":".","unknown":"program"}`,
+			dir("ssh", "${dir:state}/.ssh", `,"unknown":"program"`),
+			`{"id":"conf","type":"file","path":"${dir:ssh}/config"}`))
+	}
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}

checks/sshdir/main.go

@@ -5,7 +5,7 @@
 //	go run . <catalogue root>
 //
 // Every string of a manifest is read, wherever it stands, except prose and a file's text (Prose): a path, a
-// place, a volume. Exits 1 on a finding.
+// place, a volume; a path inside a directory of the module's own (`${dir:<id>}`) is not ~/.ssh. Exits 1 on a finding.
 package main
 
 import (
@@ -15,6 +15,7 @@ import (
 	"path/filepath"
 	"regexp"
 	"sort"
+	"strings"
 )
 
 // SSHModule is the one module allowed to name a path under ~/.ssh.
@@ -60,7 +61,7 @@ func Check(root string) ([]Finding, error) {
 		if module == SSHModule {
 			continue
 		}
-		walk(m, "", func(key, value string) {
+		walk(m, "", dirsOf(m), func(key, value string) {
 			out = append(out, Finding{Module: module, Key: key, Value: value})
 		})
 	}
@@ -68,7 +69,7 @@ func Check(root string) ([]Finding, error) {
 }
 
 // walk calls found for every string under v, outside Prose, that names a path under ~/.ssh.
-func walk(v any, key string, found func(key, value string)) {
+func walk(v any, key string, dirs map[string]string, found func(key, value string)) {
 	switch x := v.(type) {
 	case map[string]any:
 		keys := make([]string, 0, len(x))
@@ -78,20 +79,68 @@ func walk(v any, key string, found func(key, value string)) {
 		sort.Strings(keys)
 		for _, k := range keys {
 			if !Prose[k] {
-				walk(x[k], k, found)
+				walk(x[k], k, dirs, found)
 			}
 		}
 	case []any:
 		for _, e := range x {
-			walk(e, key, found)
+			walk(e, key, dirs, found)
 		}
 	case string:
-		if underSSH.MatchString(x) {
+		// A path under a directory the mesh places for the module (${dir:<id>} of a directory with a place and no path,
+		// as a runs-as module's home) is that account's own .ssh, not the operator's ~/.ssh that ssh-client sweeps
+		// (issue 1484, ADR 0466 §4). Any other ${dir:<id>} is resolved to the path its resource declares and judged.
+		if resolved, placed := resolveDir(x, dirs); !placed && underSSH.MatchString(resolved) {
 			found(key, x)
 		}
 	}
 }
 
+var ofDir = regexp.MustCompile(`^\$\{dir:([a-z0-9][a-z0-9_-]*)\}`)
+
+// placedDir marks a directory the mesh places for the module: it has no path of its own.
+const placedDir = "\x00placed"
+
+// dirsOf are the module's directories by id: the path each declares, or placedDir for one with a place and no path.
+func dirsOf(m any) map[string]string {
+	dirs := map[string]string{}
+	obj, _ := m.(map[string]any)
+	list, _ := obj["resources"].([]any)
+	for _, r := range list {
+		res, _ := r.(map[string]any)
+		id, _ := res["id"].(string)
+		path, _ := res["path"].(string)
+		switch {
+		case id == "":
+		case path != "":
+			dirs[id] = path
+		case res["type"] == "directory":
+			dirs[id] = placedDir
+		}
+	}
+	return dirs
+}
+
+// resolveDir follows a leading ${dir:<id>} through the module's directories. It answers the path with the references
+// resolved, and whether it ends under a placed directory.
+func resolveDir(x string, dirs map[string]string) (string, bool) {
+	for i := 0; i < 8; i++ {
+		m := ofDir.FindStringSubmatch(x)
+		if m == nil {
+			return x, false
+		}
+		to, ok := dirs[m[1]]
+		if !ok {
+			return x, false
+		}
+		if to == placedDir {
+			return x, true
+		}
+		x = to + strings.TrimPrefix(x, m[0])
+	}
+	return x, false
+}
+
 func main() {
 	root := "."
 	if len(os.Args) > 1 {

checks/sshdir/main_test.go

@@ -37,6 +37,36 @@ func TestAnotherModuleNamingSSHIsRefused(t *testing.T) {
 	}
 }
 
+// Issue 1484: a runs-as module's own account has a .ssh of its own, inside its home (a directory of the module's);
+// that is not the operator's ~/.ssh, which only ssh-client names. A path outside any ${dir:} is still refused.
+func TestAModulesOwnDirectoryMayHoldADotSSH(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "builder", `{"module":"builder","resources":[{"id":"state","type":"directory","place":"."},{"id":"ssh-dir","type":"directory","path":"${dir:state}/.ssh"},{"path":"${dir:ssh-dir}/config"}]}`)
+	manifest(t, root, "other", `{"module":"other","resources":[{"path":"${machine:account-home}/.ssh/config"}]}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Module != "other" {
+		t.Fatalf("refused %+v; want only other", found)
+	}
+}
+
+// Issue 1484 review: only a directory the mesh places is the module's own home. A ${dir:} that resolves to the
+// operator's home is judged by the path it resolves to.
+func TestADirResolvingToTheOperatorsHomeIsStillRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "escape", `{"module":"escape","resources":[{"id":"h","type":"directory","path":"${machine:account-home}","unknown":"module"},{"path":"${dir:h}/.ssh/config"}]}`)
+	manifest(t, root, "placed", `{"module":"placed","resources":[{"id":"state","type":"directory","place":".","unknown":"program"},{"id":"s","type":"directory","path":"${dir:state}/.ssh"},{"path":"${dir:s}/config"}]}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Module != "escape" {
+		t.Fatalf("refused %+v; want only escape", found)
+	}
+}
+
 func TestTheCatalogueHasNone(t *testing.T) {
 	found, err := Check("../..")
 	if err != nil {

health-undeclared

@@ -1,4 +1,4 @@
-61
+59
 The long-running resources of this catalogue that do not say how they are ready (`health`, novox/hq ADR 0240
 rule 8), as `module check` counts them. It may only go down: merge-check.sh fails a change that raises it, and
 one that lowers it writes the new number on the first line. From 2026-11-18, or once it is 0, a long-running

modules/brother/README.md

@@ -0,0 +1,144 @@
+# brother — the Brother multifunction device: scan, printer state, admin pages
+
+One module for one device (novox/hq ADR 0467, issue 1453): the scanner and the printer are one machine on the
+network, so one module serves both. It claims two seats, each held once for the mesh: `scanner` (verbs `scan`,
+`status`, `list`, `document`) and `printer` (verbs `status`, `settings`, `print`, `upload`; `restart` follows in a later round). It replaces the
+`scan` module of issue 1440 (ADR 0464), which ran on no node and is gone from the catalogue.
+
+## The scanner seat
+
+Built for issue 1440 as novox/hq ADR 0464 decides. It scans the glass of a network scanner (any scanner that
+speaks eSCL, also called AirScan or Mopria), cuts the document out of the lid's white, files it as a one-page PDF
+in a folder and says `scan.added` on the bus, so other modules can react. A scan happens when a tool is called:
+the module runs no process of its own, and it runs as the node's operator account.
+
+## What a scan does
+
+1. Asks the scanner for its sizes and puts one job to it (`POST <scanner>/ScanJobs`) at the configured resolution
+   and colour mode, as a JPEG: from the glass (`source` glass, the default) or from the document feeder (`source`
+   feeder, with `duplex` true for both sides of each sheet; refused on the glass). The region is A4, cut to what the
+   input can scan (the glass is 3507 high, not A4's 3508). The body is written on one line: the Brother ignores the
+   whole body, and runs its default job, when it holds a line break (issue 1452). The glass page is fetched once;
+   a feeder job is asked `NextDocument` until the scanner answers 404, at most 100 pages. A job that fails is deleted.
+2. Reads the resolution from the image's own JFIF density, never from the request: a scanner may answer a
+   300 dpi request with 200 dpi, and the page size and the event's millimetres follow what it gave.
+3. Crops the glass page (a feeder page is a whole sheet and is never cropped): the lid's level is measured in the corner farthest from where documents lie, a pixel is document when
+   it is darker than the lid, and the rows and columns holding enough of them give the box. No document, or one
+   filling nearly the whole glass, keeps the whole image (`cropped` false), and so does `crop` false.
+   With `apart` true (opt-in; without it the glass gives one document, as it always did), several documents lying apart on the glass are each cut out and filed as a one-page PDF of its own (own
+   object, own `scan.added`, own file); the answer then lists them as `documents` (each with its `path`) and
+   `count`, in reading order, and one that could not be kept or filed is named in `failed` without holding back
+   the others. The rule (`Boxes` in `crop.go`): the picture is cut into blocks of 1 mm; a block is document when a
+   quarter of its pixels are darker than the lid; blocks not at least three across (dust, JPEG ringing) are dropped;
+   blocks within 10 mm of each other are one region, so a white band narrower than that does not split a document;
+   a region under 20 mm on a side is a stain, not a document; regions whose boxes overlap are one document (a frame
+   and the text inside it). One document, or none, is cropped exactly as before.
+4. Files a PDF holding the JPEGs, one page for the glass and one per image for the feeder (so six for three
+   sheets both sides), each page as large as its image really is: written whole beside its place as `.scan-*.tmp` and renamed to
+   `scan-YYYY-MM-DD-HHMMSS.pdf` (local time); a taken name gets `-2`, `-3`, and no file is ever overwritten.
+5. Says `scan.added` once, after the rename, under the file's sha256 as its message id. It never carries the image.
+
+A scanner that refuses or gives no page files nothing and says nothing on the bus; the tool's error says why.
+
+## Config
+
+| key | meaning | default |
+|---|---|---|
+| `scanner` | the scanner's eSCL address, such as `http://192.0.2.10/eSCL` (required, trusted) | none |
+| `scan-folder` | the absolute path the PDFs are filed in (required, trusted) | none |
+| `printer` | the printer's host, such as `192.0.2.10`, for its admin page and IPP (required, trusted) | none |
+| `printer-certificate` | the SHA-256 fingerprint of the certificate the admin page may serve, `AA:BB:...`; several, separated by commas, when it serves more than one (required, trusted) | none |
+| `resolution` | dpi asked: 100, 200, 300 or 600 | 300 |
+| `color-mode` | `color` or `gray` | `color` |
+| `crop` | cut the document out of the lid's white | true |
+
+The values reach the code in one file, `settings.json` in the module's state directory, which the mesh writes
+from the config; the code reads it at every call. With `scanner` or `scan-folder` unset, every scanner verb says which and
+writes and asks nothing; `printer` and `printer-certificate` are the printer verbs' to say.
+
+The scan folder is not a manifest resource: a directory's path cannot take a config value (issue 1441), so the code
+makes it (mode 0755) when it files the first scan.
+
+## Tools
+
+| verb (tool) | does |
+|---|---|
+| `scanner.scan` | `source` (`glass`, default, or `feeder`), `duplex` (feeder only) and `apart` (glass only): asks the device process to scan, crop (glass only), keep the PDF in the bucket under its sha256 and say `scan.added`; then fetches it in parts, checks the sha256 and files it in `scan-folder`, in the background, so a scan is filed whether or not the caller still waits. A glass scan is waited for up to 180 s. Several glass pages in one PDF (a page turned over, a stapled document): `document` `start` scans page 1 into a new document and answers its id (nothing is filed yet), `document` with that id scans the next page, and `document` with the id and `finish` true closes it into one multi-page PDF, filed once with one `scan.added` (nothing is scanned). The pages are kept in the bucket under `pending/<id>/` (not in memory, so a restart of the device process loses none); a document that gets no page for 30 minutes is closed and filed so by the tool process (a restart of the tool process forgets that timer; `finish` still works). The pages in the bucket are not deleted, the bucket having no delete. A feeder scan is waited for 25 s (the mesh console gives up after 30 s); if it is not done, the answer is `started: true` with its `id`, and `scanner.scan {id}` reads the outcome (`state` running, done with the event's body and `path`, or failed with `why`). The device process ends a feeder job at 20 s a page (at least 3 min, at most 30 min). A scan whose PDF the tool could not fetch (over 100 MiB) is refused before it is kept or announced. Answers the event's body and `path` |
+| `scanner.document` | one part of a kept scan (`object`, `part` from 1): `part`, `parts`, `size`, `sha256` (of the whole), `data` (base64). Join the parts and check the sha256 |
+| `scanner.status` | whether the scanner answers, its state (Idle or Processing) and its document feeder's state; a scanner that does not answer is `answers: false` with why. |
+| `brother_health` | the module's health, asked by the node-engine every 60 s (ADR 0240) as the tool check of the `watch` process, beside the device process's unit check: the certificates the printer serves, one for each key type (ECDSA and RSA, told apart by the cipher suites offered under TLS 1.2), read with no login and compared with the pinned `printer-certificate` list. Unhealthy when one is not pinned, `why` naming the new fingerprint, so the pin can be changed before the admin pages are needed. With `printer` or `printer-certificate` not given it answers `state: waits` with `waits` naming each setting (the SDK's health.Waiting, ADR 0283), not an error. Each handshake is bounded by 3 s and the whole check by 7 s. A printer that does not answer is healthy, with `why` saying nothing was compared (it may be switched off). The process's liveness is judged by the node-engine without a declaration |
+| `scanner.list` | the newest filed scans, newest first (`limit`, default 20). Read-only |
+
+## The printer seat
+
+| verb (tool) | does |
+|---|---|
+| `printer.status` | without a login: over IPP (`Get-Printer-Attributes`, encoded by hand, on port 631) the state (idle, processing, stopped), the state reasons (such as `toner-low-warning`) and the markers' names, levels (percent; below 0 is unknown) and colours; over eSCL the scanner's state and its feeder's. A part that does not answer is `answers: false` with why. Needs `printer` and `scanner` |
+| `printer.upload` | one part of a document to print later (`upload` id, `part`, `parts`, `sha256` of the whole, `data` base64): stored as `uploads/<upload>.pdf` or `.jpg` once all parts came and the sha256 matches; a wrong sha256, a part out of range or a document that is neither PDF nor JPEG stores nothing |
+| `printer.print` | prints a file on the machine the tool runs on (`path`, absolute, a regular file under the tool account's home folder after symbolic links are resolved; any other path is refused with the one message "path refused: only a file under the home folder", which says nothing of whether it exists: the tool reads it, uploads it in parts and prints it in one call; PDF or JPEG by its bytes, never its name), a kept scan (`object`) or a completed upload (`upload`, for modules that send bytes over the bus) as an IPP Print-Job (operation 0x0002, port 631) in its own format, `copies` 1 to 99 (default 1), `sides` one-sided, two-sided-long-edge or two-sided-short-edge (default one-sided), `media` (default `iso_a4_210x297mm`); answers the job's id and state (with `path`, the upload id and the size when `path` was given) |
+| `printer.settings` | asks the device process (below) to log in, read one admin page and log out, and waits up to 60 s for its answer. Argument `page`: a path on the admin site, starting with `/` and ending in `.html` (default `/general/status.html`). Answers the page's title and forms with their fields, each with its current value (a radio group as one field with the checked button's value, a checkbox with `checked`, a select with the selected option) and `options`; the page's links only with `links: true`, hidden fields only with `hidden: true`; a password field's value is never given. Read-only: it sends the login and the logout and nothing else |
+
+### Trust and the password
+
+The admin page is HTTPS with a self-signed certificate. The module verifies no chain: it accepts the one certificate
+whose SHA-256 fingerprint is one of those in `printer-certificate` and refuses any other, in the handshake, so no
+password is sent to it; the error names the served and the pinned fingerprints. Give each as 32 upper-case hex pairs
+joined by colons, several separated by commas. The printer serves two self-signed certificates for one name, an
+ECDSA one and an RSA one, and which it serves depends on the signature algorithms the client offers, so pin both
+(issue 1503): read them with `openssl s_client -connect <printer>:443 -sigalgs ECDSA+SHA256` and `-sigalgs
+RSA-PSS+SHA256`, each piped to `openssl x509 -noout -fingerprint -sha256`.
+
+The admin password is the module's own secret `admin-password` (ADR 0467 clause 4; ADR 0283): the operator gives it
+at their desk, and the mesh never generates or rotates it. It is owned by the account `brother-device`, which the
+module makes, because the tools run as the operator account and must never read it (ADR 0436 §1, §12; the shape of
+mesh-mail's sender). The file is `${dir:state}/admin-password.secret`, mode 0600, and `BROTHER_ADMIN_PASSWORD` names
+it for the device process alone; the tools' bundle is given no such name, and `admin_boundary_test.go` checks that
+no tool file imports the package that reads it. While it is not given, `printer.settings` answers that the secret
+is not given, and the printer is not contacted.
+
+### Documents in parts
+
+The bus refuses a message over 1 MiB, so a document crosses it in parts of at most 700 KiB (both the size this module
+cuts and the most it accepts, as ADR 0468 clause 3 says),
+counted from 1, each carried base64-encoded in JSON. A caller joins the parts and checks the SHA-256. The bucket
+(`s3-bucket`, from `minio`) is spoken to by the device process alone, from `store.json` (owner `brother-device`, mode
+0600), with the S3 client mesh-mail uses; a scan is kept once as `<sha256>.pdf` and an upload as `uploads/<id>.<ext>`.
+
+### The device process
+
+`brother device` runs as `brother-device` with a bus account of its own (the own secret `broker-device`), never a
+seat, and does all the device and bucket work: the scan (and `scan.added`, emitted by it with the object's key and no
+path, since filing in the scan folder is the tool's), the documents, the printing, and the admin pages. It consumes the work-queue stream `device-asks` (event `device.asked`, body `id`, `page`, `asked-at`) and
+writes each answer, once, into the state `device-answers` under the ask's id (ten minutes' life): the page's
+title, links and form fields, or `error`. It alone reads the password, pins the certificate, logs in, reads the
+page and logs out. An ask older than two minutes is dropped without contacting the printer; at most three
+deliveries. It reads `settings.json` (mode 0644, no secret in it) and the state directory is 0711 so that it can
+reach its own files; both are the choices that let its account read what it needs. The device process is judged by its unit; `brother_health` (the printer's certificates against the pins) is the tool check of the `watch` process beside it.
+
+The login reads the form each time: the device generates the password field's name, so the code takes the name from
+the form, posts it with the form's hidden fields, and keeps the session cookie. A login is failed when the answer is
+the login page again. The logout follows a logout link or form on the page; a page with none is said in the answer
+(`logout`), and the session is left to expire on the device.
+
+## The event
+
+`scan.added`, said by this module, on the wire `mesh.mod.brother.event.scan.added`; a consumer declares `brother.scan.added`. Its body:
+`path`, `node`, `bytes`, `sha256`, `width-mm`, `height-mm`, `resolution` (dpi, as the scanner gave it),
+`color-mode`, `cropped`, `pages` (1 for the glass), `scanned-at` (RFC 3339, UTC).
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- The scan folder (`scan-folder`) is declared by no manifest. The module writes only the `scan-*.pdf` files it
+  files and their `.scan-*.tmp` while they are written; it never changes, moves or removes any other file there,
+  and `scanner.list` only reads.
+
+## Tests
+
+The unit tests use the captured answers of a real scanner (`cmd/brother/testdata/escl`, captured 2026-10-20) served
+by a test HTTP server, the captured IPP exchange (`testdata/ipp`) replayed, and the captured login page
+(`testdata/admin/login-page.html`) served by a test TLS server with its own certificate. The pages behind the login
+are synthetic (`testdata/admin/synthetic-*.html`) until round 2 captures the real ones. No test reaches the real
+device.

modules/brother/cmd/brother/admin.go

@@ -0,0 +1,231 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/cookiejar"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// Admin is a session on the printer's admin web page, over HTTPS to the one certificate pinned (ADR 0467
+// clauses 3 and 4). The device names the password field itself, so every login reads the form first.
+type Admin struct {
+	Host     string
+	Password string
+	HTTP     *http.Client
+}
+
+// loginStart is where a login starts: the root, which the printer answers with a redirect to the page it serves
+// its login form on (/home/status.html). Asking for a page behind the login instead is answered by a redirect
+// to an error page, and a loginurl naming a page this firmware lacks is a 404 after the login (issue 1514).
+const loginStart = "/"
+
+// maxPage bounds a page of the admin site.
+const maxPage = 4 << 20
+
+// NewAdmin is a client for the printer's host that trusts the certificate with this fingerprint alone, with a
+// cookie jar for the session.
+func NewAdmin(host, fingerprint, password string) (*Admin, error) {
+	jar, err := cookiejar.New(nil)
+	if err != nil {
+		return nil, err
+	}
+	return &Admin{
+		Host:     host,
+		Password: password,
+		HTTP: &http.Client{
+			Timeout: 30 * time.Second,
+			Jar:     jar,
+			CheckRedirect: func(req *http.Request, via []*http.Request) error {
+				return checkRedirect(host, req, via)
+			},
+			Transport: &http.Transport{
+				TLSClientConfig:   pinnedTLS(fingerprint),
+				DisableKeepAlives: true,
+			},
+		},
+	}, nil
+}
+
+// checkRedirect follows a redirect only on https on the printer's own host, and never with a body: a 307 or 308
+// answer to the login post would make the client send the post again, the password with it (issue 1515).
+func checkRedirect(host string, req *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return errors.New("the printer redirected more than ten times")
+	}
+	if req.URL.Scheme != "https" || req.URL.Host != host {
+		return fmt.Errorf("the printer redirected to %s, not to https on the printer %s: not followed", req.URL.Scheme+"://"+req.URL.Host, host)
+	}
+	if req.Method != http.MethodGet && req.Method != http.MethodHead {
+		return fmt.Errorf("the printer redirected a %s with its body (a 307 or 308): not followed, so the password is not sent again", via[len(via)-1].Method)
+	}
+	return nil
+}
+
+func (a *Admin) url(path string) string { return "https://" + a.Host + path }
+
+// fetch is one request; the body is read whole, up to maxPage. The final URL is the one after redirects.
+func (a *Admin) fetch(ctx context.Context, method, rawURL string, form url.Values) ([]byte, *url.URL, error) {
+	var req *http.Request
+	var err error
+	if form != nil {
+		req, err = http.NewRequestWithContext(ctx, method, rawURL, strings.NewReader(form.Encode()))
+		if err == nil {
+			req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+		}
+	} else {
+		req, err = http.NewRequestWithContext(ctx, method, rawURL, nil)
+	}
+	if err != nil {
+		return nil, nil, err
+	}
+	resp, err := a.HTTP.Do(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer resp.Body.Close()
+	buf, err := io.ReadAll(io.LimitReader(resp.Body, maxPage+1))
+	if err != nil {
+		return nil, nil, fmt.Errorf("the page %s cannot be read: %w", rawURL, err)
+	}
+	if len(buf) > maxPage {
+		return nil, nil, fmt.Errorf("the page %s is larger than %d bytes", rawURL, maxPage)
+	}
+	if resp.StatusCode >= 400 {
+		if resp.StatusCode == http.StatusNotFound {
+			return nil, nil, &notFoundError{Path: resp.Request.URL.Path}
+		}
+		return nil, nil, fmt.Errorf("the printer answered %s for %s", resp.Status, resp.Request.URL.Path)
+	}
+	return buf, resp.Request.URL, nil
+}
+
+// passwordForm is the form of a page that holds a password field, or nil.
+func passwordForm(p Page) (*Form, *Field) {
+	for i := range p.Forms {
+		for j := range p.Forms[i].Fields {
+			if p.Forms[i].Fields[j].Type == "password" {
+				return &p.Forms[i], &p.Forms[i].Fields[j]
+			}
+		}
+	}
+	return nil, nil
+}
+
+func hasField(f *Form, name string) bool {
+	for _, fl := range f.Fields {
+		if fl.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// Login asks for the printer's login page, reads its login form, and posts the form's own fields with the
+// password in the field the form names and the form's loginurl set to the default page, which every firmware has; the page asked for is a request of its own afterwards. A login
+// is failed when the answer is a login page again.
+func (a *Admin) Login(ctx context.Context) error {
+	body, at, err := a.fetch(ctx, http.MethodGet, a.url(loginStart), nil)
+	if err != nil {
+		return fmt.Errorf("the printer's admin page cannot be asked for its login: %w", err)
+	}
+	form, pw := passwordForm(ParsePage(body))
+	if form == nil {
+		return fmt.Errorf("the printer's answer to %s holds no login form with a password field", at.Path)
+	}
+	target, err := at.Parse(form.Action)
+	if err != nil {
+		return fmt.Errorf("the login form's action %q is not a URL: %w", form.Action, err)
+	}
+	if target.Scheme != "https" || target.Host != a.Host {
+		return fmt.Errorf("the login form posts to %s, not to https on the printer %s: the password is not sent", target.Scheme+"://"+target.Host, a.Host)
+	}
+	vals := url.Values{}
+	for _, f := range form.Fields {
+		if f.Type == "hidden" {
+			vals.Set(f.Name, f.Value)
+		}
+	}
+	if _, ok := vals["loginurl"]; ok {
+		vals.Set("loginurl", DefaultPage)
+	}
+	vals.Set(pw.Name, a.Password)
+	answer, _, err := a.fetch(ctx, http.MethodPost, target.String(), vals)
+	if err != nil {
+		// The post may have opened a session before its answer failed: end it if there is one.
+		if home, hat, herr := a.Get(context.Background(), DefaultPage); herr == nil {
+			a.Logout(context.Background(), home, hat)
+		}
+		return fmt.Errorf("the login was not answered: %w", err)
+	}
+	// A login page again is a form with a password field and the loginurl field; a page that was asked for may
+	// hold a password field of its own.
+	if again, _ := passwordForm(ParsePage(answer)); again != nil && hasField(again, "loginurl") {
+		return fmt.Errorf("the login failed: the printer showed its login page again, so the secret admin-password is not its password")
+	}
+	return nil
+}
+
+// Get is a page of the admin site, after a login.
+func (a *Admin) Get(ctx context.Context, path string) ([]byte, *url.URL, error) {
+	return a.fetch(ctx, http.MethodGet, a.url(path), nil)
+}
+
+// Logout ends the session through the logout link or form of a page of it, and says what it did. A page with
+// none leaves the session to expire, and the answer says so.
+func (a *Admin) Logout(ctx context.Context, page []byte, at *url.URL) string {
+	p := ParsePage(page)
+	isLogout := func(s string) bool {
+		s = strings.ToLower(strings.ReplaceAll(s, " ", ""))
+		return strings.Contains(s, "logout") || strings.Contains(s, "logoff")
+	}
+	for _, f := range p.Forms {
+		if !isLogout(f.Action) {
+			continue
+		}
+		target, err := at.Parse(f.Action)
+		if err != nil || target.Host != a.Host {
+			continue
+		}
+		vals := url.Values{}
+		for _, fl := range f.Fields {
+			if fl.Type == "hidden" {
+				vals.Set(fl.Name, fl.Value)
+			}
+		}
+		method := http.MethodPost
+		var send url.Values = vals
+		if f.Method == "get" {
+			method, send = http.MethodGet, nil
+			target.RawQuery = vals.Encode()
+		}
+		if _, _, err := a.fetch(ctx, method, target.String(), send); err != nil {
+			return "logout failed: " + err.Error()
+		}
+		return "logged out"
+	}
+	for _, l := range p.Links {
+		if !isLogout(l.Href) && !isLogout(l.Text) {
+			continue
+		}
+		target, err := at.Parse(l.Href)
+		if err != nil || target.Host != a.Host {
+			continue
+		}
+		if _, _, err := a.fetch(ctx, http.MethodGet, target.String(), nil); err != nil {
+			return "logout failed: " + err.Error()
+		}
+		return "logged out"
+	}
+	return "no logout link or form on the page: the session is left to expire on the printer"
+}
+
+// notFoundError is the printer's 404 for a page.
+type notFoundError struct{ Path string }
+
+func (e *notFoundError) Error() string { return "the printer answered 404 Not Found for " + e.Path }

modules/brother/cmd/brother/admin_test.go

@@ -0,0 +1,351 @@
+package main
+
+import (
+	"context"
+	"crypto/tls"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fakePrinter is a TLS server standing in for the printer's admin page. Its login page is the captured one
+// (testdata/admin/login-page.html, 2026-10-20) with the password field's name changed to the one the test
+// chooses, as the real device generates it. The pages behind the login are SYNTHETIC (testdata/admin/
+// synthetic-*.html): the real ones arrive in round 2 of issue 1453.
+type fakePrinter struct {
+	*httptest.Server
+	field    string // the password field's name the login form gives
+	password string
+	mu       sync.Mutex
+	conns    int               // connections opened to it
+	requests []string          // method and path of every request
+	posted   []url.Values      // every form body posted
+	session  string            // the cookie value of the one logged-in session
+	loggedIn map[string]bool   // cookie values that are logged in
+	pages    map[string]string // path -> body behind the login
+}
+
+func adminFixture(t *testing.T, name string) string {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("testdata", "admin", name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(b)
+}
+
+func newFakePrinter(t *testing.T, field, password string) *fakePrinter {
+	t.Helper()
+	f := &fakePrinter{field: field, password: password, loggedIn: map[string]bool{}, pages: map[string]string{}}
+	login := strings.ReplaceAll(adminFixture(t, "login-page.html"), "B1891", field)
+	// The login page the printer serves at /home/status.html carries that page as its loginurl (captured live
+	// 2026-10-20, testdata/admin/live/home_status_html.body); the page it serves at /etc/loginerror.html carries
+	// the page that was asked for.
+	homeLogin := strings.ReplaceAll(login, `value="/general/status.html"`, `value="/home/status.html"`)
+	synthetic := adminFixture(t, "synthetic-status.html")
+	// This firmware has no /general/status.html behind the login (issue 1514): asking for it is a 404.
+	f.pages["/home/status.html"] = synthetic
+	f.pages["/general/other.html"] = adminFixture(t, "synthetic-settings.html")
+	authed := func(r *http.Request) bool {
+		c, err := r.Cookie("session")
+		return err == nil && f.loggedIn[c.Value]
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/etc/loginerror.html", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.Write([]byte(login))
+	})
+	mux.HandleFunc("/home/status.html", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if r.Method != http.MethodPost {
+			if authed(r) {
+				w.Write([]byte(synthetic))
+				return
+			}
+			w.Write([]byte(homeLogin))
+			return
+		}
+		r.ParseForm()
+		f.posted = append(f.posted, r.PostForm)
+		if r.PostForm.Get(field) != password || r.PostForm.Get("loginurl") == "" {
+			w.Write([]byte(login))
+			return
+		}
+		f.session = "s" + field
+		f.loggedIn[f.session] = true
+		http.SetCookie(w, &http.Cookie{Name: "session", Value: f.session, Path: "/"})
+		// Like Brother's form, a good login goes on to the page named in loginurl.
+		http.Redirect(w, r, r.PostForm.Get("loginurl"), http.StatusFound)
+	})
+	mux.HandleFunc("/home/logout.html", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if c, err := r.Cookie("session"); err == nil {
+			delete(f.loggedIn, c.Value)
+		}
+		w.Write([]byte(login))
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if r.URL.Path == "/" {
+			http.Redirect(w, r, "/home/status.html", http.StatusMovedPermanently)
+			return
+		}
+		f.requests = append(f.requests, r.Method+" "+r.URL.Path)
+		// Captured: a page behind the login is answered by a redirect to the login page whether it exists or not.
+		if !authed(r) {
+			http.Redirect(w, r, "/etc/loginerror.html?url="+url.QueryEscape(r.URL.Path), http.StatusFound)
+			return
+		}
+		body, ok := f.pages[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		w.Write([]byte(body))
+	})
+	f.Server = httptest.NewUnstartedServer(mux)
+	f.Config.ConnState = func(_ net.Conn, st http.ConnState) {
+		if st == http.StateNew {
+			f.mu.Lock()
+			f.conns++
+			f.mu.Unlock()
+		}
+	}
+	f.StartTLS()
+	t.Cleanup(f.Close)
+	return f
+}
+
+func (f *fakePrinter) host() string { return strings.TrimPrefix(f.URL, "https://") }
+
+// print is the fingerprint of the certificate the server serves.
+func (f *fakePrinter) print() string { return Fingerprint(f.TLS.Certificates[0].Certificate[0]) }
+
+func (f *fakePrinter) connsNow() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.conns
+}
+
+func (f *fakePrinter) loggedInNow() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return len(f.loggedIn)
+}
+
+// 1453/AC2: a certificate whose fingerprint is not the pinned one is refused, the error names both
+// fingerprints, and the server saw no request at all, so no password was sent.
+func TestACertificateOtherThanThePinnedOneIsRefusedBeforeAnythingIsSent(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "hunter2")
+	other := strings.Repeat("AA:", 31) + "AA"
+	a, err := NewAdmin(f.host(), other, "hunter2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = a.Login(context.Background())
+	if err == nil {
+		t.Fatal("a certificate that is not the pinned one was accepted")
+	}
+	for _, want := range []string{f.print(), other} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not name the fingerprint %s", err, want)
+		}
+	}
+	if len(f.requests) != 0 || len(f.posted) != 0 {
+		t.Errorf("the server was sent %v and the forms %v: the password may have gone", f.requests, f.posted)
+	}
+}
+
+// 1453/AC2: the pinned certificate itself is accepted, in either case of hex digits.
+func TestThePinnedCertificateIsAccepted(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "hunter2")
+	a, _ := NewAdmin(f.host(), strings.ToLower(f.print()), "hunter2")
+	if err := a.Login(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// 1453/AC3: the login posts the password in the field the form names, whatever the name is (the test changes
+// it), along with the form's hidden fields, and the session cookie it gets is the one later pages are asked with.
+func TestLoginUsesThePasswordFieldNameTheFormGives(t *testing.T) {
+	for _, name := range []string{"B1891", "Zq77x"} {
+		f := newFakePrinter(t, name, "s3cret pass")
+		a, _ := NewAdmin(f.host(), f.print(), "s3cret pass")
+		ctx := context.Background()
+		if err := a.Login(ctx); err != nil {
+			t.Fatalf("field %s: %v", name, err)
+		}
+		if len(f.posted) != 1 {
+			t.Fatalf("field %s: %d forms posted", name, len(f.posted))
+		}
+		if got := f.posted[0].Get(name); got != "s3cret pass" {
+			t.Errorf("field %s: the password field holds %q", name, got)
+		}
+		if f.posted[0].Get("loginurl") != DefaultPage {
+			t.Errorf("field %s: the form's hidden loginurl was %q", name, f.posted[0].Get("loginurl"))
+		}
+		if len(f.posted[0]) != 2 {
+			t.Errorf("field %s: posted %v, want the password and loginurl only", name, f.posted[0])
+		}
+		body, _, err := a.Get(ctx, "/general/other.html")
+		if err != nil || !strings.Contains(string(body), "Synthetic settings") {
+			t.Errorf("field %s: a page behind the login was not given with the session cookie: %v %.60s", name, err, body)
+		}
+	}
+}
+
+// 1453/AC4: a wrong password is a failed login, said so: the login page comes back.
+func TestAWrongPasswordIsAFailedLogin(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "right")
+	a, _ := NewAdmin(f.host(), f.print(), "wrong")
+	err := a.Login(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "login failed") {
+		t.Fatalf("error = %v, want a failed login", err)
+	}
+	if f.loggedInNow() != 0 {
+		t.Errorf("a session was opened")
+	}
+}
+
+// 1453: the logout link on a page ends the session; a page with none says so.
+func TestLogoutEndsTheSessionAndAPageWithoutOneSaysSo(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	a, _ := NewAdmin(f.host(), f.print(), "pw")
+	ctx := context.Background()
+	if err := a.Login(ctx); err != nil {
+		t.Fatal(err)
+	}
+	body, at, err := a.Get(ctx, DefaultPage)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := a.Logout(ctx, body, at); got != "logged out" {
+		t.Errorf("logout = %q", got)
+	}
+	if f.loggedInNow() != 0 {
+		t.Errorf("the session is still open")
+	}
+	if got := a.Logout(ctx, []byte("<html><body>nothing</body></html>"), at); !strings.Contains(got, "no logout") {
+		t.Errorf("logout without a link = %q", got)
+	}
+}
+
+// 1453: the module never sends the password to a host other than the printer, even if the form says so.
+func TestThePasswordIsNotPostedToAnotherHost(t *testing.T) {
+	// A login form whose action names another host.
+	srv := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`<form method="post" action="https://elsewhere.example/x"><input type="password" name="p"/></form>`))
+	}))
+	srv.TLS = &tls.Config{}
+	srv.StartTLS()
+	defer srv.Close()
+	host := strings.TrimPrefix(srv.URL, "https://")
+	a, _ := NewAdmin(host, Fingerprint(srv.TLS.Certificates[0].Certificate[0]), "pw")
+	err := a.Login(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "not sent") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+// 1514 review: a page the printer does not have leaves no session open, and the error says the page is missing,
+// not that the login failed.
+func TestAMissingPageLeavesNoSessionOpenAndSaysSo(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	_, run := printerTools(t, f, "pw")
+	_, err := run(map[string]any{"page": "/general/nope.html"})
+	if err == nil || !strings.Contains(err.Error(), "the printer has no page /general/nope.html") {
+		t.Fatalf("error = %v, want the printer has no page", err)
+	}
+	if strings.Contains(err.Error(), "login was not answered") {
+		t.Errorf("a missing page is said to be a failed login: %v", err)
+	}
+	if f.loggedInNow() != 0 {
+		t.Errorf("%d sessions are still open on the printer", f.loggedInNow())
+	}
+}
+
+// 1514 review: the password is posted to https on the printer's host only. A form whose action is plain http
+// on the same host, or a root that redirects to plain http, is refused and nothing is posted.
+func TestThePasswordIsNotPostedOverPlainHTTP(t *testing.T) {
+	var posted int
+	mux := http.NewServeMux()
+	page := func(action string) string {
+		return `<html><body><form method="post" action="` + action + `"><input type="password" name="B1891"/><input type="hidden" name="loginurl" value="/home/status.html"/></form></body></html>`
+	}
+	var host string
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPost {
+			posted++
+		}
+		w.Write([]byte(page("http://" + host + "/home/status.html")))
+	})
+	srv := httptest.NewTLSServer(mux)
+	defer srv.Close()
+	host = strings.TrimPrefix(srv.URL, "https://")
+	a, _ := NewAdmin(host, Fingerprint(srv.TLS.Certificates[0].Certificate[0]), "pw")
+	err := a.Login(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "password is not sent") {
+		t.Errorf("error = %v, want the plain http action refused", err)
+	}
+	if posted != 0 {
+		t.Errorf("%d posts reached the server", posted)
+	}
+}
+
+// 1515: a 307 or 308 after the login post would make the HTTP client send the post again, the password with
+// it, to the place the answer names; a redirect off https or off the printer's host is refused as well.
+func TestNoRedirectResendsThePasswordOrLeavesHTTPSOnThePrinter(t *testing.T) {
+	const loginPage = `<html><body><form action="/login" method="post"><input type="password" name="pw"><input type="hidden" name="loginurl" value="/x"></form></body></html>`
+	cases := []struct {
+		name     string
+		status   int
+		location string // "SAME" is a path on the printer itself
+	}{
+		{"307 on the printer", 307, "/again"},
+		{"308 on the printer", 308, "/again"},
+		{"307 to plain http", 307, "http://192.0.2.1/steal"},
+		{"302 to another host", 302, "https://192.0.2.1/steal"},
+		{"302 to plain http", 302, "http://192.0.2.1/steal"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var mu sync.Mutex
+			var posts []string
+			srv := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				mu.Lock()
+				defer mu.Unlock()
+				switch {
+				case r.Method == http.MethodGet && r.URL.Path == "/":
+					w.Write([]byte(loginPage))
+				case r.Method == http.MethodPost:
+					r.ParseForm()
+					posts = append(posts, r.URL.Path+" "+r.PostForm.Get("pw"))
+					http.Redirect(w, r, c.location, c.status)
+				default:
+					w.Write([]byte("ok"))
+				}
+			}))
+			srv.StartTLS()
+			defer srv.Close()
+			a, _ := NewAdmin(strings.TrimPrefix(srv.URL, "https://"), Fingerprint(srv.TLS.Certificates[0].Certificate[0]), "hunter2")
+			err := a.Login(context.Background())
+			if err == nil {
+				t.Fatalf("the login went on after a %d to %s", c.status, c.location)
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			if len(posts) != 1 {
+				t.Errorf("the password was posted %d times: %v", len(posts), posts)
+			}
+		})
+	}
+}

modules/brother/cmd/brother/capture.go

@@ -0,0 +1,182 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image/jpeg"
+	"math"
+	"time"
+)
+
+// The device process's scan (novox/hq ADR 0468 clause 4): the glass scanned over eSCL, the document cut out of
+// the platen's white and built into a one-page PDF, or the feeder's sheets (both sides on request) into one multi-page PDF. Keeping it in the bucket and saying scan.added are the
+// device process's (deviceproc.go); filing it in the scan folder is the tool's (scan.go).
+
+func mm(pixels, dpi int) float64 {
+	return math.Round(float64(pixels)/float64(dpi)*25.4*10) / 10
+}
+
+// Capture is a scanned page or pages as a PDF, with what the event says of it. Width, height and resolution are
+// the first page's.
+type Capture struct {
+	PDF        []byte
+	SHA256     string
+	WidthMM    float64
+	HeightMM   float64
+	Resolution int
+	Cropped    bool
+	Pages      int
+	At         time.Time
+}
+
+// ScanRequest is what one scan asks beyond the configuration: the feeder instead of the glass, and both sides.
+type ScanRequest struct {
+	Feeder bool
+	Duplex bool
+	// Apart cuts each of several documents lying apart on the glass out as its own PDF (issue 1528); without it
+	// the glass gives one document, as it always did.
+	Apart bool
+}
+
+// ParseSource reads the scanner.scan arguments source (glass, the default, or feeder) and duplex. Duplex is for the
+// feeder: the glass holds one sheet.
+func ParseSource(source string, duplex bool) (ScanRequest, error) {
+	return ParseScan(source, duplex, false)
+}
+
+// ParseScan is ParseSource with apart: several documents on the glass, each its own file; a feeder scan is of
+// sheets and has none lying apart.
+func ParseScan(source string, duplex, apart bool) (ScanRequest, error) {
+	req, err := parseSource(source, duplex)
+	if err == nil && apart && req.Feeder {
+		return ScanRequest{}, fmt.Errorf("apart is for the glass: the feeder takes each sheet as its own page already")
+	}
+	req.Apart = apart
+	return req, err
+}
+
+func parseSource(source string, duplex bool) (ScanRequest, error) {
+	switch source {
+	case "", "glass":
+		if duplex {
+			return ScanRequest{}, fmt.Errorf("duplex is for the feeder: the glass holds one page (set source to feeder)")
+		}
+		return ScanRequest{}, nil
+	case "feeder":
+		return ScanRequest{Feeder: true, Duplex: duplex}, nil
+	}
+	return ScanRequest{}, fmt.Errorf("source %q is not glass or feeder", source)
+}
+
+// Capture scans the glass or the feeder and builds the PDFs: one for a feeder job (every page of it), and for the
+// glass one for each separate document lying on the platen when crop is set (issue 1528), in reading order. A glass
+// page is cropped when the settings say so; a feeder page is a whole sheet and never cropped. Nothing is kept and
+// nothing is said here; an error says why the scanner gave no page. The resolution is the image's own, never the
+// one asked (1440/AC2).
+func (s *Service) Capture(ctx context.Context, req ScanRequest) ([]Capture, error) {
+	at := s.Now()
+	scans, err := NewClient(s.Settings.Scanner).ScanPages(ctx, ScanOptions{Resolution: s.Settings.Resolution,
+		ColorMode: s.Settings.ColorMode, Feeder: req.Feeder, Duplex: req.Duplex})
+	if err != nil {
+		return nil, err
+	}
+	if !req.Feeder {
+		dpi, err := Density(scans[0])
+		if err != nil {
+			return nil, fmt.Errorf("page 1: %w", err)
+		}
+		cuts, err := Crop(scans[0], s.Settings.Crop)
+		one := []Cropped{cuts}
+		if req.Apart {
+			one, err = CropAll(scans[0], true, dpi)
+		}
+		if err != nil {
+			return nil, err
+		}
+		out := make([]Capture, len(one))
+		for i, cut := range one {
+			if out[i], err = captureOf([]PDFPage{{JPEG: cut.JPEG, DPI: dpi}}, cut, dpi, at); err != nil {
+				return nil, err
+			}
+		}
+		return out, nil
+	}
+	pages := make([]PDFPage, len(scans))
+	var first Cropped
+	var firstDPI int
+	for i, scan := range scans {
+		dpi, err := Density(scan)
+		if err != nil {
+			return nil, fmt.Errorf("page %d: %w", i+1, err)
+		}
+		cfg, err := jpeg.DecodeConfig(bytes.NewReader(scan))
+		if err != nil {
+			return nil, fmt.Errorf("page %d: the scanned image cannot be read: %w", i+1, err)
+		}
+		pages[i] = PDFPage{JPEG: scan, DPI: dpi}
+		if i == 0 {
+			first, firstDPI = Cropped{JPEG: scan, Width: cfg.Width, Height: cfg.Height}, dpi
+		}
+	}
+	c, err := captureOf(pages, first, firstDPI, at)
+	if err != nil {
+		return nil, err
+	}
+	return []Capture{c}, nil
+}
+
+// captureOf is the PDF of the pages, with what the event says of it from the first page.
+func captureOf(pages []PDFPage, first Cropped, firstDPI int, at time.Time) (Capture, error) {
+	pdf, err := PDFPages(pages)
+	if err != nil {
+		return Capture{}, err
+	}
+	return Capture{PDF: pdf, SHA256: sha256Hex(pdf), WidthMM: mm(first.Width, firstDPI), HeightMM: mm(first.Height, firstDPI),
+		Resolution: firstDPI, Cropped: first.Cropped, Pages: len(pages), At: at}, nil
+}
+
+// Body is the event scan.added's body (ADR 0464 §5 with the object key of ADR 0468 clause 2): never the image,
+// and no path, since filing in a folder is the tool's, after the event.
+func (c Capture) Body(node, colorMode string) map[string]any {
+	pages := max(c.Pages, 1)
+	return map[string]any{
+		"object":     c.SHA256 + ".pdf",
+		"node":       node,
+		"bytes":      len(c.PDF),
+		"sha256":     c.SHA256,
+		"width-mm":   c.WidthMM,
+		"height-mm":  c.HeightMM,
+		"resolution": c.Resolution,
+		"color-mode": colorMode,
+		"cropped":    c.Cropped,
+		"pages":      pages,
+		"scanned-at": c.At.UTC().Format(time.RFC3339),
+	}
+}
+
+// GlassImage is a page scanned from the glass.
+type GlassImage struct {
+	JPEG               []byte
+	DPI, Width, Height int
+	Cropped            bool
+}
+
+// GlassPage scans one page from the glass for a document of several pages: cropped to its document when the settings
+// say so (the first document, never split in several), with the resolution the scanner gave.
+func (s *Service) GlassPage(ctx context.Context) (page GlassImage, err error) {
+	scans, err := NewClient(s.Settings.Scanner).ScanPages(ctx, ScanOptions{Resolution: s.Settings.Resolution, ColorMode: s.Settings.ColorMode})
+	if err != nil {
+		return page, err
+	}
+	dpi, err := Density(scans[0])
+	if err != nil {
+		return page, err
+	}
+	cut, err := Crop(scans[0], s.Settings.Crop)
+	if err != nil {
+		return page, err
+	}
+	page.JPEG, page.DPI, page.Width, page.Height, page.Cropped = cut.JPEG, dpi, cut.Width, cut.Height, cut.Cropped
+	return page, nil
+}

modules/brother/cmd/brother/certcheck.go

@@ -0,0 +1,143 @@
+package main
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"net"
+	"slices"
+	"strings"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/health"
+)
+
+// The module's health (issue 1510, novox/hq ADR 0240): the node-engine asks the tool brother_health, and the tool
+// asks the printer for the certificates it serves, one for each key type, with no login, and compares them with
+// the pinned list (the config value printer-certificate). A certificate that is not pinned (the printer was reset,
+// new certificates were made, a firmware update changed them) is unhealthy and names the new fingerprint, so the
+// operator can approve the new pin before the admin pages are needed. A printer that does not answer is not
+// unhealthy (it is switched off, or asleep): nothing can be compared, and the answer says so.
+
+// keyKinds are the two certificates the printer serves for one name. Which one it serves depends on the cipher
+// suites the client offers, so each handshake offers only one kind's, under TLS 1.2 (where the suite decides).
+var keyKinds = []struct {
+	Name   string
+	Suites []uint16
+}{
+	{"ecdsa", []uint16{
+		tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
+		tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, tls.TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, tls.TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
+	}},
+	{"rsa", []uint16{
+		tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+		tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, tls.TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, tls.TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
+		tls.TLS_RSA_WITH_AES_128_GCM_SHA256, tls.TLS_RSA_WITH_AES_256_GCM_SHA384, tls.TLS_RSA_WITH_AES_128_CBC_SHA, tls.TLS_RSA_WITH_AES_256_CBC_SHA,
+	}},
+}
+
+// certDial bounds one handshake and certTotal the whole check (two handshakes), so the node-engine's look, which has
+// ten seconds, is always answered (issue 1510).
+var (
+	certDial  = 3 * time.Second
+	certTotal = 7 * time.Second
+)
+
+// Served is a certificate the printer served to a handshake of one key type.
+type Served struct {
+	Key         string `json:"key"`
+	Fingerprint string `json:"fingerprint,omitempty"`
+	Pinned      bool   `json:"pinned"`
+	Note        string `json:"note,omitempty"`
+}
+
+// CertHealth is brother_health's answer: healthy, why when it is not (or what could not be compared), and what the
+// printer served.
+type CertHealth struct {
+	Healthy bool     `json:"healthy"`
+	State   string   `json:"state"` // healthy, unhealthy or waits (ADR 0283)
+	Why     string   `json:"why"`
+	Served  []Served `json:"served"`
+}
+
+// CertWaits is the answer while printer or printer-certificate is not given: the module waits for the operator,
+// which is not a fault (ADR 0283), and names each setting as the SDK's health.Wait asks.
+func CertWaits(s Settings) (health.Answer, bool) {
+	var waits []health.Wait
+	var names []string
+	for _, c := range []struct{ name, value, what string }{
+		{"printer", s.Printer, "the printer's address"},
+		{"printer-certificate", s.PrinterCertificate, "the SHA-256 fingerprints of the certificates the printer serves"},
+	} {
+		if c.value == "" {
+			waits = append(waits, health.Wait{Part: "the printer's certificate check", Setting: c.name, What: c.what})
+			names = append(names, c.name)
+		}
+	}
+	if len(waits) == 0 {
+		return health.Answer{}, false
+	}
+	return health.Waiting("waits for the operator to give the config value "+strings.Join(names, " and "), waits...), true
+}
+
+// serveAddr is the host with the HTTPS port when it names none.
+func serveAddr(host string) string {
+	if _, _, err := net.SplitHostPort(host); err == nil {
+		return host
+	}
+	return net.JoinHostPort(strings.Trim(host, "[]"), "443")
+}
+
+// served is the leaf's fingerprint the printer gives a handshake that offers only these suites, or why it gave none.
+func served(ctx context.Context, addr string, suites []uint16) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, certDial)
+	defer cancel()
+	d := tls.Dialer{NetDialer: &net.Dialer{Timeout: certDial}, Config: &tls.Config{
+		MinVersion: tls.VersionTLS12, MaxVersion: tls.VersionTLS12, CipherSuites: suites,
+		// Nothing is sent over this connection, and the certificate is only read, to be compared with the pins.
+		InsecureSkipVerify: true,
+	}}
+	conn, err := d.DialContext(ctx, "tcp", addr)
+	if err != nil {
+		return "", err
+	}
+	defer conn.Close()
+	state := conn.(*tls.Conn).ConnectionState()
+	if len(state.PeerCertificates) == 0 {
+		return "", fmt.Errorf("the printer served no certificate")
+	}
+	return Fingerprint(state.PeerCertificates[0].Raw), nil
+}
+
+// CheckCertificates compares what the printer serves with the pins. The login is never used.
+func CheckCertificates(ctx context.Context, host, pins string) CertHealth {
+	ctx, cancel := context.WithTimeout(ctx, certTotal)
+	defer cancel()
+	want := pinList(pins)
+	addr := serveAddr(host)
+	h := CertHealth{Healthy: true, State: "healthy"}
+	var changed, unreachable []string
+	for _, k := range keyKinds {
+		s := Served{Key: k.Name}
+		fp, err := served(ctx, addr, k.Suites)
+		if err != nil {
+			s.Note = err.Error()
+			unreachable = append(unreachable, k.Name+": "+err.Error())
+		} else {
+			s.Fingerprint, s.Pinned = fp, slices.Contains(want, fp)
+			if !s.Pinned {
+				changed = append(changed, fmt.Sprintf("the %s certificate is now %s", k.Name, fp))
+			}
+		}
+		h.Served = append(h.Served, s)
+	}
+	switch {
+	case len(changed) > 0:
+		h.Healthy, h.State = false, "unhealthy"
+		h.Why = fmt.Sprintf("the printer serves a certificate that is not pinned: %s; the pinned printer-certificate is %s. If the printer was reset or given new certificates, set printer-certificate to the new fingerprint(s) (with the old ones kept if they still serve)",
+			strings.Join(changed, "; "), strings.Join(want, ", "))
+	case len(unreachable) == len(keyKinds):
+		h.Why = "the printer gave no certificate, so none was compared (it may be switched off or asleep): " + strings.Join(unreachable, "; ")
+	}
+	return h
+}

modules/brother/cmd/brother/certcheck_test.go

@@ -0,0 +1,160 @@
+package main
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/json"
+	"math/big"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/health"
+)
+
+// selfSigned is a self-signed certificate over the key.
+func selfSigned(t *testing.T, key any, pub any) tls.Certificate {
+	t.Helper()
+	tpl := &x509.Certificate{SerialNumber: big.NewInt(time.Now().UnixNano()), Subject: pkix.Name{CommonName: "printer.test"},
+		NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(24 * time.Hour), DNSNames: []string{"printer.test"}}
+	der, err := x509.CreateCertificate(rand.Reader, tpl, tpl, pub, key)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return tls.Certificate{Certificate: [][]byte{der}, PrivateKey: key}
+}
+
+// twoCertPrinter is a TLS server with an ECDSA and an RSA certificate, as the printer has; it answers its address
+// and the two fingerprints.
+func twoCertPrinter(t *testing.T) (addr, ecdsaFP, rsaFP string) {
+	t.Helper()
+	ek, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	rk, _ := rsa.GenerateKey(rand.Reader, 2048)
+	ec, rc := selfSigned(t, ek, &ek.PublicKey), selfSigned(t, rk, &rk.PublicKey)
+	ln, err := tls.Listen("tcp", "127.0.0.1:0", &tls.Config{Certificates: []tls.Certificate{ec, rc}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { ln.Close() })
+	go func() {
+		for {
+			c, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			go func() { c.(*tls.Conn).Handshake(); c.Close() }()
+		}
+	}()
+	return ln.Addr().String(), Fingerprint(ec.Certificate[0]), Fingerprint(rc.Certificate[0])
+}
+
+// 1510: both certificates pinned is healthy; a changed one is unhealthy and names the new fingerprint; none
+// pinned names both.
+func TestTheHealthComparesBothServedCertificatesWithThePins(t *testing.T) {
+	addr, e, r := twoCertPrinter(t)
+	ctx := context.Background()
+	if h := CheckCertificates(ctx, addr, e+", "+r); !h.Healthy || len(h.Served) != 2 || !h.Served[0].Pinned || !h.Served[1].Pinned {
+		t.Errorf("both pinned: %+v", h)
+	}
+	old := strings.Repeat("AB:", 31) + "AB"
+	h := CheckCertificates(ctx, addr, e+", "+old) // the RSA certificate changed
+	if h.Healthy || !strings.Contains(h.Why, r) || strings.Contains(h.Why, "ecdsa certificate is now") {
+		t.Errorf("rsa changed: %+v", h)
+	}
+	h = CheckCertificates(ctx, addr, old+", "+r) // the ECDSA certificate changed
+	if h.Healthy || !strings.Contains(h.Why, e) || strings.Contains(h.Why, "rsa certificate is now") {
+		t.Errorf("ecdsa changed: %+v", h)
+	}
+	h = CheckCertificates(ctx, addr, old)
+	if h.Healthy || !strings.Contains(h.Why, e) || !strings.Contains(h.Why, r) || !strings.Contains(h.Why, old) {
+		t.Errorf("none pinned: %+v", h)
+	}
+}
+
+// 1510: a printer that does not answer is not an unhealthy module: nothing can be compared, and the answer says so.
+func TestAPrinterThatDoesNotAnswerIsNotUnhealthy(t *testing.T) {
+	ln, _ := net.Listen("tcp", "127.0.0.1:0")
+	addr := ln.Addr().String()
+	ln.Close()
+	h := CheckCertificates(context.Background(), addr, strings.Repeat("AB:", 31)+"AB")
+	if !h.Healthy || !strings.Contains(h.Why, "none was compared") {
+		t.Errorf("%+v", h)
+	}
+}
+
+// 1510: brother_health is a tool of the module, read from the settings at each call.
+func TestBrotherHealthIsAToolThatReadsTheSettings(t *testing.T) {
+	addr, e, r := twoCertPrinter(t)
+	js := `{"printer":"` + addr + `","printer-certificate":"` + e + `, ` + r + `"}`
+	run := tool(t, newRig(t, js, "pw").tl, "brother_health").Run
+	got, err := run(map[string]any{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h, ok := got.(CertHealth); !ok || !h.Healthy {
+		t.Errorf("answer = %+v", got)
+	}
+	bad := `{"printer":"` + addr + `","printer-certificate":"` + strings.Repeat("AB:", 31) + `AB"}`
+	got, _ = tool(t, newRig(t, bad, "pw").tl, "brother_health").Run(map[string]any{})
+	if h := got.(CertHealth); h.Healthy {
+		t.Errorf("a wrong pin is healthy: %+v", h)
+	}
+}
+
+// 1510: with the printer not given the answer is waits, read by the SDK as the engine reads it: state waits, each
+// wait naming exactly one setting, a part and what is wanted; not an error and not unhealthy.
+func TestHealthWaitsForTheSettingsTheOperatorHasYetToGive(t *testing.T) {
+	for js, want := range map[string][]string{`{}`: {"printer", "printer-certificate"}, `{"printer":"192.0.2.10"}`: {"printer-certificate"}} {
+		got, err := tool(t, newRig(t, js, "pw").tl, "brother_health").Run(map[string]any{})
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, _ := json.Marshal(got)
+		a, err := health.Read(raw)
+		if err != nil || a.State != health.StateWaits || len(a.Waits) != len(want) {
+			t.Fatalf("%s: read as %+v, %v", js, a, err)
+		}
+		for i, w := range a.Waits {
+			if w.Setting != want[i] || w.Check() != nil {
+				t.Errorf("%s: wait %d = %+v (%v)", js, i, w, w.Check())
+			}
+		}
+	}
+}
+
+// 1510: each handshake is bounded by 3 s and the whole check by 7 s, and a printer that accepts and never answers
+// ends the check at the bound with the module healthy (nothing compared).
+func TestTheCheckIsBoundedAndAHungPrinterEndsItAtTheBound(t *testing.T) {
+	if certDial != 3*time.Second || certTotal != 7*time.Second {
+		t.Fatalf("bounds = %s and %s, want 3 s and 7 s", certDial, certTotal)
+	}
+	ln, _ := net.Listen("tcp", "127.0.0.1:0")
+	defer ln.Close()
+	go func() {
+		for {
+			c, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			defer c.Close() // held open, never answered
+		}
+	}()
+	oldD, oldT := certDial, certTotal
+	certDial, certTotal = 200*time.Millisecond, 500*time.Millisecond
+	t.Cleanup(func() { certDial, certTotal = oldD, oldT })
+	start := time.Now()
+	h := CheckCertificates(context.Background(), ln.Addr().String(), strings.Repeat("AB:", 31)+"AB")
+	if took := time.Since(start); took > 700*time.Millisecond {
+		t.Errorf("the check took %s", took)
+	}
+	if !h.Healthy || !strings.Contains(h.Why, "none was compared") {
+		t.Errorf("%+v", h)
+	}
+}

modules/brother/cmd/brother/crop.go

@@ -0,0 +1,343 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"sort"
+)
+
+// Cropping cuts the document out of the platen. The scanner sends the whole glass, a document in one corner
+// and the lid's white everywhere else. The lid's level is measured where no document can be (the corner
+// farthest from the origin), a pixel is document when it is darker than the lid by a margin, and the rows and
+// columns holding enough document pixels give the box (ADR 0464).
+const (
+	// lidBlock is the side of the corner block the lid's level is measured on.
+	lidBlock = 300
+	// darker is how much darker than the lid a pixel is document: paper on a white lid is a level or two
+	// under it, an edge shadow far more.
+	darker = 1
+	// rowShare is the fraction of a row's (column's) length that must be document for the row (column) to
+	// count: specks of dust stay under it.
+	rowShare = 0.05
+	// margin is the pixels kept around the box.
+	margin = 6
+	// wholeShare is the fraction of the platen a box may fill before it is no crop at all.
+	wholeShare = 0.9
+	// jpegQuality is the quality the cropped image is encoded with.
+	jpegQuality = 90
+)
+
+// gray is the pixel's level, 0 to 255.
+func grayAt(img image.Image, x, y int) int {
+	switch m := img.(type) {
+	case *image.YCbCr:
+		return int(m.Y[m.YOffset(x, y)])
+	case *image.Gray:
+		return int(m.Pix[m.PixOffset(x, y)])
+	}
+	return int(color.GrayModel.Convert(img.At(x, y)).(color.Gray).Y)
+}
+
+// Box finds the document's box in the image, and whether there is one: false when no document is found or
+// when it fills (almost) the platen.
+func Box(img image.Image) (image.Rectangle, bool) {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	if w < 2*margin || h < 2*margin {
+		return b, false
+	}
+	limit := lidLimit(img)
+
+	cols := make([]int, w)
+	rows := make([]int, h)
+	for y := b.Min.Y; y < b.Max.Y; y++ {
+		for x := b.Min.X; x < b.Max.X; x++ {
+			if grayAt(img, x, y) < limit {
+				cols[x-b.Min.X]++
+				rows[y-b.Min.Y]++
+			}
+		}
+	}
+	x0, x1 := span(cols, int(rowShare*float64(h)))
+	y0, y1 := span(rows, int(rowShare*float64(w)))
+	if x0 < 0 || y0 < 0 {
+		return b, false
+	}
+	box := image.Rect(max(0, x0-margin), max(0, y0-margin), min(w, x1+1+margin), min(h, y1+1+margin)).Add(b.Min)
+	if float64(box.Dx()*box.Dy()) >= wholeShare*float64(w*h) {
+		return b, false
+	}
+	return box, true
+}
+
+// lidLimit is the level under which a pixel is document: the lid's level, measured in the corner block farthest
+// from the origin, less darker.
+func lidLimit(img image.Image) int {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	side := lidBlock
+	if side > w/2 {
+		side = w / 2
+	}
+	if side > h/2 {
+		side = h / 2
+	}
+	sum := 0
+	for y := b.Max.Y - side; y < b.Max.Y; y++ {
+		for x := b.Max.X - side; x < b.Max.X; x++ {
+			sum += grayAt(img, x, y)
+		}
+	}
+	lid := int(float64(sum)/float64(side*side) + 0.5)
+	return lid - darker
+}
+
+// span is the first and last index whose count is over the floor, or -1 when none is.
+func span(counts []int, floor int) (int, int) {
+	first, last := -1, -1
+	for i, c := range counts {
+		if c > floor {
+			if first < 0 {
+				first = i
+			}
+			last = i
+		}
+	}
+	return first, last
+}
+
+// Cropped is what cropping a scan gave.
+type Cropped struct {
+	// JPEG is the image to file: the scanner's own bytes when kept whole, a re-encoded crop otherwise.
+	JPEG          []byte
+	Width, Height int
+	Cropped       bool
+}
+
+// Crop cuts the document out of a scanned JPEG when crop is set and a document is found; otherwise the whole
+// image is kept, its bytes untouched, and Cropped is false.
+func Crop(scan []byte, crop bool) (Cropped, error) {
+	img, err := jpeg.Decode(bytes.NewReader(scan))
+	if err != nil {
+		return Cropped{}, fmt.Errorf("the scanned image cannot be read: %w", err)
+	}
+	b := img.Bounds()
+	whole := Cropped{JPEG: scan, Width: b.Dx(), Height: b.Dy()}
+	if !crop {
+		return whole, nil
+	}
+	box, found := Box(img)
+	if !found {
+		return whole, nil
+	}
+	sub, ok := img.(interface {
+		SubImage(image.Rectangle) image.Image
+	})
+	if !ok {
+		return whole, nil
+	}
+	var out bytes.Buffer
+	if err := jpeg.Encode(&out, sub.SubImage(box), &jpeg.Options{Quality: jpegQuality}); err != nil {
+		return Cropped{}, fmt.Errorf("the cropped image cannot be encoded: %w", err)
+	}
+	return Cropped{JPEG: out.Bytes(), Width: box.Dx(), Height: box.Dy(), Cropped: true}, nil
+}
+
+// Several documents on the glass (issue 1528). Where the rows-and-columns box of Box would be one image around
+// all of them, Boxes finds each document apart from the others: the picture is cut into blocks of about a
+// millimetre, a block is document when a quarter of its pixels are darker than the lid (dust is not), blocks
+// within gapMM of each other are one region (so a white area inside a document, or a gap in it, does not split
+// it), and a region of at least minMM on both sides is a document. Regions whose boxes touch or overlap
+// (a text block inside a document's frame) are one document.
+const (
+	// blockMM is the side of a block, in millimetres.
+	blockMM = 1.0
+	// blockShare is the fraction of a block's pixels that must be document for the block to count.
+	blockShare = 0.25
+	// gapMM is how near two regions must be to be one document, in millimetres: documents lying farther apart than
+	// this are separate ones.
+	gapMM = 10.0
+	// minMM is the least a region may measure, on both sides, to be a document and not a speck or a stain.
+	minMM = 20.0
+)
+
+// Boxes is the box of each separate document on the platen, in reading order (top to bottom by the box's top,
+// then left to right), at the image's resolution dpi. It is Box's white-detection (the lid's level and darker) on
+// a grid of blocks. A box that fills (almost) the platen is no crop: then the whole image is the answer, as one
+// box with found false.
+func Boxes(img image.Image, dpi int) ([]image.Rectangle, bool) {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	if dpi <= 0 || w < 2*margin || h < 2*margin {
+		return []image.Rectangle{b}, false
+	}
+	bs := max(2, int(blockMM*float64(dpi)/25.4+0.5))
+	gw, gh := (w+bs-1)/bs, (h+bs-1)/bs
+	limit := lidLimit(img)
+	doc := make([]bool, gw*gh)
+	for gy := 0; gy < gh; gy++ {
+		for gx := 0; gx < gw; gx++ {
+			dark, total := 0, 0
+			for y := b.Min.Y + gy*bs; y < min(b.Min.Y+(gy+1)*bs, b.Max.Y); y++ {
+				for x := b.Min.X + gx*bs; x < min(b.Min.X+(gx+1)*bs, b.Max.X); x++ {
+					total++
+					if grayAt(img, x, y) < limit {
+						dark++
+					}
+				}
+			}
+			doc[gy*gw+gx] = float64(dark) >= blockShare*float64(total)
+		}
+	}
+	// Dust and the ringing of the JPEG around it make single blocks, or a pair, of "document": an opening (every
+	// block must have all eight neighbours document to survive, and survivors give back their neighbours that are
+	// document) removes what is not at least three blocks across.
+	eroded := make([]bool, gw*gh)
+	for gy := 1; gy < gh-1; gy++ {
+		for gx := 1; gx < gw-1; gx++ {
+			all := true
+			for y := gy - 1; y <= gy+1 && all; y++ {
+				for x := gx - 1; x <= gx+1; x++ {
+					if !doc[y*gw+x] {
+						all = false
+						break
+					}
+				}
+			}
+			eroded[gy*gw+gx] = all
+		}
+	}
+	opened := make([]bool, gw*gh)
+	for gy := 0; gy < gh; gy++ {
+		for gx := 0; gx < gw; gx++ {
+			if !eroded[gy*gw+gx] {
+				continue
+			}
+			for y := gy - 1; y <= gy+1; y++ {
+				for x := gx - 1; x <= gx+1; x++ {
+					opened[y*gw+x] = true
+				}
+			}
+		}
+	}
+	doc = opened
+	// Join the blocks within the gap: a block is near when it is within gapBlocks/2 of a document block in each
+	// direction (so two blocks up to gapBlocks apart meet), then the nearby blocks are labelled in 4-connected
+	// regions; each region's box is that of the document blocks in it.
+	radius := int(gapMM * float64(dpi) / 25.4 / float64(bs) / 2)
+	near := make([]bool, gw*gh)
+	for gy := 0; gy < gh; gy++ {
+		for gx := 0; gx < gw; gx++ {
+			if !doc[gy*gw+gx] {
+				continue
+			}
+			for y := max(0, gy-radius); y <= min(gh-1, gy+radius); y++ {
+				for x := max(0, gx-radius); x <= min(gw-1, gx+radius); x++ {
+					near[y*gw+x] = true
+				}
+			}
+		}
+	}
+	seen := make([]bool, gw*gh)
+	var boxes []image.Rectangle
+	for start := range near {
+		if !near[start] || seen[start] {
+			continue
+		}
+		minX, minY, maxX, maxY := gw, gh, -1, -1
+		stack := []int{start}
+		seen[start] = true
+		for len(stack) > 0 {
+			c := stack[len(stack)-1]
+			stack = stack[:len(stack)-1]
+			cx, cy := c%gw, c/gw
+			if doc[c] {
+				minX, minY, maxX, maxY = min(minX, cx), min(minY, cy), max(maxX, cx), max(maxY, cy)
+			}
+			for _, d := range [4][2]int{{1, 0}, {-1, 0}, {0, 1}, {0, -1}} {
+				x, y := cx+d[0], cy+d[1]
+				if x < 0 || y < 0 || x >= gw || y >= gh || !near[y*gw+x] || seen[y*gw+x] {
+					continue
+				}
+				seen[y*gw+x] = true
+				stack = append(stack, y*gw+x)
+			}
+		}
+		if maxX < 0 {
+			continue
+		}
+		r := image.Rect(minX*bs, minY*bs, (maxX+1)*bs, (maxY+1)*bs)
+		if float64(r.Dx())/float64(dpi)*25.4 < minMM || float64(r.Dy())/float64(dpi)*25.4 < minMM {
+			continue
+		}
+		boxes = append(boxes, r)
+	}
+	// Boxes that touch or overlap are one document: a frame and the text inside it, or a faint paper whose
+	// parts the lid's white hides, are one however far apart their blocks lie.
+	kept := boxes
+	for merged := true; merged; {
+		merged = false
+		for i := 0; i < len(kept) && !merged; i++ {
+			for j := i + 1; j < len(kept); j++ {
+				if kept[i].Overlaps(kept[j]) {
+					kept[i] = kept[i].Union(kept[j])
+					kept = append(kept[:j], kept[j+1:]...)
+					merged = true
+					break
+				}
+			}
+		}
+	}
+	if len(kept) == 0 {
+		return []image.Rectangle{b}, false
+	}
+	out := make([]image.Rectangle, len(kept))
+	for i, r := range kept {
+		out[i] = image.Rect(max(0, r.Min.X-margin), max(0, r.Min.Y-margin), min(w, r.Max.X+margin), min(h, r.Max.Y+margin)).Add(b.Min)
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].Min.Y != out[j].Min.Y {
+			return out[i].Min.Y < out[j].Min.Y
+		}
+		return out[i].Min.X < out[j].Min.X
+	})
+	if len(out) == 1 && float64(out[0].Dx()*out[0].Dy()) >= wholeShare*float64(w*h) {
+		return []image.Rectangle{b}, false
+	}
+	return out, true
+}
+
+// CropAll cuts each separate document out of a scanned glass JPEG when crop is set and there are two or more; one
+// document, none or crop off is Crop's answer, exactly as before. dpi is the scan's resolution.
+func CropAll(scan []byte, crop bool, dpi int) ([]Cropped, error) {
+	one, err := Crop(scan, crop)
+	if err != nil || !crop {
+		return []Cropped{one}, err
+	}
+	img, err := jpeg.Decode(bytes.NewReader(scan))
+	if err != nil {
+		return nil, fmt.Errorf("the scanned image cannot be read: %w", err)
+	}
+	boxes, found := Boxes(img, dpi)
+	if !found || len(boxes) < 2 {
+		return []Cropped{one}, nil
+	}
+	sub, ok := img.(interface {
+		SubImage(image.Rectangle) image.Image
+	})
+	if !ok {
+		return []Cropped{one}, nil
+	}
+	out := make([]Cropped, 0, len(boxes))
+	for _, box := range boxes {
+		var buf bytes.Buffer
+		if err := jpeg.Encode(&buf, sub.SubImage(box), &jpeg.Options{Quality: jpegQuality}); err != nil {
+			return nil, fmt.Errorf("the cropped image cannot be encoded: %w", err)
+		}
+		out = append(out, Cropped{JPEG: buf.Bytes(), Width: box.Dx(), Height: box.Dy(), Cropped: true})
+	}
+	return out, nil
+}

modules/brother/cmd/brother/crop_test.go

@@ -0,0 +1,229 @@
+package main
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/draw"
+	"image/jpeg"
+	"math/rand"
+	"testing"
+)
+
+// lidWhite is a w x h gray image of the lid's white, with a few specks of dust in one patch.
+func lidWhite(w, h int, seed int64) *image.Gray {
+	g := image.NewGray(image.Rect(0, 0, w, h))
+	draw.Draw(g, g.Bounds(), &image.Uniform{color.Gray{255}}, image.Point{}, draw.Src)
+	r := rand.New(rand.NewSource(seed))
+	for i := 0; i < 40; i++ {
+		g.SetGray(100+r.Intn(w/4), 100+r.Intn(h/4), color.Gray{120}) // all in one patch, so counting them would make a box
+	}
+	return g
+}
+
+func encode(t *testing.T, img image.Image) []byte {
+	t.Helper()
+	var b bytes.Buffer
+	if err := jpeg.Encode(&b, img, &jpeg.Options{Quality: 95}); err != nil {
+		t.Fatal(err)
+	}
+	return b.Bytes()
+}
+
+// 1440/AC3: the captured receipt, top-left of a 1696x2203 scan at 200 dpi.
+func TestCropFindsTheCapturedReceipt(t *testing.T) {
+	c, err := Crop(fixture(t, "scan.jpg"), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !c.Cropped {
+		t.Fatal("cropped = false for a scan with a receipt on it")
+	}
+	img, err := jpeg.Decode(bytes.NewReader(fixture(t, "scan.jpg")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	box, found := Box(img)
+	if !found {
+		t.Fatal("no box found")
+	}
+	if box.Min.X > 10 || box.Min.Y > 10 {
+		t.Errorf("box starts at %v, want within 10 px of (0,0)", box.Min)
+	}
+	if box.Max.X < 630 || box.Max.X > 660 {
+		t.Errorf("right edge %d, want 630..660", box.Max.X)
+	}
+	if box.Max.Y < 1730 || box.Max.Y > 1810 {
+		t.Errorf("bottom %d, want 1730..1810", box.Max.Y)
+	}
+	if c.Width != box.Dx() || c.Height != box.Dy() {
+		t.Errorf("cropped image is %dx%d, the box %dx%d", c.Width, c.Height, box.Dx(), box.Dy())
+	}
+	got, err := jpeg.DecodeConfig(bytes.NewReader(c.JPEG))
+	if err != nil || got.Width != box.Dx() || got.Height != box.Dy() {
+		t.Errorf("the cropped JPEG is %+v (%v), want %dx%d", got, err, box.Dx(), box.Dy())
+	}
+	// About 80-84 mm wide at 200 dpi.
+	if mm := float64(c.Width) / 200 * 25.4; mm < 80 || mm > 84 {
+		t.Errorf("%.1f mm wide, want 80-84", mm)
+	}
+}
+
+// 1440/AC4: a plain lid with specks has no document.
+func TestCropKeepsAPlainLidWhole(t *testing.T) {
+	scan := encode(t, lidWhite(800, 1100, 1))
+	c, err := Crop(scan, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Cropped || c.Width != 800 || c.Height != 1100 || !bytes.Equal(c.JPEG, scan) {
+		t.Fatalf("a plain lid was cropped: %+v", c)
+	}
+}
+
+// 1440/AC4: a document that fills the platen is no crop either.
+func TestCropKeepsAFullPlatenDocumentWhole(t *testing.T) {
+	g := lidWhite(800, 1100, 2)
+	draw.Draw(g, image.Rect(0, 0, 790, 1090), &image.Uniform{color.Gray{200}}, image.Point{}, draw.Src)
+	scan := encode(t, g)
+	c, err := Crop(scan, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Cropped || c.Width != 800 || c.Height != 1100 {
+		t.Fatalf("a document filling the platen was cropped: %+v", c)
+	}
+}
+
+// 1440/AC4: crop=false keeps the captured scan whole, though it has a document.
+func TestCropOffKeepsTheWholeImage(t *testing.T) {
+	scan := fixture(t, "scan.jpg")
+	c, err := Crop(scan, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Cropped || c.Width != 1696 || c.Height != 2203 || !bytes.Equal(c.JPEG, scan) {
+		t.Fatalf("crop=false cropped: %+v", c)
+	}
+}
+
+// 1440/AC3: a document away from the origin is found where it is, not assumed in the corner.
+func TestCropFindsADocumentInTheMiddleOfTheGlass(t *testing.T) {
+	g := lidWhite(800, 1100, 3)
+	draw.Draw(g, image.Rect(200, 300, 500, 700), &image.Uniform{color.Gray{240}}, image.Point{}, draw.Src)
+	img, err := jpeg.Decode(bytes.NewReader(encode(t, g)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	box, found := Box(img)
+	if !found {
+		t.Fatal("no box")
+	}
+	if box.Min.X < 190 || box.Min.X > 205 || box.Max.X < 495 || box.Max.X > 510 || box.Min.Y < 290 || box.Min.Y > 305 || box.Max.Y < 695 || box.Max.Y > 710 {
+		t.Fatalf("box = %v, want about (200,300)-(500,700)", box)
+	}
+}
+
+// onWhite is a lid-white image of w x h with the rectangles drawn on it in gray (generated, not captured: the
+// thresholds of Boxes are in millimetres, and this is 100 dpi, 1 mm about 4 px).
+func onWhite(t *testing.T, seed int64, rects ...image.Rectangle) []byte {
+	t.Helper()
+	g := lidWhite(800, 1100, seed)
+	for _, r := range rects {
+		draw.Draw(g, r, &image.Uniform{color.Gray{200}}, image.Point{}, draw.Src)
+	}
+	return encode(t, g)
+}
+
+// 1528: documents lying apart on the white are each cut out, in reading order; one document, as before, is one.
+func TestCropAllCutsEachDocumentApartFromTheOthers(t *testing.T) {
+	a := image.Rect(100, 100, 300, 300) // 51 mm square
+	b := image.Rect(450, 100, 650, 400) // 38 mm right of a
+	c := image.Rect(100, 600, 400, 900)
+	for name, tc := range map[string]struct {
+		rects []image.Rectangle
+		want  []image.Rectangle
+	}{
+		"one":   {[]image.Rectangle{a}, nil},
+		"two":   {[]image.Rectangle{b, a}, []image.Rectangle{a, b}},
+		"three": {[]image.Rectangle{c, b, a}, []image.Rectangle{a, b, c}},
+	} {
+		got, err := CropAll(onWhite(t, 5, tc.rects...), true, 100)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if tc.want == nil {
+			one, _ := Crop(onWhite(t, 5, a), true)
+			if len(got) != 1 || !bytes.Equal(got[0].JPEG, one.JPEG) {
+				t.Errorf("%s: one document is not Crop's answer", name)
+			}
+			continue
+		}
+		if len(got) != len(tc.want) {
+			t.Fatalf("%s: %d documents, want %d", name, len(got), len(tc.want))
+		}
+		for i, w := range tc.want {
+			// about the rectangle, within the margin and a block of rounding
+			if !got[i].Cropped || got[i].Width < w.Dx() || got[i].Width > w.Dx()+2*margin+2*4 || got[i].Height < w.Dy() || got[i].Height > w.Dy()+2*margin+2*4 {
+				t.Errorf("%s: document %d is %dx%d, want about %dx%d", name, i, got[i].Width, got[i].Height, w.Dx(), w.Dy())
+			}
+			cfg, err := jpeg.DecodeConfig(bytes.NewReader(got[i].JPEG))
+			if err != nil || cfg.Width != got[i].Width {
+				t.Errorf("%s: document %d JPEG %+v %v", name, i, cfg, err)
+			}
+		}
+	}
+}
+
+// 1528: one document with a white area inside it is not split: a frame with an island inside it, a sheet with a
+// white band across it narrower than the gap, and specks of dust beside it.
+func TestCropAllDoesNotSplitOneDocumentWithWhiteInsideIt(t *testing.T) {
+	g := lidWhite(800, 1100, 6)
+	frame := image.Rect(100, 100, 600, 800)
+	draw.Draw(g, frame, &image.Uniform{color.Gray{200}}, image.Point{}, draw.Src)
+	draw.Draw(g, frame.Inset(50), &image.Uniform{color.Gray{255}}, image.Point{}, draw.Src)                // white inside the frame
+	draw.Draw(g, image.Rect(300, 400, 400, 500), &image.Uniform{color.Gray{200}}, image.Point{}, draw.Src) // an island in it
+	got, err := CropAll(encode(t, g), true, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("a frame with an island inside was cut into %d documents", len(got))
+	}
+
+	g = lidWhite(800, 1100, 7)
+	draw.Draw(g, image.Rect(100, 100, 500, 500), &image.Uniform{color.Gray{200}}, image.Point{}, draw.Src)
+	draw.Draw(g, image.Rect(100, 530, 500, 900), &image.Uniform{color.Gray{200}}, image.Point{}, draw.Src) // 30 px = 7.6 mm of white between
+	got, err = CropAll(encode(t, g), true, 100)
+	if err != nil || len(got) != 1 {
+		t.Fatalf("a sheet with a narrow white band across it: %d documents, %v", len(got), err)
+	}
+}
+
+// 1528: a speck smaller than the minimum is no document, and crop off files the whole platen as one.
+func TestCropAllIgnoresSpecksAndCropOffIsOneWholeImage(t *testing.T) {
+	scan := onWhite(t, 8, image.Rect(100, 100, 300, 300), image.Rect(600, 800, 620, 815)) // 5 x 4 mm stain
+	got, err := CropAll(scan, true, 100)
+	if err != nil || len(got) != 1 {
+		t.Fatalf("a stain made %d documents (%v)", len(got), err)
+	}
+	two := onWhite(t, 9, image.Rect(100, 100, 300, 300), image.Rect(450, 100, 650, 400))
+	got, err = CropAll(two, false, 100)
+	if err != nil || len(got) != 1 || got[0].Cropped {
+		t.Fatalf("crop off: %d documents, cropped %v", len(got), got[0].Cropped)
+	}
+}
+
+// 1528: the captured scan (one receipt) is one document, the same bytes Crop gives.
+func TestCropAllOfTheCapturedReceiptIsCropsAnswer(t *testing.T) {
+	scan := fixture(t, "scan.jpg")
+	got, err := CropAll(scan, true, 200)
+	one, _ := Crop(scan, true)
+	if err != nil || len(got) != 1 || !bytes.Equal(got[0].JPEG, one.JPEG) {
+		t.Fatalf("%d documents (%v), want Crop's one", len(got), err)
+	}
+	img, _ := jpeg.Decode(bytes.NewReader(scan))
+	if boxes, _ := Boxes(img, 200); len(boxes) != 1 {
+		t.Errorf("the receipt is %d regions: %v", len(boxes), boxes)
+	}
+}

modules/brother/cmd/brother/declared_test.go

@@ -0,0 +1,95 @@
+package main
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"sort"
+	"strconv"
+	"testing"
+)
+
+// 1528: a tool reads only arguments its input schema declares; the console refuses an undeclared
+// one before it reaches the tool (scanner.scan read apart, which its schema never named).
+func TestEveryArgumentAToolReadsIsDeclared(t *testing.T) {
+	fs := token.NewFileSet()
+	f, err := parser.ParseFile(fs, "main.go", nil, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	checked := 0
+	ast.Inspect(f, func(n ast.Node) bool {
+		lit, ok := n.(*ast.CompositeLit)
+		if !ok {
+			return true
+		}
+		var name string
+		var input, run ast.Expr
+		for _, e := range lit.Elts {
+			kv, ok := e.(*ast.KeyValueExpr)
+			if !ok {
+				continue
+			}
+			switch k, _ := kv.Key.(*ast.Ident); {
+			case k == nil:
+			case k.Name == "Name":
+				if b, ok := kv.Value.(*ast.BasicLit); ok {
+					name, _ = strconv.Unquote(b.Value)
+				}
+			case k.Name == "Input":
+				input = kv.Value
+			case k.Name == "Run":
+				run = kv.Value
+			}
+		}
+		if name == "" || input == nil || run == nil {
+			return true
+		}
+		declared := map[string]bool{}
+		ast.Inspect(input, func(m ast.Node) bool {
+			kv, ok := m.(*ast.KeyValueExpr)
+			if !ok {
+				return true
+			}
+			if k, ok := kv.Key.(*ast.BasicLit); ok && k.Value == `"properties"` {
+				if props, ok := kv.Value.(*ast.CompositeLit); ok {
+					for _, p := range props.Elts {
+						if pkv, ok := p.(*ast.KeyValueExpr); ok {
+							if b, ok := pkv.Key.(*ast.BasicLit); ok {
+								s, _ := strconv.Unquote(b.Value)
+								declared[s] = true
+							}
+						}
+					}
+				}
+				return false
+			}
+			return true
+		})
+		var missing []string
+		ast.Inspect(run, func(m ast.Node) bool {
+			ix, ok := m.(*ast.IndexExpr)
+			if !ok {
+				return true
+			}
+			if id, ok := ix.X.(*ast.Ident); ok && id.Name == "args" {
+				if b, ok := ix.Index.(*ast.BasicLit); ok && b.Kind == token.STRING {
+					s, _ := strconv.Unquote(b.Value)
+					if !declared[s] {
+						missing = append(missing, s)
+					}
+				}
+			}
+			return true
+		})
+		checked++
+		if len(missing) > 0 {
+			sort.Strings(missing)
+			t.Errorf("%s reads %v, which its input schema does not declare", name, missing)
+		}
+		return false
+	})
+	if checked < 5 {
+		t.Fatalf("checked %d tools; the test no longer finds the tool literals", checked)
+	}
+}

modules/brother/cmd/brother/device_boundary_test.go

@@ -0,0 +1,70 @@
+package main
+
+// The tools never open the admin password (novox/hq ADR 0436 §12, ADR 0467 clause 4): only the device process
+// reads it, as its own account, brother-device. The build seat runs every test under one account, so no
+// permission test can show the split; this is the file-level proxy mesh-mail's secret_boundary_test.go uses
+// instead: an AST check that the tools' files import no password-reading package and name no password file.
+
+import (
+	"go/parser"
+	"go/token"
+	"os"
+	"strings"
+	"testing"
+)
+
+const secretPackage = "brother/cmd/brother/internal/secret"
+
+// toolFiles are the files the tools' bundle runs (the scanner's, the printer.status's and the printer.settings'
+// ask), as opposed to the device process's: deviceproc.go, admin.go, pin.go and html.go.
+var toolFiles = []string{"main.go", "printer.go", "scan.go", "settings.go", "ipp.go", "escl.go", "file.go", "crop.go", "pdf.go", "parts.go", "certcheck.go"}
+
+// 1453: none of the tools' files imports the password-reading package or names the password's file.
+func TestTheToolsNeverOpenTheAdminPassword(t *testing.T) {
+	for _, file := range toolFiles {
+		fset := token.NewFileSet()
+		f, err := parser.ParseFile(fset, file, nil, parser.ImportsOnly)
+		if err != nil {
+			t.Fatalf("%s: %v", file, err)
+		}
+		for _, imp := range f.Imports {
+			if strings.Trim(imp.Path.Value, `"`) == secretPackage {
+				t.Errorf("%s imports %s, which only the device process may (ADR 0436 §12)", file, secretPackage)
+			}
+		}
+		src, err := os.ReadFile(file)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, bad := range []string{`Getenv("BROTHER_ADMIN_PASSWORD")`, `Getenv("BROTHER_STORE")`, "ReadStoreFacts", "NewS3", "StoreFacts"} {
+			if strings.Contains(string(src), bad) {
+				t.Errorf("%s names %s: the password's and the bucket key's files are the device process's alone (ADR 0468 clause 1)", file, bad)
+			}
+		}
+	}
+}
+
+// 1453: the device process does read it through the package, and the package is the one place a password file is
+// opened.
+func TestTheAdminProcessReadsThePasswordThroughThePackage(t *testing.T) {
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "deviceproc.go", nil, parser.ImportsOnly)
+	if err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	for _, imp := range f.Imports {
+		if strings.Trim(imp.Path.Value, `"`) == secretPackage {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("deviceproc.go does not import %s", secretPackage)
+	}
+	for _, file := range append(append([]string{}, toolFiles...), "admin.go", "deviceproc.go", "pin.go", "html.go", "objects.go", "capture.go") {
+		src, _ := os.ReadFile(file)
+		if strings.Contains(string(src), "os.ReadFile") && file != "settings.go" && file != "file.go" && file != "escl.go" && file != "objects.go" {
+			t.Errorf("%s reads a file: only settings.json (settings.go) and the scan folder's PDFs are read outside the secret package", file)
+		}
+	}
+}

modules/brother/cmd/brother/device_integration_test.go

@@ -0,0 +1,130 @@
+//go:build integration
+
+package main
+
+// The device process over a real bus (novox/hq ADR 0467 clause 4; the shape of mesh-mail's
+// sender_integration_test.go, ADR 0436 §7): a JetStream server of the test's own, the work-queue stream
+// device-asks and its consumer, the state bucket device-answers, and a fake printer. An ask published on the
+// stream is answered in the state under its id and acknowledged. Compiled by the merge gate's
+// `go vet -tags integration`; never run on this machine.
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/process"
+	"github.com/nats-io/nats-server/v2/server"
+	"github.com/nats-io/nats.go"
+	"github.com/nats-io/nats.go/jetstream"
+
+	"brother/cmd/brother/internal/secret"
+)
+
+// printerAskedSubject is the wire subject the controller composes for the stream's one event:
+// "mesh.stream." + module + ".event." + event (mesh-controller internal/broker/modstreams.go).
+const printerAskedSubject = "mesh.stream.brother.event." + EventAsked
+
+func newTestBus(t *testing.T) string {
+	t.Helper()
+	opts := &server.Options{Host: "127.0.0.1", Port: server.RANDOM_PORT, JetStream: true, StoreDir: t.TempDir(),
+		NoLog: true, NoSigs: true}
+	s, err := server.NewServer(opts)
+	if err != nil {
+		t.Fatalf("a bus for this test could not be made: %v", err)
+	}
+	go s.Start()
+	if !s.ReadyForConnections(30 * time.Second) {
+		s.Shutdown()
+		t.Fatal("a bus for this test did not come up within 30s")
+	}
+	t.Cleanup(func() { s.Shutdown(); s.WaitForShutdown() })
+	return s.ClientURL()
+}
+
+// 1453: an ask on device-asks is answered under its id in device-answers by the device process, over the
+// printer's pinned HTTPS and the login, and acknowledged; stopping it leaves nothing in hand.
+func TestTheAdminProcessAnswersAnAskOverARealBus(t *testing.T) {
+	url := newTestBus(t)
+	ctx := context.Background()
+	nc, err := nats.Connect(url)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer nc.Close()
+	js, err := jetstream.New(nc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: AsksStream, Subjects: []string{printerAskedSubject},
+		Retention: jetstream.WorkQueuePolicy, Discard: jetstream.DiscardNew, MaxAge: 24 * time.Hour, MaxBytes: 8 << 20}); err != nil {
+		t.Fatal(err)
+	}
+	account := process.Account{URL: url, Node: "g14", Module: "brother", User: "g14.brother." + DeviceProcessID, Password: "pw"}
+	if _, err := js.CreateConsumer(ctx, AsksStream, jetstream.ConsumerConfig{Durable: account.QueueConsumerName(),
+		AckPolicy: jetstream.AckExplicitPolicy, AckWait: 30 * time.Second, MaxDeliver: 3}); err != nil {
+		t.Fatal(err)
+	}
+	kv, err := js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: account.Module + "_" + AnswersState, TTL: 10 * time.Minute})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	f := newFakePrinter(t, "B1891", "pw")
+	dir := t.TempDir()
+	settings := filepath.Join(dir, "settings.json")
+	os.WriteFile(settings, []byte(`{"printer":"`+f.host()+`","printer-certificate":"`+f.print()+`"}`), 0o600)
+	pwFile := filepath.Join(dir, "admin-password.secret")
+	os.WriteFile(pwFile, []byte("pw\n"), 0o600)
+	w := &deviceWorker{
+		Settings: func() (Settings, error) { return LoadSettings(settings) },
+		Password: func() (string, error) { return secret.Read(pwFile) },
+		Now:      time.Now,
+	}
+	runCtx, cancel := context.WithCancel(ctx)
+	done := make(chan error, 1)
+	go func() { done <- runDevice(runCtx, account, w) }()
+
+	body, _ := json.Marshal(Ask{ID: "ask-1", Op: OpSettings, Page: "/general/other.html", At: time.Now()})
+	if _, err := js.Publish(ctx, printerAskedSubject, body, jetstream.WithMsgID("ask-1")); err != nil {
+		t.Fatal(err)
+	}
+	var answer string
+	for deadline := time.Now().Add(15 * time.Second); time.Now().Before(deadline); time.Sleep(50 * time.Millisecond) {
+		if e, err := kv.Get(ctx, "ask-1"); err == nil {
+			answer = string(e.Value())
+			break
+		}
+	}
+	if !strings.Contains(answer, "Synthetic settings") {
+		t.Fatalf("the answer under ask-1 is %q", answer)
+	}
+	if strings.Contains(answer, "shouldnotshow") {
+		t.Errorf("a password field's value is in the answer")
+	}
+	time.Sleep(500 * time.Millisecond)
+	cancel()
+	select {
+	case err := <-done:
+		if err == nil {
+			t.Fatal("runDevice returned nil, want ctx.Err() once its context was cancelled")
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("runDevice did not stop once its context was cancelled")
+	}
+	cons, err := js.Consumer(ctx, AsksStream, account.QueueConsumerName())
+	if err != nil {
+		t.Fatal(err)
+	}
+	info, err := cons.Info(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.NumPending != 0 || info.NumAckPending != 0 {
+		t.Errorf("the ask was not acknowledged: %d pending, %d awaiting an acknowledgement", info.NumPending, info.NumAckPending)
+	}
+}

modules/brother/cmd/brother/deviceproc.go

@@ -0,0 +1,740 @@
+package main
+
+// mesh brother device (novox/hq ADR 0467 clause 4, in the shape of ADR 0436 §7): the device process, a process
+// with a bus account of its own (brother-device), never a seat. It alone of the module's parts reads the admin
+// password and logs in to the printer's admin page; the tools queue an ask on the work-queue stream device-asks
+// and read its answer in the state device-answers. The admin password is never in an answer, an event or a log.
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/process"
+	"github.com/nats-io/nats.go/jetstream"
+
+	"brother/cmd/brother/internal/secret"
+)
+
+// Answers is the state the worker writes an answer in, once.
+type Answers interface {
+	Create(key string, value any) (uint64, error)
+}
+
+// action is what is done to the queued message.
+type action int
+
+const (
+	actionAck action = iota
+	actionRetry
+	actionTerm
+	// actionSettled says the message was acknowledged already, before the work began: what is not safe to do twice
+	// (a scan, a print) is acknowledged first, so a slow one is not delivered again after the bus's wait.
+	actionSettled
+)
+
+// pendingUpload is the parts of an upload that have come.
+type pendingUpload struct {
+	parts map[int][]byte
+	n     int
+	sha   string
+	at    time.Time
+}
+
+// pendingFor is how long an incomplete upload's parts are kept.
+const pendingFor = 15 * time.Minute
+
+// deviceWorker answers the asks: it alone talks to the device (the scanner, the printer's pages and IPP) and to
+// the bucket. Settings and the password are read at each ask, so a changed config value or a password given later
+// is the next ask's.
+type deviceWorker struct {
+	Settings func() (Settings, error)
+	Password func() (string, error)
+	Objects  func() (Objects, error)
+	// Emit says scan.added on the bus under a message id.
+	Emit    func(body map[string]any, id string) error
+	Answers Answers
+	Node    string
+	// Capture scans; nil is the device's own (a test puts a stand-in).
+	Capture func(ctx context.Context, req ScanRequest) ([]Capture, error)
+	// answerPart is the raw size of a document part in an answer; zero is AnswerPartSize (a test makes it larger).
+	answerPart int
+	Now        func() time.Time
+	Logf       func(format string, a ...any)
+
+	mu      sync.Mutex
+	pending map[string]*pendingUpload
+	// docs serialises the work on open documents.
+	docs sync.Mutex
+}
+
+func (w *deviceWorker) logf(format string, a ...any) {
+	if w.Logf != nil {
+		w.Logf(format, a...)
+	}
+}
+
+// tooLargeCode is the bus's error code for a message over the maximum allowed (the state refuses a value so).
+const tooLargeCode = 10054
+
+// Handle answers one queued ask. An ask that cannot be read is terminated; an ask too old for anyone to wait for
+// is acknowledged and the device not touched; every other outcome, a failure included, is written as the answer
+// under the ask's id and the message acknowledged; an answer the state refuses as too large is
+// replaced by a small error answer and the message terminated; an answer that could not be written for another
+// reason (the store away, a timeout) is redelivered (the bus's limit ends that). early acknowledges the message; it is called before a scan or a print, which are not
+// done twice.
+func (w *deviceWorker) Handle(body []byte, early func()) (action, time.Duration) {
+	var ask Ask
+	if err := json.Unmarshal(body, &ask); err != nil || ask.ID == "" {
+		w.logf("[brother] device: a queued ask could not be read: %v", err)
+		return actionTerm, 0
+	}
+	if age := w.Now().Sub(ask.At); age > StaleAfter {
+		w.logf("[brother] device: ask %s is %s old; nobody waits for it, the device is not touched", ask.ID, age.Round(time.Second))
+		return actionAck, 0
+	}
+	if !ask.Deadline.IsZero() && w.Now().After(ask.Deadline) {
+		// The asker has stopped waiting for this ask to be taken up: nothing is scanned or printed for it (issue
+		// 1539). The reason is its answer, for a late reader, and the message ends here.
+		w.logf("[brother] device: ask %s was taken up after its deadline %s; the device is not touched", ask.ID, ask.Deadline.Format(time.RFC3339))
+		if _, err := w.Answers.Create(ask.ID, map[string]any{"error": "the ask was taken up after its deadline (the device process was busy): nothing was done for it; ask again"}); err != nil && !errors.Is(err, stdio.ErrChanged) {
+			w.logf("[brother] device: the answer to %s could not be written: %v", ask.ID, err)
+		}
+		return actionTerm, 0
+	}
+	settled := false
+	if (ask.Op == OpScan || ask.Op == OpPrint) && early != nil {
+		early()
+		settled = true
+	}
+	// A scan of the feeder may run as long as FeederMaxBound (the scan itself ends sooner by FeederBound, which
+	// scales with its pages) and the PDF is then stored; every other ask is done in 5 minutes.
+	bound := 5 * time.Minute
+	if ask.Op == OpScan && ask.Source == "feeder" {
+		bound = FeederMaxBound + 5*time.Minute
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), bound)
+	defer cancel()
+	var answer map[string]any
+	if got, err := w.run(ctx, ask); err != nil {
+		answer = map[string]any{"error": err.Error()}
+	} else {
+		answer = got
+	}
+	if _, err := w.Answers.Create(ask.ID, answer); err != nil && !errors.Is(err, stdio.ErrChanged) {
+		w.logf("[brother] device: the answer to %s could not be written: %v", ask.ID, err)
+		var api *jetstream.APIError
+		if !errors.As(err, &api) || api.ErrorCode != tooLargeCode {
+			// The store is away, timed out or cut: the answer may be written next time (a scan is settled already).
+			if settled {
+				return actionSettled, 0
+			}
+			return actionRetry, 5 * time.Second
+		}
+		// The ask ends here: a refused value would be refused again.
+		// Say the failure as a small error answer, so the tool's wait ends with the reason (issue 1535).
+		msg := fmt.Sprintf("the answer to this ask could not be written in the state %s: %v", AnswersState, err)
+		if _, err2 := w.Answers.Create(ask.ID, map[string]any{"error": msg}); err2 != nil && !errors.Is(err2, stdio.ErrChanged) {
+			w.logf("[brother] device: the failure of %s could not be written either: %v", ask.ID, err2)
+		}
+		if settled {
+			return actionSettled, 0
+		}
+		return actionTerm, 0
+	}
+	if settled {
+		return actionSettled, 0
+	}
+	return actionAck, 0
+}
+
+// run is the operation an ask names.
+func (w *deviceWorker) run(ctx context.Context, ask Ask) (map[string]any, error) {
+	switch ask.Op {
+	case OpSettings:
+		return w.read(ctx, ask.Page, ask.Links, ask.Hidden)
+	case OpScan:
+		return w.scan(ctx, ask)
+	case OpDocument:
+		return w.document(ctx, ask)
+	case OpUpload:
+		return w.upload(ctx, ask)
+	case OpPrint:
+		return w.print(ctx, ask)
+	case OpOpen:
+		return w.openDocuments(ctx)
+	}
+	return nil, fmt.Errorf("the ask %s names an operation, %q, the device process does not do", ask.ID, ask.Op)
+}
+
+// scan scans the glass (cropped) or the feeder (whole sheets, one PDF of all pages), builds the PDF, keeps it in the bucket under its SHA-256 and says scan.added with
+// the object's key (ADR 0468 clause 2), in that order: nothing is said of a scan that is not kept, and nothing is
+// kept nor said when the scanner gives no page (1440/AC6). The answer is the event's body with key, size and the
+// number of parts.
+func (w *deviceWorker) scan(ctx context.Context, ask Ask) (map[string]any, error) {
+	req, err := ParseScan(ask.Source, ask.Duplex, ask.Apart)
+	if err != nil {
+		return nil, err
+	}
+	set, err := w.Settings()
+	if err != nil {
+		return nil, err
+	}
+	if set.Scanner == "" {
+		return nil, unsetError("scanner")
+	}
+	objects, err := w.Objects()
+	if err != nil {
+		return nil, err
+	}
+	svc := &Service{Settings: set, Node: w.Node, Now: w.Now}
+	if ask.Document != "" {
+		return w.scanDocument(ctx, ask, svc, objects)
+	}
+	capture := svc.Capture
+	if w.Capture != nil {
+		capture = w.Capture
+	}
+	caps, err := capture(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	return w.keep(ctx, objects, set, caps)
+}
+
+// keep stores each captured PDF in the bucket and says scan.added for it, in that order. One document is answered
+// as today: the event's body with key, size and the number of parts. Several (documents lying apart on the glass)
+// are answered as documents, a list of those, each filed on its own by the tool. A document that could not be kept
+// or announced is named in failed and does not hold back the others: what is announced is always filed.
+func (w *deviceWorker) keep(ctx context.Context, objects Objects, set Settings, caps []Capture) (map[string]any, error) {
+	if len(caps) == 0 {
+		return nil, fmt.Errorf("the scanner gave no document")
+	}
+	var docs []map[string]any
+	var failed []string
+	for i, c := range caps {
+		one, err := w.keepOne(ctx, objects, set, c)
+		if err != nil {
+			if len(caps) == 1 {
+				return nil, err
+			}
+			failed = append(failed, fmt.Sprintf("document %d: %v", i+1, err))
+			continue
+		}
+		docs = append(docs, one)
+	}
+	if len(docs) == 0 {
+		return nil, fmt.Errorf("no document could be kept: %s", strings.Join(failed, "; "))
+	}
+	if len(caps) == 1 {
+		return docs[0], nil
+	}
+	out := map[string]any{"documents": docs}
+	if len(failed) > 0 {
+		out["failed"] = failed
+	}
+	return out, nil
+}
+
+// keepOne keeps one captured PDF and announces it.
+func (w *deviceWorker) keepOne(ctx context.Context, objects Objects, set Settings, c Capture) (map[string]any, error) {
+	// A scan the tool could not take is not kept nor announced: an announced scan is always filed (issue 1539).
+	if most := MostAnswerParts * AnswerPartSize; len(c.PDF) > most {
+		return nil, fmt.Errorf("the scan's PDF is %d bytes, over the %d the tool can fetch (%d parts of %d): it is not kept; scan with a lower resolution or fewer sheets",
+			len(c.PDF), most, MostAnswerParts, AnswerPartSize)
+	}
+	body := c.Body(w.Node, set.ColorMode)
+	key := body["object"].(string)
+	if err := Store(ctx, objects, key, "application/pdf", c.PDF); err != nil {
+		return nil, err
+	}
+	if err := w.Emit(body, c.SHA256); err != nil {
+		return nil, fmt.Errorf("the scan is kept as %s, but %s could not be said on the bus: %w", key, EventAdded, err)
+	}
+	answer := map[string]any{"key": key, "size": len(c.PDF), "parts": answerPartCount(len(c.PDF))}
+	for k, v := range body {
+		answer[k] = v
+	}
+	return answer, nil
+}
+
+// document is one part of a scan kept in the bucket.
+func (w *deviceWorker) document(ctx context.Context, ask Ask) (map[string]any, error) {
+	if err := checkDocument(ask); err != nil {
+		return nil, err
+	}
+	objects, err := w.Objects()
+	if err != nil {
+		return nil, err
+	}
+	data, err := objects.Get(ctx, ask.Object)
+	if err != nil {
+		return nil, err
+	}
+	each := w.answerPart
+	if each <= 0 {
+		each = AnswerPartSize
+	}
+	part, n, err := cutPartOf(data, ask.Part, each)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"part": ask.Part, "parts": n, "size": len(data), "sha256": sha256Hex(data),
+		"data": base64.StdEncoding.EncodeToString(part)}, nil
+}
+
+// upload keeps a part, and once all have come joins them, checks the SHA-256 and the format and stores the document
+// as uploads/<upload>.<ext>. A wrong SHA-256 or a document that is neither PDF nor JPEG stores nothing, and the
+// parts are dropped; a part out of range is refused.
+func (w *deviceWorker) upload(ctx context.Context, ask Ask) (map[string]any, error) {
+	if err := checkUpload(ask); err != nil {
+		return nil, err
+	}
+	raw, _ := base64.StdEncoding.DecodeString(ask.Data)
+	w.mu.Lock()
+	if w.pending == nil {
+		w.pending = map[string]*pendingUpload{}
+	}
+	for id, p := range w.pending {
+		if w.Now().Sub(p.at) > pendingFor {
+			delete(w.pending, id)
+		}
+	}
+	p := w.pending[ask.Upload]
+	if p == nil {
+		p = &pendingUpload{parts: map[int][]byte{}, n: ask.Parts, sha: ask.SHA256}
+		w.pending[ask.Upload] = p
+	}
+	if p.n != ask.Parts || p.sha != ask.SHA256 {
+		w.mu.Unlock()
+		return nil, fmt.Errorf("upload %s was begun with %d parts and SHA-256 %s: its parts all say the same", ask.Upload, p.n, p.sha)
+	}
+	p.parts[ask.Part] = raw
+	p.at = w.Now()
+	if len(p.parts) < p.n {
+		got := len(p.parts)
+		w.mu.Unlock()
+		return map[string]any{"upload": ask.Upload, "complete": false, "received": got, "parts": ask.Parts}, nil
+	}
+	delete(w.pending, ask.Upload)
+	w.mu.Unlock()
+
+	ordered := make([][]byte, p.n)
+	for i := range ordered {
+		ordered[i] = p.parts[i+1]
+	}
+	doc, err := joinParts(ordered, p.sha)
+	if err != nil {
+		return nil, fmt.Errorf("upload %s: %w", ask.Upload, err)
+	}
+	format, ext, err := SniffFormat(doc)
+	if err != nil {
+		return nil, fmt.Errorf("upload %s: %w", ask.Upload, err)
+	}
+	objects, err := w.Objects()
+	if err != nil {
+		return nil, err
+	}
+	key := "uploads/" + ask.Upload + "." + ext
+	if err := objects.Put(ctx, key, format, doc); err != nil {
+		return nil, err
+	}
+	return map[string]any{"upload": ask.Upload, "complete": true, "object": key, "size": len(doc), "sha256": p.sha}, nil
+}
+
+// print fetches a scan or a completed upload from the bucket and sends it to the printer as an IPP Print-Job in
+// its own format, and answers the job's id and state. The printer's host is its IPP address; nothing is fetched
+// or sent before the ask is checked.
+func (w *deviceWorker) print(ctx context.Context, ask Ask) (map[string]any, error) {
+	if err := checkPrint(&ask); err != nil {
+		return nil, err
+	}
+	set, err := w.Settings()
+	if err != nil {
+		return nil, err
+	}
+	if set.Printer == "" {
+		return nil, unsetError("printer")
+	}
+	objects, err := w.Objects()
+	if err != nil {
+		return nil, err
+	}
+	key := ask.Object
+	if key == "" {
+		for _, ext := range []string{"pdf", "jpg"} {
+			k := "uploads/" + ask.Upload + "." + ext
+			if has, err := objects.Has(ctx, k); err != nil {
+				return nil, err
+			} else if has {
+				key = k
+				break
+			}
+		}
+		if key == "" {
+			return nil, fmt.Errorf("upload %s is not complete: no document is kept under it", ask.Upload)
+		}
+	}
+	doc, err := objects.Get(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+	format, _, err := SniffFormat(doc)
+	if err != nil {
+		return nil, err
+	}
+	res, err := PrintJob(ctx, set.Printer, PrintOptions{Format: format, Copies: ask.Copies, Sides: ask.Sides, Media: ask.Media, Name: "brother print"}, doc)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"job-id": res.JobID, "job-state": res.State, "job-state-code": res.StateCode,
+		"job-state-reasons": res.Reasons, "format": format, "copies": ask.Copies, "sides": ask.Sides, "media": ask.Media, "object": key}, nil
+}
+
+// read logs in, reads one page of the admin site and logs out. It is read-only: the login (and the logout) are
+// the only things it sends, and a password field's value is never in the answer. The printer is not contacted
+// before the settings and the password are known to be given (1453/AC4).
+func (w *deviceWorker) read(ctx context.Context, page string, links, hidden bool) (map[string]any, error) {
+	if page == "" {
+		page = DefaultPage
+	}
+	if !validPage(page) {
+		return nil, fmt.Errorf("page %q is not a page of the admin site: it starts with / and ends in .html", page)
+	}
+	set, err := w.Settings()
+	if err != nil {
+		return nil, err
+	}
+	if err := set.MissingPrinter(); err != nil {
+		return nil, err
+	}
+	pw, err := w.Password()
+	if err != nil {
+		return nil, err
+	}
+	a, err := NewAdmin(set.Printer, set.PrinterCertificate, pw)
+	if err != nil {
+		return nil, err
+	}
+	if err := a.Login(ctx); err != nil {
+		return nil, err
+	}
+	// Log out with a context of its own: the ask's may be what ended this.
+	lctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	body, at, err := a.Get(ctx, page)
+	if err != nil {
+		if home, hat, herr := a.Get(lctx, DefaultPage); herr == nil {
+			a.Logout(lctx, home, hat)
+		}
+		var nf *notFoundError
+		if errors.As(err, &nf) {
+			return nil, fmt.Errorf("the printer has no page %s", page)
+		}
+		return nil, fmt.Errorf("page %s cannot be read: %w", page, err)
+	}
+	logout := a.Logout(lctx, body, at)
+	p := ParsePage(body)
+	out := map[string]any{
+		"page":   page,
+		"title":  p.Title,
+		"forms":  nonNilForms(withoutHidden(p.Forms, hidden)),
+		"logout": logout,
+	}
+	if links {
+		out["links"] = nonNil(p.Links)
+	}
+	return out, nil
+}
+
+// withoutHidden leaves the hidden fields (the CSRF token and the like, noise to a reader) out of the forms
+// unless they are asked for.
+func withoutHidden(forms []Form, keep bool) []Form {
+	if keep {
+		return forms
+	}
+	out := make([]Form, 0, len(forms))
+	for _, f := range forms {
+		var fields []Field
+		for _, fl := range f.Fields {
+			if fl.Type != "hidden" {
+				fields = append(fields, fl)
+			}
+		}
+		if len(fields) == 0 && len(f.Fields) > 0 {
+			continue // a form of nothing but hidden fields (the logout form) has nothing to read
+		}
+		f.Fields = fields
+		out = append(out, f)
+	}
+	return out
+}
+
+func nonNil(l []Link) []Link {
+	if l == nil {
+		return []Link{}
+	}
+	return l
+}
+
+func nonNilForms(f []Form) []Form {
+	if f == nil {
+		return []Form{}
+	}
+	return f
+}
+
+// device is `brother device`: it reads its own bus account, connects, and consumes device-asks until stopped.
+// It refuses to start naming what is missing when the account cannot be read, and never logs a password.
+func device() int {
+	settings, passwordFile, brokerFile := os.Getenv("BROTHER_SETTINGS"), os.Getenv("BROTHER_ADMIN_PASSWORD"), os.Getenv("BROTHER_BROKER")
+	store := os.Getenv("BROTHER_STORE")
+	if brokerFile == "" {
+		fmt.Fprintln(os.Stderr, "[brother] device was started without BROTHER_BROKER, its bus account's file")
+		return 2
+	}
+	account, err := process.ReadAccount(brokerFile)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "[brother] device: %v\n", err)
+		return 1
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	w := &deviceWorker{
+		Settings: func() (Settings, error) { return LoadSettings(settings) },
+		Password: func() (string, error) { return secret.Read(passwordFile) },
+		Objects: func() (Objects, error) {
+			facts, err := ReadStoreFacts(store)
+			if err != nil {
+				return nil, err
+			}
+			return NewS3(facts), nil
+		},
+		Now:  time.Now,
+		Logf: func(f string, a ...any) { fmt.Fprintf(os.Stderr, f+"\n", a...) },
+	}
+	fmt.Fprintf(os.Stderr, "[brother] device is consuming %s as %s\n", AsksStream, account.User)
+	err = runDevice(ctx, account, w)
+	if err != nil && ctx.Err() == nil {
+		fmt.Fprintf(os.Stderr, "[brother] device stopped: %v\n", err)
+		return 1
+	}
+	return 0
+}
+
+// runDevice connects as the device process's own account and consumes device-asks until ctx ends, answering each
+// ask in the state device-answers on that connection and then settling the message as Handle says. Apart from
+// device so a test can drive it over a bus of its own.
+func runDevice(ctx context.Context, account process.Account, w *deviceWorker) error {
+	conn, err := process.Connect(account)
+	if err != nil {
+		return fmt.Errorf("the bus cannot be reached: %w", err)
+	}
+	defer conn.Close()
+	w.Answers = conn.State(AnswersState)
+	if w.Node == "" {
+		w.Node = account.Node
+	}
+	w.Emit = func(body map[string]any, id string) error {
+		return conn.Emit(EventAdded, body, stdio.EmitOptions{MessageID: id})
+	}
+	return conn.Consume(ctx, AsksStream, func(msg *process.Message) {
+		var settleErr error
+		act, delay := w.Handle(msg.Body, func() { settleErr = msg.Ack() })
+		if settleErr != nil {
+			w.logf("[brother] device: acknowledging %s early: %v", msg.Subject, settleErr)
+		}
+		var aerr error
+		switch act {
+		case actionAck:
+			aerr = msg.Ack()
+		case actionRetry:
+			aerr = msg.NakWithDelay(delay)
+		case actionTerm:
+			aerr = msg.Term()
+		}
+		if aerr != nil {
+			w.logf("[brother] device: settling %s: %v", msg.Subject, aerr)
+		}
+	})
+}
+
+// An open document (issue 1538) is kept in the bucket, not in memory, so that a restart of the device process
+// loses none of its pages: each page's JPEG under pending/<id>/<n>.jpg and a manifest, pending/<id>/manifest.json,
+// that says how many pages there are and, once it is closed, the key of its PDF. The pages are not deleted when it
+// is closed (the bucket has no delete); they are the bucket's to age out.
+const mostDocumentPages = 100
+
+type docPage struct {
+	Key     string `json:"key"`
+	DPI     int    `json:"dpi"`
+	Width   int    `json:"width"`
+	Height  int    `json:"height"`
+	Cropped bool   `json:"cropped"`
+}
+
+type docManifest struct {
+	Started  time.Time `json:"started"`
+	Updated  time.Time `json:"updated"` // the last page's time
+	Pages    []docPage `json:"pages"`
+	Finished string    `json:"finished,omitempty"` // the closed document's object key
+}
+
+func manifestKey(id string) string { return "pending/" + id + "/manifest.json" }
+
+func loadManifest(ctx context.Context, o Objects, id string) (*docManifest, error) {
+	has, err := o.Has(ctx, manifestKey(id))
+	if err != nil {
+		return nil, err
+	}
+	if !has {
+		return nil, fmt.Errorf("no document %s is open: its id is wrong, or it was closed", id)
+	}
+	raw, err := o.Get(ctx, manifestKey(id))
+	if err != nil {
+		return nil, err
+	}
+	var m docManifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil, fmt.Errorf("document %s: its manifest cannot be read: %w", id, err)
+	}
+	if m.Finished != "" {
+		return nil, fmt.Errorf("document %s is closed already, as %s", id, m.Finished)
+	}
+	return &m, nil
+}
+
+func saveManifest(ctx context.Context, o Objects, id string, m *docManifest) error {
+	raw, _ := json.Marshal(m)
+	return o.Put(ctx, manifestKey(id), "application/json", raw)
+}
+
+// scanDocument adds a glass page to an open document (document start opens one, with the ask's id as its id), or
+// with finish closes the document into one multi-page PDF, kept and announced once like any scan.
+func (w *deviceWorker) scanDocument(ctx context.Context, ask Ask, svc *Service, objects Objects) (map[string]any, error) {
+	if ask.Source == "feeder" || ask.Duplex {
+		return nil, fmt.Errorf("a document of several pages is scanned from the glass, page by page; the feeder takes the whole stack in one scan")
+	}
+	id := ask.Document
+	if id == "start" {
+		if ask.Finish {
+			return nil, fmt.Errorf("finish closes an open document: name its id, not start")
+		}
+		id = ask.ID
+	}
+	if !uploadPattern.MatchString(id) {
+		return nil, fmt.Errorf("document %q is not an id: letters, digits, - and _, at most 64", id)
+	}
+	w.docs.Lock()
+	defer w.docs.Unlock()
+	var m *docManifest
+	if ask.Document == "start" {
+		m = &docManifest{Started: w.Now().UTC(), Updated: w.Now().UTC()}
+	} else {
+		var err error
+		if m, err = loadManifest(ctx, objects, id); err != nil {
+			return nil, err
+		}
+	}
+	if ask.Finish {
+		return w.finishDocument(ctx, id, m, svc, objects)
+	}
+	if len(m.Pages) >= mostDocumentPages {
+		return nil, fmt.Errorf("document %s has %d pages, the most one takes: close it", id, len(m.Pages))
+	}
+	page, err := svc.GlassPage(ctx)
+	if err != nil {
+		return nil, err
+	}
+	key := fmt.Sprintf("pending/%s/%03d.jpg", id, len(m.Pages)+1)
+	if err := objects.Put(ctx, key, "image/jpeg", page.JPEG); err != nil {
+		return nil, err
+	}
+	m.Updated = w.Now().UTC()
+	m.Pages = append(m.Pages, docPage{Key: key, DPI: page.DPI, Width: page.Width, Height: page.Height, Cropped: page.Cropped})
+	if err := saveManifest(ctx, objects, id, m); err != nil {
+		return nil, err
+	}
+	return map[string]any{"document": id, "pages": len(m.Pages), "state": "open",
+		"next": "scanner.scan {document: \"" + id + "\"} adds a page; scanner.scan {document: \"" + id + "\", finish: true} closes it into one PDF"}, nil
+}
+
+// finishDocument builds the open document's pages into one PDF and keeps and announces it.
+func (w *deviceWorker) finishDocument(ctx context.Context, id string, m *docManifest, svc *Service, objects Objects) (map[string]any, error) {
+	if len(m.Pages) == 0 {
+		return nil, fmt.Errorf("document %s has no page", id)
+	}
+	pages := make([]PDFPage, len(m.Pages))
+	for i, p := range m.Pages {
+		jpg, err := objects.Get(ctx, p.Key)
+		if err != nil {
+			return nil, fmt.Errorf("document %s: page %d is not kept: %w", id, i+1, err)
+		}
+		pages[i] = PDFPage{JPEG: jpg, DPI: p.DPI}
+	}
+	first := m.Pages[0]
+	c, err := captureOf(pages, Cropped{Width: first.Width, Height: first.Height, Cropped: first.Cropped}, first.DPI, w.Now())
+	if err != nil {
+		return nil, err
+	}
+	set, err := w.Settings()
+	if err != nil {
+		return nil, err
+	}
+	answer, err := w.keepOne(ctx, objects, set, c)
+	if err != nil {
+		return nil, err
+	}
+	m.Finished = answer["key"].(string)
+	if err := saveManifest(ctx, objects, id, m); err != nil {
+		return nil, fmt.Errorf("document %s is kept as %s, but could not be marked closed: %w", id, m.Finished, err)
+	}
+	// The pages are not needed any more: delete them. A bucket that refuses leaves them, and the answer says so.
+	for _, p := range m.Pages {
+		if err := objects.Delete(ctx, p.Key); err != nil {
+			answer["pending-kept"] = fmt.Sprintf("the pages of document %s could not be deleted from the bucket and stay under pending/%s/: %v", id, id, err)
+			break
+		}
+	}
+	return answer, nil
+}
+
+// openDocuments lists the documents of several pages that are open in the bucket, with the time of each one's last
+// page, so that the tool can arm their expiry again after it was restarted.
+func (w *deviceWorker) openDocuments(ctx context.Context) (map[string]any, error) {
+	objects, err := w.Objects()
+	if err != nil {
+		return nil, err
+	}
+	keys, err := objects.List(ctx, "pending/")
+	if err != nil {
+		return nil, err
+	}
+	open := []map[string]any{}
+	for _, k := range keys {
+		rest, ok := strings.CutPrefix(k, "pending/")
+		id, name, _ := strings.Cut(rest, "/")
+		if !ok || name != "manifest.json" || !uploadPattern.MatchString(id) {
+			continue
+		}
+		m, err := loadManifest(ctx, objects, id)
+		if err != nil {
+			continue // closed, or unreadable: not open
+		}
+		at := m.Updated
+		if at.IsZero() {
+			at = m.Started
+		}
+		open = append(open, map[string]any{"id": id, "pages": len(m.Pages), "updated": at.UTC().Format(time.RFC3339)})
+	}
+	return map[string]any{"open": open}, nil
+}

modules/brother/cmd/brother/documents_test.go

@@ -0,0 +1,629 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// pdfOf is a document that is a PDF to the sniff and size bytes long, its bytes varying so that a part out of
+// place changes the join.
+func pdfOf(size int) []byte {
+	b := make([]byte, size)
+	copy(b, "%PDF-1.4\n")
+	for i := 9; i < size; i++ {
+		b[i] = byte(i*7 + i/251)
+	}
+	return b
+}
+
+// 1453/AC10: a document is cut into parts of at most PartSize, under the limit, and the parts joined in
+// order are the document, with the SHA-256 checked; a wrong SHA-256 or a part missing is refused; a part out of
+// range is refused naming the range.
+func TestADocumentIsCutIntoPartsAndJoinedWithItsSha256Checked(t *testing.T) {
+	doc := pdfOf(2*AnswerPartSize + 1234)
+	n := answerPartCount(len(doc))
+	if n != 3 {
+		t.Fatalf("%d parts, want 3", n)
+	}
+	var parts [][]byte
+	for i := 1; i <= n; i++ {
+		p, total, err := cutPart(doc, i)
+		if err != nil || total != n {
+			t.Fatalf("part %d: %v (of %d)", i, err, total)
+		}
+		if len(p) > AnswerPartSize {
+			t.Errorf("part %d is %d bytes, over %d", i, len(p), AnswerPartSize)
+		}
+		parts = append(parts, p)
+	}
+	got, err := joinParts(parts, sha256Hex(doc))
+	if err != nil || !bytes.Equal(got, doc) {
+		t.Fatalf("the join is not the document: %v", err)
+	}
+	if _, err := joinParts(parts, sha256Hex([]byte("other"))); err == nil || !strings.Contains(err.Error(), sha256Hex(doc)) {
+		t.Errorf("a wrong SHA-256 was accepted or the error does not name the joined one: %v", err)
+	}
+	if _, err := joinParts(parts[:2], sha256Hex(doc)); err == nil {
+		t.Errorf("a join with a part missing passed its SHA-256")
+	}
+	for _, bad := range []int{0, -1, n + 1} {
+		if _, _, err := cutPart(doc, bad); err == nil || !strings.Contains(err.Error(), "out of range") {
+			t.Errorf("part %d: error = %v", bad, err)
+		}
+	}
+	if partCount(0) != 1 {
+		t.Errorf("an empty document has one part")
+	}
+}
+
+// 1453/AC10: scanner.document gives each part of a kept scan with the part count, the size and the SHA-256, each
+// answer within the bus's 1 MiB; the parts joined are the scan. A part out of range, or a key that is no scan's, is
+// refused, the first before anything is queued.
+func TestScannerDocumentGivesEachPartOfAKeptScan(t *testing.T) {
+	r := newRig(t, `{}`, "pw")
+	doc := pdfOf(AnswerPartSize + 5000)
+	key := sha256Hex(doc) + ".pdf"
+	r.objects.Put(t.Context(), key, "application/pdf", doc)
+	var joined []byte
+	for i := 1; i <= 2; i++ {
+		got, err := r.call(t, "scanner.document", map[string]any{"object": key, "part": float64(i)})
+		if err != nil {
+			t.Fatalf("part %d: %v", i, err)
+		}
+		m := got.(map[string]any)
+		if m["parts"] != float64(2) || m["size"] != float64(len(doc)) || m["sha256"] != sha256Hex(doc) || m["part"] != float64(i) {
+			t.Errorf("part %d answer = %v", i, m)
+		}
+		raw, err := base64.StdEncoding.DecodeString(m["data"].(string))
+		if err != nil {
+			t.Fatal(err)
+		}
+		joined = append(joined, raw...)
+	}
+	if !bytes.Equal(joined, doc) {
+		t.Errorf("the parts fetched are not the scan")
+	}
+	before := r.bus.asks()
+	if _, err := r.call(t, "scanner.document", map[string]any{"object": key, "part": float64(0)}); err == nil {
+		t.Errorf("part 0 was asked for")
+	}
+	if r.bus.asks() != before {
+		t.Errorf("an ask was queued for a part the tool could refuse")
+	}
+	if _, err := r.call(t, "scanner.document", map[string]any{"object": key, "part": float64(3)}); err == nil || !strings.Contains(err.Error(), "out of range") {
+		t.Errorf("part 3: error = %v", err)
+	}
+	for _, k := range []string{"../etc/passwd", "uploads/x.pdf", strings.ToUpper(key)} {
+		if _, err := r.call(t, "scanner.document", map[string]any{"object": k, "part": float64(1)}); err == nil || !strings.Contains(err.Error(), "not a scan's key") {
+			t.Errorf("object %q: error = %v", k, err)
+		}
+	}
+	if _, err := r.call(t, "scanner.document", map[string]any{"object": sha256Hex([]byte("none")) + ".pdf", "part": float64(1)}); err == nil {
+		t.Errorf("a scan that is not kept was given")
+	}
+}
+
+// 1453/AC10: a scan of more than one part is fetched whole by scanner.scan, joined, checked and filed.
+func TestScanNowFetchesAScanOfSeveralParts(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{Crop: false})
+	// Everything a scan is made of but its size is the real one; the stored object is what the parts carry, so a
+	// bigger object stands for a bigger scan: replace what the device keeps with a three-part document.
+	big := pdfOf(2*AnswerPartSize + 99)
+	bigKey := sha256Hex(big) + ".pdf"
+	r.objects.Put(t.Context(), bigKey, "application/pdf", big)
+	got := make([][]byte, 0, 3)
+	for i := 1; i <= 3; i++ {
+		p, err := r.worker.document(t.Context(), Ask{Op: OpDocument, Object: bigKey, Part: i})
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, _ := base64.StdEncoding.DecodeString(p["data"].(string))
+		got = append(got, raw)
+	}
+	if joined, err := joinParts(got, sha256Hex(big)); err != nil || !bytes.Equal(joined, big) {
+		t.Fatalf("three parts do not join: %v", err)
+	}
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if body["path"] == nil {
+		t.Errorf("no path: %v", body)
+	}
+}
+
+func upload(t *testing.T, r *printerRig, id string, doc []byte, sha string, part, parts int, piece []byte) (any, error) {
+	t.Helper()
+	return r.call(t, "printer.upload", map[string]any{"upload": id, "part": float64(part), "parts": float64(parts), "sha256": sha,
+		"data": base64.StdEncoding.EncodeToString(piece)})
+}
+
+// 1453/AC11: an upload in parts, in any order, is stored as uploads/<id>.pdf once all have come and the joined
+// SHA-256 matches; until then it says how many came and stores nothing.
+func TestAnUploadIsStoredOnceAllItsPartsCameAndTheSha256Matches(t *testing.T) {
+	r := newRig(t, `{}`, "pw")
+	doc := pdfOf(PartSize + 700)
+	sum := sha256Hex(doc)
+	p1, _, _ := cutPartOf(doc, 1, PartSize)
+	p2, _, _ := cutPartOf(doc, 2, PartSize)
+	got, err := upload(t, r, "up-1", doc, sum, 2, 2, p2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if m := got.(map[string]any); m["complete"] != false || m["received"] != float64(1) {
+		t.Errorf("after one part: %v", m)
+	}
+	if len(r.objects.keys()) != 0 {
+		t.Errorf("a document was stored before its parts all came: %v", r.objects.keys())
+	}
+	got, err = upload(t, r, "up-1", doc, sum, 1, 2, p1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := got.(map[string]any)
+	if m["complete"] != true || m["object"] != "uploads/up-1.pdf" || m["sha256"] != sum || m["size"] != float64(len(doc)) {
+		t.Errorf("after the last part: %v", m)
+	}
+	if kept, err := r.objects.Get(t.Context(), "uploads/up-1.pdf"); err != nil || !bytes.Equal(kept, doc) {
+		t.Errorf("the stored document is not the upload (%v)", err)
+	}
+	// A JPEG is stored with its own extension.
+	jpg := append([]byte{0xFF, 0xD8, 0xFF, 0xE0}, bytes.Repeat([]byte{7}, 100)...)
+	if _, err := upload(t, r, "pic", jpg, sha256Hex(jpg), 1, 1, jpg); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := r.objects.Get(t.Context(), "uploads/pic.jpg"); err != nil {
+		t.Errorf("the JPEG is not stored as uploads/pic.jpg: %v", err)
+	}
+}
+
+// 1453/AC11: a wrong SHA-256 on the joined document stores nothing and is said; a document that is neither PDF nor
+// JPEG stores nothing; a part out of range, a part larger than the limit, a part that is not base64 and parts that
+// disagree are refused; the upload can then be sent again whole.
+func TestAnUploadWithAWrongSha256OrAnOutOfRangePartStoresNothing(t *testing.T) {
+	r := newRig(t, `{}`, "pw")
+	doc := pdfOf(300)
+	wrong := sha256Hex([]byte("not it"))
+	if _, err := upload(t, r, "bad", doc, wrong, 1, 1, doc); err == nil || !strings.Contains(err.Error(), "refused") || !strings.Contains(err.Error(), sha256Hex(doc)) {
+		t.Errorf("a wrong SHA-256: error = %v", err)
+	}
+	if len(r.objects.keys()) != 0 || r.objects.puts != 0 {
+		t.Errorf("a document with a wrong SHA-256 was stored: %v", r.objects.keys())
+	}
+	text := []byte("plain text, no PDF")
+	if _, err := upload(t, r, "txt", text, sha256Hex(text), 1, 1, text); err == nil || !strings.Contains(err.Error(), "neither a PDF nor a JPEG") {
+		t.Errorf("a text upload: error = %v", err)
+	}
+	for _, c := range []struct{ part, parts int }{{0, 1}, {2, 1}, {1, 0}, {1, MostParts + 1}} {
+		if _, err := upload(t, r, "range", doc, sha256Hex(doc), c.part, c.parts, doc); err == nil {
+			t.Errorf("part %d of %d was taken", c.part, c.parts)
+		}
+	}
+	if _, err := upload(t, r, "range", doc, sha256Hex(doc), 2, 1, doc); err == nil || !strings.Contains(err.Error(), "out of range") {
+		t.Errorf("part 2 of 1: error = %v", err)
+	}
+	if _, err := r.call(t, "printer.upload", map[string]any{"upload": "x", "part": float64(1), "parts": float64(1), "sha256": sha256Hex(doc), "data": "!!"}); err == nil {
+		t.Errorf("a part that is not base64 was taken")
+	}
+	if _, err := upload(t, r, "big", doc, sha256Hex(doc), 1, 1, make([]byte, MaxPart+1)); err == nil || !strings.Contains(err.Error(), "at most") {
+		t.Errorf("a part over the limit: error = %v", err)
+	}
+	if r.bus.asks() != 2 {
+		// Only the two uploads that were complete in form reached the device process; every refusal above them
+		// was the tool's.
+		t.Errorf("%d asks queued, want the 2 whose form was right", r.bus.asks())
+	}
+	// Parts that disagree about the whole.
+	p := pdfOf(PartSize + 10)
+	p1, _, _ := cutPartOf(p, 1, PartSize)
+	if _, err := upload(t, r, "mix", p, sha256Hex(p), 1, 2, p1); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := upload(t, r, "mix", p, sha256Hex(p), 2, 3, p1); err == nil || !strings.Contains(err.Error(), "all say the same") {
+		t.Errorf("parts that disagree: error = %v", err)
+	}
+	if len(r.objects.keys()) != 0 {
+		t.Errorf("objects stored: %v", r.objects.keys())
+	}
+}
+
+// 1453/AC11: an incomplete upload's parts are dropped after fifteen minutes.
+func TestAnIncompleteUploadIsDroppedAfterAWhile(t *testing.T) {
+	r := newRig(t, `{}`, "pw")
+	doc := pdfOf(PartSize + 10)
+	p1, _, _ := cutPartOf(doc, 1, PartSize)
+	p2, _, _ := cutPartOf(doc, 2, PartSize)
+	now := fixedNow
+	r.worker.Now = func() time.Time { return now }
+	if _, err := upload(t, r, "late", doc, sha256Hex(doc), 1, 2, p1); err != nil {
+		t.Fatal(err)
+	}
+	now = now.Add(pendingFor + time.Minute)
+	// Asked of the worker directly: the tool's own clock is the fixed one, and an ask this old would be stale.
+	got, err := r.worker.upload(t.Context(), Ask{Op: OpUpload, Upload: "late", Part: 2, Parts: 2, SHA256: sha256Hex(doc),
+		Data: base64.StdEncoding.EncodeToString(p2)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got["complete"] != false {
+		t.Errorf("the dropped part was still there: %v", got)
+	}
+}
+
+// ippFake is a printer's IPP port: it records the request and answers a Print-Job answer with a job id and state.
+type ippFake struct {
+	url    string
+	body   []byte
+	status int
+}
+
+func newIPPFake(t *testing.T, jobID, jobState int) *ippFake {
+	t.Helper()
+	f := &ippFake{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.body, _ = io.ReadAll(r.Body)
+		ans := []byte{0x02, 0x00, byte(f.status >> 8), byte(f.status), 0, 0, 0, 1, ippOperation}
+		ans = appendAttr(ans, ippCharset, "attributes-charset", "utf-8")
+		ans = append(ans, ippJob)
+		ans = appendAttr(ans, ippInteger, "job-id", string(binary.BigEndian.AppendUint32(nil, uint32(jobID))))
+		ans = appendAttr(ans, ippEnum, "job-state", string(binary.BigEndian.AppendUint32(nil, uint32(jobState))))
+		ans = appendAttr(ans, ippKeyword, "job-state-reasons", "none")
+		ans = append(ans, ippEnd)
+		w.Header().Set("Content-Type", "application/ipp")
+		w.Write(ans)
+	}))
+	t.Cleanup(srv.Close)
+	f.url = srv.URL
+	old := ippURL
+	ippURL = func(string) string { return srv.URL }
+	t.Cleanup(func() { ippURL = old })
+	return f
+}
+
+// request splits what the fake was sent into its attributes and its document.
+func (f *ippFake) request(t *testing.T) (IPPAnswer, []byte) {
+	t.Helper()
+	a, off, err := decodeIPP(f.body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return a, f.body[off:]
+}
+
+// 1453/AC12: printer.print sends a kept scan to the printer as an IPP Print-Job (operation 0x0002): the document
+// bytes after the attributes, document-format by sniffing, copies, sides and media as asked, to the printer's own
+// IPP address; the answer is the job's id and state.
+func TestPrinterPrintSendsAPrintJobAndAnswersTheJob(t *testing.T) {
+	fake := newIPPFake(t, 77, 5)
+	r := newRig(t, `{"printer":"192.0.2.10"}`, "pw")
+	doc := pdfOf(5000)
+	key := sha256Hex(doc) + ".pdf"
+	r.objects.Put(t.Context(), key, "application/pdf", doc)
+	got, err := r.call(t, "printer.print", map[string]any{"object": key, "copies": float64(2), "sides": "two-sided-long-edge", "media": "na_letter_8.5x11in"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := got.(map[string]any)
+	if m["job-id"] != float64(77) || m["job-state"] != "processing" || m["format"] != "application/pdf" {
+		t.Errorf("answer = %v", m)
+	}
+	if binary.BigEndian.Uint16(fake.body[2:4]) != 0x0002 {
+		t.Errorf("operation = 0x%04x, want Print-Job 0x0002", binary.BigEndian.Uint16(fake.body[2:4]))
+	}
+	attrs, sent := fake.request(t)
+	if !bytes.Equal(sent, doc) {
+		t.Errorf("the document sent is not the kept one (%d bytes, want %d)", len(sent), len(doc))
+	}
+	text := func(n string) string { return strings.Join(attrs.texts(n), ",") }
+	if text("document-format") != "application/pdf" || text("sides") != "two-sided-long-edge" || text("media") != "na_letter_8.5x11in" ||
+		text("printer-uri") != "ipp://192.0.2.10/ipp/port1" {
+		t.Errorf("attributes = %v", attrs.Attributes)
+	}
+	if c := attrs.Attributes["copies"]; len(c) != 1 || c[0].Integer != 2 {
+		t.Errorf("copies = %v", c)
+	}
+}
+
+// 1453/AC12: the defaults are one copy, one-sided, A4; a JPEG is sent as image/jpeg; an upload is printed by its id.
+func TestPrinterPrintDefaultsAndFormatsAndUploads(t *testing.T) {
+	fake := newIPPFake(t, 8, 3)
+	r := newRig(t, `{"printer":"192.0.2.10"}`, "pw")
+	jpg := append([]byte{0xFF, 0xD8, 0xFF, 0xE0}, bytes.Repeat([]byte{9}, 200)...)
+	if _, err := upload(t, r, "photo", jpg, sha256Hex(jpg), 1, 1, jpg); err != nil {
+		t.Fatal(err)
+	}
+	got, err := r.call(t, "printer.print", map[string]any{"upload": "photo"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.(map[string]any)["job-state"] != "pending" {
+		t.Errorf("answer = %v", got)
+	}
+	attrs, sent := fake.request(t)
+	if !bytes.Equal(sent, jpg) || strings.Join(attrs.texts("document-format"), "") != "image/jpeg" ||
+		strings.Join(attrs.texts("sides"), "") != "one-sided" || strings.Join(attrs.texts("media"), "") != DefaultMedia || attrs.Attributes["copies"][0].Integer != 1 {
+		t.Errorf("attributes = %v, %d bytes sent", attrs.Attributes, len(sent))
+	}
+	if _, err := r.call(t, "printer.print", map[string]any{"upload": "never-uploaded"}); err == nil || !strings.Contains(err.Error(), "not complete") {
+		t.Errorf("an upload never made: error = %v", err)
+	}
+}
+
+// 1453/AC12: a print that is not well formed is refused before anything is queued; the printer's refusal is an
+// error naming its IPP status; a printer not set is said by name.
+func TestPrinterPrintRefusesWhatIsNotWellFormed(t *testing.T) {
+	fake := newIPPFake(t, 1, 3)
+	r := newRig(t, `{"printer":"192.0.2.10"}`, "pw")
+	key := sha256Hex([]byte("x")) + ".pdf"
+	for name, args := range map[string]map[string]any{
+		"neither":      {},
+		"both":         {"object": key, "upload": "u"},
+		"copies 0":     {"object": key, "copies": float64(-1)},
+		"copies 100":   {"object": key, "copies": float64(100)},
+		"sides":        {"object": key, "sides": "sideways"},
+		"media":        {"object": key, "media": "A4 paper"},
+		"not a key":    {"object": "../x.pdf"},
+		"copies float": {"object": key, "copies": 1.5},
+	} {
+		if _, err := r.call(t, "printer.print", args); err == nil {
+			t.Errorf("%s: accepted", name)
+		}
+	}
+	if r.bus.asks() != 0 || fake.body != nil {
+		t.Errorf("%d asks queued, the printer was sent %d bytes", r.bus.asks(), len(fake.body))
+	}
+	doc := pdfOf(100)
+	dk := sha256Hex(doc) + ".pdf"
+	r.objects.Put(t.Context(), dk, "application/pdf", doc)
+	fake.status = 0x0400
+	if _, err := r.call(t, "printer.print", map[string]any{"object": dk}); err == nil || !strings.Contains(err.Error(), "0x0400") {
+		t.Errorf("a refused job: error = %v", err)
+	}
+	// A kept object that is not a document the printer takes is not sent.
+	fake.status, fake.body = 0, nil
+	r.objects.Put(t.Context(), key, "text/plain", []byte("hello"))
+	if _, err := r.call(t, "printer.print", map[string]any{"object": key}); err == nil || !strings.Contains(err.Error(), "neither a PDF nor a JPEG") || fake.body != nil {
+		t.Errorf("a text object: error = %v, sent %d bytes", err, len(fake.body))
+	}
+	un := newRig(t, `{}`, "pw")
+	if _, err := un.call(t, "printer.print", map[string]any{"object": key}); err == nil || !strings.Contains(err.Error(), "printer is not set") || un.bus.asks() != 0 {
+		t.Errorf("no printer: error = %v", err)
+	}
+}
+
+// The Print-Job request is the one RFC 8011 gives: header, operation attributes in order, the job's own, the
+// end-of-attributes tag, then the document.
+func TestThePrintJobRequestIsWellFormed(t *testing.T) {
+	doc := []byte("%PDF-1.4 hello")
+	b := EncodePrintJob("ipp://192.0.2.10/ipp/port1", PrintOptions{Format: "application/pdf", Copies: 3, Sides: "one-sided", Media: DefaultMedia, Name: "n"}, doc)
+	if !bytes.Equal(b[:8], []byte{2, 0, 0, 2, 0, 0, 0, 1}) || b[8] != ippOperation {
+		t.Errorf("header = %x", b[:9])
+	}
+	a, off, err := decodeIPP(b)
+	if err != nil || !bytes.Equal(b[off:], doc) {
+		t.Fatalf("decode: %v, document %q", err, b[off:])
+	}
+	if first := string(b[9:]); !strings.HasPrefix(first[3:], "attributes-charset") {
+		t.Errorf("the first attribute is not attributes-charset")
+	}
+	if len(a.Attributes["copies"]) != 1 || a.Attributes["copies"][0].Integer != 3 {
+		t.Errorf("copies = %v", a.Attributes["copies"])
+	}
+}
+
+// 1453: a scan and a print are acknowledged before the work (a slow one is not delivered again and done twice);
+// the other operations are acknowledged after it.
+func TestAScanAndAPrintAreAcknowledgedBeforeTheWork(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{Crop: true})
+	body, _ := json.Marshal(Ask{ID: "s1", Op: OpScan, At: fixedNow})
+	calls := 0
+	var postsAtAck int
+	act, _ := r.worker.Handle(body, func() { calls++; postsAtAck = f.posts })
+	if calls != 1 || postsAtAck != 0 || act != actionSettled || f.posts != 1 {
+		t.Errorf("early called %d times with %d scans begun; action %v; %d scans in all", calls, postsAtAck, act, f.posts)
+	}
+	body, _ = json.Marshal(Ask{ID: "s2", Op: OpSettings, Page: DefaultPage, At: fixedNow})
+	calls = 0
+	if act, _ := r.worker.Handle(body, func() { calls++ }); calls != 0 || act != actionAck {
+		t.Errorf("settings: early called %d times, action %v", calls, act)
+	}
+}
+
+// 1453/AC11: a part of 700 KiB is taken and one of a byte more is refused, by the module's own message naming
+// 700 KiB, before it is queued; the limit and the size the module cuts are one.
+func TestAPartOverSevenHundredKiBIsRefusedByTheModulesOwnMessage(t *testing.T) {
+	if MaxPart != PartSize || PartSize != 700<<10 {
+		t.Fatalf("MaxPart %d, PartSize %d: both are 700 KiB", MaxPart, PartSize)
+	}
+	r := newRig(t, `{}`, "pw")
+	big := make([]byte, 700<<10+1)
+	_, err := upload(t, r, "over", big, sha256Hex(big), 1, 1, big)
+	if err == nil || !strings.Contains(err.Error(), "700 KiB") {
+		t.Fatalf("a part of 700 KiB + 1 byte: error = %v, want the module's own message naming 700 KiB", err)
+	}
+	if r.bus.asks() != 0 {
+		t.Errorf("an oversized part was queued")
+	}
+	ok := pdfOf(700 << 10)
+	if _, err := upload(t, r, "exact", ok, sha256Hex(ok), 1, 1, ok); err != nil {
+		t.Errorf("a part of exactly 700 KiB: %v", err)
+	}
+}
+
+// 1535: a scan larger than the state's value limit (256 KiB) is filed whole, its SHA-256 equal, and the answer to
+// the scan itself is small: it carries the event's body and never the document. Every part answer fits the state.
+func TestAScanLargerThanTheStatesValueLimitIsFiledWholeAndItsAnswerIsSmall(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: false})
+	// The real capture is small; the worker keeps a stand-in of 3 parts' size under the key the scan names.
+	big := pdfOf(222388 + 2*AnswerPartSize)
+	if len(big) <= StateMaxValue {
+		t.Fatal("the stand-in is not larger than the state's value limit")
+	}
+	r.worker.Capture = func(ctx context.Context, req ScanRequest) ([]Capture, error) {
+		return []Capture{{PDF: big, SHA256: sha256Hex(big), Resolution: 300, At: fixedNow}}, nil
+	}
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	path, _ := body["path"].(string)
+	got, err := os.ReadFile(path)
+	if err != nil || sha256Hex(got) != sha256Hex(big) || filepath.Dir(path) != folder {
+		t.Fatalf("filed %s: %v, SHA-256 equal %v", path, err, err == nil && sha256Hex(got) == sha256Hex(big))
+	}
+	for id, raw := range r.answers.m {
+		if len(raw) > StateMaxValue {
+			t.Errorf("answer %s is %d bytes, over the state's %d", id, len(raw), StateMaxValue)
+		}
+	}
+	for _, a := range r.bus.published {
+		if a.Op == OpScan {
+			if raw := r.answers.get(a.ID); len(raw) > 4<<10 || bytes.Contains(raw, []byte(`"data"`)) {
+				t.Errorf("the scan's answer is %d bytes and may carry the document: %s", len(raw), raw)
+			}
+		}
+	}
+}
+
+// 1535: an answer the state refuses ends the ask: a small error answer says why, and the queued message is
+// terminated, never redelivered into the same failure; a scan's message, acknowledged early, stays settled.
+func TestARefusedAnswerEndsTheAskWithAnErrorAndNoRedelivery(t *testing.T) {
+	r := newRig(t, `{}`, "pw")
+	big := pdfOf(300 << 10)
+	key := sha256Hex(big) + ".pdf"
+	r.objects.Put(t.Context(), key, "application/pdf", big)
+	// A part answer of 700 KiB, as the old cut made it, is over the state's limit; the worker must not loop on it.
+	r.worker.answerPart = PartSize
+	ask, _ := json.Marshal(Ask{ID: "big1", Op: OpDocument, Object: key, Part: 1, At: fixedNow})
+	act, _ := r.worker.Handle(ask, nil)
+	if act != actionTerm {
+		t.Errorf("action = %v, want term", act)
+	}
+	raw := r.answers.get("big1")
+	if raw == nil || !bytes.Contains(raw, []byte(`"error"`)) || len(raw) > 4<<10 {
+		t.Errorf("no small error answer: %s", raw)
+	}
+}
+
+// 1535: only a refused value (error code 10054, message too large) ends the ask; a store that is away, a timeout
+// or a cut connection is redelivered, a document fetch being safe to repeat.
+func TestOnlyATooLargeAnswerEndsTheAskATransientFailureIsRetried(t *testing.T) {
+	r := newRig(t, `{}`, "pw")
+	big := pdfOf(300 << 10)
+	key := sha256Hex(big) + ".pdf"
+	r.objects.Put(t.Context(), key, "application/pdf", big)
+	ask, _ := json.Marshal(Ask{ID: "t1", Op: OpDocument, Object: key, Part: 1, At: fixedNow})
+	r.answers.fail = fmt.Errorf("nats: timeout")
+	if act, d := r.worker.Handle(ask, nil); act != actionRetry || d <= 0 {
+		t.Errorf("a timeout: action %v delay %v, want retry", act, d)
+	}
+	r.answers.fail = nil
+	r.worker.answerPart = PartSize
+	ask2, _ := json.Marshal(Ask{ID: "t2", Op: OpDocument, Object: key, Part: 1, At: fixedNow})
+	if act, _ := r.worker.Handle(ask2, nil); act != actionTerm {
+		t.Errorf("a too large answer: action %v, want term", act)
+	}
+}
+
+// home makes a home folder for the tool account and returns it.
+func home(t *testing.T) string {
+	t.Helper()
+	h := t.TempDir()
+	t.Setenv("HOME", h)
+	return h
+}
+
+// 1551: printer.print with a path reads the file, uploads it in parts and prints it in one call; a document of
+// several parts arrives whole, and the answer has the job's id and state.
+func TestPrinterPrintTakesAPathAndUploadsAndPrintsInOneCall(t *testing.T) {
+	fake := newIPPFake(t, 31, 5)
+	r := newRig(t, `{"printer":"192.0.2.10"}`, "pw")
+	doc := pdfOf(2*PartSize + 1234)
+	file := filepath.Join(home(t), "letter.bin") // the name says nothing: the bytes are read
+	if err := os.WriteFile(file, doc, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got, err := r.call(t, "printer.print", map[string]any{"path": file, "copies": float64(2)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := got.(map[string]any)
+	if m["job-id"] != float64(31) || m["job-state"] != "processing" || m["format"] != "application/pdf" || m["bytes"] != len(doc) {
+		t.Errorf("answer = %v", m)
+	}
+	attrs, sent := fake.request(t)
+	if !bytes.Equal(sent, doc) || attrs.Attributes["copies"][0].Integer != 2 {
+		t.Errorf("sent %d bytes (want %d), attributes %v", len(sent), len(doc), attrs.Attributes)
+	}
+	ops := r.bus.ops()
+	if len(ops) != 4 || ops[0] != OpUpload || ops[2] != OpUpload || ops[3] != OpPrint {
+		t.Errorf("asks = %v, want three upload parts and a print", ops)
+	}
+}
+
+// 1551: only a regular file under the tool account's home folder is read, after symbolic links are resolved; every
+// other path is refused in one fixed way that says nothing of whether it exists or how large it is; a file in the
+// home folder that is no PDF or JPEG by its bytes is refused by name of the type.
+func TestPrinterPrintReadsOnlyAFileUnderTheHomeFolder(t *testing.T) {
+	fake := newIPPFake(t, 1, 5)
+	r := newRig(t, `{"printer":"192.0.2.10"}`, "pw")
+	h := home(t)
+	outside := t.TempDir()
+	secret := filepath.Join(outside, "secret.pdf")
+	os.WriteFile(secret, pdfOf(3000), 0o600)
+	link := filepath.Join(h, "link.pdf")
+	os.Symlink(secret, link)
+	dirLink := filepath.Join(h, "dirlink")
+	os.Symlink(outside, dirLink)
+	os.Mkdir(filepath.Join(h, "folder"), 0o700)
+	for name, path := range map[string]string{
+		"outside home":           secret,
+		"link out of home":       link,
+		"folder link out":        filepath.Join(dirLink, "secret.pdf"),
+		"dot-dot out of home":    filepath.Join(h, "..", filepath.Base(outside), "secret.pdf"),
+		"missing in home":        filepath.Join(h, "none.pdf"),
+		"missing outside home":   filepath.Join(outside, "none.pdf"),
+		"folder":                 filepath.Join(h, "folder"),
+		"the home folder itself": h,
+		"relative":               "secret.pdf",
+		"proc":                   "/proc/self/environ",
+	} {
+		_, err := r.call(t, "printer.print", map[string]any{"path": path})
+		if err == nil || err.Error() != PathRefused {
+			t.Errorf("%s: error = %v, want exactly %q", name, err, PathRefused)
+		}
+	}
+	text := filepath.Join(h, "fake.pdf")
+	os.WriteFile(text, []byte("just text, named .pdf"), 0o600)
+	if _, err := r.call(t, "printer.print", map[string]any{"path": text}); err == nil || !strings.Contains(err.Error(), "neither a PDF nor a JPEG") {
+		t.Errorf("text in home: error = %v", err)
+	}
+	if _, err := r.call(t, "printer.print", map[string]any{"path": text, "object": sha256Hex([]byte("x")) + ".pdf"}); err == nil {
+		t.Error("path with object accepted")
+	}
+	if r.bus.asks() != 0 || fake.body != nil {
+		t.Errorf("%d asks queued, printer sent %d bytes", r.bus.asks(), len(fake.body))
+	}
+	// A symbolic link inside the home folder to a file inside it is fine.
+	inside := filepath.Join(h, "real.pdf")
+	os.WriteFile(inside, pdfOf(3000), 0o600)
+	os.Symlink(inside, filepath.Join(h, "ok.pdf"))
+	if _, err := r.call(t, "printer.print", map[string]any{"path": filepath.Join(h, "ok.pdf")}); err != nil {
+		t.Errorf("a link within home: %v", err)
+	}
+}

modules/brother/cmd/brother/escl.go

@@ -0,0 +1,454 @@
+package main
+
+import (
+	"context"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"sync"
+	"time"
+)
+
+// eSCL (the AirScan protocol) over HTTP: POST <base>/ScanJobs answers 201 and the job's Location, GET
+// <Location>/NextDocument answers the image, and a second NextDocument answers 404 once the job is done (that is what closes it; DELETE of the job does too).
+
+// maxImage bounds what a scanner may send: a 600 dpi A4 JPEG is a few tens of megabytes.
+const maxImage = 256 << 20
+
+// Client speaks eSCL to one scanner.
+type Client struct {
+	Base      string
+	HTTP      *http.Client
+	RetryWait time.Duration // the wait before the one retry of a busy scanner (default 4 s)
+	Logf      func(format string, a ...any)
+}
+
+// NewClient is a client for the eSCL base URL, with a timeout that outlasts a slow scan.
+func NewClient(base string) *Client {
+	return &Client{Base: strings.TrimRight(base, "/"), HTTP: &http.Client{Timeout: 3 * time.Minute}}
+}
+
+// Size is the largest scan region of one input, in the 300ths of an inch the region is asked in.
+type Size struct{ MaxWidth, MaxHeight int }
+
+// Capabilities are the largest scan regions of the platen and of the document feeder (simplex and duplex). A
+// scanner with no feeder has zero sizes for it.
+type Capabilities struct {
+	MaxWidth, MaxHeight  int // the platen
+	Feeder, FeederDuplex Size
+}
+
+type capabilitiesXML struct {
+	MaxWidth     int `xml:"Platen>PlatenInputCaps>MaxWidth"`
+	MaxHeight    int `xml:"Platen>PlatenInputCaps>MaxHeight"`
+	AdfWidth     int `xml:"Adf>AdfSimplexInputCaps>MaxWidth"`
+	AdfHeight    int `xml:"Adf>AdfSimplexInputCaps>MaxHeight"`
+	DuplexWidth  int `xml:"Adf>AdfDuplexInputCaps>MaxWidth"`
+	DuplexHeight int `xml:"Adf>AdfDuplexInputCaps>MaxHeight"`
+}
+
+// Status is what /ScannerStatus says.
+type Status struct {
+	State    string `xml:"State" json:"state"`
+	AdfState string `xml:"AdfState" json:"adf-state"`
+}
+
+func (c *Client) get(ctx context.Context, rawURL string) (*http.Response, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+	if err != nil {
+		return nil, err
+	}
+	return c.HTTP.Do(req)
+}
+
+func readBody(resp *http.Response, limit int64) ([]byte, error) {
+	defer resp.Body.Close()
+	return io.ReadAll(io.LimitReader(resp.Body, limit))
+}
+
+// Capabilities asks the scanner how large its glass is.
+func (c *Client) Capabilities(ctx context.Context) (Capabilities, error) {
+	resp, err := c.get(ctx, c.Base+"/ScannerCapabilities")
+	if err != nil {
+		return Capabilities{}, fmt.Errorf("the scanner does not answer: %w", err)
+	}
+	body, err := readBody(resp, 1<<20)
+	if err != nil {
+		return Capabilities{}, fmt.Errorf("the scanner's capabilities cannot be read: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return Capabilities{}, fmt.Errorf("the scanner refused its capabilities: %s", resp.Status)
+	}
+	return parseCapabilities(body)
+}
+
+func parseCapabilities(body []byte) (Capabilities, error) {
+	var x capabilitiesXML
+	if err := xml.Unmarshal(body, &x); err != nil {
+		return Capabilities{}, fmt.Errorf("the scanner's capabilities are not XML: %w", err)
+	}
+	if x.MaxWidth <= 0 || x.MaxHeight <= 0 {
+		return Capabilities{}, fmt.Errorf("the scanner's capabilities name no platen size")
+	}
+	return Capabilities{MaxWidth: x.MaxWidth, MaxHeight: x.MaxHeight,
+		Feeder: Size{x.AdfWidth, x.AdfHeight}, FeederDuplex: Size{x.DuplexWidth, x.DuplexHeight}}, nil
+}
+
+// Status asks what the scanner is doing.
+func (c *Client) Status(ctx context.Context) (Status, error) {
+	resp, err := c.get(ctx, c.Base+"/ScannerStatus")
+	if err != nil {
+		return Status{}, fmt.Errorf("the scanner does not answer: %w", err)
+	}
+	body, err := readBody(resp, 1<<20)
+	if err != nil {
+		return Status{}, fmt.Errorf("the scanner's status cannot be read: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return Status{}, fmt.Errorf("the scanner refused its status: %s", resp.Status)
+	}
+	var s Status
+	if err := xml.Unmarshal(body, &s); err != nil {
+		return Status{}, fmt.Errorf("the scanner's status is not XML: %w", err)
+	}
+	return s, nil
+}
+
+// colorModes maps the config's words to eSCL's.
+var colorModes = map[string]string{"color": "RGB24", "gray": "Grayscale8"}
+
+// ScanOptions is what one job asks: the resolution and colour mode of the configuration, and the input. Duplex is
+// for the feeder.
+type ScanOptions struct {
+	Resolution int
+	ColorMode  string
+	Feeder     bool
+	Duplex     bool
+	// Bound is how long a feeder job may have run when it has this many pages and is asked for the next; nil is
+	// FeederBound. The job is deleted and an error given when it has run longer.
+	Bound func(pages int) time.Duration
+}
+
+// FeederBound is how long a feeder job may run when it has this many pages (issue 1539): 20 seconds for each,
+// at least 3 minutes and at most 30. The scanner gives a duplex sheet about every 3.4 seconds, so this is generous
+// and only ends a job that is stuck.
+func FeederBound(pages int) time.Duration {
+	return min(max(time.Duration(pages)*20*time.Second, 3*time.Minute), FeederMaxBound)
+}
+
+// FeederMaxBound is the longest a feeder job may run.
+const FeederMaxBound = 30 * time.Minute
+
+// A4 in the 300ths of an inch the region is asked in; a region is cut to what the input can scan.
+const a4Width, a4Height = 2480, 3508
+
+// maxFeederPages bounds one feeder job: the feeder holds 50 sheets, which duplex is 100 pages. After them the
+// scanner has to answer 404.
+const maxFeederPages = 100
+
+// ScanSettings is the request body, on ONE line: the Brother ignores the whole body, and runs its default job (the
+// platen, 200 dpi), when there is a line break anywhere before the closing root tag (issue 1452). The region is A4
+// cut to the input's largest region.
+func ScanSettings(c Capabilities, o ScanOptions) (string, error) {
+	escl, ok := colorModes[o.ColorMode]
+	if !ok {
+		return "", fmt.Errorf("color-mode %q is not color or gray", o.ColorMode)
+	}
+	size, source := Size{c.MaxWidth, c.MaxHeight}, "Platen"
+	if o.Duplex && !o.Feeder {
+		return "", fmt.Errorf("duplex is for the feeder")
+	}
+	if o.Feeder {
+		source, size = "Feeder", c.Feeder
+		if o.Duplex {
+			size = c.FeederDuplex
+		}
+		if size.MaxWidth <= 0 || size.MaxHeight <= 0 {
+			return "", fmt.Errorf("the scanner names no document feeder%s", map[bool]string{true: " that scans both sides", false: ""}[o.Duplex])
+		}
+	}
+	duplex := ""
+	if o.Duplex {
+		duplex = "<scan:Duplex>true</scan:Duplex>"
+	}
+	return fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?><scan:ScanSettings xmlns:scan="http://schemas.hp.com/imaging/escl/2011/05/03" xmlns:pwg="http://www.pwg.org/schemas/2010/12/sm">`+
+		`<pwg:Version>2.0</pwg:Version><scan:Intent>Document</scan:Intent>`+
+		`<pwg:ScanRegions><pwg:ScanRegion><pwg:ContentRegionUnits>escl:ThreeHundredthsOfInches</pwg:ContentRegionUnits><pwg:XOffset>0</pwg:XOffset><pwg:YOffset>0</pwg:YOffset><pwg:Width>%d</pwg:Width><pwg:Height>%d</pwg:Height></pwg:ScanRegion></pwg:ScanRegions>`+
+		`<pwg:InputSource>%s</pwg:InputSource><scan:ColorMode>%s</scan:ColorMode><pwg:DocumentFormat>image/jpeg</pwg:DocumentFormat>`+
+		`<scan:XResolution>%d</scan:XResolution><scan:YResolution>%d</scan:YResolution>%s</scan:ScanSettings>`,
+		min(a4Width, size.MaxWidth), min(a4Height, size.MaxHeight), source, escl, o.Resolution, o.Resolution, duplex), nil
+}
+
+// Scan puts one job for the glass to the scanner and returns the JPEG it sends. The resolution asked is only a
+// request: the real one is the image's own density (Density).
+//
+// A job stays open on the scanner (pwg:State Processing, and 503 to the next ScanJobs) until NextDocument has
+// answered 404 or the job is DELETEd, so Scan always ends the job it made: after the page it asks NextDocument
+// again, and on any failure after the job was created it deletes the job.
+func (c *Client) Scan(ctx context.Context, resolution int, colorMode string) ([]byte, error) {
+	pages, err := c.ScanPages(ctx, ScanOptions{Resolution: resolution, ColorMode: colorMode})
+	if err != nil {
+		return nil, err
+	}
+	return pages[0], nil
+}
+
+// ScanPages puts one job to the scanner, the glass or the feeder, and returns its pages in order. The glass holds
+// one page (a second is an error); the feeder is asked NextDocument until it answers 404, at most maxFeederPages
+// times. Either way the job is ended, and deleted on any failure after it was created.
+func (c *Client) ScanPages(ctx context.Context, o ScanOptions) ([][]byte, error) {
+	caps, err := c.Capabilities(ctx)
+	if err != nil {
+		return nil, err
+	}
+	settings, err := ScanSettings(caps, o)
+	if err != nil {
+		return nil, err
+	}
+	job, err := c.createJob(ctx, settings)
+	if err != nil {
+		return nil, err
+	}
+	doc := job + "/NextDocument"
+	if o.Feeder {
+		pages, err := c.feederPages(ctx, doc, o.Bound)
+		if err != nil {
+			c.deleteJob(job)
+			return nil, err
+		}
+		return pages, nil
+	}
+	image, err := c.page(ctx, doc)
+	if err != nil {
+		c.deleteJob(job)
+		return nil, err
+	}
+	closed, extra := c.closeJob(ctx, doc)
+	if !closed {
+		c.deleteJob(job)
+	}
+	if extra > 0 {
+		return nil, fmt.Errorf("the scanner gave more pages than the glass holds: %d", 1+extra)
+	}
+	return [][]byte{image}, nil
+}
+
+// feederPages asks NextDocument until the scanner answers 404, which ends the job. The first page missing means no
+// paper was in the feeder.
+func (c *Client) feederPages(ctx context.Context, doc string, bound func(int) time.Duration) ([][]byte, error) {
+	if bound == nil {
+		bound = FeederBound
+	}
+	start := time.Now()
+	var pages [][]byte
+	for len(pages) <= maxFeederPages {
+		if len(pages) > 0 {
+			if run, limit := time.Since(start), bound(len(pages)); run > limit {
+				return nil, fmt.Errorf("the feeder scan has run %s and has %d pages, past its bound of %s: it is stopped", run.Round(time.Second), len(pages), limit)
+			}
+		}
+		got, err := c.get(ctx, doc)
+		if err != nil {
+			return nil, fmt.Errorf("the scanned page %d cannot be fetched: %w", len(pages)+1, err)
+		}
+		image, err := readBody(got, maxImage)
+		if err != nil {
+			return nil, fmt.Errorf("the scanned page %d cannot be read: %w", len(pages)+1, err)
+		}
+		switch got.StatusCode {
+		case http.StatusOK:
+		case http.StatusNotFound:
+			if len(pages) == 0 {
+				return nil, fmt.Errorf("the scanner gave no page: is paper in the feeder?")
+			}
+			return pages, nil
+		case http.StatusGone:
+			return nil, fmt.Errorf("the scanner dropped the job: %s", got.Status)
+		default:
+			return nil, fmt.Errorf("the scanner gave no page %d: %s", len(pages)+1, got.Status)
+		}
+		if len(pages) == maxFeederPages {
+			break
+		}
+		if ct := got.Header.Get("Content-Type"); !strings.HasPrefix(ct, "image/jpeg") {
+			return nil, fmt.Errorf("the scanner sent %q, not image/jpeg", ct)
+		}
+		pages = append(pages, image)
+	}
+	return nil, fmt.Errorf("the feeder gave more than %d pages and the scanner did not end the job", maxFeederPages)
+}
+
+// leftOpen is the job URL, per scanner, that brother could neither finish nor delete.
+var leftOpen sync.Map
+
+func (c *Client) logf(format string, a ...any) {
+	if c.Logf != nil {
+		c.Logf(format, a...)
+		return
+	}
+	fmt.Fprintf(os.Stderr, format+"\n", a...)
+}
+
+func (c *Client) retryWait() time.Duration {
+	if c.RetryWait > 0 {
+		return c.RetryWait
+	}
+	return 4 * time.Second
+}
+
+// createJob posts the settings and returns the job's URL. A 503 is a scanner busy with another job; when the job
+// brother itself left open on this scanner is now closed, the post goes once more, never more than once.
+func (c *Client) createJob(ctx context.Context, settings string) (string, error) {
+	resp, reply, err := c.postJob(ctx, settings)
+	if err != nil {
+		return "", err
+	}
+	if resp.StatusCode == http.StatusServiceUnavailable {
+		if left, ok := leftOpen.Load(c.Base); ok {
+			select {
+			case <-time.After(c.retryWait()):
+			case <-ctx.Done():
+				return "", ctx.Err()
+			}
+			if c.deleteJob(left.(string)) {
+				if resp, reply, err = c.postJob(ctx, settings); err != nil {
+					return "", err
+				}
+			}
+		}
+		if resp.StatusCode == http.StatusServiceUnavailable {
+			return "", fmt.Errorf("the scanner is busy with another job: %s %s", resp.Status, strings.TrimSpace(string(reply)))
+		}
+	}
+	if resp.StatusCode != http.StatusCreated {
+		return "", fmt.Errorf("the scanner refused the scan job: %s %s", resp.Status, strings.TrimSpace(string(reply)))
+	}
+	loc := resp.Header.Get("Location")
+	if loc == "" {
+		return "", fmt.Errorf("the scanner took the scan job but named no Location")
+	}
+	base, _ := url.Parse(c.Base + "/")
+	ref, err := url.Parse(loc)
+	if err != nil {
+		return "", fmt.Errorf("the scan job's Location %q is not a URL: %w", loc, err)
+	}
+	return strings.TrimRight(base.ResolveReference(ref).String(), "/"), nil
+}
+
+func (c *Client) postJob(ctx context.Context, settings string) (*http.Response, []byte, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.Base+"/ScanJobs", strings.NewReader(settings))
+	if err != nil {
+		return nil, nil, err
+	}
+	req.Header.Set("Content-Type", "text/xml")
+	resp, err := c.HTTP.Do(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("the scanner does not answer: %w", err)
+	}
+	reply, _ := readBody(resp, 1<<20)
+	return resp, reply, nil
+}
+
+// page fetches the job's one page.
+func (c *Client) page(ctx context.Context, doc string) ([]byte, error) {
+	got, err := c.get(ctx, doc)
+	if err != nil {
+		return nil, fmt.Errorf("the scanned page cannot be fetched: %w", err)
+	}
+	image, err := readBody(got, maxImage)
+	if err != nil {
+		return nil, fmt.Errorf("the scanned page cannot be read: %w", err)
+	}
+	if got.StatusCode == http.StatusGone {
+		return nil, fmt.Errorf("the scanner dropped the job: %s", got.Status)
+	}
+	if got.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("the scanner gave no page: %s", got.Status)
+	}
+	if ct := got.Header.Get("Content-Type"); !strings.HasPrefix(ct, "image/jpeg") {
+		return nil, fmt.Errorf("the scanner sent %q, not image/jpeg", ct)
+	}
+	return image, nil
+}
+
+// maxClosing bounds the NextDocument requests that ask for the end of a job.
+const maxClosing = 1
+
+// closeJob asks NextDocument until the scanner answers 404, which ends the job; true when it did (or the job is
+// gone already), and how many further pages it sent instead; any is an error for the caller, for a Platen job holds
+// one page. It stops at the first further page, and the job is then deleted.
+func (c *Client) closeJob(ctx context.Context, doc string) (closed bool, extra int) {
+	ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 15*time.Second)
+	defer cancel()
+	for i := 0; i < maxClosing; i++ {
+		resp, err := c.get(ctx, doc)
+		if err != nil {
+			c.logf("brother: closing the scan job: %v", err)
+			return false, 0
+		}
+		readBody(resp, maxImage)
+		switch resp.StatusCode {
+		case http.StatusNotFound, http.StatusGone:
+			return true, 0
+		case http.StatusOK:
+			c.logf("brother: the scanner sent a further page after the glass's one")
+			return false, 1
+		}
+		c.logf("brother: closing the scan job: NextDocument answered %s", resp.Status)
+		return false, 0
+	}
+	return false, 0
+}
+
+// deleteJob deletes the job, best effort; true when the job is gone. A job that cannot be deleted is remembered, so
+// a 503 on the next scan can be told from another client's job.
+func (c *Client) deleteJob(job string) bool {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, job, nil)
+	if err == nil {
+		var resp *http.Response
+		if resp, err = c.HTTP.Do(req); err == nil {
+			readBody(resp, 1<<20)
+			if resp.StatusCode/100 == 2 || resp.StatusCode == http.StatusNotFound || resp.StatusCode == http.StatusGone {
+				leftOpen.Delete(c.Base)
+				return true
+			}
+			err = fmt.Errorf("answered %s", resp.Status)
+		}
+	}
+	c.logf("brother: deleting the scan job %s: %v", job, err)
+	leftOpen.Store(c.Base, job)
+	return false
+}
+
+// Density is the image's own resolution in dpi, from its JFIF header (units dpi, or dots per cm).
+func Density(jpegBytes []byte) (int, error) {
+	b := jpegBytes
+	if len(b) < 4 || b[0] != 0xFF || b[1] != 0xD8 {
+		return 0, fmt.Errorf("the image is not a JPEG")
+	}
+	for i := 2; i+4 <= len(b) && b[i] == 0xFF; {
+		marker, n := b[i+1], int(b[i+2])<<8|int(b[i+3])
+		if marker == 0xE0 && n >= 16 && i+4+12 <= len(b) && string(b[i+4:i+9]) == "JFIF\x00" {
+			units := b[i+11]
+			x := int(b[i+12])<<8 | int(b[i+13])
+			switch {
+			case units == 1 && x > 0:
+				return x, nil
+			case units == 2 && x > 0:
+				return int(float64(x)*2.54 + 0.5), nil
+			}
+			return 0, fmt.Errorf("the image's JFIF header gives no resolution")
+		}
+		if marker == 0xDA || n < 2 {
+			break
+		}
+		i += 2 + n
+	}
+	return 0, fmt.Errorf("the image has no JFIF header, so its resolution is unknown")
+}

modules/brother/cmd/brother/escl_test.go

@@ -0,0 +1,216 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+)
+
+// 1440/AC1: the captured capabilities, job creation, document and status replies, served by a test server.
+func TestScanPostsOnePlatenJobOverTheWholeGlassAndAsksNextDocumentAgainToCloseIt(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	image, err := NewClient(f.base()).Scan(context.Background(), 300, "color")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.posts != 1 {
+		t.Fatalf("%d ScanJobs posts, want 1", f.posts)
+	}
+	// The scanner ignores the whole body when it holds a line break (issue 1452), so the settings must have taken
+	// effect: the Platen, 300 dpi, A4 cut to the glass (2480 x 3507).
+	if f.job != (scannerJob{Source: "Platen", Resolution: 300, Region: "2480x3507"}) {
+		t.Fatalf("the scanner took %+v from the body %q", f.job, f.postBody)
+	}
+	// The page, then the second request that the scanner answers 404, which closes the job.
+	if f.documents != 2 || f.open || f.deletes != 0 {
+		t.Fatalf("%d NextDocument requests, job open %v, %d DELETEs, want 2, closed, 0", f.documents, f.open, f.deletes)
+	}
+	if want := fixture(t, "scan.jpg"); string(image) != string(want) {
+		t.Fatalf("the returned image is %d bytes, want the scanner's %d", len(image), len(want))
+	}
+}
+
+// 1440/AC1: the colour mode and resolution asked are the configured ones.
+func TestScanAsksForTheConfiguredResolutionAndColourMode(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	if _, err := NewClient(f.base()).Scan(context.Background(), 600, "gray"); err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"<scan:ColorMode>Grayscale8</scan:ColorMode>", "<scan:XResolution>600</scan:XResolution>", "<scan:YResolution>600</scan:YResolution>"} {
+		if !strings.Contains(f.postBody, want) {
+			t.Errorf("the job lacks %s:\n%s", want, f.postBody)
+		}
+	}
+}
+
+// 1440/AC1: a job the scanner refuses is an error that says so, and no page is fetched.
+func TestScanSaysWhyAScannerRefusal(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.refuse = 503
+	_, err := NewClient(f.base()).Scan(context.Background(), 300, "color")
+	if err == nil || !strings.Contains(err.Error(), "503") {
+		t.Fatalf("error = %v, want the refusal's 503", err)
+	}
+	if f.documents != 0 {
+		t.Fatalf("%d documents fetched after a refusal", f.documents)
+	}
+}
+
+// 1440/AC2: the image's own density, never the request's.
+func TestDensityIsTheImagesOwn(t *testing.T) {
+	dpi, err := Density(fixture(t, "scan.jpg"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if dpi != 200 {
+		t.Fatalf("density = %d dpi, want the captured scan's 200 (the request said 300)", dpi)
+	}
+}
+
+func TestDensityOfAnImageWithNoneIsAnError(t *testing.T) {
+	if _, err := Density([]byte{0xFF, 0xD8, 0xFF, 0xDA, 0, 2}); err == nil {
+		t.Fatal("an image with no JFIF header has a resolution")
+	}
+}
+
+// 1440/AC8: the captured status replies.
+func TestStatusReadsStateAndAdfState(t *testing.T) {
+	f := newFakeScanner(t, nil)
+	s, err := NewClient(f.base()).Status(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.State != "Idle" || s.AdfState != "ScannerAdfEmpty" {
+		t.Fatalf("status = %+v, want Idle / ScannerAdfEmpty", s)
+	}
+}
+
+// 1440/AC7: which value is unset is said by name.
+func TestMissingNamesWhatIsUnset(t *testing.T) {
+	for _, c := range []struct {
+		s    Settings
+		want string
+	}{
+		{Settings{Folder: "/x"}, "scanner"},
+		{Settings{Scanner: "http://192.0.2.10/eSCL"}, "scan-folder"},
+	} {
+		err := c.s.Missing()
+		if err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("Missing(%+v) = %v, want it to name %s", c.s, err, c.want)
+		}
+	}
+	if err := (Settings{Scanner: "a", Folder: "/x"}).Missing(); err != nil {
+		t.Errorf("both set: %v", err)
+	}
+}
+
+// 1531: two scans in a row both succeed, for the scanner answers 503 to a new job while one is open.
+func TestTwoScansInARowBothSucceed(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	c := NewClient(f.base())
+	for i := 1; i <= 2; i++ {
+		if _, err := c.Scan(context.Background(), 300, "color"); err != nil {
+			t.Fatalf("scan %d: %v", i, err)
+		}
+	}
+	if f.posts != 2 || f.open {
+		t.Fatalf("%d posts, job open %v, want 2, closed", f.posts, f.open)
+	}
+}
+
+// 1531: a page that cannot be had (the answer is lost) leaves no job open: the job is DELETEd.
+func TestAJobWhoseNextDocumentFailsIsDeleted(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.dropConn = true
+	if _, err := NewClient(f.base()).Scan(context.Background(), 300, "color"); err == nil {
+		t.Fatal("a lost answer is a scan")
+	}
+	if f.deletes != 1 || f.open {
+		t.Fatalf("%d DELETEs, job open %v, want 1, closed", f.deletes, f.open)
+	}
+	f.mu.Lock()
+	f.dropConn = false
+	f.mu.Unlock()
+	if _, err := NewClient(f.base()).Scan(context.Background(), 300, "color"); err != nil {
+		t.Fatalf("the scan after it: %v", err)
+	}
+}
+
+// 1531: a job with no page (404) is deleted too.
+func TestAJobThatGivesNoPageIsDeleted(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.noPage = true
+	if _, err := NewClient(f.base()).Scan(context.Background(), 300, "color"); err == nil {
+		t.Fatal("no page is a scan")
+	}
+	if f.open {
+		t.Fatal("the job stays open")
+	}
+}
+
+// 1531: a 410 on NextDocument is said as a dropped job, and the job is deleted.
+func TestAGoneJobIsSaidAsDroppedAndDeleted(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.gone = true
+	_, err := NewClient(f.base()).Scan(context.Background(), 300, "color")
+	if err == nil || !strings.Contains(err.Error(), "the scanner dropped the job") {
+		t.Fatalf("error = %v, want the scanner dropped the job", err)
+	}
+	if f.deletes != 1 {
+		t.Fatalf("%d DELETEs, want 1", f.deletes)
+	}
+}
+
+// 1531: a 503 while another job is open is said as busy, with no loop and no retry when brother left no job.
+func TestABusyScannerIsSaidAndNotRetriedWhenBrotherLeftNoJob(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.open = true // another client's job
+	c := NewClient(f.base())
+	c.RetryWait = time.Millisecond
+	_, err := c.Scan(context.Background(), 300, "color")
+	if err == nil || !strings.Contains(err.Error(), "the scanner is busy with another job") {
+		t.Fatalf("error = %v, want busy", err)
+	}
+	if f.posts != 1 {
+		t.Fatalf("%d posts, want 1", f.posts)
+	}
+}
+
+// 1531: a job brother left open (it could not close it) is closed after a wait, and the refused POST goes once more.
+func TestABusyScannerWithABrotherJobLeftIsRetriedOnceAfterItCloses(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.stuck = true
+	c := NewClient(f.base())
+	c.RetryWait = time.Millisecond
+	if _, err := c.Scan(context.Background(), 300, "color"); err == nil {
+		t.Fatal("a stuck job is a scan")
+	}
+	f.mu.Lock()
+	if !f.open {
+		t.Fatal("the fake should have kept the job open")
+	}
+	f.stuck = false
+	f.mu.Unlock()
+	c2 := NewClient(f.base())
+	c2.RetryWait = time.Millisecond
+	if _, err := c2.Scan(context.Background(), 300, "color"); err != nil {
+		t.Fatalf("scan after the left job closes: %v", err)
+	}
+	if f.posts != 3 {
+		t.Fatalf("%d posts, want 3 (stuck job, refused, retried)", f.posts)
+	}
+}
+
+// 1531: a second page for a Platen job is an error, never a silently incomplete scan, and the job is closed.
+func TestMorePagesThanTheGlassHoldsIsAnErrorAndTheJobIsClosed(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.pages = 2
+	image, err := NewClient(f.base()).Scan(context.Background(), 300, "color")
+	if err == nil || !strings.Contains(err.Error(), "the scanner gave more pages than the glass holds") {
+		t.Fatalf("image %d bytes, error = %v, want more pages than the glass holds", len(image), err)
+	}
+	if f.open || f.deletes != 1 {
+		t.Fatalf("job open %v, %d DELETEs, want closed by 1 DELETE", f.open, f.deletes)
+	}
+}

modules/brother/cmd/brother/feeder_test.go

@@ -0,0 +1,307 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// 1452: the Brother ignores the whole body when it holds a line break before the closing root tag, and runs its
+// default job (Platen, 200 dpi). The body is one line.
+func TestScanSettingsAreOneLineAndTheCapturedRequest(t *testing.T) {
+	caps, err := parseCapabilities(fixture(t, "capabilities.xml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, err := ScanSettings(caps, ScanOptions{Resolution: 200, ColorMode: "color", Feeder: true, Duplex: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	end := strings.Index(body, "</scan:ScanSettings>")
+	if end < 0 || strings.Contains(body[:end], "\n") {
+		t.Fatalf("the body has a line break before the closing root tag: %q", body)
+	}
+	// It is the request the real scanner took to feed three sheets, both sides (testdata/escl/settings.xml).
+	if want := strings.TrimSpace(string(fixture(t, "settings.xml"))); strings.TrimSpace(body) != want {
+		t.Fatalf("not the captured request\n got: %s\nwant: %s", body, want)
+	}
+	glass, _ := ScanSettings(caps, ScanOptions{Resolution: 300, ColorMode: "gray"})
+	if strings.Contains(glass[:strings.Index(glass, "</scan:ScanSettings>")], "\n") || strings.Contains(glass, "Duplex") ||
+		!strings.Contains(glass, "<pwg:InputSource>Platen</pwg:InputSource>") ||
+		!strings.Contains(glass, "<pwg:Width>2480</pwg:Width><pwg:Height>3507</pwg:Height>") {
+		t.Fatalf("the glass body is not one line of Platen, A4 cut to the glass's 3507: %q", glass)
+	}
+}
+
+// 1452: the fake is the real scanner in that: a body with a line break gets the defaults.
+func TestTheFakeScannerIgnoresABodyWithALineBreak(t *testing.T) {
+	multi := strings.Replace(string(fixture(t, "settings.xml")), "<pwg:Version>", "\n<pwg:Version>", 1)
+	if j := readSettings(multi); j.Source != "Platen" || j.Resolution != 200 || j.Duplex {
+		t.Fatalf("a body with a line break was read as %+v", j)
+	}
+	if j := readSettings(strings.TrimSpace(string(fixture(t, "settings.xml"))) + "\n"); j.Source != "Feeder" || !j.Duplex || j.Resolution != 200 {
+		t.Fatalf("the captured body with a trailing newline was read as %+v", j)
+	}
+}
+
+// 1452: three sheets, both sides, are six images from one job, fetched until NextDocument answers 404.
+func TestAFeederDuplexScanOfThreeSheetsGivesSixPagesAndClosesTheJob(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.sheets = 3
+	pages, err := NewClient(f.base()).ScanPages(context.Background(), ScanOptions{Resolution: 200, ColorMode: "color", Feeder: true, Duplex: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.job.Source != "Feeder" || !f.job.Duplex || f.job.Resolution != 200 || f.job.Region != "2480x3508" {
+		t.Fatalf("the scanner took %+v", f.job)
+	}
+	if len(pages) != 6 {
+		t.Fatalf("%d pages, want 6", len(pages))
+	}
+	if f.open || f.deletes != 0 || f.documents != 7 {
+		t.Fatalf("job open %v, %d DELETEs, %d NextDocument requests, want closed, 0, 7 (6 pages and the 404)", f.open, f.deletes, f.documents)
+	}
+}
+
+// 1452: an empty feeder is an error that says so, and no job stays open.
+func TestAnEmptyFeederIsAnErrorAndLeavesNoJob(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.sheets = 0
+	_, err := NewClient(f.base()).ScanPages(context.Background(), ScanOptions{Resolution: 200, ColorMode: "color", Feeder: true})
+	if err == nil || !strings.Contains(err.Error(), "feeder") {
+		t.Fatalf("error = %v, want it to name the feeder", err)
+	}
+	if f.open {
+		t.Fatal("the job stays open")
+	}
+}
+
+// 1452: a feeder that never says 404 is cut at 100 pages and the job is deleted.
+func TestAFeederThatNeverEndsIsCutAndTheJobDeleted(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.sheets = 500
+	_, err := NewClient(f.base()).ScanPages(context.Background(), ScanOptions{Resolution: 100, ColorMode: "gray", Feeder: true})
+	if err == nil || !strings.Contains(err.Error(), "100") {
+		t.Fatalf("error = %v, want the 100-page bound", err)
+	}
+	if f.open || f.deletes != 1 {
+		t.Fatalf("job open %v, %d DELETEs, want closed by 1 DELETE", f.open, f.deletes)
+	}
+}
+
+// 1452: a page that cannot be had in the middle of a feeder job deletes the job.
+func TestAFeederJobThatDropsMidwayIsDeleted(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.sheets = 3
+	f.dropConn = true
+	if _, err := NewClient(f.base()).ScanPages(context.Background(), ScanOptions{Resolution: 200, ColorMode: "color", Feeder: true}); err == nil {
+		t.Fatal("a lost answer is a scan")
+	}
+	if f.open || f.deletes != 1 {
+		t.Fatalf("job open %v, %d DELETEs, want closed by 1 DELETE", f.open, f.deletes)
+	}
+}
+
+func scanArgs(source string, duplex bool) map[string]any {
+	a := map[string]any{}
+	if source != "" {
+		a["source"] = source
+	}
+	if duplex {
+		a["duplex"] = true
+	}
+	return a
+}
+
+// 1452: through the tool, a duplex feeder scan is ONE PDF of six pages, filed once, and scan.added says pages 6.
+func TestTheToolFilesOneSixPagePDFForAFeederDuplexScan(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.sheets = 3
+	r, folder := scanRig(t, f, Settings{Crop: true, Resolution: 200})
+	got, err := r.call(t, "scanner.scan", scanArgs("feeder", true))
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := got.(map[string]any)
+	if body["pages"] != float64(6) || body["cropped"] != false {
+		t.Errorf("pages = %v, cropped = %v, want 6, false (a feeder page is a whole sheet)", body["pages"], body["cropped"])
+	}
+	pdf, err := os.ReadFile(body["path"].(string))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := bytes.Count(pdf, []byte("/Type /Page /Parent")); n != 6 || !bytes.Contains(pdf, []byte("/Count 6")) {
+		t.Errorf("the PDF has %d page objects, want 6 and /Count 6", n)
+	}
+	if f.open || f.deletes != 0 || f.posts != 1 {
+		t.Errorf("job open %v, %d DELETEs, %d posts", f.open, f.deletes, f.posts)
+	}
+	if entries, _ := os.ReadDir(folder); len(entries) != 1 {
+		t.Errorf("%d files in the scan folder, want 1", len(entries))
+	}
+	if out := *r.said; len(out) != 1 || out[0].body["pages"] != 6 || !out[0].seen {
+		t.Errorf("events = %+v, want one scan.added with pages 6, said after the scan was kept", out)
+	}
+}
+
+// 1452: the glass is one page, and duplex is for the feeder.
+func TestDuplexOnTheGlassIsRefusedAndNothingIsAsked(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{})
+	for _, args := range []map[string]any{scanArgs("", true), scanArgs("glass", true)} {
+		_, err := r.call(t, "scanner.scan", args)
+		if err == nil || !strings.Contains(err.Error(), "duplex") || !strings.Contains(err.Error(), "feeder") {
+			t.Errorf("%v: error = %v, want duplex is for the feeder", args, err)
+		}
+	}
+	if _, err := r.call(t, "scanner.scan", scanArgs("tray", false)); err == nil || !strings.Contains(err.Error(), "glass or feeder") {
+		t.Errorf("an unknown source: error = %v", err)
+	}
+	if r.bus.asks() != 0 || f.posts != 0 {
+		t.Errorf("%d asks queued, %d jobs posted", r.bus.asks(), f.posts)
+	}
+}
+
+// pdfCapture is a stand-in capture of a small PDF, ready to be released.
+func standInCapture(release <-chan struct{}, fail error) func(ctx context.Context, req ScanRequest) ([]Capture, error) {
+	return func(ctx context.Context, req ScanRequest) ([]Capture, error) {
+		<-release
+		if fail != nil {
+			return nil, fail
+		}
+		pdf := pdfOf(5000)
+		return []Capture{{PDF: pdf, SHA256: sha256Hex(pdf), Resolution: 200, Pages: 3, At: fixedNow}}, nil
+	}
+}
+
+// waitFor polls until the condition holds.
+func waitFor(t *testing.T, what string, cond func() bool) {
+	t.Helper()
+	for i := 0; i < 400; i++ {
+		if cond() {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("timed out waiting for %s", what)
+}
+
+// 1552 and 1539: a feeder scan not done within the quick wait is answered as started with its id; the scan goes on
+// and is filed although the caller has gone; the id reads the outcome, running and then done with the path.
+func TestALongFeederScanAnswersStartedAndIsFiledWithoutTheCaller(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{})
+	old := quickWait
+	quickWait = 50 * time.Millisecond
+	t.Cleanup(func() { quickWait = old })
+	release := make(chan struct{})
+	r.worker.Capture = standInCapture(release, nil)
+
+	got, err := r.call(t, "scanner.scan", scanArgs("feeder", false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	start := got.(map[string]any)
+	id, _ := start["id"].(string)
+	if start["started"] != true || id == "" || start["path"] != nil {
+		t.Fatalf("answer = %v, want started with an id", start)
+	}
+	running, err := r.call(t, "scanner.scan", map[string]any{"id": id})
+	if err != nil || running.(map[string]any)["state"] != "running" {
+		t.Fatalf("while it runs: %v, %v", running, err)
+	}
+	close(release)
+	// Nobody asks again: the scan is filed all the same.
+	waitFor(t, "the scan to be filed", func() bool { e, _ := os.ReadDir(folder); return len(e) == 1 })
+	// The file is renamed into place before the job is marked done: read the outcome until it is.
+	var d map[string]any
+	waitFor(t, "the outcome to be done", func() bool {
+		got, err := r.call(t, "scanner.scan", map[string]any{"id": id})
+		if err != nil {
+			t.Fatal(err)
+		}
+		d = got.(map[string]any)
+		return d["state"] != "running"
+	})
+	if d["state"] != "done" || d["pages"] != float64(3) || d["path"] == nil {
+		t.Fatalf("outcome = %v, want done with pages and the path", d)
+	}
+	if _, err := os.Stat(d["path"].(string)); err != nil {
+		t.Error(err)
+	}
+}
+
+// 1552: a scan that fails after the caller was told it started is read as failed, with why; an unknown id is an
+// error that says so.
+func TestAFailedLongScanIsReadAsFailedWithWhy(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{})
+	old := quickWait
+	quickWait = 50 * time.Millisecond
+	t.Cleanup(func() { quickWait = old })
+	release := make(chan struct{})
+	r.worker.Capture = standInCapture(release, errors.New("the scanner dropped the job: 410 Gone"))
+	start, err := r.call(t, "scanner.scan", scanArgs("feeder", true))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id := start.(map[string]any)["id"].(string)
+	close(release)
+	var out map[string]any
+	waitFor(t, "the failure", func() bool {
+		got, _ := r.call(t, "scanner.scan", map[string]any{"id": id})
+		out = got.(map[string]any)
+		return out["state"] == "failed"
+	})
+	if !strings.Contains(out["why"].(string), "410 Gone") {
+		t.Errorf("why = %v", out["why"])
+	}
+	if _, err := r.call(t, "scanner.scan", map[string]any{"id": "nosuchid"}); err == nil || !strings.Contains(err.Error(), "nosuchid") {
+		t.Errorf("an unknown id: %v", err)
+	}
+}
+
+// 1539: the feeder job's bound scales with its pages, from 3 to 30 minutes.
+func TestTheFeederBoundScalesWithThePages(t *testing.T) {
+	for pages, want := range map[int]time.Duration{1: 3 * time.Minute, 9: 3 * time.Minute, 30: 10 * time.Minute, 100: 30 * time.Minute, 500: 30 * time.Minute} {
+		if got := FeederBound(pages); got != want {
+			t.Errorf("FeederBound(%d) = %s, want %s", pages, got, want)
+		}
+	}
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.sheets = 3
+	_, err := NewClient(f.base()).ScanPages(context.Background(), ScanOptions{Resolution: 200, ColorMode: "color", Feeder: true,
+		Bound: func(int) time.Duration { return 0 }})
+	if err == nil || !strings.Contains(err.Error(), "bound") {
+		t.Fatalf("error = %v, want the bound", err)
+	}
+	if f.open || f.deletes != 1 {
+		t.Errorf("job open %v, %d DELETEs, want the job deleted", f.open, f.deletes)
+	}
+}
+
+// 1539: a scan too large for the tool to fetch is not kept nor announced: it is refused with its size.
+func TestAScanTooLargeToFetchIsNeitherKeptNorAnnounced(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{})
+	release := make(chan struct{})
+	close(release)
+	huge := make([]byte, MostAnswerParts*AnswerPartSize+1)
+	r.worker.Capture = func(ctx context.Context, req ScanRequest) ([]Capture, error) {
+		return []Capture{{PDF: huge, SHA256: "x", Resolution: 200, Pages: 99, At: fixedNow}}, nil
+	}
+	_, err := r.call(t, "scanner.scan", scanArgs("feeder", false))
+	if err == nil || !strings.Contains(err.Error(), "not kept") {
+		t.Fatalf("error = %v", err)
+	}
+	if len(*r.said) != 0 {
+		t.Errorf("%d events said for a scan not kept", len(*r.said))
+	}
+	if e, _ := os.ReadDir(folder); len(e) != 0 {
+		t.Errorf("filed: %v", e)
+	}
+}

modules/brother/cmd/brother/file.go

@@ -0,0 +1,163 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+// FileMode is the mode a created scan folder gets and ScanMode the mode of a filed scan.
+const (
+	FolderMode os.FileMode = 0o755
+	ScanMode   os.FileMode = 0o644
+)
+
+// File writes the PDF into the folder as scan-YYYY-MM-DD-HHMMSS.pdf (local time): whole beside its place as
+// .scan-*.tmp and then renamed, so nothing ever sees half a scan. A name taken already gets -2, -3, and a file
+// that is there is never overwritten. The folder is created when it is not there. Nothing in it that this
+// writes is touched but what it makes (1440/AC5, AC11).
+func File(folder string, pdf []byte, at time.Time) (string, error) {
+	if !filepath.IsAbs(folder) {
+		return "", fmt.Errorf("scan-folder %q is not an absolute path", folder)
+	}
+	if _, err := os.Stat(folder); os.IsNotExist(err) {
+		if err := os.MkdirAll(folder, FolderMode); err != nil {
+			return "", fmt.Errorf("the scan folder cannot be made: %w", err)
+		}
+		// The umask may have narrowed it; a folder this made is 0755 whatever the umask.
+		if err := os.Chmod(folder, FolderMode); err != nil {
+			return "", fmt.Errorf("the scan folder cannot be made: %w", err)
+		}
+	}
+	tmp, err := os.CreateTemp(folder, ".scan-*.tmp")
+	if err != nil {
+		return "", fmt.Errorf("the scan cannot be written in %s: %w", folder, err)
+	}
+	done := false
+	defer func() {
+		if !done {
+			tmp.Close()
+			os.Remove(tmp.Name())
+		}
+	}()
+	if _, err := tmp.Write(pdf); err != nil {
+		return "", fmt.Errorf("the scan cannot be written: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		return "", fmt.Errorf("the scan cannot be written: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return "", fmt.Errorf("the scan cannot be written: %w", err)
+	}
+	if err := os.Chmod(tmp.Name(), ScanMode); err != nil {
+		return "", err
+	}
+	stem := "scan-" + at.Local().Format("2006-01-02-150405")
+	for n := 1; n < 10000; n++ {
+		name := stem + ".pdf"
+		if n > 1 {
+			name = fmt.Sprintf("%s-%d.pdf", stem, n)
+		}
+		final := filepath.Join(folder, name)
+		// The name is taken by creating it exclusively; the finished file is then renamed over that empty
+		// one, so a scan never replaces a file that was there.
+		f, err := os.OpenFile(final, os.O_CREATE|os.O_EXCL|os.O_WRONLY, ScanMode)
+		if os.IsExist(err) {
+			continue
+		}
+		if err != nil {
+			return "", fmt.Errorf("the scan cannot be named in %s: %w", folder, err)
+		}
+		f.Close()
+		if err := os.Rename(tmp.Name(), final); err != nil {
+			os.Remove(final)
+			return "", fmt.Errorf("the scan cannot be put in place: %w", err)
+		}
+		done = true
+		return final, nil
+	}
+	return "", fmt.Errorf("no free scan name for %s in %s", stem, folder)
+}
+
+// Entry is one filed scan, as scan_list says it.
+type Entry struct {
+	Path     string    `json:"path"`
+	Bytes    int64     `json:"bytes"`
+	Modified time.Time `json:"modified"`
+}
+
+// List is the newest PDFs named scan-*.pdf in the folder, newest first, at most limit. A folder that is not
+// there yet is an empty list.
+func List(folder string, limit int) ([]Entry, error) {
+	entries, err := os.ReadDir(folder)
+	if os.IsNotExist(err) {
+		return []Entry{}, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("the scan folder cannot be read: %w", err)
+	}
+	out := []Entry{}
+	for _, e := range entries {
+		n := e.Name()
+		if e.IsDir() || !strings.HasPrefix(n, "scan-") || !strings.HasSuffix(n, ".pdf") {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil || !info.Mode().IsRegular() {
+			continue
+		}
+		out = append(out, Entry{Path: filepath.Join(folder, n), Bytes: info.Size(), Modified: info.ModTime()})
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if !out[i].Modified.Equal(out[j].Modified) {
+			return out[i].Modified.After(out[j].Modified)
+		}
+		return out[i].Path > out[j].Path
+	})
+	if limit > 0 && len(out) > limit {
+		out = out[:limit]
+	}
+	return out, nil
+}
+
+// PathRefused is the one answer to a path that may not be printed from: it says nothing of whether the path exists,
+// what it is or how large (issue 1551).
+const PathRefused = "path refused: only a file under the home folder"
+
+// ReadDocument is the file at path, read whole: a regular file under the tool account's home folder, of at most
+// most bytes. The path is resolved through its symbolic links first and the real path must still lie under the
+// home folder (which is itself resolved); anything else, a missing path included, is PathRefused and no more.
+func ReadDocument(path string, most int64) ([]byte, error) {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" || !filepath.IsAbs(path) {
+		return nil, errors.New(PathRefused)
+	}
+	realHome, err := filepath.EvalSymlinks(home)
+	if err != nil {
+		return nil, errors.New(PathRefused)
+	}
+	real, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		return nil, errors.New(PathRefused)
+	}
+	rel, err := filepath.Rel(realHome, real)
+	if err != nil || rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return nil, errors.New(PathRefused)
+	}
+	info, err := os.Stat(real)
+	if err != nil || !info.Mode().IsRegular() {
+		return nil, errors.New(PathRefused)
+	}
+	if info.Size() > most {
+		return nil, fmt.Errorf("file %s is %d bytes, over the %d the module takes", path, info.Size(), most)
+	}
+	doc, err := os.ReadFile(real)
+	if err != nil {
+		return nil, fmt.Errorf("file %s cannot be read: %w", path, err)
+	}
+	return doc, nil
+}

modules/brother/cmd/brother/file_test.go

@@ -0,0 +1,194 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+var scanName = regexp.MustCompile(`^scan-\d{4}-\d{2}-\d{2}-\d{6}(-\d+)?\.pdf$`)
+
+// 1440/AC5: a valid one-page PDF holding the JPEG as DCTDecode, at the image's real size.
+func TestPDFHoldsTheJPEGAtItsRealSize(t *testing.T) {
+	jpg := fixture(t, "scan.jpg")
+	pdf, err := PDF(jpg, 200)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(pdf)
+	if !strings.HasPrefix(s, "%PDF-1.4") || !strings.HasSuffix(s, "%%EOF\n") {
+		t.Fatalf("not a PDF: starts %q ends %q", s[:8], s[len(s)-6:])
+	}
+	if !bytes.Contains(pdf, jpg) {
+		t.Error("the JPEG is not embedded as it is")
+	}
+	for _, want := range []string{"/Filter /DCTDecode", "/Width 1696", "/Height 2203", "/ColorSpace /DeviceRGB", "/Count 1"} {
+		if !strings.Contains(s, want) {
+			t.Errorf("the PDF lacks %s", want)
+		}
+	}
+	// 1696 x 2203 px at 200 dpi is 610.56 x 793.08 pt, never the 300 dpi that was asked.
+	if !strings.Contains(s, "/MediaBox [0 0 610.56 793.08]") {
+		t.Errorf("page size wrong:\n%s", regexp.MustCompile(`/MediaBox[^\]]*\]`).FindString(s))
+	}
+	if n := strings.Count(s, "/Type /Page "); n != 1 {
+		t.Errorf("%d pages", n)
+	}
+	// Every xref entry points at its object.
+	at := strings.LastIndex(s, "startxref\n")
+	xref, _ := strconv.Atoi(strings.Fields(s[at+len("startxref\n"):])[0])
+	lines := strings.Split(s[xref:], "\n")
+	for i := 3; i <= 7 && i < len(lines); i++ {
+		off, err := strconv.Atoi(lines[i][:10])
+		if err != nil || !strings.HasPrefix(s[off:], fmt.Sprintf("%d 0 obj", i-2)) {
+			t.Errorf("xref entry %d (%q) does not point at object %d", i-2, lines[i], i-2)
+		}
+	}
+}
+
+// 1440/AC2: the page size follows the density it is given.
+func TestPDFPageSizeFollowsTheDensity(t *testing.T) {
+	jpg := fixture(t, "scan.jpg")
+	a, _ := PDF(jpg, 200)
+	b, _ := PDF(jpg, 300)
+	if bytes.Equal(a, b) {
+		t.Fatal("200 and 300 dpi give the same page")
+	}
+	if !strings.Contains(string(b), "/MediaBox [0 0 407.04 528.72]") {
+		t.Errorf("300 dpi page wrong")
+	}
+	if _, err := PDF(jpg, 0); err == nil {
+		t.Error("0 dpi accepted")
+	}
+}
+
+// 1440/AC5: exactly one file, named by local time, no temporary left, its bytes the PDF.
+func TestFileWritesOneNamedFileAndLeavesNoTemporary(t *testing.T) {
+	folder := t.TempDir()
+	at := time.Date(2026, 10, 20, 19, 5, 9, 0, time.Local)
+	path, err := File(folder, []byte("%PDF-x"), at)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := filepath.Join(folder, "scan-2026-10-20-190509.pdf"); path != want {
+		t.Fatalf("path = %s, want %s", path, want)
+	}
+	entries, _ := os.ReadDir(folder)
+	if len(entries) != 1 || !scanName.MatchString(entries[0].Name()) {
+		t.Fatalf("folder holds %v, want the one scan", entries)
+	}
+	if got, _ := os.ReadFile(path); string(got) != "%PDF-x" {
+		t.Fatalf("file holds %q", got)
+	}
+}
+
+// 1440/AC5: a name taken gets -2, -3; what was there is never overwritten.
+func TestFileNeverOverwritesAndSuffixes(t *testing.T) {
+	folder := t.TempDir()
+	at := time.Date(2026, 10, 20, 19, 5, 9, 0, time.Local)
+	first, _ := File(folder, []byte("one"), at)
+	second, err := File(folder, []byte("two"), at)
+	if err != nil {
+		t.Fatal(err)
+	}
+	third, _ := File(folder, []byte("three"), at)
+	for p, want := range map[string]string{
+		first: "one", second: "two", third: "three",
+	} {
+		if got, _ := os.ReadFile(p); string(got) != want {
+			t.Errorf("%s holds %q, want %q", p, got, want)
+		}
+	}
+	if filepath.Base(second) != "scan-2026-10-20-190509-2.pdf" || filepath.Base(third) != "scan-2026-10-20-190509-3.pdf" {
+		t.Errorf("names %s and %s", filepath.Base(second), filepath.Base(third))
+	}
+}
+
+// 1440/AC11: a folder that is not there is made, 0755, and the scan is filed in it.
+func TestFileMakesAMissingFolder(t *testing.T) {
+	folder := filepath.Join(t.TempDir(), "a", "scans")
+	path, err := File(folder, []byte("x"), time.Now())
+	if err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(folder)
+	if err != nil || info.Mode().Perm() != 0o755 {
+		t.Fatalf("folder: %v, mode %v, want 0755", err, info)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// 1440/AC11: a file in the folder that the module did not write is left as it was by every tool.
+func TestFileLeavesForeignFilesAlone(t *testing.T) {
+	folder := t.TempDir()
+	old := time.Date(2020, 1, 2, 3, 4, 5, 0, time.UTC)
+	foreign := map[string]string{"notes.txt": "mine", ".scan-theirs.tmp": "half", "scan-2020-01-01-000000.pdf": "someone else's"}
+	for n, c := range foreign {
+		p := filepath.Join(folder, n)
+		os.WriteFile(p, []byte(c), 0o600)
+		os.Chtimes(p, old, old)
+	}
+	if _, err := File(folder, []byte("x"), time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := List(folder, 10); err != nil {
+		t.Fatal(err)
+	}
+	for n, c := range foreign {
+		p := filepath.Join(folder, n)
+		got, err := os.ReadFile(p)
+		info, _ := os.Stat(p)
+		if err != nil || string(got) != c || !info.ModTime().Equal(old) || info.Mode().Perm() != 0o600 {
+			t.Errorf("%s changed: %q %v", n, got, err)
+		}
+	}
+}
+
+// 1440/AC7: a relative folder writes nothing.
+func TestFileRefusesARelativeFolder(t *testing.T) {
+	dir := t.TempDir()
+	t.Chdir(dir)
+	if _, err := File("scans", []byte("x"), time.Now()); err == nil {
+		t.Fatal("a relative folder was accepted")
+	}
+	if entries, _ := os.ReadDir(dir); len(entries) != 0 {
+		t.Fatalf("wrote %v", entries)
+	}
+}
+
+// 1440/AC8: scan_list: newest first, only scan PDFs, limited.
+func TestListIsNewestFirstAndLimited(t *testing.T) {
+	folder := t.TempDir()
+	base := time.Date(2026, 10, 1, 12, 0, 0, 0, time.UTC)
+	for i, n := range []string{"scan-a.pdf", "scan-b.pdf", "scan-c.pdf", "other.pdf", "scan-d.txt"} {
+		p := filepath.Join(folder, n)
+		os.WriteFile(p, []byte("x"), 0o644)
+		at := base.Add(time.Duration(i) * time.Hour)
+		os.Chtimes(p, at, at)
+	}
+	got, err := List(folder, 20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	names := []string{}
+	for _, e := range got {
+		names = append(names, filepath.Base(e.Path))
+	}
+	if strings.Join(names, ",") != "scan-c.pdf,scan-b.pdf,scan-a.pdf" {
+		t.Fatalf("list = %v", names)
+	}
+	if got, _ = List(folder, 2); len(got) != 2 || filepath.Base(got[0].Path) != "scan-c.pdf" {
+		t.Fatalf("limit 2 = %v", got)
+	}
+	if got, err = List(filepath.Join(folder, "none"), 5); err != nil || len(got) != 0 {
+		t.Fatalf("missing folder = %v, %v", got, err)
+	}
+}

modules/brother/cmd/brother/glass_test.go

@@ -0,0 +1,322 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"image"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// withDensity puts a JFIF header of dpi into a JPEG that has none (Go's encoder writes none).
+func withDensity(jpg []byte, dpi int) []byte {
+	app0 := []byte{0xFF, 0xE0, 0, 16, 'J', 'F', 'I', 'F', 0, 1, 1, 1, byte(dpi >> 8), byte(dpi), byte(dpi >> 8), byte(dpi), 0, 0}
+	return append(append(append([]byte{}, jpg[:2]...), app0...), jpg[2:]...)
+}
+
+// 1528: three receipts lying apart on the glass are three PDFs, each its own object, own scan.added and own file
+// in the scan folder, one page each; the answer lists every document.
+func TestSeveralDocumentsOnTheGlassAreFiledEachOnItsOwn(t *testing.T) {
+	scan := withDensity(onWhite(t, 11, image.Rect(100, 100, 300, 300), image.Rect(450, 100, 650, 400), image.Rect(100, 600, 400, 900)), 100)
+	f := newFakeScanner(t, scan)
+	r, folder := scanRig(t, f, Settings{Crop: true, Resolution: 100})
+	got, err := r.call(t, "scanner.scan", map[string]any{"apart": true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := got.(map[string]any)
+	docs, _ := body["documents"].([]any)
+	if len(docs) != 3 || body["count"] != 3 {
+		t.Fatalf("answer = %v, want three documents", body)
+	}
+	seen := map[string]bool{}
+	for _, d := range docs {
+		m := d.(map[string]any)
+		path, _ := m["path"].(string)
+		if _, err := os.Stat(path); err != nil || m["pages"] != float64(1) || m["cropped"] != true || seen[path] {
+			t.Errorf("document %v: %v", m, err)
+		}
+		seen[path] = true
+	}
+	if e, _ := os.ReadDir(folder); len(e) != 3 {
+		t.Errorf("%d files in the scan folder, want 3", len(e))
+	}
+	out := *r.said
+	if len(out) != 3 {
+		t.Fatalf("%d events, want one each", len(out))
+	}
+	keys := map[any]bool{}
+	for _, ev := range out {
+		keys[ev.body["object"]] = true
+		if !ev.seen {
+			t.Error("an event was said before its PDF was kept")
+		}
+	}
+	if len(keys) != 3 {
+		t.Errorf("the events name %d different objects, want 3", len(keys))
+	}
+}
+
+// 1528: one document on the glass is answered as today: a flat body with its path.
+func TestOneDocumentOnTheGlassIsAnsweredAsBefore(t *testing.T) {
+	scan := withDensity(onWhite(t, 12, image.Rect(100, 100, 300, 300)), 100)
+	f := newFakeScanner(t, scan)
+	r, _ := scanRig(t, f, Settings{Crop: true, Resolution: 100})
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if body["documents"] != nil || body["path"] == nil || len(*r.said) != 1 {
+		t.Errorf("answer = %v, %d events", body, len(*r.said))
+	}
+}
+
+func docArgs(document string, finish bool) map[string]any {
+	a := map[string]any{"document": document}
+	if finish {
+		a["finish"] = true
+	}
+	return a
+}
+
+// 1538: start scans page 1 into a new document and files nothing; the id adds the next page; finish closes the
+// pages into one PDF, one object, one scan.added, one file, and scans nothing.
+func TestAGlassDocumentOfTwoPagesIsOnePDFFiledOnce(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: false, Resolution: 200})
+	got, err := r.call(t, "scanner.scan", docArgs("start", false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id, _ := got.(map[string]any)["document"].(string)
+	if id == "" || got.(map[string]any)["pages"] != float64(1) {
+		t.Fatalf("start answered %v", got)
+	}
+	if got, err = r.call(t, "scanner.scan", docArgs(id, false)); err != nil || got.(map[string]any)["pages"] != float64(2) {
+		t.Fatalf("second page: %v, %v", got, err)
+	}
+	if e, _ := os.ReadDir(folder); len(e) != 0 || len(*r.said) != 0 {
+		t.Fatalf("an open document filed %d files and said %d events", len(e), len(*r.said))
+	}
+	posts := f.posts
+	got, err = r.call(t, "scanner.scan", docArgs(id, true))
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := got.(map[string]any)
+	if body["pages"] != float64(2) || body["path"] == nil || f.posts != posts {
+		t.Fatalf("finish answered %v (%d scans after, %d before)", body, f.posts, posts)
+	}
+	pdf, _ := os.ReadFile(body["path"].(string))
+	if !bytes.Contains(pdf, []byte("/Count 2")) || bytes.Count(pdf, []byte("/Type /Page /Parent")) != 2 {
+		t.Error("the filed PDF does not have two pages")
+	}
+	if e, _ := os.ReadDir(folder); len(e) != 1 || len(*r.said) != 1 || (*r.said)[0].body["pages"] != 2 {
+		t.Errorf("%d files, %d events", len(e), len(*r.said))
+	}
+	// A closed document takes no more.
+	if _, err := r.call(t, "scanner.scan", docArgs(id, false)); err == nil || !strings.Contains(err.Error(), "closed already") {
+		t.Errorf("a page into a closed document: %v", err)
+	}
+}
+
+// 1538: what is refused: finish with start, an unknown id, a feeder document, an id that is no id.
+func TestGlassDocumentsRefuseWhatIsNotWellFormed(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{})
+	for name, args := range map[string]map[string]any{
+		"finish with start": docArgs("start", true),
+		"finish alone":      {"finish": true},
+		"unknown id":        docArgs("nosuchdocument", false),
+		"unknown finish":    docArgs("nosuchdocument", true),
+		"bad id":            docArgs("../../etc", false),
+		"on the feeder":     {"document": "start", "source": "feeder"},
+	} {
+		if _, err := r.call(t, "scanner.scan", args); err == nil {
+			t.Errorf("%s: accepted", name)
+		}
+	}
+	if f.posts != 0 {
+		t.Errorf("%d scans were put for refused asks", f.posts)
+	}
+}
+
+// 1538: an open document that gets no page is closed and filed as one PDF by the tool: its pages are not lost.
+func TestAnUnfinishedGlassDocumentIsFiledAfterItsExpiry(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: false, Resolution: 200})
+	old := docExpiry
+	docExpiry = 150 * time.Millisecond
+	t.Cleanup(func() { docExpiry = old })
+	got, err := r.call(t, "scanner.scan", docArgs("start", false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id := got.(map[string]any)["document"].(string)
+	if _, err := r.call(t, "scanner.scan", docArgs(id, false)); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, "the expired document to be filed", func() bool { e, _ := os.ReadDir(folder); return len(e) == 1 })
+	e, _ := os.ReadDir(folder)
+	pdf, _ := os.ReadFile(filepath.Join(folder, e[0].Name()))
+	if !bytes.Contains(pdf, []byte("/Count 2")) || len(*r.said) != 1 {
+		t.Errorf("the expired document: %d events, two pages %v", len(*r.said), bytes.Contains(pdf, []byte("/Count 2")))
+	}
+}
+
+// 1538: finishing a document does not wait for the expiry: its timer is gone, so nothing is filed twice.
+func TestAFinishedGlassDocumentIsNotFiledAgainByItsExpiry(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: false, Resolution: 200})
+	old := docExpiry
+	docExpiry = 150 * time.Millisecond
+	t.Cleanup(func() { docExpiry = old })
+	got, _ := r.call(t, "scanner.scan", docArgs("start", false))
+	id := got.(map[string]any)["document"].(string)
+	if _, err := r.call(t, "scanner.scan", docArgs(id, true)); err != nil {
+		t.Fatal(err)
+	}
+	time.Sleep(400 * time.Millisecond)
+	if e, _ := os.ReadDir(folder); len(e) != 1 {
+		t.Errorf("%d files, want 1", len(e))
+	}
+}
+
+// 1539: an ask carries its deadline, and a device process that takes it up later does nothing for it: nothing is
+// scanned, the answer says why, and the message ends.
+func TestAnAskTakenUpAfterItsDeadlineIsDroppedBeforeAnyWork(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{})
+	scans := 0
+	r.worker.Capture = func(ctx context.Context, req ScanRequest) ([]Capture, error) {
+		scans++
+		return nil, errors.New("scanned")
+	}
+	late, _ := json.Marshal(Ask{ID: "late", Op: OpScan, At: fixedNow.Add(-4 * time.Minute), Deadline: fixedNow.Add(-time.Second)})
+	if act, _ := r.worker.Handle(late, func() { t.Error("a late ask was acknowledged early as work to be done") }); act != actionTerm {
+		t.Errorf("action = %v, want the message ended", act)
+	}
+	if scans != 0 || len(*r.said) != 0 {
+		t.Errorf("%d scans, %d events for a late ask", scans, len(*r.said))
+	}
+	if raw := r.answers.get("late"); !strings.Contains(string(raw), "deadline") {
+		t.Errorf("answer = %s", raw)
+	}
+	onTime, _ := json.Marshal(Ask{ID: "ontime", Op: OpScan, At: fixedNow, Deadline: fixedNow.Add(time.Minute)})
+	r.worker.Handle(onTime, nil)
+	if scans != 1 {
+		t.Errorf("an ask in time was not scanned")
+	}
+	_ = folder
+}
+
+// 1539: a scan the device process took up in time but ran past the tool's start-by wait is still filed: the tool
+// follows it for the run's own bound.
+func TestAScanThatRunsPastTheStartByWaitIsStillFiled(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{})
+	old := scanWait
+	scanWait = 100 * time.Millisecond
+	t.Cleanup(func() { scanWait = old })
+	release := make(chan struct{})
+	r.worker.Capture = standInCapture(release, nil)
+	got, err := r.call(t, "scanner.scan", map[string]any{})
+	if err != nil || got.(map[string]any)["started"] != true {
+		t.Fatalf("answer = %v, %v, want started", got, err)
+	}
+	time.Sleep(300 * time.Millisecond) // past the start-by wait; the answer comes only now
+	close(release)
+	waitFor(t, "the late scan to be filed", func() bool { e, _ := os.ReadDir(folder); return len(e) == 1 })
+}
+
+// 1538: an expired document whose closing fails is not forgotten: it is tried again.
+func TestAnExpiredDocumentWhoseClosingFailsIsClosedOnTheNextTry(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: false, Resolution: 200})
+	oldE, oldR := docExpiry, docRetry
+	docExpiry, docRetry = 100*time.Millisecond, 100*time.Millisecond
+	t.Cleanup(func() { docExpiry, docRetry = oldE, oldR })
+	askBus = &flakyBus{fakeAskBus: &fakeAskBus{worker: r.worker, answers: r.answers}, fails: 2,
+		match: func(a Ask) bool { return a.Op == OpScan && a.Finish }}
+	if _, err := r.call(t, "scanner.scan", docArgs("start", false)); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, "the document to be filed on the third try", func() bool { e, _ := os.ReadDir(folder); return len(e) == 1 })
+}
+
+// 1538: after a restart of the tool process the open documents are found again in the bucket and their expiry
+// armed from the time of their last page; closing a document deletes its pages.
+func TestAnOpenDocumentIsFoundAgainAfterARestartAndItsPagesAreDeletedWhenClosed(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: false, Resolution: 200})
+	got, err := r.call(t, "scanner.scan", docArgs("start", false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	id := got.(map[string]any)["document"].(string)
+	// A new tool process: no timers. Its Recover finds the document and arms it.
+	old := docExpiry
+	docExpiry = 200 * time.Millisecond
+	t.Cleanup(func() { docExpiry = old })
+	s := &Service{Settings: Settings{Scanner: f.base(), Folder: folder, Resolution: 200, ColorMode: "color"}, Now: func() time.Time { return fixedNow },
+		Asks: askBus, AnswerWait: 5 * time.Second, ScanWait: 5 * time.Second, AnswerPoll: 5 * time.Millisecond, Jobs: NewJobs()}
+	if err := s.Recover(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, "the recovered document to be closed", func() bool { e, _ := os.ReadDir(folder); return len(e) == 1 })
+	waitFor(t, "its pages to be deleted", func() bool {
+		for _, k := range r.objects.keys() {
+			if strings.HasPrefix(k, "pending/"+id+"/") && strings.HasSuffix(k, ".jpg") {
+				return false
+			}
+		}
+		return true
+	})
+	var hasManifest bool
+	for _, k := range r.objects.keys() {
+		hasManifest = hasManifest || k == "pending/"+id+"/manifest.json"
+	}
+	if !hasManifest {
+		t.Error("the manifest that says the document is closed was deleted too")
+	}
+}
+
+// 1552: a finished job's outcome is forgotten after jobKeep.
+func TestAFinishedJobIsForgottenAfterAnHour(t *testing.T) {
+	old := jobKeep
+	jobKeep = 30 * time.Millisecond
+	t.Cleanup(func() { jobKeep = old })
+	j := NewJobs()
+	first := j.put("a")
+	close(first.done)
+	time.Sleep(60 * time.Millisecond)
+	j.put("b")
+	if j.get("a") != nil || j.get("b") == nil {
+		t.Errorf("a = %v, b = %v", j.get("a"), j.get("b"))
+	}
+}
+
+// 1528: without apart three documents on the glass are one, cut around all of them, as before.
+func TestWithoutApartSeveralDocumentsOnTheGlassAreOneScan(t *testing.T) {
+	scan := withDensity(onWhite(t, 11, image.Rect(100, 100, 300, 300), image.Rect(450, 100, 650, 400), image.Rect(100, 600, 400, 900)), 100)
+	f := newFakeScanner(t, scan)
+	r, folder := scanRig(t, f, Settings{Crop: true, Resolution: 100})
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if body["documents"] != nil || body["path"] == nil || len(*r.said) != 1 {
+		t.Errorf("answer = %v, %d events", body, len(*r.said))
+	}
+	if e, _ := os.ReadDir(folder); len(e) != 1 {
+		t.Errorf("%d files, want 1", len(e))
+	}
+	if _, err := r.call(t, "scanner.scan", map[string]any{"apart": true, "source": "feeder"}); err == nil || !strings.Contains(err.Error(), "apart is for the glass") {
+		t.Errorf("apart on the feeder: %v", err)
+	}
+}

modules/brother/cmd/brother/helpers_test.go

@@ -0,0 +1,183 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fixture reads a capture of the real scanner's answers (testdata/escl, 2026-10-20). Tests never reach a real scanner.
+func fixture(t *testing.T, name string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("testdata", "escl", name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}
+
+// fakeScanner serves the captured eSCL answers and records what it was asked.
+type fakeScanner struct {
+	*httptest.Server
+	mu        sync.Mutex
+	image     []byte
+	postBody  string
+	posts     int
+	documents int // NextDocument requests
+	refuse    int // when set, the status ScanJobs answers instead of 201
+	noPage    bool
+	// A real scanner keeps a job open (and answers a new POST with 503) until its NextDocument has answered 404
+	// or the job is DELETEd; the fake does the same.
+	open      bool
+	delivered bool
+	pages     int // pages a job holds beyond the first
+	served    int
+	deletes   int
+	gone      bool // the first NextDocument answers 410 (the job was cancelled at the device)
+	dropConn  bool // the first NextDocument loses its answer
+	stuck     bool // the job cannot be closed: NextDocument and DELETE both fail
+	// sheets is what the feeder holds; a duplex job gives two pages a sheet.
+	sheets int
+	// job is what the scanner took of the last body. The real Brother ignores the WHOLE body when it holds a line
+	// break before the closing root tag (issue 1452) and runs its default job: Platen, 200 dpi, one page.
+	job scannerJob
+}
+
+type scannerJob struct {
+	Source     string
+	Resolution int
+	Duplex     bool
+	Region     string // width x height
+}
+
+var (
+	reSource = regexp.MustCompile(`<pwg:InputSource>(\w+)</pwg:InputSource>`)
+	reXRes   = regexp.MustCompile(`<scan:XResolution>(\d+)</scan:XResolution>`)
+	reRegion = regexp.MustCompile(`<pwg:Width>(\d+)</pwg:Width><pwg:Height>(\d+)</pwg:Height>`)
+)
+
+// readSettings is the real scanner's reading of a body: a line break before the closing root tag and every setting
+// is ignored.
+func readSettings(body string) scannerJob {
+	end := strings.Index(body, "</scan:ScanSettings>")
+	if end < 0 || strings.Contains(body[:end], "\n") {
+		return scannerJob{Source: "Platen", Resolution: 200, Region: "1696x2203"}
+	}
+	j := scannerJob{Source: "Platen", Resolution: 200, Duplex: strings.Contains(body, "<scan:Duplex>true</scan:Duplex>")}
+	if m := reSource.FindStringSubmatch(body); m != nil {
+		j.Source = m[1]
+	}
+	if m := reXRes.FindStringSubmatch(body); m != nil {
+		j.Resolution, _ = strconv.Atoi(m[1])
+	}
+	if m := reRegion.FindStringSubmatch(body); m != nil {
+		j.Region = m[1] + "x" + m[2]
+	}
+	return j
+}
+
+// total is how many pages the job holds.
+func (f *fakeScanner) total() int {
+	if f.job.Source == "Feeder" {
+		if f.job.Duplex {
+			return 2 * f.sheets
+		}
+		return f.sheets
+	}
+	return 1 + f.pages
+}
+
+func newFakeScanner(t *testing.T, image []byte) *fakeScanner {
+	t.Helper()
+	f := &fakeScanner{image: image}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/eSCL/ScannerCapabilities", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/xml")
+		w.Write(fixture(t, "capabilities.xml"))
+	})
+	mux.HandleFunc("/eSCL/ScannerStatus", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/xml")
+		w.Write(fixture(t, "status-idle.xml"))
+	})
+	mux.HandleFunc("/eSCL/ScanJobs", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if r.Method != http.MethodPost {
+			http.Error(w, "post only", http.StatusMethodNotAllowed)
+			return
+		}
+		b := make([]byte, 1<<16)
+		n, _ := r.Body.Read(b)
+		f.postBody = string(b[:n])
+		f.posts++
+		f.job = readSettings(f.postBody)
+		if f.refuse != 0 {
+			http.Error(w, "busy", f.refuse)
+			return
+		}
+		if f.open {
+			http.Error(w, "busy", http.StatusServiceUnavailable)
+			return
+		}
+		f.open, f.delivered, f.served = true, false, 0
+		// The captured Location names the real scanner's host; the test's own server stands in for it.
+		w.Header().Set("Location", f.URL+"/eSCL/ScanJobs/7320ead5")
+		w.WriteHeader(http.StatusCreated)
+	})
+	mux.HandleFunc("/eSCL/ScanJobs/7320ead5/NextDocument", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		f.documents++
+		if f.stuck {
+			http.Error(w, "stuck", http.StatusInternalServerError)
+			return
+		}
+		if f.gone {
+			f.gone, f.open = false, false
+			http.Error(w, "gone", http.StatusGone)
+			return
+		}
+		if f.dropConn {
+			if hj, ok := w.(http.Hijacker); ok {
+				c, _, _ := hj.Hijack()
+				c.Close()
+			}
+			return
+		}
+		if f.noPage || f.served >= f.total() {
+			f.open = false
+			http.NotFound(w, r)
+			return
+		}
+		f.delivered = true
+		f.served++
+		w.Header().Set("Content-Type", "image/jpeg")
+		w.Write(f.image)
+	})
+	mux.HandleFunc("/eSCL/ScanJobs/7320ead5", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if r.Method != http.MethodDelete {
+			http.Error(w, "delete only", http.StatusMethodNotAllowed)
+			return
+		}
+		f.deletes++
+		if f.stuck {
+			http.Error(w, "stuck", http.StatusInternalServerError)
+			return
+		}
+		f.open = false
+		w.WriteHeader(http.StatusOK)
+	})
+	f.Server = httptest.NewServer(mux)
+	t.Cleanup(f.Close)
+	return f
+}
+
+func (f *fakeScanner) base() string { return f.URL + "/eSCL" }

modules/brother/cmd/brother/html.go

@@ -0,0 +1,400 @@
+package main
+
+import (
+	"html"
+	"regexp"
+	"strings"
+	"unicode/utf8"
+)
+
+// The printer's admin pages are small, tolerant HTML (XHTML 1.0 with unclosed inputs). Only what the module
+// reads is taken out of them: the title, the links, and the forms with their fields.
+
+// Link is an anchor of a page.
+type Link struct {
+	Href string `json:"href"`
+	Text string `json:"text"`
+}
+
+// Field is a named control of a form. A password field's value is never kept (ADR 0467 clause 4).
+type Field struct {
+	Name    string   `json:"name"`
+	Type    string   `json:"type"`
+	Value   string   `json:"value"`
+	Checked *bool    `json:"checked,omitempty"`
+	Label   string   `json:"label"`
+	Options []Option `json:"options,omitempty"`
+	id      string
+	own     string // the label of this control alone: <label for>, a wrapping <label>, or a radio button's text after it
+	row     string // what the control's table row (or <dt>) calls it
+}
+
+// Option is a choice of a select (Value and Text) or a button of a radio group (Value and Label).
+type Option struct {
+	Value string `json:"value"`
+	Label string `json:"label,omitempty"`
+	Text  string `json:"text,omitempty"`
+}
+
+// Form is a form of a page with its named fields.
+type Form struct {
+	Action string  `json:"action"`
+	Method string  `json:"method"`
+	Fields []Field `json:"fields"`
+}
+
+// Page is what a page of the admin site holds.
+type Page struct {
+	Title string `json:"title"`
+	Links []Link `json:"links"`
+	Forms []Form `json:"forms"`
+}
+
+var attrRE = regexp.MustCompile(`([A-Za-z_:][-A-Za-z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?`)
+
+// attrs reads a tag's attributes, names in lower case and values unescaped.
+func attrs(s string) map[string]string {
+	out := map[string]string{}
+	for _, m := range attrRE.FindAllStringSubmatch(s, -1) {
+		v := m[2] + m[3] + m[4]
+		out[strings.ToLower(m[1])] = html.UnescapeString(v)
+	}
+	return out
+}
+
+func squash(s string) string { return strings.Join(strings.Fields(html.UnescapeString(s)), " ") }
+
+// latin1 turns a body that is not UTF-8 into UTF-8, reading each byte as the character of the same number:
+// the printer's pages say iso-8859-1.
+func latin1(b []byte) string {
+	if utf8.Valid(b) {
+		return string(b)
+	}
+	r := make([]rune, len(b))
+	for i, c := range b {
+		r[i] = rune(c)
+	}
+	return string(r)
+}
+
+// tagEnd is the index of the '>' that closes the tag starting at s[0], skipping quoted values, or -1.
+func tagEnd(s string) int {
+	var q byte
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		switch {
+		case q != 0:
+			if c == q {
+				q = 0
+			}
+		case c == '"' || c == '\'':
+			q = c
+		case c == '>':
+			return i
+		}
+	}
+	return -1
+}
+
+// ParsePage reads a page. Unknown markup is skipped, and what is not closed is closed at the end.
+func ParsePage(body []byte) Page {
+	s := latin1(body)
+	var p Page
+	var (
+		inTitle  bool
+		title    strings.Builder
+		link     *Link
+		formOpen bool
+		form     Form
+		labelFor string
+		inLabel  bool
+		label    strings.Builder
+		labelIDs = map[string]string{}
+		wrapped  []int // fields inside a label that names none, by index in form.Fields
+		selIdx   = -1
+		inOption bool
+		optValue string
+		optHasV  bool
+		optSel   bool
+		optText  strings.Builder
+		inTextA  bool
+		textA    strings.Builder
+		textAIdx = -1
+		// Where a control stands in its row: Brother pages lay a setting out as <tr><th>name</th><td>control</td></tr>
+		// or <dt>name</dt><dd>control</dd>; the first cell names the row.
+		cellN    int
+		cellOpen bool
+		cellText strings.Builder
+		rowFirst string
+		lastText string
+		tailIdx  = -1
+	)
+	finishOption := func() {
+		if !inOption || selIdx < 0 {
+			inOption = false
+			return
+		}
+		v := optValue
+		if !optHasV {
+			v = squash(optText.String())
+		}
+		f := &form.Fields[selIdx]
+		if len(f.Options) == 0 {
+			f.Value = v // a browser shows the first option when none is selected
+		}
+		f.Options = append(f.Options, Option{Value: v, Text: squash(optText.String())})
+		if optSel {
+			f.Value = v
+		}
+		inOption = false
+	}
+	closeForm := func() {
+		finishOption()
+		selIdx = -1
+		if formOpen {
+			p.Forms = append(p.Forms, form)
+		}
+		formOpen = false
+		form = Form{}
+	}
+	addField := func(f Field) {
+		f.row = rowFirst
+		if (cellOpen && cellN == 1) || f.row == "" {
+			f.row = lastText
+		}
+		lastText = "" // text before a control names that control alone
+		form.Fields = append(form.Fields, f)
+		if inLabel && labelFor == "" {
+			wrapped = append(wrapped, len(form.Fields)-1)
+		}
+	}
+	text := func(t string) {
+		switch {
+		case inTitle:
+			title.WriteString(t)
+		case inOption:
+			optText.WriteString(t)
+		case inTextA:
+			textA.WriteString(t)
+		}
+		if !inTitle && !inOption && !inTextA && link == nil {
+			if q := squash(t); q != "" {
+				switch {
+				case tailIdx >= 0:
+					// the text right after a radio button is that button's, not the next field's
+					if form.Fields[tailIdx].own == "" {
+						form.Fields[tailIdx].own = q
+					}
+				case !inLabel:
+					lastText = q
+				}
+			}
+			if cellOpen && cellN == 1 {
+				cellText.WriteString(t)
+			}
+		}
+		if link != nil {
+			link.Text += t
+		}
+		if inLabel {
+			label.WriteString(t)
+		}
+	}
+	i := 0
+	for i < len(s) {
+		lt := strings.IndexByte(s[i:], '<')
+		if lt < 0 {
+			text(s[i:])
+			break
+		}
+		text(s[i : i+lt])
+		i += lt
+		switch {
+		case strings.HasPrefix(s[i:], "<!--"):
+			end := strings.Index(s[i:], "-->")
+			if end < 0 {
+				i = len(s)
+			} else {
+				i += end + 3
+			}
+			continue
+		case strings.HasPrefix(s[i:], "<!") || strings.HasPrefix(s[i:], "<?"):
+			end := strings.IndexByte(s[i:], '>')
+			if end < 0 {
+				i = len(s)
+			} else {
+				i += end + 1
+			}
+			continue
+		}
+		end := tagEnd(s[i:])
+		if end < 0 {
+			break
+		}
+		tailIdx = -1
+		raw := s[i+1 : i+end]
+		i += end + 1
+		closing := strings.HasPrefix(raw, "/")
+		raw = strings.TrimSuffix(strings.TrimPrefix(raw, "/"), "/")
+		name := raw
+		rest := ""
+		if sp := strings.IndexAny(raw, " \t\r\n"); sp >= 0 {
+			name, rest = raw[:sp], raw[sp:]
+		}
+		name = strings.ToLower(name)
+		if !closing && (name == "script" || name == "style") {
+			if e := strings.Index(strings.ToLower(s[i:]), "</"+name); e >= 0 {
+				i += e
+			} else {
+				i = len(s)
+			}
+			continue
+		}
+		a := map[string]string{}
+		if !closing {
+			a = attrs(rest)
+		}
+		switch name {
+		case "title":
+			inTitle = !closing
+		case "tr":
+			cellN, cellOpen, rowFirst, lastText = 0, false, "", ""
+			cellText.Reset()
+		case "td", "th", "dt", "dd":
+			if cellOpen && cellN == 1 {
+				rowFirst = squash(cellText.String())
+			}
+			cellOpen = false
+			if name == "dt" && !closing {
+				cellN, rowFirst, lastText = 0, "", ""
+			}
+			if !closing {
+				cellN++
+				if name == "dd" && cellN < 2 {
+					cellN = 2
+				}
+				cellOpen = true
+				cellText.Reset()
+			}
+		case "a":
+			if closing {
+				if link != nil {
+					link.Text = squash(link.Text)
+					p.Links = append(p.Links, *link)
+				}
+				link = nil
+			} else if href, ok := a["href"]; ok {
+				link = &Link{Href: href}
+			}
+		case "form":
+			closeForm()
+			lastText = ""
+			if !closing {
+				formOpen = true
+				form = Form{Action: a["action"], Method: strings.ToLower(a["method"])}
+				if form.Method == "" {
+					form.Method = "get"
+				}
+			}
+		case "label":
+			if closing {
+				t := squash(label.String())
+				if labelFor != "" {
+					labelIDs[labelFor] = t
+				}
+				for _, k := range wrapped {
+					form.Fields[k].own = t
+				}
+				inLabel, labelFor, wrapped = false, "", nil
+				label.Reset()
+			} else {
+				inLabel, labelFor = true, a["for"]
+				label.Reset()
+			}
+		case "input":
+			if closing || a["name"] == "" {
+				break
+			}
+			typ := strings.ToLower(a["type"])
+			if typ == "" {
+				typ = "text"
+			}
+			if typ == "submit" || typ == "button" || typ == "image" || typ == "reset" {
+				break
+			}
+			f := Field{Name: a["name"], Type: typ, Value: a["value"], id: a["id"]}
+			if typ == "password" {
+				f.Value = ""
+			}
+			if typ == "checkbox" || typ == "radio" {
+				_, on := a["checked"]
+				f.Checked = &on
+			}
+			addField(f)
+			if typ == "radio" {
+				tailIdx = len(form.Fields) - 1
+			}
+		case "select":
+			finishOption()
+			selIdx = -1
+			if !closing && a["name"] != "" {
+				addField(Field{Name: a["name"], Type: "select", id: a["id"]})
+				selIdx = len(form.Fields) - 1
+			}
+		case "option":
+			finishOption()
+			if !closing && selIdx >= 0 {
+				inOption = true
+				optValue, optHasV = a["value"], false
+				if _, ok := a["value"]; ok {
+					optHasV = true
+				}
+				_, optSel = a["selected"]
+				optText.Reset()
+			}
+		case "textarea":
+			if closing {
+				if inTextA && textAIdx >= 0 {
+					form.Fields[textAIdx].Value = html.UnescapeString(textA.String())
+				}
+				inTextA = false
+			} else if a["name"] != "" {
+				addField(Field{Name: a["name"], Type: "textarea", id: a["id"]})
+				inTextA, textAIdx = true, len(form.Fields)-1
+				textA.Reset()
+			}
+		}
+	}
+	closeForm()
+	p.Title = squash(title.String())
+	for fi := range p.Forms {
+		var fields []Field
+		groups := map[string]int{}
+		for k := range p.Forms[fi].Fields {
+			f := p.Forms[fi].Fields[k]
+			if f.own == "" && f.id != "" {
+				f.own = labelIDs[f.id]
+			}
+			if f.Type != "radio" {
+				f.Label = f.own
+				if f.Label == "" && f.Type != "hidden" {
+					f.Label = f.row
+				}
+				fields = append(fields, f)
+				continue
+			}
+			g, ok := groups[f.Name]
+			if !ok {
+				g = len(fields)
+				groups[f.Name] = g
+				fields = append(fields, Field{Name: f.Name, Type: "radio", Label: f.row})
+			}
+			fields[g].Options = append(fields[g].Options, Option{Value: f.Value, Label: f.own})
+			if f.Checked != nil && *f.Checked {
+				fields[g].Value = f.Value
+			}
+		}
+		p.Forms[fi].Fields = fields
+	}
+	return p
+}

modules/brother/cmd/brother/html_test.go

@@ -0,0 +1,123 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func fieldNamed(t *testing.T, p Page, name string) Field {
+	t.Helper()
+	for _, f := range p.Forms {
+		for _, fl := range f.Fields {
+			if fl.Name == name {
+				return fl
+			}
+		}
+	}
+	t.Fatalf("no field %s in %+v", name, p.Forms)
+	return Field{}
+}
+
+// 1530: a radio group is ONE field that answers the checked button's value, and every button is an option.
+func TestARadioGroupIsOneFieldAnsweringTheCheckedButton(t *testing.T) {
+	p := ParsePage([]byte(`<form><table><tr><th>Mode</th><td>
+<input type="radio" id="a" name="R" value="1"/><label for="a">Enabled</label>
+<input type="radio" id="b" name="R" value="0" checked="checked"/><label for="b">Disabled</label></td></tr></table></form>`))
+	if n := len(p.Forms[0].Fields); n != 1 {
+		t.Fatalf("%d fields, want the radio group as one: %+v", n, p.Forms[0].Fields)
+	}
+	f := fieldNamed(t, p, "R")
+	if f.Type != "radio" || f.Value != "0" || f.Label != "Mode" {
+		t.Errorf("group = %+v", f)
+	}
+	if len(f.Options) != 2 || f.Options[0] != (Option{Value: "1", Label: "Enabled"}) || f.Options[1] != (Option{Value: "0", Label: "Disabled"}) {
+		t.Errorf("options = %+v", f.Options)
+	}
+}
+
+// 1530: a checkbox answers whether it is checked, both ways.
+func TestACheckboxAnswersCheckedOrNot(t *testing.T) {
+	p := ParsePage([]byte(`<form><input type="checkbox" name="on" value="1" checked/><input type="checkbox" name="off" value="1"/></form>`))
+	on, off := fieldNamed(t, p, "on"), fieldNamed(t, p, "off")
+	if on.Checked == nil || !*on.Checked || off.Checked == nil || *off.Checked {
+		t.Errorf("on = %+v, off = %+v", on, off)
+	}
+	raw, _ := json.Marshal(off)
+	if !strings.Contains(string(raw), `"checked":false`) {
+		t.Errorf("an unchecked box says so in JSON: %s", raw)
+	}
+}
+
+// 1530: a select answers the selected option's value, else the first, with its options as value and text.
+func TestASelectAnswersTheSelectedOptionElseTheFirst(t *testing.T) {
+	p := ParsePage([]byte(`<form><select name="s"><option value="0">English</option><option value="3" selected>Deutsch</option></select>
+<select name="d"><option value="0">English</option><option value="3">Deutsch</option></select></form>`))
+	s, d := fieldNamed(t, p, "s"), fieldNamed(t, p, "d")
+	if s.Value != "3" || d.Value != "0" {
+		t.Errorf("selected %q, default %q", s.Value, d.Value)
+	}
+	if len(s.Options) != 2 || s.Options[1] != (Option{Value: "3", Text: "Deutsch"}) {
+		t.Errorf("options = %+v", s.Options)
+	}
+}
+
+// 1530: a field with no <label for> is labelled by its table row's first cell, or its <dt>.
+func TestAFieldIsLabelledByItsTableRow(t *testing.T) {
+	p := ParsePage([]byte(`<form><table><tr><td>Sleep time</td><td><input type="text" name="B1"/></td></tr></table>
+<dl><dt>Volume</dt><dd><input type="text" name="B2"/></dd></dl>
+<table><tr><td><label for="c">Own</label></td><td><input id="c" type="text" name="B3"/></td></tr></table></form>`))
+	for name, want := range map[string]string{"B1": "Sleep time", "B2": "Volume", "B3": "Own"} {
+		if got := fieldNamed(t, p, name).Label; got != want {
+			t.Errorf("%s label = %q, want %q", name, got, want)
+		}
+	}
+}
+
+// 1530: the scan-from-PC page, RECONSTRUCTED (its checked button and row heading are assumptions, only the form
+// actions, field names, option labels and values come from the live answer): only its structure is asserted.
+func TestTheReconstructedScanFromPCPageHasItsRadioGroupAsOneField(t *testing.T) {
+	p := ParsePage([]byte(adminFixture(t, "reconstructed-scanfrompc.html")))
+	if len(p.Forms) != 2 {
+		t.Fatalf("forms = %+v", p.Forms)
+	}
+	var radios []Field
+	for _, f := range p.Forms[1].Fields {
+		if f.Type == "radio" {
+			radios = append(radios, f)
+		}
+	}
+	if len(radios) != 1 || radios[0].Name != "B117d" || len(radios[0].Options) != 2 ||
+		radios[0].Options[0] != (Option{Value: "1", Label: "Enabled"}) || radios[0].Options[1] != (Option{Value: "0", Label: "Disabled"}) {
+		t.Errorf("radios = %+v", radios)
+	}
+	first := p.Forms[0]
+	if first.Action != "/home/status.html" || len(first.Fields) != 2 || first.Fields[0].Name != "CSRFToken" || first.Fields[1].Name != "B1892" {
+		t.Errorf("first form = %+v", first)
+	}
+}
+
+// 1530: a radio group with no checked button answers value "" and both options.
+func TestARadioGroupWithNothingCheckedAnswersNoValue(t *testing.T) {
+	p := ParsePage([]byte(`<form><input type="radio" id="a" name="R" value="1"/><label for="a">On</label><input type="radio" id="b" name="R" value="0"/><label for="b">Off</label></form>`))
+	f := fieldNamed(t, p, "R")
+	if f.Value != "" || len(f.Options) != 2 {
+		t.Errorf("group = %+v", f)
+	}
+}
+
+// 1530: a label is never guessed from text that is not the field's: the text after a radio button, the text of
+// another form, a menu link, a layout table's menu. The label is empty instead.
+func TestAFieldIsNotLabelledByOtherTexts(t *testing.T) {
+	for name, c := range map[string]struct{ html, field string }{
+		"after a radio group": {`<form><input type="radio" name="R" value="1"/>Off<input type="text" name="X"/></form>`, "X"},
+		"after a label":       {`<form><input type="radio" id="a" name="R" value="1"/><label for="a">Disabled</label><input type="text" name="X"/></form>`, "X"},
+		"in a second form":    {`<form><input type="radio" name="R" value="1"/>Disabled</form><form><input type="text" name="X"/></form>`, "X"},
+		"after a menu link":   {`<a href="/scan/scanfrompc.html">Scan from PC</a><form><input type="text" name="X"/></form>`, "X"},
+		"layout table menu":   {`<table><tr><td><a href="/a">Menu</a><a href="/b">Status</a></td><td><form><input type="text" name="X"/></form></td></tr></table>`, "X"},
+	} {
+		if got := fieldNamed(t, ParsePage([]byte(c.html)), c.field).Label; got != "" {
+			t.Errorf("%s: label = %q, want none", name, got)
+		}
+	}
+}

modules/brother/cmd/brother/internal/secret/secret.go

@@ -0,0 +1,30 @@
+// Package secret reads the module's own secret admin-password (novox/hq ADR 0283, ADR 0467 clause 4). It is
+// imported only by the admin process (adminproc.go), which runs as its own account, brother-admin, and alone
+// can open the file: never by the tools, which the operator account's tool runner serves and which must never
+// open a password file (novox/hq ADR 0436 §12). admin_boundary_test.go checks that.
+package secret
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// Read is the password in the file at path. A password not given yet (no file, or an empty one) is an error
+// that names the secret and says the operator gives it at the desk, and that nothing was contacted.
+func Read(path string) (string, error) {
+	if path == "" {
+		return "", fmt.Errorf("BROTHER_ADMIN_PASSWORD names no file: the module's secret admin-password does not reach the code")
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return "", fmt.Errorf("the secret admin-password cannot be read: %w", err)
+	}
+	pw := strings.TrimRight(string(raw), "\r\n")
+	if pw == "" {
+		return "", fmt.Errorf("the secret admin-password is not given: the printer's admin password waits for the operator, " +
+			"who gives it at their desk (ADR 0283)")
+	}
+	return pw, nil
+}

modules/brother/cmd/brother/internal/secret/secret_test.go

@@ -0,0 +1,27 @@
+package secret
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The password is the file's content without its trailing newline; no file or an empty one is "not given",
+// said by the secret's name; the password itself is never in an error.
+func TestReadGivesThePasswordOrSaysItIsNotGiven(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "admin-password.secret")
+	os.WriteFile(p, []byte("p4ss\n"), 0o600)
+	if pw, err := Read(p); err != nil || pw != "p4ss" {
+		t.Errorf("Read = %q, %v", pw, err)
+	}
+	for _, path := range []string{filepath.Join(dir, "none"), func() string { e := filepath.Join(dir, "e"); os.WriteFile(e, []byte("\r\n"), 0o600); return e }()} {
+		if _, err := Read(path); err == nil || !strings.Contains(err.Error(), "admin-password is not given") {
+			t.Errorf("Read(%s) error = %v", path, err)
+		}
+	}
+	if _, err := Read(""); err == nil || !strings.Contains(err.Error(), "BROTHER_ADMIN_PASSWORD") {
+		t.Errorf("Read(\"\") error = %v", err)
+	}
+}

modules/brother/cmd/brother/ipp.go

@@ -0,0 +1,345 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/binary"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// IPP (RFC 8010, RFC 8011) by hand: Get-Printer-Attributes and Print-Job, neither of which needs a login.
+
+const (
+	ippGetPrinterAttributes = 0x000B
+	ippPrintJob             = 0x0002
+	ippOperation            = 0x01
+	ippJob                  = 0x02
+	ippEnd                  = 0x03
+	ippInteger              = 0x21
+	ippEnum                 = 0x23
+	ippNameNoLang           = 0x42
+	ippKeyword              = 0x44
+	ippURItag               = 0x45
+	ippMimeType             = 0x49
+	ippCharset              = 0x47
+	ippLanguage             = 0x48
+)
+
+// statusAttributes are the attributes printer.status asks for.
+var statusAttributes = []string{
+	"printer-state", "printer-state-reasons", "marker-names", "marker-levels", "marker-colors", "printer-make-and-model",
+}
+
+// ippURL is where a printer's IPP service answers: the port IPP is registered on, and the path the printer
+// serves (CUPS shows ipp://<printer>/ipp/port1). A variable so a test can put a server of its own in its place.
+var ippURL = func(host string) string {
+	h := host
+	if hh, _, err := net.SplitHostPort(host); err == nil {
+		h = hh
+	}
+	if strings.Contains(h, ":") {
+		h = "[" + h + "]"
+	}
+	return "http://" + h + ":631/ipp/port1"
+}
+
+// ippPrinterURI is the printer-uri operation attribute for a host.
+func ippPrinterURI(host string) string {
+	h := host
+	if hh, _, err := net.SplitHostPort(host); err == nil {
+		h = hh
+	}
+	return "ipp://" + h + "/ipp/port1"
+}
+
+func appendAttr(b []byte, tag byte, name, value string) []byte {
+	b = append(b, tag)
+	b = binary.BigEndian.AppendUint16(b, uint16(len(name)))
+	b = append(b, name...)
+	b = binary.BigEndian.AppendUint16(b, uint16(len(value)))
+	return append(b, value...)
+}
+
+// EncodeGetPrinterAttributes is the request: IPP 2.0, operation 0x000B, request id 1, the operation attributes
+// RFC 8011 requires first (charset, natural language, printer-uri), and the attributes asked for.
+func EncodeGetPrinterAttributes(printerURI string, requested []string) []byte {
+	b := []byte{0x02, 0x00, 0x00, byte(ippGetPrinterAttributes), 0, 0, 0, 1, ippOperation}
+	b = appendAttr(b, ippCharset, "attributes-charset", "utf-8")
+	b = appendAttr(b, ippLanguage, "attributes-natural-language", "en")
+	b = appendAttr(b, ippURItag, "printer-uri", printerURI)
+	for i, r := range requested {
+		name := ""
+		if i == 0 {
+			name = "requested-attributes"
+		}
+		b = appendAttr(b, ippKeyword, name, r)
+	}
+	return append(b, ippEnd)
+}
+
+// IPPValue is one value of an attribute: an integer or enum, or text.
+type IPPValue struct {
+	Tag     byte
+	Integer int
+	Text    string
+}
+
+// IPPAnswer is a decoded response: its status code and its attributes by name, each with its values in order.
+type IPPAnswer struct {
+	Status     int
+	Attributes map[string][]IPPValue
+}
+
+// DecodeIPP reads a response. It reads only what Get-Printer-Attributes answers hold: groups of attributes of
+// integers, enums and strings, whose additional values have an empty name.
+func DecodeIPP(b []byte) (IPPAnswer, error) {
+	a, _, err := decodeIPP(b)
+	return a, err
+}
+
+// decodeIPP is DecodeIPP and the offset after the end-of-attributes tag, where a request's document begins.
+func decodeIPP(b []byte) (IPPAnswer, int, error) {
+	a := IPPAnswer{Attributes: map[string][]IPPValue{}}
+	if len(b) < 9 {
+		return a, 0, fmt.Errorf("the IPP answer is %d bytes, shorter than its header", len(b))
+	}
+	a.Status = int(binary.BigEndian.Uint16(b[2:4]))
+	i := 8
+	last := ""
+	for i < len(b) {
+		tag := b[i]
+		i++
+		if tag == ippEnd {
+			return a, i, nil
+		}
+		if tag <= 0x05 { // a group's start
+			last = ""
+			continue
+		}
+		if i+2 > len(b) {
+			return a, 0, fmt.Errorf("the IPP answer ends inside an attribute")
+		}
+		nl := int(binary.BigEndian.Uint16(b[i:]))
+		i += 2
+		if i+nl+2 > len(b) {
+			return a, 0, fmt.Errorf("the IPP answer ends inside an attribute name")
+		}
+		name := string(b[i : i+nl])
+		i += nl
+		vl := int(binary.BigEndian.Uint16(b[i:]))
+		i += 2
+		if i+vl > len(b) {
+			return a, 0, fmt.Errorf("the IPP answer ends inside the value of %q", name)
+		}
+		raw := b[i : i+vl]
+		i += vl
+		if name == "" {
+			name = last
+		}
+		last = name
+		v := IPPValue{Tag: tag}
+		if (tag == ippInteger || tag == ippEnum) && vl == 4 {
+			v.Integer = int(int32(binary.BigEndian.Uint32(raw)))
+		} else {
+			v.Text = string(raw)
+		}
+		a.Attributes[name] = append(a.Attributes[name], v)
+	}
+	return a, 0, fmt.Errorf("the IPP answer has no end-of-attributes tag")
+}
+
+func (a IPPAnswer) texts(name string) []string {
+	var out []string
+	for _, v := range a.Attributes[name] {
+		out = append(out, v.Text)
+	}
+	return out
+}
+
+// printerStates are the values RFC 8011 gives printer-state.
+var printerStates = map[int]string{3: "idle", 4: "processing", 5: "stopped"}
+
+// Marker is one consumable of the printer: a toner, a drum, a belt. A level below 0 is the standard's way
+// to say it is unknown (-1) or not reported (-2).
+type Marker struct {
+	Name  string `json:"name"`
+	Level int    `json:"level"`
+	Color string `json:"color,omitempty"`
+}
+
+// PrinterState is what printer.status reads over IPP.
+type PrinterState struct {
+	State        string   `json:"state"`
+	StateCode    int      `json:"state-code"`
+	Reasons      []string `json:"state-reasons"`
+	MakeAndModel string   `json:"make-and-model"`
+	Markers      []Marker `json:"markers"`
+}
+
+// State reads the answer into the printer's state; an answer whose status is not a success is an error.
+func (a IPPAnswer) State() (PrinterState, error) {
+	if a.Status >= 0x0100 {
+		return PrinterState{}, fmt.Errorf("the printer refused the IPP request with status 0x%04x", a.Status)
+	}
+	st := a.Attributes["printer-state"]
+	if len(st) == 0 {
+		return PrinterState{}, fmt.Errorf("the IPP answer holds no printer-state")
+	}
+	code := st[0].Integer
+	name, ok := printerStates[code]
+	if !ok {
+		name = fmt.Sprintf("unknown (%d)", code)
+	}
+	s := PrinterState{State: name, StateCode: code, Reasons: a.texts("printer-state-reasons"), Markers: []Marker{}}
+	if s.Reasons == nil {
+		s.Reasons = []string{}
+	}
+	if m := a.texts("printer-make-and-model"); len(m) > 0 {
+		s.MakeAndModel = m[0]
+	}
+	names, levels, colors := a.texts("marker-names"), a.Attributes["marker-levels"], a.texts("marker-colors")
+	for i, n := range names {
+		m := Marker{Name: n, Level: -1}
+		if i < len(levels) {
+			m.Level = levels[i].Integer
+		}
+		if i < len(colors) {
+			m.Color = colors[i]
+		}
+		s.Markers = append(s.Markers, m)
+	}
+	return s, nil
+}
+
+// PrinterStateOf asks the printer for its state over IPP. The printer is asked on its IPP port, not through the
+// pinned HTTPS client, and nothing secret is sent.
+func PrinterStateOf(ctx context.Context, host string) (PrinterState, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, ippURL(host),
+		bytes.NewReader(EncodeGetPrinterAttributes(ippPrinterURI(host), statusAttributes)))
+	if err != nil {
+		return PrinterState{}, err
+	}
+	req.Header.Set("Content-Type", "application/ipp")
+	c := &http.Client{Timeout: 15 * time.Second}
+	resp, err := c.Do(req)
+	if err != nil {
+		return PrinterState{}, fmt.Errorf("the printer's IPP service does not answer: %w", err)
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return PrinterState{}, fmt.Errorf("the printer's IPP answer cannot be read: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return PrinterState{}, fmt.Errorf("the printer's IPP service answered %s", resp.Status)
+	}
+	ans, err := DecodeIPP(body)
+	if err != nil {
+		return PrinterState{}, err
+	}
+	return ans.State()
+}
+
+// PrintOptions are what a Print-Job asks of the printer.
+type PrintOptions struct {
+	Format string // document-format, application/pdf or image/jpeg
+	Copies int
+	Sides  string
+	Media  string
+	Name   string // job-name
+}
+
+// SniffFormat is the document format of the bytes the printer accepts: PDF or JPEG, by their first bytes, and
+// otherwise an error.
+func SniffFormat(doc []byte) (format, ext string, err error) {
+	switch {
+	case bytes.HasPrefix(doc, []byte("%PDF-")):
+		return "application/pdf", "pdf", nil
+	case len(doc) > 3 && doc[0] == 0xFF && doc[1] == 0xD8 && doc[2] == 0xFF:
+		return "image/jpeg", "jpg", nil
+	}
+	return "", "", fmt.Errorf("the document is neither a PDF nor a JPEG: the printer is sent those two only")
+}
+
+// EncodePrintJob is the Print-Job request (RFC 8011 §4.2.1): the operation attributes in the order the standard
+// requires, the job's copies, sides and media, and the document after the end-of-attributes tag.
+func EncodePrintJob(printerURI string, o PrintOptions, doc []byte) []byte {
+	b := []byte{0x02, 0x00, 0x00, byte(ippPrintJob), 0, 0, 0, 1, ippOperation}
+	b = appendAttr(b, ippCharset, "attributes-charset", "utf-8")
+	b = appendAttr(b, ippLanguage, "attributes-natural-language", "en")
+	b = appendAttr(b, ippURItag, "printer-uri", printerURI)
+	b = appendAttr(b, ippNameNoLang, "requesting-user-name", "brother")
+	b = appendAttr(b, ippNameNoLang, "job-name", o.Name)
+	b = appendAttr(b, ippMimeType, "document-format", o.Format)
+	b = append(b, ippJob)
+	b = appendAttr(b, ippInteger, "copies", string(binary.BigEndian.AppendUint32(nil, uint32(o.Copies))))
+	b = appendAttr(b, ippKeyword, "sides", o.Sides)
+	b = appendAttr(b, ippKeyword, "media", o.Media)
+	b = append(b, ippEnd)
+	return append(b, doc...)
+}
+
+// jobStates are the values RFC 8011 gives job-state.
+var jobStates = map[int]string{3: "pending", 4: "pending-held", 5: "processing", 6: "processing-stopped", 7: "canceled", 8: "aborted", 9: "completed"}
+
+// PrintResult is what a Print-Job answered: the job's id and state.
+type PrintResult struct {
+	JobID     int      `json:"job-id"`
+	State     string   `json:"job-state"`
+	StateCode int      `json:"job-state-code"`
+	Reasons   []string `json:"job-state-reasons"`
+}
+
+// PrintResult reads a Print-Job answer; a failing status is an error naming it.
+func (a IPPAnswer) PrintResult() (PrintResult, error) {
+	if a.Status >= 0x0100 {
+		return PrintResult{}, fmt.Errorf("the printer refused the print job with IPP status 0x%04x", a.Status)
+	}
+	id := a.Attributes["job-id"]
+	if len(id) == 0 {
+		return PrintResult{}, fmt.Errorf("the printer's answer to the print job names no job-id")
+	}
+	r := PrintResult{JobID: id[0].Integer, Reasons: a.texts("job-state-reasons")}
+	if r.Reasons == nil {
+		r.Reasons = []string{}
+	}
+	if st := a.Attributes["job-state"]; len(st) > 0 {
+		r.StateCode = st[0].Integer
+		r.State = jobStates[r.StateCode]
+		if r.State == "" {
+			r.State = fmt.Sprintf("unknown (%d)", r.StateCode)
+		}
+	}
+	return r, nil
+}
+
+// PrintJob sends the document to the printer's IPP service as a Print-Job, and answers the job's id and state.
+func PrintJob(ctx context.Context, host string, o PrintOptions, doc []byte) (PrintResult, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, ippURL(host), bytes.NewReader(EncodePrintJob(ippPrinterURI(host), o, doc)))
+	if err != nil {
+		return PrintResult{}, err
+	}
+	req.Header.Set("Content-Type", "application/ipp")
+	resp, err := (&http.Client{Timeout: 2 * time.Minute}).Do(req)
+	if err != nil {
+		return PrintResult{}, fmt.Errorf("the printer's IPP service does not answer: %w", err)
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return PrintResult{}, fmt.Errorf("the printer's IPP answer cannot be read: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return PrintResult{}, fmt.Errorf("the printer's IPP service answered %s", resp.Status)
+	}
+	ans, err := DecodeIPP(body)
+	if err != nil {
+		return PrintResult{}, err
+	}
+	return ans.PrintResult()
+}

modules/brother/cmd/brother/ipp_test.go

@@ -0,0 +1,143 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+func ippFixture(t *testing.T, name string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("testdata", "ipp", name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}
+
+// fakeIPP replays the captured Get-Printer-Attributes answer (testdata/ipp, 2026-10-20) and records what it
+// was sent. It stands in for the printer's port 631: no test reaches a real printer.
+func fakeIPP(t *testing.T, answer []byte) (url string, got *[]byte) {
+	t.Helper()
+	var sent []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		sent, _ = io.ReadAll(r.Body)
+		if r.Header.Get("Content-Type") != "application/ipp" {
+			http.Error(w, "not ipp", http.StatusUnsupportedMediaType)
+			return
+		}
+		w.Header().Set("Content-Type", "application/ipp")
+		w.Write(answer)
+	}))
+	t.Cleanup(srv.Close)
+	return srv.URL, &sent
+}
+
+// 1453/AC5: the request the module encodes is byte for byte the captured one the printer answered.
+func TestTheIPPRequestIsTheCapturedOne(t *testing.T) {
+	got := EncodeGetPrinterAttributes(ippPrinterURI("192.0.2.10"), statusAttributes)
+	if want := ippFixture(t, "get-printer-attributes.request"); !bytes.Equal(got, want) {
+		t.Errorf("request =\n%x\nwant\n%x", got, want)
+	}
+}
+
+// 1453/AC5: the captured IPP answer decodes to the printer's state, its reasons and its marker levels.
+func TestTheCapturedIPPAnswerDecodes(t *testing.T) {
+	ans, err := DecodeIPP(ippFixture(t, "get-printer-attributes.answer"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	st, err := ans.State()
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := PrinterState{State: "idle", StateCode: 3, Reasons: []string{"toner-low-warning"},
+		MakeAndModel: "Brother MFC-L8390CDW series",
+		Markers:      []Marker{{"BK", 40, "#000000"}, {"C", 10, "#00FFFF"}, {"M", 0, "#FF00FF"}, {"Y", 100, "#FFFF00"}}}
+	if !reflect.DeepEqual(st, want) {
+		t.Errorf("state = %+v\nwant %+v", st, want)
+	}
+}
+
+// 1453/AC5: an answer cut short, or one with a failing status, is an error and not a state.
+func TestABrokenIPPAnswerIsAnError(t *testing.T) {
+	good := ippFixture(t, "get-printer-attributes.answer")
+	if _, err := DecodeIPP(good[:len(good)-20]); err == nil {
+		t.Errorf("a truncated answer decoded")
+	}
+	refused := append([]byte{}, good...)
+	refused[2], refused[3] = 0x04, 0x00
+	ans, err := DecodeIPP(refused)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ans.State(); err == nil || !strings.Contains(err.Error(), "0x0400") {
+		t.Errorf("error = %v", err)
+	}
+}
+
+// 1453/AC5: printer.status gives the IPP state and the eSCL state, replayed from the captures, and sends the
+// captured request.
+func TestPrinterStatusToolGivesTheIPPAndESCLState(t *testing.T) {
+	url, sent := fakeIPP(t, ippFixture(t, "get-printer-attributes.answer"))
+	old := ippURL
+	ippURL = func(string) string { return url }
+	t.Cleanup(func() { ippURL = old })
+	f := newFakeScanner(t, nil)
+	tl := tools(settingsFile(t, `{"printer":"192.0.2.10","scanner":"`+f.base()+`"}`), time.Now)
+	got, err := tool(t, tl, "printer.status").Run(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := got.(map[string]any)
+	if m["answers"] != true || m["state"] != "idle" || m["make-and-model"] != "Brother MFC-L8390CDW series" {
+		t.Errorf("answer = %v", m)
+	}
+	if r := m["state-reasons"].([]string); !reflect.DeepEqual(r, []string{"toner-low-warning"}) {
+		t.Errorf("reasons = %v", r)
+	}
+	if mk := m["markers"].([]Marker); len(mk) != 4 || mk[0] != (Marker{"BK", 40, "#000000"}) {
+		t.Errorf("markers = %v", mk)
+	}
+	if sc := m["scanner"].(map[string]any); sc["answers"] != true || sc["state"] != "Idle" || sc["adf-state"] != "ScannerAdfEmpty" {
+		t.Errorf("scanner = %v", sc)
+	}
+	if !bytes.Equal(*sent, ippFixture(t, "get-printer-attributes.request")) {
+		t.Errorf("the printer was sent %x", *sent)
+	}
+}
+
+// 1453/AC4 and AC5: a part that does not answer is answers false with why, the other part is still given; an
+// unset printer or scanner is said by name and nothing is contacted.
+func TestPrinterStatusSaysWhatDoesNotAnswerAndWhatIsUnset(t *testing.T) {
+	old := ippURL
+	ippURL = func(string) string { return "http://127.0.0.1:1/ipp/port1" }
+	t.Cleanup(func() { ippURL = old })
+	f := newFakeScanner(t, nil)
+	tl := tools(settingsFile(t, `{"printer":"192.0.2.10","scanner":"`+f.base()+`"}`), time.Now)
+	got, err := tool(t, tl, "printer.status").Run(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := got.(map[string]any)
+	if m["answers"] != false || m["why"] == nil || m["scanner"].(map[string]any)["answers"] != true {
+		t.Errorf("answer = %v", m)
+	}
+	for _, c := range []struct{ js, want string }{
+		{`{"scanner":"` + f.base() + `"}`, "printer is not set"},
+		{`{"printer":"192.0.2.10"}`, "scanner is not set"},
+		{`{}`, "printer and scanner"},
+	} {
+		tl := tools(settingsFile(t, c.js), time.Now)
+		if _, err := tool(t, tl, "printer.status").Run(nil); err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s: error = %v, want %q", c.js, err, c.want)
+		}
+	}
+}

modules/brother/cmd/brother/main.go

@@ -0,0 +1,410 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	if len(os.Args) > 1 && os.Args[1] == "device" {
+		os.Exit(device())
+	}
+	if len(os.Args) > 1 && os.Args[1] == "watch" {
+		os.Exit(watch())
+	}
+	if err := stdio.Serve("", tools(os.Getenv("BROTHER_SETTINGS"), time.Now)); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+// watch is `brother watch`: the process that carries the tool check brother_health beside the device process's unit
+// check, as fail2ban's watch does (ADR 0240: a tool check is only beside a check the module does not run itself).
+// It does nothing itself; the node-engine asks the tool, and this stays up until it is stopped.
+func watch() int {
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	fmt.Fprintln(os.Stderr, "[brother] watch is up; the node-engine asks brother_health")
+	<-ctx.Done()
+	return 0
+}
+
+// intArg reads a whole number out of a tool's arguments: a JSON number, which arrives as a float64.
+func intArg(args map[string]any, name string) (int, error) {
+	v, ok := args[name]
+	if !ok {
+		return 0, nil
+	}
+	switch n := v.(type) {
+	case float64:
+		if n != float64(int(n)) {
+			return 0, fmt.Errorf("%s is a whole number", name)
+		}
+		return int(n), nil
+	case int:
+		return n, nil
+	}
+	return 0, fmt.Errorf("%s is a whole number", name)
+}
+
+func strArg(args map[string]any, name string) (string, error) {
+	v, ok := args[name]
+	if !ok {
+		return "", nil
+	}
+	s, isStr := v.(string)
+	if !isStr {
+		return "", fmt.Errorf("%s is a string", name)
+	}
+	return s, nil
+}
+
+// boolArgs reads the two flags printer.settings takes: links and hidden.
+func boolArgs(args map[string]any) (links, hidden bool, err error) {
+	for name, dst := range map[string]*bool{"links": &links, "hidden": &hidden} {
+		if v, ok := args[name]; ok {
+			b, isBool := v.(bool)
+			if !isBool {
+				return false, false, fmt.Errorf("%s is true or false", name)
+			}
+			*dst = b
+		}
+	}
+	return links, hidden, nil
+}
+
+// askFrom reads the arguments an ask takes out of a tool's.
+func askFrom(args map[string]any) (Ask, error) {
+	var a Ask
+	var err error
+	for name, dst := range map[string]*string{"page": &a.Page, "object": &a.Object, "upload": &a.Upload, "sha256": &a.SHA256,
+		"data": &a.Data, "sides": &a.Sides, "media": &a.Media} {
+		if *dst, err = strArg(args, name); err != nil {
+			return a, err
+		}
+	}
+	for name, dst := range map[string]*int{"part": &a.Part, "parts": &a.Parts, "copies": &a.Copies} {
+		if *dst, err = intArg(args, name); err != nil {
+			return a, err
+		}
+	}
+	return a, nil
+}
+
+// tools are the scanner seat's and the printer seat's verbs, served as <seat>.<verb> (ADR 0467 clause 2, ADR 0468).
+// The settings are read at each call, so a changed config value is the next call's. None opens a credential: what
+// needs one is asked of the device process.
+func tools(settingsFile string, now func() time.Time) []stdio.Tool {
+	jobs := NewJobs()
+	service := func() (*Service, error) {
+		s, err := LoadSettings(settingsFile)
+		if err != nil {
+			return nil, err
+		}
+		return &Service{Settings: s, Node: os.Getenv("MESH_NODE"), Now: now, Asks: askBus,
+			AnswerWait: answerWait, ScanWait: scanWait, AnswerPoll: answerPoll,
+			QuickWait: quickWait, FeederWait: feederWait, Jobs: jobs}, nil
+	}
+	// ask is a tool that reads its arguments, and answers what the service gives.
+	ask := func(run func(s *Service, ctx context.Context, a Ask) (map[string]any, error), bound time.Duration) func(map[string]any) (any, error) {
+		return func(args map[string]any) (any, error) {
+			a, err := askFrom(args)
+			if err != nil {
+				return nil, err
+			}
+			s, err := service()
+			if err != nil {
+				return nil, err
+			}
+			ctx, cancel := context.WithTimeout(context.Background(), bound)
+			defer cancel()
+			return run(s, ctx, a)
+		}
+	}
+	str := func(d string) map[string]any { return map[string]any{"type": "string", "description": d} }
+	num := func(d string) map[string]any { return map[string]any{"type": "integer", "description": d} }
+	return []stdio.Tool{
+		{
+			Name: "printer.upload",
+			Description: "Send one part of a document to the device process, to be printed later (printer.print with the upload id). " +
+				"Cut the document into parts of at most 700 KiB (700 KiB is the limit), number them from 1, and send each with the " +
+				"whole document's SHA-256. When the last part has come and the joined SHA-256 matches, the document is stored as " +
+				"uploads/<upload>.pdf or .jpg and the answer says complete; a wrong SHA-256 stores nothing. PDF and JPEG only.",
+			Input: map[string]any{"type": "object", "required": []string{"upload", "part", "parts", "sha256", "data"}, "properties": map[string]any{
+				"upload": str("an id of your choosing: letters, digits, - and _, at most 64"),
+				"part":   num("this part's number, from 1"),
+				"parts":  num("how many parts the document has"),
+				"sha256": str("the whole document's SHA-256, lower-case hex"),
+				"data":   str("this part's bytes, base64"),
+			}},
+			Run: ask(func(s *Service, ctx context.Context, a Ask) (map[string]any, error) { return s.PrinterUpload(ctx, a) }, 2*time.Minute),
+		},
+		{
+			Name: "printer.print",
+			Description: "Print a document on the printer: a file under the home folder of the account the tool runs as, on the machine it runs on (path: reads it, uploads it in parts " +
+				"and prints it, in one call), a scan kept in the bucket (object), or a completed upload (upload; for a module that sends " +
+				"bytes over the bus). Only PDF and JPEG, told by the file's bytes and not its name. The device " +
+				"process sends it as an IPP Print-Job in its own format and answers the job's id and state (with path, the upload id and the size).",
+			Input: map[string]any{"type": "object", "properties": map[string]any{
+				"path":   str("an absolute path of a PDF or JPEG file under the tool account's home folder (symbolic links are resolved and the real path must lie there too; any other path is refused in one fixed way)"),
+				"object": str("a scan's key, as scan.added names it"),
+				"upload": str("a completed upload's id"),
+				"copies": num("1 to 99 (default 1)"),
+				"sides":  str("one-sided (default), two-sided-long-edge or two-sided-short-edge"),
+				"media":  str("the paper's size name (default " + DefaultMedia + ")"),
+			}},
+			Run: func(args map[string]any) (any, error) {
+				path, err := strArg(args, "path")
+				if err != nil {
+					return nil, err
+				}
+				a, err := askFrom(args)
+				if err != nil {
+					return nil, err
+				}
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				if path == "" {
+					ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+					defer cancel()
+					return s.PrinterPrint(ctx, a)
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), 15*time.Minute)
+				defer cancel()
+				return s.PrintFile(ctx, path, a)
+			},
+		},
+		{
+			Name: "scanner.document",
+			Description: "One part of a scan kept in the bucket, by the key scan.added names (object): answers part, parts (how many), " +
+				"size, sha256 (of the whole document) and data (this part, base64). Join the parts and check the SHA-256.",
+			Input: map[string]any{"type": "object", "required": []string{"object", "part"}, "properties": map[string]any{
+				"object": str("the scan's key"),
+				"part":   num("the part's number, from 1"),
+			}},
+			Run: ask(func(s *Service, ctx context.Context, a Ask) (map[string]any, error) {
+				return s.ScanDocument(ctx, a.Object, a.Part)
+			}, 2*time.Minute),
+		},
+		{
+			Name: "printer.status",
+			Description: "The printer's state without a login: over IPP its state (idle, processing or stopped), its state " +
+				"reasons (such as toner-low-warning), its toner and other markers with their levels in percent (below 0 " +
+				"is unknown), and over eSCL the scanner's state and its document feeder's. A part that does not answer " +
+				"is said as answers false with why. Read-only.",
+			Run: func(map[string]any) (any, error) {
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+				defer cancel()
+				return s.PrinterStatus(ctx)
+			},
+		},
+		{
+			Name: "printer.settings",
+			Description: "Read one page of the printer's admin site, read-only: the module's device process logs in with the " +
+				"secret admin-password (the operator's; it trusts the printer's pinned certificate alone), gets the page and logs " +
+				"out; this tool asks it and waits up to a minute for its answer. Answers the " +
+				"page's title and its forms with their fields, each answering its current value: a text, textarea or hidden " +
+				"field its value; a checkbox its value and checked (true or false); a select its selected option's value (the " +
+				"first when none is marked) and options (value, text); a radio group ONE field whose value is the checked button's " +
+				"and whose options are the buttons (value, label). A field's label is its <label for>, else the first cell of its " +
+				"table row or its <dt>. The page's links (href and text) are answered only with links: true (they repeat the " +
+				"printer's whole menu), hidden fields (CSRF token, page id) only with hidden: true. A " +
+				"password field's value is never given. It sends nothing but the login and the logout, and writes no " +
+				"setting of the printer.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"page":   map[string]any{"type": "string", "description": "a page of the admin site: a path starting with / and ending in .html (default /home/status.html)"},
+					"links":  map[string]any{"type": "boolean", "description": "also answer the page's links (default false)"},
+					"hidden": map[string]any{"type": "boolean", "description": "also answer the hidden fields (default false)"},
+				},
+			},
+			Run: func(args map[string]any) (any, error) {
+				page := ""
+				if v, ok := args["page"]; ok {
+					str, isStr := v.(string)
+					if !isStr {
+						return nil, fmt.Errorf("page is a string")
+					}
+					page = str
+				}
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+				defer cancel()
+				links, hidden, err := boolArgs(args)
+				if err != nil {
+					return nil, err
+				}
+				return s.PrinterSettings(ctx, page, links, hidden)
+			},
+		},
+		{
+			Name: "scanner.scan",
+			Description: "Scan with the configured network scanner, from the glass (source glass, the default: one page, cut out of " +
+				"the platen's white when crop is set) or from the document feeder (source feeder: every sheet in it, whole, up to 50; " +
+				"duplex true scans both sides of each sheet). The device process keeps the result as one PDF in the module's bucket " +
+				"under its sha256 (one page for the glass, one page per side for the feeder; with apart true and several documents lying apart on the glass, each is its own one-page PDF with its own object and scan.added) and says scan.added on the bus; this " +
+				"tool then fetches it and files it in the scan folder, in the background, so a scan is filed even when you stop waiting. " +
+				"A glass scan is waited for (up to three minutes). A feeder scan is waited for 25 seconds (the mesh console gives up on a " +
+				"call after 30): when it is not done by then the answer is {started: true, id, state: running}; the scan goes on (the " +
+				"device process lets a feeder run last 20 seconds a page, 3 to 30 minutes) and is filed when done, and " +
+				"scanner.scan {id} reads the outcome: state running, state done with the answer below, or state failed with why. " +
+				"The id is known to the tool process that started the scan; scan.added also announces it. " +
+				"Several pages of the glass in one PDF (a page turned over, a stapled document): document start scans page 1 and answers {document: <id>, pages: 1}; " +
+				"document <id> scans the next page; document <id> with finish true closes it into one PDF, filed once, answered like a scan. " +
+				"An open document that gets no page for 30 minutes is closed and filed so by the tool, and its pages are kept meanwhile in the bucket. Answers the event's body: " +
+				"the object's key, its size and sha256, the first page's real size in millimetres, the resolution the scanner really gave, " +
+				"whether it was cropped, the number of pages and the file's path; for apart true and several documents on the glass {documents: [that, for each], count} (a failure of one is in failed). The image itself is never sent. " +
+				"Duplex on the glass is refused.",
+			Input: map[string]any{"type": "object", "properties": map[string]any{
+				"source":   map[string]any{"type": "string", "enum": []string{"glass", "feeder"}, "description": "glass (default) or feeder"},
+				"id":       map[string]any{"type": "string", "description": "read the outcome of the scan with this id (from an answer that said started) instead of scanning"},
+				"document": map[string]any{"type": "string", "description": "glass only, a document of several pages in one PDF: start opens one and scans its first page; the id of an open document scans the next page into it"},
+				"finish":   map[string]any{"type": "boolean", "description": "with document: the id of an open document: close it into one PDF, filed once (nothing is scanned)"},
+				"duplex":   map[string]any{"type": "boolean", "description": "feeder only: scan both sides of each sheet (default false)"},
+				"apart":    map[string]any{"type": "boolean", "description": "glass only: several documents lying apart on the glass are each filed as their own PDF (default false: one scan of the glass)"},
+			}},
+			Run: func(args map[string]any) (any, error) {
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				apart := false
+				if v, ok := args["apart"]; ok {
+					if apart, ok = v.(bool); !ok {
+						return nil, fmt.Errorf("apart is true or false")
+					}
+				}
+				id, err := strArg(args, "id")
+				if err != nil {
+					return nil, err
+				}
+				if id != "" {
+					return s.ScanResult(id)
+				}
+				document, err := strArg(args, "document")
+				if err != nil {
+					return nil, err
+				}
+				finish := false
+				if v, ok := args["finish"]; ok {
+					if finish, ok = v.(bool); !ok {
+						return nil, fmt.Errorf("finish is true or false")
+					}
+				}
+				if document != "" || finish {
+					if document == "" {
+						return nil, fmt.Errorf("finish closes a document: name its id in document")
+					}
+					if v, _ := args["source"].(string); v == "feeder" {
+						return nil, fmt.Errorf("a document of several pages is scanned from the glass; the feeder takes the whole stack in one scan")
+					}
+					ctx, cancel := context.WithTimeout(context.Background(), scanWait+10*time.Minute)
+					defer cancel()
+					return s.ScanPage(ctx, document, finish)
+				}
+				source, err := strArg(args, "source")
+				if err != nil {
+					return nil, err
+				}
+				duplex := false
+				if v, ok := args["duplex"]; ok {
+					if duplex, ok = v.(bool); !ok {
+						return nil, fmt.Errorf("duplex is true or false")
+					}
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), feederWait+10*time.Minute)
+				defer cancel()
+				return s.ScanNow(ctx, source, duplex, apart)
+			},
+		},
+		{
+			Name: "brother_health",
+			Description: "The module's health, asked by the node-engine (novox/hq ADR 0240): the certificates the printer serves, one for each " +
+				"key type (ECDSA and RSA), read with no login and compared with the pinned printer-certificate list. Answers healthy, why, " +
+				"and what was served with each fingerprint and whether it is pinned. Not healthy when a certificate served is not pinned (the " +
+				"printer was reset or given new certificates): why names the new fingerprint, so the pin can be changed before the admin " +
+				"pages are needed. A printer that does not answer is healthy, with why saying nothing was compared. Read-only.",
+			Run: func(map[string]any) (any, error) {
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				// The node-engine asks this every minute, so it is also what brings back, after a restart of this
+				// process, the expiry of the documents left open in the bucket (issue 1538).
+				if s.Settings.Missing() == nil && jobs.tryRecover() {
+					go func() {
+						ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+						defer cancel()
+						if err := s.Recover(ctx); err != nil {
+							jobs.recoverFailed()
+						}
+					}()
+				}
+				if w, waits := CertWaits(s.Settings); waits {
+					return w, nil
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), certTotal+time.Second)
+				defer cancel()
+				return CheckCertificates(ctx, s.Settings.Printer, s.Settings.PrinterCertificate), nil
+			},
+		},
+		{
+			Name: "scanner.status",
+			Description: "Whether the configured scanner answers, and what it is doing: its state (Idle or Processing) " +
+				"and its document feeder's state. A scanner that does not answer is said as answers false with why. Read-only.",
+			Run: func(map[string]any) (any, error) {
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+				defer cancel()
+				return s.ScanStatus(ctx)
+			},
+		},
+		{
+			Name:        "scanner.list",
+			Description: "The newest scans filed in the scan folder, newest first, with their size and time. Read-only.",
+			Input: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"limit": map[string]any{"type": "integer", "description": "at most this many scans (default 20)"},
+				},
+			},
+			Run: func(args map[string]any) (any, error) {
+				limit := 20
+				if v, ok := args["limit"]; ok {
+					f, isNum := v.(float64)
+					if i, isInt := v.(int); isInt {
+						f, isNum = float64(i), true
+					}
+					if !isNum || f < 1 || f > 1000 || f != float64(int(f)) {
+						return nil, fmt.Errorf("limit is a whole number from 1 to 1000")
+					}
+					limit = int(f)
+				}
+				s, err := service()
+				if err != nil {
+					return nil, err
+				}
+				return s.ScanList(limit)
+			},
+		},
+	}
+}

modules/brother/cmd/brother/manifest_test.go

@@ -0,0 +1,411 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"reflect"
+	"regexp"
+	"slices"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type manifest struct {
+	Requires   []string                  `json:"requires"`
+	Binds      map[string]string         `json:"binds"`
+	Secrets    map[string]string         `json:"secrets"`
+	Emits      []string                  `json:"emits"`
+	OwnSecrets map[string]map[string]any `json:"own-secrets"`
+	Seats      []seat                    `json:"seats"`
+	Claims     []seat                    `json:"claims"`
+	Tools      []string                  `json:"tools"`
+	Config     map[string]map[string]any `json:"config"`
+	Resources  []map[string]any          `json:"resources"`
+	Build      struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
+}
+
+type seat struct {
+	Name   string   `json:"name"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("module.json: %v", err)
+	}
+	return m
+}
+
+// 1440/AC9: the scan folder is no manifest resource, because a directory's path cannot take a config value
+// (issue 1441, ADR 0464 clause 4): no resource's path names it, and no directory but the state one is declared.
+func TestTheScanFolderIsNoManifestResource(t *testing.T) {
+	m := readManifest(t)
+	for _, r := range m.Resources {
+		if p, _ := r["path"].(string); strings.Contains(p, "${config:") || strings.Contains(p, "${setting:") {
+			t.Errorf("resource %v puts a config value in a path, which composition does not fill", r["id"])
+		}
+		if r["type"] == "directory" && r["id"] != "state" {
+			t.Errorf("directory %v: the code makes the scan folder", r["id"])
+		}
+	}
+}
+
+// 1440/AC9: the event the code emits is the one the manifest declares, and the tools it serves are named.
+func TestTheManifestDeclaresWhatTheCodeServes(t *testing.T) {
+	m := readManifest(t)
+	// Declared in both places, as mesh-mail declares its sender's events: the module's own, and the device
+	// process's bus block (the controller refuses a process's emit the module does not declare as its own,
+	// ADR 0436 §1).
+	if !reflect.DeepEqual(m.Emits, []string{EventAdded}) {
+		t.Errorf("the module's own emits = %v, want [%s]", m.Emits, EventAdded)
+	}
+	bus, _ := resource(t, m, "device")["bus"].(map[string]any)
+	if !reflect.DeepEqual(bus["emits"], []any{EventAdded}) {
+		t.Errorf("the device process's bus emits = %v, want [%s]", bus["emits"], EventAdded)
+	}
+	var served []string
+	for _, tl := range tools("", nil) {
+		served = append(served, tl.Name)
+	}
+	got := append([]string{}, m.Tools...)
+	sort.Strings(got)
+	sort.Strings(served)
+	if !reflect.DeepEqual(got, served) {
+		t.Errorf("manifest tools = %v, the bundle serves %v", got, served)
+	}
+	// Every verb of a seat is a tool named <seat>.<verb>.
+	for _, st := range m.Claims {
+		for _, v := range st.Serves {
+			if !slices.Contains(served, st.Name+"."+v) {
+				t.Errorf("the seat %s serves %s, but no tool %s.%s is served", st.Name, v, st.Name, v)
+			}
+		}
+	}
+}
+
+// 1440/AC9: the config reaches the code as the one file, under the name the code reads, and every key the
+// code reads is declared, taken by the file and in its template, with the default the code lays under it.
+func TestTheConfigReachesTheCodeThroughItsSettingsFile(t *testing.T) {
+	m := readManifest(t)
+	keys := []string{"scanner", "scan-folder", "printer", "printer-certificate", "resolution", "color-mode", "crop"}
+	for _, k := range keys {
+		if _, ok := m.Config[k]; !ok {
+			t.Errorf("config does not declare %s", k)
+		}
+	}
+	if len(m.Config) != len(keys) {
+		t.Errorf("config declares %d keys, the code reads %d", len(m.Config), len(keys))
+	}
+	// The printer's pins and addresses are written into the file as they are given, and match what the
+	// code's own validators accept (ADR 0467 clause 3).
+	fp := regexp.MustCompile(m.Config["printer-certificate"]["pattern"].(string))
+	host := regexp.MustCompile(m.Config["printer"]["pattern"].(string))
+	if !fp.MatchString(strings.Repeat("0A:", 31)+"0A") || fp.MatchString("0a:0a") || !host.MatchString("192.0.2.10") || host.MatchString("a b/c") {
+		t.Errorf("the printer patterns do not say a host and a SHA-256 fingerprint")
+	}
+	var taken []any
+	for _, r := range m.Resources {
+		if r["id"] == "settings" {
+			taken, _ = r["takes-config"].([]any)
+		}
+	}
+	if len(taken) != len(keys) {
+		t.Errorf("the settings file takes %v", taken)
+	}
+	env := ""
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			env, _ = a["env"].(map[string]any)["BROTHER_SETTINGS"].(string)
+		}
+	}
+	if env != "${dir:state}/settings.json" {
+		t.Errorf("BROTHER_SETTINGS = %q", env)
+	}
+	raw, err := os.ReadFile(filepath.Join("..", "..", "files", "settings.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var tpl map[string]any
+	if err := json.Unmarshal(raw, &tpl); err != nil {
+		t.Fatal(err)
+	}
+	// What the template and the manifest default say is what LoadSettings falls back to.
+	d, err := LoadSettings(settingsFile(t, string(raw)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for k, want := range map[string]any{"resolution": float64(d.Resolution), "color-mode": d.ColorMode, "crop": d.Crop} {
+		if m.Config[k]["default"] != want || tpl[k] != want {
+			t.Errorf("%s: manifest default %v, template %v, code %v", k, m.Config[k]["default"], tpl[k], want)
+		}
+	}
+	for _, k := range []string{"scanner", "scan-folder", "printer", "printer-certificate"} {
+		if m.Config[k]["required"] != true || m.Config[k]["trusted"] != true {
+			t.Errorf("%s is the operator's: required and trusted", k)
+		}
+	}
+}
+
+// 1453/AC6: the manifest declares the scanner seat, held once for the mesh, and claims it, with the verbs
+// ADR 0467 clause 2 names; the module serves each verb as the tool <seat>.<verb>.
+func TestTheManifestDeclaresAndClaimsTheScannerAndPrinterSeats(t *testing.T) {
+	m := readManifest(t)
+	for _, want := range []seat{
+		{Name: "scanner", Scope: "mesh", Serves: []string{"scan", "status", "list", "document"}},
+		// restart is round 2 of issue 1453, and is not declared yet.
+		{Name: "printer", Scope: "mesh", Serves: []string{"status", "settings", "print", "upload"}},
+	} {
+		for what, got := range map[string][]seat{"seats": m.Seats, "claims": m.Claims} {
+			found := false
+			for _, s := range got {
+				if s.Name == want.Name {
+					found = true
+					if !reflect.DeepEqual(s, want) {
+						t.Errorf("%s: %s = %+v, want %+v", what, want.Name, s, want)
+					}
+				}
+			}
+			if !found {
+				t.Errorf("%s does not hold the %s seat", what, want.Name)
+			}
+		}
+	}
+}
+
+// 1453/AC6 (issue 1446): the three preferences are not trusted, so a person's own setting is not refused.
+func TestThePreferencesAreNotTrusted(t *testing.T) {
+	m := readManifest(t)
+	for _, k := range []string{"resolution", "color-mode", "crop"} {
+		if v, ok := m.Config[k]["trusted"]; !ok || v != false {
+			t.Errorf("%s: trusted = %v, want false", k, v)
+		}
+	}
+}
+
+// 1453/AC6: the scan module is gone from the catalogue.
+func TestTheScanModuleIsGone(t *testing.T) {
+	if _, err := os.Stat(filepath.Join("..", "..", "..", "scan")); !os.IsNotExist(err) {
+		t.Errorf("modules/scan still exists (err %v)", err)
+	}
+}
+
+// resource is the manifest's resource of this id.
+func resource(t *testing.T, m manifest, id string) map[string]any {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			return r
+		}
+	}
+	t.Fatalf("no resource %s", id)
+	return nil
+}
+
+// 1453/AC4 (ADR 0467 clause 4, ADR 0436 §1): the admin password is the module's own secret, issued by the
+// operator (never generated), and owned by an account the module makes, brother-device: the tools' runner
+// (the operator account) cannot read it, the device process (that account) can. The process's bus account is
+// the own secret broker-device, owned by the same account.
+func TestTheAdminPasswordIsTheOperatorsOwnSecretOwnedByTheAdminAccount(t *testing.T) {
+	m := readManifest(t)
+	s, ok := m.OwnSecrets["admin-password"]
+	if !ok {
+		t.Fatal("own-secrets does not declare admin-password")
+	}
+	if s["issued-by"] != "outside" {
+		t.Errorf("issued-by = %v, want outside: the mesh never generates the device's password", s["issued-by"])
+	}
+	if s["owner"] != "brother-device" {
+		t.Errorf("owner = %v, want brother-device (never root or ${machine:account}: ADR 0436 §1)", s["owner"])
+	}
+	if p, _ := s["prompt"].(string); p != "the admin password of the Brother printer" {
+		t.Errorf("prompt = %q", p)
+	}
+	if b := m.OwnSecrets["broker-device"]; b["owner"] != "brother-device" || b["path"] != "${dir:state}/broker-device.secret" {
+		t.Errorf("broker-device = %v", b)
+	}
+	acct := resource(t, m, "account")
+	if acct["type"] != "user" || acct["name"] != "brother-device" || acct["shell"] != "/usr/bin/nologin" {
+		t.Errorf("account = %v", acct)
+	}
+}
+
+// 1453 (ADR 0467 clause 4): the device process runs as brother-device with the bus access of ADR 0436 §7: it
+// consumes the work queue device-asks and writes the state device-answers, and is judged by its unit. The
+// tools' bundle is given no password file.
+func TestTheAdminProcessIsDeclaredAsMeshMailsSenderIs(t *testing.T) {
+	m := readManifest(t)
+	p := resource(t, m, "device")
+	if p["type"] != "process" || p["name"] != "brother-device" || p["user"] != "brother-device" || p["artifact"] != "tools" {
+		t.Errorf("process = %v", p)
+	}
+	if !reflect.DeepEqual(p["run"], []any{"./brother", "device"}) {
+		t.Errorf("run = %v", p["run"])
+	}
+	bus, _ := p["bus"].(map[string]any)
+	if !reflect.DeepEqual(bus["queues"], []any{"device-asks"}) || !reflect.DeepEqual(bus["state"], []any{"device-answers"}) {
+		t.Errorf("bus = %v", bus)
+	}
+	if h, _ := p["health"].(map[string]any); h["kind"] != "unit" {
+		t.Errorf("health = %v", p["health"])
+	}
+	env, _ := p["env"].(map[string]any)
+	want := map[string]any{
+		"BROTHER_SETTINGS":       "${dir:state}/settings.json",
+		"BROTHER_ADMIN_PASSWORD": m.OwnSecrets["admin-password"]["path"],
+		"BROTHER_BROKER":         m.OwnSecrets["broker-device"]["path"],
+		"BROTHER_STORE":          "${dir:state}/store.json",
+	}
+	if !reflect.DeepEqual(env, want) {
+		t.Errorf("env = %v, want %v", env, want)
+	}
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			if _, has := a["env"].(map[string]any)["BROTHER_ADMIN_PASSWORD"]; has {
+				t.Errorf("the tools' bundle is given the password file")
+			}
+		}
+	}
+	// The admin account reads the settings file and walks the state directory; neither holds a secret.
+	if r := resource(t, m, "settings"); r["mode"] != "0644" {
+		t.Errorf("settings mode = %v: the admin account must read it", r["mode"])
+	}
+	if r := resource(t, m, "state"); r["mode"] != "0711" {
+		t.Errorf("state mode = %v: the admin account must reach its files in it", r["mode"])
+	}
+	for _, r := range m.Resources {
+		if r["id"] != "device" {
+			if r["takes-config"] != nil {
+				for _, k := range r["takes-config"].([]any) {
+					if k == "admin-password" {
+						t.Errorf("the password is a config value")
+					}
+				}
+			}
+		}
+	}
+}
+
+// 1453 (ADR 0467 clause 4): the stream device-asks is a work queue like mesh-mail's mail-sends, and the
+// answers are a state that expires.
+func TestThePrinterAsksStreamIsAWorkQueue(t *testing.T) {
+	raw, _ := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	var m struct {
+		Streams []map[string]any `json:"streams"`
+		State   []any            `json:"state"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if len(m.Streams) != 1 {
+		t.Fatalf("streams = %v", m.Streams)
+	}
+	st := m.Streams[0]
+	if st["name"] != "device-asks" || st["retention"] != "work-queue" || st["max-deliveries"] != float64(3) ||
+		!reflect.DeepEqual(st["events"], []any{EventAsked}) {
+		t.Errorf("stream = %v", st)
+	}
+	if st["duplicates"] != float64(24) {
+		t.Errorf("the stream has no duplicates window like mail-sends': %v", st["duplicates"])
+	}
+	if st["max-age-days"] == nil || st["max-mib"] == nil {
+		t.Errorf("the stream is bounded: %v", st)
+	}
+	if len(m.State) != 1 || m.State[0].(map[string]any)["name"] != AnswersState || m.State[0].(map[string]any)["ttl-seconds"] == nil {
+		t.Errorf("state = %v", m.State)
+	}
+}
+
+// 1453/AC8 (ADR 0468 clause 2): the module requires an s3-bucket as mesh-mail does, and its facts and key are
+// written into store.json, a file only the device account can read; the tools' bundle is not told where it is.
+func TestTheBucketIsRequiredAndItsKeyIsOnlyTheDeviceAccounts(t *testing.T) {
+	m := readManifest(t)
+	if !reflect.DeepEqual(m.Requires, []string{"s3-bucket"}) {
+		t.Errorf("requires = %v", m.Requires)
+	}
+	if m.Binds["s3-bucket"] != "${dir:state}/store-binding.json" || m.Secrets["s3-bucket"] != "${dir:state}/store.secret" {
+		t.Errorf("binds %v, secrets %v", m.Binds, m.Secrets)
+	}
+	r := resource(t, m, "store")
+	if r["type"] != "file" || r["path"] != "${dir:state}/store.json" || r["mode"] != "0600" || r["owner"] != "brother-device" || r["template"] != "files/store.json" {
+		t.Errorf("store = %v", r)
+	}
+	mine, _ := os.ReadFile(filepath.Join("..", "..", "files", "store.json"))
+	theirs, err := os.ReadFile(filepath.Join("..", "..", "..", "mesh-mail", "files", "store.json"))
+	if err != nil || string(mine) != string(theirs) {
+		t.Errorf("files/store.json is not mesh-mail's (%v)", err)
+	}
+	p := resource(t, m, "device")
+	if env, _ := p["env"].(map[string]any); env["BROTHER_STORE"] != "${dir:state}/store.json" {
+		t.Errorf("the device process's BROTHER_STORE = %v", env["BROTHER_STORE"])
+	}
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "bundle" {
+			if _, has := a["env"].(map[string]any)["BROTHER_STORE"]; has {
+				t.Errorf("the tools' bundle is told where the bucket's key is")
+			}
+		}
+	}
+}
+
+// Issue 1472: mesh-config matches a config value against its pattern whole, as mesh-sdk's catalogue compiles it
+// (`^(?:<pattern>)$`, go/catalogue/config.go). Each value the operator gives on a real node passes, and a value
+// of the wrong form does not.
+func TestEachConfigPatternAdmitsARealValueWhole(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Config map[string]struct {
+			Pattern string `json:"pattern"`
+		} `json:"config"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	cases := map[string]struct{ good, bad string }{
+		"scanner":             {"http://192.0.2.10/eSCL", "192.0.2.10"},
+		"scan-folder":         {"/home/operator/Documents/Scans", "Documents/Scans"},
+		"printer":             {"192.0.2.10", "http://192.0.2.10"},
+		"printer-certificate": {"EA:B4:B7:0F:96:CD:A6:2B:61:53:2E:F0:A8:D6:9F:42:EA:9F:66:0A:82:5B:C2:43:0B:97:C5:9A:7A:B4:18:5B", "EAB4"},
+	}
+	for key, c := range cases {
+		p := m.Config[key].Pattern
+		if p == "" {
+			t.Errorf("%s declares no pattern", key)
+			continue
+		}
+		re := regexp.MustCompile(`^(?:` + p + `)$`)
+		if !re.MatchString(c.good) {
+			t.Errorf("%s's pattern %q refuses the real value %q", key, p, c.good)
+		}
+		if re.MatchString(c.bad) {
+			t.Errorf("%s's pattern %q admits %q", key, p, c.bad)
+		}
+	}
+}
+
+// 1510: the certificate check is a tool check on a process of its own beside the device process's unit check, as
+// fail2ban's watch is (ADR 0227 rule 8, ADR 0240: a tool check only beside a check of another kind).
+func TestTheCertificateCheckIsAToolCheckBesideTheUnitCheck(t *testing.T) {
+	m := readManifest(t)
+	w := resource(t, m, "watch")
+	h, _ := w["health"].(map[string]any)
+	if w["type"] != "process" || w["artifact"] != "tools" || h["kind"] != "tool" || h["tool"] != "brother_health" || !reflect.DeepEqual(w["run"], []any{"./brother", "watch"}) {
+		t.Errorf("watch = %v", w)
+	}
+	if !slices.Contains(m.Tools, "brother_health") {
+		t.Errorf("tools = %v", m.Tools)
+	}
+}

modules/brother/cmd/brother/objects.go

@@ -0,0 +1,270 @@
+package main
+
+// The module's bucket (novox/hq ADR 0468 clause 2): each scan's PDF kept once, by its SHA-256, and each upload
+// under uploads/, in the bucket the `minio` module provides this module through the `s3-bucket` provision. The
+// mesh writes the bucket's facts and its key into one file, store.json, which only the device process (account
+// brother-device) can read (BROTHER_STORE); this speaks S3 to it with the standard library alone, as mesh-mail's
+// store does (modules/mesh-mail/cmd/mesh-mail/objects.go): a HEAD, a PUT and a GET, each signed with AWS
+// Signature Version 4, path-style.
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"sort"
+	"strings"
+	"time"
+)
+
+// Objects is the module's bucket.
+type Objects interface {
+	// Bucket is the bucket's name, as an event names it.
+	Bucket() string
+	// Has says whether the key is kept.
+	Has(ctx context.Context, key string) (bool, error)
+	// Put keeps the bytes under the key.
+	Put(ctx context.Context, key, mediaType string, data []byte) error
+	// Get is the bytes kept under the key.
+	Get(ctx context.Context, key string) ([]byte, error)
+	// List is the keys kept that start with the prefix, in order (the first thousand).
+	List(ctx context.Context, prefix string) ([]string, error)
+	// Delete removes the key; a key not kept is not an error.
+	Delete(ctx context.Context, key string) error
+}
+
+// Store keeps the bytes under the key once: a key already kept is left as it is, since a key that names the
+// content (the SHA-256 of a scan) names the same bytes.
+func Store(ctx context.Context, o Objects, key, mediaType string, data []byte) error {
+	has, err := o.Has(ctx, key)
+	if err != nil {
+		return err
+	}
+	if has {
+		return nil
+	}
+	return o.Put(ctx, key, mediaType, data)
+}
+
+// StoreFacts is the file the mesh writes from the s3-bucket binding and its secret.
+type StoreFacts struct {
+	Scheme string `json:"scheme"`
+	At     string `json:"at"`
+	Port   string `json:"port"`
+	Bucket string `json:"bucket"`
+	Region string `json:"region"`
+	Key    string `json:"key"`
+	Secret string `json:"secret"`
+}
+
+// ReadStoreFacts reads the store's facts.
+func ReadStoreFacts(path string) (StoreFacts, error) {
+	var f StoreFacts
+	if path == "" {
+		return f, errors.New("the module was started without its store's facts (BROTHER_STORE)")
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return f, fmt.Errorf("the store's facts cannot be read: %w", err)
+	}
+	if err := json.Unmarshal(raw, &f); err != nil {
+		return f, fmt.Errorf("the store's facts are not the module's: %v", err)
+	}
+	if f.At == "" || f.Bucket == "" || f.Key == "" || f.Secret == "" {
+		return f, errors.New("the store's facts name no address, bucket or key")
+	}
+	if f.Scheme == "" {
+		f.Scheme = "http"
+	}
+	if f.Region == "" {
+		f.Region = "us-east-1"
+	}
+	return f, nil
+}
+
+// S3 is the module's bucket over S3.
+type S3 struct {
+	Endpoint string // scheme://host[:port]
+	Name     string
+	Region   string
+	Access   string
+	Secret   string
+	Client   *http.Client
+	Now      func() time.Time
+}
+
+// NewS3 is the store the facts name.
+func NewS3(f StoreFacts) *S3 {
+	host := f.At
+	if f.Port != "" {
+		host += ":" + f.Port
+	}
+	return &S3{Endpoint: f.Scheme + "://" + host, Name: f.Bucket, Region: f.Region, Access: f.Key, Secret: f.Secret,
+		Client: &http.Client{Timeout: 2 * time.Minute}, Now: time.Now}
+}
+
+func (s *S3) Bucket() string { return s.Name }
+
+func (s *S3) do(ctx context.Context, method, key, mediaType string, body []byte) (*http.Response, error) {
+	u, err := url.Parse(s.Endpoint + "/" + s.Name + "/" + key)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, method, u.String(), bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	if mediaType != "" {
+		req.Header.Set("Content-Type", mediaType)
+	}
+	req.ContentLength = int64(len(body))
+	Sign(req, body, s.Access, s.Secret, s.Region, s.Now().UTC())
+	return s.Client.Do(req)
+}
+
+func (s *S3) Has(ctx context.Context, key string) (bool, error) {
+	resp, err := s.do(ctx, http.MethodHead, key, "", nil)
+	if err != nil {
+		return false, fmt.Errorf("the module's bucket cannot be reached: %w", err)
+	}
+	resp.Body.Close()
+	switch resp.StatusCode {
+	case http.StatusOK:
+		return true, nil
+	case http.StatusNotFound:
+		return false, nil
+	}
+	return false, fmt.Errorf("the module's bucket answered %s to asking for %s", resp.Status, key)
+}
+
+func (s *S3) Put(ctx context.Context, key, mediaType string, data []byte) error {
+	resp, err := s.do(ctx, http.MethodPut, key, mediaType, data)
+	if err != nil {
+		return fmt.Errorf("the module's bucket cannot be reached: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 {
+		said, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return fmt.Errorf("the module's bucket refused %s: %s %s", key, resp.Status, strings.TrimSpace(string(said)))
+	}
+	return nil
+}
+
+func (s *S3) Get(ctx context.Context, key string) ([]byte, error) {
+	resp, err := s.do(ctx, http.MethodGet, key, "", nil)
+	if err != nil {
+		return nil, fmt.Errorf("the module's bucket cannot be reached: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("the module's bucket answered %s for %s", resp.Status, key)
+	}
+	return io.ReadAll(resp.Body)
+}
+
+func (s *S3) List(ctx context.Context, prefix string) ([]string, error) {
+	resp, err := s.do(ctx, http.MethodGet, "?list-type=2&prefix="+url.QueryEscape(prefix), "", nil)
+	if err != nil {
+		return nil, fmt.Errorf("the module's bucket cannot be reached: %w", err)
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("the module's bucket answered %s to listing %s", resp.Status, prefix)
+	}
+	var out struct {
+		Keys []string `xml:"Contents>Key"`
+	}
+	if err := xml.Unmarshal(body, &out); err != nil {
+		return nil, fmt.Errorf("the module's bucket listed %s in a form that cannot be read: %w", prefix, err)
+	}
+	return out.Keys, nil
+}
+
+func (s *S3) Delete(ctx context.Context, key string) error {
+	resp, err := s.do(ctx, http.MethodDelete, key, "", nil)
+	if err != nil {
+		return fmt.Errorf("the module's bucket cannot be reached: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 && resp.StatusCode != http.StatusNotFound {
+		return fmt.Errorf("the module's bucket refused to delete %s: %s", key, resp.Status)
+	}
+	return nil
+}
+
+// Sign signs a request with AWS Signature Version 4 for S3: every header it carries but the agent and the length is
+// signed, with the payload's hash.
+func Sign(req *http.Request, body []byte, access, secret, region string, now time.Time) {
+	payload := sha256.Sum256(body)
+	payloadHex := hex.EncodeToString(payload[:])
+	amzDate := now.Format("20060102T150405Z")
+	day := now.Format("20060102")
+	req.Header.Set("x-amz-date", amzDate)
+	req.Header.Set("x-amz-content-sha256", payloadHex)
+
+	headers := map[string]string{"host": req.URL.Host}
+	for k, v := range req.Header {
+		lk := strings.ToLower(k)
+		if lk == "user-agent" || lk == "content-length" || lk == "authorization" {
+			continue
+		}
+		headers[lk] = strings.TrimSpace(strings.Join(v, ","))
+	}
+	names := make([]string, 0, len(headers))
+	for k := range headers {
+		names = append(names, k)
+	}
+	sort.Strings(names)
+	var canonHeaders strings.Builder
+	for _, k := range names {
+		canonHeaders.WriteString(k + ":" + headers[k] + "\n")
+	}
+	signed := strings.Join(names, ";")
+	path := req.URL.EscapedPath()
+	if path == "" {
+		path = "/"
+	}
+	canonical := strings.Join([]string{req.Method, path, canonicalQuery(req.URL.Query()), canonHeaders.String(), signed, payloadHex}, "\n")
+	scope := day + "/" + region + "/s3/aws4_request"
+	sum := sha256.Sum256([]byte(canonical))
+	toSign := "AWS4-HMAC-SHA256\n" + amzDate + "\n" + scope + "\n" + hex.EncodeToString(sum[:])
+	key := hmacOf([]byte("AWS4"+secret), day)
+	key = hmacOf(key, region)
+	key = hmacOf(key, "s3")
+	key = hmacOf(key, "aws4_request")
+	sig := hex.EncodeToString(hmacOf(key, toSign))
+	req.Header.Set("Authorization", "AWS4-HMAC-SHA256 Credential="+access+"/"+scope+", SignedHeaders="+signed+", Signature="+sig)
+}
+
+func canonicalQuery(q url.Values) string {
+	keys := make([]string, 0, len(q))
+	for k := range q {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	var parts []string
+	for _, k := range keys {
+		vs := append([]string(nil), q[k]...)
+		sort.Strings(vs)
+		for _, v := range vs {
+			parts = append(parts, url.QueryEscape(k)+"="+strings.ReplaceAll(url.QueryEscape(v), "+", "%20"))
+		}
+	}
+	return strings.Join(parts, "&")
+}
+
+func hmacOf(key []byte, data string) []byte {
+	h := hmac.New(sha256.New, key)
+	h.Write([]byte(data))
+	return h.Sum(nil)
+}

modules/brother/cmd/brother/objects_test.go

@@ -0,0 +1,178 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// memObjects is the bucket in memory, for the tests of what the device process keeps.
+type memObjects struct {
+	mu   sync.Mutex
+	kept map[string][]byte
+	puts int
+}
+
+func newMemObjects() *memObjects { return &memObjects{kept: map[string][]byte{}} }
+
+func (m *memObjects) Bucket() string { return "brother-test" }
+
+func (m *memObjects) Has(_ context.Context, key string) (bool, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	_, ok := m.kept[key]
+	return ok, nil
+}
+
+func (m *memObjects) Put(_ context.Context, key, _ string, data []byte) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.kept[key] = append([]byte(nil), data...)
+	m.puts++
+	return nil
+}
+
+func (m *memObjects) Get(_ context.Context, key string) ([]byte, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	b, ok := m.kept[key]
+	if !ok {
+		return nil, fmt.Errorf("%s is not kept", key)
+	}
+	return b, nil
+}
+
+func (m *memObjects) List(_ context.Context, prefix string) ([]string, error) {
+	var out []string
+	for _, k := range m.keys() {
+		if strings.HasPrefix(k, prefix) {
+			out = append(out, k)
+		}
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+func (m *memObjects) Delete(_ context.Context, key string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.kept, key)
+	return nil
+}
+
+func (m *memObjects) keys() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var k []string
+	for key := range m.kept {
+		k = append(k, key)
+	}
+	return k
+}
+
+// 1453/AC8: the S3 client puts, heads and gets path-style under a Signature Version 4 header, and Store keeps
+// a key once.
+func TestTheBucketIsSpokenToPathStyleSignedAndKeptOnce(t *testing.T) {
+	var mu sync.Mutex
+	objects := map[string][]byte{}
+	var puts int
+	var auth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		defer mu.Unlock()
+		auth = r.Header.Get("Authorization")
+		if !strings.HasPrefix(r.URL.Path, "/scans/") {
+			http.Error(w, "path-style: /<bucket>/<key>", http.StatusBadRequest)
+			return
+		}
+		key := strings.TrimPrefix(r.URL.Path, "/scans/")
+		switch r.Method {
+		case http.MethodPut:
+			b, _ := io.ReadAll(r.Body)
+			objects[key] = b
+			puts++
+		case http.MethodHead, http.MethodGet:
+			b, ok := objects[key]
+			if !ok {
+				http.NotFound(w, r)
+				return
+			}
+			if r.Method == http.MethodGet {
+				w.Write(b)
+			}
+		}
+	}))
+	defer srv.Close()
+	host := strings.TrimPrefix(srv.URL, "http://")
+	at, port, _ := strings.Cut(host, ":")
+	s3 := NewS3(StoreFacts{Scheme: "http", At: at, Port: port, Bucket: "scans", Region: "us-east-1", Key: "AKID", Secret: "sek"})
+	ctx := context.Background()
+	for i := 0; i < 2; i++ {
+		if err := Store(ctx, s3, "abc.pdf", "application/pdf", []byte("%PDF-x")); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if puts != 1 {
+		t.Errorf("%d puts, want the one: a key is kept once", puts)
+	}
+	got, err := s3.Get(ctx, "abc.pdf")
+	if err != nil || string(got) != "%PDF-x" {
+		t.Errorf("Get = %q, %v", got, err)
+	}
+	if !strings.HasPrefix(auth, "AWS4-HMAC-SHA256 Credential=AKID/") || !strings.Contains(auth, "SignedHeaders=") || strings.Contains(auth, "sek") {
+		t.Errorf("Authorization = %q", auth)
+	}
+	if _, err := s3.Get(ctx, "none.pdf"); err == nil {
+		t.Errorf("a key not kept was got")
+	}
+}
+
+// 1453: the store's facts are read from store.json, and one that names no bucket or key is refused by name.
+func TestTheStoresFactsAreRead(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "store.json")
+	os.WriteFile(p, []byte(`{"at":"minio.example","port":"9000","bucket":"brother","key":"k","secret":"s"}`), 0o600)
+	f, err := ReadStoreFacts(p)
+	if err != nil || f.Scheme != "http" || f.Region != "us-east-1" || f.Bucket != "brother" {
+		t.Errorf("facts = %+v, %v", f, err)
+	}
+	os.WriteFile(p, []byte(`{"at":"x"}`), 0o600)
+	if _, err := ReadStoreFacts(p); err == nil || !strings.Contains(err.Error(), "bucket") {
+		t.Errorf("error = %v", err)
+	}
+	if _, err := ReadStoreFacts(""); err == nil || !strings.Contains(err.Error(), "BROTHER_STORE") {
+		t.Errorf("error = %v", err)
+	}
+}
+
+// 1538: the bucket lists keys by prefix (ListObjectsV2, signed, path-style) and deletes one.
+func TestTheBucketListsByPrefixAndDeletes(t *testing.T) {
+	var gotQuery, gotDelete string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.Method {
+		case http.MethodGet:
+			gotQuery = r.URL.RawQuery
+			w.Write([]byte(`<?xml version="1.0"?><ListBucketResult><Contents><Key>pending/a/manifest.json</Key></Contents><Contents><Key>pending/b/manifest.json</Key></Contents></ListBucketResult>`))
+		case http.MethodDelete:
+			gotDelete = r.URL.Path
+			w.WriteHeader(http.StatusNoContent)
+		}
+	}))
+	defer srv.Close()
+	at, port, _ := strings.Cut(strings.TrimPrefix(srv.URL, "http://"), ":")
+	s3 := NewS3(StoreFacts{Scheme: "http", At: at, Port: port, Bucket: "scans", Region: "us-east-1", Key: "AKID", Secret: "sek"})
+	keys, err := s3.List(context.Background(), "pending/")
+	if err != nil || len(keys) != 2 || keys[1] != "pending/b/manifest.json" || !strings.Contains(gotQuery, "prefix=pending%2F") || !strings.Contains(gotQuery, "list-type=2") {
+		t.Errorf("List = %v, %v (query %q)", keys, err, gotQuery)
+	}
+	if err := s3.Delete(context.Background(), "pending/a/001.jpg"); err != nil || gotDelete != "/scans/pending/a/001.jpg" {
+		t.Errorf("Delete: %v, %q", err, gotDelete)
+	}
+}

modules/brother/cmd/brother/parts.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+)
+
+// Documents cross the bus in parts (novox/hq ADR 0468 clause 3): the bus refuses a message over 1 MiB, and a
+// part travels base64-encoded inside a JSON message.
+const (
+	// PartSize is how large the parts this module cuts are, and MaxPart the most raw bytes a part may hold; a part
+	// of more is refused. They are one: 700 KiB, so that a part's base64 text (about 933 KB) and the message around
+	// it stay under the bus's 1 MiB. (ADR 0468 clause 3.)
+	PartSize = 700 << 10
+	MaxPart  = PartSize
+	// AnswerPartSize is the raw size of a part the device process answers in the state device-answers
+	// (scanner.document). The state refuses a value over 256 KiB (the mesh's cap on every bucket's value), and a
+	// part travels base64-encoded in JSON, so 128 KiB (about 175 KB written) fits with room to spare; a part of
+	// 700 KiB (about 933 KB) can only cross the bus as a message, never as a state value (issue 1535).
+	AnswerPartSize = 128 << 10
+	// StateMaxValue is the most a state value may hold.
+	StateMaxValue = 256 << 10
+	// MostAnswerParts bounds how many answer parts a document has (a 100 MiB document is the most).
+	MostAnswerParts = 800
+	// MostParts bounds how many parts one document has (a 100 MiB document is the most).
+	MostParts = 150
+)
+
+func sha256Hex(b []byte) string {
+	sum := sha256.Sum256(b)
+	return hex.EncodeToString(sum[:])
+}
+
+// partCount is how many parts of PartSize hold size bytes: at least one.
+func partCount(size int) int { return partsOf(size, PartSize) }
+
+// answerPartCount is how many parts of AnswerPartSize hold size bytes: at least one.
+func answerPartCount(size int) int { return partsOf(size, AnswerPartSize) }
+
+func partsOf(size, each int) int {
+	if size <= 0 {
+		return 1
+	}
+	return (size + each - 1) / each
+}
+
+// cutPart is part number part (counted from 1) of data, in parts of AnswerPartSize, and how many parts there are.
+func cutPart(data []byte, part int) ([]byte, int, error) {
+	return cutPartOf(data, part, AnswerPartSize)
+}
+
+func cutPartOf(data []byte, part, each int) ([]byte, int, error) {
+	n := partsOf(len(data), each)
+	if part < 1 || part > n {
+		return nil, n, fmt.Errorf("part %d is out of range: the document has parts 1 to %d", part, n)
+	}
+	lo := (part - 1) * each
+	hi := min(lo+each, len(data))
+	return data[lo:hi], n, nil
+}
+
+// joinParts is the parts in order as one document, once its SHA-256 is the one named.
+func joinParts(parts [][]byte, wantSHA string) ([]byte, error) {
+	var n int
+	for _, p := range parts {
+		n += len(p)
+	}
+	out := make([]byte, 0, n)
+	for _, p := range parts {
+		out = append(out, p...)
+	}
+	if got := sha256Hex(out); got != wantSHA {
+		return nil, fmt.Errorf("the joined parts' SHA-256 is %s, not the %s named: refused", got, wantSHA)
+	}
+	return out, nil
+}

modules/brother/cmd/brother/pdf.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"image/color"
+	"image/jpeg"
+	"strings"
+)
+
+// PDF writes a one-page PDF holding the JPEG as it is (DCTDecode), the page as large as the image really is:
+// pixels over dpi, in points (72 to the inch).
+func PDF(jpegBytes []byte, dpi int) ([]byte, error) {
+	return PDFPages([]PDFPage{{JPEG: jpegBytes, DPI: dpi}})
+}
+
+// PDFPage is one image and its own resolution.
+type PDFPage struct {
+	JPEG []byte
+	DPI  int
+}
+
+// PDFPages writes a PDF with one page for each image, in order, each as it is (DCTDecode) and as large as it really
+// is.
+func PDFPages(pages []PDFPage) ([]byte, error) {
+	if len(pages) == 0 {
+		return nil, fmt.Errorf("a PDF needs a page")
+	}
+	var b bytes.Buffer
+	var offsets []int
+	b.WriteString("%PDF-1.4\n%\xE2\xE3\xCF\xD3\n")
+	// Objects 1 and 2 are the catalog and the page tree; page i is objects 3+3i (page), 4+3i (image), 5+3i (content).
+	add := func(body string) {
+		offsets = append(offsets, b.Len())
+		fmt.Fprintf(&b, "%d 0 obj\n%s\nendobj\n", len(offsets), body)
+	}
+	kids := make([]string, len(pages))
+	for i := range pages {
+		kids[i] = fmt.Sprintf("%d 0 R", 3+3*i)
+	}
+	add("<< /Type /Catalog /Pages 2 0 R >>")
+	add(fmt.Sprintf("<< /Type /Pages /Kids [%s] /Count %d >>", strings.Join(kids, " "), len(pages)))
+	for i, pg := range pages {
+		if pg.DPI <= 0 {
+			return nil, fmt.Errorf("resolution %d dpi is no resolution", pg.DPI)
+		}
+		cfg, err := jpeg.DecodeConfig(bytes.NewReader(pg.JPEG))
+		if err != nil {
+			return nil, fmt.Errorf("the image of page %d cannot be read: %w", i+1, err)
+		}
+		space := "DeviceRGB"
+		if cfg.ColorModel == color.GrayModel {
+			space = "DeviceGray"
+		}
+		wpt := float64(cfg.Width) / float64(pg.DPI) * 72
+		hpt := float64(cfg.Height) / float64(pg.DPI) * 72
+		content := fmt.Sprintf("q %.2f 0 0 %.2f 0 0 cm /Im0 Do Q\n", wpt, hpt)
+		add(fmt.Sprintf("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 %.2f %.2f] /Resources << /XObject << /Im0 %d 0 R >> >> /Contents %d 0 R >>", wpt, hpt, 4+3*i, 5+3*i))
+		offsets = append(offsets, b.Len())
+		fmt.Fprintf(&b, "%d 0 obj\n<< /Type /XObject /Subtype /Image /Width %d /Height %d /ColorSpace /%s /BitsPerComponent 8 /Filter /DCTDecode /Length %d >>\nstream\n",
+			len(offsets), cfg.Width, cfg.Height, space, len(pg.JPEG))
+		b.Write(pg.JPEG)
+		b.WriteString("\nendstream\nendobj\n")
+		add(fmt.Sprintf("<< /Length %d >>\nstream\n%sendstream", len(content), content))
+	}
+	xref := b.Len()
+	fmt.Fprintf(&b, "xref\n0 %d\n0000000000 65535 f \n", len(offsets)+1)
+	for _, o := range offsets {
+		fmt.Fprintf(&b, "%010d 00000 n \n", o)
+	}
+	fmt.Fprintf(&b, "trailer\n<< /Size %d /Root 1 0 R >>\nstartxref\n%d\n%%%%EOF\n", len(offsets)+1, xref)
+	return b.Bytes(), nil
+}

modules/brother/cmd/brother/pin.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"crypto/sha256"
+	"crypto/tls"
+	"crypto/x509"
+	"fmt"
+	"strings"
+)
+
+// Fingerprint is the SHA-256 of a certificate's DER bytes, as upper-case hex pairs joined by colons: the
+// form the printer's own certificate page and the config value printer-certificate give (ADR 0467 clause 3).
+func Fingerprint(der []byte) string {
+	sum := sha256.Sum256(der)
+	parts := make([]string, len(sum))
+	for i, b := range sum {
+		parts[i] = fmt.Sprintf("%02X", b)
+	}
+	return strings.Join(parts, ":")
+}
+
+// pinList splits the config value printer-certificate into its fingerprints: one or more, separated by commas
+// with optional spaces, upper-cased. The printer serves two certificates for one name, an ECDSA one and an RSA
+// one, and which it serves depends on the client, so the operator pins both (issue 1503).
+func pinList(value string) []string {
+	var out []string
+	for _, p := range strings.Split(value, ",") {
+		if p = strings.ToUpper(strings.TrimSpace(p)); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// pinned is the check on the certificate a printer serves: the leaf's fingerprint must be one of those pinned,
+// and any other certificate is refused, with the served and every pinned fingerprint in the message. It runs in
+// the handshake, so a refused certificate is refused before one byte of a request (a password) is sent.
+func pinned(value string) func([][]byte, [][]*x509.Certificate) error {
+	want := pinList(value)
+	list := strings.Join(want, ", ")
+	return func(raw [][]byte, _ [][]*x509.Certificate) error {
+		if len(raw) == 0 {
+			return fmt.Errorf("the printer served no certificate; the pinned printer-certificate is %s", list)
+		}
+		got := Fingerprint(raw[0])
+		for _, w := range want {
+			if got == w {
+				return nil
+			}
+		}
+		return fmt.Errorf("the printer's certificate is %s, but the pinned printer-certificate is %s: refused", got, list)
+	}
+}
+
+// pinnedTLS is the TLS configuration for the printer's admin page: the printer's certificate is self-signed,
+// so no chain is verified; the pinned fingerprint is the whole of the trust (ADR 0467 clause 3).
+func pinnedTLS(fingerprint string) *tls.Config {
+	return &tls.Config{
+		MinVersion: tls.VersionTLS12,
+		// The chain is not verified because the pinned fingerprint is checked in its place, below.
+		InsecureSkipVerify:    true,
+		VerifyPeerCertificate: pinned(fingerprint),
+	}
+}

modules/brother/cmd/brother/pin_test.go

@@ -0,0 +1,105 @@
+package main
+
+import (
+	"context"
+	"encoding/pem"
+	"os"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// Captured from the printer 2026-10-20 (testdata/pin): it serves two self-signed certificates for one name, an
+// ECDSA one to a client offering ECDSA and an RSA one to a client offering RSA only (issue 1503).
+const (
+	printerECDSAPrint = "EA:B4:B7:0F:96:CD:A6:2B:61:53:2E:F0:A8:D6:9F:42:EA:9F:66:0A:82:5B:C2:43:0B:97:C5:9A:7A:B4:18:5B"
+	printerRSAPrint   = "7A:3D:E2:A4:1E:AB:A9:7B:E6:61:0A:C4:18:DD:68:FF:9B:A5:77:E8:02:7F:7E:F8:97:D0:3B:82:A2:89:7D:F4"
+)
+
+func capturedDER(t *testing.T, name string) []byte {
+	t.Helper()
+	raw, err := os.ReadFile("testdata/pin/" + name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := pem.Decode(raw)
+	if b == nil {
+		t.Fatalf("%s is not PEM", name)
+	}
+	return b.Bytes
+}
+
+// 1503/AC1: the two captured certificates have the two fingerprints, and a pin listing both accepts each.
+func TestThePrintersTwoCapturedCertificatesAreBothAcceptedByAPinListingBoth(t *testing.T) {
+	both := printerECDSAPrint + ", " + printerRSAPrint
+	for file, want := range map[string]string{"ecdsa.pem": printerECDSAPrint, "rsa.pem": printerRSAPrint} {
+		der := capturedDER(t, file)
+		if got := Fingerprint(der); got != want {
+			t.Fatalf("%s has fingerprint %s, want %s", file, got, want)
+		}
+		if err := pinned(both)([][]byte{der}, nil); err != nil {
+			t.Errorf("%s refused by a pin listing both: %v", file, err)
+		}
+	}
+}
+
+// 1503/AC1: a server presenting one certificate is accepted when the pin lists its fingerprint among two.
+func TestAPinListingTwoFingerprintsAcceptsTheCertificateTheServerPresents(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "hunter2")
+	a, err := NewAdmin(f.host(), printerECDSAPrint+","+f.print(), "hunter2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.Login(context.Background()); err != nil {
+		t.Fatalf("a pin listing the served certificate was refused: %v", err)
+	}
+}
+
+// 1503/AC2: a pin that lists only another certificate still refuses, and names every pinned fingerprint.
+func TestAPinListingOnlyOtherCertificatesStillRefuses(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "hunter2")
+	a, _ := NewAdmin(f.host(), printerECDSAPrint+" , "+printerRSAPrint, "hunter2")
+	err := a.Login(context.Background())
+	if err == nil {
+		t.Fatal("a certificate that is in no pinned fingerprint was accepted")
+	}
+	for _, want := range []string{f.print(), printerECDSAPrint, printerRSAPrint} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not name %s", err, want)
+		}
+	}
+	if len(f.requests) != 0 {
+		t.Errorf("the server was sent %v", f.requests)
+	}
+}
+
+// 1503/AC1: a single fingerprint is still a valid pin, in either case.
+func TestASingleFingerprintStillPins(t *testing.T) {
+	der := capturedDER(t, "rsa.pem")
+	for _, p := range []string{printerRSAPrint, strings.ToLower(printerRSAPrint), " " + printerRSAPrint + " "} {
+		if err := pinned(p)([][]byte{der}, nil); err != nil {
+			t.Errorf("pin %q refused: %v", p, err)
+		}
+	}
+	if err := pinned(printerECDSAPrint)([][]byte{der}, nil); err == nil {
+		t.Error("the other certificate's pin accepted the RSA certificate")
+	}
+}
+
+// 1503/AC3: the manifest's pattern takes one or more fingerprints, separated by commas and optional spaces, and
+// nothing else.
+func TestThePrinterCertificatePatternTakesACommaSeparatedList(t *testing.T) {
+	m := readManifest(t)
+	re := regexp.MustCompile(`^(?:` + m.Config["printer-certificate"]["pattern"].(string) + `)$`)
+	for _, ok := range []string{printerRSAPrint, printerECDSAPrint + "," + printerRSAPrint, printerECDSAPrint + ", " + printerRSAPrint} {
+		if !re.MatchString(ok) {
+			t.Errorf("pattern refuses %q", ok)
+		}
+	}
+	for _, bad := range []string{"", printerRSAPrint + ",", "," + printerRSAPrint, printerECDSAPrint + printerRSAPrint,
+		printerECDSAPrint + ",," + printerRSAPrint, printerECDSAPrint + ";" + printerRSAPrint, printerRSAPrint + ",EAB4", strings.ToLower(printerRSAPrint)} {
+		if re.MatchString(bad) {
+			t.Errorf("pattern admits %q", bad)
+		}
+	}
+}

modules/brother/cmd/brother/printer.go

@@ -0,0 +1,396 @@
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"slices"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// pagePattern is a page of the admin site a caller may ask for: an absolute path under the site ending in
+// .html, with no query, no dot-dot and no second slash at its start (which would name another host).
+var pagePattern = regexp.MustCompile(`^/[A-Za-z0-9_./-]*\.html$`)
+
+// DefaultPage is the page printer.settings reads when none is asked for.
+const DefaultPage = "/home/status.html"
+
+// The asks the verbs put to the device process (ADR 0468 clause 1; the shape of ADR 0436's mail-sends): the tools
+// never hold a credential, so each verb queues an ask on the work-queue stream device-asks, and the device process,
+// an account of its own, answers under the ask's id in the state device-answers.
+const (
+	// EventAsked is the event on the work queue; the stream device-asks carries it.
+	EventAsked = "device.asked"
+	// AsksStream is the work-queue stream's name on the bus: the manifest's local name device-asks, capitalised
+	// with its hyphen an underscore, as the controller composes a stream's own bus name.
+	AsksStream = "DEVICE_ASKS"
+	// AnswersState is the state the device process writes its answers in.
+	AnswersState = "device-answers"
+	// DeviceProcessID is the device process's id as module.json's resource "device" names it: the controller
+	// delivers its bus account as the own secret broker-device.
+	DeviceProcessID = "device"
+	// AnswerWait is how long a verb waits for the device process; ScanWait how long a scan does.
+	AnswerWait = 60 * time.Second
+	ScanWait   = 180 * time.Second
+	// QuickWait is how long a feeder scan is waited for in one call: the mesh console gives up on a call after
+	// 30 seconds, so a longer scan is answered as started, with its id, and read later (issue 1552).
+	QuickWait = 25 * time.Second
+	// FeederWait is how long the tool waits in the background for a feeder scan: the longest the device process
+	// lets one run (FeederMaxBound) and two minutes to store it.
+	FeederWait = FeederMaxBound + 2*time.Minute
+	// StaleAfter is how old an ask may be when the device process takes it: older than twice the longest wait,
+	// nobody waits for it any more, so the device is not touched for it.
+	StaleAfter = 2 * ScanWait
+)
+
+// The operations of an ask.
+const (
+	OpSettings = "settings"
+	OpScan     = "scan"
+	OpDocument = "document"
+	OpUpload   = "upload"
+	OpPrint    = "print"
+	// OpOpen asks which documents of several pages are open in the bucket (issue 1538).
+	OpOpen = "open-documents"
+)
+
+// Ask is what a verb queues: the operation, when it was asked, and the operation's own arguments.
+type Ask struct {
+	ID string    `json:"id"`
+	Op string    `json:"op"`
+	At time.Time `json:"asked-at"`
+	// Deadline is when the asker stops waiting for the device process to take the ask up: one taken after it is
+	// dropped before any work, so nothing is scanned or printed for an asker that has gone (issue 1539).
+	Deadline time.Time `json:"deadline,omitempty"`
+
+	Page   string `json:"page,omitempty"`   // settings
+	Links  bool   `json:"links,omitempty"`  // settings: the page's links are answered too
+	Hidden bool   `json:"hidden,omitempty"` // settings: the hidden fields are answered too
+	Object string `json:"object,omitempty"` // document, print: a scan's key
+	Upload string `json:"upload,omitempty"` // upload, print: an upload's id
+	Part   int    `json:"part,omitempty"`   // document, upload: counted from 1
+	Parts  int    `json:"parts,omitempty"`  // upload
+	SHA256 string `json:"sha256,omitempty"` // upload: the whole document's
+	Data   string `json:"data,omitempty"`   // upload: the part, base64
+	Copies int    `json:"copies,omitempty"` // print
+	Sides  string `json:"sides,omitempty"`  // print
+	Media  string `json:"media,omitempty"`  // print
+	Source string `json:"source,omitempty"` // scan: glass (default) or feeder
+	Duplex bool   `json:"duplex,omitempty"` // scan: both sides of each sheet, feeder only
+	Apart  bool   `json:"apart,omitempty"`  // scan: glass only, each of several documents lying apart is its own file
+
+	Document string `json:"document,omitempty"` // scan: start, or an open document's id: a glass page into it
+	Finish   bool   `json:"finish,omitempty"`   // scan: close the document named in Document into one PDF
+}
+
+// AskBus is how the tools reach the device process: they queue an ask and read an answer back.
+type AskBus interface {
+	Publish(id string, body any) error
+	Answer(id string) (json.RawMessage, error)
+}
+
+type sdkAskBus struct{}
+
+func (sdkAskBus) Publish(id string, body any) error {
+	return stdio.Emit(EventAsked, body, stdio.EmitOptions{MessageID: id})
+}
+
+func (sdkAskBus) Answer(id string) (json.RawMessage, error) {
+	e, err := stdio.State(AnswersState).Get(id)
+	if err != nil || e == nil {
+		return nil, err
+	}
+	return e.Value, nil
+}
+
+// answerWait, scanWait and answerPoll are what the tools wait with; a test shortens them.
+var (
+	answerWait = AnswerWait
+	scanWait   = ScanWait
+	quickWait  = QuickWait
+	feederWait = FeederWait
+	// scanRun and feederRun are how long the device process may take over a scan once it has taken it up (its own
+	// bounds, deviceproc.go); the tool follows a scan for its start-by wait and this.
+	scanRun    = 5 * time.Minute
+	feederRun  = FeederMaxBound + 5*time.Minute
+	answerPoll = 500 * time.Millisecond
+)
+
+// askBus is the bus the tools use; a test puts a bus of its own in its place.
+var askBus AskBus = sdkAskBus{}
+
+func newAskID() string {
+	b := make([]byte, 12)
+	rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+// call queues the ask and waits for the device process's answer, at most wait. An answer that is an error is
+// the error. Nothing here reads, opens or sends a credential (ADR 0436 §12).
+func (s *Service) call(ctx context.Context, ask Ask, wait time.Duration) (map[string]any, error) {
+	id, err := s.queue(ask, wait)
+	if err != nil {
+		return nil, err
+	}
+	return s.await(ctx, id, wait)
+}
+
+// queue puts the ask on the work queue and answers its id, under which the answer is written. The asker waits
+// startBy for the device process to take the ask up (0 is for as long as it is waited for).
+func (s *Service) queue(ask Ask, startBy time.Duration) (string, error) {
+	ask.ID, ask.At = newAskID(), s.Now().UTC()
+	if startBy > 0 {
+		ask.Deadline = ask.At.Add(startBy)
+	}
+	if err := s.Asks.Publish(ask.ID, ask); err != nil {
+		return "", fmt.Errorf("the ask for the device process could not be queued: %w", err)
+	}
+	return ask.ID, nil
+}
+
+// await waits at most wait for the answer to the ask with this id. An answer that is an error is the error.
+func (s *Service) await(ctx context.Context, id string, wait time.Duration) (map[string]any, error) {
+	poll := s.AnswerPoll
+	if wait <= 0 {
+		wait = AnswerWait
+	}
+	if poll <= 0 {
+		poll = 500 * time.Millisecond
+	}
+	ctx, cancel := context.WithTimeout(ctx, wait)
+	defer cancel()
+	for {
+		raw, err := s.Asks.Answer(id)
+		if err != nil {
+			return nil, fmt.Errorf("the device process's answers cannot be read: %w", err)
+		}
+		if raw != nil {
+			var out map[string]any
+			if err := json.Unmarshal(raw, &out); err != nil {
+				return nil, fmt.Errorf("the device process's answer is not JSON: %w", err)
+			}
+			if msg, bad := out["error"].(string); bad {
+				return nil, fmt.Errorf("%s", msg)
+			}
+			return out, nil
+		}
+		select {
+		case <-ctx.Done():
+			return nil, fmt.Errorf("the device process did not answer within %s: it may not be running, or the device is slow (ask %s)",
+				wait, id)
+		case <-time.After(poll):
+		}
+	}
+}
+
+// PrinterSettings asks the device process to log in, read one page of the admin site and log out, and waits for
+// its answer. Nothing is queued before the page is checked and printer and printer-certificate are known to be set.
+func (s *Service) PrinterSettings(ctx context.Context, page string, links, hidden bool) (map[string]any, error) {
+	if page == "" {
+		page = DefaultPage
+	}
+	if !validPage(page) {
+		return nil, fmt.Errorf("page %q is not a page of the admin site: it starts with / and ends in .html", page)
+	}
+	if err := s.Settings.MissingPrinter(); err != nil {
+		return nil, err
+	}
+	return s.call(ctx, Ask{Op: OpSettings, Page: page, Links: links, Hidden: hidden}, s.AnswerWait)
+}
+
+func validPage(page string) bool {
+	return pagePattern.MatchString(page) && !strings.Contains(page, "..") && !strings.Contains(page, "//")
+}
+
+var (
+	scanKeyPattern = regexp.MustCompile(`^[0-9a-f]{64}\.pdf$`)
+	uploadPattern  = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
+	mediaPattern   = regexp.MustCompile(`^[a-z0-9_.-]{1,64}$`)
+	sha256Pattern  = regexp.MustCompile(`^[0-9a-f]{64}$`)
+)
+
+// Sides are the values the printer's sides take.
+var sidesValues = []string{"one-sided", "two-sided-long-edge", "two-sided-short-edge"}
+
+// DefaultMedia is the paper printer.print takes when none is named.
+const DefaultMedia = "iso_a4_210x297mm"
+
+// checkDocument is what is wrong with an ask for a scan's part, or nil.
+func checkDocument(a Ask) error {
+	if !scanKeyPattern.MatchString(a.Object) {
+		return fmt.Errorf("object %q is not a scan's key: 64 hex digits and .pdf", a.Object)
+	}
+	if a.Part < 1 {
+		return fmt.Errorf("part is a whole number from 1")
+	}
+	return nil
+}
+
+// checkUpload is what is wrong with an ask for an upload's part, or nil: the numbers, the SHA-256, the size.
+func checkUpload(a Ask) error {
+	if !uploadPattern.MatchString(a.Upload) {
+		return fmt.Errorf("upload %q is not an upload id: letters, digits, - and _, at most 64", a.Upload)
+	}
+	if a.Parts < 1 || a.Parts > MostParts {
+		return fmt.Errorf("parts is a whole number from 1 to %d, not %d", MostParts, a.Parts)
+	}
+	if a.Part < 1 || a.Part > a.Parts {
+		return fmt.Errorf("part %d is out of range: the upload has parts 1 to %d", a.Part, a.Parts)
+	}
+	if !sha256Pattern.MatchString(a.SHA256) {
+		return fmt.Errorf("sha256 is the whole document's SHA-256, 64 lower-case hex digits")
+	}
+	raw, err := base64.StdEncoding.DecodeString(a.Data)
+	if err != nil {
+		return fmt.Errorf("data is not base64: %v", err)
+	}
+	if len(raw) > MaxPart {
+		return fmt.Errorf("a part is at most %d bytes (700 KiB), not %d", MaxPart, len(raw))
+	}
+	return nil
+}
+
+// checkPrint is what is wrong with an ask to print, or nil, after the defaults are laid in.
+func checkPrint(a *Ask) error {
+	if (a.Object == "") == (a.Upload == "") {
+		return fmt.Errorf("name either object (a scan's key) or upload (a completed upload's id), not both and not neither")
+	}
+	if a.Object != "" && !scanKeyPattern.MatchString(a.Object) {
+		return fmt.Errorf("object %q is not a scan's key: 64 hex digits and .pdf", a.Object)
+	}
+	if a.Upload != "" && !uploadPattern.MatchString(a.Upload) {
+		return fmt.Errorf("upload %q is not an upload id: letters, digits, - and _, at most 64", a.Upload)
+	}
+	if a.Copies == 0 {
+		a.Copies = 1
+	}
+	if a.Copies < 1 || a.Copies > 99 {
+		return fmt.Errorf("copies is a whole number from 1 to 99, not %d", a.Copies)
+	}
+	if a.Sides == "" {
+		a.Sides = "one-sided"
+	}
+	if !slices.Contains(sidesValues, a.Sides) {
+		return fmt.Errorf("sides is one of %s, not %q", strings.Join(sidesValues, ", "), a.Sides)
+	}
+	if a.Media == "" {
+		a.Media = DefaultMedia
+	}
+	if !mediaPattern.MatchString(a.Media) {
+		return fmt.Errorf("media %q is not a media size name such as %s", a.Media, DefaultMedia)
+	}
+	return nil
+}
+
+// ScanDocument asks for one part of a scan kept in the bucket.
+func (s *Service) ScanDocument(ctx context.Context, object string, part int) (map[string]any, error) {
+	a := Ask{Op: OpDocument, Object: object, Part: part}
+	if err := checkDocument(a); err != nil {
+		return nil, err
+	}
+	return s.call(ctx, a, s.AnswerWait)
+}
+
+// PrinterUpload sends one part of a document to be printed later, and says whether the upload is complete.
+func (s *Service) PrinterUpload(ctx context.Context, a Ask) (map[string]any, error) {
+	a.Op = OpUpload
+	if err := checkUpload(a); err != nil {
+		return nil, err
+	}
+	return s.call(ctx, a, s.AnswerWait)
+}
+
+// PrintFile prints a PDF or a JPEG that lies on the machine the tool runs on: it reads the file, uploads it in
+// parts under an upload id of its own and prints that, in one call (issue 1551). The type is read from the
+// file's first bytes, never its name; any other file is refused before anything is queued. The answer is the
+// print's, with the upload id and the file's size.
+func (s *Service) PrintFile(ctx context.Context, path string, a Ask) (map[string]any, error) {
+	if a.Object != "" || a.Upload != "" {
+		return nil, fmt.Errorf("name path, or object, or upload: one of the three")
+	}
+	// The path is checked first, and refused in one fixed way that tells nothing about the file.
+	doc, err := ReadDocument(path, MostParts*PartSize)
+	if err != nil {
+		return nil, err
+	}
+	a.Upload = "p-" + newAskID()
+	if err := checkPrint(&a); err != nil {
+		return nil, err
+	}
+	if s.Settings.Printer == "" {
+		return nil, unsetError("printer")
+	}
+	if _, _, err := SniffFormat(doc); err != nil {
+		return nil, fmt.Errorf("file %s: %w", path, err)
+	}
+	sum, n := sha256Hex(doc), partCount(len(doc))
+	for i := 1; i <= n; i++ {
+		part, _, _ := cutPartOf(doc, i, PartSize)
+		up, err := s.PrinterUpload(ctx, Ask{Upload: a.Upload, Part: i, Parts: n, SHA256: sum, Data: base64.StdEncoding.EncodeToString(part)})
+		if err != nil {
+			return nil, fmt.Errorf("part %d of %d of %s could not be uploaded: %w", i, n, path, err)
+		}
+		if i == n && up["complete"] != true {
+			return nil, fmt.Errorf("the upload of %s is not complete after its last part: %v", path, up)
+		}
+	}
+	out, err := s.PrinterPrint(ctx, a)
+	if err != nil {
+		return nil, fmt.Errorf("%s is uploaded as %s but could not be printed: %w", path, a.Upload, err)
+	}
+	out["path"], out["upload"], out["bytes"] = path, a.Upload, len(doc)
+	return out, nil
+}
+
+// PrinterPrint asks the device process to print a kept scan or a completed upload.
+func (s *Service) PrinterPrint(ctx context.Context, a Ask) (map[string]any, error) {
+	a.Op = OpPrint
+	if err := checkPrint(&a); err != nil {
+		return nil, err
+	}
+	if s.Settings.Printer == "" {
+		return nil, unsetError("printer")
+	}
+	return s.call(ctx, a, s.AnswerWait)
+}
+
+// PrinterStatus is the printer's state over IPP and the scanner's over eSCL, none of it behind a login
+// (ADR 0467 clause 5). A part that does not answer is an answer, with why, not an error. Which of printer and
+// scanner is not set is said by name, and nothing is contacted.
+func (s *Service) PrinterStatus(ctx context.Context) (map[string]any, error) {
+	var unset []string
+	if s.Settings.Printer == "" {
+		unset = append(unset, "printer")
+	}
+	if s.Settings.Scanner == "" {
+		unset = append(unset, "scanner")
+	}
+	if len(unset) > 0 {
+		return nil, unsetError(unset...)
+	}
+	out := map[string]any{}
+	if st, err := PrinterStateOf(ctx, s.Settings.Printer); err != nil {
+		out["answers"] = false
+		out["why"] = err.Error()
+	} else {
+		out["answers"] = true
+		out["state"] = st.State
+		out["state-code"] = st.StateCode
+		out["state-reasons"] = st.Reasons
+		out["make-and-model"] = st.MakeAndModel
+		out["markers"] = st.Markers
+	}
+	if es, err := NewClient(s.Settings.Scanner).Status(ctx); err != nil {
+		out["scanner"] = map[string]any{"answers": false, "why": err.Error()}
+	} else {
+		out["scanner"] = map[string]any{"answers": true, "state": es.State, "adf-state": es.AdfState}
+	}
+	return out, nil
+}

modules/brother/cmd/brother/printer_test.go

@@ -0,0 +1,282 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"brother/cmd/brother/internal/secret"
+)
+
+// 1453/AC3: printer.settings logs in by the field name the form gives, sends the password from the secret
+// file, follows the session cookie, and returns the page's title, links and form fields; a password field's
+// value is never returned, and the session is logged out. The page is SYNTHETIC (testdata/admin/
+// synthetic-settings.html): the real pages arrive in round 2.
+func TestPrinterSettingsReadsAPageBehindTheLogin(t *testing.T) {
+	f := newFakePrinter(t, "Qw9z3", "p4ss word")
+	_, run := printerTools(t, f, "p4ss word")
+	got, err := run(map[string]any{"page": "/general/other.html"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(f.posted) != 1 || f.posted[0].Get("Qw9z3") != "p4ss word" {
+		t.Errorf("the login posted %v", f.posted)
+	}
+	raw, _ := json.Marshal(got)
+	out := string(raw)
+	var a struct {
+		Title  string
+		Links  []Link
+		Forms  []Form
+		Logout string
+	}
+	json.Unmarshal(raw, &a)
+	if a.Title != "Synthetic settings" {
+		t.Errorf("title = %q", a.Title)
+	}
+	if len(a.Links) != 0 {
+		t.Errorf("links in the default answer: %v", a.Links)
+	}
+	if len(a.Forms) != 1 || a.Forms[0].Action != "/general/other.html" || a.Forms[0].Method != "post" {
+		t.Fatalf("forms = %+v", a.Forms)
+	}
+	want := map[string]Field{
+		"lock": {Name: "lock", Type: "checkbox", Value: "on", Label: "Scan lock"},
+		"node": {Name: "node", Type: "text", Value: "BRN-SYNTH", Label: "Name"},
+		"pw":   {Name: "pw", Type: "password", Value: "", Label: "Secret"},
+		"note": {Name: "note", Type: "textarea", Value: "hello & bye"},
+	}
+	for _, fl := range a.Forms[0].Fields {
+		if fl.Name == "mode" {
+			if fl.Type != "select" || fl.Value != "m" || fl.Label != "Mode" || len(fl.Options) != 2 || fl.Options[0] != (Option{Value: "a", Text: "Auto"}) || fl.Options[1] != (Option{Value: "m", Text: "Manual"}) {
+				t.Errorf("mode = %+v", fl)
+			}
+			continue
+		}
+		w, ok := want[fl.Name]
+		if !ok || fl.Name != w.Name || fl.Type != w.Type || fl.Value != w.Value || fl.Label != w.Label {
+			t.Errorf("field %+v, want %+v", fl, w)
+		}
+		delete(want, fl.Name)
+	}
+	if len(want) != 0 {
+		t.Errorf("fields missing: %v", want)
+	}
+	if strings.Contains(out, "shouldnotshow") {
+		t.Errorf("a password field's value was returned: %s", out)
+	}
+	if a.Logout != "logged out" || f.loggedInNow() != 0 {
+		t.Errorf("logout = %q, sessions open %d", a.Logout, f.loggedInNow())
+	}
+	// Read-only: the only form posted is the login.
+	if len(f.posted) != 1 {
+		t.Errorf("forms posted: %v", f.posted)
+	}
+}
+
+// 1453/AC3: with no page asked for, the status page is read.
+func TestPrinterSettingsDefaultsToTheStatusPage(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	_, run := printerTools(t, f, "pw")
+	got, err := run(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.(map[string]any)["title"] != "Synthetic status" {
+		t.Errorf("answer = %v", got)
+	}
+}
+
+// 1453/AC4: a wrong password is said as a failed login.
+func TestPrinterSettingsSaysAFailedLogin(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "right")
+	_, run := printerTools(t, f, "wrong")
+	if _, err := run(nil); err == nil || !strings.Contains(err.Error(), "login failed") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+// 1453/AC4: printer or printer-certificate not set is said by name by the tool, nothing is queued and the
+// printer is not contacted.
+func TestPrinterSettingsSaysWhichConfigIsUnsetAndQueuesNothing(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	for _, c := range []struct{ name, settings, want string }{
+		{"no printer", `{"printer-certificate":"` + f.print() + `"}`, "printer is not set"},
+		{"no certificate", `{"printer":"` + f.host() + `"}`, "printer-certificate is not set"},
+		{"neither", `{}`, "printer and printer-certificate"},
+	} {
+		r := newRig(t, c.settings, "pw")
+		_, err := r.run(nil)
+		if err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s: error = %v, want it to say %q", c.name, err, c.want)
+		}
+		if r.bus.asks() != 0 {
+			t.Errorf("%s: an ask was queued", c.name)
+		}
+	}
+	if f.connsNow() != 0 || len(f.requests) != 0 {
+		t.Errorf("the printer was contacted: %d connections, %v", f.connsNow(), f.requests)
+	}
+}
+
+// 1453/AC4: the secret not given is said by name, by the device process, and the printer is not contacted.
+func TestPrinterSettingsSaysTheSecretIsNotGivenAndContactsNothing(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	_, run := printerTools(t, f, "")
+	if _, err := run(nil); err == nil || !strings.Contains(err.Error(), "admin-password is not given") {
+		t.Errorf("no secret file: error = %v", err)
+	}
+	// An empty file is not given either.
+	r := newRig(t, printerSettingsJSON(f), "")
+	r.worker.Password = func() (string, error) {
+		p := filepath.Join(t.TempDir(), "e")
+		os.WriteFile(p, []byte("\n"), 0o600)
+		return secret.Read(p)
+	}
+	if _, err := r.run(nil); err == nil || !strings.Contains(err.Error(), "admin-password is not given") {
+		t.Errorf("empty secret: error = %v", err)
+	}
+	if f.connsNow() != 0 || len(f.requests) != 0 {
+		t.Errorf("the printer was contacted: %d connections, %v", f.connsNow(), f.requests)
+	}
+}
+
+// 1453: a page that is not a page of the admin site is refused before anything is queued, and by the admin
+// process too if one reaches it.
+func TestPrinterSettingsRefusesAPageOutsideTheSite(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	r := newRig(t, printerSettingsJSON(f), "pw")
+	for _, p := range []string{"general/status.html", "/general/status", "//evil.example/x.html", "/a/../b.html", "/a.html?x=1", "/a b.html"} {
+		if _, err := r.run(map[string]any{"page": p}); err == nil || !strings.Contains(err.Error(), "not a page") {
+			t.Errorf("page %q: error = %v", p, err)
+		}
+		if _, err := r.worker.read(t.Context(), p, false, false); err == nil || !strings.Contains(err.Error(), "not a page") {
+			t.Errorf("the device process, page %q: error = %v", p, err)
+		}
+	}
+	if _, err := r.run(map[string]any{"page": 5}); err == nil {
+		t.Errorf("a page that is no string was accepted")
+	}
+	if r.bus.asks() != 0 || f.connsNow() != 0 {
+		t.Errorf("%d asks queued, the printer contacted %d times", r.bus.asks(), f.connsNow())
+	}
+}
+
+// 1453: nobody consuming the queue is said as the device process not answering, naming the wait.
+func TestPrinterSettingsSaysWhenTheAdminProcessDoesNotAnswer(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	r := newRig(t, printerSettingsJSON(f), "pw")
+	r.bus.worker = nil
+	answerWait = 100 * time.Millisecond
+	_, err := r.run(nil)
+	if err == nil || !strings.Contains(err.Error(), "device process did not answer") {
+		t.Fatalf("error = %v", err)
+	}
+	if r.bus.asks() != 1 {
+		t.Errorf("%d asks queued", r.bus.asks())
+	}
+}
+
+// 1453: the device process terminates an ask it cannot read, drops one nobody waits for any more without
+// contacting the printer, acknowledges one already answered, and asks for redelivery when it cannot write its
+// answer.
+func TestTheAdminWorkerSettlesEachAsk(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	r := newRig(t, printerSettingsJSON(f), "pw")
+	w := r.worker
+	if act, _ := w.Handle([]byte("not json"), nil); act != actionTerm {
+		t.Errorf("an unreadable ask: action %v, want term", act)
+	}
+	old, _ := json.Marshal(Ask{ID: "old", Op: OpSettings, Page: DefaultPage, At: fixedNow.Add(-StaleAfter - time.Second)})
+	if act, _ := w.Handle(old, nil); act != actionAck || r.answers.get("old") != nil || f.connsNow() != 0 {
+		t.Errorf("a stale ask: action %v, answer %s, %d connections", act, r.answers.get("old"), f.connsNow())
+	}
+	fresh, _ := json.Marshal(Ask{ID: "a1", Op: OpSettings, Page: DefaultPage, At: fixedNow})
+	if act, _ := w.Handle(fresh, nil); act != actionAck || r.answers.get("a1") == nil {
+		t.Errorf("a fresh ask: action %v", act)
+	}
+	conns := f.connsNow()
+	if act, _ := w.Handle(fresh, nil); act != actionAck {
+		t.Errorf("an ask already answered: action %v, want ack", act)
+	}
+	_ = conns
+	r.answers.fail = fmt.Errorf("the bus is away")
+	again, _ := json.Marshal(Ask{ID: "a2", Op: OpSettings, Page: DefaultPage, At: fixedNow})
+	if act, delay := w.Handle(again, nil); act != actionRetry || delay <= 0 {
+		t.Errorf("an answer that cannot be written for want of the bus: action %v delay %v, want retry", act, delay)
+	}
+}
+
+// 1514: printer.settings with no page, and with /home/status.html, logs in from the page the printer serves its
+// login form on (the root redirects to it) and reads that page. The printer has no /general/status.html behind
+// the login: the fake, like the captured printer, answers it a 404 once logged in, and a redirect to the login
+// page before.
+func TestPrinterSettingsDefaultPageAndHomeStatusAreReadAfterTheLogin(t *testing.T) {
+	for name, args := range map[string]map[string]any{"default": {}, "explicit": {"page": "/home/status.html"}} {
+		f := newFakePrinter(t, "B1891", "pw")
+		_, run := printerTools(t, f, "pw")
+		got, err := run(args)
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		raw, _ := json.Marshal(got)
+		if !strings.Contains(string(raw), "Synthetic status") || !strings.Contains(string(raw), "/home/status.html") {
+			t.Errorf("%s: answer %.200s", name, raw)
+		}
+		if len(f.posted) != 1 || f.posted[0].Get("loginurl") != "/home/status.html" {
+			t.Errorf("%s: posted %v, want loginurl /home/status.html", name, f.posted)
+		}
+		if f.loggedInNow() != 0 {
+			t.Errorf("%s: the session is still open", name)
+		}
+	}
+	if DefaultPage != "/home/status.html" {
+		t.Errorf("DefaultPage = %s", DefaultPage)
+	}
+}
+
+// 1530: the printer's menu links are left out of the answer unless links:true is asked, and hidden fields
+// (the CSRF token) unless hidden:true is asked; a password field's value is never given.
+func TestPrinterSettingsLeavesOutLinksAndHiddenFieldsUnlessAsked(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	f.pages["/scan/scanfrompc.html"] = adminFixture(t, "reconstructed-scanfrompc.html")
+	_, run := printerTools(t, f, "pw")
+	read := func(args map[string]any) map[string]any {
+		t.Helper()
+		got, err := run(args)
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, _ := json.Marshal(got)
+		var m map[string]any
+		json.Unmarshal(raw, &m)
+		return m
+	}
+	names := func(m map[string]any) string {
+		var n []string
+		for _, fm := range m["forms"].([]any) {
+			for _, fl := range fm.(map[string]any)["fields"].([]any) {
+				n = append(n, fl.(map[string]any)["name"].(string))
+			}
+		}
+		return strings.Join(n, ",")
+	}
+	plain := read(map[string]any{"page": "/scan/scanfrompc.html"})
+	if _, has := plain["links"]; has {
+		t.Errorf("links in the default answer: %v", plain["links"])
+	}
+	if names(plain) != "B117d" {
+		t.Errorf("default fields = %s, want B117d alone", names(plain))
+	}
+	more := read(map[string]any{"page": "/scan/scanfrompc.html", "links": true, "hidden": true})
+	if l, _ := more["links"].([]any); len(l) != 3 {
+		t.Errorf("links:true gave %v", more["links"])
+	}
+	if names(more) != "CSRFToken,B1892,pageid,CSRFToken,postif_registration_reject,B117d" {
+		t.Errorf("hidden:true fields = %s", names(more))
+	}
+}

modules/brother/cmd/brother/rig_test.go

@@ -0,0 +1,160 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"github.com/nats-io/nats.go/jetstream"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+
+	"brother/cmd/brother/internal/secret"
+)
+
+// fixedNow is the time the tools and the device worker of a rig read.
+var fixedNow = time.Date(2026, 10, 20, 19, 5, 9, 0, time.Local)
+
+// memAnswers is the state device-answers, in memory.
+type memAnswers struct {
+	mu sync.Mutex
+	m  map[string]json.RawMessage
+	// fail, when set, is the error every Create answers.
+	fail error
+}
+
+func (a *memAnswers) Create(key string, v any) (uint64, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if a.fail != nil {
+		return 0, a.fail
+	}
+	if _, ok := a.m[key]; ok {
+		return 0, fmt.Errorf("%s: %w", key, stdio.ErrChanged)
+	}
+	if a.m == nil {
+		a.m = map[string]json.RawMessage{}
+	}
+	raw, _ := json.Marshal(v)
+	if len(raw) > StateMaxValue {
+		return 0, fmt.Errorf("brother's state device-answers, key %s: nats: %w", key, &jetstream.APIError{Code: 400, ErrorCode: jetstream.ErrorCode(10054), Description: "message size exceeds maximum allowed"})
+	}
+	a.m[key] = raw
+	return 1, nil
+}
+
+func (a *memAnswers) get(key string) json.RawMessage {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return a.m[key]
+}
+
+// fakeAskBus is the bus between the tools and the device process: an ask published on it is handed to the
+// worker, as the work queue hands it to the device process, and the worker's answers are what the tools read.
+type fakeAskBus struct {
+	worker    *deviceWorker // nil: nobody consumes the queue
+	answers   *memAnswers
+	mu        sync.Mutex
+	published []Ask
+}
+
+func (b *fakeAskBus) Publish(id string, body any) error {
+	raw, _ := json.Marshal(body)
+	if len(raw) > 1<<20 {
+		return fmt.Errorf("a message of %d bytes is over the bus's 1 MiB", len(raw))
+	}
+	var ask Ask
+	json.Unmarshal(raw, &ask)
+	b.mu.Lock()
+	b.published = append(b.published, ask)
+	b.mu.Unlock()
+	if b.worker != nil {
+		go b.worker.Handle(raw, nil)
+	}
+	return nil
+}
+
+func (b *fakeAskBus) Answer(id string) (json.RawMessage, error) { return b.answers.get(id), nil }
+
+func (b *fakeAskBus) asks() int {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return len(b.published)
+}
+
+func (b *fakeAskBus) ops() []string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	var o []string
+	for _, a := range b.published {
+		o = append(o, a.Op)
+	}
+	return o
+}
+
+// printerRig is the tools, the bus and the device worker over a settings file, with the secret in a file the way
+// the mesh writes it (a trailing newline included; an empty password writes none) and the bucket in memory.
+type printerRig struct {
+	tl      []stdio.Tool
+	run     func(args map[string]any) (any, error) // printer.settings
+	bus     *fakeAskBus
+	worker  *deviceWorker
+	answers *memAnswers
+	objects *memObjects
+	said    *[]said
+	mu      *sync.Mutex
+}
+
+// call runs a tool by name.
+func (r *printerRig) call(t *testing.T, name string, args map[string]any) (any, error) {
+	t.Helper()
+	return tool(t, r.tl, name).Run(args)
+}
+
+func newRig(t *testing.T, settings, password string) *printerRig {
+	t.Helper()
+	secretFile := filepath.Join(t.TempDir(), "admin-password.secret")
+	if password != "" {
+		if err := os.WriteFile(secretFile, []byte(password+"\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	file := settingsFile(t, settings)
+	answers, objects := &memAnswers{}, newMemObjects()
+	var out []said
+	var mu sync.Mutex
+	w := &deviceWorker{
+		Settings: func() (Settings, error) { return LoadSettings(file) },
+		Password: func() (string, error) { return secret.Read(secretFile) },
+		Objects:  func() (Objects, error) { return objects, nil },
+		Emit: func(body map[string]any, id string) error {
+			mu.Lock()
+			defer mu.Unlock()
+			_, err := objects.Get(t.Context(), body["object"].(string))
+			out = append(out, said{body, id, err == nil})
+			return nil
+		},
+		Answers: answers,
+		Node:    "shanks",
+		Now:     func() time.Time { return fixedNow },
+	}
+	bus := &fakeAskBus{worker: w, answers: answers}
+	old, oldWait, oldScan, oldPoll := askBus, answerWait, scanWait, answerPoll
+	askBus, answerWait, scanWait, answerPoll = bus, 5*time.Second, 5*time.Second, 5*time.Millisecond
+	t.Cleanup(func() { askBus, answerWait, scanWait, answerPoll = old, oldWait, oldScan, oldPoll })
+	tl := tools(file, func() time.Time { return fixedNow })
+	return &printerRig{tl: tl, run: tool(t, tl, "printer.settings").Run, bus: bus, worker: w, answers: answers, objects: objects, said: &out, mu: &mu}
+}
+
+func printerSettingsJSON(f *fakePrinter) string {
+	return `{"printer":"` + f.host() + `","printer-certificate":"` + f.print() + `"}`
+}
+
+func printerTools(t *testing.T, f *fakePrinter, password string) (settings string, run func(args map[string]any) (any, error)) {
+	t.Helper()
+	js := printerSettingsJSON(f)
+	return js, newRig(t, js, password).run
+}

modules/brother/cmd/brother/scan.go

@@ -0,0 +1,416 @@
+package main
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+)
+
+// EventAdded is the module's event: a scan was kept in the bucket (ADR 0464, ADR 0468 clause 2), said by the device
+// process. Consumers declare brother.scan.added; it
+// travels as mesh.mod.brother.event.scan.added. It names the object and never carries the image.
+const EventAdded = "scan.added"
+
+// Service is what the tools do, over one reading of the settings. The device process's own scan is Capture's.
+type Service struct {
+	Settings Settings
+	// Node is this machine's name, for the event.
+	Node string
+	Now  func() time.Time
+	// Asks is how the verbs reach the device process, which alone holds a credential.
+	Asks AskBus
+	// AnswerWait is how long a verb waits for the device process's answer (ScanWait for a scan); AnswerPoll how
+	// often it looks.
+	AnswerWait, ScanWait, AnswerPoll time.Duration
+	// QuickWait is how long a feeder scan is waited for in one call, FeederWait how long it is followed.
+	QuickWait, FeederWait time.Duration
+	// Jobs are the scans this process follows.
+	Jobs *Jobs
+}
+
+// Jobs are the scans this tool process has started and not yet been asked the outcome of. A scan runs in the
+// background from the moment it is asked for, so that it is filed whether or not the caller still waits (issue
+// 1539); the caller waits for it, and reads its outcome later with its id when it did not finish in time.
+type Jobs struct {
+	mu        sync.Mutex
+	m         map[string]*job
+	open      map[string]*time.Timer // open documents: the timer that closes each
+	recovered bool                   // the open documents of the bucket were looked for
+}
+
+// arm (re)starts the timer that closes the open document after d.
+func (j *Jobs) arm(doc string, d time.Duration, closeIt func()) {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	if j.open == nil {
+		j.open = map[string]*time.Timer{}
+	}
+	if t := j.open[doc]; t != nil {
+		t.Stop()
+	}
+	j.open[doc] = time.AfterFunc(d, func() {
+		j.disarm(doc)
+		closeIt()
+	})
+}
+
+// disarm forgets the open document's timer.
+func (j *Jobs) disarm(doc string) {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	if t := j.open[doc]; t != nil {
+		t.Stop()
+		delete(j.open, doc)
+	}
+}
+
+type job struct {
+	at   time.Time
+	done chan struct{}
+	body map[string]any // set when done
+	err  error          // set when failed
+}
+
+// jobKeep is how long a finished job's outcome can be read with its id.
+var jobKeep = time.Hour
+
+// docRetry is how long after a failed closing of an expired document it is tried again.
+var docRetry = 5 * time.Minute
+
+// NewJobs is an empty set of jobs.
+func NewJobs() *Jobs { return &Jobs{m: map[string]*job{}} }
+
+func (j *Jobs) get(id string) *job {
+	if j == nil {
+		return nil
+	}
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	return j.m[id]
+}
+
+func (j *Jobs) put(id string) *job {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	if j.m == nil {
+		j.m = map[string]*job{}
+	}
+	// A job nobody has asked after for jobKeep is forgotten (a finished one only).
+	for k, o := range j.m {
+		select {
+		case <-o.done:
+			if time.Since(o.at) > jobKeep {
+				delete(j.m, k)
+			}
+		default:
+		}
+	}
+	x := &job{at: time.Now(), done: make(chan struct{})}
+	j.m[id] = x
+	return x
+}
+
+// ScanNow asks the device process to scan, crop, build the PDF, keep it in the bucket and say scan.added, waits for
+// the stored scan's key, fetches its parts through the device process, joins them, checks their SHA-256 and files
+// the PDF in the scan folder (temp and rename, no overwrite). It answers the event's body and the path. Nothing is
+// asked before scanner and scan-folder are known to be set (1440/AC7); the tool never reads a credential.
+//
+// The scan is followed by a goroutine of its own to the end, so it is filed even when the caller has gone. A glass
+// scan is waited for (ScanWait); a feeder scan only for QuickWait, and when it is not finished by then the answer is
+// started: true with the scan's id, and ScanResult reads the outcome later.
+func (s *Service) ScanNow(ctx context.Context, source string, duplex, apart bool) (map[string]any, error) {
+	if err := s.Settings.Missing(); err != nil {
+		return nil, err
+	}
+	req, err := ParseScan(source, duplex, apart)
+	if err != nil {
+		return nil, err
+	}
+	run, quick := scanRun, s.ScanWait
+	if req.Feeder {
+		run, quick = feederRun, s.QuickWait
+	}
+	return s.runScan(ctx, Ask{Op: OpScan, Source: source, Duplex: duplex, Apart: apart}, run, quick)
+}
+
+// runScan queues the ask and follows it in the background to its end (filing included); the caller is given the
+// outcome if it comes within quick, and started: true with the id otherwise.
+func (s *Service) runScan(ctx context.Context, ask Ask, run, quick time.Duration) (map[string]any, error) {
+	id, j, err := s.startScan(ask, run)
+	if err != nil {
+		return nil, err
+	}
+	select {
+	case <-j.done:
+		return j.body, j.err
+	case <-time.After(quick):
+		return map[string]any{"started": true, "id": id, "state": "running",
+			"note": "the scan goes on and is filed when it is done; read its outcome with scanner.scan {id}, or wait for scan.added"}, nil
+	case <-ctx.Done():
+		return nil, fmt.Errorf("the caller went away; the scan %s goes on and is filed: %w", id, ctx.Err())
+	}
+}
+
+// startScan queues the ask and starts the goroutine that follows it, however long the caller waits.
+//
+// The ask carries a deadline, ScanWait from now: the device process drops it unscanned if it is taken up later (it
+// may be busy with a long feeder scan). One taken up in time may run for run, and the goroutine waits for that
+// too, so a scan that is announced is always filed, however long the caller has waited.
+func (s *Service) startScan(ask Ask, run time.Duration) (string, *job, error) {
+	startBy := s.ScanWait
+	bound := startBy + run
+	id, err := s.queue(ask, startBy)
+	if err != nil {
+		return "", nil, err
+	}
+	j := s.Jobs.put(id)
+	go func() {
+		// The goroutine outlives the caller: a context of its own, bounded by the scan's own bound and the time
+		// to fetch the parts.
+		ctx, cancel := context.WithTimeout(context.Background(), bound+10*time.Minute)
+		defer cancel()
+		j.body, j.err = s.finishScan(ctx, id, bound, ask)
+		close(j.done)
+	}()
+	return id, j, nil
+}
+
+// docExpiry is how long an open document waits for its next page before its pages are filed as one PDF anyway.
+var docExpiry = 30 * time.Minute
+
+// ScanPage scans the glass into a document of several pages (issue 1538). document is start, which opens a
+// document and scans its first page into it, or the id of an open one, which scans the next page into it; with
+// finish the document is closed into one PDF, filed once (nothing is scanned). An open document that gets no page
+// for docExpiry is closed and filed so, by this process: its pages are never lost.
+func (s *Service) ScanPage(ctx context.Context, document string, finish bool) (map[string]any, error) {
+	if err := s.Settings.Missing(); err != nil {
+		return nil, err
+	}
+	if document != "start" && !uploadPattern.MatchString(document) {
+		return nil, fmt.Errorf("document is start, or the id of an open document: letters, digits, - and _, at most 64")
+	}
+	if finish && document == "start" {
+		return nil, fmt.Errorf("finish closes an open document: name its id in document, not start")
+	}
+	return s.runScan(ctx, Ask{Op: OpScan, Document: document, Finish: finish}, scanRun, s.ScanWait)
+}
+
+// ScanResult is the outcome of the scan with this id: its body and path when it is done, state running when it is
+// not, and state failed with why when it failed. A scan this process does not know (it was restarted, or the id is
+// wrong) is an error.
+func (s *Service) ScanResult(id string) (map[string]any, error) {
+	j := s.Jobs.get(id)
+	if j == nil {
+		return nil, fmt.Errorf("no scan %s is known to this tool: its id is wrong, or the tool was restarted since it was asked for (a scan the device process kept is announced by scan.added)", id)
+	}
+	select {
+	case <-j.done:
+		if j.err != nil {
+			return map[string]any{"id": id, "state": "failed", "why": j.err.Error()}, nil
+		}
+		out := map[string]any{"id": id, "state": "done"}
+		for k, v := range j.body {
+			out[k] = v
+		}
+		return out, nil
+	default:
+		return map[string]any{"started": true, "id": id, "state": "running"}, nil
+	}
+}
+
+// finishScan waits for the device process's answer to the scan ask, then fetches the stored scan and files it.
+func (s *Service) finishScan(ctx context.Context, id string, wait time.Duration, ask Ask) (map[string]any, error) {
+	ans, err := s.await(ctx, id, wait)
+	if err != nil {
+		return nil, err
+	}
+	if doc, _ := ans["document"].(string); doc != "" && ans["key"] == nil {
+		// A page was added to an open document: nothing to file yet, and the document is closed if it is left open.
+		s.armDocument(doc, docExpiry, 0)
+		return ans, nil
+	}
+	if ask.Document != "" && ask.Finish {
+		out, err := s.fileAnswer(ctx, ans)
+		if err == nil {
+			s.Jobs.disarm(ask.Document)
+		}
+		return out, err
+	}
+	return s.fileAnswer(ctx, ans)
+}
+
+// fileAnswer fetches the scan the device process's answer names and files it; an answer that lists documents (several
+// lying apart on the glass, issue 1528) is each fetched and filed as a PDF of its own, and answered as documents,
+// in the order the scanner found them. One that cannot be filed does not hold back the others: it is named in failed.
+func (s *Service) fileAnswer(ctx context.Context, ans map[string]any) (map[string]any, error) {
+	list, many := ans["documents"].([]any)
+	if !many {
+		return s.fileOne(ctx, ans)
+	}
+	var filed []any
+	var failed []string
+	for i, d := range list {
+		one, _ := d.(map[string]any)
+		body, err := s.fileOne(ctx, one)
+		if err != nil {
+			failed = append(failed, fmt.Sprintf("document %d: %v", i+1, err))
+			continue
+		}
+		filed = append(filed, body)
+	}
+	if bad, ok := ans["failed"].([]any); ok {
+		for _, b := range bad {
+			failed = append(failed, fmt.Sprint(b))
+		}
+	}
+	if len(filed) == 0 {
+		return nil, fmt.Errorf("no document could be filed: %s", strings.Join(failed, "; "))
+	}
+	out := map[string]any{"documents": filed, "count": len(filed)}
+	if len(failed) > 0 {
+		out["failed"] = failed
+	}
+	return out, nil
+}
+
+// fileOne fetches the one scan the answer names and files it.
+func (s *Service) fileOne(ctx context.Context, ans map[string]any) (map[string]any, error) {
+	key, _ := ans["key"].(string)
+	sum, _ := ans["sha256"].(string)
+	parts, _ := ans["parts"].(float64)
+	if key == "" || sum == "" || parts < 1 || parts > MostAnswerParts {
+		return nil, fmt.Errorf("the device process's answer to the scan names no stored scan: %v", ans)
+	}
+	got := make([][]byte, 0, int(parts))
+	for i := 1; i <= int(parts); i++ {
+		p, err := s.fetchPart(ctx, key, i)
+		if err != nil && ctx.Err() == nil {
+			// A part fetch is a read, safe to repeat: one retry rides out a short bus outage (issue 1536).
+			p, err = s.fetchPart(ctx, key, i)
+		}
+		if err != nil {
+			return nil, fmt.Errorf("the scan is kept as %s, but its part %d could not be fetched: %w", key, i, err)
+		}
+		got = append(got, p)
+	}
+	pdf, err := joinParts(got, sum)
+	if err != nil {
+		return nil, fmt.Errorf("the scan is kept as %s: %w", key, err)
+	}
+	at, err := time.Parse(time.RFC3339, fmt.Sprint(ans["scanned-at"]))
+	if err != nil {
+		at = s.Now()
+	}
+	path, err := File(s.Settings.Folder, pdf, at.Local())
+	if err != nil {
+		return nil, fmt.Errorf("the scan is kept as %s, but could not be filed: %w", key, err)
+	}
+	body := map[string]any{}
+	for k, v := range ans {
+		if k != "key" && k != "size" && k != "parts" {
+			body[k] = v
+		}
+	}
+	body["path"] = path
+	return body, nil
+}
+
+// fetchPart is one part of a stored object, asked of the device process and decoded.
+func (s *Service) fetchPart(ctx context.Context, object string, part int) ([]byte, error) {
+	ans, err := s.call(ctx, Ask{Op: OpDocument, Object: object, Part: part}, s.AnswerWait)
+	if err != nil {
+		return nil, err
+	}
+	data, _ := ans["data"].(string)
+	raw, err := base64.StdEncoding.DecodeString(data)
+	if err != nil {
+		return nil, fmt.Errorf("the part is not base64: %w", err)
+	}
+	return raw, nil
+}
+
+// ScanStatus says whether the scanner answers, and what it is doing. A scanner that does not answer is an
+// answer, not an error: that is how the module's health is read.
+func (s *Service) ScanStatus(ctx context.Context) (map[string]any, error) {
+	if err := s.Settings.Missing(); err != nil {
+		return nil, err
+	}
+	st, err := NewClient(s.Settings.Scanner).Status(ctx)
+	if err != nil {
+		return map[string]any{"answers": false, "why": err.Error()}, nil
+	}
+	return map[string]any{"answers": true, "state": st.State, "adf-state": st.AdfState}, nil
+}
+
+// ScanList is the newest filed scans, newest first.
+func (s *Service) ScanList(limit int) (map[string]any, error) {
+	if err := s.Settings.Missing(); err != nil {
+		return nil, err
+	}
+	scans, err := List(s.Settings.Folder, limit)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"folder": s.Settings.Folder, "scans": scans}, nil
+}
+
+// armDocument closes the open document in d, from the expiry on: if that fails (the device process dropped the ask,
+// the bucket was away) it is tried again after docRetry, up to ten times, unless the document is gone or closed
+// already. A document is never forgotten while it can still be filed.
+func (s *Service) armDocument(doc string, d time.Duration, attempts int) {
+	s.Jobs.arm(doc, d, func() {
+		_, j, err := s.startScan(Ask{Op: OpScan, Document: doc, Finish: true}, scanRun)
+		if err == nil {
+			<-j.done
+			err = j.err
+		}
+		if err == nil || attempts >= 10 || strings.Contains(err.Error(), "is closed already") || strings.Contains(err.Error(), "its id is wrong") {
+			return
+		}
+		s.armDocument(doc, docRetry, attempts+1)
+	})
+}
+
+// Recover arms the expiry of every document the device process finds open in the bucket, so that a restart of
+// this process forgets none (issue 1538). A document gets what is left of its time since its last page.
+func (s *Service) Recover(ctx context.Context) error {
+	ans, err := s.call(ctx, Ask{Op: OpOpen}, s.AnswerWait)
+	if err != nil {
+		return err
+	}
+	open, _ := ans["open"].([]any)
+	for _, o := range open {
+		m, _ := o.(map[string]any)
+		id, _ := m["id"].(string)
+		if id == "" {
+			continue
+		}
+		left := docExpiry
+		if at, err := time.Parse(time.RFC3339, fmt.Sprint(m["updated"])); err == nil {
+			left = max(docExpiry-s.Now().Sub(at), time.Second)
+		}
+		s.armDocument(id, left, 0)
+	}
+	return nil
+}
+
+// tryRecover says whether this process has still to recover its open documents, and takes the turn; failed gives it
+// back.
+func (j *Jobs) tryRecover() bool {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	if j.recovered {
+		return false
+	}
+	j.recovered = true
+	return true
+}
+
+func (j *Jobs) recoverFailed() {
+	j.mu.Lock()
+	j.recovered = false
+	j.mu.Unlock()
+}

modules/brother/cmd/brother/service_test.go

@@ -0,0 +1,399 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+type said struct {
+	body map[string]any
+	id   string
+	// seen is whether the scan was kept in the bucket when it was said.
+	seen bool
+}
+
+// scanRig is the tools, the device worker and a bucket in memory over a settings file for the fake scanner and a
+// scan folder of the test's own, with the real defaults laid under what s sets.
+func scanRig(t *testing.T, f *fakeScanner, s Settings) (*printerRig, string) {
+	t.Helper()
+	if s.Scanner == "" {
+		s.Scanner = f.base()
+	}
+	if s.Folder == "" {
+		s.Folder = filepath.Join(t.TempDir(), "scans")
+	}
+	if s.Resolution == 0 {
+		s.Resolution = 300
+	}
+	if s.ColorMode == "" {
+		s.ColorMode = "color"
+	}
+	js, _ := json.Marshal(map[string]any{"scanner": s.Scanner, "scan-folder": s.Folder, "resolution": s.Resolution,
+		"color-mode": s.ColorMode, "crop": s.Crop})
+	return newRig(t, string(js), "pw"), s.Folder
+}
+
+func (r *printerRig) scan(t *testing.T) (map[string]any, error) {
+	t.Helper()
+	got, err := r.call(t, "scanner.scan", map[string]any{})
+	if err != nil {
+		return nil, err
+	}
+	return got.(map[string]any), nil
+}
+
+// 1440/AC2: asked 300 dpi, the scanner gave 200: the event's resolution and millimetres, and the PDF's page,
+// are the image's own.
+func TestTheFiledScanIsAtTheImagesOwnResolution(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{Crop: false, Resolution: 300})
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if body["resolution"] != float64(200) {
+		t.Errorf("resolution = %v, want the image's 200 (300 was asked)", body["resolution"])
+	}
+	if body["width-mm"] != 215.4 || body["height-mm"] != 279.8 {
+		t.Errorf("size = %v x %v mm, want 215.4 x 279.8 (1696 x 2203 px at 200 dpi)", body["width-mm"], body["height-mm"])
+	}
+	pdf, _ := os.ReadFile(body["path"].(string))
+	if !strings.Contains(string(pdf), "/MediaBox [0 0 610.56 793.08]") {
+		t.Errorf("the page is not 200 dpi's size")
+	}
+}
+
+// 1440/AC6 and 1453/AC9: one scan.added, said by the device process after the PDF is kept in the bucket under its
+// sha256, with every key, the object's key and never the image; the tool then files the PDF.
+func TestScanNowEmitsOneEventAfterTheScanIsKeptUnderTheSha256(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{Crop: true})
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := *r.said
+	if len(out) != 1 {
+		t.Fatalf("%d events, want 1", len(out))
+	}
+	ev := out[0]
+	if !ev.seen {
+		t.Error("the event was said before the PDF was kept in the bucket")
+	}
+	for _, k := range []string{"object", "node", "bytes", "sha256", "width-mm", "height-mm", "resolution", "color-mode", "cropped", "pages", "scanned-at"} {
+		if _, ok := ev.body[k]; !ok {
+			t.Errorf("the event lacks %s", k)
+		}
+	}
+	if len(ev.body) != 11 {
+		t.Errorf("the event has %d keys, want the eleven named (no path: filing is the tool's)", len(ev.body))
+	}
+	pdf, err := os.ReadFile(body["path"].(string))
+	if err != nil {
+		t.Fatal(err)
+	}
+	sum := sha256.Sum256(pdf)
+	want := hex.EncodeToString(sum[:])
+	if ev.body["sha256"] != want || ev.id != want || ev.body["object"] != want+".pdf" {
+		t.Errorf("sha256 %v / message id %v / object %v, want the file's %s", ev.body["sha256"], ev.id, ev.body["object"], want)
+	}
+	if kept, err := r.objects.Get(t.Context(), want+".pdf"); err != nil || !bytes.Equal(kept, pdf) {
+		t.Errorf("the bucket does not hold the filed PDF under its sha256 (%v)", err)
+	}
+	if ev.body["bytes"] != len(pdf) || ev.body["node"] != "shanks" || ev.body["cropped"] != true || ev.body["color-mode"] != "color" {
+		t.Errorf("event = %v", ev.body)
+	}
+	if want := fixedNow.UTC().Format(time.RFC3339); ev.body["scanned-at"] != want {
+		t.Errorf("scanned-at = %v, want %v", ev.body["scanned-at"], want)
+	}
+	if bytes.Contains(pdf, []byte("scanned-at")) || len(body) != 12 {
+		t.Errorf("the tool's answer has %d keys, want the event's eleven and the path", len(body))
+	}
+	if _, has := body["key"]; has {
+		t.Errorf("the device process's own answer keys leak into the tool's: %v", body)
+	}
+	// The cropped scan is the receipt, about 80-84 mm wide (1440/AC3).
+	if w := ev.body["width-mm"].(float64); w < 80 || w > 84 {
+		t.Errorf("width = %v mm", w)
+	}
+	files, _ := os.ReadDir(folder)
+	if len(files) != 1 || filepath.Join(folder, files[0].Name()) != body["path"] {
+		t.Errorf("folder holds %v, want the one scan", files)
+	}
+}
+
+// 1453/AC9: the same scan twice is one object in the bucket: a key is kept once.
+func TestTheSameScanTwiceIsOneObject(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{Crop: true})
+	if _, err := r.scan(t); err != nil {
+		t.Fatal(err)
+	}
+	f.mu.Lock()
+	_ = f.documents
+	f.mu.Unlock()
+	if _, err := r.scan(t); err != nil {
+		t.Fatal(err)
+	}
+	if r.objects.puts != 1 || len(r.objects.keys()) != 1 {
+		t.Errorf("%d puts, objects %v: want the one", r.objects.puts, r.objects.keys())
+	}
+}
+
+// 1440/AC6: a scanner that refuses keeps nothing, writes nothing, says nothing, and the error says why.
+func TestAScannerRefusalKeepsWritesAndSaysNothing(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.refuse = 503
+	r, folder := scanRig(t, f, Settings{})
+	_, err := r.scan(t)
+	if err == nil || !strings.Contains(err.Error(), "503") {
+		t.Fatalf("error = %v, want the refusal said", err)
+	}
+	if len(*r.said) != 0 || len(r.objects.keys()) != 0 {
+		t.Errorf("%d events, objects %v after a refusal", len(*r.said), r.objects.keys())
+	}
+	if _, err := os.Stat(folder); !os.IsNotExist(err) {
+		t.Errorf("the folder exists after a refusal: %v", err)
+	}
+}
+
+// 1440/AC6: a job that gives no page (the second NextDocument's 404) is the same.
+func TestAJobThatGivesNoPageKeepsWritesAndSaysNothing(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	f.noPage = true
+	r, folder := scanRig(t, f, Settings{})
+	if _, err := r.scan(t); err == nil || !strings.Contains(err.Error(), "404") {
+		t.Fatalf("error = %v", err)
+	}
+	if len(*r.said) != 0 || len(r.objects.keys()) != 0 {
+		t.Errorf("%d events, objects %v", len(*r.said), r.objects.keys())
+	}
+	if _, err := os.Stat(folder); !os.IsNotExist(err) {
+		t.Errorf("the folder exists: %v", err)
+	}
+}
+
+// 1440/AC6: an image that is no JPEG (a scanner that sent something else) keeps and files nothing.
+func TestAnImageThatIsNotAJPEGKeepsAndFilesNothing(t *testing.T) {
+	f := newFakeScanner(t, []byte("not an image"))
+	r, folder := scanRig(t, f, Settings{})
+	if _, err := r.scan(t); err == nil {
+		t.Fatal("a non-image was filed")
+	}
+	if len(*r.said) != 0 || len(r.objects.keys()) != 0 {
+		t.Errorf("%d events, objects %v", len(*r.said), r.objects.keys())
+	}
+	if _, err := os.Stat(folder); !os.IsNotExist(err) {
+		t.Errorf("the folder exists: %v", err)
+	}
+}
+
+// 1440/AC11: the first scan into a folder that is not there makes it.
+func TestTheFirstScanMakesTheFolder(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, folder := scanRig(t, f, Settings{})
+	if _, err := r.scan(t); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(folder)
+	if err != nil || info.Mode().Perm() != 0o755 {
+		t.Fatalf("folder %v %v", info, err)
+	}
+}
+
+func settingsFile(t *testing.T, json string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "settings.json")
+	if err := os.WriteFile(p, []byte(json), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+func tool(t *testing.T, tl []stdio.Tool, name string) stdio.Tool {
+	t.Helper()
+	for _, x := range tl {
+		if x.Name == name {
+			return x
+		}
+	}
+	t.Fatalf("no tool %s", name)
+	return stdio.Tool{}
+}
+
+// 1440/AC7: scanner or folder unset: every tool says which, and nothing is written or asked.
+func TestEveryToolSaysWhichValueIsUnsetAndWritesNothing(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	for _, c := range []struct{ json, want string }{
+		{`{"scanner":"` + "%s" + `","scan-folder":""}`, "scan-folder"},
+		{`{"scanner":"","scan-folder":"FOLDER"}`, "scanner"},
+		{`{}`, "scanner and scan-folder"},
+	} {
+		folder := filepath.Join(t.TempDir(), "scans")
+		js := strings.ReplaceAll(strings.Replace(c.json, "%s", f.base(), 1), "FOLDER", folder)
+		r := newRig(t, js, "pw")
+		out := *r.said
+		for _, name := range []string{"scanner.scan", "scanner.status", "scanner.list"} {
+			_, err := tool(t, r.tl, name).Run(map[string]any{})
+			if err == nil || !strings.Contains(err.Error(), c.want) {
+				t.Errorf("%s with %s: error = %v, want it to name %q", name, c.json, err, c.want)
+			}
+		}
+		if f.posts != 0 || f.documents != 0 || len(out) != 0 || r.bus.asks() != 0 || len(r.objects.keys()) != 0 {
+			t.Errorf("the scanner was asked, an ask queued or an event said: %d posts, %d documents, %d events, %d asks", f.posts, f.documents, len(out), r.bus.asks())
+		}
+		if _, err := os.Stat(folder); !os.IsNotExist(err) {
+			t.Errorf("the folder was made: %v", err)
+		}
+	}
+}
+
+// 1440/AC7: the settings file is not there at all.
+func TestAMissingSettingsFileIsSaid(t *testing.T) {
+	tl := tools(filepath.Join(t.TempDir(), "none.json"), time.Now)
+	if _, err := tool(t, tl, "scanner.status").Run(nil); err == nil || !strings.Contains(err.Error(), "settings") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+// 1440/AC8: scan_status from the captured idle status; a scanner that does not answer is answers false.
+func TestScanStatusSaysStateAndAdfState(t *testing.T) {
+	f := newFakeScanner(t, nil)
+	svc := &Service{Settings: Settings{Scanner: f.base(), Folder: "/x"}}
+	got, err := svc.ScanStatus(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got["answers"] != true || got["state"] != "Idle" || got["adf-state"] != "ScannerAdfEmpty" {
+		t.Fatalf("status = %v", got)
+	}
+	f.Close()
+	got, err = svc.ScanStatus(context.Background())
+	if err != nil || got["answers"] != false || got["why"] == "" {
+		t.Fatalf("a scanner that is gone: %v, %v", got, err)
+	}
+}
+
+// 1440/AC8: scan_list through the tool, newest first.
+func TestScanListToolListsTheNewestFirst(t *testing.T) {
+	folder := t.TempDir()
+	base := time.Date(2026, 10, 1, 12, 0, 0, 0, time.UTC)
+	for i, n := range []string{"scan-1.pdf", "scan-2.pdf"} {
+		p := filepath.Join(folder, n)
+		os.WriteFile(p, []byte("x"), 0o644)
+		os.Chtimes(p, base.Add(time.Duration(i)*time.Hour), base.Add(time.Duration(i)*time.Hour))
+	}
+	tl := tools(settingsFile(t, `{"scanner":"http://192.0.2.10/eSCL","scan-folder":"`+folder+`"}`), time.Now)
+	got, err := tool(t, tl, "scanner.list").Run(map[string]any{"limit": float64(5)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	scans := got.(map[string]any)["scans"].([]Entry)
+	if len(scans) != 2 || filepath.Base(scans[0].Path) != "scan-2.pdf" {
+		t.Fatalf("scans = %v", scans)
+	}
+	if _, err := tool(t, tl, "scanner.list").Run(map[string]any{"limit": float64(0)}); err == nil {
+		t.Error("limit 0 accepted")
+	}
+}
+
+// 1440/AC1: the whole path through the tool, settings read from the file, with the real defaults.
+func TestScanNowToolScansWithTheFileSettings(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	folder := filepath.Join(t.TempDir(), "scans")
+	r := newRig(t, `{"scanner":"`+f.base()+`","scan-folder":"`+folder+`","resolution":300,"color-mode":"color","crop":true}`, "pw")
+	got, err := r.call(t, "scanner.scan", map[string]any{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(*r.said) != 1 || got.(map[string]any)["cropped"] != true {
+		t.Fatalf("%d events, body %v", len(*r.said), got)
+	}
+}
+
+func TestLoadSettingsLaysTheDefaultsUnder(t *testing.T) {
+	s, err := LoadSettings(settingsFile(t, `{"scanner":" http://192.0.2.10/eSCL ","scan-folder":"/srv/scans"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Scanner != "http://192.0.2.10/eSCL" || s.Folder != "/srv/scans" || s.Resolution != 300 || s.ColorMode != "color" || !s.Crop {
+		t.Fatalf("settings = %+v", s)
+	}
+	s, _ = LoadSettings(settingsFile(t, `{"resolution":600,"color-mode":"gray","crop":false}`))
+	if s.Resolution != 600 || s.ColorMode != "gray" || s.Crop {
+		t.Fatalf("settings = %+v", s)
+	}
+}
+
+// flakyBus fails the first n document asks with an error answer, as a bus outage would end one wait, and passes
+// everything else on.
+type flakyBus struct {
+	*fakeAskBus
+	mu    sync.Mutex
+	fails int
+	// match says which asks fail; nil is the document fetches.
+	match func(Ask) bool
+}
+
+func (b *flakyBus) Publish(id string, body any) error {
+	raw, _ := json.Marshal(body)
+	var ask Ask
+	json.Unmarshal(raw, &ask)
+	b.mu.Lock()
+	fail := (b.match == nil && ask.Op == OpDocument || b.match != nil && b.match(ask)) && b.fails > 0
+	if fail {
+		b.fails--
+	}
+	b.mu.Unlock()
+	if fail {
+		b.answers.Create(id, map[string]any{"error": "nats: timeout"})
+		return nil
+	}
+	return b.fakeAskBus.Publish(id, body)
+}
+
+// 1536: a part fetch that fails once is asked again, and the scan is filed; one that fails twice is a failure
+// naming the stored object, so it can be filed later.
+func TestAFailedPartFetchIsAskedOnceMoreBeforeTheScanFails(t *testing.T) {
+	f := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r, _ := scanRig(t, f, Settings{Crop: false})
+	r.bus = nil
+	flaky := &flakyBus{fakeAskBus: &fakeAskBus{worker: r.worker, answers: r.answers}, fails: 1}
+	askBus = flaky
+	body, err := r.scan(t)
+	if err != nil {
+		t.Fatalf("one failed part fetch ended the scan: %v", err)
+	}
+	if _, err := os.Stat(body["path"].(string)); err != nil {
+		t.Errorf("the scan is not filed: %v", err)
+	}
+
+	f2 := newFakeScanner(t, fixture(t, "scan.jpg"))
+	r2, folder := scanRig(t, f2, Settings{Crop: false})
+	askBus = &flakyBus{fakeAskBus: &fakeAskBus{worker: r2.worker, answers: r2.answers}, fails: 2}
+	_, err = r2.scan(t)
+	if err == nil {
+		t.Fatal("two failed part fetches did not fail the scan")
+	}
+	key := ""
+	if got := *r2.said; len(got) == 1 {
+		key, _ = got[0].body["object"].(string)
+	}
+	if key == "" || !strings.Contains(err.Error(), key) {
+		t.Errorf("the failure %q does not name the stored object %q", err, key)
+	}
+	if entries, _ := os.ReadDir(folder); len(entries) != 0 {
+		t.Errorf("a scan whose parts failed was filed: %v", entries)
+	}
+}

modules/brother/cmd/brother/settings.go

@@ -0,0 +1,110 @@
+// Package main is the brother module's Go tools bundle (novox/hq ADR 0464, issue 1440): it scans the glass of a
+// network scanner over eSCL, crops the document, files it as a one-page PDF in a folder and says so on the bus.
+// A scan happens when a tool is called; the module runs no process of its own.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// Settings are the module's seven config values, as the mesh writes them into settings.json (ADR 0348).
+type Settings struct {
+	// Scanner is the eSCL base URL, such as http://192.0.2.10/eSCL.
+	Scanner string
+	// Folder is the absolute path the PDFs are filed in. It is not a manifest resource: a directory's path
+	// cannot take a config value (issue 1441), so the code creates it.
+	Folder string
+	// Resolution is the dpi asked of the scanner: 100, 200, 300 or 600.
+	Resolution int
+	// ColorMode is "color" or "gray".
+	ColorMode string
+	// Printer is the device's host (with a port if it is not 443), such as 192.0.2.10: the host of its admin
+	// page and its IPP service (ADR 0467 clause 3).
+	Printer string
+	// PrinterCertificate is the SHA-256 fingerprint of the one certificate the device's admin page may serve.
+	PrinterCertificate string
+	// Crop says whether the document is cut out of the platen's white.
+	Crop bool
+}
+
+// LoadSettings reads settings.json (the file named by BROTHER_SETTINGS) and lays the defaults under it. A missing
+// or unreadable file is an error that names it; an unset scanner or folder is Missing's to say.
+func LoadSettings(path string) (Settings, error) {
+	s := Settings{Resolution: 300, ColorMode: "color", Crop: true}
+	if path == "" {
+		return s, fmt.Errorf("BROTHER_SETTINGS names no settings file: the module's config does not reach the code")
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return s, fmt.Errorf("settings cannot be read: %w", err)
+	}
+	var in map[string]any
+	if err := json.Unmarshal(raw, &in); err != nil {
+		return s, fmt.Errorf("settings are not JSON (%s): %w", path, err)
+	}
+	if v, ok := in["scanner"].(string); ok {
+		s.Scanner = strings.TrimSpace(v)
+	}
+	if v, ok := in["scan-folder"].(string); ok {
+		s.Folder = strings.TrimSpace(v)
+	}
+	if v, ok := in["resolution"].(float64); ok && v > 0 {
+		s.Resolution = int(v)
+	}
+	if v, ok := in["color-mode"].(string); ok && v != "" {
+		s.ColorMode = v
+	}
+	if v, ok := in["printer"].(string); ok {
+		s.Printer = strings.TrimSpace(v)
+	}
+	if v, ok := in["printer-certificate"].(string); ok {
+		s.PrinterCertificate = strings.TrimSpace(v)
+	}
+	if v, ok := in["crop"].(bool); ok {
+		s.Crop = v
+	}
+	return s, nil
+}
+
+// Missing is nil when both required values are set, and otherwise says which is not: no tool writes or
+// asks anything before that (1440/AC7).
+func (s Settings) Missing() error {
+	var unset []string
+	if s.Scanner == "" {
+		unset = append(unset, "scanner")
+	}
+	if s.Folder == "" {
+		unset = append(unset, "scan-folder")
+	}
+	if len(unset) == 0 {
+		return nil
+	}
+	return fmt.Errorf("config value %s is not set: the operator gives it with the config verb for the brother module on this node",
+		strings.Join(unset, " and "))
+}
+
+// unsetError says which config values are not set.
+func unsetError(names ...string) error {
+	return fmt.Errorf("config value %s is not set: the operator gives it with the config verb for the brother module on this node",
+		strings.Join(names, " and "))
+}
+
+// MissingPrinter is nil when the two values the printer's verbs need are set, and otherwise says which is not:
+// nothing is contacted before that (1453/AC4).
+func (s Settings) MissingPrinter() error {
+	var unset []string
+	if s.Printer == "" {
+		unset = append(unset, "printer")
+	}
+	if s.PrinterCertificate == "" {
+		unset = append(unset, "printer-certificate")
+	}
+	if len(unset) == 0 {
+		return nil
+	}
+	return fmt.Errorf("config value %s is not set: the operator gives it with the config verb for the brother module on this node",
+		strings.Join(unset, " and "))
+}

modules/brother/cmd/brother/testdata/admin/live/etc_loginerror_html_url__2Fgeneral_2Fstatus_2Ehtml.body

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="iso-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html lang="en-gb" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-gb"><head><meta http-equiv="Content-Script-Type" content="text/javascript" /><meta http-equiv="content-style-type" content="text/css" /><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><meta http-equiv="X-UA-Compatible" content="IE=edge"><script type="text/javascript" src="/common/js/ews.js"></script><link rel="stylesheet" type="text/css" href="../common/css/mobile_common.css" />
+<link rel="stylesheet" type="text/css" href="../common/css/mobile_ews.css" />
+<title>Brother MFC-L8390CDW series</title><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, user-scalable=no" /></head><body><div id="headerFrame"><div id="menuButton" layout="pc" onclick="toggleMenu();"><img src="/common/images/menu_icon.gif" alt="Menu"></div><div id="modelName" layout="pc">MFC-L8390CDW series</div><div id="corporateLogo" layout="pc"><img src="/common/images/logo.gif" alt="Brother" /></div></div></div><div id="Menu" layout="pc"><div id="navigationContainer"><div id="navMenu"><div id="LayoutButton"><img id="PCButton" layout="pc" src="/common/images/chevron_left.gif" onclick="changeLayout('user_layout','mobile');"></img><img id="MobileButton" layout="pc" src="/common/images/pin.gif" onclick="changeLayout('user_layout','pc');"></img></div><hr><div id="LogInOutBox"><form method="post" action="/home/status.html"><div><input type="password" id="LogBox" name="B1891" /><input type="hidden" name="loginurl" value="/general/status.html"/><input id="login" type="submit" value="Login" /></div></form></div><div class="links"><a href="https://update.brother.co.jp/device/redirect.aspx?redirecttype=6&country=w&lang=en&device=MFC-L8390CDW series&alias=aqfs" target="_blank">Trouble logging in?</a></div><hr><div id="menu_tree_root"><div class="menuLv1"><a href="#" onclick="expandMenu('home_sub');">Home</a><div id="home_sub" class="open"><div class="menuLv2"><a href="/home/status.html">Status</a></div><div class="menuLv2"><a href="/home/reflesh.html" class="subMenu">Auto&#32;Refresh&#32;Interval</a></div></div></div><hr></div></div></div></div><div id="Page" layout="pc"><div id="rightFrameContainer"><div id="rightFrame"><div id="mainContent"><div id="pageTitle"><h2>Please&#32;Login</h2></div><div id="pageContents"><div class="contentsGroup"><p class="noteMessage">To&#32;Access&#32;this&#32;page&#32;you&#32;are&#32;required&#32;to&#32;Login,&#32;please&#32;Login.</p></div></div></div></div></div></div></div><div id="footerFrame">Copyright(C) 2000-2023 Brother Industries, Ltd. All Rights Reserved.</div><script type="text/javascript" src="/common/js/mobilemenucontrl.js"></script><script>window.onpageshow = function(event) {if (event.persisted) { window.location.reload(); }};</script></body></html>

modules/brother/cmd/brother/testdata/admin/live/etc_loginerror_html_url__2Fgeneral_2Fstatus_2Ehtml.headers

@@ -0,0 +1,11 @@
+HTTP/1.1 200 OK
+Cache-Control: no-store
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Content-Length: 2974
+Content-Type: text/html
+Content-Language: en-gb
+Connection: close
+X-XSS-Protection: 1; mode=block
+Pragma: no-cache
+

modules/brother/cmd/brother/testdata/admin/live/general_status_html.headers

@@ -0,0 +1,8 @@
+HTTP/1.1 302 Moved Temporarily
+Cache-Control: no-store
+X-Frame-Options: DENY
+Content-Length: 0
+Connection: close
+Pragma: no-cache
+Location: /etc/loginerror.html?url=%2Fgeneral%2Fstatus%2Ehtml
+

modules/brother/cmd/brother/testdata/admin/live/home_status_html.body

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="iso-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html lang="en-gb" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-gb"><head><meta http-equiv="Content-Script-Type" content="text/javascript" /><meta http-equiv="content-style-type" content="text/css" /><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><meta http-equiv="X-UA-Compatible" content="IE=edge"><script type="text/javascript" src="/common/js/ews.js"></script><link rel="stylesheet" type="text/css" href="../common/css/mobile_common.css" />
+<link rel="stylesheet" type="text/css" href="../common/css/mobile_ews.css" />
+<script type="text/javascript" src="../common/js/cookie.js"></script>
+<script type="text/javascript" src="../common/js/language.js"></script>
+<script type="text/javascript" src="../common/js/lcddisplay.js"></script>
+<title>Brother MFC-L8390CDW series</title><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, user-scalable=no" /></head><body><div id="headerFrame"><div id="menuButton" layout="pc" onclick="toggleMenu();"><img src="/common/images/menu_icon.gif" alt="Menu"></div><div id="modelName" layout="pc">MFC-L8390CDW series</div><div id="corporateLogo" layout="pc"><img src="/common/images/logo.gif" alt="Brother" /></div></div></div><div id="Menu" layout="pc"><div id="navigationContainer"><div id="navMenu"><div id="LayoutButton"><img id="PCButton" layout="pc" src="/common/images/chevron_left.gif" onclick="changeLayout('user_layout','mobile');"></img><img id="MobileButton" layout="pc" src="/common/images/pin.gif" onclick="changeLayout('user_layout','pc');"></img></div><hr><div id="LogInOutBox"><form method="post" action="/home/status.html"><div><input type="password" id="LogBox" name="B1891" /><input type="hidden" name="loginurl" value="/home/status.html"/><input id="login" type="submit" value="Login" /></div></form></div><div class="links"><a href="https://update.brother.co.jp/device/redirect.aspx?redirecttype=6&country=w&lang=en&device=MFC-L8390CDW series&alias=aqfs" target="_blank">Trouble logging in?</a></div><hr><div id="menu_tree_root"><div class="menuLv1"><a href="#" onclick="expandMenu('home_sub');">Home</a><div id="home_sub" class="open"><div class="menuLv2 selected"><a href="../home/status.html">Status</a></div><div class="menuLv2"><a href="/home/reflesh.html" class="subMenu">Auto&#32;Refresh&#32;Interval</a></div></div></div><hr></div></div></div></div><div id="Page" layout="pc"><div id="rightFrameContainer"><div id="rightFrame"><div id="mainContent"><div id="pageTitle"><h2>Status</h2></div><div id="pageContents"><form method="post" action="/home/status.html"><div><input type="hidden" id="pageid" name="pageid" value="1" /></div><div class="contentsGroup"><dl class="items"><dt>Device&#32;Status</dt><dd><div id="moni_data"><span class="moni moniError"></span></div></dd><dt class="subhead"><span>Automatic&#32;Refresh</span></dt><dd><div><label class="radioSimple"><input type="radio" name="Refresh" value="0" onclick="refreshLCD(0);" checked="checked" />
+Off</label><label class="radioSimple"><input type="radio" name="Refresh" value="1" onclick="refreshLCD(60000);" />
+On</label></div></dd><dt>Toner&#32;Level</dt><dd><div id="ink_level"><table id="inkLevel" summary="ink level"><tr><th></th><th><img src="../common/images/low.gif" alt="Low" /></th><th><img src="../common/images/replace.gif" alt="Replace" /></th><th></th></tr><tr><td><img src="../common/images/black.gif" alt="Black" class="tonerremain" height="22" /></td><td><img src="../common/images/cyan.gif" alt="Cyan" class="tonerremain" height="5" /></td><td><img src="../common/images/magenta.gif" alt="Magenta" class="tonerremain" height="0" /></td><td><img src="../common/images/yellow.gif" alt="Yellow" class="tonerremain" height="56" /></td></tr><tr><th>BK</th><th>C</th><th>M</th><th>Y</th></tr></table></div></dd></dl></div><div class="contentsGroup"><dl class="items"><dt>Web&#32;Language</dt><dd><select id="Language" name="Language" onchange="changeLanguage('Language', 'WebLang');"><option value="0" selected="selected">Auto</option><option value="2">English</option><option value="3">French</option><option value="4">German</option><option value="5">Dutch</option><option value="6">Spanish</option><option value="7">Italian</option><option value="10">Russian</option><option value="11">Portuguese</option><option value="12">Polish</option></select></dd></dl></div><div class="contentsGroup"><dl class="items"><dt>Device&#32;Location</dt><dd><ul class="itemList"><li class="contact">Contact<span class="spacer">:</span></li><li class="location">Location<span class="spacer">:</span></li></ul></dd></dl></div></form></div></div></div></div><script type="text/javascript">
+<!--
+judge_refresh(60000);
+//-->
+</script>
+</div></div><div id="footerFrame">Copyright(C) 2000-2023 Brother Industries, Ltd. All Rights Reserved.</div><script type="text/javascript" src="/common/js/mobilemenucontrl.js"></script><script>window.onpageshow = function(event) {if (event.persisted) { window.location.reload(); }};</script></body></html>

modules/brother/cmd/brother/testdata/admin/live/home_status_html.headers

@@ -0,0 +1,11 @@
+HTTP/1.1 200 OK
+Cache-Control: no-store
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Content-Length: 5180
+Content-Type: text/html
+Content-Language: en-gb
+Connection: close
+X-XSS-Protection: 1; mode=block
+Pragma: no-cache
+

modules/brother/cmd/brother/testdata/admin/live/root.headers

@@ -0,0 +1,8 @@
+HTTP/1.1 301 Moved Permanently
+Cache-Control: no-store
+X-Frame-Options: DENY
+Content-Length: 0
+Connection: close
+Pragma: no-cache
+Location: /home/status.html
+

modules/brother/cmd/brother/testdata/admin/login-page-headers.txt

@@ -0,0 +1,11 @@
+HTTP/1.1 200 OK
+Cache-Control: no-store
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Content-Length: 2974
+Content-Type: text/html
+Content-Language: en-gb
+Connection: close
+X-XSS-Protection: 1; mode=block
+Pragma: no-cache
+

modules/brother/cmd/brother/testdata/admin/login-page.html

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="iso-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html lang="en-gb" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-gb"><head><meta http-equiv="Content-Script-Type" content="text/javascript" /><meta http-equiv="content-style-type" content="text/css" /><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><meta http-equiv="X-UA-Compatible" content="IE=edge"><script type="text/javascript" src="/common/js/ews.js"></script><link rel="stylesheet" type="text/css" href="../common/css/mobile_common.css" />
+<link rel="stylesheet" type="text/css" href="../common/css/mobile_ews.css" />
+<title>Brother MFC-L8390CDW series</title><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, user-scalable=no" /></head><body><div id="headerFrame"><div id="menuButton" layout="pc" onclick="toggleMenu();"><img src="/common/images/menu_icon.gif" alt="Menu"></div><div id="modelName" layout="pc">MFC-L8390CDW series</div><div id="corporateLogo" layout="pc"><img src="/common/images/logo.gif" alt="Brother" /></div></div></div><div id="Menu" layout="pc"><div id="navigationContainer"><div id="navMenu"><div id="LayoutButton"><img id="PCButton" layout="pc" src="/common/images/chevron_left.gif" onclick="changeLayout('user_layout','mobile');"></img><img id="MobileButton" layout="pc" src="/common/images/pin.gif" onclick="changeLayout('user_layout','pc');"></img></div><hr><div id="LogInOutBox"><form method="post" action="/home/status.html"><div><input type="password" id="LogBox" name="B1891" /><input type="hidden" name="loginurl" value="/general/status.html"/><input id="login" type="submit" value="Login" /></div></form></div><div class="links"><a href="https://update.brother.co.jp/device/redirect.aspx?redirecttype=6&country=w&lang=en&device=MFC-L8390CDW series&alias=aqfs" target="_blank">Trouble logging in?</a></div><hr><div id="menu_tree_root"><div class="menuLv1"><a href="#" onclick="expandMenu('home_sub');">Home</a><div id="home_sub" class="open"><div class="menuLv2"><a href="/home/status.html">Status</a></div><div class="menuLv2"><a href="/home/reflesh.html" class="subMenu">Auto&#32;Refresh&#32;Interval</a></div></div></div><hr></div></div></div></div><div id="Page" layout="pc"><div id="rightFrameContainer"><div id="rightFrame"><div id="mainContent"><div id="pageTitle"><h2>Please&#32;Login</h2></div><div id="pageContents"><div class="contentsGroup"><p class="noteMessage">To&#32;Access&#32;this&#32;page&#32;you&#32;are&#32;required&#32;to&#32;Login,&#32;please&#32;Login.</p></div></div></div></div></div></div></div><div id="footerFrame">Copyright(C) 2000-2023 Brother Industries, Ltd. All Rights Reserved.</div><script type="text/javascript" src="/common/js/mobilemenucontrl.js"></script><script>window.onpageshow = function(event) {if (event.persisted) { window.location.reload(); }};</script></body></html>

modules/brother/cmd/brother/testdata/admin/reconstructed-scanfrompc.html

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="iso-8859-1"?><html><head><title>Brother MFC-L8390CDW series</title></head><body>
+<!-- RECONSTRUCTED, not captured: built from what printer.settings answered for /scan/scanfrompc.html on 2026-10-21
+     (the two form actions, the first form's hidden fields CSRFToken and B1892, the second form's hidden fields without their token values, the radio group B117d with the labels Enabled and Disabled
+     and the values 1 and 0). Which button is checked, the table layout and the row heading are assumptions. -->
+<a href="/home/status.html">Status</a><a href="/scan/scanfrompc.html">Scan from PC</a><a href="/home/logout.html">Logout</a>
+<form method="post" action="/home/status.html"><input type="hidden" name="CSRFToken" value="TOKEN"/><input type="hidden" name="B1892" value=""/></form>
+<form method="post" action="/scan/scanfrompc.html"><input type="hidden" name="pageid" value="247"/><input type="hidden" name="CSRFToken" value="TOKEN"/><input type="hidden" name="postif_registration_reject" value="1"/>
+<table><tr><th>Scan from PC</th><td><input type="radio" id="B117d_1" name="B117d" value="1" checked="checked"/><label for="B117d_1">Enabled</label>
+<input type="radio" id="B117d_0" name="B117d" value="0"/><label for="B117d_0">Disabled</label></td></tr></table>
+<input type="submit" value="Submit"/></form></body></html>

modules/brother/cmd/brother/testdata/admin/synthetic-settings.html

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="iso-8859-1"?><html><head><title>Synthetic settings</title></head><body><a href="/home/logout.html">Logout</a><a href="/general/status.html">Status</a><form method="post" action="/general/other.html"><table><tr><td><label for="lock">Scan&#32;lock</label></td><td><input type="checkbox" id="lock" name="lock" value="on"/></td></tr><tr><td><label for="name">Name</label></td><td><input type="text" id="name" name="node" value="BRN-SYNTH"/></td></tr><tr><td><label for="mode">Mode</label></td><td><select id="mode" name="mode"><option value="a">Auto</option><option value="m" selected="selected">Manual</option></select></td></tr><tr><td><label>Secret<input type="password" name="pw" value="shouldnotshow"/></label></td></tr><tr><td><textarea name="note">hello &amp; bye</textarea></td></tr></table><input type="hidden" name="token" value="t1"/><input type="submit" value="Save"/></form></body></html>

modules/brother/cmd/brother/testdata/admin/synthetic-status.html

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="iso-8859-1"?><html><head><title>Synthetic status</title></head><body><div id="LogInOutBox"><a href="/home/logout.html">Logout</a></div><div id="pageTitle"><h2>Status</h2></div><div><a href="/general/other.html">Other&#32;page</a><a href="/net/net/airprint.html">AirPrint</a></div></body></html>

modules/brother/cmd/brother/testdata/escl/capabilities.xml

@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<scan:ScannerCapabilities
+xmlns:scan="http://schemas.hp.com/imaging/escl/2011/05/03"
+xmlns:pwg="http://www.pwg.org/schemas/2010/12/sm"
+xmlns:dest="http://schemas.hp.com/imaging/destination/2011/06/06"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="http://schemas.hp.com/imaging/escl/2011/05/03 ../../schemas/eSCL-1_92.xsd">
+<pwg:Version>2.93</pwg:Version>
+<pwg:MakeAndModel>Brother MFC-L8390CDW series</pwg:MakeAndModel>
+<pwg:SerialNumber>E82414G4N581626</pwg:SerialNumber>
+<scan:Manufacturer>Brother</scan:Manufacturer>
+<scan:UUID>e3248000-80ce-11db-8000-94ddf83ec78a</scan:UUID>
+<scan:AdminURI>http://BRW58CDC9DFC80B.local./net/net/airprint.html</scan:AdminURI>
+<scan:IconURI>http://BRW58CDC9DFC80B.local./icons/device-icons-128.png</scan:IconURI>
+<scan:Certifications>
+<scan:Certification>
+<scan:Name>mopria-certified-scan</scan:Name>
+<scan:Version>1.4</scan:Version>
+</scan:Certification>
+</scan:Certifications>
+<scan:Platen>
+<scan:PlatenInputCaps>
+<scan:MinWidth>64</scan:MinWidth>
+<scan:MaxWidth>2550</scan:MaxWidth>
+<scan:MinHeight>64</scan:MinHeight>
+<scan:MaxHeight>3507</scan:MaxHeight>
+<scan:MaxXOffset>2486</scan:MaxXOffset>
+<scan:MaxYOffset>3443</scan:MaxYOffset>
+<scan:MaxScanRegions>1</scan:MaxScanRegions>
+<scan:SettingProfiles>
+<scan:SettingProfile>
+<scan:ColorModes>
+<scan:ColorMode>BlackAndWhite1</scan:ColorMode>
+<scan:ColorMode>Grayscale8</scan:ColorMode>
+<scan:ColorMode>RGB24</scan:ColorMode>
+</scan:ColorModes>
+<scan:DocumentFormats>
+<pwg:DocumentFormat>application/pdf</pwg:DocumentFormat>
+<pwg:DocumentFormat>image/jpeg</pwg:DocumentFormat>
+<scan:DocumentFormatExt>application/pdf</scan:DocumentFormatExt>
+<scan:DocumentFormatExt>image/jpeg</scan:DocumentFormatExt>
+</scan:DocumentFormats>
+<scan:SupportedResolutions>
+<scan:DiscreteResolutions>
+<scan:DiscreteResolution>
+<scan:XResolution>100</scan:XResolution>
+<scan:YResolution>100</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>200</scan:XResolution>
+<scan:YResolution>200</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>300</scan:XResolution>
+<scan:YResolution>300</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>600</scan:XResolution>
+<scan:YResolution>600</scan:YResolution>
+</scan:DiscreteResolution>
+</scan:DiscreteResolutions>
+</scan:SupportedResolutions>
+<scan:ColorSpaces>
+<scan:ColorSpace>CMYK</scan:ColorSpace>
+<scan:ColorSpace>YCC</scan:ColorSpace>
+<scan:ColorSpace>sRGB</scan:ColorSpace>
+</scan:ColorSpaces>
+<scan:CcdChannels>
+<scan:CcdChannel>Red</scan:CcdChannel>
+<scan:CcdChannel>Green</scan:CcdChannel>
+<scan:CcdChannel>Blue</scan:CcdChannel>
+<scan:CcdChannel>NTSC</scan:CcdChannel>
+<scan:CcdChannel>GrayCcd</scan:CcdChannel>
+<scan:CcdChannel>GrayCcdEmulated</scan:CcdChannel>
+</scan:CcdChannels>
+<scan:BinaryRenderings>
+<scan:BinaryRendering>Halftone</scan:BinaryRendering>
+<scan:BinaryRendering>Threshold</scan:BinaryRendering>
+</scan:BinaryRenderings>
+</scan:SettingProfile>
+</scan:SettingProfiles>
+<scan:SupportedIntents>
+<scan:Intent>Document</scan:Intent>
+<scan:Intent>TextAndGraphic</scan:Intent>
+<scan:Intent>Photo</scan:Intent>
+<scan:Intent>Preview</scan:Intent>
+</scan:SupportedIntents>
+<scan:MaxOpticalXResolution>1200</scan:MaxOpticalXResolution>
+<scan:MaxOpticalYResolution>2400</scan:MaxOpticalYResolution>
+<scan:RiskyLeftMargin>0</scan:RiskyLeftMargin>
+<scan:RiskyRightMargin>0</scan:RiskyRightMargin>
+<scan:RiskyTopMargin>0</scan:RiskyTopMargin>
+<scan:RiskyBottomMargin>0</scan:RiskyBottomMargin>
+<scan:MaxPhysicalWidth>2550</scan:MaxPhysicalWidth>
+<scan:MaxPhysicalHeight>3507</scan:MaxPhysicalHeight>
+</scan:PlatenInputCaps>
+</scan:Platen>
+<scan:Adf>
+<scan:AdfSimplexInputCaps>
+<scan:MinWidth>64</scan:MinWidth>
+<scan:MaxWidth>2550</scan:MaxWidth>
+<scan:MinHeight>1740</scan:MinHeight>
+<scan:MaxHeight>4200</scan:MaxHeight>
+<scan:MaxXOffset>2486</scan:MaxXOffset>
+<scan:MaxYOffset>2460</scan:MaxYOffset>
+<scan:MaxScanRegions>1</scan:MaxScanRegions>
+<scan:SettingProfiles>
+<scan:SettingProfile>
+<scan:ColorModes>
+<scan:ColorMode>BlackAndWhite1</scan:ColorMode>
+<scan:ColorMode>Grayscale8</scan:ColorMode>
+<scan:ColorMode>RGB24</scan:ColorMode>
+</scan:ColorModes>
+<scan:DocumentFormats>
+<pwg:DocumentFormat>application/pdf</pwg:DocumentFormat>
+<pwg:DocumentFormat>image/jpeg</pwg:DocumentFormat>
+<scan:DocumentFormatExt>application/pdf</scan:DocumentFormatExt>
+<scan:DocumentFormatExt>image/jpeg</scan:DocumentFormatExt>
+</scan:DocumentFormats>
+<scan:SupportedResolutions>
+<scan:DiscreteResolutions>
+<scan:DiscreteResolution>
+<scan:XResolution>100</scan:XResolution>
+<scan:YResolution>100</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>200</scan:XResolution>
+<scan:YResolution>200</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>300</scan:XResolution>
+<scan:YResolution>300</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>600</scan:XResolution>
+<scan:YResolution>600</scan:YResolution>
+</scan:DiscreteResolution>
+</scan:DiscreteResolutions>
+</scan:SupportedResolutions>
+<scan:ColorSpaces>
+<scan:ColorSpace>CMYK</scan:ColorSpace>
+<scan:ColorSpace>YCC</scan:ColorSpace>
+<scan:ColorSpace>sRGB</scan:ColorSpace>
+</scan:ColorSpaces>
+<scan:CcdChannels>
+<scan:CcdChannel>Red</scan:CcdChannel>
+<scan:CcdChannel>Green</scan:CcdChannel>
+<scan:CcdChannel>Blue</scan:CcdChannel>
+<scan:CcdChannel>NTSC</scan:CcdChannel>
+<scan:CcdChannel>GrayCcd</scan:CcdChannel>
+<scan:CcdChannel>GrayCcdEmulated</scan:CcdChannel>
+</scan:CcdChannels>
+<scan:BinaryRenderings>
+<scan:BinaryRendering>Halftone</scan:BinaryRendering>
+<scan:BinaryRendering>Threshold</scan:BinaryRendering>
+</scan:BinaryRenderings>
+</scan:SettingProfile>
+</scan:SettingProfiles>
+<scan:SupportedIntents>
+<scan:Intent>Document</scan:Intent>
+<scan:Intent>TextAndGraphic</scan:Intent>
+<scan:Intent>Photo</scan:Intent>
+<scan:Intent>Preview</scan:Intent>
+</scan:SupportedIntents>
+<scan:MaxOpticalXResolution>1200</scan:MaxOpticalXResolution>
+<scan:MaxOpticalYResolution>600</scan:MaxOpticalYResolution>
+<scan:RiskyLeftMargin>0</scan:RiskyLeftMargin>
+<scan:RiskyRightMargin>0</scan:RiskyRightMargin>
+<scan:RiskyTopMargin>0</scan:RiskyTopMargin>
+<scan:RiskyBottomMargin>0</scan:RiskyBottomMargin>
+<scan:MaxPhysicalWidth>2550</scan:MaxPhysicalWidth>
+<scan:MaxPhysicalHeight>4200</scan:MaxPhysicalHeight>
+</scan:AdfSimplexInputCaps>
+<scan:AdfDuplexInputCaps>
+<scan:MinWidth>64</scan:MinWidth>
+<scan:MaxWidth>2550</scan:MaxWidth>
+<scan:MinHeight>1740</scan:MinHeight>
+<scan:MaxHeight>4200</scan:MaxHeight>
+<scan:MaxXOffset>2486</scan:MaxXOffset>
+<scan:MaxYOffset>2460</scan:MaxYOffset>
+<scan:MaxScanRegions>1</scan:MaxScanRegions>
+<scan:SettingProfiles>
+<scan:SettingProfile>
+<scan:ColorModes>
+<scan:ColorMode>BlackAndWhite1</scan:ColorMode>
+<scan:ColorMode>Grayscale8</scan:ColorMode>
+<scan:ColorMode>RGB24</scan:ColorMode>
+</scan:ColorModes>
+<scan:DocumentFormats>
+<pwg:DocumentFormat>application/pdf</pwg:DocumentFormat>
+<pwg:DocumentFormat>image/jpeg</pwg:DocumentFormat>
+<scan:DocumentFormatExt>application/pdf</scan:DocumentFormatExt>
+<scan:DocumentFormatExt>image/jpeg</scan:DocumentFormatExt>
+</scan:DocumentFormats>
+<scan:SupportedResolutions>
+<scan:DiscreteResolutions>
+<scan:DiscreteResolution>
+<scan:XResolution>100</scan:XResolution>
+<scan:YResolution>100</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>200</scan:XResolution>
+<scan:YResolution>200</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>300</scan:XResolution>
+<scan:YResolution>300</scan:YResolution>
+</scan:DiscreteResolution>
+<scan:DiscreteResolution>
+<scan:XResolution>600</scan:XResolution>
+<scan:YResolution>600</scan:YResolution>
+</scan:DiscreteResolution>
+</scan:DiscreteResolutions>
+</scan:SupportedResolutions>
+<scan:ColorSpaces>
+<scan:ColorSpace>CMYK</scan:ColorSpace>
+<scan:ColorSpace>YCC</scan:ColorSpace>
+<scan:ColorSpace>sRGB</scan:ColorSpace>
+</scan:ColorSpaces>
+<scan:CcdChannels>
+<scan:CcdChannel>Red</scan:CcdChannel>
+<scan:CcdChannel>Green</scan:CcdChannel>
+<scan:CcdChannel>Blue</scan:CcdChannel>
+<scan:CcdChannel>NTSC</scan:CcdChannel>
+<scan:CcdChannel>GrayCcd</scan:CcdChannel>
+<scan:CcdChannel>GrayCcdEmulated</scan:CcdChannel>
+</scan:CcdChannels>
+<scan:BinaryRenderings>
+<scan:BinaryRendering>Halftone</scan:BinaryRendering>
+<scan:BinaryRendering>Threshold</scan:BinaryRendering>
+</scan:BinaryRenderings>
+</scan:SettingProfile>
+</scan:SettingProfiles>
+<scan:SupportedIntents>
+<scan:Intent>Document</scan:Intent>
+<scan:Intent>TextAndGraphic</scan:Intent>
+<scan:Intent>Photo</scan:Intent>
+<scan:Intent>Preview</scan:Intent>
+</scan:SupportedIntents>
+<scan:MaxOpticalXResolution>600</scan:MaxOpticalXResolution>
+<scan:MaxOpticalYResolution>600</scan:MaxOpticalYResolution>
+<scan:RiskyLeftMargin>0</scan:RiskyLeftMargin>
+<scan:RiskyRightMargin>0</scan:RiskyRightMargin>
+<scan:RiskyTopMargin>0</scan:RiskyTopMargin>
+<scan:RiskyBottomMargin>0</scan:RiskyBottomMargin>
+<scan:MaxPhysicalWidth>2550</scan:MaxPhysicalWidth>
+<scan:MaxPhysicalHeight>4200</scan:MaxPhysicalHeight>
+</scan:AdfDuplexInputCaps>
+<scan:FeederCapacity>50</scan:FeederCapacity>
+<scan:AdfOptions>
+<scan:AdfOption>DetectPaperLoaded</scan:AdfOption>
+<scan:AdfOption>Duplex</scan:AdfOption>
+</scan:AdfOptions>
+</scan:Adf>
+<scan:CompressionFactorSupport>
+<scan:Min>1</scan:Min>
+<scan:Max>3</scan:Max>
+<scan:Normal>2</scan:Normal>
+<scan:Step>1</scan:Step>
+</scan:CompressionFactorSupport>
+</scan:ScannerCapabilities>

modules/brother/cmd/brother/testdata/escl/doc-headers-feeder.txt

@@ -0,0 +1,6 @@
+HTTP/1.1 200 OK
+Content-Location: /eSCL/ScanJobs/1b61ed02-ccda-11f1-809a-94ddf83ec78a/doc-33
+Accept-Encoding: identity
+Content-Type: image/jpeg
+Transfer-Encoding: chunked
+

modules/brother/cmd/brother/testdata/escl/doc-headers.txt

@@ -0,0 +1,6 @@
+HTTP/1.1 200 OK
+Content-Location: /eSCL/ScanJobs/7320ead5-ccb0-11f1-8ff9-94ddf83ec78a/doc-1
+Accept-Encoding: identity
+Content-Type: image/jpeg
+Transfer-Encoding: chunked
+

modules/brother/cmd/brother/testdata/escl/post-headers.txt

@@ -0,0 +1,10 @@
+HTTP/1.1 201 Created
+Cache-Control: no-store
+Accept-Encoding: identity
+X-Frame-Options: DENY
+Content-Length: 0
+Content-Type: text/xml
+Connection: close
+Pragma: no-cache
+Location: http://192.168.1.171/eSCL/ScanJobs/7320ead5-ccb0-11f1-8ff9-94ddf83ec78a
+

modules/brother/cmd/brother/testdata/escl/settings.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><scan:ScanSettings xmlns:scan="http://schemas.hp.com/imaging/escl/2011/05/03" xmlns:pwg="http://www.pwg.org/schemas/2010/12/sm"><pwg:Version>2.0</pwg:Version><scan:Intent>Document</scan:Intent><pwg:ScanRegions><pwg:ScanRegion><pwg:ContentRegionUnits>escl:ThreeHundredthsOfInches</pwg:ContentRegionUnits><pwg:XOffset>0</pwg:XOffset><pwg:YOffset>0</pwg:YOffset><pwg:Width>2480</pwg:Width><pwg:Height>3508</pwg:Height></pwg:ScanRegion></pwg:ScanRegions><pwg:InputSource>Feeder</pwg:InputSource><scan:ColorMode>RGB24</scan:ColorMode><pwg:DocumentFormat>image/jpeg</pwg:DocumentFormat><scan:XResolution>200</scan:XResolution><scan:YResolution>200</scan:YResolution><scan:Duplex>true</scan:Duplex></scan:ScanSettings>

modules/brother/cmd/brother/testdata/escl/status-after.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><scan:ScannerStatus xmlns:pwg="http://www.pwg.org/schemas/2010/12/sm" xmlns:scan="http://schemas.hp.com/imaging/escl/2011/05/03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.hp.com/imaging/escl/2011/05/03 ../../schemas/eSCL-1_92.xsd"><pwg:Version>2.93</pwg:Version><pwg:State>Idle</pwg:State><scan:AdfState>ScannerAdfEmpty</scan:AdfState><scan:Jobs><scan:JobInfo><pwg:JobUri>/eSCL/ScanJobs/7320ead5-ccb0-11f1-8ff9-94ddf83ec78a</pwg:JobUri><pwg:JobUuid>urn:uuid:7320ead5-ccb0-11f1-8ff9-94ddf83ec78a</pwg:JobUuid><scan:Age>9291071</scan:Age><pwg:ImagesCompleted>1</pwg:ImagesCompleted><pwg:ImagesToTransfer>1</pwg:ImagesToTransfer><pwg:JobState>Completed</pwg:JobState><pwg:JobStateReasons><pwg:JobStateReason>JobCompletedSuccessfully</pwg:JobStateReason></pwg:JobStateReasons></scan:JobInfo></scan:Jobs></scan:ScannerStatus>

modules/brother/cmd/brother/testdata/escl/status-idle.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><scan:ScannerStatus xmlns:pwg="http://www.pwg.org/schemas/2010/12/sm" xmlns:scan="http://schemas.hp.com/imaging/escl/2011/05/03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.hp.com/imaging/escl/2011/05/03 ../../schemas/eSCL-1_92.xsd"><pwg:Version>2.93</pwg:Version><pwg:State>Idle</pwg:State><scan:AdfState>ScannerAdfEmpty</scan:AdfState><scan:Jobs><scan:JobInfo><pwg:JobUri>/eSCL/ScanJobs/7320ead5-ccb0-11f1-8ff9-94ddf83ec78a</pwg:JobUri><pwg:JobUuid>urn:uuid:7320ead5-ccb0-11f1-8ff9-94ddf83ec78a</pwg:JobUuid><scan:Age>9292192</scan:Age><pwg:ImagesCompleted>1</pwg:ImagesCompleted><pwg:ImagesToTransfer>1</pwg:ImagesToTransfer><pwg:JobState>Completed</pwg:JobState><pwg:JobStateReasons><pwg:JobStateReason>JobCompletedSuccessfully</pwg:JobStateReason></pwg:JobStateReasons></scan:JobInfo></scan:Jobs></scan:ScannerStatus>

modules/brother/cmd/brother/testdata/pin/ecdsa.pem

@@ -0,0 +1,10 @@
+-----BEGIN CERTIFICATE-----
+MIIBVzCB/qADAgECAgQoWaUiMAoGCCqGSM49BAMCMCAxHjAcBgNVBAMTFUJSVzU4
+Q0RDOURGQzgwQi5sb2NhbDAgFw0wMDAxMDEwMDAwMDBaGA8yMTEwMTIzMTIzNTk1
+OVowIDEeMBwGA1UEAxMVQlJXNThDREM5REZDODBCLmxvY2FsMFkwEwYHKoZIzj0C
+AQYIKoZIzj0DAQcDQgAENrR0q9JKcMSypD7yVGMzXpaarlLA3nc4ju1gh9ymeqjy
+xyfdiAy08GgvGKZMv+EaqH1xoAaaglmF8Dhgn0GrS6MkMCIwIAYDVR0RBBkwF4IV
+QlJXNThDREM5REZDODBCLmxvY2FsMAoGCCqGSM49BAMCA0gAMEUCIQCTpBb5+82s
+f/OXfEA77SJREW+6UHFgaDruuJ06wdTouwIgUUr5FkoGzsunwrYAZmqcBw96UKK5
+o5tz3ZLrtSke6VM=
+-----END CERTIFICATE-----

modules/brother/cmd/brother/testdata/pin/rsa.pem

@@ -0,0 +1,18 @@
+-----BEGIN CERTIFICATE-----
+MIIC5DCCAcygAwIBAgIEIvomBDANBgkqhkiG9w0BAQsFADAgMR4wHAYDVQQDExVC
+Ulc1OENEQzlERkM4MEIubG9jYWwwIBcNMDAwMTAxMDAwMDAwWhgPMjExMDEyMzEy
+MzU5NTlaMCAxHjAcBgNVBAMTFUJSVzU4Q0RDOURGQzgwQi5sb2NhbDCCASIwDQYJ
+KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMGbBrytUZsYjcH/d75H1ax+EMKElDWX
+p+bnafu5vB0WooGCG7gYbCGuYJRnI+PtFGEVwPlOQojiGmvuDVO2THs+kefcAi/c
+7inSrD550kBsfWYVVhyZ3e0tK+UsEgTC9QQ0fdi3AFWnS68L93ooPkCgVBCl1B/c
+5VsoGOtdFGgDLPJlmf22KxfSjI2+0cB4/f+VJX+1AoP71s1A4NN8okfuEL+mC1h1
+tbzaT+MLTtgxAFMu//tF3287yVLyG+vSBAbX7pujpBsrzBzv5mn2dZrlPwDjD17w
+oqfjfuu1ERpxn3fpBtexqXV3ybw2ftGGOVtn9kV2Po/vTTfGMgrz33UCAwEAAaMk
+MCIwIAYDVR0RBBkwF4IVQlJXNThDREM5REZDODBCLmxvY2FsMA0GCSqGSIb3DQEB
+CwUAA4IBAQBfP6IfdFsaWyc8FHooiRW/oS9OlZxDUrmUrdNP9doRq7PROM2bCnIZ
+D6q5B34bLFxHmitMLpy3MKV475yrS83ges5k5rlUPlRFIJaSCpNY6xRwUZdGgurX
+h8KdHERXmtCuj1egkTJ9SRAchjlgdQevVJRgeFUCdVZ63NVIBy37zcIVBHOB5R3L
+V9lMijXwV2ow9DnXARdXYeSn98XoOMVNyL8lHESyHPN2cS8fijunudGtoieSA0TK
+NpAr18jfGBYvM35AYwvSFGqo/yECCfKVHup2HykhOqhWnrvv8OyHmsvdYn2s9bx1
+lT903TyZyla6PjeA/8dGj4eJHkVIKv87
+-----END CERTIFICATE-----

modules/brother/files/settings.json

@@ -0,0 +1,9 @@
+{
+  "scanner": "",
+  "scan-folder": "",
+  "printer": "",
+  "printer-certificate": "",
+  "resolution": 300,
+  "color-mode": "color",
+  "crop": true
+}

modules/brother/files/store.json

@@ -0,0 +1,9 @@
+{
+  "scheme": "${bound:s3-bucket:scheme}",
+  "at": "${bound:s3-bucket:at}",
+  "port": "${bound:s3-bucket:port}",
+  "bucket": "${bound:s3-bucket:bucket}",
+  "region": "${bound:s3-bucket:region}",
+  "key": "${bound:s3-bucket:as}",
+  "secret": "${secret:s3-bucket}"
+}

modules/brother/go.mod

@@ -1,22 +1,22 @@
-module mesh-delivery
+module brother
 
-go 1.25.0
+go 1.26.0
 
 require (
-	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013182924-5933eb757d44
+	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020060201-88581d0acaef
 	github.com/nats-io/nats-server/v2 v2.11.17
-	github.com/nats-io/nats.go v1.51.0
+	github.com/nats-io/nats.go v1.54.0
 )
 
 require (
 	github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op // indirect
 	github.com/google/go-tpm v0.9.8 // indirect
-	github.com/klauspost/compress v1.18.5 // indirect
+	github.com/klauspost/compress v1.20.0 // indirect
 	github.com/minio/highwayhash v1.0.4 // indirect
 	github.com/nats-io/jwt/v2 v2.8.1 // indirect
-	github.com/nats-io/nkeys v0.4.15 // indirect
+	github.com/nats-io/nkeys v0.4.16 // indirect
 	github.com/nats-io/nuid v1.0.1 // indirect
-	golang.org/x/crypto v0.50.0 // indirect
+	golang.org/x/crypto v0.57.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/sys v0.48.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
 )

modules/brother/go.sum

@@ -0,0 +1,27 @@
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020060201-88581d0acaef h1:xy3wuGWJpqMAXYdXolocYG6w9xnWqBltVUffoaziIKo=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020060201-88581d0acaef/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
+github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op h1:Z/MZK75wC/NSrkgqeNIa7jexam9uWzhLmFTSCPI/kn0=
+github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op/go.mod h1:FQyySiasQQM8735Ddel3MRojmy4dA1IqCeyJ5jmPMbI=
+github.com/google/go-tpm v0.9.8 h1:slArAR9Ft+1ybZu0lBwpSmpwhRXaa85hWtMinMyRAWo=
+github.com/google/go-tpm v0.9.8/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
+github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA=
+github.com/klauspost/compress v1.20.0/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
+github.com/minio/highwayhash v1.0.4 h1:asJizugGgchQod2ja9NJlGOWq4s7KsAWr5XUc9Clgl4=
+github.com/minio/highwayhash v1.0.4/go.mod h1:GGYsuwP/fPD6Y9hMiXuapVvlIUEhFhMTh0rxU3ik1LQ=
+github.com/nats-io/jwt/v2 v2.8.1 h1:V0xpGuD/N8Mi+fQNDynXohVvp7ZztevW5io8CUWlPmU=
+github.com/nats-io/jwt/v2 v2.8.1/go.mod h1:nWnOEEiVMiKHQpnAy4eXlizVEtSfzacZ1Q43LIRavZg=
+github.com/nats-io/nats-server/v2 v2.11.17 h1:GKEghcFK6A+aFx11Yf1LjgLC3txAwvyhnYzhBIQZA8I=
+github.com/nats-io/nats-server/v2 v2.11.17/go.mod h1:B1sFVz4StNosQ903ak4N1G01Fl/9f8e06mXpFIE2K24=
+github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
+github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
+github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
+github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
+github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
+github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
+golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
+golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
+golang.org/x/sys v0.21.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=

modules/brother/module.json

@@ -0,0 +1,280 @@
+{
+  "module": "brother",
+  "version": "1",
+  "requires": [
+    "s3-bucket"
+  ],
+  "binds": {
+    "s3-bucket": "${dir:state}/store-binding.json"
+  },
+  "secrets": {
+    "s3-bucket": "${dir:state}/store.secret"
+  },
+  "config": {
+    "scanner": {
+      "type": "string",
+      "description": "The network scanner's eSCL address, such as http://192.0.2.10/eSCL: the scanner's own address and the path its eSCL service answers on; the operator's, with no default.",
+      "pattern": "^https?://.+",
+      "trusted": true,
+      "required": true
+    },
+    "scan-folder": {
+      "type": "string",
+      "description": "The absolute path of the folder the scans are filed in as PDF files; the module makes it when it files the first scan, and never touches a file in it that it did not write. The operator's, with no default.",
+      "pattern": "^/.+$",
+      "trusted": true,
+      "required": true
+    },
+    "printer": {
+      "type": "string",
+      "description": "The printer's host, such as 192.0.2.10: where its admin page (HTTPS) and its IPP service answer. The device is the scanner's own; the operator's, with no default.",
+      "pattern": "^[A-Za-z0-9.:-]+$",
+      "trusted": true,
+      "required": true
+    },
+    "printer-certificate": {
+      "type": "string",
+      "description": "The SHA-256 fingerprint of the certificate the printer's admin page serves, as 32 upper-case hex pairs joined by colons; several, separated by commas, when the printer serves more than one (it serves an ECDSA and an RSA certificate for one name). The module trusts those certificates alone and refuses any other; the operator's, with no default.",
+      "pattern": "^([0-9A-F]{2}:){31}[0-9A-F]{2}(, *([0-9A-F]{2}:){31}[0-9A-F]{2})*$",
+      "trusted": true,
+      "required": true
+    },
+    "resolution": {
+      "type": "number",
+      "description": "The resolution asked of the scanner, in dpi: 100, 200, 300 or 600. A scanner may give another; the scan is filed at the resolution it gave.",
+      "enum": [
+        100,
+        200,
+        300,
+        600
+      ],
+      "trusted": false,
+      "default": 300
+    },
+    "color-mode": {
+      "type": "string",
+      "description": "Whether the scan is in colour or in grays: color or gray.",
+      "enum": [
+        "color",
+        "gray"
+      ],
+      "trusted": false,
+      "default": "color"
+    },
+    "crop": {
+      "type": "boolean",
+      "description": "Whether the document is cut out of the platen's white lid; false files the whole platen. A feeder scan is never cropped.",
+      "trusted": false,
+      "default": true
+    }
+  },
+  "own-secrets": {
+    "admin-password": {
+      "path": "${dir:state}/admin-password.secret",
+      "issued-by": "outside",
+      "prompt": "the admin password of the Brother printer",
+      "owner": "brother-device"
+    },
+    "broker-device": {
+      "path": "${dir:state}/broker-device.secret",
+      "owner": "brother-device"
+    }
+  },
+  "streams": [
+    {
+      "name": "device-asks",
+      "events": [
+        "device.asked"
+      ],
+      "max-age-days": 1,
+      "max-mib": 8,
+      "retention": "work-queue",
+      "max-deliveries": 3,
+      "duplicates": 24
+    }
+  ],
+  "state": [
+    {
+      "name": "device-answers",
+      "ttl-seconds": 600
+    }
+  ],
+  "seats": [
+    {
+      "name": "scanner",
+      "scope": "mesh",
+      "serves": [
+        "scan",
+        "status",
+        "list",
+        "document"
+      ]
+    },
+    {
+      "name": "printer",
+      "scope": "mesh",
+      "serves": [
+        "status",
+        "settings",
+        "print",
+        "upload"
+      ]
+    }
+  ],
+  "claims": [
+    {
+      "name": "scanner",
+      "scope": "mesh",
+      "serves": [
+        "scan",
+        "status",
+        "list",
+        "document"
+      ]
+    },
+    {
+      "name": "printer",
+      "scope": "mesh",
+      "serves": [
+        "status",
+        "settings",
+        "print",
+        "upload"
+      ]
+    }
+  ],
+  "emits": [
+    "scan.added"
+  ],
+  "tools": [
+    "scanner.scan",
+    "scanner.status",
+    "scanner.list",
+    "scanner.document",
+    "printer.status",
+    "printer.settings",
+    "printer.print",
+    "printer.upload",
+    "brother_health"
+  ],
+  "resources": [
+    {
+      "id": "account",
+      "type": "user",
+      "name": "brother-device",
+      "shell": "/usr/bin/nologin"
+    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0711",
+      "owner": "${machine:account}",
+      "place": ".",
+      "unknown": "program"
+    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.json",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "takes-config": [
+        "scanner",
+        "scan-folder",
+        "printer",
+        "printer-certificate",
+        "resolution",
+        "color-mode",
+        "crop"
+      ],
+      "merge": "json",
+      "template": "files/settings.json",
+      "trusted": true
+    },
+    {
+      "id": "store",
+      "type": "file",
+      "path": "${dir:state}/store.json",
+      "owner": "brother-device",
+      "mode": "0600",
+      "template": "files/store.json"
+    },
+    {
+      "id": "device",
+      "type": "process",
+      "name": "brother-device",
+      "artifact": "tools",
+      "run": [
+        "./brother",
+        "device"
+      ],
+      "user": "brother-device",
+      "env": {
+        "BROTHER_SETTINGS": "${dir:state}/settings.json",
+        "BROTHER_ADMIN_PASSWORD": "${dir:state}/admin-password.secret",
+        "BROTHER_BROKER": "${dir:state}/broker-device.secret",
+        "BROTHER_STORE": "${dir:state}/store.json"
+      },
+      "restart-on": [
+        "settings",
+        "store"
+      ],
+      "bus": {
+        "queues": [
+          "device-asks"
+        ],
+        "state": [
+          "device-answers"
+        ],
+        "emits": [
+          "scan.added"
+        ]
+      },
+      "health": {
+        "kind": "unit"
+      }
+    },
+    {
+      "id": "watch",
+      "type": "process",
+      "name": "brother-watch",
+      "artifact": "tools",
+      "run": [
+        "./brother",
+        "watch"
+      ],
+      "user": "brother-device",
+      "health": {
+        "kind": "tool",
+        "tool": "brother_health",
+        "interval": "60s",
+        "timeout": "10s",
+        "looks": 2,
+        "grace": "60s"
+      }
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/brother",
+        "binary": "brother",
+        "loads": [
+          "brother"
+        ],
+        "env": {
+          "BROTHER_SETTINGS": "${dir:state}/settings.json"
+        }
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
+      }
+    ]
+  }
+}

modules/gitea/README.md

@@ -44,7 +44,7 @@ base64-encoded. The Go bundle `cmd/forge` serves the commit, and the reads an ag
 
 | tool | | what |
 |---|---|---|
-| `gitea_commit` | a | one commit on a branch of its own, created from `base` (default the default branch) when absent, carrying either `files` (each `{path, content \| content_base64 \| delete: true}`) `patch` (a unified diff, as `git diff` writes it), or `patch_file` with `patch_sha256` (a patch too large to type, see below); answers the commit and its parent |
+| `gitea_commit` | a | one commit on a branch of its own, created from `base` (default the default branch) when absent, carrying either `files` (each `{path, content \| content_base64 \| delete: true \| copy_from}`; `copy_from` `{owner, repo, ref, path}` copies a file, or every file under a directory recursively to the same relative paths, of another forge repository, read by the module at one commit sha resolved from `ref` once and named per entry in the answer; files only, a symlink is refused; the copied files count against the 200 files, 4 MiB each and 16 MiB together, and a copy over them is refused naming the count and size, to be split by subdirectory) `patch` (a unified diff, as `git diff` writes it), or `patch_file` with `patch_sha256` (a patch too large to type, see below); answers the commit and its parent |
 | `gitea_commits` | r | a ref's history, newest first, optionally only commits touching a path: sha, author, date, subject |
 | `gitea_compare` | r | what head holds that base does not: its commits and the files they touch |
 | `gitea_pull_reviews` | r | a pull request's reviews — state, the commit reviewed and whether it is the head now, stale, dismissed — with their line comments |

modules/gitea/client.ts

@@ -3,6 +3,7 @@
 // gitea. Both this module's tools and its events entrypoint import it, and nothing outside gitea
 // does.
 
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { ConfiguredToken, MintedToken, type TokenSource } from "./token.js";
 import { MAIN_BRANCH, mainRuleBody, protectionBody, type BranchProtection, type ProtectionWanted } from "./protection.js";
@@ -21,6 +22,19 @@ function commitSegment(sha: unknown): string {
   if (!isCommit(v)) throw new Refused(`${JSON.stringify(sha)} is not a commit. Nothing was sent`);
   return v;
 }
+/** git's hash of a tree from its entries: sha1 of "tree <length>\0" and, for each entry in git's order (byte order of the
+ *  name, a tree compared as its name and a slash), "<mode> <name>\0" and the 20 raw bytes of its sha. git writes a
+ *  tree's mode 40000 where the forge says 040000. */
+export function gitTreeHash(entries: { path: string; mode: string; type: string; sha: string }[]): string {
+  const ordered = entries
+    .map((e) => ({ e, key: Buffer.from(e.path + (e.type === "tree" ? "/" : "")) }))
+    .sort((a, b) => Buffer.compare(a.key, b.key));
+  const body = Buffer.concat(ordered.map(({ e }) => {
+    if (!/^[0-9a-f]{40}$/i.test(String(e.sha))) throw new Error(`the forge named no sha for ${e.path}`);
+    return Buffer.concat([Buffer.from(`${String(e.mode).replace(/^0+/, "")} ${e.path}\0`), Buffer.from(e.sha, "hex")]);
+  }));
+  return createHash("sha1").update(Buffer.concat([Buffer.from(`tree ${body.length}\0`), body])).digest("hex");
+}
 export type { BranchProtection, ProtectionWanted } from "./protection.js";
 
 /** A repository, trimmed to what the mesh cares about. */
@@ -92,6 +106,8 @@ export interface OpenPull {
   repo: string;
   number: number;
   base: string;
+  /** The pull request's head branch: what a delivery group is named by (novox/hq ADR 0249). */
+  head?: string;
   head_sha: string;
   html_url?: string;
   /** The contexts the base branch's protection requires; none when it requires none, or cannot be read. */
@@ -374,7 +390,7 @@ export class GiteaClient {
       const rule = rules.get(base);
       const checks = await this.headChecks(found.owner, found.name, pull.head_sha);
       const labels = found.labels ?? [];
-      out.push({ owner: found.owner, repo: found.name, number: pull.number, base: pull.base ?? "", head_sha: pull.head_sha,
+      out.push({ owner: found.owner, repo: found.name, number: pull.number, base: pull.base ?? "", head: pull.head, head_sha: pull.head_sha,
         html_url: pull.html_url, required: rule?.enable_status_check ? (rule.status_check_contexts ?? []) : [],
         statuses: Object.keys(checks), checks, labels: labels.map((l) => l.name) });
     }
@@ -510,6 +526,43 @@ export class GiteaClient {
     return out;
   }
 
+  /** **A commit's trees: its root, and the tree of every directory that holds a `module.json`** (novox/hq issue 1234,
+   *  ADR 0437 §4 and §5), from the forge's one recursive listing of the commit, read page by page. A directory is
+   *  spelled as the repository spells it, no slash at either end, the root as `""`.
+   *
+   *  **A listing the forge cut is no listing** (it says `truncated` on a page with nothing more to read, or the pages
+   *  run past a bound): the call fails naming the repository and the commit, never answering the directories it did
+   *  see, since a directory left out would be taken for one without a module. Reads only. */
+  async commitTrees(owner: string, repo: string, sha: string): Promise<{ root: string; trees: Record<string, string> }> {
+    const base = `${repoPath(owner, repo)}/git/trees/${commitSegment(sha)}?recursive=true`;
+    const cut = (why: string) => new Error(`the forge's tree listing of ${owner}/${repo} at ${sha} was cut (${why}); no trees are answered from a part`);
+    const entries: any[] = [];
+    for (let page = 1; ; page++) {
+      if (page > 200) throw cut("more than 200 pages");
+      const got = await this.request<any>(`${base}&page=${page}&per_page=1000`);
+      if (!Array.isArray(got?.tree)) throw new Error(`the forge's tree listing of ${owner}/${repo} at ${sha} has no tree`);
+      entries.push(...got.tree);
+      if (got.truncated !== true) break;
+      // Truncated with nothing more to ask for: the forge itself could not give the rest.
+      if (got.tree.length === 0 || entries.length >= Number(got.total_count ?? 0)) throw cut("truncated");
+    }
+    // **The listing's top `sha` is the commit's, not the root tree's** (seen live, novox/mesh-delivery at 7f61817), so the
+    // root tree is hashed from the root's own entries, as git does (gitTreeHash).
+    const root = gitTreeHash(entries.filter((e) => typeof e?.path === "string" && !e.path.includes("/")));
+    const trees: Record<string, string> = {};
+    const dirOf = new Map<string, string>();
+    for (const e of entries) if (e?.type === "tree" && typeof e.path === "string") dirOf.set(e.path, String(e.sha));
+    for (const e of entries) {
+      if (e?.type !== "blob" || typeof e.path !== "string") continue;
+      if (e.path !== "module.json" && !e.path.endsWith("/module.json")) continue;
+      const dir = e.path === "module.json" ? "" : e.path.slice(0, -"/module.json".length);
+      const tree = dir === "" ? root : dirOf.get(dir);
+      if (!tree) throw new Error(`the forge's tree listing of ${owner}/${repo} at ${sha} holds ${e.path} but not the tree of ${dir}`);
+      trees[dir] = tree;
+    }
+    return { root, trees };
+  }
+
   /** Whether a repository holds a file at a commit: true, false for a 404, thrown when the forge cannot say. */
   async holdsFile(owner: string, repo: string, sha: string, file: string): Promise<boolean> {
     return this.exists(`${repoPath(owner, repo)}/contents/${encodePath(file)}?ref=${encodeURIComponent(sha)}`);

modules/gitea/cmd/forge-account-provider/builder_test.go

@@ -0,0 +1,356 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/provider"
+
+	"gitea/internal/forgehttp"
+)
+
+// Issue 1481 (novox/hq ADR 0466 §3): the build modules' keys on one forge user that reads and pushes nothing. The forge
+// is faked with the teams, members and keys it keeps, so a team's shape and a key's right can be read back.
+
+type forgeKey struct {
+	ID       int64
+	Title    string
+	Key      string
+	ReadOnly bool
+}
+
+type teamForge struct {
+	mu      sync.Mutex
+	users   map[string]bool
+	teams   map[string]map[string]any // by name: the shape last sent
+	ids     map[string]int64
+	members map[string][]string // by team name
+	keys    map[string][]forgeKey
+	next    int64
+}
+
+func newTeamForge() *teamForge {
+	return &teamForge{users: map[string]bool{}, teams: map[string]map[string]any{}, ids: map[string]int64{},
+		members: map[string][]string{}, keys: map[string][]forgeKey{}, next: 10}
+}
+
+var (
+	teamRe    = regexp.MustCompile(`^/api/v1/teams/(\d+)(?:/members/([^/]+))?$`)
+	userKeyRe = regexp.MustCompile(`^/api/v1/(?:admin/)?users/([^/]+)/keys(?:/(\d+))?$`)
+)
+
+func (f *teamForge) teamByID(id string) string {
+	for name, n := range f.ids {
+		if fmt.Sprint(n) == id {
+			return name
+		}
+	}
+	return ""
+}
+
+func (f *teamForge) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	body, _ := io.ReadAll(r.Body)
+	var in map[string]any
+	_ = json.Unmarshal(body, &in)
+	reply := func(code int, v any) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(code)
+		if v != nil {
+			_ = json.NewEncoder(w).Encode(v)
+		}
+	}
+	p := r.URL.Path
+	if m := userKeyRe.FindStringSubmatch(p); m != nil {
+		switch r.Method {
+		case http.MethodGet:
+			out := []map[string]any{}
+			for _, k := range f.keys[m[1]] {
+				out = append(out, map[string]any{"id": k.ID, "title": k.Title, "key": k.Key})
+			}
+			reply(200, out)
+		case http.MethodPost:
+			f.next++
+			ro, _ := in["read_only"].(bool)
+			f.keys[m[1]] = append(f.keys[m[1]], forgeKey{ID: f.next, Title: in["title"].(string), Key: in["key"].(string), ReadOnly: ro})
+			reply(201, map[string]any{"id": f.next})
+		case http.MethodDelete:
+			var kept []forgeKey
+			for _, k := range f.keys[m[1]] {
+				if fmt.Sprint(k.ID) != m[2] {
+					kept = append(kept, k)
+				}
+			}
+			f.keys[m[1]] = kept
+			reply(204, nil)
+		}
+		return
+	}
+	if m := teamRe.FindStringSubmatch(p); m != nil {
+		name := f.teamByID(m[1])
+		switch {
+		case name == "":
+			reply(404, map[string]any{"message": "no team"})
+		case r.Method == http.MethodPatch && m[2] == "":
+			f.teams[name] = in
+			reply(200, map[string]any{})
+		case r.Method == http.MethodPut:
+			for _, u := range f.members[name] {
+				if u == m[2] {
+					reply(204, nil)
+					return
+				}
+			}
+			f.members[name] = append(f.members[name], m[2])
+			reply(204, nil)
+		default:
+			http.Error(w, "unexpected "+r.Method+" "+p, 400)
+		}
+		return
+	}
+	switch {
+	case r.Method == http.MethodGet && strings.HasPrefix(p, "/api/v1/users/"):
+		if !f.users[strings.TrimPrefix(p, "/api/v1/users/")] {
+			reply(404, map[string]any{"message": "no"})
+			return
+		}
+		reply(200, map[string]any{"active": true})
+	case r.Method == http.MethodPost && p == "/api/v1/admin/users":
+		f.users[in["username"].(string)] = true
+		reply(201, map[string]any{})
+	case p == "/api/v1/orgs/novox/teams" && r.Method == http.MethodGet:
+		out := []map[string]any{}
+		for name, id := range f.ids {
+			out = append(out, map[string]any{"id": id, "name": name})
+		}
+		reply(200, out)
+	case p == "/api/v1/orgs/novox/teams" && r.Method == http.MethodPost:
+		f.next++
+		name := in["name"].(string)
+		f.ids[name], f.teams[name] = f.next, in
+		reply(201, map[string]any{"id": f.next})
+	default:
+		http.Error(w, "unexpected "+r.Method+" "+p, 400)
+	}
+}
+
+func (f *teamForge) titles(user string) []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := []string{}
+	for _, k := range f.keys[user] {
+		out = append(out, k.Title)
+	}
+	return out
+}
+
+type teamRig struct {
+	t      *testing.T
+	bus    *fakeBus
+	forge  *teamForge
+	svc    *Service
+	runner *fakeRunner
+}
+
+func newTeamRig(t *testing.T) *teamRig {
+	t.Helper()
+	forge := newTeamForge()
+	srv := httptest.NewServer(forge)
+	t.Cleanup(srv.Close)
+	dir := t.TempDir()
+	pw, host, origins := filepath.Join(dir, "pw"), filepath.Join(dir, "host"), filepath.Join(dir, "origins")
+	for p, c := range map[string]string{pw: "x\n", host: "novox.internal\n", origins: "https://git.novox.be\n"} {
+		if err := os.WriteFile(p, []byte(c), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	runner := &fakeRunner{out: scanned}
+	svc := NewService(Config{Node: "novox", HostFile: host, OriginsFile: origins, Port: 222,
+		Forge: forgehttp.Client{URL: srv.URL, User: "mesh-admin", PasswordFile: pw}, Runner: runner, Log: func(string, ...any) {}})
+	svc.loaded = true
+	svc.loadedFrom["mesh-build-go"], svc.loadedFrom["mesh-build-node"] = true, true
+	return &teamRig{t: t, bus: newBus(), forge: forge, svc: svc, runner: runner}
+}
+
+func (r *teamRig) pass() []provider.Outcome {
+	r.t.Helper()
+	out, err := r.svc.Provider(r.bus).Pass(context.Background())
+	if err != nil {
+		r.t.Fatal(err)
+	}
+	return out
+}
+
+// bind makes module on node bind gitea's forge-account in the assignments mirror.
+func (r *teamRig) bind(node, module string) {
+	r.bus.set(provider.AssignmentsBucket, node+"."+module, []byte(fmt.Sprintf(
+		`{"node":%q,"module":%q,"provisioning":{"provisions":[{"provision":"forge-account","provider":"novox","provider-module":"gitea","as":"mesh_%s"}]}}`,
+		node, module, strings.ReplaceAll(node+"_"+module, "-", "_"))))
+}
+
+func (r *teamRig) unbind(node, module string) {
+	r.bus.mu.Lock()
+	delete(r.bus.buckets[provider.AssignmentsBucket], node+"."+module)
+	r.bus.mu.Unlock()
+}
+
+// key reports a key in module's state keys, of the kind and for the account given.
+func (r *teamRig) key(module, node, account, kind, public string) {
+	b, _ := json.Marshal(map[string]string{"node": node, "account": account, "kind": kind, "public": public,
+		"fingerprint": "SHA256:x", "at": "2026-10-20T10:00:00Z"})
+	r.svc.SourceKeyChanged(module, node+"."+account, b)
+}
+
+const (
+	pubGo   = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGGG"
+	pubNode = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN"
+	pubOps  = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO"
+)
+
+// 1481/AC1: an entry from mesh-build-go on ace: the forge user nox-builder and the team builders are ensured, the team's
+// units are code, read only, on every repository, and the entry's values name nox-builder. The key is registered
+// read-only under its title.
+func TestABuildModulesEntryIsServedAsNoxBuilderInAReadOnlyTeam(t *testing.T) {
+	r := newTeamRig(t)
+	r.bind("ace", "mesh-build-go")
+	r.key("mesh-build-go", "ace", "mesh-build-go", "builder", pubGo+" mesh-build-go@ace (mesh)")
+	r.pass()
+
+	if !r.forge.users["nox-builder"] || r.forge.users["nox-agent"] {
+		t.Errorf("users = %v, want nox-builder alone", r.forge.users)
+	}
+	shape := r.forge.teams["builders"]
+	if shape == nil {
+		t.Fatalf("no team builders: %v", r.forge.teams)
+	}
+	units, _ := json.Marshal(shape["units_map"])
+	if shape["permission"] != "read" || shape["includes_all_repositories"] != true || shape["can_create_org_repo"] != false || string(units) != `{"repo.code":"read"}` {
+		t.Errorf("the team's shape = %v (units %s), want code read on every repository and no other right", shape, units)
+	}
+	if got := strings.Join(r.forge.members["builders"], ","); got != "nox-builder" || len(r.forge.members["agents"]) != 0 {
+		t.Errorf("members = %v", r.forge.members)
+	}
+	keys := r.forge.keys["nox-builder"]
+	if len(keys) != 1 || keys[0].Title != "mesh:ace.mesh-build-go" || !keys[0].ReadOnly {
+		t.Errorf("nox-builder's keys = %+v, want one read-only key titled mesh:ace.mesh-build-go", keys)
+	}
+	e := r.bus.entry(t, "ace.mesh-build-go.forge-account")
+	if e.Values["user"] != "nox-builder" || e.Values["ssh_alias"] != "mesh-forge" || e.Values["host_key"] != "ssh-ed25519 AAAAC3HOSTKEY" {
+		t.Errorf("values = %v", e.Values)
+	}
+}
+
+// 1481/AC2: an entry from ssh-client is what it was: nox-agent, the agents team, a key that may write. (The existing
+// tests of the provider pass unchanged.)
+func TestAnSshClientEntryIsStillTheAgentsWithAKeyThatMayWrite(t *testing.T) {
+	r := newTeamRig(t)
+	// the agents team exists, as the forge has it
+	r.forge.ids["agents"], r.forge.teams["agents"] = 5, map[string]any{}
+	r.bind("g14", "ssh-client")
+	r.key("ssh-client", "g14", "nox", "machine", pubA+" nox@g14 (mesh)")
+	r.pass()
+	if e := r.bus.entry(t, "g14.ssh-client.forge-account"); e.Values["user"] != "nox-agent" {
+		t.Errorf("values = %v", e.Values)
+	}
+	keys := r.forge.keys["nox-agent"]
+	if len(keys) != 1 || keys[0].Title != "mesh:g14.nox" || keys[0].ReadOnly {
+		t.Errorf("nox-agent's keys = %+v, want one key that may write", keys)
+	}
+	if r.forge.teams["builders"] != nil || r.forge.users["nox-builder"] {
+		t.Errorf("a machine's entry made the builders' account or team")
+	}
+	if got := strings.Join(r.forge.members["agents"], ","); got != "nox-agent" {
+		t.Errorf("agents = %v", r.forge.members)
+	}
+}
+
+// 1481/AC3: a builder entry gone: only the keys titled mesh:<node>.mesh-build-go are removed; the user and the team
+// stay, and so do the other build module's key on that machine and a key of the operator's.
+func TestABuilderEntryGoneRemovesItsOwnKeyAndNothingElse(t *testing.T) {
+	r := newTeamRig(t)
+	r.bind("ace", "mesh-build-go")
+	r.bind("ace", "mesh-build-node")
+	r.key("mesh-build-go", "ace", "mesh-build-go", "builder", pubGo+" mesh-build-go@ace (mesh)")
+	r.key("mesh-build-node", "ace", "mesh-build-node", "builder", pubNode+" mesh-build-node@ace (mesh)")
+	r.pass()
+	r.forge.mu.Lock()
+	r.forge.keys["nox-builder"] = append(r.forge.keys["nox-builder"], forgeKey{ID: 99, Title: "my own", Key: pubOps})
+	r.forge.mu.Unlock()
+	if got := strings.Join(r.forge.titles("nox-builder"), ","); got != "mesh:ace.mesh-build-go,mesh:ace.mesh-build-node,my own" {
+		t.Fatalf("before: %s", got)
+	}
+	r.unbind("ace", "mesh-build-go")
+	r.pass()
+	if got := strings.Join(r.forge.titles("nox-builder"), ","); got != "mesh:ace.mesh-build-node,my own" {
+		t.Errorf("after: %s, want only the go module's key gone", got)
+	}
+	if !r.forge.users["nox-builder"] || r.forge.teams["builders"] == nil || len(r.forge.members["builders"]) != 1 {
+		t.Errorf("the user or the team went: users %v, members %v", r.forge.users, r.forge.members)
+	}
+	if r.bus.has("ace.mesh-build-go.forge-account") {
+		t.Errorf("the entry stayed")
+	}
+}
+
+// A build module and ssh-client on one machine each have their own entry, keys, user and team.
+func TestABuildModuleAndSshClientOnOneMachineDoNotShareAnything(t *testing.T) {
+	r := newTeamRig(t)
+	r.forge.ids["agents"], r.forge.teams["agents"] = 5, map[string]any{}
+	r.bind("ace", "ssh-client")
+	r.bind("ace", "mesh-build-go")
+	r.key("ssh-client", "ace", "nox", "machine", pubA+" nox@ace (mesh)")
+	r.key("mesh-build-go", "ace", "mesh-build-go", "builder", pubGo+" mesh-build-go@ace (mesh)")
+	r.pass()
+	if got := strings.Join(r.forge.titles("nox-agent"), ","); got != "mesh:ace.nox" {
+		t.Errorf("nox-agent: %s", got)
+	}
+	if got := strings.Join(r.forge.titles("nox-builder"), ","); got != "mesh:ace.mesh-build-go" {
+		t.Errorf("nox-builder: %s", got)
+	}
+	// ssh-client's entry gone: nox-builder's key stays.
+	r.unbind("ace", "ssh-client")
+	r.pass()
+	if got := strings.Join(r.forge.titles("nox-builder"), ","); got != "mesh:ace.mesh-build-go" {
+		t.Errorf("nox-builder after ssh-client left: %s", got)
+	}
+	if got := strings.Join(r.forge.titles("nox-agent"), ","); got != "" {
+		t.Errorf("nox-agent after ssh-client left: %s", got)
+	}
+}
+
+// A build module's entry waits for its own module's builder key: a machine key of the same node, a key of the wrong
+// kind in the build module's state, or the other build module's key is none.
+func TestABuildModulesEntryWaitsForItsOwnBuilderKey(t *testing.T) {
+	r := newTeamRig(t)
+	r.bind("ace", "mesh-build-go")
+	r.key("ssh-client", "ace", "nox", "machine", pubA)                     // a machine's key
+	r.key("mesh-build-go", "ace", "mesh-build-go", "machine", pubGo)       // the wrong kind in the build module's state
+	r.key("mesh-build-node", "ace", "mesh-build-node", "builder", pubNode) // the other build module's
+	out := r.pass()
+	if r.bus.has("ace.mesh-build-go.forge-account") || len(r.forge.users) != 0 || len(r.forge.teams) != 0 {
+		t.Fatalf("something was made without a builder key: users %v teams %v", r.forge.users, r.forge.teams)
+	}
+	if len(out) != 1 || !strings.Contains(out[0].Why, "mesh-build-go") || !strings.Contains(out[0].Why, "builder key") {
+		t.Errorf("the wait should name the module and the key: %+v", out)
+	}
+}
+
+func TestTheKindOfAModulesKeyAndItsForgeUser(t *testing.T) {
+	for module, want := range map[string]string{"mesh-build-go": "nox-builder", "mesh-build-node": "nox-builder", "ssh-client": "nox-agent", "anything-else": "nox-agent"} {
+		got, err := (&Service{}).valuesForUser("ace", module)
+		if err != nil || got != want {
+			t.Errorf("%s: %q, %v; want %q", module, got, err, want)
+		}
+	}
+}

modules/gitea/cmd/forge-account-provider/main.go

@@ -4,7 +4,10 @@
 // For each machine whose ssh-client binds the provision and has reported its public key (ssh-client's state `keys`),
 // it makes the machine's agent the one forge user nox-agent (in the agents team; ADR 0410), registers the key for
 // it, and serves where and as whom to reach the forge over ssh: the user, the forge machine's mesh name and port, its
-// host key and the two url roots. A public key is no secret, so the provision has no credential.
+// host key and the two url roots. A public key is no secret, so the provision has no credential. For each build
+// module that binds it and has reported its builder key (its own state `keys`), it does the same as the forge user
+// nox-builder, in the builders team that reads the code of every repository and nothing else, with the key read-only
+// (ADR 0466 §3).
 //
 // stdout is the MCP channel; it says what it says on stderr, and never the admin's password.
 package main
@@ -22,6 +25,7 @@ import (
 	stdio "git.novox.be/novox/mesh-sdk/go"
 	"git.novox.be/novox/mesh-sdk/go/provider"
 
+	"gitea/internal/forgeaccount"
 	"gitea/internal/forgehttp"
 )
 
@@ -42,11 +46,12 @@ func (execRunner) Run(ctx context.Context, name string, args ...string) ([]byte,
 	return out, nil
 }
 
-// stateKeys is ssh-client's state `keys` over the runtime (the manifest's `reads` grants it).
+// stateKeys is the state `keys` of one module over the runtime (the manifest's `reads` grants it): ssh-client's for
-type stateKeys struct{}
+// the machines' keys, a build module's for the builders' (ADR 0466 §3).
+type stateKeys struct{ module string }
 
-func (stateKeys) Watch(handle func(key, op string, value []byte, current bool)) error {
+func (k stateKeys) Watch(handle func(key, op string, value []byte, current bool)) error {
-	return stdio.State("ssh-client.keys").Watch("", func(c stdio.StateChange) error {
+	return stdio.State(k.module+".keys").Watch("", func(c stdio.StateChange) error {
 		handle(c.Key, c.Op, c.Value, c.Current)
 		return nil
 	})
@@ -106,14 +111,18 @@ func main() {
 		}
 	}
 	svc.OnKeys = func(string) { go pass() }
-	go func() {
+	// Each module's keys are watched on their own, and a module whose state never answers (a build module that is not
-		if err := svc.WatchKeys(ctx, stateKeys{}); err != nil {
+	// installed) holds back its own entries only.
-			say("the machines' keys are not watched: %v", err)
+	for _, module := range append([]string{SSHClient}, forgeaccount.BuildModules...) {
-			return
+		go func() {
-		}
+			if err := svc.WatchSource(ctx, module, stateKeys{module}); err != nil {
-		say("watching the machines' keys")
+				say("the keys of %s are not watched: %v", module, err)
-		pass()
+				return
-	}()
+			}
+			say("watching the keys of %s", module)
+			pass()
+		}()
+	}
 	go func() {
 		svc.KeepRunning(ctx, p.Run)
 	}()

modules/gitea/cmd/forge-account-provider/service.go

@@ -64,8 +64,11 @@ type Service struct {
 
 	mu     sync.Mutex
 	keys   map[string]machineKey
-	loaded bool   // the machines' keys have been read: until then a node with none has not reported none
+	loaded bool // the machines' keys have been read: until then a node with none has not reported none
-	known  string // the forge's host key line, as the machines write it into known_hosts
+	// loadedFrom says of each build module's state that its keys have been read, as loaded says of ssh-client's: a build
+	// module's state that never answers (the module is not installed) holds back its own entries and no other.
+	loadedFrom map[string]bool
+	known      string // the forge's host key line, as the machines write it into known_hosts
 
 	bound provider.Bus // the bus the entries are written to (set by Provider)
 
@@ -76,14 +79,40 @@ type Service struct {
 
 type machineKey struct {
 	Node, Account, Kind, Public string
+	// Source is the module whose state the key was read from: ssh-client's for a machine's, a build module's for a
+	// builder's. Empty is ssh-client's.
+	Source string
 }
 
+// SSHClient is the module whose `keys` state holds the machines' keys (kind machine); the build modules' states hold
+// the builders' (kind builder, ADR 0466 §2).
+const SSHClient = "ssh-client"
+
+// sourceOf is the module a stored key was read from.
+func (k machineKey) sourceOf() string {
+	if k.Source == "" {
+		return SSHClient
+	}
+	return k.Source
+}
+
+// storageKey is the key a source's key is kept under: a machine's as it is, a builder's under its module's name.
+func storageKey(source, key string) string {
+	if source == "" || source == SSHClient {
+		return key
+	}
+	return source + "/" + key
+}
+
+// kindOf is the kind of key a consumer module's entry is made for.
+func kindOf(module string) string { return forgeaccount.KindOfModule(module) }
+
 // NewService is the service over its environment.
 func NewService(cfg Config) *Service {
 	if cfg.Log == nil {
 		cfg.Log = func(f string, a ...any) { fmt.Fprintf(os.Stderr, "[gitea forge-account] "+f+"\n", a...) }
 	}
-	return &Service{cfg: cfg, keys: map[string]machineKey{}, letGo: map[string]bool{}, Pause: time.Sleep,
+	return &Service{cfg: cfg, keys: map[string]machineKey{}, letGo: map[string]bool{}, loadedFrom: map[string]bool{}, Pause: time.Sleep,
 		accounts: &forgeaccount.Accounts{Forge: cfg.Forge, Log: cfg.Log}}
 }
 
@@ -103,38 +132,67 @@ func (s *Service) Provider(bus provider.Bus) *provider.Provider {
 }
 
 // errNoKey is a consumer whose machine has reported no key yet: nothing is made, and the client says it waits.
-type errNoKey struct{ node string }
+type errNoKey struct{ node, module string }
 
 func (e errNoKey) Error() string {
+	if kind := kindOf(e.module); kind == "builder" {
+		return "no key from " + e.node + " yet: its " + e.module + " has not reported a builder key, so there is no " +
+			"entry to make"
+	}
 	return "no key from " + e.node + " yet: its ssh-client has not reported a machine key, so there is no account " +
 		"and no entry to make"
 }
 
+// sourceOfModule is the module whose state holds the keys a consumer module's entry is made from: a build module's
+// own, ssh-client's for any other consumer.
+func sourceOfModule(module string) string {
+	if kindOf(module) == "builder" {
+		return module
+	}
+	return SSHClient
+}
+
+// scopeFor is the title prefix of the keys one entry registered: every key of a machine for a machine's entry, one
+// build module's key for a builder's (nox-builder holds the keys of every build module of the mesh).
+func scopeFor(kind, node, module string) string {
+	if kind == "builder" {
+		return forgeaccount.BuilderScope(node, module)
+	}
+	return forgeaccount.MachineScope(node)
+}
+
 // Make brings one consumer's account, its team membership and its keys into being, as the machine reported them. It
 // leaves what is as asked alone, so it is asked again freely.
 func (s *Service) Make(ctx context.Context, c provider.Consumer) error {
 	s.making.Lock()
 	defer s.making.Unlock()
 	node := c.Entry.Consumer
-	user := forgeaccount.ForgeUser(node, "machine")
+	module, kind := c.Entry.Module, kindOf(c.Entry.Module)
+	user := forgeaccount.ForgeUser(node, kind)
 	if user == "" {
 		return fmt.Errorf("%q is not a machine's name an account can be named for", node)
 	}
+	source := sourceOfModule(module)
 	s.mu.Lock()
 	loaded := s.loaded
+	if source != SSHClient {
+		loaded = s.loadedFrom[source]
+	}
 	s.mu.Unlock()
 	if !loaded {
 		// After a restart the first pass can come before the keys arrive: nothing is removed or deleted on that.
-		return errors.New("the machines' keys are not read yet, so nothing is made, removed or deleted")
+		return fmt.Errorf("the keys of %s are not read yet, so nothing is made, removed or deleted", source)
 	}
-	have := s.keysOf(node)
+	have := s.keysFrom(source, node, kind)
 	if len(have) == 0 {
-		if err := s.releasePerNodeUser(ctx, node); err != nil {
+		if kind == "machine" {
-			return err
+			if err := s.releasePerNodeUser(ctx, node); err != nil {
+				return err
+			}
 		}
 		// A key the machine no longer reports is no longer wanted (ADR 0400 §2): the mesh's keys go, the operator's
 		// stay, and the entry that served the machine goes with them.
-		if _, err := s.accounts.RemoveKeysTitled(ctx, user, forgeaccount.MachineScope(node)); err != nil {
+		if _, err := s.accounts.RemoveKeysTitled(ctx, user, scopeFor(kind, node, module)); err != nil {
 			return err
 		}
 		if s.bound != nil {
@@ -142,7 +200,7 @@ func (s *Service) Make(ctx context.Context, c provider.Consumer) error {
 				return err
 			}
 		}
-		return errNoKey{node}
+		return errNoKey{node: node, module: module}
 	}
 	if _, err := s.hostName(); err != nil {
 		return err
@@ -154,20 +212,23 @@ func (s *Service) Make(ctx context.Context, c provider.Consumer) error {
 	if err := s.accounts.EnsureAccount(ctx, user); err != nil {
 		return err
 	}
-	if err := s.accounts.EnsureInTeam(ctx, user); err != nil {
+	if err := s.accounts.EnsureInTeamOf(ctx, forgeaccount.TeamOfUser(user), user); err != nil {
 		return err
 	}
 	var wanted []forgeaccount.WantedKey
 	for _, k := range have {
-		wanted = append(wanted, forgeaccount.WantedKey{Title: forgeaccount.KeyTitle(k.Node, k.Account), Key: k.Public})
+		// A builder's key may read and never push (ADR 0466 §3): the key says it beside the team that does.
+		wanted = append(wanted, forgeaccount.WantedKey{Title: forgeaccount.KeyTitle(k.Node, k.Account), Key: k.Public, ReadOnly: kind == "builder"})
 	}
 	// The forge holds one public key on one user only, so the key leaves agent-<node> before it joins nox-agent. That
 	// is done here, after everything that can fail before it, so the window in which the machine's key is on no user
 	// is only the span between these two calls; if the add fails, the next pass (at most ten minutes) puts it back.
-	if err := s.releasePerNodeUser(ctx, node); err != nil {
+	if kind == "machine" {
-		return err
+		if err := s.releasePerNodeUser(ctx, node); err != nil {
+			return err
+		}
 	}
-	if err := s.accounts.EnsureKeys(ctx, user, forgeaccount.MachineScope(node), wanted); err != nil {
+	if err := s.accounts.EnsureKeys(ctx, user, scopeFor(kind, node, module), wanted); err != nil {
 		return err
 	}
 	s.mu.Lock()
@@ -176,20 +237,25 @@ func (s *Service) Make(ctx context.Context, c provider.Consumer) error {
 	return nil
 }
 
-// Gone removes the keys the mesh registered for a machine that no longer binds the forge. The account stays: it may
+// Gone removes the keys the mesh registered for a machine (or, for a build module, the module's key on that machine)
+// that no longer binds the forge. The account stays: it may
 // hold what the machine's agent wrote, and the keys of the operator's own that were added by hand are not touched
 // (ADR 0399 §2).
 func (s *Service) Gone(ctx context.Context, e provider.Entry) error {
 	s.making.Lock()
 	defer s.making.Unlock()
-	user := forgeaccount.ForgeUser(e.Consumer, "machine")
+	kind := kindOf(e.Module)
+	user := forgeaccount.ForgeUser(e.Consumer, kind)
 	if user == "" {
 		return nil
 	}
-	if err := s.releasePerNodeUser(ctx, e.Consumer); err != nil {
+	if kind == "machine" {
-		return err
+		if err := s.releasePerNodeUser(ctx, e.Consumer); err != nil {
+			return err
+		}
 	}
-	_, err := s.accounts.RemoveKeysTitled(ctx, user, forgeaccount.MachineScope(e.Consumer))
+	// A builder's entry gone removes that entry's key only: the user and the team serve the other machines.
+	_, err := s.accounts.RemoveKeysTitled(ctx, user, scopeFor(kind, e.Consumer, e.Module))
 	return err
 }
 
@@ -220,17 +286,24 @@ func (s *Service) releasePerNodeUser(ctx context.Context, node string) error {
 }
 
 // KeyChanged takes in one machine key as the bus keeps it, and tells OnKeys its node.
-func (s *Service) KeyChanged(key string, value []byte) {
+func (s *Service) KeyChanged(key string, value []byte) { s.SourceKeyChanged(SSHClient, key, value) }
-	if node := s.store(key, value); node != "" && s.OnKeys != nil {
+
+// KeyGone forgets one machine key, and tells OnKeys its node.
+func (s *Service) KeyGone(key string) { s.SourceKeyGone(SSHClient, key) }
+
+// SourceKeyChanged takes in one key of the state `keys` of the module source (ssh-client's, or a build module's), and
+// tells OnKeys its node.
+func (s *Service) SourceKeyChanged(source, key string, value []byte) {
+	if node := s.storeFrom(source, key, value); node != "" && s.OnKeys != nil {
 		s.OnKeys(node)
 	}
 }
 
-// KeyGone forgets one machine key, and tells OnKeys its node.
+// SourceKeyGone forgets one key of the module source's state, and tells OnKeys its node.
-func (s *Service) KeyGone(key string) {
+func (s *Service) SourceKeyGone(source, key string) {
 	node, _, _ := strings.Cut(key, ".")
 	s.mu.Lock()
-	delete(s.keys, key)
+	delete(s.keys, storageKey(source, key))
 	s.mu.Unlock()
 	if s.OnKeys != nil {
 		s.OnKeys(node)
@@ -240,24 +313,38 @@ func (s *Service) KeyGone(key string) {
 // store keeps a machine key that reads as one: its node and account the key's own, and a public half that is a
 // public key line and nothing private. It answers the node, or "" for a value it did not keep (and drops what was
 // kept under that key, since the key now says something else).
-func (s *Service) store(key string, value []byte) string {
+func (s *Service) store(key string, value []byte) string { return s.storeFrom(SSHClient, key, value) }
+
+// storeFrom is store for a key of the module source's state.
+func (s *Service) storeFrom(source, key string, value []byte) string {
 	node, account, _ := strings.Cut(key, ".")
+	stored := storageKey(source, key)
 	var k machineKey
 	var raw struct {
 		Node, Account, Kind, Public string
 	}
 	err := json.Unmarshal(value, &raw)
-	k = machineKey(raw)
+	k = machineKey{Node: raw.Node, Account: raw.Account, Kind: raw.Kind, Public: raw.Public}
+	if source != SSHClient {
+		k.Source = source
+	}
 	s.mu.Lock()
 	defer s.mu.Unlock()
-	if err != nil || k.Node != node || k.Account != account || !publicKeyLine(k.Public) {
+	if want := kindOf(source); err == nil && k.Kind != want && k.Node == node && k.Account == account {
-		if _, had := s.keys[key]; had {
+		// Each state holds one kind: ssh-client's the machines', a build module's the builders' (ADR 0466 §2). The other
-			delete(s.keys, key)
+		// kind in either is not this entry's to serve, and is said.
-		}
+		delete(s.keys, stored)
-		s.cfg.Log("the key %s is not a machine's public key; it is not registered", key)
+		s.cfg.Log("the key %s in the state keys of %s is of kind %q, not %q; it is ignored", key, source, k.Kind, want)
 		return ""
 	}
-	s.keys[key] = k
+	if err != nil || k.Node != node || k.Account != account || !publicKeyLine(k.Public) {
+		if _, had := s.keys[stored]; had {
+			delete(s.keys, stored)
+		}
+		s.cfg.Log("the key %s of %s is not a public key that can be registered; it is not registered", key, source)
+		return ""
+	}
+	s.keys[stored] = k
 	return node
 }
 
@@ -267,12 +354,15 @@ func publicKeyLine(line string) bool {
 }
 
 // keysOf are the machine keys one node reported, by key.
-func (s *Service) keysOf(node string) []machineKey {
+func (s *Service) keysOf(node string) []machineKey { return s.keysFrom(SSHClient, node, "machine") }
+
+// keysFrom are the keys of the kind that one node reported in the module source's state, by key.
+func (s *Service) keysFrom(source, node, kind string) []machineKey {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	var names []string
 	for key, k := range s.keys {
-		if k.Node == node && k.Kind == "machine" && strings.HasPrefix(key, node+".") {
+		if k.Node == node && k.Kind == kind && k.sourceOf() == source && strings.HasPrefix(key, storageKey(source, node+".")) {
 			names = append(names, key)
 		}
 	}
@@ -284,27 +374,37 @@ func (s *Service) keysOf(node string) []machineKey {
 	return out
 }
 
-// WatchKeys keeps the machines' keys as the bus holds them, asking again until the runtime answers (the channel to it
+// WatchKeys keeps the machines' keys as the bus holds them (ssh-client's state `keys`), asking again until the runtime
-// opens as the bundle starts, and the state of ssh-client may arrive after this one). A change after the first
+// answers (the channel to it opens as the bundle starts, and the state of ssh-client may arrive after this one). A
-// values is told to OnKeys; the first values are not, since one pass answers them all.
+// change after the first values is told to OnKeys; the first values are not, since one pass answers them all.
 func (s *Service) WatchKeys(ctx context.Context, src KeySource) error {
+	return s.WatchSource(ctx, SSHClient, src)
+}
+
+// WatchSource is WatchKeys for the state `keys` of any module whose keys the provider registers: ssh-client's, or a
+// build module's (ADR 0466 §3). Once its first values are in, the entries made from them are no longer held back.
+func (s *Service) WatchSource(ctx context.Context, source string, src KeySource) error {
 	waits := []time.Duration{2 * time.Second, 5 * time.Second, 10 * time.Second, 30 * time.Second}
 	for attempt := 0; ; attempt++ {
 		err := src.Watch(func(key, op string, value []byte, current bool) {
 			switch {
 			case op != "put" && current:
 			case op != "put":
-				s.KeyGone(key)
+				s.SourceKeyGone(source, key)
 			case current:
-				s.store(key, value)
+				s.storeFrom(source, key, value)
 			default:
-				s.KeyChanged(key, value)
+				s.SourceKeyChanged(source, key, value)
 			}
 		})
 		if err == nil {
 			// The watch answers once the current values are all handled (stdio KeptState.Watch).
 			s.mu.Lock()
-			s.loaded = true
+			if source == SSHClient {
+				s.loaded = true
+			} else {
+				s.loadedFrom[source] = true
+			}
 			s.mu.Unlock()
 			return nil
 		}
@@ -312,7 +412,7 @@ func (s *Service) WatchKeys(ctx context.Context, src KeySource) error {
 		if attempt < len(waits) {
 			pause = waits[attempt]
 		}
-		s.cfg.Log("the machines' keys cannot be watched yet (%v); asking again in %s", err, pause)
+		s.cfg.Log("the keys of %s cannot be watched yet (%v); asking again in %s", source, err, pause)
 		if ctx.Err() != nil {
 			return ctx.Err()
 		}
@@ -377,9 +477,18 @@ func knownHostLine(scanned, host string, port int) (string, error) {
 	return "", errors.New("the forge's sshd gave no ed25519 host key")
 }
 
+// valuesForUser is the forge user a consumer module's entry is served as.
+func (s *Service) valuesForUser(node, module string) (string, error) {
+	user := forgeaccount.ForgeUser(node, kindOf(module))
+	if user == "" {
+		return "", fmt.Errorf("%q is not a machine's name an account can be named for", node)
+	}
+	return user, nil
+}
+
 // valuesFor are the values served to one machine's consumer (ADR 0400 §3, §4).
-func (s *Service) valuesFor(node string) (map[string]any, error) {
+func (s *Service) valuesFor(node, module string) (map[string]any, error) {
-	user := forgeaccount.ForgeUser(node, "machine")
+	user := forgeaccount.ForgeUser(node, kindOf(module))
 	host, err := s.hostName()
 	if err != nil {
 		return nil, err
@@ -421,7 +530,7 @@ func (b *valuesBus) Put(ctx context.Context, bucket, key string, value []byte) e
 		return err
 	}
 	if e.Refused == "" {
-		extra, err := b.s.valuesFor(e.Consumer)
+		extra, err := b.s.valuesFor(e.Consumer, e.Module)
 		if err != nil {
 			return err
 		}

modules/gitea/cmd/forge-account-provider/watch_test.go

@@ -0,0 +1,162 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// Issue 1482 (novox/hq ADR 0466 §3): the provider watches the build modules' state `keys` beside ssh-client's, and
+// registers each builder entry read-only on nox-builder.
+
+func keyJSON(node, account, kind, public string) []byte {
+	b, _ := json.Marshal(map[string]string{"node": node, "account": account, "kind": kind, "public": public,
+		"fingerprint": "SHA256:x", "at": "2026-10-20T10:00:00Z"})
+	return b
+}
+
+// watched is a team rig whose keys come through watches of the modules' states, as in the running provider.
+type watched struct {
+	*teamRig
+	sources map[string]*fakeKeys
+	passes  *int
+	logs    *[]string
+	mu      *sync.Mutex
+}
+
+func newWatched(t *testing.T) *watched {
+	r := newTeamRig(t)
+	r.svc.loaded, r.svc.loadedFrom = false, map[string]bool{}
+	r.svc.Pause = func(time.Duration) {}
+	n, logs, mu := 0, []string{}, &sync.Mutex{}
+	r.svc.OnKeys = func(string) { n++ }
+	r.svc.cfg.Log = func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() }
+	w := &watched{teamRig: r, sources: map[string]*fakeKeys{}, passes: &n, logs: &logs, mu: mu}
+	for _, module := range []string{"ssh-client", "mesh-build-go", "mesh-build-node"} {
+		w.sources[module] = &fakeKeys{}
+		if err := r.svc.WatchSource(context.Background(), module, w.sources[module]); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return w
+}
+
+func (w *watched) said() string {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return strings.Join(*w.logs, "\n")
+}
+
+// 1482/AC1: a mesh-build-go.keys entry ace.mesh-build-go of kind builder: its public half is registered read-only on
+// nox-builder titled mesh:ace.mesh-build-go.
+func TestABuilderEntryOfABuildModulesStateIsRegisteredReadOnlyOnNoxBuilder(t *testing.T) {
+	w := newWatched(t)
+	w.bind("ace", "mesh-build-go")
+	w.sources["mesh-build-go"].send("ace.mesh-build-go", "put", keyJSON("ace", "mesh-build-go", "builder", pubGo+" mesh-build-go@ace (mesh)"), true)
+	w.pass()
+	keys := w.forge.keys["nox-builder"]
+	if len(keys) != 1 || keys[0].Title != "mesh:ace.mesh-build-go" || !keys[0].ReadOnly || keys[0].Key != pubGo+" mesh-build-go@ace (mesh)" {
+		t.Errorf("nox-builder's keys = %+v", keys)
+	}
+	if !w.svc.loadedFrom["mesh-build-go"] {
+		t.Errorf("the state was watched and its keys are not counted as read")
+	}
+}
+
+// 1482/AC2: that entry changed: the old key is removed and the new one registered; deleted: the key is removed and no key
+// titled otherwise is touched.
+func TestAChangedBuilderEntryReplacesItsKeyAndADeletedOneRemovesIt(t *testing.T) {
+	w := newWatched(t)
+	w.bind("ace", "mesh-build-go")
+	src := w.sources["mesh-build-go"]
+	src.send("ace.mesh-build-go", "put", keyJSON("ace", "mesh-build-go", "builder", pubGo), true)
+	w.pass()
+	w.forge.mu.Lock()
+	w.forge.keys["nox-builder"] = append(w.forge.keys["nox-builder"], forgeKey{ID: 99, Title: "my own", Key: pubOps})
+	w.forge.mu.Unlock()
+
+	before := *w.passes
+	src.send("ace.mesh-build-go", "put", keyJSON("ace", "mesh-build-go", "builder", pubNode), false)
+	if *w.passes != before+1 {
+		t.Errorf("a change asked for %d passes, want 1", *w.passes-before)
+	}
+	w.pass()
+	got := w.forge.keys["nox-builder"]
+	if len(got) != 2 || got[0].Title != "my own" || got[1].Title != "mesh:ace.mesh-build-go" || got[1].Key != pubNode || !got[1].ReadOnly {
+		t.Errorf("after the change: %+v", got)
+	}
+
+	src.send("ace.mesh-build-go", "delete", nil, false)
+	w.pass()
+	if got := strings.Join(w.forge.titles("nox-builder"), ","); got != "my own" {
+		t.Errorf("after the delete: %s, want only the operator's key", got)
+	}
+}
+
+// 1482/AC3: an entry of kind machine in a build module's state, or of kind builder in ssh-client's, is ignored and
+// said in the provider's log.
+func TestAKeyOfTheWrongKindForItsStateIsIgnoredAndSaid(t *testing.T) {
+	w := newWatched(t)
+	w.bind("ace", "mesh-build-go")
+	w.bind("g14", "ssh-client")
+	w.sources["mesh-build-go"].send("ace.mesh-build-go", "put", keyJSON("ace", "mesh-build-go", "machine", pubGo), true)
+	w.sources["ssh-client"].send("g14.nox", "put", keyJSON("g14", "nox", "builder", pubA), true)
+	w.pass()
+	if len(w.forge.users) != 0 || w.bus.has("ace.mesh-build-go.forge-account") || w.bus.has("g14.ssh-client.forge-account") {
+		t.Errorf("a key of the wrong kind was served: users %v", w.forge.users)
+	}
+	said := w.said()
+	for _, want := range []string{`ace.mesh-build-go in the state keys of mesh-build-go is of kind "machine", not "builder"`, `g14.nox in the state keys of ssh-client is of kind "builder", not "machine"`} {
+		if !strings.Contains(said, want) {
+			t.Errorf("the log lacks %q:\n%s", want, said)
+		}
+	}
+}
+
+// A build module's state that never answers holds back its own entries, never a machine's.
+func TestABuildModulesStateThatNeverAnswersHoldsBackOnlyItsOwnEntries(t *testing.T) {
+	w := newWatched(t)
+	w.svc.loadedFrom = map[string]bool{} // mesh-build-go's watch has not answered
+	w.bind("ace", "mesh-build-go")
+	w.bind("g14", "ssh-client")
+	w.sources["ssh-client"].send("g14.nox", "put", keyJSON("g14", "nox", "machine", pubA+" nox@g14 (mesh)"), true)
+	out := w.pass()
+	if !w.bus.has("g14.ssh-client.forge-account") {
+		t.Errorf("a machine's entry waited for a build module's state")
+	}
+	waits := 0
+	for _, o := range out {
+		if strings.Contains(o.Key, "mesh-build-go") && strings.Contains(o.Why, "keys of mesh-build-go are not read yet") {
+			waits++
+		}
+	}
+	if waits != 1 {
+		t.Errorf("outcomes = %+v", out)
+	}
+}
+
+// 1482/AC4 (the provider's half): the manifest reads the states of both build modules beside ssh-client's and the
+// controller's assignments; the provider watches exactly the modules the code names as builders.
+func TestTheManifestReadsTheBuildModulesKeys(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Reads []string `json:"reads"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, state := range []string{"mesh-controller.assignments", "ssh-client.keys", "mesh-build-go.keys", "mesh-build-node.keys"} {
+		if !slices.Contains(m.Reads, state) {
+			t.Errorf("gitea's reads %v lack %q", m.Reads, state)
+		}
+	}
+}

modules/gitea/cmd/forge/commit.go

@@ -25,6 +25,8 @@ type FileChange struct {
 	Content       *string
 	ContentBase64 *string
 	Delete        bool
+	CopyFrom      *CopyFrom // copy_from (novox/hq issue 1365): the content of a file or directory of another repository
+	size          int       // the content's size in bytes, as committed
 }
 
 // CommitAsk is one gitea_commit call.
@@ -51,6 +53,7 @@ type Committed struct {
 	Parent     string          `json:"parent"`
 	Commit     string          `json:"commit"`
 	Files      []CommittedFile `json:"files,omitempty"`
+	Copies     []CopiedFrom    `json:"copies,omitempty"`
 	Said       []string        `json:"said"`
 }
 
@@ -118,6 +121,16 @@ func readCommitAsk(args map[string]any) (CommitAsk, error) {
 				}
 				fc.Delete = b
 			}
+			if v, ok := m["copy_from"]; ok && v != nil {
+				c, err := readCopyFrom(i, v)
+				if err != nil {
+					return a, err
+				}
+				fc.CopyFrom = c
+				if fc.Content != nil || fc.ContentBase64 != nil || fc.Delete {
+					return a, refuse("files[%d] (%s) gives copy_from together with content, content_base64 or delete: it takes exactly one of them. Nothing was sent", i, fc.Path)
+				}
+			}
 			a.Files = append(a.Files, fc)
 		}
 	}
@@ -157,13 +170,13 @@ func readCommitAsk(args map[string]any) (CommitAsk, error) {
 		}
 		seen[fc.Path] = true
 		have := 0
-		for _, g := range []bool{fc.Content != nil, fc.ContentBase64 != nil, fc.Delete} {
+		for _, g := range []bool{fc.Content != nil, fc.ContentBase64 != nil, fc.Delete, fc.CopyFrom != nil} {
 			if g {
 				have++
 			}
 		}
 		if have != 1 {
-			return a, refuse("files[%d] (%s) needs exactly one of content, content_base64 or delete: true. Nothing was sent", i, fc.Path)
+			return a, refuse("files[%d] (%s) needs exactly one of content, content_base64, delete: true or copy_from. Nothing was sent", i, fc.Path)
 		}
 		if fc.Content != nil && !utf8.ValidString(*fc.Content) {
 			return a, refuse("files[%d].content (%s) is not UTF-8 text: give it as content_base64. Nothing was sent", i, fc.Path)
@@ -186,6 +199,7 @@ func readCommitAsk(args map[string]any) (CommitAsk, error) {
 		if size > maxFileBytes {
 			return a, refuse("files[%d] (%s) is %s, more than the %s one file of a commit may be. Nothing was sent", i, fc.Path, mib(size), mib(maxFileBytes))
 		}
+		a.Files[i].size = size
 		total += size
 	}
 	if total > maxCommitBytes {
@@ -318,8 +332,19 @@ func commit(ctx context.Context, f *Forge, a CommitAsk) (*Committed, error) {
 			return nil, fmt.Errorf("the forge did not take the patch: %w", err)
 		}
 	} else {
-		var ops []map[string]any
+		files := a.Files
 		for _, fc := range a.Files {
+			if fc.CopyFrom != nil {
+				// Read, and judged against the limits, before anything is sent.
+				var err error
+				if files, out.Copies, err = expandCopies(ctx, f, a); err != nil {
+					return nil, err
+				}
+				break
+			}
+		}
+		var ops []map[string]any
+		for _, fc := range files {
 			sha, err := f.blobAt(ctx, repo, fc.Path, ref)
 			if err != nil {
 				return nil, err

modules/gitea/cmd/forge/copy.go

@@ -0,0 +1,270 @@
+package main
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// copy_from (novox/hq issue 1365): a file or a directory of another repository of the forge, copied by the
+// module itself, so a large move between repositories is not typed through the caller. Read through the
+// forge's API as the module's reads are (the contents of a path at a commit), every file at one commit sha
+// resolved once; the commit carries the files as it carries any others, within the same limits.
+
+// CopyFrom is where a files entry takes its content from.
+type CopyFrom struct {
+	Owner, Repo, Ref, Path string
+}
+
+// CopiedFrom says, for one copy_from entry, what was read and at which commit.
+type CopiedFrom struct {
+	Path   string `json:"path"`
+	From   string `json:"from"`
+	Source string `json:"source_commit"`
+	Files  int    `json:"files"`
+	Bytes  int    `json:"bytes"`
+}
+
+var fullSHA = regexp.MustCompile(`^[0-9a-f]{40}$`)
+
+// readCopyFrom reads one files[i].copy_from.
+func readCopyFrom(i int, v any) (*CopyFrom, error) {
+	m, ok := v.(map[string]any)
+	if !ok {
+		return nil, refuse("files[%d].copy_from is an object {owner, repo, ref, path}. Nothing was sent", i)
+	}
+	c := &CopyFrom{Owner: text(m, "owner"), Repo: text(m, "repo"), Ref: text(m, "ref"), Path: strings.Trim(text(m, "path"), "/")}
+	if c.Owner == "" || c.Repo == "" || c.Ref == "" || c.Path == "" {
+		return nil, refuse("files[%d].copy_from needs owner, repo, ref (a branch, tag or commit) and path. Nothing was sent", i)
+	}
+	if _, err := repoPath(c.Owner, c.Repo); err != nil {
+		return nil, err
+	}
+	if _, err := segments("copy_from path", c.Path); err != nil {
+		return nil, err
+	}
+	return c, nil
+}
+
+// copySource is one file to copy: where it goes, its content (base64 as the forge answered, once read) and size.
+type copySource struct {
+	target, source string
+	size           int
+}
+
+// resolveRef is the full commit sha a ref names in a repository, "" when there is none.
+func (f *Forge) resolveRef(ctx context.Context, repo, ref string) (string, error) {
+	if fullSHA.MatchString(ref) {
+		return ref, nil
+	}
+	if _, err := segments("copy_from ref", ref); err != nil {
+		return "", err
+	}
+	b, err := f.branch(ctx, repo, ref)
+	if err != nil {
+		return "", err
+	}
+	if b != nil && b.Commit.ID != "" {
+		return b.Commit.ID, nil
+	}
+	// Not a branch: a tag or a short commit, as the commit history reads it.
+	var got []forgeCommit
+	if err := f.GetJSON(ctx, repo+"/commits?sha="+queryEscape(ref)+"&limit=1&stat=false&verification=false&files=false", &got); err != nil {
+		if errors.Is(err, errNotFound) {
+			return "", nil
+		}
+		return "", err
+	}
+	if len(got) == 0 {
+		return "", nil
+	}
+	return got[0].SHA, nil
+}
+
+// contentEntry is one entry of the forge's answer for a path: a file or a symlink, or the entries of a directory.
+type contentEntry struct {
+	Name     string `json:"name"`
+	Path     string `json:"path"`
+	Type     string `json:"type"`
+	Size     int64  `json:"size"`
+	Encoding string `json:"encoding"`
+	Content  string `json:"content"`
+}
+
+// contentsAt reads a path at a commit: a single entry for a file, a list for a directory; found false for none.
+func (f *Forge) contentsAt(ctx context.Context, repo, path, sha string) (one contentEntry, list []contentEntry, found bool, err error) {
+	seg, err := segments("copy_from path", path)
+	if err != nil {
+		return one, nil, false, err
+	}
+	body, err := f.Do(ctx, "GET", repo+"/contents/"+seg+"?ref="+queryEscape(sha), nil, maxBody)
+	if err != nil {
+		if errors.Is(err, errNotFound) {
+			return one, nil, false, nil
+		}
+		return one, nil, false, err
+	}
+	if jsonInto(body, &list) == nil {
+		return one, list, true, nil
+	}
+	if err := jsonInto(body, &one); err != nil {
+		return one, nil, false, fmt.Errorf("the forge's answer about %s is not readable: %w", path, err)
+	}
+	return one, nil, true, nil
+}
+
+// walkCopy lists every file under a directory at a commit, recursively; a symlink or anything not a file is refused.
+func (f *Forge) walkCopy(ctx context.Context, repo, label string, dir string, list []contentEntry, out *[]copySource, prefix, target string) error {
+	for _, e := range list {
+		p := e.Path
+		if p == "" {
+			p = dir + "/" + e.Name
+		}
+		switch e.Type {
+		case "file":
+			rel := strings.TrimPrefix(strings.TrimPrefix(p, prefix), "/")
+			*out = append(*out, copySource{target: target + "/" + rel, source: p, size: int(e.Size)})
+		case "dir":
+			_, sub, found, err := f.contentsAt(ctx, repo, p, label)
+			if err != nil {
+				return err
+			}
+			if !found {
+				return fmt.Errorf("the forge listed %s but then did not have it", p)
+			}
+			if err := f.walkCopy(ctx, repo, label, p, sub, out, prefix, target); err != nil {
+				return err
+			}
+		case "symlink":
+			return refuse("%s is a symlink: copy_from copies files only. Nothing was sent", p)
+		default:
+			return refuse("%s is a %s: copy_from copies files only. Nothing was sent", p, e.Type)
+		}
+	}
+	return nil
+}
+
+// expandCopies replaces every copy_from entry by the files it stands for, read at one commit per entry, and says
+// what was read. The limits count the copied files with the others before anything is read in full.
+func expandCopies(ctx context.Context, f *Forge, a CommitAsk) ([]FileChange, []CopiedFrom, error) {
+	type plan struct {
+		at      int
+		sha     string
+		sources []copySource
+		from    *CopyFrom
+		repo    string
+	}
+	var plans []plan
+	count, total := 0, 0
+	for i, fc := range a.Files {
+		if fc.CopyFrom == nil {
+			count++
+			total += fc.size
+			continue
+		}
+		c := fc.CopyFrom
+		repo, err := repoPath(c.Owner, c.Repo)
+		if err != nil {
+			return nil, nil, err
+		}
+		var r Repo
+		if err := f.GetJSON(ctx, repo, &r); err != nil {
+			if errors.Is(err, errNotFound) {
+				return nil, nil, refuse("files[%d].copy_from: the forge has no repository %s/%s. Nothing was sent", i, c.Owner, c.Repo)
+			}
+			return nil, nil, err
+		}
+		sha, err := f.resolveRef(ctx, repo, c.Ref)
+		if err != nil {
+			return nil, nil, err
+		}
+		if sha == "" {
+			return nil, nil, refuse("files[%d].copy_from: %s/%s has no branch, tag or commit %q. Nothing was sent", i, c.Owner, c.Repo, c.Ref)
+		}
+		one, list, found, err := f.contentsAt(ctx, repo, c.Path, sha)
+		if err != nil {
+			return nil, nil, err
+		}
+		if !found {
+			return nil, nil, refuse("files[%d].copy_from: %s/%s has no %q at %s. Nothing was sent", i, c.Owner, c.Repo, c.Path, short(sha))
+		}
+		p := plan{at: i, sha: sha, from: c, repo: repo}
+		if list != nil || one.Type == "dir" {
+			if err := f.walkCopy(ctx, repo, sha, c.Path, list, &p.sources, c.Path, fc.Path); err != nil {
+				return nil, nil, err
+			}
+		} else if one.Type == "file" {
+			p.sources = []copySource{{target: fc.Path, source: c.Path, size: int(one.Size)}}
+		} else {
+			return nil, nil, refuse("files[%d].copy_from: %s is a %s, not a file or a directory: copy_from copies files only. Nothing was sent", i, c.Path, one.Type)
+		}
+		if len(p.sources) == 0 {
+			return nil, nil, refuse("files[%d].copy_from: %s/%s has no file under %q at %s. Nothing was sent", i, c.Owner, c.Repo, c.Path, short(sha))
+		}
+		for _, s := range p.sources {
+			count++
+			total += s.size
+			if s.size > maxFileBytes {
+				return nil, nil, refuse("files[%d].copy_from: %s is %s, more than the %s one file of a commit may be. Nothing was sent", i, s.source, mib(s.size), mib(maxFileBytes))
+			}
+		}
+		plans = append(plans, p)
+	}
+	if count > maxFiles || total > maxCommitBytes {
+		return nil, nil, refuse("the commit would carry %d files, %s together (copied and given), more than the %d files and %s one commit carries: "+
+			"split the copy by subdirectory into several commits. Nothing was sent", count, mib(total), maxFiles, mib(maxCommitBytes))
+	}
+	// The files are read now, each at its commit sha.
+	var out []FileChange
+	var said []CopiedFrom
+	seen := map[string]bool{}
+	for _, fc := range a.Files {
+		if fc.CopyFrom == nil {
+			if seen[fc.Path] {
+				return nil, nil, refuse("%s is named twice in files. Nothing was sent", fc.Path)
+			}
+			seen[fc.Path] = true
+			out = append(out, fc)
+		}
+	}
+	for _, p := range plans {
+		cf := CopiedFrom{Path: a.Files[p.at].Path, From: p.from.Owner + "/" + p.from.Repo + ":" + p.from.Path, Source: p.sha}
+		sort.Slice(p.sources, func(i, j int) bool { return p.sources[i].target < p.sources[j].target })
+		for _, s := range p.sources {
+			if seen[s.target] {
+				return nil, nil, refuse("%s is named twice in files (a copy_from reaches it as well). Nothing was sent", s.target)
+			}
+			seen[s.target] = true
+			if _, err := segments("file path", s.target); err != nil {
+				return nil, nil, err
+			}
+			one, _, found, err := f.contentsAt(ctx, p.repo, s.source, p.sha)
+			if err != nil {
+				return nil, nil, err
+			}
+			if !found || one.Type != "file" {
+				return nil, nil, refuse("%s/%s: %s is not a file at %s any more. Nothing was sent", p.from.Owner, p.from.Repo, s.source, short(p.sha))
+			}
+			if one.Encoding != "base64" {
+				return nil, nil, fmt.Errorf("the forge answered %s without its content in base64 (encoding %q): nothing was sent", s.source, one.Encoding)
+			}
+			b64 := strings.NewReplacer("\n", "", "\r", "").Replace(one.Content)
+			raw, err := base64.StdEncoding.DecodeString(b64)
+			if err != nil {
+				return nil, nil, fmt.Errorf("the forge's content of %s is not base64: %w", s.source, err)
+			}
+			if len(raw) > maxFileBytes {
+				return nil, nil, refuse("%s is %s, more than the %s one file of a commit may be. Nothing was sent", s.source, mib(len(raw)), mib(maxFileBytes))
+			}
+			cf.Files++
+			cf.Bytes += len(raw)
+			out = append(out, FileChange{Path: s.target, ContentBase64: &b64, size: len(raw)})
+		}
+		said = append(said, cf)
+	}
+	return out, said, nil
+}

modules/gitea/cmd/forge/copy_test.go

@@ -0,0 +1,295 @@
+package main
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"sort"
+	"strings"
+	"testing"
+)
+
+// sourceRepo is another repository of the fake forge, answering the contents, branch, repository and commit
+// reads in the shapes the module already parses elsewhere (forge.go, reads.go, commit.go); a file's content
+// is the forge's base64 "content" with its "encoding".
+type sourceRepo struct {
+	branches map[string]string
+	trees    map[string]map[string]string // commit -> path -> content
+	symlinks map[string]bool              // paths that are symlinks, in every tree
+	moveTo   map[string]string            // branch -> commit it moves to right after it is first read
+	tags     map[string]string
+	reads    []string
+}
+
+func (f *fakeForge) addSource(name string, s *sourceRepo) {
+	if f.sources == nil {
+		f.sources = map[string]*sourceRepo{}
+	}
+	f.sources[name] = s
+}
+
+func (f *fakeForge) handleSource(w http.ResponseWriter, r *http.Request, path string) {
+	rest := strings.TrimPrefix(path, "/api/v1/repos/acme/")
+	name, rest, _ := strings.Cut(rest, "/")
+	s := f.sources[name]
+	if s == nil {
+		http.NotFound(w, r)
+		return
+	}
+	reply := func(v any) { _ = json.NewEncoder(w).Encode(v) }
+	s.reads = append(s.reads, r.Method+" "+path+"?"+r.URL.RawQuery)
+	switch {
+	case rest == "":
+		reply(map[string]any{"full_name": "acme/" + name, "default_branch": "main"})
+	case strings.HasPrefix(rest, "branches/"):
+		b := strings.TrimPrefix(rest, "branches/")
+		c, ok := s.branches[b]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		reply(map[string]any{"name": b, "commit": map[string]any{"id": c}})
+		if to, ok := s.moveTo[b]; ok {
+			delete(s.moveTo, b)
+			s.branches[b] = to
+		}
+	case rest == "commits":
+		if c, ok := s.tags[r.URL.Query().Get("sha")]; ok {
+			reply([]any{map[string]any{"sha": c}})
+			return
+		}
+		reply([]any{})
+	case strings.HasPrefix(rest, "contents/"):
+		p := strings.TrimPrefix(rest, "contents/")
+		tree, ok := s.trees[r.URL.Query().Get("ref")]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		if content, ok := tree[p]; ok {
+			typ := "file"
+			if s.symlinks[p] {
+				typ = "symlink"
+			}
+			reply(map[string]any{"type": typ, "path": p, "name": p[strings.LastIndex(p, "/")+1:], "sha": blob(content),
+				"size": len(content), "encoding": "base64", "content": base64.StdEncoding.EncodeToString([]byte(content))})
+			return
+		}
+		// A directory: its entries, each with its full path.
+		entries := map[string]map[string]any{}
+		for q, content := range tree {
+			if !strings.HasPrefix(q, p+"/") {
+				continue
+			}
+			sub := strings.TrimPrefix(q, p+"/")
+			first, more, nested := strings.Cut(sub, "/")
+			_ = more
+			if nested {
+				entries[first] = map[string]any{"name": first, "path": p + "/" + first, "type": "dir"}
+				continue
+			}
+			typ := "file"
+			if s.symlinks[q] {
+				typ = "symlink"
+			}
+			entries[first] = map[string]any{"name": first, "path": q, "type": typ, "size": len(content), "sha": blob(content)}
+		}
+		if len(entries) == 0 {
+			http.NotFound(w, r)
+			return
+		}
+		var names []string
+		for n := range entries {
+			names = append(names, n)
+		}
+		sort.Strings(names)
+		list := []any{}
+		for _, n := range names {
+			list = append(list, entries[n])
+		}
+		reply(list)
+	default:
+		http.NotFound(w, r)
+	}
+}
+
+func newSource() *sourceRepo {
+	return &sourceRepo{
+		branches: map[string]string{"main": "s0"},
+		tags:     map[string]string{"v1": "s0"},
+		trees: map[string]map[string]string{
+			"s0": {"lib/a.go": "package a\n", "lib/deep/b.go": "package b\n", "lib/deep/er/c.txt": "c\n", "top.md": "top\n", "other/x": "x\n"},
+		},
+	}
+}
+
+func copyAsk(t *testing.T, files ...map[string]any) CommitAsk {
+	return ask(t, map[string]any{"branch": "fix/1365-x", "files": filesArg(files...)})
+}
+
+func cp(path, repo, ref, src string) map[string]any {
+	return map[string]any{"path": path, "copy_from": map[string]any{"owner": "acme", "repo": repo, "ref": ref, "path": src}}
+}
+
+// Seen failing first: with the expansion switched off the commit carried no copy and the answer named no source.
+func TestACopyFromAFileCommitsTheSourcesContentAndNamesItsCommit(t *testing.T) {
+	f := newFake(t)
+	f.addSource("src", newSource())
+	got, err := commit(context.Background(), f.serve(), copyAsk(t, cp("vendor/top.md", "src", "main", "top.md")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.trees[got.Commit]["vendor/top.md"] != "top\n" {
+		t.Fatalf("tree %v", f.trees[got.Commit])
+	}
+	if len(got.Copies) != 1 || got.Copies[0].Source != "s0" || got.Copies[0].Path != "vendor/top.md" || got.Copies[0].Files != 1 {
+		t.Fatalf("copies %+v", got.Copies)
+	}
+}
+
+// Seen failing first, as above.
+func TestACopyFromADirectoryCopiesEveryFileUnderItToTheSameRelativePaths(t *testing.T) {
+	f := newFake(t)
+	f.addSource("src", newSource())
+	got, err := commit(context.Background(), f.serve(), copyAsk(t, cp("pkg/lib", "src", "v1", "lib"),
+		map[string]any{"path": "own.md", "content": "own\n"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	tree := f.trees[got.Commit]
+	want := map[string]string{"pkg/lib/a.go": "package a\n", "pkg/lib/deep/b.go": "package b\n", "pkg/lib/deep/er/c.txt": "c\n", "own.md": "own\n"}
+	for p, c := range want {
+		if tree[p] != c {
+			t.Errorf("%s is %q, want %q", p, tree[p], c)
+		}
+	}
+	if tree["pkg/lib/top.md"] != "" || tree["pkg/other/x"] != "" {
+		t.Errorf("files outside the directory were copied: %v", tree)
+	}
+	if len(got.Copies) != 1 || got.Copies[0].Source != "s0" || got.Copies[0].Files != 3 || got.Copies[0].Bytes != len("package a\npackage b\nc\n") {
+		t.Fatalf("copies %+v", got.Copies)
+	}
+	if len(got.Files) != 4 {
+		t.Errorf("files %+v", got.Files)
+	}
+}
+
+// Seen failing first, as above: the files were read at the branch's new head.
+func TestEveryCopiedFileIsReadAtTheOneShaTheRefResolvedTo(t *testing.T) {
+	f := newFake(t)
+	s := newSource()
+	s.trees["s1"] = map[string]string{"lib/a.go": "package MOVED\n", "lib/deep/b.go": "package MOVED\n", "lib/deep/er/c.txt": "MOVED\n"}
+	s.moveTo = map[string]string{"main": "s1"}
+	f.addSource("src", s)
+	got, err := commit(context.Background(), f.serve(), copyAsk(t, cp("pkg", "src", "main", "lib")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.trees[got.Commit]["pkg/a.go"] != "package a\n" || got.Copies[0].Source != "s0" {
+		t.Fatalf("tree %v, copies %+v", f.trees[got.Commit], got.Copies)
+	}
+	for _, r := range s.reads {
+		if strings.Contains(r, "/contents/") && !strings.Contains(r, "ref=s0") {
+			t.Errorf("a file was read at another ref: %s", r)
+		}
+	}
+}
+
+// Seen failing first: each case was taken or refused for another reason (or sent).
+func TestEveryRefusalOfACopySendsNothingAndSaysWhy(t *testing.T) {
+	big := strings.Repeat("z", maxFileBytes+1)
+	many := map[string]string{}
+	for i := 0; i < maxFiles+1; i++ {
+		many[fmt.Sprintf("many/f%03d", i)] = "m"
+	}
+	for name, c := range map[string]struct {
+		file map[string]any
+		want string
+	}{
+		"unknown repository": {cp("t", "nope", "main", "top.md"), "no repository acme/nope"},
+		"unknown ref":        {cp("t", "src", "nothing", "top.md"), `no branch, tag or commit "nothing"`},
+		"unknown path":       {cp("t", "src", "main", "missing/dir"), `no "missing/dir"`},
+		"symlink in source":  {cp("t", "src", "main", "link"), "link is a symlink"},
+		"symlink under dir":  {cp("t", "src", "main", "withlink"), "withlink/l is a symlink"},
+		"file over 4 MiB":    {cp("t", "src", "main", "big"), "more than the 4.0 MiB"},
+		"over 200 files":     {cp("t", "src", "main", "many"), "201 files"},
+		"with content":       {map[string]any{"path": "t", "content": "x", "copy_from": cp("t", "src", "main", "top.md")["copy_from"]}, "copy_from together with content"},
+		"with base64":        {map[string]any{"path": "t", "content_base64": "eA==", "copy_from": cp("t", "src", "main", "top.md")["copy_from"]}, "copy_from together with content"},
+		"with delete":        {map[string]any{"path": "t", "delete": true, "copy_from": cp("t", "src", "main", "top.md")["copy_from"]}, "copy_from together with content"},
+		"meets a given file": {cp("pkg", "src", "main", "lib"), "pkg/a.go is named twice"},
+	} {
+		f := newFake(t)
+		s := newSource()
+		s.trees["s0"]["link"] = "top.md"
+		s.symlinks = map[string]bool{"link": true, "withlink/l": true}
+		s.trees["s0"]["withlink/l"] = "top.md"
+		s.trees["s0"]["withlink/ok"] = "ok"
+		s.trees["s0"]["big/f"] = big
+		for p, v := range many {
+			s.trees["s0"][p] = v
+		}
+		f.addSource("src", s)
+		files := []map[string]any{c.file}
+		if name == "meets a given file" {
+			files = append(files, map[string]any{"path": "pkg/a.go", "content": "mine"})
+		}
+		a, err := readCommitAsk(map[string]any{"owner": "acme", "repo": "app", "message": "m", "branch": "fix/1365-x", "files": filesArg(files...)})
+		if err == nil {
+			_, err = commit(context.Background(), f.serve(), a)
+		}
+		if err == nil || !strings.Contains(err.Error(), c.want) || !strings.Contains(err.Error(), "Nothing was sent") {
+			t.Errorf("%s: %v (want %q)", name, err, c.want)
+		}
+		if len(f.writes) != 0 || len(f.patches) != 0 || f.branches["fix/1365-x"] != "" {
+			t.Errorf("%s: something was sent: %v %v", name, f.writes, f.branches)
+		}
+	}
+}
+
+// Seen failing first: the copy was not counted, so the commit was sent.
+func TestACopyOverTheTotalNamesItsCountAndSizeSoItCanBeSplit(t *testing.T) {
+	f := newFake(t)
+	s := newSource()
+	chunk := strings.Repeat("q", maxFileBytes)
+	for i := 0; i < 5; i++ {
+		s.trees["s0"][fmt.Sprintf("heavy/f%d", i)] = chunk
+	}
+	f.addSource("src", s)
+	_, err := commit(context.Background(), f.serve(), copyAsk(t, cp("h", "src", "main", "heavy")))
+	if err == nil || !strings.Contains(err.Error(), "5 files, 20.0 MiB together") || !strings.Contains(err.Error(), "by subdirectory") {
+		t.Fatalf("%v", err)
+	}
+	if len(f.writes) != 0 {
+		t.Fatal("sent")
+	}
+}
+
+func TestCopyFromIsInTheToolsSchemaAndTheReadme(t *testing.T) {
+	var schema map[string]any
+	for _, tl := range Tools(func() (*Forge, error) { return nil, fmt.Errorf("unset") }) {
+		if tl.Name == "gitea_commit" {
+			schema = tl.Input
+		}
+	}
+	item := schema["properties"].(map[string]any)["files"].(map[string]any)["items"].(map[string]any)["properties"].(map[string]any)
+	cf, ok := item["copy_from"].(map[string]any)
+	if !ok {
+		t.Fatalf("copy_from is not in the schema: %v", item)
+	}
+	props := cf["properties"].(map[string]any)
+	for _, k := range []string{"owner", "repo", "ref", "path"} {
+		if _, ok := props[k]; !ok {
+			t.Errorf("copy_from has no %s", k)
+		}
+	}
+}
+
+func TestACopyFromThatIsNotAnObjectIsRefused(t *testing.T) {
+	_, err := readCommitAsk(map[string]any{"owner": "acme", "repo": "app", "message": "m", "branch": "b",
+		"files": filesArg(map[string]any{"path": "x", "copy_from": "acme/src:top.md"})})
+	if err == nil || !strings.Contains(err.Error(), "copy_from is an object") {
+		t.Fatalf("%v", err)
+	}
+}

modules/gitea/cmd/forge/forge_test.go

@@ -45,6 +45,7 @@ type fakeForge struct {
 	noParents     bool              // the forge's answer to a write does not say the parents
 	parentsBroken bool              // and GET git/commits fails
 	parents       map[string]string // commit -> parent, as GET git/commits says it
+	sources       map[string]*sourceRepo
 }
 
 type move struct {
@@ -88,6 +89,10 @@ func (f *fakeForge) handle(w http.ResponseWriter, r *http.Request) {
 	reply := func(v any) { _ = json.NewEncoder(w).Encode(v) }
 	const repo = "/api/v1/repos/acme/app"
 	path := r.URL.EscapedPath()
+	if strings.HasPrefix(path, "/api/v1/repos/acme/") && !strings.HasPrefix(path, repo) {
+		f.handleSource(w, r, path)
+		return
+	}
 	switch {
 	case r.Method == "GET" && path == repo:
 		reply(map[string]any{"full_name": "acme/app", "default_branch": "main"})

modules/gitea/cmd/forge/main.go

@@ -51,7 +51,7 @@ func Tools(forge func() (*Forge, error)) []stdio.Tool {
 				"when it does not exist. Refused on the repository's default branch and on any branch a protection " +
 				"rule names (novox/hq ADR 0266): a change reaches those only by a pull request whose head an " +
 				"independent review approved and whose required checks passed (gitea_merge_pull_request). Carries " +
-				"either files — each {path, content (text) | content_base64 | delete: true}, created or updated as " +
+				"either files — each {path, content (text) | content_base64 | delete: true | copy_from {owner, repo, ref, path}: a file or directory of another repository, copied by the module}, created or updated as " +
 				"the branch holds them — or patch, a unified diff as git diff writes it, which the forge applies. " +
 				"At most 200 files, 4 MiB each and 16 MiB together, or a 4 MiB patch. Answers the commit it made and " +
 				"the parent the forge made it on, read back from the branch, and says when the branch moved under " +
@@ -77,6 +77,17 @@ func Tools(forge func() (*Forge, error)) []stdio.Tool {
 								"content":        str("its whole new content, as UTF-8 text"),
 								"content_base64": str("its whole new content, base64-encoded, for a file that is not text"),
 								"delete":         map[string]any{"type": "boolean", "description": "true to delete the file"},
+								"copy_from": map[string]any{
+									"type":        "object",
+									"description": "instead of content: copy a file, or every file under a directory (recursively, to the same relative paths under this path), of another repository of the forge, read at one commit sha resolved from ref once (the answer names it per entry). Files only: a symlink is refused. The copied files count against the limits; an unknown repository, ref or path, or a copy over the limits, is refused with nothing sent, naming the count and size so the copy can be split by subdirectory. Not together with content, content_base64 or delete",
+									"properties": map[string]any{
+										"owner": str("the source repository's owner"),
+										"repo":  str("the source repository's name"),
+										"ref":   str("a branch, tag or commit of the source repository"),
+										"path":  str("the file or directory to copy, from the source repository's root"),
+									},
+									"required": []string{"owner", "repo", "path", "ref"},
+								},
 							},
 							"required": []string{"path"},
 						},

modules/gitea/cmd/repositories/manifest_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"encoding/json"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 )
@@ -35,14 +36,33 @@ func TestManifestDeclaresTheValueAndItsTrigger(t *testing.T) {
 	}
 	var file, process map[string]any
 	for _, r := range m.Resources {
-		for _, k := range strs(r["takes-config"]) {
+		if r["id"] == "repositories-file" {
-			if k == ConfigKey {
+			file = r
-				file = r
-			}
 		}
 	}
 	if file == nil || file["type"] != "file" {
-		t.Fatalf("no file takes the value %s", ConfigKey)
+		t.Fatalf("no file repositories-file")
+	}
+	// 1128/AC1: a plain template the provisioner client fills, so an approved value lands at once: a file the
+	// controller merges (merge, takes-config) takes a config change only on the node's next send (ADR 0348 §10).
+	if file["merge"] != nil || file["takes-config"] != nil {
+		t.Errorf("repositories-file is merged by the controller (merge %v, takes-config %v), want a plain template",
+			file["merge"], file["takes-config"])
+	}
+	text, err := os.ReadFile("../../" + file["template"].(string))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(text), "${config:"+ConfigKey+"}") {
+		t.Fatalf("the template %s does not say ${config:%s}: %s", file["template"], ConfigKey, text)
+	}
+	filled := filepath.Join(t.TempDir(), "repositories.json")
+	value := `{"mesh-delivery":{"private":false,"description":"d"}}`
+	if err := os.WriteFile(filled, []byte(strings.ReplaceAll(string(text), "${config:"+ConfigKey+"}", value)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if v, err := ReadValue(filled); err != nil || len(v) != 1 || v["mesh-delivery"].Description != "d" {
+		t.Errorf("the filled template reads as %v, %v; want mesh-delivery", v, err)
 	}
 	for _, r := range m.Resources {
 		if r["type"] == "process" && has(strs(r["restart-on"]), file["id"].(string)) {

modules/gitea/cmd/repositories/override_test.go

@@ -0,0 +1,49 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+// 1141/AC1: a repository the program makes gets main's rule with an administrator's merge past a status refused,
+// as every repository's main has had since 2026-10-07.
+func TestNewRepositoryRefusesTheAdministratorsOverride(t *testing.T) {
+	f := newFake()
+	s, _ := syncer(t, f)
+	run(t, s, Value{"mesh-delivery": {Description: "d"}})
+	rule := f.repos["novox/mesh-delivery"].Rules[mainRule]
+	if rule["block_admin_merge_override"] != true {
+		t.Errorf("main lets an administrator merge past its statuses: %v", rule)
+	}
+}
+
+// 1141/AC2: a narrowed main rule that still lets an administrator override is not right: it is put right, its
+// statuses kept, and a second pass changes nothing.
+func TestNarrowedRuleLettingTheAdministratorOverrideIsPutRight(t *testing.T) {
+	f := newFake()
+	repo := f.add("novox/mesh-delivery", map[string]map[string]any{mainRule: {
+		"enable_push": false, "enable_push_whitelist": false, "push_whitelist_usernames": []any{},
+		"enable_merge_whitelist": true, "merge_whitelist_usernames": []any{tools},
+		"enable_status_check": true, "status_check_contexts": []any{"mesh/merge-gate", "mesh/repo-check", "other/x"},
+		"block_admin_merge_override": false,
+	}}, "main")
+	s, _ := syncer(t, f)
+	o := run(t, s, Value{"mesh-delivery": {Description: "d"}})
+	rule := repo.Rules[mainRule]
+	if rule["block_admin_merge_override"] != true {
+		t.Errorf("the administrator's override is still allowed: %v", rule)
+	}
+	for _, c := range []string{"mesh/merge-gate", "mesh/repo-check", "other/x"} {
+		if !has(strs(rule["status_check_contexts"]), c) {
+			t.Errorf("a status was dropped: %v", rule["status_check_contexts"])
+		}
+	}
+	if r := result(o, "mesh-delivery"); r.Did != DidPutRight {
+		t.Errorf("outcome %+v, want put right", r)
+	}
+	before := len(f.writes())
+	run(t, s, Value{"mesh-delivery": {Description: "d"}})
+	if got := f.writes(); len(got) != before {
+		t.Errorf("a second pass wrote %s", strings.Join(got[before:], ", "))
+	}
+}

modules/gitea/cmd/repositories/repositories.go

@@ -333,12 +333,14 @@ func statuses(rules ...rule) []string {
 }
 
 // narrowed is main's rule of ADR 0398 §2 (protection.ts mainRuleBody): no push, only the tools' account merges,
-// requiring the statuses (ADR 0428 §5). A field the forge keeps beside these is left as it is.
+// requiring the statuses (ADR 0428 §5), and no administrator merging past them, as every repository's main has been
+// since 2026-10-07 (issue 1141). A field the forge keeps beside these is left as it is.
 func narrowed(r rule, toolsAccount string, also ...rule) map[string]any {
 	return map[string]any{
 		"enable_push": false, "enable_push_whitelist": false, "push_whitelist_usernames": []string{},
 		"enable_merge_whitelist": true, "merge_whitelist_usernames": []string{toolsAccount},
 		"enable_status_check": true, "status_check_contexts": statuses(append([]rule{r}, also...)...),
+		"block_admin_merge_override": true,
 	}
 }
 
@@ -350,7 +352,8 @@ func isRight(r rule, toolsAccount string) bool {
 	if m := strList(r["merge_whitelist_usernames"]); len(m) != 1 || m[0] != toolsAccount {
 		return false
 	}
-	return r["enable_status_check"] == true && hasAll(strList(r["status_check_contexts"]))
+	return r["enable_status_check"] == true && hasAll(strList(r["status_check_contexts"])) &&
+		r["block_admin_merge_override"] == true
 }
 
 func hasAll(have []string) bool {
@@ -394,9 +397,6 @@ func (s *Syncer) putRight(ctx context.Context, owner, name string) (bool, error)
 		if n, _ := r["required_approvals"].(float64); n > approvals {
 			approvals = n
 		}
-		if r["block_admin_merge_override"] == true {
-			body["block_admin_merge_override"] = true
-		}
 	}
 	if approvals > 0 {
 		body["required_approvals"] = approvals

modules/gitea/cmd/repositories/repositories_test.go

@@ -225,6 +225,7 @@ func TestStatusesAreAddedAndNeverDropped(t *testing.T) {
 	more := f.add("novox/more", map[string]map[string]any{mainRule: {
 		"enable_push": false, "enable_merge_whitelist": true, "merge_whitelist_usernames": []any{tools},
 		"enable_status_check": true, "status_check_contexts": []any{"mesh/merge-gate", "mesh/repo-check", "mesh/delivery"},
+		"block_admin_merge_override": true, // right since issue 1141
 	}}, "main")
 	s, _ := syncer(t, f)
 	o := run(t, s, Value{"only": {}, "more": {}})

modules/gitea/files/repositories.json

@@ -1 +1 @@
-{}
+{"repositories": ${config:repositories}}

modules/gitea/guard.ts

@@ -94,6 +94,8 @@ export const QUERY_KEYS: ReadonlySet<string> = new Set([
   "limit", "page", "state", "type", "q", "sort", "order", "since", "before", "ref", "sha", "path", "labels",
   "milestones", "keyword", "stat", "verification", "files", "not", "mode", "include_desc", "archived", "private",
   "exclusive", "uid", "priority_repo_id", "created_by", "assigned_by", "mentioned_by", "whitespace", "binary",
+  // Read flags of the forge's tree listing (gitea_commit_trees, novox/hq issue 1234): they widen what one read answers, never what a call may write.
+  "recursive", "per_page",
 ]);
 
 /** The query a call sends: only allow-listed keys, each as given; refused when any other key is there. */

modules/gitea/internal/forgeaccount/account.go

@@ -1,7 +1,8 @@
 // Package forgeaccount is the forge accounts the mesh makes for its agents (novox/hq ADR 0365 clauses 1 and 3, ADR
 // 0398 §1, ADR 0399, ADR 0400; issue 955): an account of the agent's own, no administrator, in the agents write
 // team. Both the token tool (cmd/agent-token) and the forge-account provider use it, so there is one place that says
-// what an agent's account is.
+// what an agent's account is. It also makes the one account of the build modules' keys, nox-builder, in the builders
+// team that reads the code of every repository and nothing else (ADR 0466 §3; issue 1481).
 package forgeaccount
 
 import (
@@ -26,8 +27,23 @@ const (
 	TeamName = "agents"
 )
 
-// teamShape is what the agents team grants: write on code, issues and pull requests of every repository of the
+// BuildersTeamName is the team of the build modules' account (ADR 0466 §3).
+const BuildersTeamName = "builders"
+
+// Team is a team of the organisation as the mesh keeps it: its name and the shape it is put back to.
+type Team struct {
+	Name  string
+	Shape func() map[string]any
+}
+
+// AgentsTeam is the team of the machines' agents: write on code, issues and pull requests of every repository of the
 // organisation and no more, the shape of the forge tools' team (tools-account.ts).
+var AgentsTeam = Team{Name: TeamName, Shape: teamShape}
+
+// BuildersTeam is the team of the build modules' account: it may read the code of every repository of the organisation
+// and has no other right (ADR 0466 §3).
+var BuildersTeam = Team{Name: BuildersTeamName, Shape: buildersTeamShape}
+
 func teamShape() map[string]any {
 	return map[string]any{
 		"name": TeamName, "permission": "write", "includes_all_repositories": true, "can_create_org_repo": false,
@@ -35,6 +51,13 @@ func teamShape() map[string]any {
 	}
 }
 
+func buildersTeamShape() map[string]any {
+	return map[string]any{
+		"name": BuildersTeamName, "permission": "read", "includes_all_repositories": true, "can_create_org_repo": false,
+		"units_map": map[string]string{"repo.code": "read"},
+	}
+}
+
 // User is gitea's account as the admin reads it.
 type User struct {
 	IsAdmin       bool `json:"is_admin"`
@@ -87,35 +110,41 @@ func (m *Accounts) EnsureAccount(ctx context.Context, account string) error {
 // EnsureInTeam makes the agents team when there is none, puts a team that is there back to its shape, and adds the
 // account to it; an account already in it stays (ADR 0398 §1, issue 948).
 func (m *Accounts) EnsureInTeam(ctx context.Context, account string) error {
-	id, err := m.teamID(ctx)
+	return m.EnsureInTeamOf(ctx, AgentsTeam, account)
+}
+
+// EnsureInTeamOf is EnsureInTeam for any team of the mesh's: it makes the team when there is none, puts a team that is
+// there back to its shape, and adds the account to it.
+func (m *Accounts) EnsureInTeamOf(ctx context.Context, team Team, account string) error {
+	id, err := m.teamID(ctx, team.Name)
 	if err != nil {
 		return err
 	}
 	if id != 0 {
-		if err := m.Forge.SendJSON(ctx, http.MethodPatch, fmt.Sprintf("/api/v1/teams/%d", id), teamShape(), nil); err != nil {
+		if err := m.Forge.SendJSON(ctx, http.MethodPatch, fmt.Sprintf("/api/v1/teams/%d", id), team.Shape(), nil); err != nil {
-			return fmt.Errorf("the team %s could not be put back to its shape: %w", TeamName, err)
+			return fmt.Errorf("the team %s could not be put back to its shape: %w", team.Name, err)
 		}
 	} else {
 		var made struct {
 			ID int64 `json:"id"`
 		}
-		if err := m.Forge.SendJSON(ctx, http.MethodPost, "/api/v1/orgs/"+TeamOrg+"/teams", teamShape(), &made); err != nil {
+		if err := m.Forge.SendJSON(ctx, http.MethodPost, "/api/v1/orgs/"+TeamOrg+"/teams", team.Shape(), &made); err != nil {
-			return fmt.Errorf("the team %s could not be made: %w", TeamName, err)
+			return fmt.Errorf("the team %s could not be made: %w", team.Name, err)
 		}
 		id = made.ID
-		m.say("made the forge team %s in %s: write on every repository", TeamName, TeamOrg)
+		m.say("made the forge team %s in %s", team.Name, TeamOrg)
 	}
 	if id == 0 {
-		return fmt.Errorf("the forge answered no id for the team %s", TeamName)
+		return fmt.Errorf("the forge answered no id for the team %s", team.Name)
 	}
 	if err := m.Forge.SendJSON(ctx, http.MethodPut, fmt.Sprintf("/api/v1/teams/%d/members/%s", id, account), nil, nil); err != nil {
-		return fmt.Errorf("the account %s could not be added to the team %s: %w", account, TeamName, err)
+		return fmt.Errorf("the account %s could not be added to the team %s: %w", account, team.Name, err)
 	}
 	return nil
 }
 
-// teamID is the agents team's id, or 0 when there is none.
+// teamID is the id of the team of that name, or 0 when there is none.
-func (m *Accounts) teamID(ctx context.Context) (int64, error) {
+func (m *Accounts) teamID(ctx context.Context, name string) (int64, error) {
 	var id int64
 	for page := 1; page <= 20 && id == 0; page++ {
 		var teams []struct {
@@ -126,7 +155,7 @@ func (m *Accounts) teamID(ctx context.Context) (int64, error) {
 			return 0, fmt.Errorf("the teams of %s could not be read: %w", TeamOrg, err)
 		}
 		for _, t := range teams {
-			if t.Name == TeamName {
+			if t.Name == name {
 				id = t.ID
 			}
 		}
@@ -160,16 +189,49 @@ var NodeName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,31}$`)
 // AgentUser is the one forge user of every machine's agents (ADR 0410 §1), in the agents write team.
 const AgentUser = "nox-agent"
 
-// ForgeUser is the forge user of a machine's key of the given kind (ADR 0410 §1): `nox-agent` for every machine
+// BuilderUser is the one forge user of every build module's key (ADR 0466 §3), in the builders team: it reads and
-// and account (kind machine). A kind not built yet has none, and the answer is empty. The machine's name must still
+// pushes nothing.
-// be one an account could be named for.
+const BuilderUser = "nox-builder"
+
+// BuildModules are the modules whose keys are the builders' (kind builder), by their name, which is also the name of
+// the account each runs as (ADR 0466 §1).
+var BuildModules = []string{"mesh-build-go", "mesh-build-node"}
+
+// KindOfModule is the kind of key a consumer module's entry is made for: builder for a build module, machine for any
+// other (ssh-client's).
+func KindOfModule(module string) string {
+	for _, m := range BuildModules {
+		if m == module {
+			return "builder"
+		}
+	}
+	return "machine"
+}
+
+// ForgeUser is the forge user of a key of the given kind (ADR 0410 §1, ADR 0466 §3): `nox-agent` for every machine
+// and account (kind machine), `nox-builder` for every build module (kind builder). A kind not built yet has none, and
+// the answer is empty. The machine's name must still be one an account could be named for.
 func ForgeUser(node, kind string) string {
-	if kind == "machine" && NodeName.MatchString(node) {
+	if !NodeName.MatchString(node) {
+		return ""
+	}
+	switch kind {
+	case "machine":
 		return AgentUser
+	case "builder":
+		return BuilderUser
 	}
 	return ""
 }
 
+// TeamOfUser is the team a forge user of the mesh is in.
+func TeamOfUser(user string) Team {
+	if user == BuilderUser {
+		return BuildersTeam
+	}
+	return AgentsTeam
+}
+
 // NodeAccount is the forge account the token tool (cmd/agent-token) keeps for a node's agent: `agent-<node>` (ADR
 // 0365 §1). It is not the forge user of the machine's ssh key (ForgeUser), and its behaviour is unchanged.
 func NodeAccount(node string) string { return AccountPrefix + node }

modules/gitea/internal/forgeaccount/builder_test.go

@@ -0,0 +1,46 @@
+package forgeaccount
+
+import "testing"
+
+// Issue 1481 (novox/hq ADR 0466 §3): the build modules' forge user, team and key scope.
+func TestTheBuildModulesHaveOneForgeUserAndTheMachinesKeepTheirs(t *testing.T) {
+	for kind, want := range map[string]string{"machine": "nox-agent", "builder": "nox-builder", "session": ""} {
+		if got := ForgeUser("ace", kind); got != want {
+			t.Errorf("ForgeUser(ace, %s) = %q, want %q", kind, got, want)
+		}
+	}
+	if ForgeUser("Not A Node", "builder") != "" {
+		t.Errorf("a name no account could be named for got a user")
+	}
+	for module, want := range map[string]string{"mesh-build-go": "builder", "mesh-build-node": "builder", "ssh-client": "machine", "": "machine"} {
+		if got := KindOfModule(module); got != want {
+			t.Errorf("KindOfModule(%q) = %s, want %s", module, got, want)
+		}
+	}
+	if TeamOfUser(BuilderUser).Name != "builders" || TeamOfUser(AgentUser).Name != "agents" {
+		t.Errorf("teams: %s and %s", TeamOfUser(BuilderUser).Name, TeamOfUser(AgentUser).Name)
+	}
+}
+
+// A build module's scope names the module, so one module's pass does not remove the other's key on the same machine;
+// the machine's scope is every key of the machine.
+func TestABuilderScopeNamesTheModule(t *testing.T) {
+	if got := BuilderScope("ace", "mesh-build-go"); got != "mesh:ace.mesh-build-go" {
+		t.Errorf("scope = %q", got)
+	}
+	if BuilderScope("ace", "mesh-build-go") == BuilderScope("ace", "mesh-build-node") {
+		t.Errorf("two build modules share a scope")
+	}
+	if got := KeyTitle("ace", "mesh-build-go"); got != BuilderScope("ace", "mesh-build-go") {
+		t.Errorf("the key's title %q is not inside the scope", got)
+	}
+}
+
+// The builders team reads the code of every repository of the organisation and has no other right.
+func TestTheBuildersTeamReadsCodeOnly(t *testing.T) {
+	s := BuildersTeam.Shape()
+	units, _ := s["units_map"].(map[string]string)
+	if s["permission"] != "read" || s["includes_all_repositories"] != true || s["can_create_org_repo"] != false || len(units) != 1 || units["repo.code"] != "read" {
+		t.Errorf("shape = %v", s)
+	}
+}

modules/gitea/internal/forgeaccount/keys.go

@@ -22,6 +22,8 @@ type WantedKey struct {
 	Title string
 	// Key is the public key line: type, base64 and a comment.
 	Key string
+	// ReadOnly registers the key as one that may not push (a builder's, ADR 0466 §3).
+	ReadOnly bool
 }
 
 // Key is a key the forge holds for an account.
@@ -56,10 +58,10 @@ func (m *Accounts) Keys(ctx context.Context, user string) ([]Key, error) {
 	return all, nil
 }
 
-// AddKey registers a key for the account, one it may write with.
+// AddKey registers a key for the account, one it may write with unless the key is wanted read-only.
 func (m *Accounts) AddKey(ctx context.Context, user string, k WantedKey) error {
 	err := m.Forge.SendJSON(ctx, http.MethodPost, "/api/v1/admin/users/"+user+"/keys",
-		map[string]any{"title": k.Title, "key": k.Key, "read_only": false}, nil)
+		map[string]any{"title": k.Title, "key": k.Key, "read_only": k.ReadOnly}, nil)
 	if err != nil {
 		return fmt.Errorf("the key %s could not be added for %s: %w", k.Title, user, err)
 	}
@@ -78,6 +80,11 @@ func (m *Accounts) DeleteKey(ctx context.Context, user string, id int64) error {
 // MachineScope is the title prefix of one machine's keys, `mesh:<node>.`: what a pass for that machine may remove.
 func MachineScope(node string) string { return TitlePrefix + node + "." }
 
+// BuilderScope is the title prefix of one build module's key on one machine, `mesh:<node>.<module>`: what a pass for
+// that module's entry may remove. It names the module, since nox-builder holds the keys of both build modules of a
+// machine and one's pass must not remove the other's.
+func BuilderScope(node, module string) string { return TitlePrefix + node + "." + module }
+
 // EnsureKeys registers each wanted key the account does not hold and removes the keys the mesh registered
 // for one machine (title starting scope, `mesh:<node>.`) that are no longer wanted. One forge user holds every
 // machine's keys (ADR 0410 §2), so a key under another machine's title is never removed here. A key whose title does not start `mesh:` is the operator's and

modules/gitea/module.json

@@ -322,11 +322,7 @@
       "type": "file",
       "path": "${dir:mesh-state}/repositories.json",
       "mode": "0600",
-      "template": "files/repositories.json",
+      "template": "files/repositories.json"
-      "merge": "json",
-      "takes-config": [
-        "repositories"
-      ]
     },
     {
       "id": "consumers",
@@ -544,6 +540,8 @@
   ],
   "reads": [
     "mesh-controller.assignments",
-    "ssh-client.keys"
+    "ssh-client.keys",
+    "mesh-build-go.keys",
+    "mesh-build-node.keys"
   ]
 }

modules/gitea/test/commit-trees.test.ts

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createServer } from "node:http";
+
+// Fixtures follow Gitea's GitTreeResponse as its API documents it (swagger: sha, url, tree[{path, mode, type, size,
+// sha, url}], truncated, page, total_count) and as the forge answers GET /repos/{o}/{r}/git/trees/{sha}; the entry
+// fields are those, with sha values written out. The live capture (1234/AC6): GET
+// /repos/novox/mesh-delivery/git/trees/7f61817 (non-recursive) answered the COMMIT's sha at the top, not the root
+// tree's; the root tree is computed from the root's own entries, as git does.
+import { createHash } from "node:crypto";
+
+const COMMIT = "c".repeat(40);
+const h = (c: string) => c.repeat(40);
+const entry = (path: string, type: "tree" | "blob", sha: string) => ({
+  path, mode: type === "tree" ? "040000" : "100644", type, size: type === "tree" ? 0 : 12, sha, url: `u/${sha}`,
+});
+const LISTING = [
+  entry("README.md", "blob", h("1")),
+  entry("module.json", "blob", h("2")),
+  entry("modules", "tree", h("3")),
+  entry("modules/a", "tree", h("4")),
+  entry("modules/a/module.json", "blob", h("5")),
+  entry("modules/a/main.go", "blob", h("6")),
+  entry("modules/b", "tree", h("7")),
+  entry("modules/b/c", "tree", h("8")),
+  entry("modules/b/c/module.json", "blob", h("9")),
+  entry("modules/d", "tree", h("a")),
+  entry("modules/d/notes.md", "blob", h("b")),
+];
+
+/** git's own hash of a tree from its entries (an independent restatement for the fixtures): mode without leading zero. */
+function gitTree(es: { path: string; type: string; sha: string; mode: string }[]): string {
+  const ordered = es.map((e) => ({ ...e, key: e.path + (e.type === "tree" ? "/" : "") })).sort((a, b) => Buffer.compare(Buffer.from(a.key), Buffer.from(b.key)));
+  const body = Buffer.concat(ordered.map((e) => Buffer.concat([Buffer.from(`${e.mode.replace(/^0+/, "")} ${e.path}\0`), Buffer.from(e.sha, "hex")])));
+  return createHash("sha1").update(Buffer.concat([Buffer.from(`tree ${body.length}\0`), body])).digest("hex");
+}
+const ROOT = gitTree(LISTING.filter((e) => !e.path.includes("/")));
+
+async function serve(pages: any[]) {
+  const { GiteaClient } = await import("../client.ts");
+  const asked: string[] = [];
+  const server = createServer((req, res) => {
+    asked.push(req.url ?? "");
+    const url = new URL(req.url ?? "", "http://x");
+    if (url.pathname !== `/api/v1/repos/novox/hq/git/trees/${COMMIT}` || url.searchParams.get("recursive") !== "true") {
+      res.statusCode = 404;
+      return res.end("{}");
+    }
+    const page = Number(url.searchParams.get("page") ?? 1);
+    res.end(JSON.stringify(pages[page - 1] ?? { sha: COMMIT, tree: [], truncated: false, page, total_count: 0 }));
+  });
+  await new Promise<void>((r) => server.listen(0, r));
+  const client = new GiteaClient(`http://127.0.0.1:${(server.address() as any).port}`, "t");
+  return { client, server, asked };
+}
+
+test("a commit's trees: the root and the tree of each directory holding a module.json", async () => {
+  // 1234/AC1 and 1234/AC4
+  const { client, server } = await serve([{ sha: COMMIT, url: "u", tree: LISTING, truncated: false, page: 1, total_count: LISTING.length }]);
+  try {
+    const got = await client.commitTrees("novox", "hq", COMMIT);
+    assert.deepEqual(got, { root: ROOT, trees: { "": ROOT, "modules/a": h("4"), "modules/b/c": h("8") } });
+  } finally {
+    server.close();
+  }
+});
+
+test("a listing the forge pages is read page by page", async () => {
+  // 1234/AC1
+  const { client, server, asked } = await serve([
+    { sha: COMMIT, tree: LISTING.slice(0, 5), truncated: true, page: 1, total_count: LISTING.length },
+    { sha: COMMIT, tree: LISTING.slice(5, 9), truncated: true, page: 2, total_count: LISTING.length },
+    { sha: COMMIT, tree: LISTING.slice(9), truncated: false, page: 3, total_count: LISTING.length },
+  ]);
+  try {
+    const got = await client.commitTrees("novox", "hq", COMMIT);
+    assert.deepEqual(got.trees, { "": ROOT, "modules/a": h("4"), "modules/b/c": h("8") });
+    assert.equal(asked.length, 3, `asked ${asked.join(" ")}`);
+  } finally {
+    server.close();
+  }
+});
+
+test("a listing the forge says is cut fails, naming the repository and the commit, and answers no trees", async () => {
+  // 1234/AC2
+  const { client, server } = await serve([{ sha: COMMIT, tree: LISTING, truncated: true, page: 1, total_count: LISTING.length }]);
+  try {
+    await assert.rejects(client.commitTrees("novox", "hq", COMMIT), (err: Error) => {
+      assert.match(err.message, /novox\/hq/);
+      assert.ok(err.message.includes(COMMIT), err.message);
+      assert.match(err.message, /cut/);
+      return true;
+    });
+  } finally {
+    server.close();
+  }
+});
+
+test("a sha that is not a full commit, or no owner or repo, is refused before the forge is asked", async () => {
+  // 1234/AC3
+  const { getGiteaTools } = await import("../tools/index.ts");
+  const { client, server, asked } = await serve([]);
+  try {
+    const tool = getGiteaTools(client).find((t) => t.name === "gitea_commit_trees")!;
+    assert.ok(tool, "the tool is listed");
+    for (const args of [
+      { owner: "novox", repo: "hq", sha: "abc1234" },
+      { owner: "novox", repo: "hq", sha: "main" },
+      { owner: "novox", repo: "hq", sha: "" },
+      { owner: "novox", repo: "hq", sha: "c".repeat(41) },
+      { owner: "", repo: "hq", sha: COMMIT },
+      { owner: "novox", repo: " ", sha: COMMIT },
+    ]) await assert.rejects(tool.run(args as any), /./, JSON.stringify(args));
+    assert.equal(asked.length, 0, `the forge was asked ${asked.join(" ")}`);
+  } finally {
+    server.close();
+  }
+});
+
+test("gitea_open_pulls says each pull request's head branch beside its head sha", async () => {
+  // 1234/AC5
+  const { GiteaClient } = await import("../client.ts");
+  const server = createServer((req, res) => {
+    const url = req.url ?? "";
+    const send = (v: unknown) => res.end(JSON.stringify(v));
+    if (url.startsWith("/api/v1/repos/issues/search")) {
+      return send(url.includes("page=1") ? [{ number: 7, repository: { owner: "novox", name: "hq", full_name: "novox/hq" } }] : []);
+    }
+    if (url.startsWith("/api/v1/repos/novox/hq/pulls/7")) {
+      return send({ number: 7, state: "open", base: { ref: "main" }, head: { ref: "feat/x", sha: "aaa1111" }, html_url: "h" });
+    }
+    if (url.includes("/branch_protections")) { res.statusCode = 403; return res.end("{}"); }
+    if (url.startsWith("/api/v1/repos/novox/hq/branches/main")) return send({ name: "main" });
+    if (url.includes("/commits/aaa1111/status")) return send({ statuses: [] });
+    res.statusCode = 404;
+    res.end("{}");
+  });
+  await new Promise<void>((r) => server.listen(0, r));
+  const client = new GiteaClient(`http://127.0.0.1:${(server.address() as any).port}`, "t");
+  try {
+    const [p] = await client.openPulls();
+    assert.deepEqual(p, { owner: "novox", repo: "hq", number: 7, base: "main", head: "feat/x", head_sha: "aaa1111", html_url: "h",
+      required: [], statuses: [], checks: {}, labels: [] });
+  } finally {
+    server.close();
+  }
+});
+
+test("the root tree is git's hash of the root's own entries, never the listing's top sha (the commit's)", async () => {
+  // 1234/AC6, from the live capture named in the header: novox/mesh-delivery at 7f61817.
+  const commit = "7f618177d6773d8d2d2b9e0b10e13b85ec700c59";
+  const listing = [
+    entry("README.md", "blob", "a087d22cbcbecce42256315671ff7e4d6ca85a7c"),
+    entry("merge-check.sh", "blob", "c4ef9a3dd6390b0edde7e4137095553897cecfb0"),
+    entry("modules", "tree", "31c0abb312ee6ce4693a7aacdd8b3fba871d6cf3"),
+    entry("modules/x", "tree", h("d")),
+    entry("modules/x/module.json", "blob", h("e")),
+  ];
+  const { GiteaClient } = await import("../client.ts");
+  const server = createServer((req, res) => {
+    res.end(JSON.stringify(new URL(req.url ?? "", "http://x").pathname.endsWith(`/git/trees/${commit}`)
+      ? { sha: commit, tree: listing, truncated: false, page: 1, total_count: listing.length } : {}));
+  });
+  await new Promise<void>((r) => server.listen(0, r));
+  const client = new GiteaClient(`http://127.0.0.1:${(server.address() as any).port}`, "t");
+  try {
+    const got = await client.commitTrees("novox", "mesh-delivery", commit);
+    assert.equal(got.root, "659bcaaac6c16972ec380267a4eba69d15558c26");
+    assert.deepEqual(got.trees, { "modules/x": h("d") });
+  } finally {
+    server.close();
+  }
+});

modules/gitea/test/token.test.ts

@@ -539,7 +539,7 @@ test("the tools register once there is a way to a token, and the first call mint
       "gitea_list_branches",
       "gitea_delete_branch",
       "gitea_branch_protection_get", "gitea_branch_protection_set",
-      "gitea_note_append", "gitea_delivery_view", "gitea_commit_statuses", "gitea_open_pulls", "gitea_contains",
+      "gitea_note_append", "gitea_delivery_view", "gitea_commit_statuses", "gitea_open_pulls", "gitea_commit_trees", "gitea_contains",
       "gitea_list_labels", "gitea_create_label",
       "gitea_api",
     ],