linux: complete WebAuthn bridge handling

[Jesssullivan]

Summary

Linux browser panels currently install a WebAuthn bridge, but the native handler
is still stubbed.

This is an implementation gap, not just a validation gap.

Current State

• browser panel setup installs the bridge
• the native message handler still has TODOs for request parsing, CTAP2 dispatch,
  and JS reply handling
• current parity docs should treat Linux WebAuthn as not yet supported end-to-end

References

• cmux-linux/src/browser.zig
• cmux-linux/src/webauthn_bridge.zig
• docs/linux-parity-matrix.md
• docs/linux-validation-checklist.md
• docs/linear-qa-shard-punchlist.md (PAR-001)

Scope

• parse WebKit bridge messages
• route requests through the Linux CTAP2 path
• reply to the page with success and error responses
• run one real hardware-backed ceremony on a Tier A distro

Exit Criteria

• Linux WebAuthn request handling is implemented end-to-end
• one real hardware-backed ceremony succeeds on Ubuntu 24.04 or Fedora 42
• parity docs can move WebAuthn above unsupported

[Jesssullivan]

Investigation — implementation gap inventory

Stub scope

cmux-linux/src/webauthn_bridge.zig lines 70–75 are 4 TODOs in onScriptMessage:

1. Extract JSON from JSCValue
2. Parse type / options / origin
3. Dispatch to CTAP2 on a background thread
4. Reply to JS with the credential response

Existing pieces (reusable)

• vendor/ctap2/src/ctap2.zig — full CTAP2 codec: encodeMakeCredential, encodeGetAssertion, parseMakeCredentialResponse, parseGetAssertionResponse, status mapping. Plus cbor.zig, pin.zig, ctaphid.zig.
• vendor/ctap2/src/hid_linux.zig — Linux HID transport (already linked into cmux-linux).
• cmux-linux/src/webauthn_bridge_js.zig — JS injected at document start. Sends await window.webkit.messageHandlers.cmuxWebAuthn.postMessage({ type, options, origin }) and expects a result (line 152). Identical payload shape to macOS.
• macOS reference: Sources/Panels/WebAuthnCoordinator.swift (1107 LOC) — uses WKScriptMessageHandlerWithReply. Sections to port:
  • registration (181–308) — make-credential ceremony
  • assertion (308–408) — get-assertion ceremony
  • PIN prompt (109–163)
  • origin validation (163–181)
  • CTAP2 C calls (408–614) — these already have a Zig codec equivalent
  • PIN-authenticated CTAP2 (614–759)
  • allow-list pointer helper (1068)
  • base64url Data extension (1089)

Linux-specific pieces missing

1. WebKitGTK reply mechanism: current bridge uses webkit_user_content_manager_register_script_message_handler (one-way). For reply, switch to register_script_message_handler_with_reply and return a JSCValue from the script-message-with-reply-received signal handler. This is a new signal connection and a new C-API binding to add to c_api.zig.
2. JSCValue ⇄ JSON conversion: jsc_value_to_json(value, indent) returns a heap-allocated C string; need wrappers + free.
3. PIN entry UX on GTK: macOS uses an NSAlert-style sheet. GTK4 equivalent is AdwAlertDialog or GtkDialog — need a new modal flow.
4. Background dispatch: macOS uses DispatchQueue. Linux can use std.Thread.spawn + g_idle_add to marshal the reply back to the GTK main loop.

Estimated scope

• ~600–800 LOC new Zig (port macOS coordinator's call structure to Zig + GTK4 idioms)
• ~30 new C-API bindings in c_api.zig (jsc_value_*, webkit message-handler-with-reply, AdwAlertDialog)
• ~1 GTK4 PIN dialog component
• Hardware test on honey + YubiKey (manual; no automation possible without u2f-tools mock)

Sequencing recommendation (spike → land)

Spike 1 (1 day) — wire the reply round-trip end-to-end without CTAP2:

• Switch to register_script_message_handler_with_reply
• Stub: parse type, return a hardcoded NotAllowedError DOMException
• Verify: dummy.js webauthn.io demo page sees the rejection promise resolve

Spike 2 (1 day) — get-assertion happy path on a single rp_id:

• Wire vendor/ctap2.encodeGetAssertion + hid_linux.zig for transport
• No PIN, no allow-list filtering, no extensions
• Verify: passwordless ceremony on webauthn.io succeeds

Land (2–3 days) — feature-complete:

• make-credential
• PIN flow (AdwAlertDialog)
• allow-list filtering, transports, extensions parity with macOS coordinator
• error mapping (DOMException names: NotAllowedError, SecurityError, InvalidStateError)

Validate (manual) — honey runner with attached YubiKey, Tier A distros (Ubuntu 24.04, Fedora 42 once #209 unblocks).

Blockers / dependencies

• None on the codec side — vendor/ctap2 is ready.
• WebKitGTK 6 script-message-with-reply API needs the GTK 4.10+ / WebKitGTK 6.0+ targets we already require.
• Fedora 42 distro coverage (ci(distro): establish Fedora 42 fresh-install VM proof #209) is independent but useful for end-to-end validation.

Recommended next action

Open a tracking PR with Spike 1 only (~50 LOC), behind a webauthn-spike build flag, to validate the JSCValue reply machinery is wired correctly before committing to the larger port. That PR can land green without YubiKey hardware (just exercises the JS↔native round trip).