Firebase

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:

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:

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
  { 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

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.