Larapass Laravel Package

Technical Evaluation

Larapass (DarkGhostHunter/Larapass) is a Laravel-native WebAuthn/Passkey server implementation. v3.0.2 is a maintenance patch on the v3.x line, not a feature release, so the architecture assessment is dominated by one migration hazard rather than new capability.

Architecture fit. The value proposition is that WebAuthn ceremony handling (challenge generation, credential creation/assertion, attestation parsing, signature verification) is encapsulated as a first-party Laravel service provider with publishable config, migrations, and an Eloquent-backed credential repository. That maps cleanly onto a standard Laravel app: you get a WebAuthn facade, opinionated routes for registration/login ceremonies, and a HasWebAuthn-style trait contract for the authenticatable model. For a TPM this is genuinely attractive — the alternative is hand-rolling CBOR parsing and COSE key verification, which is high-risk specialist work. Fit is strong if the app is on Laravel 10/11-era conventions and uses Eloquent; fit degrades if authentication is delegated to an external IdP, or if the frontend stack cannot adopt navigator.credentials calls (which Larapass assumes, typically via a small JS helper).

Integration feasibility. Two workstreams: (1) backend — publish config/migrations, run migrations, add the trait, expose ceremony endpoints; (2) frontend — WebAuthn browser API invocation, base64url encoding/decoding, and UX for platform vs. roaming authenticators. Backend is measured in days; frontend plus fallback-flow design is the longer pole. The v3.0.2 release materially changes step (1): the web_authn_credentials.attestation_type column must be string, not json. Anyone who ran the v3.0.0/v3.0.1 migrations has the wrong column type and requires a new migration to alter it. This is packaged as a bugfix but is functionally a schema migration, and it landed in a patch release.

Technical risk.

• Schema-type change under a patch version is the headline risk. A semver-conscious consumer pinning ^3.0.1 and auto-updating gets a package that expects a column type their database does not have. Failure mode is at write time on credential creation — likely a JSON-encoding error or a driver-level type error, i.e. registration breaks, not login. That is a poor failure mode: silent until a user tries to enroll, and it affects new users preferentially.
• Config mismatch fixes in the same release imply prior config keys or published-config defaults were inconsistent with what the code read. Teams that published config early may be running stale keys that now behave differently. Worth diffing the published config against the vendor default.
• Small-maintainer dependency. Single primary maintainer, community PRs. Acceptable for the maturity level, but this is now a security-adjacent dependency in your auth path; vendor risk and CVE responsiveness need to be tracked deliberately, not assumed.
• Attestation handling is a compliance question, not just a code question. Attestation conveys device provenance; some product/legal contexts require it, most consumer flows deliberately use none. The renamed attestation_type column is a reminder that this is persisted state you should understand the semantics of before shipping.
• Recovery path. Passkeys are one factor. Without a documented fallback (password, email magic link, recovery codes), a lost device becomes an account lockout. This is a product risk the package will not solve for you.

Key questions. What Laravel and PHP versions are supported in the 3.x line, and is the app inside that window? Are we on v3.0.0/v3.0.1 today — and if so, has the attestation_type column been altered, and is there a forward/backfill plan for rows already stored as JSON? Does the app's auth layer allow adding a second credential model without conflicting with an existing 2FA/MFA package? Which attestation conveyance policy do we actually want, and does it match the column we are persisting? What is our passkey-loss recovery flow, and is it out of scope for this release? Do we need to support conditional UI / autofill (passkey autofill) — if so, does the version in scope expose it, or is that a frontend-only concern? Is the maintainer responsive to security reports, and what is our policy for pinning versus tracking?

Integration Approach

Stack fit. Best-case fit is a Laravel monolith on Eloquent with server-rendered or first-party SPA auth. Larapass slots in as an additional guard/ceremony layer alongside existing session auth — it does not replace password auth unless you deliberately remove it. In a decoupled or multi-service setup (e.g. Laravel as API behind a Next.js frontend), the ceremony endpoints are consumable but you own CORS, cookie/domain strategy, and the base64url contract end-to-end; effort roughly doubles. In a non-Laravel or heavily customized auth stack, the package's opinions become friction and the build-vs-buy calculus shifts toward a dedicated WebAuthn library or a managed passkey provider.

Migration path. Sequence matters because of the schema change:

1. Diff the published config/larapass.php against the v3.0.2 vendor default and reconcile — do this first, since PR #40 targets exactly this class of drift.
2. On databases created under v3.0.0/v3.0.1, add an explicit migration altering web_authn_credentials.attestation_type from json to string, and decide how to handle existing column contents (existing rows likely hold a JSON-encoded scalar; verify whether they need unwrapping or can be truncated, given credentials are re-enrollable).
3. Verify the alter on the real driver, not just SQLite — MySQL/TiDB and PostgreSQL handle json→varchar differently, and SQLite requires the table-rebuild path that Laravel's schema builder abstracts but does not always get right for constrained columns.
4. Deploy backend with the trait and routes disabled/feature-flagged, then enable registration before login.
5. Ship the frontend ceremony calls behind the same flag; run enrollment on staging with real hardware (platform authenticator, roaming key, synced passkey) before enabling in production.

Compatibility. Confirm PHP and Laravel version constraints against the app's composer lock, and check for collision with any existing 2FA package that also hooks the user model or the login pipeline. Because this is a patch release carrying an implicit schema expectation, treat pinning as a decision: pin to 3.0.2 exactly and upgrade deliberately rather than floating ^3.0. Note also that teams still on v2.x face a genuine major-version migration (namespace, contracts, and table shape), which is a separate project from this patch.

Sequencing relative to other work. Do not bundle this with an unrelated auth refactor. Keep the column migration isolated and reversible — ideally shipped one release before the package upgrade so the schema is correct when the code lands, avoiding a window where new code writes to an old column type. Feature-flag at the ceremony level so you can disable passkey enrollment without rolling back a migration.

Operational Impact

Maintenance. Low steady-state maintenance — this is a small, focused package. The recurring cost is version tracking on a security-relevant dependency and re-diffing published config after each release (as v3.0.2 demonstrates, config drift is a real failure mode). Budget a recurring line item for reviewing release notes before auto-merge of dependency updates.

Support. Primary support burden is end-user, not developer: users who lose a device, use a browser or platform without passkey support, or hit confusing OS-level prompts. Tier-1 support needs a script that distinguishes "authenticator problem" from "our bug." Have a documented, tested fallback sign-in path and staff trained on it before launch. Second burden is internal: whoever owns auth must understand the ceremony well enough to debug it, which means at least one engineer goes deep rather than everyone skimming.

Scaling. Ceremony verification is CPU-bound cryptography (ECDSA/EdDSA signature checks, CBOR parsing) per login attempt, not per request — trivial load for most applications, but note that verification happens in the PHP process, so very high login throughput on small PHP-FPM pools is worth a load test rather than an assumption. Storage is negligible: one row per credential, a few hundred bytes to a couple KB. No background jobs, no cache dependency, no external service call in the login path — a genuine operational virtue, since it means no third-party outage can break sign-in.

Failure modes. (1) Schema/type mismatch from the patch — breaks registration, surfaces only when a user enrolls; the highest-probability incident for this upgrade. (2) Config drift after publish — ceremony endpoints return errors or use wrong relying-party ID, which breaks all passkey operations and is often misdiagnosed as a client bug. (3) RP ID / origin misconfiguration across environments — credentials enrolled on staging silently fail on production, and subdomain changes invalidate existing credentials entirely. (4) Trait or model integration gaps — credentials persist but are not retrievable for the user, or the user model's identifier changes and orphans credentials. (5) No fallback path — a package or browser regression turns into a total lockout rather than a degraded experience. (6) Lost-device lockout without recovery codes. Mitigations: correct the column type before deploying code, alert on registration-ceremony error rate as a distinct metric from login errors, freeze RP ID/origin as a treated-as-immutable config, and rehearse the fallback path.

Ramp-up. Backend integration is learnable in a day by a competent Laravel developer; the WebAuthn domain (attestation conveyance, resident/discoverable credentials, user verification requirements, cross-device authentication) takes considerably longer and should not be picked up on the fly if you are making policy decisions about attestation. Frontend work requires someone comfortable with the Credential Management API and base64url handling. Realistic ramp: one engineer, roughly one to two weeks to a flagged, staging-tested integration for a standard Laravel app, plus product time for the recovery flow and support enablement — the latter two are routinely underestimated and are where passkey rollouts actually stall.