feat(webauthn): add mfa option to passkey enrollment (update)

[dorsha]

What

Adds an optional login_options to the WebAuthn passkey-enrollment flow (sync + async) so it can return a merged-amr session in a single ceremony:

client.webauthn.update_start(login_id, refresh_token, origin, LoginOptions(mfa=True))
# ... browser ceremony ...
jwt = client.webauthn.update_finish(transaction_id, response)  # merged-amr session (e.g. ["pwd","webauthn","mfa"]) or None

Why

Enrolling a passkey for an already-authenticated user registered the credential but minted no session — getting a session reflecting the new passkey required a second WebAuthn ceremony (sign_in_start(mfa=True) + finish). Reported by PerciHealth (descope/etc#16573); pairs with the backend change.

Changes

• update_start (sync webauthn.py + async webauthn_async.py) gains an optional trailing login_options: Optional[LoginOptions] = None (non-breaking), composed into the request body only when provided (shared _webauthn_base._compose_update_start_body).
• update_finish gains an optional audience kwarg and now returns Optional[dict]: the JWT response (parsed from the nested jwt) when the enrollment was mfa, else None (default flow). Sync uses generate_jwt_response; async uses prepare_jwt_response.

Both changes are runtime backward-compatible (new optional params; None return for the default flow).

Tests

test_compose_update_start_body (mfa body), test_update_start_with_mfa, test_update_finish_with_mfa, plus the existing default-flow tests — all run in both sync and async modes. tests/test_webauthn.py passes (25 cases).

🤖 Generated with Claude Code

[shuni-bot-dev]

🐕 Review complete — View session on Shuni Portal 🐾

[shuni-bot-dev]

🐕 Suggested Reviewers

The reviewers were selected based on recent contributions to the key files involved in WebAuthn implementation and testing, ensuring they have relevant and current context to review the changes effectively.

Reviewer	Reason
guyp-descope	Modified 'descope/authmethod/webauthn.py' and 'tests/test_webauthn.py'; knowledgeable in WebAuthn flow and testing.
itaihanski	Contributed to 'descope/authmethod/webauthn.py' and its tests; experienced with WebAuthn implementation and test coverage.
omercnet	Worked on 'descope/authmethod/webauthn.py' and its tests; suitable for reviewing updates to WebAuthn logic.
tebeka	Contributed to 'descope/authmethod/webauthn.py' and testing modules; familiar with WebAuthn integration.

_{Suggested by Shuni based on git history and PR context. Names are not @-mentioned to avoid notifying anyone — request a review from whoever fits best.}

[shuni-bot-dev]

🐕 Shuni's Review

Adds an optional login_options to the WebAuthn passkey-enrollment flow so update_finish can return a merged-amr session in one ceremony (sync + async).

No issues found — good bones! Serialization (login_options.__dict__), the sync/async generate_jwt_response/prepare_jwt_response split, and the optional-param backward compat all match the sibling sign-in/sign-up flows. Tests cover the mfa and default paths in both modes. Woof!

[github-actions]

Coverage report

The coverage rate went from 98.04% to 98.05% ⬆️

100% of new lines are covered.

Diff Coverage details (click to unfold)

descope/authmethod/webauthn.py

100% of new lines are covered (100% of the complete file).

descope/authmethod/_webauthn_base.py

100% of new lines are covered (100% of the complete file).

descope/authmethod/webauthn_async.py

100% of new lines are covered (100% of the complete file).