Skip to content

Trusted-proxy client IP and bounded device commands - #21

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

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

Conversation

@IbraTech04

@IbraTech04 IbraTech04 commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Backend fixes from the MusallahBoard production-readiness survey. Supersedes the intent of open PRs 11 and 14 (which target minbar-features) on the develop line.

1. Client address only from trusted proxies

With forward-headers-strategy=framework, any client could choose its own IP through X-Forwarded-For, getting a fresh rate-limit bucket per request and forging audit IPs.

  • Example config switches to native (Tomcat RemoteIpValve, trusted proxies only).
  • nginx overwrites X-Forwarded-For with $remote_addr; upstream port corrected to 8085.
  • compose binds the app port to 127.0.0.1 by default (LENSBRIDGE_BIND_ADDRESS to override).
  • Integration test through embedded Tomcat; it fails if the strategy is set back to framework.

2. Commands: bounded TTL and deadline, validated payloads

  • Max TTL per kind: 10 min for reboot / kiosk restart / install-now, 15 min for screenshot and log tail, 1 h for reload and config refresh. Deadline capped at 15 min.
  • Kinds without parameters reject a non-empty payload; logs.tail accepts only {"lines": 1..500}. The console's current requests are replayed in a test and pass.
  • openapi.yaml regenerated.

Dropped from this PR

The refresh-stream signature check and revoke hook were reverted: the refresh stream is being removed in favour of a content-changed message on the agent WebSocket.

Deployment changes required on the server

  1. Production application.properties: server.forward-headers-strategy=native.
  2. Live nginx: proxy_set_header X-Forwarded-For $remote_addr; and upstream port 8085. Behind Cloudflare, add set_real_ip_from / real_ip_header CF-Connecting-IP first.
  3. Recreate the container so 8085 is not published on all interfaces.

Testing

Full suite: 890 tests, 0 failures.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE

/api/refresh-musallahboard accepted any socket that named a known,
unrevoked ?deviceId=, and a newcomer closed the existing session for that
device. Device ids are not secret, so anyone could keep evicting a board
from its push channel and watch when pushes arrive.

BoardStreamHandshakeInterceptor now checks the upgrade with the existing
X-MB-* device signature (DeviceRequestAuthenticator: GET, the path, an
empty body):
- a present signature is always verified; a bad or partial one is 401;
- the device comes from the signature, and a ?deviceId= naming another
  device is 400 (the query is not signed);
- each signed upgrade must carry a newer timestamp than the last one
  accepted for that device, because the scheme accepts replays inside
  its five-minute window and here a replay would displace the board;
- an unsigned upgrade is 401 when
  musallahboard.board-stream.require-signature is true. While it is
  false (the default, for boards still on an older agent) it is accepted
  and logged, and the handler never lets it displace a signed session
  for the same device (closed with 4004 signed_session_active).

BoardStreamHandler gains disconnect(deviceId) for revokes, and its
javadoc now describes the agent it serves rather than kiosk pages and a
ten-minute poll.

BoardStreamHandshakeInterceptorTest verifies the agent's golden vector
(fixed key and time) with the real authenticator, so the two sides agree
on the signed message.
Revoking a device closed only its agent WebSocket; the board stream
stayed open and kept receiving pushes until the board disconnected on
its own. revoke now also calls BoardStreamHandler.disconnect, which
closes it with 4003 device_revoked; the reconnect fails both the
signature and the enrollment check.
server.forward-headers-strategy=framework installs Spring's
ForwardedHeaderFilter, which believes X-Forwarded-For and Forwarded from
any peer. getRemoteAddr(), and with it the rate-limit bucket, the audit
log address and an enrolling board's lastSeenIp, was whatever the caller
wrote: a fresh header per request was a fresh bucket.

The example configuration now uses the native strategy. Tomcat's
RemoteIpValve honours X-Forwarded-For only on a connection from a
trusted proxy (server.tomcat.remoteip.internal-proxies; unset, loopback
and the private ranges), reads it from the right and stops at the first
untrusted address, so entries a client prepends are never used. On
other connections the socket address stands and X-Forwarded-* are
ignored; the RFC 7239 Forwarded header is never read. A trusted proxy's
X-Forwarded-Proto/-Host/-Port still give the app https, secure requests
and the public host, which the WebSocket same-origin check uses.

The valve rather than an application filter: it runs in the container
before any filter, so nothing in the app can be ordered ahead of it,
and it is the configuration Spring Boot already maintains.

ClientAddressProxyIntegrationTest sends real requests to an embedded
Tomcat set up from these properties, with the production WebConfig and
RateLimitingFilter (MockMvc would skip the valve). From an untrusted
peer, rotating X-Forwarded-For or Forwarded: for= keeps charging one
bucket until 429; through a trusted proxy each client gets its own, and
the client's prepended entries are ignored. With the old strategy the
untrusted-peer tests fail.
…-For

- docker-compose.yml published 8085 on every interface, so the proxy
  could be bypassed. It now binds 127.0.0.1 unless
  LENSBRIDGE_BIND_ADDRESS says otherwise.
- nginx is the edge, so it sets X-Forwarded-For to $remote_addr instead
  of appending to the client's, with a note on restoring the client
  address first when a CDN sits in front. It also drops any client
  Forwarded and X-Forwarded-Prefix headers.
- The nginx upstream pointed at lensbridge:8080; the app listens on
  8085.
IssueCommandRequest only required deadlineMs and ttlSeconds to be
positive, and the dispatcher stored whatever payload JSON it was given.
A system.reboot issued with a year-long TTL would fire whenever an
offline board next connected, and any payload reached the board as sent.

- Each CommandKind now carries a maximum time-to-live: 10 minutes for the
  disruptive kinds (kiosk.restart, system.reboot, update.install_now),
  15 for chrome.screenshot and logs.tail, an hour for chrome.reload and
  config.refresh. The 5-minute default fits all of them. ttlSeconds is
  also capped at an hour on the DTO, deadlineMs at 15 minutes (the
  console gives update.install_now 10).
- Each kind has a payload rule. Parameterless kinds take none: absent,
  null or {} (what the admin console sends); anything else is refused.
  logs.tail takes {"lines": n} with n a whole number from 1 to 500, the
  agent's bounds, and no other field. What is stored and sent is rebuilt
  from the checked values.
- Every failure is a 400 whose message names the field and the limit.

DeviceAdminControllerIssueCommandTest replays the exact requests
CommandLauncher.jsx sends and expects them accepted.
- issueDeviceCommand documents its 400 and the per-kind limits;
  IssueCommandRequest gains maximum 900000 on deadlineMs and 3600 on
  ttlSeconds.
- revokeDevice says it also closes the refresh stream.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 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-17T06:24:32.965607Z 612faa0 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.

The refresh stream is being removed in favour of a content-changed
message on the agent WebSocket.

This reverts commits c18275b and 7bad652.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YY5BHXmNUhs48eubkKCNuE
@IbraTech04 IbraTech04 changed the title Device channel hardening: authenticated refresh stream, trusted-proxy client IP, bounded commands Trusted-proxy client IP and bounded device commands Nov 19, 2026
@IbraTech04
IbraTech04 merged commit a1c6512 into develop Nov 19, 2026
1 check failed
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