Registry / auth-security / cloudfire-auth

cloudfire-auth

JSON →
library0.4.0jsnpmunverified

Cloudfire Auth is a JavaScript/TypeScript library designed to integrate Firebase Authentication functionalities directly within Cloudflare Workers environments. Currently at version 0.4.0, it provides core features such as Firebase ID token verification, user retrieval, and user deletion. The library leverages native Cloudflare APIs, specifically Cloudflare KV, for efficient OAuth2 token caching, which is crucial for performance and cost-effectiveness in a serverless context. It is built with a strong emphasis on modern JavaScript, being ESM-only, and offers full TypeScript support, making it suitable for contemporary development workflows. Key differentiators include its tight integration with Cloudflare's ecosystem, minimal external dependencies (only 'jose' for JWT handling), and its focus on solving the specific challenge of running Firebase Auth in a Worker environment where the official Firebase Admin SDK is not directly compatible due to Node.js-specific dependencies.

npm install cloudfire-auth
INSTALL
IMPORT
SIG · CLOUDFIRE-AUTH
C
cloudfire-auth
auth-securityjavascriptv0.4.0
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.

CloudFireAuth
✓ import { CloudFireAuth } from 'cloudfire-auth';
✗ const CloudFireAuth = require('cloudfire-auth');
The library is ESM-only and does not support CommonJS `require()` syntax. Use ES module imports.
ServiceAccountKey
✓ import type { ServiceAccountKey } from 'cloudfire-auth/types';
Import the `ServiceAccountKey` type explicitly for type-checking, especially when defining your service account object.
KVNamespace
✓ declare const env: { YOUR_KV_NAMESPACE?: KVNamespace }; // In Workers environment const auth = new CloudFireAuth(serviceAccountKey, env.YOUR_KV_NAMESPACE);
While `KVNamespace` is a global type in Cloudflare Workers, it's often passed to the constructor. Ensure it's correctly typed and available in your Worker's `env` object.

This quickstart demonstrates how to initialize `CloudFireAuth` in a Cloudflare Worker, load service account credentials from environment variables, and verify a Firebase ID token from an incoming request's Authorization header.

import { CloudFireAuth } from "cloudfire-auth"; interface Env { YOUR_KV_NAMESPACE?: KVNamespace; FIREBASE_PRIVATE_KEY: string; FIREBASE_CLIENT_EMAIL: string; // ... other service account fields as environment variables } export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> { // It is best practice to store your service account key separately and // load it from a secure source, e.g., environment variables. const serviceAccountKey = { private_key: env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, '\n'), // Handle newline characters if from env client_email: env.FIREBASE_CLIENT_EMAIL, // Add other necessary fields from your Firebase service account key // For example, project_id, type, private_key_id, etc. // Ensure the structure matches ServiceAccountKey type. }; // Initialize with your Firebase project credentials const auth = new CloudFireAuth( serviceAccountKey, env.YOUR_KV_NAMESPACE // Optional: KV namespace for token caching ); const idToken = request.headers.get('Authorization')?.split('Bearer ')[1]; if (!idToken) { return new Response('No ID token provided', { status: 401 }); } // Verify an ID token try { const decodedToken = await auth.verifyIdToken(idToken); console.log("User ID:", decodedToken.uid); return new Response(`Verified user: ${decodedToken.uid}`, { status: 200 }); } catch (error: any) { console.error("Token verification failed:", error.message); return new Response(`Token verification failed: ${error.message}`, { status: 401 }); } }, };
Debug
Known issues
gotchaCloudfire Auth is ESM-only. Attempting to import it using CommonJS `require()` will result in a runtime error.
fix
Always use ES module import syntax: `import { CloudFireAuth } from 'cloudfire-auth';`
affects: >=0.1.0
gotchaNot all Firebase Admin SDK methods are currently implemented. Several authentication and user management methods are marked with '❌' in the API reference (e.g., `verifySessionCookie`, `createCustomToken`, `createUser`, `getUserByEmail`, `deleteUsers`).
fix
Review the API reference carefully before integrating to ensure the required functionality is available. If a method is missing, you may need to implement it manually using the Firebase REST API or contribute to the library.
affects: >=0.1.0
gotchaThe `serviceAccountKey` must be correctly formatted. When loading from environment variables, private keys with newline characters (e.g., `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----`) must have these newlines preserved or correctly replaced (e.g., using `.replace(/\\n/g, '\n')`).
fix
Ensure the `private_key` string in your `serviceAccountKey` object has actual newline characters '\n', not escaped '\\n'. When loading from `.env` or similar, explicit replacement might be needed.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Dynamic require of "crypto" is not supported
Attempting to use `cloudfire-auth` in a Node.js-incompatible environment (like Cloudflare Workers) while a dependency tries to `require` Node.js built-ins, or if the library itself is incorrectly bundled.
fix
This specific library is designed for Cloudflare Workers. Ensure you are importing correctly (`import`) and that your build process for the Worker handles ESM correctly. This error can also indicate a misconfigured dependency attempting to use Node.js crypto, but `cloudfire-auth` aims to avoid this by using `jose` which is universal.
SyntaxError: Unexpected token 'export'
Trying to run ESM-only code in an environment that only supports CommonJS, or a build tool is misconfigured for ESM.
fix
Ensure your Cloudflare Worker environment and local development setup are configured for ES Modules. If using `npm install` and bundling, verify your bundler (e.g., Webpack, Rollup, esbuild) correctly handles `module` and `exports` fields in `package.json` for ESM.
Error: Id token is expired. Get a fresh one from your client app and try again.
The Firebase ID token provided to `verifyIdToken` has exceeded its validity period (typically 1 hour).
fix
Instruct the client application to refresh the ID token and send the newly obtained token. Firebase client SDKs automatically handle token refreshing; ensure the client-side logic correctly retrieves and sends fresh tokens.
TypeError: Cannot read properties of undefined (reading 'YOUR_KV_NAMESPACE')
The `KVNamespace` object was not provided to the `CloudFireAuth` constructor when it was expected, or `env` is not correctly passed/typed in your Worker handler.
fix
If you intend to use KV caching, ensure `env.YOUR_KV_NAMESPACE` (or whatever your KV binding is named) is correctly passed as the second argument to `new CloudFireAuth()`. If not using KV, ensure the constructor is called without the second argument, or explicitly with `undefined`.
Upgrade
Version history
0.4.0latest on npm
Audit
Dependencies
joserequiredRequired for secure JSON Web Token (JWT) handling and verification.
Agent activity
18 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources
cloudfire-auth — npm install cloudfire-auth · libregistry