[kentcdodds]

Summary

Passkey sign-in no longer asks for a TOTP code when two-factor is enabled. A verified WebAuthn assertion already requires possession of the authenticator plus user verification (biometric/PIN), so it is treated as MFA-complete. Password and social logins still challenge through /verify when 2FA is on.

Changes

• POST /webauthn/authentication always issues kody_session after a verified passkey assertion
• E2E updated to assert passkey login lands on /account even with 2FA enabled
• Account passkeys copy and auth docs updated to match

Test plan

• Unit tests for passkeys / two-factor handlers
• E2E passkey sign-in skips TOTP when two-factor is enabled
• E2E passkey lifecycle and existing two-factor password login still pass

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ 8e0cafb8 · Head: 8c67b9bd

Classification: extends — passkey authentication on app-sessions now issues a session without the TOTP /verify gate; password and social login behavior is unchanged.

Primitives touched

Primitive	Group	Impact
app-sessions	auth	extends — verified WebAuthn login skips TOTP when 2FA is enabled
app-ui	surfaces	extends — account passkeys copy documents the MFA-complete passkey UX

System map

Passkey login verifies the WebAuthn assertion, then issues kody_session without routing through the pending kody_verify / /verify TOTP step.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	appUi["app-ui<br/>Browser app"]:::extended
	appSessions["app-sessions<br/>Browser sessions"]:::extended
	appUi -->|"Sign in with a passkey"| appSessions
	appSessions -->|"verified assertion → kody_session"| appSessions
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Change flow

sequenceDiagram
	participant Browser
	participant WebAuthn as POST /webauthn/authentication
	participant Session as kody_session
	Browser->>WebAuthn: passkey assertion
	WebAuthn->>WebAuthn: verifyAuthenticationResponse<br/>requireUserVerification
	WebAuthn->>Session: Set-Cookie kody_session
	Note over Browser,Session: No kody_verify / /verify TOTP step

Loading

Before / after

Path	Before	After
Passkey login + 2FA enabled	requiresTwoFactor: true → /verify	ok: true + kody_session
Password / social login + 2FA	/verify TOTP challenge	unchanged

  

Summary by CodeRabbit

• New Features

  • Passkey sign-in now completes multi-factor authentication through browser verification.
  • Users signing in with a passkey proceed directly to their account, without entering a separate TOTP code.

• Documentation

  • Updated authentication and social-login guidance to clarify when TOTP verification is required.
  • Updated passkey setup instructions to explain the streamlined sign-in experience.

• Tests

  • Updated passkey sign-in coverage to verify that TOTP is skipped when two-factor authentication is enabled.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3b558837-d26f-4e14-ad24-29ba57e4cc07

📥 Commits

Reviewing files that changed from the base of the PR and between 8e0cafb and 8c67b9b.

📒 Files selected for processing (7)

• docs/contributing/architecture/authentication.md
• docs/contributing/architecture/primitives.yaml
• docs/contributing/social-login.md
• e2e/passkeys.spec.ts
• packages/worker/client/routes/account-passkeys.tsx
• packages/worker/src/app/handlers/passkeys.node.test.ts
• packages/worker/src/app/handlers/webauthn.ts

💤 Files with no reviewable changes (1)

• packages/worker/src/app/handlers/passkeys.node.test.ts

---

📝 Walkthrough

Walkthrough

Passkey authentication now treats a verified WebAuthn assertion as MFA-complete, creates the normal auth session directly, and skips TOTP verification. Tests, UI text, and authentication documentation were updated to reflect the new flow.

Changes

Passkey MFA flow

Layer / File(s)	Summary
Direct auth session after passkey verification packages/worker/src/app/handlers/webauthn.ts, packages/worker/src/app/handlers/passkeys.node.test.ts	WebAuthn authentication no longer creates a verify session or requires TOTP; it creates the normal auth cookie directly, with test secrets updated accordingly.
Passkey flow validation and user messaging e2e/passkeys.spec.ts, packages/worker/client/routes/account-passkeys.tsx	The end-to-end test expects direct navigation to /account, and the registration text states that passkey sign-in skips the two-factor code.
Authentication flow documentation docs/contributing/architecture/authentication.md, docs/contributing/architecture/primitives.yaml, docs/contributing/social-login.md	Documentation distinguishes password-login TOTP gating from MFA-complete passkey sign-in.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• kentcdodds/kody#661: Introduced the passkey/WebAuthn sign-in behavior being updated here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the main change: verified passkey sign-ins now bypass TOTP.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/passkey-skips-2fa-7e28

---

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.}

[github-actions]

🔎 Preview deployed: https://kody-pr-774.kody-a99.workers.dev

Worker: kody-pr-774
D1: kody-pr-774-db
KV: kody-pr-774-oauth-kv

Mocks:

• cloudflare: https://kody-pr-774-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-774-mock-cloudflare)