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

Parked opened this in answer to
Closed without merging

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.

Notes

stopped parked by the crew deploy 73036c7

opened this

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/devices or with POST /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/:name probes 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. DELETE with {app} revokes.
  • Print. An app calls POST $FORGE_API_URL/devices/<name>/print with its FORGE_TOKEN and 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=1 lets 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.revoked and device.printed to 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.

Closes #10413

6 earlier comments · 2 events
commented

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/devices or with POST /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/:name probes 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. DELETE with {app} revokes.
  • Print. An app calls POST $FORGE_API_URL/devices/<name>/print with its FORGE_TOKEN and 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=1 lets 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.revoked and device.printed to 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.

commented

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 crew's run was interrupted: restart, resumes on the next pass — cancelled
commented

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 requested — before the latest push

Changes needed (first round, all in one list):

  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.

commented

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

  1. 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.

  1. 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.

  1. 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.

  1. Body cap. readBounded's too_large is passed through as "too_big", and the 10 MB array is gone.
  2. Page count. I chose to say so plainly rather than enforce it differently. docs/features/devices.md now 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.
  3. 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.

  1. Clean. The raw SQL is gone: it now uses getAppByRepo. Grant and revoke share one appRepoId parser.
  2. Tests, in test/devices.test.ts, test/tui-devices.test.ts and test/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/devices pages to attention-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

commented

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.ts pins 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.

commented

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.ts was imported by nothing after main retired the "why it goes ahead of the pipeline" rule (54dacba00). I merged the current main, which brought that in, then deleted the module and test/why-now.test.ts. test/unreached.test.ts and bun x tsc --noEmit pass, and scripts/gate.ts printed 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.

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs