docs: state device approval as an API rendezvous in the blueprint

[FSM1]

Records ADR 0009 (FSM1/cipher-box-next#65) in the blueprint. Documentation only, no code surface.

Based on #1255, not on main. Both PRs edit the same login sections of web-client.md and desktop.md, so this is stacked to avoid a conflict. Merge #1255 first; the base then collapses to main.

Draft until FSM1/cipher-box-next#65 is accepted — the decision corpus is normative and this repo carries the as-built statement of it.

The framing being corrected

Three files described MFA and device approval as chrome-side Core Kit UX. Device approval cannot be UI-side: the Core Kit has no native cross-device share transfer (Web3Auth confirmed as much to the v1 build), so approval is a server-mediated rendezvous — and v1 built an API module with its own table and migration to provide one. The mislabel is why v2 has no endpoint, no UI, and until today no issue.

What changed

api.md — the rendezvous joins the other API surfaces: request, poll, respond, cancel and a pending list, under a scoped non-refreshable pre-reconstruction token, with the API as a bulletin board that relays ciphertext and never holds plaintext key material. Both halves carry a device-key signature, and a row's life ends at collection or expiry. device_approvals joins the table list.

web-client.md — the Core Kit bullet keeps MFA enrollment and loses device approval. A new bullet states the client's part: mint the ephemeral key, display the comparison value both devices must match, sign both halves with the device identity key, and seal a fresh factor rather than the approver's own. The /settings row now distinguishes enrollment and recovery from authorized devices and approval.

desktop.md — records that the recovery phrase always works on this host, with no second device and no rendezvous, and that desktop's participation in approval is a scope decision to be made rather than left open. v1 shipped a requester UI that could never work beside a settings string saying MFA was web-only; the affordance and the truth have to agree.

testing.md — the Core Kit staging-dispatch exemption covers interactive login and MFA enrollment, and explicitly does not extend to device approval, which runs over our own API and needs a harness driving two sessions. v1 skipped every cross-device case for want of a second device, which is exactly how a desktop path sending a 33-byte key where 65 were required reached a verified status.

Checks

markdownlint-cli2 and prettier --check clean on all four files.

Note

Document device approval as a server-mediated API rendezvous in the blueprint

Updates four blueprint documents to describe device approval (per ADR 0009) as a server-mediated rendezvous rather than a client-side concern.

• api.md: adds device approval (request/poll/respond/cancel + pending list) under Identity and auth, scoped to a non-refreshable pre-reconstruction token, and adds a device_approvals table entry.
• web-client.md: removes device approval from Core Kit responsibilities; describes it as requiring an ephemeral key, comparison value display, device-key signatures, and a fresh sealed factor; notes recovery phrase as the guaranteed fallback path.
• desktop.md: asserts recovery phrase always works on desktop (ADR 0009 D2) and flags an open scope decision on whether the shell participates in device approval.
• testing.md: states device approval is not exempt from staging-dispatch testing and notes v1's gap in cross-device test coverage.

^{Macroscope summarized b8edcd7. (Automatic summaries will resume when PR exits draft mode or review begins).}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d2a2d34c-01aa-467f-adc4-1a3f32fb4417

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}