Repository navigation
MusallahBoard v3: pre-created boards, setup files, USB kits, claim, content_changed - #22
Conversation
The /api/refresh-musallahboard socket was the v1 hosted kiosk's push channel;
only the agent still listened, on a second, unauthenticated connection. Every
place that pushed on it now sends {"type":"content_changed"} over the agent's
own authenticated WebSocket, after the change commits: content edits to every
connected board, config, name and audience changes to that board, and
POST /api/admin/board/refresh to every board.
musallahboard.baseurl, the CORS origin of the hosted kiosk, goes with it: the
board app is served by the agent from the board itself.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
The rename/audience endpoint lived in BoardAdminController under the /api/admin/board/devices prefix that DeviceAdminController owns, so finding every device endpoint meant reading two controllers. Same URL, permission, audit and content_changed push; one owner. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A board visited by USB stick once a quarter needs three months of payloads in one package. A day's payload is a few KB, so the cap only bounds a hostile request, and the agent's limit moves to the same 92 (contract C4). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
A board no longer has to come online before the backend knows it (contracts
C1, C3, C4):
- POST /api/admin/board/devices creates the device and its config with no
public key. Its config, content packages and setup file work at once.
- GET /api/admin/board/devices/{id}/setup-file returns the board's setup
file: a provision .mbu holding provision.json (deviceId, displayName,
sequence, issuedAt), signed with the content key by the same packager as
content packages. ?online=true adds backendUrl and a new claim secret,
which replaces the stored one. Every download has a higher sequence.
V5 adds devices.claim_secret and devices.provision_sequence, and
enrollment_tokens.device_id for the token path that follows. The secret is
stored as is (the claim is an HMAC over it), excluded from toString and from
every response but the setup file, and never logged.
enrolledAt is now null until a board first connects, and new boards share
the default config token enrollment used.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
POST /api/agent/claim (contract C2): a board set up with an online setup
file sends {deviceId, publicKey, proof, agentVersion, hostname}, where proof
is base64url(HMAC-SHA256(claimSecret, deviceId + "\n" + publicKey)). The
proof is compared in constant time. A device with no key binds this one
(a conditional update, so two racing boards cannot both win), the same key
again succeeds so a lost response can be retried, a different key is 409.
Unknown, revoked, never-online devices and wrong proofs are one 401. The
response is enrollment's: deviceId, websocketUrl, contentSigningKeys.
The endpoint is open like /api/agent/enroll and shares its per-address rate
limit. Neither the secret nor the proof is logged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
POST /api/admin/board/devices/{id}/enrollment-tokens mints a token that
enrolls the board already added in the console: musallahboard-agent enroll
--token binds its key to that row (enrollment_tokens.device_id, V5) instead
of creating a new device. It replaces a key the board had, which is how a
maintainer re-keys a board after an SD card swap, and closes the old key's
live session after commit. The generic token endpoint still creates a new
device, for the legacy path.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
GET /api/admin/board/devices/{id}/usb-kit and GET /api/admin/board/usb-kit
(contract C4) return a zip holding one MusallahBoard/ folder:
content-<id8>.mbu per board, setup-<id8>.mbu per board with
includeSetup=true (online=true for online setup files), and the latest
board app and arm64 agent .mbu from the release channels the agent follows.
The channels are fetched on demand, checked at most every 30 minutes and the
package is kept in memory, checked against the channel's sha256 and size and
passed on byte for byte: the backend never signs software, the board
verifies it with its release key. When GitHub cannot be reached and nothing
is cached, the kit goes without that package and X-Usb-Kit-Omitted says why.
The kit is written to a temp file first, so memory stays bounded by one
board's package and a failure is still a JSON error. Content kits need
board:device:read; setup files need board:device:enroll as well.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Contract C6 asks that dated items carry an end date and that per-day assembly leave them out after it. Posters already require startTime and endTime and each day of a package asks for the posters overlapping that day; OfflineBundleServiceTest covers the assembly with a faked query. This runs the real query on the migrated schema. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
websocketUrl is now returned by the claim as well as by enrollment, and docs/MIGRATIONS.md never existed; MigrationParityTest is what holds the two migration directories together. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c649554d3e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| byte[] content = bytesOf(offlineBundleService.build(device.getId(), days)); | ||
| if (includeSetup) { | ||
| put(zip, "setup-" + shortId + ".mbu", bytesOf(setupFileService.build(device.getId(), online))); |
There was a problem hiding this comment.
Roll back setup-file issuance when a multi-board kit fails
When an all-boards kit includes online setup files, each call to setupFileService.build commits its rotated claim secret independently. If content generation for a later board fails—for example, because its poster cannot be fetched—the entire ZIP is deleted, but earlier boards retain their newly committed secrets. Previously downloaded setup files for those boards can consequently no longer claim, even though the replacement files were never delivered. Make setup-file issuance atomic across the kit build, or defer committing the rotations until all board packages have been built successfully.
Useful? React with 👍 / 👎.
| long previous = device.getProvisionSequence() == null ? 0 : device.getProvisionSequence(); | ||
| long sequence = Math.max(now.toEpochMilli(), previous + 1); | ||
| device.setProvisionSequence(sequence); |
There was a problem hiding this comment.
Serialize setup-file sequence and secret updates per device
When two setup-file downloads for the same board overlap (including a standalone download racing with a USB-kit build), both transactions can read the same previous sequence because the device lookup takes no lock and Device has no version field. They can issue identical sequences or commit in reverse sequence order, leaving the stored claim secret associated with an older file. A board that applied the higher-sequence file then cannot claim with its secret and will reject the lower-sequence replacement. Allocate the sequence and rotate the secret under a per-device database lock or an equivalent atomic update.
Useful? React with 👍 / 👎.
Two downloads of a board's setup file at once (a standalone file racing a kit, say) both read the same previous sequence: they could issue the same sequence, or commit in reverse order and leave the stored claim secret belonging to the older file. The sequence is now allocated by one conditional UPDATE (one more than the last, or the clock when greater; revoked and unknown boards match no row), issued as the transaction's first statement so it takes the row's lock (the database's on SQLite) before reading the old value. The secret is replaced under that lock, and the file is built from the row read back. A kit with online setup files committed each board's rotation on its own, so a failure on a later board left earlier boards with new secrets nobody received. The kit now writes every content package and the releases first (posters and GitHub, outside any transaction, nothing stored), then issues every board's setup file in one transaction, in id order, that commits only after the zip is complete; any failure rolls back every board's sequence and secret. Setup files now come last in the zip, which boards do not mind: they apply setup files before content from one stick. SetupFileIssuanceTest runs this on the migrated SQLite schema with real commits: a kit whose last board fails (content, or its setup file) changes no board, and four concurrent issuances in one millisecond get four consecutive sequences with the newest file's secret stored. The same test passes on Postgres 16 and fails on both databases with the old code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
Backend half of the MusallahBoard offline-first restructure. Pairs with:
Added
POST /api/admin/board/devices: create a board with no key. Offline bundles work for it straight away.GET /api/admin/board/devices/{id}/setup-file?online=: a signed provision.mbuthat gives a board its identity.GET /api/admin/board/devices/{id}/usb-kitandGET /api/admin/board/usb-kit: a zip with oneMusallahBoard/folder holding setup and content files plus the latest app and arm64 agent packages.X-Usb-Kit-Omitted.POST /api/agent/claim: an online board binds its own public key by proving it holds the claim secret (HMAC-SHA256, constant-time comparison).POST /api/admin/board/devices/{id}/enrollment-tokens: an enrollment token bound to an existing board. This is the maintainer path, and also how a board is re-keyed after an SD card swap.devices.claim_secret,devices.provision_sequence,enrollment_tokens.device_id.Changed
/api/refresh-musallahboard,BoardStreamHandler) is removed. Content changes now send{"type":"content_changed"}over the agent WebSocket after the commit.musallahboard.baseurlis removed (it was left over from the hosted kiosk).PATCH /api/admin/board/devices/{id}now lives in one controller.MbuPackager). Content bytes are unchanged.Deployment notes
musallahboard.agent.backendUrlis the URL written into online setup files. When unset, it is derived from the WebSocket URL.musallahboard.release.{app,agent}-channel-url.MUSALLAHBOARD_BASEURLcan be removed from deployed config.Known trade-offs
UPDATE_BOARD_CONFIG, because adding a new action means rebuilding a check constraint on SQLite.Testing
openapi.yamlregenerated;check_openapi.py --strict-idsOK.Generated by Claude Code