Firebase — Firestore, Rules, Auth, Functions, Storage

The Firebase product surface that sits on top of GCP, on the modular Web SDK (v12) and the Admin SDK. The whole skill exists to stop two failure modes: dragging relational/SQL habits into a NoSQL document store, and leaving the database open to the internet.

Two facts drive everything below:

• It is a NoSQL document store, shaped for the read path. No joins, no server-side OR across different fields without a composite index, no SELECT * across collections. Denormalize and fan-out so a screen is one cheap query — reads are what you pay for and what users wait on.
• Rules ARE the access control. Firestore is reachable directly from untrusted clients. There is no app server in the trust path by default — firestore.rules (CEL) is the only thing between a browser and your data. App Check attests the request even came from your app before Rules evaluate.

Not this skill:

Instead of Firebase	Go to
Relational schema, SQL, EXPLAIN, indexing a SQL engine	../postgresdb/SKILL.md
Managed Postgres BaaS (SQL + Postgres RLS + PostgREST) — the most-confused sibling: same "backend-as-a-service" shape, completely different data model and rules language	supabase
AWS document/key-value store with its own capacity model	dynamodb
Self-hosted Mongo document modeling	mongodb
Generic GCP project/IAM/billing not specific to a Firebase product	gcp-essentials
React/Next.js component or rendering work that merely calls Firebase	react / ../nextjs/SKILL.md

Data modeling

Firestore charges and waits on reads. Model so the common screen is one query against one collection.

Collection vs subcollection vs root + denormalized field — decide by access pattern:

Shape	Use when	Why
Subcollection (rooms/{id}/messages)	Child list is only ever read inside its parent, can grow unbounded	Subcollections don't bloat the parent doc; deleting a parent does NOT delete them (handle that)
Separate root collection + foreign id	Child must be queried across all parents (collection-group query)	A collectionGroup('messages') query needs the docs in same-named subcollections OR a root collection
Denormalized field on the parent	A few values are shown alongside the parent and rarely change	Avoids a second read; you accept writing the copy on every change

Hard limits — design around them, don't discover them in prod:

• A document maxes out at 1 MiB (1,048,576 bytes). Don't accumulate an unbounded array (chat messages, audit log) inside one doc — it will hit the wall and every read pays for the whole blob. Use a subcollection.
• A single document tolerates only ~1 sustained write/sec. Monotonic IDs and indexed sequential timestamps create a hotspot on one index range. Use scattered auto-IDs (doc(collection(db,'x'))), and for high-frequency counters use a sharded counter (N shard docs, sum on read).

Query reality: no joins; range/inequality filters on a field plus an orderBy on another field require a composite index; in / array-contains-any are capped (~30 values). If a query needs an index, declare it in firestore.indexes.json — see the emulator gotcha below.

// Bad — unbounded array inside one doc; hits 1 MiB, every read pays for all of it
await setDoc(doc(db, "rooms", roomId), { messages: [...allMessages, newMsg] });

// Good — one doc per message in a subcollection, scattered auto-ID, no hotspot
await addDoc(collection(db, "rooms", roomId, "messages"), {
  text, authorId, createdAt: serverTimestamp(),
});

Denormalization recipes, counter sharding, cursor pagination, getCountFromServer, collection-group queries, and composite-index design live in references/data-modeling.md.

Security Rules — the load-bearing section

Rules are NOT filters. A query is rejected outright unless the rules can guarantee every matched document is readable — Firestore will not silently drop the docs you can't see. So a list rule and the query that runs against it must agree: if the rule allows reading only your own docs, the query must itself be constrained (where("ownerId","==",uid)), or the whole query fails.

// Bad — the entire database is readable AND writable by anyone on the internet
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} { allow read, write: if true; }
  }
}

// Good — default-deny, ownership-scoped, with create-time validation
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /posts/{postId} {
      allow get:    if resource.data.ownerId == request.auth.uid;
      allow list:   if request.auth != null;            // query MUST add where(ownerId == uid)
      allow create: if request.auth.uid == request.resource.data.ownerId;
      allow update, delete: if resource.data.ownerId == request.auth.uid;
    }
    // everything else: no rule = denied
  }
}

Rules to internalize:

• Default-deny. No matching allow = denied. Never add a /{document=**} catch-all with if true. That single line is the "open to the internet" headline risk.
• request.auth is the authenticated identity (null when signed out); request.auth.token carries custom claims for RBAC (e.g. request.auth.token.admin == true).
• resource.data is the existing doc; request.resource.data is the incoming write. Validate the incoming write on create/update (types, immutable ownerId, no privilege escalation).
• get() / exists() read another doc for cross-document checks (e.g. role lookup) — each costs a billed read and counts against rule-evaluation limits, so keep them shallow.
• get vs list are distinct: a single-doc read vs a query. read = both; split them so a query can't leak documents a single get would also have blocked.

Set custom claims with the Admin SDK, never from the client. Add App Check in production so Rules only run for requests that provably came from your real app.

Full CEL patterns — RBAC via claims, ownership, validation functions, time-based throttling, and the complete @firebase/rules-unit-testing recipe — are in references/security-rules.md.

Auth

• Client sign-in with getAuth() + a provider; the SDK manages the refresh of the ID token.
• Server-side, verify the ID token with getAuth(adminApp).verifyIdToken(idToken) before trusting any caller. A raw UID from the client is not proof of anything.
• Custom claims for RBAC: getAuth(adminApp).setCustomUserClaims(uid, { admin: true }). Claims land in request.auth.token in Rules and in the decoded token on the server. They refresh on the client's next token refresh, not instantly — force a refresh if you need it immediately.
• Session cookies (createSessionCookie) suit SSR / server-rendered apps where you want an httpOnly cookie instead of shipping the ID token to every request — pairs with ../nextjs/SKILL.md.

Cloud Functions (2nd gen)

2nd gen is the default and the only generation that runs Node.js 22. Use firebase-functions v7 modular triggers and firebase-admin.

import { onDocumentWritten } from "firebase-functions/v2/firestore";
import { onCall, HttpsError } from "firebase-functions/v2/https";
import { defineSecret } from "firebase-functions/params";

const STRIPE_KEY = defineSecret("STRIPE_KEY"); // never hard-code secrets

export const onPostWrite = onDocumentWritten(
  { document: "posts/{postId}", region: "europe-west1" },
  async (event) => {
    // Background events deliver AT-LEAST-ONCE — make this idempotent.
    const eventId = event.id; // dedupe on this (e.g. a processed/{eventId} marker doc)
  }
);

export const setAdminClaim = onCall(async (request) => {
  if (request.auth?.token.admin !== true) throw new HttpsError("permission-denied", "admins only");
  // ... verify, then setCustomUserClaims via admin SDK
});

• Callable (onCall) gives you request.auth already verified; raw onRequest HTTPS does not — you must verify the ID token yourself.
• Idempotency is mandatory for background triggers (onDocumentWritten etc.): events can fire more than once, so guard side effects with the event id.
• Pin region, set secrets with defineSecret (not env literals), and tune concurrency for cost.
• Functions require the Blaze plan; outbound networking from a function also requires Blaze.

Trigger catalogue, callable-vs-HTTPS auth, idempotency keys, cold-start/cost, Auth blocking functions, and region pinning are in references/cloud-functions.md.

Cloud Storage

Storage paths are gated by their own Rules; clients can hit them directly.

// Bad — any signed-in user can overwrite any other user's avatar
match /avatars/{fileName} { allow write: if request.auth != null; }

// Good — path-scoped to the owner, with a size/type guard
match /avatars/{uid}/{fileName} {
  allow read:  if true;                          // public avatars
  allow write: if request.auth.uid == uid
               && request.resource.size < 5 * 1024 * 1024
               && request.resource.contentType.matches('image/.*');
}

For server-issued time-limited access (private downloads), generate a signed URL from the Admin SDK rather than loosening the Rules.

SDK & project mechanics

Use the modular SDK so the bundler tree-shakes unused Firebase code. The old namespaced firebase.firestore() API is gone in v9+.

// Bad — pulls the entire SDK; defeats tree-shaking (and the compat/namespaced API is legacy)
import firebase from "firebase";
firebase.firestore().collection("posts").get();

// Good — named imports, only what you use ships (Web SDK v12)
import { initializeApp } from "firebase/app";
import { getFirestore, collection, getDocs } from "firebase/firestore";
const db = getFirestore(initializeApp(config));
const snap = await getDocs(collection(db, "posts"));

• firebase.json configures emulators, rules/index file paths, and hosting; firestore.indexes.json declares composite indexes.
• Run the Local Emulator Suite (firebase emulators:start) for local dev and tests.
• Emulator gotcha: the Firestore emulator does NOT enforce composite indexes — it runs any valid query. So "works in the emulator, fails in prod with requires an index" is expected. Verify index coverage separately by keeping firestore.indexes.json in sync and deploying it.
• The Firebase API key in client config is not a secret (it identifies the project, not authorizes access — Rules + App Check do that). Service-account JSON keys ARE secrets; keep them server-side.

Anti-patterns

Anti-pattern	Why it's wrong	Do instead
allow read, write: if true; catch-all	Whole DB is open to the internet	Default-deny; scope each match to request.auth + ownership
Treating rules as query filters	Query is rejected, not filtered — it fails entirely	Constrain the query to match what list allows
Unbounded array in one document	Hits the 1 MiB limit; every read pays for the whole blob	Subcollection, one doc per item
Monotonic IDs / sequential indexed timestamps	Index hotspot → ~1 write/sec/doc wall	Scattered auto-IDs; sharded counters for high write rate
Trusting client writes for sensitive fields	Client can set role: "admin" on itself	Validate request.resource in Rules; set claims via Admin SDK only
No App Check in production	Rules run for any caller, including scripts/scrapers	Enable App Check (reCAPTCHA / Play Integrity / App Attest)
Service-account key in client / repo	Full admin access leaks	Keep service-account JSON server-side; client API key is fine
Namespaced/compat SDK (firebase.firestore())	Legacy, not tree-shakeable, gone in modular	Modular named imports from firebase/firestore
No emulator / rules tests	Open or broken rules ship silently	@firebase/rules-unit-testing via firebase emulators:exec
Background trigger with non-idempotent side effects	At-least-once delivery double-charges/double-writes	Dedupe on event.id

Verify

scripts/verify.sh is read-only and runs from your project root. It locates firestore.rules and fails if a root match /{document=**} carries an allow read, write: if true; catch-all or the rules file is empty; validates firestore.indexes.json parses as JSON; and, when the Firebase CLI is present, points at the firebase emulators:exec rules-test path. It exits 0 and skips cleanly when no Firebase artifacts are in the working directory — not every repo has them.