Skip to content

MusallahBoard v3: pre-created boards, setup files, USB kits, claim, content_changed - #22

Merged
IbraTech04 merged 11 commits into
developfrom
claude/wizardly-curie-s90b5i
Nov 19, 2026
Merged

IbraTech04 merged 11 commits into
developfrom
claude/wizardly-curie-s90b5i

Conversation

@IbraTech04

Copy link
Copy Markdown
Collaborator

Backend half of the MusallahBoard offline-first restructure. Pairs with:

  • LensBridge/agent: board side
  • LensBridge/LensBridgeFrontend: console

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 .mbu that gives a board its identity.
  • GET /api/admin/board/devices/{id}/usb-kit and GET /api/admin/board/usb-kit: a zip with one MusallahBoard/ folder holding setup and content files plus the latest app and arm64 agent packages.
    • App and agent packages are proxied from the release channels, checked against the channel's sha256 and size, and cached.
    • If a channel can't be reached, that package is left out and named in 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).
    • Repeating the claim with the same key succeeds; a different key gets 409.
    • The key is bound with a conditional update, so two boards racing to claim can't both win.
  • 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.
  • Migration V5: devices.claim_secret, devices.provision_sequence, enrollment_tokens.device_id.

Changed

  • The refresh stream (/api/refresh-musallahboard, BoardStreamHandler) is removed. Content changes now send {"type":"content_changed"} over the agent WebSocket after the commit.
  • musallahboard.baseurl is removed (it was left over from the hosted kiosk).
  • Content packages may cover up to 92 days.
  • The duplicate PATCH /api/admin/board/devices/{id} now lives in one controller.
  • Signing and zip layout are shared between content and provision packages (MbuPackager). Content bytes are unchanged.

Deployment notes

  • Flyway V5 runs on start.
  • Optional musallahboard.agent.backendUrl is the URL written into online setup files. When unset, it is derived from the WebSocket URL.
  • Optional musallahboard.release.{app,agent}-channel-url.
  • The backend needs outbound HTTPS to github.com for kits to include software.
  • MUSALLAHBOARD_BASEURL can be removed from deployed config.

Known trade-offs

  • Downloading an online setup file again rotates the claim secret, so earlier copies can no longer claim.
  • The claim secret is stored in plain text, because the backend has to verify an HMAC made with it. It is never logged.
  • Creating a board is audited as UPDATE_BOARD_CONFIG, because adding a new action means rebuilding a check constraint on SQLite.

Testing

  • Full suite passes, 0 failures.
  • openapi.yaml regenerated; check_openapi.py --strict-ids OK.
  • The claim HMAC test vector was recomputed independently in Python.
  • A sample setup file generated by this code is accepted by the agent's real verification path (test in the agent PR).

Generated by Claude Code

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
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T16:38:06.364200Z c649554 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment on lines +93 to +95
byte[] content = bytesOf(offlineBundleService.build(device.getId(), days));
if (includeSetup) {
put(zip, "setup-" + shortId + ".mbu", bytesOf(setupFileService.build(device.getId(), online)));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment on lines +107 to +109
long previous = device.getProvisionSequence() == null ? 0 : device.getProvisionSequence();
long sequence = Math.max(now.toEpochMilli(), previous + 1);
device.setProvisionSequence(sequence);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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
@IbraTech04
IbraTech04 merged commit 28f8d8f into develop Nov 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants