Public: anyone can read this; the crew can change it.
Home devices: declare the LAN printer once; an app with a grant prints through the forge #10419
The forge can now hold a declared LAN printer and relay an app's PDF to it, but I haven't tried it against the real Brother. bun x tsc --noEmit, scripts/gate.ts, scripts/hollow.ts and scripts/design-lint.ts are clean.
stopped parked by the crew deploy 73036c7
6 earlier comments · 2 events
The forge can now hold a declared LAN printer and relay an app's PDF to it, but I haven't tried it against the real Brother. bun x tsc --noEmit, scripts/gate.ts, scripts/hollow.ts and scripts/design-lint.ts are clean. The new test/devices.test.ts passes against a fake IPP server, as do the reserved-names, shards, check-list, hollow, event-audience, xss-everywhere and openapi tests. I ran those by name and not the full suite, because scripts/fast.ts named 1604 files. The forge's check runs the rest.
What it does
- Declare. The forge's owner (a site admin) declares a device at
/settings/devicesor withPOST /api/v1/devices {name, kind: "printer", url}. The URL must be an IPv4 literal in 10.x, 172.16–31.x or 192.168.x, e.g.ipp://192.168.1.161:631/ipp/print. It is refused if it is loopback, link-local, one of the forge's own cluster ranges, a host name, or carries credentials. - Device page.
/settings/devices/:nameprobes the printer with IPP Get-Printer-Attributes. When all is well it shows one line, e.g.Brother HL-L2350DW · idle · supplies fine. Otherwise it shows the state, reasons and supply levels, or "not reachable". It also lists the apps granted (each with its cap and use today) and recent jobs. - Grant.
PUT /api/v1/devices/:name/grants {app: "owner/name", daily_cap}grants a device to an app; the cap defaults to 10 a day.DELETEwith{app}revokes. - Print. An app calls
POST $FORGE_API_URL/devices/<name>/printwith itsFORGE_TOKENand the PDF as the body, up to 10 MB and 20 pages. A success returns 201 with{job, state, pages}. The refusals are:
- 404: no grant. - 429: over the daily cap. - 422: not a PDF, or more than 20 pages. - 413: too big. - 502: the printer failed.
- No other LAN reach. The relay takes a declared device and re-checks its address on every call. It never follows redirects and reads replies to a fixed size. Nothing in the print request (path, query, header or body) can name an address; the test asserts that.
- Log. Every job past the grant check is logged with app, pages, outcome and job state, and shown on the device page.
- Tests. The fake IPP server covers the grant check, the cap, the PDF limits, a down printer and revocation. A separate test covers the refused LAN addresses.
How an app is identified. The app's token is named app:<slug>/<env> and held by the repo's owner, and the print route requires both. A token named that way but held by anyone else matches no app.
Not done
- No MCP tool for devices.
- No
ipps://: a printer's self-signed certificate would need a trust decision. - PDF page counting reads the bytes. A PDF that hides its page tree in compressed object streams reads as zero pages and is refused as unreadable.
Things to know
- Loopback switch.
FORGE_DEVICE_LOOPBACK=1lets a developer's fake printer on 127.0.0.1 be declared. The test sets it; production leaves it unset. - Event kinds. I added
device.declared,device.removed,device.granted,device.revokedanddevice.printedto the event outbox. - Docs. How-to is in
docs/features/devices.md, and OpenAPI rows are added.
To try it: sign in as the owner and open /settings/devices (it is under Connections). Declare the printer, grant trevato/morning-paper, then curl -H "authorization: Bearer $FORGE_TOKEN" -H 'content-type: application/pdf' --data-binary @paper.pdf "$FORGE_API_URL/devices/<name>/print" from the app.
The pull was failing the gate rule "say why it goes ahead of the pipeline". The pull adds src/actions/devices.ts, src/http/api/devices.ts and src/web/pages/devices.ts, and none of its commit messages had a Why now: line or a Pipeline: #N line. The deploy log you pasted shows the app booting and then draining on SIGTERM, with no application error in it.
I added an empty commit whose message carries Why now: a LAN printer is only reachable from inside the home, so apps that print need the forge to declare it once. I did not rewrite history. bun scripts/gate.ts now passes, and bun x tsc --noEmit is clean. I pushed to the same branch. I did not run any tests; this commit changes no code, and the forge runs the full check on the push.
Nothing else changed in this pull. It still declares a LAN printer once under Home devices, and an app with a grant prints through the forge.
To try it, open the preview at https://lab--10419--forge-trevato-apps.open-platform.sh.
🤖 Generated with Claude Code
The preview needed no fix, and I pushed nothing new. The deploy log ends with done and no error, and / on the preview answers 200. The "failed" label comes from the note "no tests declared, none run". forge.json has no test command under app; the tests run in check.fast and check.verify.
The gate and tsc --noEmit both pass on the current head, 23d9d9a. The working tree is clean and the branch is already pushed.
I did not run the tests for the Home devices change in this turn.
What the pull does: a LAN printer is declared once, and an app with a grant prints through the forge. Device events are classified, the pages are timed, and the page is listed in the audit.
Changes needed (first round, all in one list):
- FIRST: Both doors. The terminal has no devices screen. Add a screen in src/tui/ (list devices, device status line, grants with use today, jobs, declare/grant/revoke/remove) with its entry where AGENTS.md says, gated exactly like the page (site admin only, guest sees nothing), and a test for it. docs/features/devices.md must say how to do it in the terminal. Writes from the terminal must reach web viewers live. The pull body says no MCP tool either; if AGENTS.md lists tools as a door, add them or say why not.
- Speed: devicePage and GET /api/v1/devices/:name await a live IPP probe (up to 5 s) before first paint. The common request must answer in under 50 ms. Server-render the page at once with the declared facts, grants and jobs, and fetch the status separately (a cached probe with a short TTL, or a second request/fragment that works without JS via a link), so a dead printer cannot hang the page or tie up a worker.
- DoS / log growth: rejected prints (not_pdf, too_big, too_long, over_cap) each write a print_job row but do not count toward the cap, so a granted app can fill the table without limit. Rate-limit by the token's identity (or cap rejected rows per app per day, and prune old rows). Also a 'reserved' row left by a crash is counted forever as used; settle stale reserved rows.
- Body cap: for a body over the limit the route allocates a zero-filled 10 MB array to fake the size. Pass a flag or return 'too_big' directly instead of allocating per request.
- Page count is a regex over the bytes and can be understated by a crafted PDF (a fake small /Count with page objects in object streams reads low). Say so plainly in docs/features/devices.md, or enforce the page limit another way; the 20-page limit is otherwise advisory.
- Design (docs/DESIGN.md): principle 1/8: the device list repeats itself (explainer paragraph plus placeholder-only inputs); keep one confident sentence. Principle 3/6: the device page stacks three settings-block sections with h2s and a bare destructive 'Remove this device' button with no confirmation step; separate it and ask first. The Devices nav entry reuses the 'globe' icon of Origins; give it its own. Use the attention-budget for /settings/devices pages if they are measured, not only the settings page.
- Clean: src/actions/devices.ts has raw SQL (getAppByRepoId, misleadingly named, returns a boolean) that belongs in core/apps.ts or core/devices.ts. Duplicate the app-ref parsing in grant/revoke into one function.
- Tests: confirm there are tests that fail without each of: guest and non-admin get 404 on every page and API route; an agent-kind admin is refused; a token named app:<slug>/x held by a non-owner prints nothing; cap race; SSRF refusals for 0300.x/decimal host forms. I could not see the whole test file (cut off); add any missing.
What is good: IPv4-literal-only LAN allowlist re-checked on every call, no redirects, bounded reply, grant is the only door, 404 without a grant, admin gating on every mutation, event audience classified, README untouched.
This round answers all eight points except one part of the design item (the attention budget for the devices pages; see "Not done"). bun x tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts are clean. I ran the devices, MCP, TUI, contract, design, attention and confirm suites and they pass. scripts/fast.ts named 1752 of 2417 files for this diff, so I ran the covering files instead of the full suite.
What changed, by review point
- Terminal and MCP.
- src/tui/screens/devices.ts is the new screen, with its entry in ENTRIES in src/tui/screens/entries.ts. It lists devices, and enter opens one (status line, grants with use today, jobs). n declares, g grants, x revokes, d removes, and the last three ask first.
- It is gated like the page: site admin only, never an agent-kind admin. Anyone else gets no palette entry and sees nothing if they drive the screen directly.
- It calls the same actions as the page, so each write appends the same device.* event, and the screens refresh on those events. A test asserts the four events.
- AGENTS.md and VISION.md count the MCP as a door, so I added a devices tool (admin token; list, show, status, declare, grant, revoke, remove). The conversation-confirm list asks first for everything but list, show and status.
- docs/features/devices.md now covers the terminal and MCP.
- Speed.
- devicePage and GET /api/v1/devices/:name no longer touch the printer. They answer from the database, and a test asserts the printer receives no request.
- The status is its own request: /settings/devices/:name/status (a plain link on the page, no JS) and GET /api/v1/devices/:name/status.
- Probes are cached for 30 s and shared, so a dead printer costs one wait per half minute. The device page shows the cached answer when it is fresh.
- Log growth.
- Refused prints are written at most 50 a day per app (REJECTED_DAILY_MAX); past that they are still answered but not stored.
- Rows older than 30 days are deleted.
- A reserved row older than 10 minutes is settled as failed, so it counts once toward the cap and no longer forever.
- Body cap.
readBounded'stoo_largeis passed through as"too_big", and the 10 MB array is gone. - Page count. I chose to say so plainly rather than enforce it differently.
docs/features/devices.mdnow says the 20-page limit is advisory and can be understated by a crafted PDF, and that the hard bounds are 10 MB and the daily cap. Refusing every PDF with object streams would reject most real PDFs. - Design.
- The list page has one sentence and labelled inputs.
- The device page is one settings block; the jobs sit in a <details>.
- Remove is now a confirmAction through /-/confirm, which I extended with the device wording.
- The Devices nav entry has its own printer icon.
- Clean. The raw SQL is gone: it now uses
getAppByRepo. Grant and revoke share oneappRepoIdparser. - Tests, in
test/devices.test.ts,test/tui-devices.test.tsandtest/mcp-devices.test.ts:
- Guest and non-admin on every page and API route.
- An agent-kind admin refused.
- A token named app:paper/production held by a non-owner prints nothing.
- Four concurrent prints at cap 1 reach the printer once.
- Octal, decimal, hex and shortened-IPv4 host forms are refused.
- The refusal cap, stale-reservation settling and pruning.
- The remove confirmation.
A real bug the new test caught. The pages checked only isAdmin, so an agent-kind admin got a 200 on /settings/devices. Pages now refuse it like the actions do.
Not done
- I did not add
/settings/devicespages toattention-budget.json. Measuring them needs a rendered browser, which this sandbox lacks. The settings page's own budget is unchanged and its test passes. - I did not change the guest response on pages. Guests are sent to sign-in, as every settings page does, and the test accepts that or a 404. Non-admins get 404 everywhere.
To try it. Run with FORGE_DEVICE_LOOPBACK=1 and a fake printer on 127.0.0.1. Declare it in /settings/devices or the terminal palette ("Devices"), grant an app, and POST /api/v1/devices/<name>/print with that app's token.
🤖 Generated with Claude Code
The check's three failures came down to one real cause (the palette roster test) and two tests that passed every time I ran them here. I fixed the first and left the other two alone. I haven't seen the forge's re-run of the check yet.
- Palette roster test:
test/palette-roster.test.tspins the exact list of palette entries. The Devices page this pull adds also adds a "Devices" palette entry, so the test no longer matched. I added that entry to the expected list. It sits between "Secrets" and "Trusted hosts", where the palette puts it. - Search cache and build cart tests: "a repeat search answers identically and far faster than the greps" and "a captured cart plays sandboxed…" pass here, three runs in a row. The search one compares timings, so it can fail when the shard is busy. I didn't find a cause for the cart one, since I didn't have its failure message. If the forge's re-run fails either again, I'll look at its log.
bun x tsc --noEmit is clean. I pushed the fix to the pull's branch as 9f82678b4.
This pull adds Home devices. You declare a LAN printer once, and an app that has a grant prints through the forge. The previous check failed on 3 tests; I fixed one cause and could not reproduce the other two.
- Unreached module (fixed):
src/kernel/why_now.tswas imported by nothing aftermainretired the "why it goes ahead of the pipeline" rule (54dacba00). I merged the currentmain, which brought that in, then deleted the module andtest/why-now.test.ts.test/unreached.test.tsandbun x tsc --noEmitpass, andscripts/gate.tsprinted nothing. - Two ETag tests (not reproduced): "a signed-out page showing a flash carries no ETag and is never a 304" and "a signed-out 404 carries no ETag" passed when I ran
test/etag.test.ts, before and after the merge. I changed nothing for them. If they fail again on this push, the log will say why. - Not run here: the full suite. The forge runs it on this push.
To try it, open the Devices page in settings, declare a printer, and grant an app access. The same flow is available through the /api/v1/devices API, the terminal screen and the MCP tool.
Parked by the crew: the check stayed red through 2 automatic tries
The forge can now hold a declared LAN printer and relay an app's PDF to it, but I haven't tried it against the real Brother.
bun x tsc --noEmit,scripts/gate.ts,scripts/hollow.tsandscripts/design-lint.tsare clean. The newtest/devices.test.tspasses against a fake IPP server, as do the reserved-names, shards, check-list, hollow, event-audience, xss-everywhere and openapi tests. I ran those by name and not the full suite, becausescripts/fast.tsnamed 1604 files. The forge's check runs the rest.What it does
/settings/devicesor withPOST /api/v1/devices {name, kind: "printer", url}. The URL must be an IPv4 literal in 10.x, 172.16–31.x or 192.168.x, e.g.ipp://192.168.1.161:631/ipp/print. It is refused if it is loopback, link-local, one of the forge's own cluster ranges, a host name, or carries credentials./settings/devices/:nameprobes the printer with IPP Get-Printer-Attributes. When all is well it shows one line, e.g.Brother HL-L2350DW · idle · supplies fine. Otherwise it shows the state, reasons and supply levels, or "not reachable". It also lists the apps granted (each with its cap and use today) and recent jobs.PUT /api/v1/devices/:name/grants {app: "owner/name", daily_cap}grants a device to an app; the cap defaults to 10 a day.DELETEwith{app}revokes.POST $FORGE_API_URL/devices/<name>/printwith itsFORGE_TOKENand the PDF as the body, up to 10 MB and 20 pages. A success returns 201 with{job, state, pages}. The refusals are:- 404: no grant. - 429: over the daily cap. - 422: not a PDF, or more than 20 pages. - 413: too big. - 502: the printer failed.
How an app is identified. The app's token is named
app:<slug>/<env>and held by the repo's owner, and the print route requires both. A token named that way but held by anyone else matches no app.Not done
ipps://: a printer's self-signed certificate would need a trust decision.Things to know
FORGE_DEVICE_LOOPBACK=1lets a developer's fake printer on 127.0.0.1 be declared. The test sets it; production leaves it unset.device.declared,device.removed,device.granted,device.revokedanddevice.printedto the event outbox.docs/features/devices.md, and OpenAPI rows are added.To try it: sign in as the owner and open
/settings/devices(it is under Connections). Declare the printer, granttrevato/morning-paper, thencurl -H "authorization: Bearer $FORGE_TOKEN" -H 'content-type: application/pdf' --data-binary @paper.pdf "$FORGE_API_URL/devices/<name>/print"from the app.Closes #10413