Webauthn Framework Laravel Package

Technical Evaluation

What we're actually evaluating. farsh4d/webauthn-framework is not an original implementation. It is a self-declared copy of web-auth/webauthn-framework 4.9.2 with "some changes for personal use," published by a single maintainer with 0 stars, 0 dependents, and a trust score of ~2.5/100. The upstream project is the de facto FIDO2/WebAuthn implementation for PHP, powering production passkey deployments across Symfony and PHP-FIG ecosystems. Every architectural virtue we would cite here — PSR-7/PSR-15 middleware, pluggable credential repositories, attestation and assertion validators, the JWT/CO SE handling — is inherited from upstream and is a reason to use upstream.

Architecture fit. The underlying design is a good fit for us: a framework-agnostic core (web-auth/webauthn-lib) with thin framework adapters (a Symfony bundle here) and Doctrine-backed credential source repositories. It is request/response oriented, so it bridges cleanly into Laravel via PSR-7. The Relying Party entity, user entity interface, and credential source repository are the three seams we would implement. That said, we inherit the Symfony bundle we do not need, and its service definitions, config tree, and Doctrine mappings will sit unused in our dependency graph.

Integration feasibility. Technically feasible: composer require farsh4d/webauthn-framework, wire the library manually, implement PublicKeyCredentialSourceRepository and PublicKeyCredentialUserEntityRepository against Eloquent, and expose /webauthn/register/* and /webauthn/authenticate/* routes. Realistic effort for a competent Laravel engineer with no prior WebAuthn exposure: 3–4 weeks to a hardened production flow (registration options, attestation verification, assertion verification, challenge lifecycle, credential management UI), versus ~3 days just to get a happy-path demo working. The fork's "personal changes" are undocumented — we cannot diff them against upstream without doing the work ourselves, and any behavioral difference is unverified and untested by anyone but its author.

Technical and supply-chain risk — this is the core issue. We are being asked to adopt a security-critical, authentication-path dependency from a fork whose only stated purpose is one person's private modifications. Concretely:

• No security posture. Upstream publishes advisories and patches against web-auth/*. A fork does not receive them. If CVE-XXXX lands against 4.9.2's assertion validation, we get no notification and no patch.
• Fork drift. The fork pins to 4.9.2 with unknown deltas. Upgrading means either re-applying an unknown patch set to a newer upstream, or discarding it — the classic fork tax.
• Package identity confusion. Namespace collisions, Composer replace semantics, and transitive dependencies on web-auth/* sub-packages mean we could end up with a mixed tree of forked and upstream code paths — the worst possible state for an auth boundary.
• Zero adoption signal. 0 stars / 0 dependents / single maintainer is not a proxy for quality, but for a WebAuthn verifier it means no third party has ever run this code in anger.

Key questions before we spend another hour on it.

1. What are the actual deltas from upstream 4.9.2? Can the author publish a diff or a branch of upstream with named commits? If the changes are generic (e.g., a Laravel adapter, a configurable CO SE algorithm list), they belong upstream as a PR or in our own thin wrapper.
2. Can we satisfy the requirement with web-auth/webauthn-lib directly plus ~300 lines of Laravel glue? Almost certainly yes.
3. Is there a hard business constraint (air-gapped review, license/legal objection to the upstream maintainer, a specific bug fix) that forces a fork? If not, the fork has no reason to exist in our tree.
4. Who owns security response for this dependency if we adopt it?

Recommendation: Do not adopt the fork. Default to upstream web-auth/webauthn-lib (or the Symfony bundle if we ever build on Symfony) and write our own Laravel integration layer. Reconsider the fork only if question 1 surfaces a concrete, auditable patch we cannot upstream or reimplement, in which case we vendor it as an internal, reviewed fork we control — not as a third-party dependency.

Integration Approach

Stack fit. Our Laravel stack is a reasonable host for the upstream library, but not for the Symfony bundle. The plan should be: depend on web-auth/webauthn-lib, add nyholm/psr7 + symfony/psr-http-message-bridge to translate Laravel requests, bind the library's CeremonyStepManagerFactory (or equivalent validator chain in 4.9.x) in a service provider, and implement two Eloquent repositories. If we insist on the fork, it is the same work plus an unexplained patch set — strictly worse.

Migration path. There is no installed base, so "migration" is really "adoption sequencing." The clean path:

1. composer require web-auth/webauthn-lib (pin exact version, commit the lockfile).
2. Spike: verify a single assertion against a known-good FIDO2 authenticator in a scratch environment. Kill criterion for the whole initiative if this fails.
3. If the fork is ever required, add it via a vcs repository entry and an explicit replace declaration so we cannot accidentally pull both codebases; forbid it in CI otherwise.

Compatibility. Confirm PHP version constraints (upstream 4.9.x targets PHP 8.1+) against our runtime, and audit transitive deps: web-token/jwt-framework, symfony/uid, psr/http-message, spomky-labs/cbor-php. These are heavier than they look and will interact with our existing JWT usage if we have one. The Symfony-specific packages (symfony/config, symfony/dependency-injection, symfony/http-kernel) are dead weight in Laravel and should be excluded where possible.

Sequencing.

• Week 0: Upstream-vs-fork decision record; confirm no regulatory constraint on the upstream maintainer.
• Week 1: Environment, PSR-7 bridge, repository interfaces, schema for webauthn_credentials (credential ID, public key, sign count, AAGUID, transports, user handle, created/last-used timestamps, backup-eligible flags).
• Week 2: Registration ceremony end-to-end, including attestation policy (recommend none for consumer UX, packed only if we have a device fleet).
• Week 3: Authentication ceremony, challenge store, replay and sign-count enforcement.
• Week 4: Credential management UI, recovery/second-factor fallback, security review, load test.

Non-negotiables. Challenge storage must be server-side, single-use, and short-TTL; RP ID and origin must be per-environment config, not code; and the fallback path (password + TOTP) must be defined before launch, because WebAuthn enrollment attrition is real.

Operational Impact

Maintenance. With upstream: routine, well-understood — track releases, apply security patches, retest ceremonies quarterly. With the fork: effectively we own it. Someone must diff against upstream on every release, re-apply unknown changes, and take personal responsibility for a verifier on our login path. Budget ~1–2 engineer-days per quarter for upstream tracking; the fork makes that ~4–6 days per upgrade attempt plus unbounded incident risk. The fork's November 2025 release date is not reassurance — it is likely a re-tag, and recency without a changelog or diff is noise.

Support. Upstream has documentation, an issue tracker, and a real user base. The fork has a single author and no stated support channel. Escalation for a broken ceremony at 2 a.m. is "read the FIDO2 spec and the upstream source." That is acceptable for an internal tool; it is not acceptable for an authentication boundary.

Scaling. The ceremonies themselves are stateless and cheap — a few milliseconds of crypto per assertion, no bottleneck until very high volume. The operational scaling questions are elsewhere: challenge/session storage (Redis with short TTL, not the database), a write per registration and a sign-count update per authentication (plan for write amplification on the credentials table, or accept a lower-frequency sign-count write and rely on cloning detection policy), and database indexes on credential_id and user_handle. None of this is fork-specific, but all of it is on us to build because neither package ships a Laravel-native persistence layer.

Failure modes to design for. Lost or expired challenge (user left the tab open) → clean, retryable error, not a 500. Origin/RP ID mismatch across subdomains and environments → the single most common integration defect; make it a config invariant with a startup assertion. Unsupported attestation format or CO SE algorithm from an exotic authenticator → degrade to none attestation rather than blocking enrollment. Counter regression / cloned authenticator → policy decision, not an exception. Passkey synced across devices with no counter increment → must not be treated as a clone. Dependency disappearance (author deletes the repo) → this is a live risk with 0 dependents and no mirror; if we ever adopt the fork, mirror it internally on day one.

Ramp-up. WebAuthn is genuinely subtle — attestation trust chains, resident keys, user verification flags, conditional UI. Plan 2–3 weeks of learning curve for the implementing engineer regardless of package choice, and require a second reviewer who understands the spec before the flow touches production. The package does not reduce that cost; it only reduces the amount of raw CBOR/JWT plumbing we write. Choosing the fork adds a governance and provenance burden on top of an already non-trivial domain, for no identified benefit.