[AmanKrSahu]

Overview

This Pull Request implements full Passkeys / WebAuthn (FIDO2) authentication support in AuthKit (Task 3.3 in docs/audit/2026-07-20/task.md — FR-4). It provides phishing-resistant, passwordless authentication using platform authenticators (FaceID, TouchID, Windows Hello) and roaming hardware security keys (YubiKey).

The implementation integrates seamlessly with AuthKit's existing authentication architecture, session management, multi-factor authentication (MFA) layer, Redis challenge storage, immutable audit logging, outbound webhook triggers, and the OpenID Connect (OIDC) interaction pipeline.

---

Key Changes by Functional Area

1. FIDO2 / WebAuthn Core Architecture (@simplewebauthn/server)

• Dedicated Service Layer: Built WebAuthnService encapsulating registration and authentication ceremonies (generateRegistrationOptions, verifyRegistration, generateAuthenticationOptions, verifyAuthentication, listAuthenticators, deleteAuthenticator).
• Cryptographic & Utility Helpers: Extracted binary-to-base64url converters, transport sanitizers, and BigInt counter serialization helpers into src/core/common/utils/webauthn.util.ts to maintain strict separation of concerns.
• Challenge Lifecycle Management: WebAuthn ceremony challenges are cached in Redis with a 5-minute TTL (webauthn:challenge:{userId/email/interactionId}) and invalidated immediately upon verification to prevent replay attacks.

2. Data Persistence & Authenticator Security

• Authenticator Model: Added a persistent Prisma schema model supporting 1:N relations with User, unique credentialId indexing, cascade deletions, and byte array (Bytes) storage for public keys and authenticator IDs (aaguid).
• Signature Counter & Clone Detection: Tracks device invocation counters with atomic database updates during authentication to immediately detect and reject cloned authenticators.
• Sensitive Data Masking: Ensured API responses strip internal cryptographic public key representations and sanitize BigInt counters before sending JSON payloads.

3. Direct Login & OIDC Interaction Pipeline

• Direct Authentication Routes: Implemented /api/v1/webauthn/* endpoints for registering authenticators, authenticating users with discoverable credentials (resident keys), listing active passkeys, and revoking authenticators.
• OIDC Interaction Integration: Added /interaction/:uid/webauthn/* endpoints allowing users to complete passwordless authentication and satisfy MFA steps seamlessly within the OIDC authorization code flow.

4. Event Bus, Auditing & Webhook Ingestion

• Audit Logging: Recorded immutable audit entries (WEBAUTHN_REGISTER, WEBAUTHN_AUTHENTICATE, WEBAUTHN_DELETE) capturing device transports, client IP, and user-agent metadata.
• Outbound Webhooks: Integrated WebAuthn actions with eventBus to publish webauthn.registered, webauthn.authenticated, and webauthn.deleted events for HMAC-SHA256 signed external webhook delivery.
• Worker Architecture Alignment: Relocated background queue processing daemon to src/core/workers/webhook-queue.worker.ts in alignment with the system service architecture.

---

Documentation & API Synchronization

• README.md: Documented WebAuthn feature capabilities and environment variables (WEBAUTHN_RP_NAME, WEBAUTHN_RP_ID, WEBAUTHN_ORIGIN).
• docs/api_endpoints.md: Added endpoint specifications, request payloads, and response structures for all 7 WebAuthn endpoints.
• docs/security_architecture.md: Documented FIDO2 challenge flows, clone detection, user verification policies, and audit logging integration.
• docs/testing_architecture.md: Added test architecture specifications for WebAuthn unit, integration, and E2E journeys.
• docs/api-specs/openapi.json: Generated and formatted OpenAPI 3.0 specs with full WebAuthn route definitions.
• docs/api-specs/AuthKit.postman_collection.json: Added a complete Postman collection folder for testing WebAuthn ceremonies and device management.
• docs/audit/2026-07-20/task.md: Marked Task 3.3 (FR-4) as Done.

---

Verification & Test Summary

• Type Check: Zero TypeScript compilation errors (tsc --noEmit).
• Linting & Formatting: 100% compliant with ESLint and Prettier (pnpm lint, pnpm format:check).
• Test Suite Coverage: 23 test files passed, 113 tests passed (100% green):
  • Unit tests: tests/unit/webauthn.service.test.ts (14 passing tests)
  • Integration tests: tests/integration/webauthn-endpoints.test.ts (5 passing tests)
  • End-to-End tests: tests/e2e/webauthn-journeys.test.ts (Registration $\rightarrow$ Challenge $\rightarrow$ Verification $\rightarrow$ Revocation lifecycle)
  • Regression tests: Zero regressions across Auth, Admin, OIDC, MFA, and Webhook test suites.

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}