Registry / gcp / firebase-auth-cloudflare-workers

firebase-auth-cloudflare-workers

library2.0.6jsnpmunverified

firebase-auth-cloudflare-workers is a specialized, zero-dependency library designed to facilitate Firebase ID token (JWT) verification directly within Cloudflare Workers environments. Currently stable at version 2.0.6, it provides a robust solution for authenticating users by leveraging Web Standard APIs, ensuring minimal bundle size and optimized performance at the edge. Key differentiators include its complete independence from external npm dependencies, full support for UTF-8 character encoding, and dedicated integration with the Firebase Auth Emulator for local development and testing. The library enables developers to offload authentication logic to the Cloudflare edge, reducing latency and reliance on origin servers for token validation. While a specific release cadence isn't published, updates typically align with evolving Firebase authentication standards or Cloudflare Workers platform features.

gcp auth-security web-framework

npm install firebase-auth-cloudflare-workers

package ↗

INSTALL

IMPORT

SIG · FIREBASE-AUTH-CLOU

firebase-auth-cloudflare-workers

gcpjavascriptv2.0.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Auth

✓ import { Auth } from 'firebase-auth-cloudflare-workers'

✗ const Auth = require('firebase-auth-cloudflare-workers').Auth

The library is designed for ESM in Cloudflare Workers environments. Use named import.

WorkersKVStoreSingle

✓ import { WorkersKVStoreSingle } from 'firebase-auth-cloudflare-workers'

✗ import { KVStore } from 'firebase-auth-cloudflare-workers'

This specific implementation uses Cloudflare KV for caching public JWKs. Ensure it's correctly imported.

EmulatorEnv

✓ import type { EmulatorEnv } from 'firebase-auth-cloudflare-workers'

✗ import { EmulatorEnv } from 'firebase-auth-cloudflare-workers'

EmulatorEnv is a type definition. Import it using 'import type' to avoid bundling issues.

Demonstrates how to set up a Cloudflare Worker using the module syntax to verify a Firebase ID token, including KV store initialization for caching public JWKs and basic error handling. This is a complete, runnable example for a worker.

import type { EmulatorEnv } from "firebase-auth-cloudflare-workers"; import { Auth, WorkersKVStoreSingle } from "firebase-auth-cloudflare-workers"; interface Bindings extends EmulatorEnv { PROJECT_ID: string; PUBLIC_JWK_CACHE_KEY: string; PUBLIC_JWK_CACHE_KV: KVNamespace; FIREBASE_AUTH_EMULATOR_HOST?: string; // Made optional as it's for emulator } const verifyJWT = async (req: Request, env: Bindings): Promise<Response> => { const authorization = req.headers.get('Authorization'); if (authorization === null) { return new Response(JSON.stringify({ error: 'Authorization header missing' }), { status: 400, headers: { 'Content-Type': 'application/json' } }); } const jwt = authorization.replace(/Bearer\s+/i, ""); // Auth is designed as a singleton for Workers const auth = Auth.getOrInitialize( env.PROJECT_ID, WorkersKVStoreSingle.getOrInitialize(env.PUBLIC_JWK_CACHE_KEY, env.PUBLIC_JWK_CACHE_KV) ); try { const firebaseToken = await auth.verifyIdToken(jwt, false, env); return new Response(JSON.stringify(firebaseToken), { headers: { "Content-Type": "application/json" } }); } catch (error: any) { return new Response(JSON.stringify({ error: error.message }), { status: 401, headers: { 'Content-Type': 'application/json' } }); } }; export default { async fetch(request: Request, env: Bindings, ctx: ExecutionContext): Promise<Response> { return await verifyJWT(request, env); } }; // To run, ensure wrangler.toml is configured: // name = "firebase-auth-example" // compatibility_date = "2022-07-05" // // [vars] // PROJECT_ID = "your-firebase-project-id" // PUBLIC_JWK_CACHE_KEY = "public-jwk-cache-key" // FIREBASE_AUTH_EMULATOR_HOST = "127.0.0.1:9099" # Only if using emulator // // [[kv_namespaces]] // binding = "PUBLIC_JWK_CACHE_KV" // id = "<YOUR_KV_NAMESPACE_ID>" // preview_id = "<YOUR_KV_NAMESPACE_PREVIEW_ID>" // // You can install with: `npm i firebase-auth-cloudflare-workers`

Debug

Known issues

gotchaThe `Auth.getOrInitialize` method is designed as a singleton. Repeated calls with the same `projectId` and `keyStore` will return the same `Auth` instance. This behavior is crucial for managing resources efficiently in a Cloudflare Worker's stateless execution model.

fix

Always use `Auth.getOrInitialize` to retrieve the Auth instance, passing the necessary environment variables for consistent behavior across requests.

affects: >=1.0.0

gotchaBy default, `authObj.verifyIdToken` does NOT check if the Firebase session cookie (or ID token) has been revoked. This could allow access with a revoked token. To enable revocation checks, you must explicitly pass `true` as the second argument.

fix

For enhanced security, call `authObj.verifyIdToken(idToken, true, env)` to ensure revocation status is checked. Be aware this incurs an additional network request to Firebase Auth backend.

affects: >=1.0.0

gotchaWhen using the Firebase Auth Emulator, the `env` parameter in `verifyIdToken` is critical for detecting the emulator host. Forgetting to pass `env` (or not configuring `FIREBASE_AUTH_EMULATOR_HOST` in `Bindings` and `wrangler.toml`) will cause token verification to attempt to reach production Firebase services, even if you intend to use the emulator.

fix

Ensure `FIREBASE_AUTH_EMULATOR_HOST` is correctly configured in your Worker's `Bindings` interface and `wrangler.toml`, and always pass the `env` object to `authObj.verifyIdToken` when developing with the emulator.

affects: >=1.0.0

breakingVersions prior to 2.x might have differing initialization patterns or require slightly different type definitions. Upgrading from 1.x to 2.x may require minor adjustments to import paths or method signatures.

fix

Refer to the official documentation for specific migration guides if upgrading from major version 1.x. Ensure `import { Auth } from 'firebase-auth-cloudflare-workers';` and associated types are correct.

affects: <2.0.0

Errors

Common errors & fixes

Error: Firebase ID token has incorrect 'aud' (audience) claim.

The Firebase project ID extracted from the ID token does not match the `projectId` configured for the `Auth` instance in your Cloudflare Worker.

fix

Verify that `env.PROJECT_ID` in your Worker's `Bindings` and `wrangler.toml` exactly matches your Firebase project ID (e.g., `example-project12345`). This ID is part of the token's claims.

Error: Firebase ID token has expired. Get a fresh token from your client app and try again.

The JWT presented in the Authorization header has passed its expiration time.

fix

Ensure the client application is refreshing Firebase ID tokens regularly before they expire. The client-side Firebase SDK handles this automatically, but custom implementations might need explicit refresh logic.

ReferenceError: KVNamespace is not defined

The `PUBLIC_JWK_CACHE_KV` binding, which is an instance of `KVNamespace`, was not properly declared and bound in your `wrangler.toml` file or passed correctly in the Worker's `Bindings`.

fix

Add the `[[kv_namespaces]]` entry to your `wrangler.toml` and ensure `binding = "PUBLIC_JWK_CACHE_KV"` matches the name used in your code, along with a valid `id` for your KV namespace.

Error: Firebase ID token has invalid signature.

The ID token's signature cannot be verified using the public keys obtained from Firebase, possibly due to a malformed token, incorrect public key caching, or an issue with the signing keys.

fix

Check the `PUBLIC_JWK_CACHE_KEY` and `PUBLIC_JWK_CACHE_KV` configurations. Ensure the KV store is accessible and correctly storing / retrieving the public JSON Web Keys (JWKs). Clear the KV cache if keys might be stale.

Upgrade

Version history

2.0.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/firebase-auth-cloudflare-workers ↗