Write design 61, the print and scan page, as the home of ADR 0479

2026-10-21 11:15:36 +02:00
parent a0ab91dcae
commit e0118ca67e
2 changed files with 69 additions and 0 deletions
@@ -0,0 +1,68 @@
+---
+layer: to-be
+status: proposed
+code: [mesh-catalog]
+updated: 2026-10-21
+decisions:
+  - "ADR 0479"
+  - "ADR 0468"
+  - "ADR 0440"
+---
+
+# 61 — The print and scan page
+
+**A web page where the people the operator names sign in with Keycloak, print a document and scan from the glass
+or the feeder, and where only the operator manages the printer. It is a module of its own, `print-and-scan`, that
+knows only the seats `printer`, `scanner` and `object-store`, so any module holding the printer and scanner seats
+works with it unchanged.** (ADR 0479, proposed and not in force.)
+
+**Acceptance.** A person named in `users`, on a phone that is not a machine of the mesh, signs in, uploads a PDF
+and finds it printed, and scans the glass and downloads the PDF; that person is refused the printer's settings and
+its restart, which a person named in `managers` may use; a browser that has not signed in sees nothing but the
+sign-in.
+
+## 1. The parts
+
+```
+a browser (a phone or laptop, inside the mesh or not)
+   │  HTTPS, through the route proxy's public name, signed in with Keycloak
+   ▼
+print-and-scan — renders the pages on the server, holds a bucket of its own
+   │  printer.status · printer.print · printer.settings · printer.configure · printer.restart
+   │  scanner.scan · scanner.status · object-store.link
+   ▼
+the holders of the printer, scanner and object-store seats ── signed links ──▶ the object store
+```
+
+The page claims the seat `print-and-scan`, held once for the mesh, with the verbs `open` and `status`. It calls
+only seat verbs, never a module's own tool, and knows no device's protocol (ADR 0479 §1).
+
+## 2. Who may do what
+
+The page requires a Keycloak client, as the mail web client does (ADR 0440 §3). Two trusted settings name the
+identities let in, by the ID token's user name: `users` print and scan, `managers` also manage. Both are empty by
+default. A browser that has not signed in is sent to the sign-in; an identity in neither setting gets a refusal page
+that names no holder, document or setting (ADR 0479 §2, §3).
+
+Its route is public, so a person reaches it from a device that is not a machine of the mesh; this is where it
+differs from the mail web client, whose route is internal only (ADR 0479 §3).
+
+## 3. Documents
+
+A document goes from the browser to the page over HTTPS, and from the page into its own bucket by a link the object
+store signs; it never crosses the bus, and a signed link never reaches a browser, because the links name the store's
+internal name (ADR 0468 §3, ADR 0479 §4). To print, the page names its own bucket and the key; its bucket shares
+reading with the printer seat (ADR 0479 §5). A scan is read from the scanner's bucket, which shares reading with the
+page, and streamed to the browser as a download (ADR 0479 §6).
+
+## 4. Managing the printer
+
+Every user sees the printer's state. Reading and changing its settings and restarting it are the printer seat's
+verbs, for managers only, and each call names who asked (ADR 0479 §7). Those verbs are proposed in ADR 0474; until it
+is accepted and built, the page shows only the state.
+
+## 5. Still open
+
+- **Several printers.** The page serves the seats' one holder; issue 1602 asks for the decision that lets a second
+  printer join, after which the page lets the user choose (ADR 0479 §8).
+- **Order.** The page is built after design 60's milestones F1 to F3 (ADR 0479 §9).
@@ -60,6 +60,7 @@ document is written and this one's status becomes `implemented`.
 | [`58-agent-work-as-the-meshs-own.md`](58-agent-work-as-the-meshs-own.md) | **Designed.** Agent work as the mesh's own: a thread seat keeps every thread whole on the bus; a thread handler runs the harness headless in a sandbox per session, the workspace on the thread's own forge branch; a workspace toolkit and named tools, no general command runner; one identity seat for persons, agents and modules, roles of grants, every tool an effect, signed bus logins, and the switch to them one identity at a time | ADR 0383, ADR 0384, ADR 0385, ADR 0386, ADR 0387, ADR 0388, ADR 0389, ADR 0390 |
 | [`59-the-mail-web-client.md`](59-the-mail-web-client.md) | **In progress.** The operator's mail, every account, in a browser on the mesh's own machines: a module of its own, `mesh-mail-web`, holds `mail-webclient`, renders pages on the server and reads and sends only through `mail-store`'s verbs under a caller granted per account; its route reaches the private network only, the operator signs in with Keycloak, and a mail goes out only on the operator's Approve; then Betterbird is removed | ADR 0440, ADR 0378, ADR 0379 |
 | [`60-the-brother-module.md`](60-the-brother-module.md) | **Proposed.** One module, `brother`, holds the `scanner` and `printer` seats for the Brother multifunction device: scans from the glass (cropped) or the feeder (one PDF), keeps each scan in its bucket and announces it, prints in one call, reads the admin pages and changes settings on those where a mistake cannot lock the operator out, each change recorded and told; only its device process holds the credentials | ADR 0467, ADR 0464, ADR 0468, ADR 0474 |
+| [`61-the-print-and-scan-page.md`](61-the-print-and-scan-page.md) | **Proposed.** A web page, behind a Keycloak sign-in and on a public name, where the people the operator names print and scan, and only managers manage the printer: a module of its own, `print-and-scan`, that calls only the printer, scanner and object-store seats, so any holder of those seats works with it; documents go from the browser to the page and by signed links to the store, never over the bus | ADR 0479, ADR 0468, ADR 0440 |

 ## Not yet written