Laravel Firebase App Check Laravel Package

Product Decisions This Supports

• Build vs. buy for API abuse protection. Verifying Firebase App Check tokens properly (fetching and caching Google's public keys, validating audience against project numbers, honoring token expiry, handling revocation and outages) is a multi-sprint build with ongoing key-rotation maintenance. This package collapses that into a middleware install — a clear "buy/adopt" signal for any team whose clients are Firebase apps.
• Staged rollout of enforcement (the headline decision). Default behavior is soft enforcement for reads and hard enforcement for everything else, with firebase-app-check:soft available per route. This is the feature that makes the adoption decision reversible: you can ship attestation in observe-only mode, watch reportUsing() telemetry for false positives, then tighten route-by-route. A package without a soft mode forces a flag-day cutover — a much harder sell.
• Roadmap sequencing for anti-abuse work. Because enforcement is per-route and per-project, "harden the write endpoints and expensive reads first" becomes a plan you can schedule rather than a big-bang milestone. It also defers the harder investments (rate limiting, WAF/bot management, quota redesign) until you have evidence of what's actually getting through.
• Multi-brand / multi-tenant feasibility. Projects are keyed by name with aliases and resolved via resolveProjectUsing(). If the roadmap includes additional apps, white-label clients, or regional Firebase projects, that's a config change rather than a fork — a meaningful de-risk for a platform strategy.
• Auth scope decision: verify vs. build. IdTokenVerifier + Identity cover the "my Laravel API needs to trust a Firebase-signed-in user" case, with InvalidIdToken / IdTokenVerificationFailed giving you distinguishable 401-vs-503 handling. This can remove custom JWT-verification code from the roadmap entirely, or let you scope it down to session/refresh concerns only.
• Test strategy and delivery velocity. AppCheck::fake() and IdTokenVerifier::fake() with recorded verifications and assertions mean CI doesn't need real Firebase credentials or network egress — it removes the most common reason teams quietly skip testing protected endpoints.
• Operational posture decisions. skipWhen() for webhooks, health checks and server-to-server calls, plus rejectUsing() / reportUsing() hooks for custom logging and metrics, are the seams you need to answer "what do we do when a legitimate client gets rejected?" before it happens.

When to Consider This Package

Adopt when most of these hold:

• You have first-party iOS, Android, and/or web clients built on Firebase, and they call a Laravel API you own.
• You already use (or plan to use) Firebase Auth, so ID-token verification replaces bespoke code rather than adding a second identity system.
• You have a credible abuse or cost problem — scraped endpoints, inflated bills from automated traffic, leaked API keys — and need a signal before investing in heavier bot mitigation.
• You want enforcement to be incremental and observable, and you're prepared to run soft mode in production for a release or two.
• You operate more than one Firebase project and don't want per-project code paths.
• You're comfortable pinning a pre-1.0 dependency and reviewing upgrades.

Look elsewhere — or build/spike first — when:

• Your clients aren't Firebase apps. Server-to-server integrations, partner APIs, and CLIs can't produce App Check tokens; attestation there is a dead end.
• You need a hard security guarantee. App Check is a signal, not a wall — jailbroken/rooted devices and replayed tokens from compromised clients exist. If the requirement is "provably block," you want WAF/Cloud Armor, rate limiting, and server-side authorization, with App Check as one input.
• You want attestation without Firebase (Play Integrity, DeviceCheck/App Attest directly, or a non-Google IdP). This package is Firebase-shaped by design.
• You need a stable, supported API surface with a deprecation policy. At 0.1.0 the public API — facade methods, middleware parameters, exception types — is still finding its shape. Any team with a long support tail should assume churn.
• You need edge/CDN-level blocking. Middleware runs in PHP after the request has already cost you a connection and a boot; if the goal is absorbing volumetric traffic, solve it upstream.
• Fail-open vs. fail-closed on Google outage must be explicit and audited. The notes say outages are never cached, which is correct, but they don't state the per-request verdict when the key endpoint is unreachable. Confirm that behavior against your availability requirements before you put it in front of revenue traffic.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost addition that lets us turn on client attestation for our Firebase-backed apps without a flag-day migration. Because it ships with a soft/observe-only mode, we can measure false-positive impact on real users before enforcing, and roll out route-by-route. It replaces work we'd otherwise have to build and maintain ourselves (Google key rotation, token validation, caching) and gives us a defensible answer to "how do we know requests are coming from our apps?" It's not a silver bullet against determined attackers — it raises the cost of casual abuse and buys us the data to justify the next investment. Main caveat: this is a 0.1.0 release, so we pin the version, isolate it behind our own middleware/config, and expect to review upgrades.

To engineering: Thin middleware, sensible defaults (soft on reads, hard elsewhere, overridable per route), per-project verdict caching bounded by token expiry so we're not calling Google on every request, and outages deliberately not cached so a transient failure doesn't pin a bad verdict. Multi-project via named projects and aliases with resolveProjectUsing() means no branching for future apps; credentials accept a path, JSON string, or array so it fits our secret-management choice. skipWhen() handles webhooks and health checks; rejectUsing() and reportUsing() are the hooks for our logging and metrics. AppCheck::fake() and IdTokenVerifier::fake() with assertions mean protected endpoints stay testable in CI with zero Firebase egress. Two things to nail down in the spike: the failure mode when Google's key endpoint is unreachable (fail-open vs. fail-closed per route), and how we surface rejected-client telemetry before we move anything off soft mode.