chore(deps): migrate firebase-admin to v14 (#223)

[spizeck]

Closes #223

Summary

• firebase-admin ^13.10.0 -> ^14.5.0 (app + functions/).
• Splits src/lib/firebase-admin.ts into firebase-admin-app / -auth / -db / -storage: Firestore- and Storage-only consumers no longer import firebase-admin/auth (the jwks-rsa -> jose graph behind the Fix production /admin crash from firebase-admin v14 ESM dependency conflict #144 Vercel outage). All call sites and vi.mock specifiers updated.
• next.config.ts: adds serverExternalPackages: ["firebase-admin"].
• Scoped override jwks-rsa -> jose@5.10.0 — required, verified on a live Vercel Preview in chore(deps): migrate firebase-admin to v14 (#141) deepdivebrewing-web#142: unoverridden Admin 14.5.0 resolves jose@6.1.3 (ESM-only) and the deployed function 500s with ERR_REQUIRE_ESM despite Node 24.
• functions/index.js: replaces legacy require("firebase-admin") + admin.initializeApp() with firebase-admin/app (v14 removed the namespaced service API; only initializeApp was used here).
• scripts/check-admin-import.mjs wired into npm test — credential-free plain-Node import of app/auth/firestore/storage entrypoints, asserts 14.x.
• tests/firebase-admin-runtime.test.ts (Fix production /admin crash from firebase-admin v14 ESM dependency conflict #144 CJS-only subprocess guard) now also loads firebase-admin/storage.

Verification (local)

• npm ci-equivalent install clean; tree: firebase-admin@14.5.0 -> jwks-rsa@4.1.0 -> jose@5.10.0 (overridden)
• node scripts/check-admin-import.mjs -> firebase-admin@14.5.0: server import chain OK
• npm run type-check, npm run lint clean (5 pre-existing warnings)
• npm test — 869 pass incl. CJS-only runtime guard
• npm run build green
• functions/: npm install -> firebase-admin@14.5.0 + firebase-functions@7.4.0 (peer-compatible)

Vercel Preview validation (required before merge)

• POST /api/auth/session with an invalid idToken executes verifyIdToken and returns the app's own 401 — not a module-graph 500
• /admin page render + receipt sweep/admin path loads Storage graph; runtime logs free of ERR_REQUIRE_ESM/jose
• Functions: deploy/emulator check of onFirestoreChange + triggerRebuild

Generated with Devin

Summary by Sourcery

Migrate Firebase Admin to v14 while hardening server-runtime compatibility across Next.js and Cloud Functions.

Bug Fixes:

• Prevent Firebase Admin's ESM dependency chain from causing serverless runtime failures by isolating service imports and pinning a compatible jose version.

Enhancements:

• Migrate the application and Cloud Functions to Firebase Admin SDK 14.5.0 and use service-specific Admin modules for authentication, Firestore, and Storage.
• Keep Firebase Admin external to the Next.js server bundle and update the Functions initialization for the v14 API.

Tests:

• Add credential-free import smoke checks and extend CommonJS runtime coverage to the Firebase Admin Storage entrypoint.

Chores:

• Update Firebase Admin dependency lockfiles and all affected application, script, and test imports.

[sourcery-ai]

Sorry @spizeck, this account has used its review budget of 1,500,000 diff characters for the last 7 days.

You can request another review in 1 day and 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sfpca	Ready	Preview	Sep 29, 2026 11:50pm UTC

[sourcery-ai]

Reviewer's Guide

Migrates both app and Functions usage to firebase-admin 14.5.0, isolates service imports to avoid pulling Auth’s problematic jwks-rsa/jose graph into unrelated server paths, and adds dependency/runtime safeguards for CJS-compatible Vercel execution. Review the deployment validation items separately, especially invalid-token session handling, Admin/Storage rendering, and Functions execution.

Sequence diagram for the Firebase Admin runtime import safeguard

sequenceDiagram
  participant Test as npm test
  participant Check as check-admin-import.mjs
  participant Node as Plain Node runtime
  participant Admin as firebase-admin 14.x entrypoints
  Test->>Check: node scripts/check-admin-import.mjs
  Check->>Node: import firebase-admin/app
  Check->>Node: import firebase-admin/auth
  Check->>Node: import firebase-admin/firestore
  Check->>Node: import firebase-admin/storage
  Node->>Admin: resolve CJS-compatible dependency chain
  Admin-->>Check: required exports available
  Check-->>Test: server import chain OK

Loading

Sequence diagram for Functions Firebase initialization with Admin SDK v14

sequenceDiagram
  participant Functions as Functions runtime
  participant App as firebase-admin/app
  participant Firebase as Firebase services
  Functions->>App: initializeApp()
  App->>Firebase: initialize default app
  Firebase-->>Functions: initialized app

Loading

File-Level Changes

Change	Details	Files
Migrates the application and Cloud Functions code to Firebase Admin SDK 14’s modular APIs.	Updates Firebase Admin dependencies to 14.5.0 and adapts Functions initialization to import initializeApp from firebase-admin/app. Removes reliance on the legacy namespaced Admin SDK service API. Refreshes dependency lockfiles and keeps firebase-functions peer-compatible.	package.json package-lock.json functions/package.json functions/package-lock.json functions/index.js
Splits Firebase Admin access by service to prevent unnecessary Auth dependency loading.	Extracts shared app initialization from Auth, Firestore, and Storage wrappers. Updates application routes, libraries, scripts, and tests to import the narrowest service-specific module. Adds Storage coverage to the CommonJS runtime guard.	src/lib/firebase-admin-app.ts src/lib/firebase-admin-auth.ts src/lib/firebase-admin-db.ts src/lib/firebase-admin-storage.ts src/app/admin/homepage/actions.ts src/app/admin/registrations/actions.ts src/app/api/auth/session/route.ts src/app/api/cron/sweep-receipts/route.ts src/lib/auth.ts scripts/audit-firestore.ts scripts/db-backup.ts scripts/db-restore.ts scripts/migrate-firestore.ts scripts/reconcile-migration.ts tests/admin-actions.test.ts tests/auth.test.ts tests/firebase-admin-env.test.ts tests/session-route.test.ts tests/firebase-admin-runtime.test.ts
Hardens the server dependency graph against the jose ESM runtime failure.	Externalizes firebase-admin from the Next.js server bundle. Pins jwks-rsa’s jose dependency to 5.10.0 through a package override. Adds a credential-free plain-Node smoke check for all Firebase Admin entrypoints and verifies the installed SDK is 14.x. Runs the import check as part of npm test.	next.config.ts package.json package-lock.json scripts/check-admin-import.mjs

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#223	Migrate the application and functions from firebase-admin 13 to ^14.5.0, including splitting the Admin SDK integration into app, auth, Firestore, and Storage modules and updating all consumers.	✅
#223	Prevent the Vercel ERR_REQUIRE_ESM outage by externalizing firebase-admin in Next.js, pinning the jwks-rsa jose dependency to 5.10.0, and adding plain-Node and CommonJS runtime import checks covering the relevant Admin SDK entrypoints.	✅
#223	Complete the required validation, including Vercel Preview checks for auth token verification, Storage/admin paths, and runtime logs, plus functions deployment or emulator verification.	❌	The PR includes local verification and the new import/runtime tests, but its own verification checklist leaves the required Vercel Preview and functions deployment/emulator checks unchecked. Therefore, the code changes address the validation mechanisms, but the issue's required pre-merge runtime validation is not fully demonstrated.

Possibly linked issues

• Maintenance: migrate Firebase Admin to v14 with Vercel runtime validation #223: The PR implements the issue’s complete Firebase Admin v14 migration and Vercel ERR_REQUIRE_ESM prevention scope.
• Maintenance: migrate Firebase Admin to v14 with Vercel runtime validation #223: PR directly fixes the reported production import conflict with dependency overrides, import isolation, externalization, and regression guards.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[spizeck]

Vercel Preview runtime validation — PASSED

Initial Vercel deploy failed with Resource provisioning failed (platform-side flake — builds never ran; not a code error). Redeployed.

Deployment: dpl_H91C1yvRFTTkMHSAzYP4uwdhx3hU → https://sfpca-icx3q9vwn-chad-nuttalls-projects.vercel.app (branch chore/firebase-admin-v14, READY)

Exercised:

• POST /api/auth/session with a bogus ID token → 401 {"error":"Unauthorized"} — adminAuth().verifyIdToken ran the full firebase-admin/auth → jwks-rsa → jose graph in the Vercel serverless runtime and failed closed as designed. App log line: session request rejected (warn level, expected).
• GET /admin → 307 → GET /login 200 — server middleware/session path healthy.

Runtime logs: zero error/fatal entries for the deployment window; no ERR_REQUIRE_ESM, jose, or jwks-rsa entries.

Firestore/Storage graphs: unchanged semantics, statically covered by tests/firebase-admin-runtime.test.ts (CJS-only subprocess incl. firebase-admin/storage) and the plain-Node check:admin-import smoke; the session route's Firestore path (provisionAdminUser/upsertAuthIdentity) only runs on a valid token and could not be exercised without credentials.

Also re-ran the push-triggered E2E job that flaked on Postgres ECONNREFUSED 127.0.0.1:5544 (the PR-context run of the same suite passed).