Master via roaming authenticator (YubiKey-as-K11) — actor role, not machine class

[hanwencheng]

Updated framing — master vs agent is an actor role, not a machine class

Per the revised architecture in docs/spec/architecture.md §4 (HDKD actor tree) + §4a (mental model), master and agent are roles on the actor axis, not separate machine classes. This issue's original framing ("YubiKey-on-Linux is a different machine class") is incomplete.

What changed

The architecture now distinguishes four orthogonal axes (§4a):

Axis	What
Identity	Who is the human?
Actor	Master, or which agent? (HDKD tree node)
Machine	Which physical box is signing right now?
Capability	What is this actor allowed to do?

A Linux box with a YubiKey could play either role:

• Linux + YubiKey as master — the box runs the master role; YubiKey provides the K11 hardware-attested user-presence credential at binding ceremonies. This issue.
• Linux + YubiKey as agent — the box runs the agent role; YubiKey is irrelevant because agent bootstrap is link-code-only (no WebAuthn ceremony). Already covered by agent-infra/sandbox flow per §5a.2.

Revised scope of this issue

Specify and ship the YubiKey-as-K11 alternative for the master role:

1. Detection / opt-in flow — at agentkeys init --master, detect when a roaming authenticator is plugged in and offer "use as K11" instead of defaulting to platform authenticator. Likely a --roaming-authenticator flag for the explicit case.

2. WebAuthn ceremony adjustment — authenticatorAttachment: "cross-platform" (vs. the platform-authenticator master flow's "platform"). Other params (userVerification: "required", attestation: "direct") stay the same.

3. Per-request signing — same K10 file device-key model. The roaming authenticator only attests at master binding/rotation time, not per-request.

4. Re-bind ceremony — WebAuthn get() against the YubiKey credential ID. Operator inserts the YubiKey, taps it, ceremony succeeds.

5. Recovery shape when YubiKey is lost — explicitly different from platform-authenticator loss. With Touch ID, the OS keychain may sync the credential via iCloud / Google PM. With a YubiKey, the credential is bound to that physical device — losing it requires the deliberately-high-friction recovery flow (re-do identity ceremony, accept first-enroller-wins for the new credential).

6. Documentation — add §5a.1.YK ("Master via roaming authenticator") subsection in architecture.md, plus a section in the operator runbook.

What this issue does NOT cover

• Linux as agent role — already supported (link-code bootstrap, no WebAuthn needed). Out of scope.
• Cross-platform passkey sync (iCloud / Google / 1Password) — that's automatic for platform authenticators where the OS supports it; nothing for AgentKeys to design.
• Hybrid transports (phone-as-authenticator via QR + BLE) — the WebAuthn API exposes this transparently if the browser supports it; should "just work" once the master WebAuthn ceremony ships.
• TPM-on-Linux as a platform authenticator — distinct from YubiKey case; would require Linux-side WebAuthn API integration that historically has been weaker than other platforms.

Dependencies

• Blocks on Step 1c: device-key authentication for /dev/* signer endpoints (follow-up to #74) #76 (issue Replace dev_key_service with TEE worker for omni-anchored EVM keypair derivation #74 step 1c) landing first — the master WebAuthn binding ceremony machinery has to exist before this can extend it.
• Blocks on the v1c → v1.0 transition: per-agent HDKD omni model + uniform WebAuthn binding (per architecture.md §4–§5a).

Why deferred (not built in v0.2)

The v0.2 ship shape is "platform-authenticator masters + link-code agents." Adding YubiKey-master support requires a second WebAuthn ceremony shape (cross-platform attachment), a different recovery story (no OS-sync fallback), and extra UX surface (detect-and-offer at init). Each is small in isolation but they compound. Better to ship the common case clean, then add this once we have actual operator demand on Linux + YubiKey workflows.

References

• docs/spec/architecture.md §4 (HDKD actor tree), §4a (4-axis mental model), §5a.1 (master init), §5a.2 (agent bootstrap)
• .omc/wiki/agent-role-and-usage-hdkd-per-agent-omni.md — operator-focused agent-role reference
• docs/spec/plans/issue-74-step-1c-device-key-auth.md — v1c interim shapes + v0.2 target
• #76 — device-key auth (must land first)
• WebAuthn authenticatorAttachment spec