FIDO2: five host-side bugs from the transit v2 hardware brief

[0c-coder]

Five host-side bugs found running the transit v2 hardware test brief against v3.0.5-test on 2026-09-16/17. All five are in the WebAuthn/FIDO2 layer; none needs a firmware change.

1. Transit framing state was per-instance, not per-device

onlykey.extra.js is a factory. onlykey-api.js requires it twice, onlykey-pgp.js and onlykey-3rd-party.js once each — four independent copies of transit. transit_select() flipped v2 on one of them while the derive/composite path went on framing v1 at a v2 device: transit_seal() fell through to aesgcm_encrypt(), transit_open() to aesgcm_decrypt(), and transit_framed() understated every expected length by 20 bytes — all while the connect banner reported Transit framing: v2 from a different copy.

TRANSIT_V2_MIN and transit are hoisted to module scope so all four share one object.

2. The composite chunk size was not a multiple of 57

ok_extension.cpp re-chunks each arriving keyhandle into 57-byte device packets:

recv_buffer[6] = 0xFF;
if (opt2 && handle_len<=57) recv_buffer[6] = handle_len;

0xFF means "a full 57, more coming", and the true length is written only when opt2 marks the final host chunk. There is no way to say "n bytes, more coming" — so on every chunk but the last, a tail shorter than 57 still counts as 57 and the device advances past bytes the host never sent.

At 224 (57×3 + 53) each non-final chunk overshot by 4. A derived X-Wing [label32 | ct1120] = 1152 sends five non-final chunks, so the device reached 1140 where the host had sent 1120, and the 32-byte tail took it to 1172 against a 1152 total — 20 over, past the 16-byte padding tolerance, refused with Error derived decaps payload size. RSA-4096 (512 B, two non-final chunks) overshot by 8 the same way.

Sizing: a credential id is 255 bytes with a 10-byte header → 245 per assertion; the transit frame costs 20 (4-byte counter + 16-byte tag) → 225 of plaintext; the largest multiple of 57 at or below 225 is 171. Changed in both onlykey-3rd-party.js (COMPOSITE_MAX_PACKET) and onlykey-pgp.js (maxPacketSize).

Chunk counts go up — ML-KEM-768 5→7, derived X-Wing 6→7, RSA-4096 3→3 — and each chunk is a full WebAuthn ceremony, so priming is slower. That is the price of the framing.

3. A failed chunk was stepped over instead of ending the send

Neither prime_composite() nor u2fSignBuffer() looked at what came back from the ceremony. A cancelled prompt, a tab that refused to run WebAuthn, or a key pulled mid-send simply did not reach the device — and the loop went on and eventually set opt2, so the device reassembled a payload short by however many chunks were lost and refused it for its size. That blames the payload for a transport failure; it cost a long detour into chunk arithmetic that was correct.

Both paths now stop and name the chunk that did not land. packetnum is deliberately not reset on abort: the device keeps an opt3 high-water mark across operations and drops anything not strictly greater, so restarting at 1 would make the next operation's first chunk vanish silently.

This one proved itself during testing — a browser-extension failure on an unrelated run surfaced as packet 1 did not reach the device instead of a silent size error.

4. The derived-decap challenge code was missing

Field 30 (web_agent_derive_mode) = 0 makes the key blink and wait for three specific buttons, and the host is the only thing that can say which. The earlier precomputation hashed [keytype | label32 | ct_X32], which stopped being what the firmware hashes, and had been removed rather than corrected — leaving "press these in order:" above an empty box, and on a press:

Error incorrect challenge was entered

emit_derive_challenge() restores it over the preimage the firmware actually uses, from okcrypto.cpp and okcore_prime_user_confirmation():

inner    = SHA256(derive_label(32) || large_buffer(1120))
outer    = SHA256(inner)
button_n = (outer[{0,15,31}] % 6) + 1

Two hashes, not one — easy to get wrong reading only the call site. Emitted before the chunks go out and cleared when the request ends, so stale digits never carry into the next prompt. Verified against python-onlykey's challenge_code() and the live age CLI before shipping.

It is unconditional (six buttons, the same default python-onlykey ships) because onlykeyApi.OKversion cannot gate it — see below.

5. aesgcm_encrypt/aesgcm_decrypt threw on an empty payload

forge returns '' for a zero-length input and ''.match(/.{2}/g) is null, so poll_for_response()'s sealed empty OKPING produced Cannot read properties of null (reading 'map') on every poll of a v1 session — a message that points nowhere near framing, and the first symptom of bug 1. Both paths now use bytesFromHex(), which has the guard.

---

Separate finding, not fixed here

onlykeyApi.OKversion is derived as response[32+19] == 99 ? 'Color' : 'Go'. UNLOCKED reports UNLOCKEDv3.0.5-test — exactly 19 characters — so index 19 of that field is the NUL terminator, not a hardware byte, and every Color reports itself as a Go. Gating the challenge box on that string left it empty on the very hardware it is for. Wants fixing at the protocol level rather than worked around in the library; flagged for a separate change.

Build

docs/ is the onlyagent.app deployment, so the second commit rebuilds it. It picks up these five fixes and also the monochrome OnlyKey theme and shell copy from 2489083 / d0fd23d, whose source changes had never been rebuilt.

Test status

Transit v2 brief: tests 1, 3, 4, 5, 6 and 8 pass; test 2 passes on lengths and status; test 7 decrypt passes, sign was not run (the browser extension dropped the message channel twice, not a device failure).