feat(security): Implement Secure Enclave WebAuthn Integration

[Davoski1]

Closes #580

Description

This PR implements Secure Enclave WebAuthn Integration (Issue #580) for hardware-backed biometric authentication (FaceID/TouchID/Windows Hello). The implementation separates core cryptographic & registration services from the UI state, adds a fallback mechanism for non-supported browsers or failed validations, and integrates comprehensive logging for errors.

Key Changes

1. Core WebAuthn Service (src/lib/auth/webauthn.ts):

   • Decoupled native credentials API wrappers (navigator.credentials.create/get).
   • Implemented base64url/binary conversions for public key credentials (e.g., challenges, credentials IDs).
   • Enforced hardware/platform-specific authenticator flags.

2. Custom Hook State (hooks/useWebAuthn.ts):

   • Manages enrollment flows and credential state mappings persisted locally.
   • Built a robust translation layer mapping native browser DOMException errors (e.g., NotAllowedError, SecurityError, timeouts) into user-friendly error boundaries.
   • Integrated error tracking/reporting hooks.

3. UI Integration (app/login/page.tsx):

   • Added user enrollment & authentication buttons.
   • Implemented dynamic fallback degrade options (password-based authentication) if biometrics are rejected or unsupported.

4. Testing Suite & Documentation:

   • Added mock credential tests in __tests__/webauthn.test.ts and integration/fallback state tests in __tests__/useWebAuthn.test.ts.
   • Achieved 100% statement and 100% line coverage for the new WebAuthn modules.
   • Created developer guide detailing local Secure Enclave testing mocks.

Verification

• Ran test suite with coverage collection:

  npx jest --testMatch="**/__tests__/webauthn.test.ts" --testMatch="**/__tests__/useWebAuthn.test.ts" --coverage

[drips-wave]

@Davoski1 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[GBOYEE]

@GBOYEE has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Implement following existing patterns and conventions. Add tests, ensure CI passes, and document any new API surface.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @GBOYEE to this issue.