Webauthn Lib Laravel Package

Getting Started

Start by installing the package via Composer: composer require web-auth/webauthn-lib. Review the README.md for initial setup—focus on the registration and authentication flow examples. Begin with a minimal implementation:

• Use PublicKeyCredentialCreationOptionsGenerator to create registration options (sent to frontend)
• Use PublicKeyCredentialParser to decode the response from the browser
• Validate the credential using PublicKeyCredentialSourceValidator and a temporary in-memory repository (InMemoryPublicKeyCredentialSourceRepository)
  This gives you immediate feedback without DB overhead. Next, wire in a real CredentialRepositoryInterface implementation to persist credentials.

Implementation Patterns

Implement WebAuthn in two discrete, idempotent flows:

Registration Flow

1. On user-initiated registration: generate CreateCredentialOptions (include user.id, user.name, challenge)
2. Send options → frontend calls navigator.credentials.create()
3. Receive PublicKeyCredential → parse with PublicKeyCredentialParser
4. Validate: check origin, RP ID, client extensions, attestation format, and signature
5. Persist PublicKeyCredentialSource (store credentialId, publicKey, signCount, aaguid, attestationType) via your repository

Authentication Flow

1. On login: generate GetCredentialOptions (include challenge, allowed credentialIds)
2. Frontend calls navigator.credentials.get()
3. Parse and validate assertion: verify challenge, rpId, user present/verification flags, and signature
4. Enforce monotonic signCount against stored credential
5. Issue your app’s auth session

Integrate via a dedicated WebAuthnService class that encapsulates both flows. Use Laravel’s Auth contract to bridge—e.g., create a WebAuthnGuard or custom UserProvider that authenticates users by credential ID. For storage, extend DefaultPublicKeyCredentialSourceRepository to persist to Eloquent models with columns: credential_id (string), public_key (json), sign_count (int), transports (json), created_at.

Gotchas and Tips

• RP ID must be a registrable suffix of the origin: https://app.example.test → RP ID example.test fails; use app.example.test or run tests with localhost (allowed by spec) for dev. Double-check $_SERVER['HTTP_ORIGIN'] vs your configured RP ID.
• Base64url ≠ standard Base64: All JSON-exchanged fields (e.g., credentialId, attestationStatement) use base64url. Use Base64Url::encode() / decode() helpers from the package—but note internal COSE keys are binary.
• User Verification (UV) defaults to required: If your authenticator (e.g., Touch ID, Windows Hello) doesn’t enforce UV, assertions fail. For low-risk flows (e.g., non-financial), set requireUserVerification: false in GetCredentialOptions.
• signCount monotonicity is critical: The authenticator increments this—your validator must reject assertions where the new signCount ≤ stored value (ignoring wraparound). Track it per credential in DB.
• Testing gotcha: Browser WebAuthn APIs require HTTPS except for localhost. Use php artisan serve (Laravel’s dev server) + ngrok for local HTTPS, or use web-auth’s test fixtures (MockRegistration, MockAuthentication) for unit tests.
• Extension support is limited: The library supports basic extensions (e.g., u2fappId, credProps), but advanced ones (e.g., largeBlob, hue) require manual parsing—check PublicKeyCredential::getClientExtensionResults().