Firebase Auth Middleware Lite

A minimal and framework-agnostic Firebase ID token verification middleware for Node.js. Works with Express, but does not depend on it.

---

✨ Features

• 🔐 Verifies Firebase ID tokens
• 💥 Uses res.writeHead + res.end (no Express dependency)
• 🧠 Attaches claims and token to res.locals for downstream usage
• 🧩 Plug-and-play with Express, Bun, Node HTTP, etc.

---

📦 Installation

1npm install firebase-auth-middleware-lite

Make sure you also install firebase-admin and @google-cloud/firestore (required by Firebase types):

1npm install firebase-admin @google-cloud/firestore

---

🧪 Usage

1. Initialize Firebase

1import { initFirebase } from "firebase-auth-middleware-lite";
2import serviceAccount from "./firebase-key.json";
3
4initFirebase(serviceAccount);

2. Use the middleware

1import express from "express";
2import { authMiddleware } from "firebase-auth-middleware-lite";
3
4const app = express();
5
6app.use(authMiddleware());
7
8app.get("/protected", (req, res) => {
9  res.json({ uid: res.locals.claims.uid });
10});

---

🔍 Advanced Usage

You can pass a callback to the middleware if you want to run custom logic when a user is verified:

1const withDatabaseUser = async ({ claims, ctx, token, res }) => {
2  console.log("Authenticated user id:", claims.uid);
3
4  // get user information like permissions or roles for authorization
5  const user = await getUserFromDB(claims.uid);
6
7  ctx.user = user // attach user to locals
8
9
10  // return something to stop the flow
11  if (!user) return res.status(403).json({ error: "Forbidden" });
12
13  // if nothing is returned, middleware will add claims and token
14  // to res.locals and continue;
15};
16
17app.use(authMiddleware(withDatabaseUser));

---

🔄 Token Expiration Handling

If a token is expired, the middleware will return an error. You will have to refresh the token using the frontend firebase SDK:

• Set the HTTP header x-firebase-token-refresh: true
• Return a 401 Unauthorized response

---

📚 Types

1type AuthContext = { // not exported
2  claims: DecodedIdToken; // from firebase-admin
3  token: string;
4};
5
6type AuthCBParams = {
7  claims: DecodedIdToken; // from firebase-admin
8  ctx: Record<string, any>;
9  token: string;
10  res: Response;
11};

---

🛡 License

MIT — use it, hack it, improve it.