enricobuehler
539ac2f2a5
Reported from the field: "is there a possibility of renaming the moonlight paired
devices? as they're all named CN=NVidia Gamestream Client". They are, and it is not a
display bug — every moonlight-common-c client self-signs with that same fixed subject,
so the certificate carries no device identity at all. Until now the console listed that
string for every Moonlight row, which means a user with a phone, a TV and a Switch saw
three identical rows and had nothing but a fingerprint prefix to tell them apart — most
sharply when deciding which one to unpair.
The name is an operator-supplied label, stored host-side keyed by fingerprint:
* `client-labels.json`, a SIDECAR to `paired.json` rather than a field inside it.
`paired.json` is a bare `Vec<Vec<u8>>` of DERs, so giving it a shape would be a
migration on the one file that decides who may connect — and a label is not part of
that trust decision, so a corrupt or missing label file must never be able to lock
anyone out. Same atomic temp-file + rename as `save_paired`.
* `PATCH /api/v1/clients/{fingerprint}` sets or clears it; `GET /clients` grows a
`label`. A whitespace-only body clears rather than storing a blank name, and only an
already-paired fingerprint may be named (a label for an unknown one would be
invisible and never cleaned up). Unpairing forgets the label, so the file cannot grow
without bound and a re-pairing of the same certificate starts unnamed.
* Scrubbing reuses `native_pairing::sanitize_device_name` rather than growing a second
one: it already strips C0/C1 controls and Unicode bidi overrides and caps at 64.
That is not cosmetic here — the label is the ONLY thing distinguishing two paired
devices in the console, so an unscrubbed one could dress a stranger's device up as
the operator's TV and be spared an unpair on that basis. For the same reason the new
route takes the plugin/cert lanes of the DELETE beside it (neither may reach it),
not the roster GET's read permission; the lane test now pins that.
* Console: a pencil on Moonlight rows opens the existing `promptText` dialog seeded
with the current label (not the `CN=…` fallback, or every rename would start by
deleting boilerplate). Native rows keep their pairing-supplied name and get no
pencil.
Test: one round trip through the API — name it, see it in the list, watch the bidi
override and the whitespace collapse get scrubbed, clear it two ways, reject a
malformed and an unpaired fingerprint, and assert the unpair forgot it on disk.
VERIFIED on .173 (the Windows box, since punktfunk-host does not build on macOS):
`cargo test -p punktfunk-host mgmt::` → 58 passed, including the new
`client_label_round_trips_scrubs_and_is_forgotten_on_unpair` and both guardrails that
caught this work in progress (`every_route_is_classified_for_the_plugin_and_cert_lanes`
and `openapi_document_is_complete_and_checked_in`). Web `tsc --noEmit` clean.
Two notes on the diff, both PRE-EXISTING and verified as such rather than assumed:
* `sdk/src/gen/punktfunk.ts` is bigger than this feature. Regenerating it from the
UNCHANGED committed spec already produces a ~700-line diff, i.e. the checked-in copy
had drifted from its own pinned generator — nothing in CI regenerates or verifies
it. This lands the clean regeneration rather than hand-patching generated code.
* `api/openapi.json` was regenerated on Windows, not CI's Linux. Checked structurally
before committing: the only differences are `PATCH /clients/{fingerprint}`, the
`RenameClient` schema and `PairedClient.label` — no OS-driven drift.
Unrelated and NOT touched: `mgmt::tests::display_monitors_answers_even_with_no_compositor`
fails on Windows, at HEAD as well. It answers `compositor="windows", monitors=[],
error=null`, and the test's escape hatches only cover gamescope, an absent compositor or
an error. Either the test needs a Windows arm or Windows display enumeration is returning
nothing it should — that is a real question, so it is left for someone to answer rather
than papered over here.
punktfunk web — management console
The browser UI for the punktfunk host's management REST API (crates/punktfunk-host/src/mgmt.rs,
OpenAPI at api/openapi.json). It shows live status, host capabilities, paired
clients, the pairing-PIN flow, and session controls.
Stack: TanStack Start (full SSR) on Bun via Nitro v2 (bun preset) · React
Query through orval codegen from the OpenAPI spec · @unom/ui
— the shared punktfunk/unom design system the marketing site + docs are built on (Tailwind v4,
animated components on the violet brand over dark chrome) ·
Paraglide i18n (en/de). Package manager + runtime: Bun.
The @unom registry mapping lives in .npmrc; the auth token comes from
~/.npmrc (or a CI secret).
Develop
# from web/ — Bun is the toolchain (https://bun.sh)
bun install # runs `prepare` → codegen (orval + paraglide)
bun run dev # http://localhost:47992
# The dev server proxies /api → https://127.0.0.1:47990 (the host's mgmt API; it serves HTTPS
# with the host's self-signed identity cert — the dev proxy uses `secure: false`).
# Point it elsewhere: PUNKTFUNK_MGMT_URL=https://<host>:47990 bun run dev
Start a host with the management API up:
# from the repo root — `serve` brings up the native punktfunk/1 plane + the mgmt API (the console
# only needs the mgmt API; add --gamestream too if you also want the Moonlight surface):
WAYLAND_DISPLAY=wayland-kde XDG_CURRENT_DESKTOP=KDE \
cargo run -rp punktfunk-host -- serve
# loopback :47990, no token (a token is mandatory for non-loopback binds).
The management token is server-side only — set PUNKTFUNK_MGMT_TOKEN in the console's
environment and the BFF injects it when proxying (server/routes/api/[...].ts). It never reaches
the browser, so there is no token field in the UI; the browser only ever holds the session cookie.
Build & run (Nitro + Bun)
The console runs on bun (Bun.serve is a Bun API — node can't run it): Nitro's bun preset
plus a custom entry (nitro-entry/bun-https.mjs) that calls Bun.serve({ tls }), so it serves
HTTPS (HTTP/1.1 over TLS) with the host's own identity cert (the cert native clients already
pin). One trust anchor across the data plane, the mgmt API, and this console. (No HTTP/2 — Bun.serve
has no h2 server — and no HTTP/3, which a browser won't speak against this self-signed, no-SAN host
cert; a browser-trusted, SAN-matching cert + a fronting server would be needed, out of scope for a
LAN console.)
bun run build # → .output/ (Nitro `bun` preset + our Bun.serve TLS entry)
PORT=47992 HOST=0.0.0.0 \
PUNKTFUNK_UI_PASSWORD=… PUNKTFUNK_MGMT_TOKEN=… \
PUNKTFUNK_MGMT_URL=https://127.0.0.1:47990 \
PUNKTFUNK_UI_TLS_CERT=~/.config/punktfunk/cert.pem \
PUNKTFUNK_UI_TLS_KEY=~/.config/punktfunk/key.pem PUNKTFUNK_UI_SECURE=1 \
bun run start # = bun run .output/server/index.mjs
# PUNKTFUNK_UI_TLS_* unset ⇒ plain HTTP (local dev); both set ⇒ HTTPS (HTTP/1.1 over TLS).
# The host's self-signed mgmt cert is accepted only for the proxy's loopback hop, scoped in code
# (Bun per-request TLS: server/routes/api/[...].ts) — no process-wide NODE_TLS_REJECT_UNAUTHORIZED.
# See .env.example.
bun run lint # tsc --noEmit
The built Nitro bun server SSR-renders the app and is the only thing exposed on the LAN.
Run it on the same box as the host; it serves the console over HTTPS on :47992 (or $PORT).
Auth (backend-for-frontend)
Single-user, login-gated. Config via env (see .env.example):
- The console requires a login (
PUNKTFUNK_UI_PASSWORD). On success the server sets a sealed session cookie (h3useSession, AES-GCM).server/middleware/auth.tsgates every request — pages redirect to/login,/apireturns 401 — and fails closed (503) ifPUNKTFUNK_UI_PASSWORDis unset, so a misconfigured LAN server admits no one. - The bearer-token admin surface of the management API is loopback-only — the host honors a
bearer token only from a loopback peer, so the admin API is never LAN-exposed. The web server
holds
PUNKTFUNK_MGMT_TOKENserver-side and injects it when proxying/api/**→PUNKTFUNK_MGMT_URL(loopback;server/routes/api/[...].ts). The token never reaches the browser; the browser only ever holds the session cookie. (The host also binds the read-only surface — host status + the game library — to the LAN so paired native clients can fetch it directly over mTLS; that path uses client certs, not the token, and never touches this console.)
So: browser ──password──▶ web server (session cookie) ──mgmt token, server-side──▶ mgmt API.
Run the host with a matching token: cargo run -rp punktfunk-host -- serve +
PUNKTFUNK_MGMT_TOKEN=… (or --mgmt-token …). vite dev has no gate (localhost-only) and
proxies straight to the loopback mgmt API.
Toolchain notes (load-bearing): TanStack Start's
start-plugin-corepeer-requires Vite ≥ 7 — on Vite 6 the build's prerender/post-build hook silently doesn't run.@vitejs/plugin-reactmust match Vite (v5 ↔ Vite 7, v6 ↔ Vite 8); it's required even for dev (TanStack Start's dev mode needs the React Refresh runtime, else a blank screen). Nitro is the server target — without itvite buildonly emits client+SSR bundles, no deployable server. The Nitrobunpreset makes.output/server/index.mjsBun-runnable.
Codegen
Generated code is not committed (gitignored) — reproduced from sources:
bun run codegen— regenerate the API client (orval) + i18n runtime (paraglide). Runs onbun install(prepare) and beforedev/build(pre*for orval; the Vite plugin compiles paraglide on dev/build).- After a management-API change, regenerate the spec on the Rust side first:
cargo run -p punktfunk-host -- openapi > api/openapi.json, thenbun run api:gen.
Layout
src/
routes/ file-based routes (index=dashboard, host, clients, pairing, settings)
components/
app-shell.tsx sidebar nav (brand lens + wordmark) + language switcher
brand-mark/wordmark/logo.tsx punktfunk lens mark + wordmark (shared with the site/docs)
ui/ @unom/ui-backed primitives (button, input, label, card; badge/table/skeleton)
query-state.tsx loading/error wrapper (401 → the session is gone, re-login)
api/
fetcher.ts orval mutator: base URL, bearer token, JSON, throwing ApiError
gen/ GENERATED react-query hooks + models (orval)
lib/i18n.ts reactive Paraglide locale hook
paraglide/ GENERATED i18n runtime (paraglide)
messages/{en,de}.json translation sources