How does each of the three surfaces actually enrol? #42

New issue

Closed

opened 2026-07-30 13:15:03 +00:00 by aiko · 1 comment

aiko commented

2026-07-30 13:15:03 +00:00

Owner

Question

ADR-0011 makes the go-between mint a short-lived enrolment code and issue a
long-lived per-device token. denpa#40 says the Receiver offers "code entry and
QR". Neither says what that means per surface, and the surfaces are not alike:

The desktop shell has no camera, so a QR is only scannable by it if the
code is displayed elsewhere — or the flow is type-the-code and QR never applies.
The tablet and the phone have cameras, but the code is minted at the
server console, which is the desktop machine. Scanning means pointing the
Android device at the desktop's screen.
The code is minted "at the server console, or through Hermes purely as
transport". Whether the Hermes-relayed path is needed at all when the operator
is standing at their own console is open.

Decide the concrete flow for each of the three surfaces: where the code is
displayed, how it is entered, whether QR earns its place, and what the operator
does when they are not at the console.

Rough it out rather than arguing it — /prototype a stub of each surface's
enrolment screen and react to it.

denpa/docs/adr/0011-devices-pair-to-the-go-between.md
ollvt-hermes-bridge#26 — mint, hash, TTL, consume, issue, check
denpa#40 — the Receiver half

Map: aiko/denpa#41

## Question ADR-0011 makes the go-between mint a short-lived enrolment code and issue a long-lived per-device token. `denpa#40` says the Receiver offers "code entry and QR". Neither says what that means per surface, and the surfaces are not alike: - The **desktop** shell has no camera, so a QR is only scannable *by* it if the code is displayed elsewhere — or the flow is type-the-code and QR never applies. - The **tablet** and the **phone** have cameras, but the code is minted at the **server console**, which is the desktop machine. Scanning means pointing the Android device at the desktop's screen. - The code is minted "at the server console, or through Hermes purely as transport". Whether the Hermes-relayed path is needed at all when the operator is standing at their own console is open. Decide the concrete flow for each of the three surfaces: where the code is displayed, how it is entered, whether QR earns its place, and what the operator does when they are not at the console. Rough it out rather than arguing it — `/prototype` a stub of each surface's enrolment screen and react to it. ## Related - `denpa/docs/adr/0011-devices-pair-to-the-go-between.md` - `ollvt-hermes-bridge#26` — mint, hash, TTL, consume, issue, check - `denpa#40` — the Receiver half --- Map: `aiko/denpa#41`

aiko added the

wayfinder:ticket

wayfinder:prototype

labels

2026-07-30 13:15:03 +00:00

aiko commented

2026-07-30 17:08:27 +00:00

Author

Owner

Resolution

The code is minted at the server's own CLI, which prints it as text and as a QR code in the terminal.

Operator's call, 2026-07-30: it is a server application, so the console is a first-class place to run a command, and terminals can render QR codes perfectly well.

The flow, per surface

Minting — a subcommand on the go-between. run_server.py already uses argparse (run_server.py:50), so this is a flag or subcommand rather than a new entry point. It prints the code in plain text and as an ASCII/ANSI QR block. Both, always: the text is what you type, the QR is what you point a camera at, and which one is useful depends on which device is enrolling.

The desktop app — same machine as the console. No camera, and no need for one: read the code off the terminal and type it. The QR is not for this surface.

The tablet and the phone — point the camera at the terminal and scan.

What the QR carries, and why that is the real win

Origin plus code, not the code alone.

ADR-0011 records a deliberate concession: carry an origin, not a host, so a later move to Caddy and TLS does not force every device to re-enrol. That concession pays here. A scanned device learns where the go-between is as well as which code to present, so it never has to be told an address.

That matters more than it sounds. Onboarding's 周波数 step currently asks for ws://192.168.1.24:12393/client-ws — the single most error-prone thing on the board, typed on a touch keyboard, on the device least able to check it. A scan removes that step entirely for the two surfaces where typing is worst. Typing a short code is tolerable; typing a websocket URL on a tablet is not.

Not in v1

The Hermes-relayed path. Asking her for a code in a chat is the thing ollvt-hermes-bridge#25 exists to unblock, and it is v2. The console covers every surface: the desktop reads it directly, the mobiles scan it.

What this hands the build

ollvt-hermes-bridge#26 — the CLI subcommand, the QR rendering, and the payload shape are its work, on top of mint / salted hash / minutes-long TTL / consume / issue / check.
denpa#40 — two entry paths, not one: enter a code (desktop, where the address is already known or typed once) and scan (mobile, where the QR supplies origin and code together, so the address field is skipped). The address step becomes conditional rather than mandatory.

A dependency worth stating: qrcode is not currently installed in the go-between, and uv run is broken in that repo (a yanked fish-audio-sdk), so it has to be added to requirements.txt and installed into .venv directly.

## Resolution **The code is minted at the server's own CLI, which prints it as text and as a QR code in the terminal.** Operator's call, 2026-07-30: it is a server application, so the console is a first-class place to run a command, and terminals can render QR codes perfectly well. ### The flow, per surface **Minting** — a subcommand on the go-between. `run_server.py` already uses `argparse` (`run_server.py:50`), so this is a flag or subcommand rather than a new entry point. It prints the code in plain text **and** as an ASCII/ANSI QR block. Both, always: the text is what you type, the QR is what you point a camera at, and which one is useful depends on which device is enrolling. **The desktop app** — same machine as the console. No camera, and no need for one: read the code off the terminal and type it. The QR is not for this surface. **The tablet and the phone** — point the camera at the terminal and scan. ### What the QR carries, and why that is the real win **Origin plus code, not the code alone.** ADR-0011 records a deliberate concession: *carry an origin, not a host*, so a later move to Caddy and TLS does not force every device to re-enrol. That concession pays here. A scanned device learns **where the go-between is** as well as **which code to present**, so it never has to be told an address. That matters more than it sounds. Onboarding's 周波数 step currently asks for `ws://192.168.1.24:12393/client-ws` — the single most error-prone thing on the board, typed on a touch keyboard, on the device least able to check it. A scan removes that step entirely for the two surfaces where typing is worst. Typing a short code is tolerable; typing a websocket URL on a tablet is not. ### Not in v1 **The Hermes-relayed path.** Asking her for a code in a chat is the thing `ollvt-hermes-bridge#25` exists to unblock, and it is `v2`. The console covers every surface: the desktop reads it directly, the mobiles scan it. ### What this hands the build - **`ollvt-hermes-bridge#26`** — the CLI subcommand, the QR rendering, and the payload shape are its work, on top of mint / salted hash / minutes-long TTL / consume / issue / check. - **`denpa#40`** — two entry paths, not one: **enter a code** (desktop, where the address is already known or typed once) and **scan** (mobile, where the QR supplies origin and code together, so the address field is skipped). The address step becomes conditional rather than mandatory. A dependency worth stating: `qrcode` is not currently installed in the go-between, and **`uv run` is broken in that repo** (a yanked `fish-audio-sdk`), so it has to be added to `requirements.txt` and installed into `.venv` directly.

aiko closed this issue

2026-07-30 17:08:27 +00:00

aiko referenced this issue

2026-07-30 17:08:28 +00:00

Enrollment in the Receiver: enter a code or scan a QR, and stop reading trust out of her prose #40

aiko referenced this issue

2026-07-30 17:08:28 +00:00

Wayfinder map — the conversation works (v1) #41

aiko referenced this issue

2026-07-30 20:17:27 +00:00

Enrollment in the Receiver: enter a code or scan a QR, and stop reading trust out of her prose #40

aiko referenced this issue