Laravel Firebase App Check Laravel Package

Technical Evaluation

Architecture fit

• Ships as Laravel-native HTTP middleware (firebase-app-check), so it slots into the existing kernel/route-group model rather than introducing a new request pipeline. Low architectural intrusion.
• The soft/hard enforcement split is the standout design decision: reads can run in observe-only mode while writes are enforced. This maps directly onto a staged rollout plan and lets us ship the package before clients are ready.
• Multi-project support (name + aliases, per-project credentials) fits a multi-tenant or multi-brand model where each mobile app has its own Firebase project. This is the feature that decides whether the package is a fit for us versus a single-app convenience.
• IdTokenVerifier/Identity means one dependency covers both client attestation and user identity, potentially replacing a heavier Firebase SDK dependency for auth-only use cases.
• Extension seams (skipWhen, resolveProjectUsing, rejectUsing, reportUsing) allow policy and telemetry without forking — a strong signal for long-term maintainability.

Integration feasibility

• Credentials accept a key file path, JSON string, or array, which accommodates both secret-manager mounts and env-var injection. No bespoke infrastructure required.
• AppCheck::fake() and IdTokenVerifier::fake() with recorded verifications and assertions means the test story is solved on day one — no live Firebase calls in CI.
• Blocking dependency is client-side: iOS/Android/web must be minting App Check tokens before hard enforcement is viable. That is an app-store release-train constraint, not a PHP constraint, and it dominates the timeline.
• Local development and CI need debug-token handling or fakes; this is the most common friction point in App Check rollouts and should be documented as a runbook step, not discovered mid-sprint.

Technical risk

• Version 0.1.0: pre-1.0 API surface, no stability guarantee. Expect breaking changes in the facade signatures and middleware parameters. Pin exact versions.
• No published support matrix in the release notes (Laravel 10/11/12, PHP 8.x, Octane compatibility). Unverified — must confirm before committing.
• Verdict caching is correct in principle (token-expiry-bounded, outages never cached) but assumes a shared cache store. On multi-node deployments with file or array caching, enforcement becomes per-node and inconsistent. This is the highest-severity misconfiguration risk.
• Fail-closed behavior on hard-enforced routes during a Firebase/Google outage is the right security posture but a real availability risk. rejectUsing controls the response shape, not the fail-open/closed decision.
• Unknown or unconfigured projects are rejected in all modes: excellent for security, high blast radius for a config typo. Config validation belongs in CI.
• Unclear: retry/timeout behavior on verification calls, clock-skew tolerance, and whether the facade holds request-scoped state safely under Octane.

Key questions

1. What Laravel and PHP versions are supported, and is Octane explicitly supported?
2. Which cache stores are supported, and is a shared store enforced or merely documented?
3. What are the HTTP timeout and retry semantics for verification calls, and does a timeout fail open or closed in each mode?
4. How is the cache key derived (per token? per project + token?) and what is the growth/eviction profile?
5. How does resolveProjectUsing behave when a request is ambiguous or the alias is missing?
6. Is there a security disclosure process, and what is the license?
7. What is the changelog/upgrade discipline pre-1.0, and is there a stated path to 1.0?
8. Can skipWhen be combined safely with auth middleware ordering, and is the ordering documented?

Integration Approach

Stack fit

• Registers as a named middleware alias alongside Sanctum/Passport. App Check sits in front as a client-authenticity gate; user authentication stays where it is. No conflict with existing auth or rate limiting.
• reportUsing hooks into the existing logging/Sentry pipeline, so verdicts become observable without new tooling.
• rejectUsing lets us match the existing API error contract, which matters because mobile clients need to distinguish "refresh your token and retry" from "you are not allowed."

Migration path

• Greenfield endpoints: register in soft mode, collect verdicts, then promote to hard enforcement per route group.
• Brownfield: gate the entire middleware behind skipWhen so older app versions without App Check are not broken. Enforcement must lag the app-store rollout by at least one full adoption cycle — typically 2–3 release trains for a consumer app.
• Adopting IdTokenVerifier is a separate, optional migration and should not be bundled with the App Check rollout. Keep the two changes independently revertable.

Compatibility

• Requires Firebase App Check configured per client platform plus debug tokens for dev/CI.
• rejectUsing output shape must be validated against existing mobile error handling before hard mode — a 403 where the client expects 401 generates support load.
• Cache backend must be confirmed in every environment (local, CI, staging, prod) before enforcement; file in staging will produce misleading rollout data.

Sequencing

1. Staging spike: single project, soft mode, verify verdict logging.
2. Config validation in CI (unknown project names, missing credentials, cache store check).
3. Soft-mode canary on low-risk read endpoints; baseline the pass/fail rate.
4. Hard enforcement on abuse-prone write endpoints first — highest value, smallest audience.
5. Extend to additional projects/aliases once single-project behavior is boring.
6. Evaluate IdTokenVerifier separately as an auth consolidation project.
7. Pin the version; schedule a re-review at 1.0 or on any minor bump.

Operational Impact

Maintenance

• Pre-1.0 churn is the primary ongoing cost. Pin exact versions and budget a half-day to a day of review per minor release. Treat upgrades as routine maintenance, not drive-by dependency bumps.
• Key-file rotation is a runbook item. Prefer secret-manager mounted paths over inline JSON in env vars; inline JSON in environment configuration raises the blast radius of a config leak.

Support

• Small, likely single-maintainer package with no stated SLA. Name an internal owner and accept that a fork/vendor is a realistic fallback. Do not put this on a critical path without that contingency.

Scaling

• Every uncached token requires a network round trip. Steady-state cost is governed by cache hit rate, and TTL is bounded by token expiry (typically around an hour), so hit rates should be high but are not guaranteed.
• Cold-cache events — deploys, cache flushes, Redis failover — produce verification storms. Run soft mode during the first cache-cold window after each enforcement change, and consider a warm-up or gradual traffic shift.
• Per-project cache namespacing means cost scales with traffic, not with project count. Fine.

Failure modes

• Firebase/Google outage: hard-enforced routes fail closed. This is the correct security tradeoff but should be a documented, rehearsed scenario with a stated incident procedure.
• Config typo (project name, alias, credentials): rejected in all modes. Full outage from a one-line mistake. Mitigate with CI validation and a startup check, not with hope.
• Clock skew / stale client tokens: false rejections appearing as a support-ticket spike on enforcement day. Watch the first 24–48 hours of each hard-mode flip closely.
• Debug tokens accidentally left enabled in production: silent bypass, no error. Add a deployment check.
• Multi-node with a non-shared cache: inconsistent enforcement that looks like intermittent, unreproducible bugs. Highest-cost failure to diagnose.
• Cache eviction under memory pressure during an outage: request volume against the verification API rises exactly when it is least healthy.

Ramp-up

• A Laravel developer is productive in under a day; the fakes make tests trivial and the middleware config is conventional.
• The real learning curve is Firebase-side: project registration, per-platform App Check providers, debug tokens, and client SDK integration. Budget that work with the mobile team, not the backend team.
• Total assessment: worth a staging spike now. The soft/hard enforcement model and the fake layer make this a low-commitment evaluation, while 0.1.0 version status and the fail-closed/multi-node caveats make any production commitment conditional on the open questions above being answered.