@prmichaelsen/firebase-admin-sdk-v8 2.0.2 → 2.0.5

package/README.md

@@ -30,28 +30,50 @@ npm install firebase-admin-sdk-v8
 
 ## 🚀 Quick Start
 
-### 1. Set Environment Variables
+### 1. Initialize the SDK
 
-```env
-# Firebase Admin Service Account (JSON string) - REQUIRED
-FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}'
+**Option A: Cloudflare Workers / Edge Runtimes (Recommended)**
 
-# Firebase Project ID - REQUIRED (use either variable name)
-FIREBASE_PROJECT_ID=your-project-id
-# OR
-PUBLIC_FIREBASE_PROJECT_ID=your-project-id
-
-# Optional: Standard Firebase client config (for reference)
-FIREBASE_API_KEY=your-api-key
-FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
-FIREBASE_STORAGE_BUCKET=your-project.appspot.com
-FIREBASE_MESSAGING_SENDER_ID=your-sender-id
-FIREBASE_APP_ID=your-app-id
+```typescript
+import { initializeApp, verifyIdToken } from '@prmichaelsen/firebase-admin-sdk-v8';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Initialize with env variables
+    initializeApp({
+      serviceAccount: env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY,
+      projectId: env.FIREBASE_PROJECT_ID
+    });
+
+    // Now use the SDK
+    const token = request.headers.get('authorization')?.split('Bearer ')[1];
+    const user = await verifyIdToken(token);
+    
+    return new Response(JSON.stringify({ user }));
+  }
+};
+```
+
+**Option B: Node.js / Traditional Environments**
+
+```typescript
+import { initializeApp } from '@prmichaelsen/firebase-admin-sdk-v8';
+
+// Option 1: Explicit initialization
+initializeApp({
+  serviceAccount: JSON.parse(process.env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY!),
+  projectId: process.env.FIREBASE_PROJECT_ID
+});
+
+// Option 2: Auto-detect from process.env (no initialization needed)
+// The SDK will automatically use process.env if initializeApp() is not called
 ```
 
-**Required Environment Variables:**
-- `FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY` - Your Firebase service account JSON (as a string)
-- `FIREBASE_PROJECT_ID` or `PUBLIC_FIREBASE_PROJECT_ID` - Your Firebase project ID
+**Environment Variables (if not using initializeApp):**
+```env
+FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY='{"type":"service_account",...}'
+FIREBASE_PROJECT_ID=your-project-id
+```
 
 ### 2. Verify ID Tokens
 

package/dist/index.d.mts

@@ -175,6 +175,67 @@ interface BatchWriteResult {
     }>;
 }
 
+/**
+ * Firebase Admin SDK v8 - Configuration
+ * Manages SDK configuration and credentials
+ */
+
+/**
+ * SDK Configuration
+ */
+interface SDKConfig {
+    serviceAccount?: ServiceAccount | string;
+    projectId?: string;
+}
+/**
+ * Initialize the Firebase Admin SDK with configuration
+ * This is optional - the SDK will fall back to environment variables if not called
+ *
+ * @param config - SDK configuration
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare Workers
+ * export default {
+ *   async fetch(request, env) {
+ *     initializeApp({
+ *       serviceAccount: env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY,
+ *       projectId: env.FIREBASE_PROJECT_ID
+ *     });
+ *     // ... use SDK
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Node.js (optional - will use process.env by default)
+ * initializeApp({
+ *   serviceAccount: JSON.parse(process.env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY),
+ *   projectId: process.env.FIREBASE_PROJECT_ID
+ * });
+ * ```
+ */
+declare function initializeApp(config: SDKConfig): void;
+/**
+ * Get the current SDK configuration
+ */
+declare function getConfig(): SDKConfig;
+/**
+ * Clear the SDK configuration (useful for testing)
+ */
+declare function clearConfig(): void;
+/**
+ * Get service account from config or environment
+ * Priority: 1) globalConfig, 2) process.env
+ */
+declare function getServiceAccount(): ServiceAccount;
+/**
+ * Get Firebase project ID from config or environment
+ * Priority: 1) globalConfig, 2) process.env
+ */
+declare function getProjectId(): string;
+
 /**
  * Firebase Admin SDK v8 - Authentication
  * ID token verification supporting both Firebase v9 and v10 token formats
@@ -451,22 +512,4 @@ declare function getAdminAccessToken(): Promise<string>;
  */
 declare function clearTokenCache(): void;
 
-/**
- * Firebase Admin SDK v8 - Service Account Management
- */
-
-/**
- * Get Firebase service account from environment variable
- * @throws {Error} If FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY is not set
- * @returns {ServiceAccount} Parsed service account credentials
- */
-declare function getServiceAccount(): ServiceAccount;
-/**
- * Get Firebase project ID from environment
- * Checks multiple possible environment variable names
- * @throws {Error} If no project ID is found
- * @returns {string} Firebase project ID
- */
-declare function getProjectId(): string;
-
-export { type BatchWrite, type BatchWriteResult, type DataObject, type DecodedIdToken, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FirestoreDocument, type FirestoreValue, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type TokenResponse, type UpdateOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearTokenCache, deleteDocument, getAdminAccessToken, getAuth, getDocument, getProjectId, getServiceAccount, getUserFromToken, queryDocuments, setDocument, updateDocument, verifyIdToken };
+export { type BatchWrite, type BatchWriteResult, type DataObject, type DecodedIdToken, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FirestoreDocument, type FirestoreValue, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type TokenResponse, type UpdateOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearConfig, clearTokenCache, deleteDocument, getAdminAccessToken, getAuth, getConfig, getDocument, getProjectId, getServiceAccount, getUserFromToken, initializeApp, queryDocuments, setDocument, updateDocument, verifyIdToken };

package/dist/index.d.ts

@@ -175,6 +175,67 @@ interface BatchWriteResult {
     }>;
 }
 
+/**
+ * Firebase Admin SDK v8 - Configuration
+ * Manages SDK configuration and credentials
+ */
+
+/**
+ * SDK Configuration
+ */
+interface SDKConfig {
+    serviceAccount?: ServiceAccount | string;
+    projectId?: string;
+}
+/**
+ * Initialize the Firebase Admin SDK with configuration
+ * This is optional - the SDK will fall back to environment variables if not called
+ *
+ * @param config - SDK configuration
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare Workers
+ * export default {
+ *   async fetch(request, env) {
+ *     initializeApp({
+ *       serviceAccount: env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY,
+ *       projectId: env.FIREBASE_PROJECT_ID
+ *     });
+ *     // ... use SDK
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Node.js (optional - will use process.env by default)
+ * initializeApp({
+ *   serviceAccount: JSON.parse(process.env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY),
+ *   projectId: process.env.FIREBASE_PROJECT_ID
+ * });
+ * ```
+ */
+declare function initializeApp(config: SDKConfig): void;
+/**
+ * Get the current SDK configuration
+ */
+declare function getConfig(): SDKConfig;
+/**
+ * Clear the SDK configuration (useful for testing)
+ */
+declare function clearConfig(): void;
+/**
+ * Get service account from config or environment
+ * Priority: 1) globalConfig, 2) process.env
+ */
+declare function getServiceAccount(): ServiceAccount;
+/**
+ * Get Firebase project ID from config or environment
+ * Priority: 1) globalConfig, 2) process.env
+ */
+declare function getProjectId(): string;
+
 /**
  * Firebase Admin SDK v8 - Authentication
  * ID token verification supporting both Firebase v9 and v10 token formats
@@ -451,22 +512,4 @@ declare function getAdminAccessToken(): Promise<string>;
  */
 declare function clearTokenCache(): void;
 
-/**
- * Firebase Admin SDK v8 - Service Account Management
- */
-
-/**
- * Get Firebase service account from environment variable
- * @throws {Error} If FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY is not set
- * @returns {ServiceAccount} Parsed service account credentials
- */
-declare function getServiceAccount(): ServiceAccount;
-/**
- * Get Firebase project ID from environment
- * Checks multiple possible environment variable names
- * @throws {Error} If no project ID is found
- * @returns {string} Firebase project ID
- */
-declare function getProjectId(): string;
-
-export { type BatchWrite, type BatchWriteResult, type DataObject, type DecodedIdToken, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FirestoreDocument, type FirestoreValue, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type TokenResponse, type UpdateOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearTokenCache, deleteDocument, getAdminAccessToken, getAuth, getDocument, getProjectId, getServiceAccount, getUserFromToken, queryDocuments, setDocument, updateDocument, verifyIdToken };
+export { type BatchWrite, type BatchWriteResult, type DataObject, type DecodedIdToken, FieldValue, type FieldValue$1 as FieldValueSentinel, FieldValueType, type FirestoreDocument, type FirestoreValue, type QueryFilter, type QueryOptions, type QueryOrder, type ServiceAccount, type SetOptions, type TokenResponse, type UpdateOptions, type UserInfo, type WhereFilterOp, addDocument, batchWrite, clearConfig, clearTokenCache, deleteDocument, getAdminAccessToken, getAuth, getConfig, getDocument, getProjectId, getServiceAccount, getUserFromToken, initializeApp, queryDocuments, setDocument, updateDocument, verifyIdToken };

package/dist/index.js

@@ -23,14 +23,17 @@ __export(index_exports, {
   FieldValue: () => FieldValue,
   addDocument: () => addDocument,
   batchWrite: () => batchWrite,
+  clearConfig: () => clearConfig,
   clearTokenCache: () => clearTokenCache,
   deleteDocument: () => deleteDocument,
   getAdminAccessToken: () => getAdminAccessToken,
   getAuth: () => getAuth,
+  getConfig: () => getConfig,
   getDocument: () => getDocument,
   getProjectId: () => getProjectId,
   getServiceAccount: () => getServiceAccount,
   getUserFromToken: () => getUserFromToken,
+  initializeApp: () => initializeApp,
   queryDocuments: () => queryDocuments,
   setDocument: () => setDocument,
   updateDocument: () => updateDocument,
@@ -38,12 +41,28 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/service-account.ts
+// src/config.ts
+var globalConfig = {};
+function initializeApp(config) {
+  globalConfig = { ...config };
+}
+function getConfig() {
+  return globalConfig;
+}
+function clearConfig() {
+  globalConfig = {};
+}
 function getServiceAccount() {
-  const key = process.env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY;
+  if (globalConfig.serviceAccount) {
+    if (typeof globalConfig.serviceAccount === "string") {
+      return JSON.parse(globalConfig.serviceAccount);
+    }
+    return globalConfig.serviceAccount;
+  }
+  const key = typeof process !== "undefined" && process.env?.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY;
   if (!key) {
     throw new Error(
-      `FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY environment variable is not set. Please provide your Firebase service account JSON as a string. Example: FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY='{"type":"service_account",...}'`
+      "Firebase service account not configured. Either call initializeApp({ serviceAccount: ... }) or set FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY environment variable."
     );
   }
   try {
@@ -73,13 +92,18 @@ function getServiceAccount() {
   }
 }
 function getProjectId() {
-  const projectId = process.env.FIREBASE_PROJECT_ID || process.env.PUBLIC_FIREBASE_PROJECT_ID;
-  if (!projectId) {
-    throw new Error(
-      "Firebase project ID not found. Please set one of: FIREBASE_PROJECT_ID or PUBLIC_FIREBASE_PROJECT_ID"
-    );
+  if (globalConfig.projectId) {
+    return globalConfig.projectId;
+  }
+  if (typeof process !== "undefined" && process.env) {
+    const projectId = process.env.FIREBASE_PROJECT_ID || process.env.PUBLIC_FIREBASE_PROJECT_ID;
+    if (projectId) {
+      return projectId;
+    }
   }
-  return projectId;
+  throw new Error(
+    "Firebase project ID not configured. Either call initializeApp({ projectId: ... }) or set FIREBASE_PROJECT_ID environment variable."
+  );
 }
 
 // src/x509.ts
@@ -173,18 +197,22 @@ async function importPublicKeyFromX509(pem) {
 // src/auth.ts
 var publicKeysCache = null;
 var publicKeysCacheExpiry = 0;
-async function fetchPublicKeys() {
+async function fetchPublicKeys(issuer) {
+  let endpoint = "https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com";
+  if (issuer && issuer.includes("session.firebase.google.com")) {
+    endpoint = "https://www.googleapis.com/identitytoolkit/v3/relyingparty/publicKeys";
+  }
   if (publicKeysCache && Date.now() < publicKeysCacheExpiry) {
     return publicKeysCache;
   }
-  const response = await fetch(
-    "https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com"
-  );
+  console.log(`[fetchPublicKeys] Fetching from: ${endpoint}`);
+  const response = await fetch(endpoint);
   if (!response.ok) {
-    throw new Error("Failed to fetch Firebase public keys");
+    throw new Error(`Failed to fetch Firebase public keys from ${endpoint}`);
   }
   publicKeysCache = await response.json();
   publicKeysCacheExpiry = Date.now() + 36e5;
+  console.log(`[fetchPublicKeys] Fetched ${Object.keys(publicKeysCache || {}).length} keys`);
   return publicKeysCache;
 }
 function base64UrlDecode(str) {
@@ -257,13 +285,20 @@ async function verifyIdToken(idToken) {
     if (payload.sub.length > 128) {
       throw new Error("Subject too long");
     }
-    const publicKeys = await fetchPublicKeys();
-    const publicKeyPem = publicKeys[header.kid];
+    let publicKeys = await fetchPublicKeys(payload.iss);
+    let publicKeyPem = publicKeys[header.kid];
     if (!publicKeyPem) {
-      const availableKids = Object.keys(publicKeys).join(", ");
-      throw new Error(
-        `Public key not found for kid: ${header.kid}. Available kids: ${availableKids}. This might indicate a key rotation issue or the token is from a different Firebase project.`
-      );
+      console.log(`[verifyIdToken] Key ${header.kid} not found in cache, refreshing keys...`);
+      publicKeysCache = null;
+      publicKeysCacheExpiry = 0;
+      publicKeys = await fetchPublicKeys(payload.iss);
+      publicKeyPem = publicKeys[header.kid];
+      if (!publicKeyPem) {
+        const availableKids = Object.keys(publicKeys).join(", ");
+        throw new Error(
+          `Public key not found for kid: ${header.kid}. Available kids: ${availableKids}. This might indicate the token is from a different Firebase project or was signed with a very old key.`
+        );
+      }
     }
     const publicKey = await importPublicKeyFromX509(publicKeyPem);
     const isValid = await verifySignature(idToken, publicKey);
@@ -863,14 +898,17 @@ async function batchWrite(operations) {
   FieldValue,
   addDocument,
   batchWrite,
+  clearConfig,
   clearTokenCache,
   deleteDocument,
   getAdminAccessToken,
   getAuth,
+  getConfig,
   getDocument,
   getProjectId,
   getServiceAccount,
   getUserFromToken,
+  initializeApp,
   queryDocuments,
   setDocument,
   updateDocument,

package/dist/index.mjs

@@ -1,9 +1,25 @@
-// src/service-account.ts
+// src/config.ts
+var globalConfig = {};
+function initializeApp(config) {
+  globalConfig = { ...config };
+}
+function getConfig() {
+  return globalConfig;
+}
+function clearConfig() {
+  globalConfig = {};
+}
 function getServiceAccount() {
-  const key = process.env.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY;
+  if (globalConfig.serviceAccount) {
+    if (typeof globalConfig.serviceAccount === "string") {
+      return JSON.parse(globalConfig.serviceAccount);
+    }
+    return globalConfig.serviceAccount;
+  }
+  const key = typeof process !== "undefined" && process.env?.FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY;
   if (!key) {
     throw new Error(
-      `FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY environment variable is not set. Please provide your Firebase service account JSON as a string. Example: FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY='{"type":"service_account",...}'`
+      "Firebase service account not configured. Either call initializeApp({ serviceAccount: ... }) or set FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY environment variable."
     );
   }
   try {
@@ -33,13 +49,18 @@ function getServiceAccount() {
   }
 }
 function getProjectId() {
-  const projectId = process.env.FIREBASE_PROJECT_ID || process.env.PUBLIC_FIREBASE_PROJECT_ID;
-  if (!projectId) {
-    throw new Error(
-      "Firebase project ID not found. Please set one of: FIREBASE_PROJECT_ID or PUBLIC_FIREBASE_PROJECT_ID"
-    );
+  if (globalConfig.projectId) {
+    return globalConfig.projectId;
+  }
+  if (typeof process !== "undefined" && process.env) {
+    const projectId = process.env.FIREBASE_PROJECT_ID || process.env.PUBLIC_FIREBASE_PROJECT_ID;
+    if (projectId) {
+      return projectId;
+    }
   }
-  return projectId;
+  throw new Error(
+    "Firebase project ID not configured. Either call initializeApp({ projectId: ... }) or set FIREBASE_PROJECT_ID environment variable."
+  );
 }
 
 // src/x509.ts
@@ -133,18 +154,22 @@ async function importPublicKeyFromX509(pem) {
 // src/auth.ts
 var publicKeysCache = null;
 var publicKeysCacheExpiry = 0;
-async function fetchPublicKeys() {
+async function fetchPublicKeys(issuer) {
+  let endpoint = "https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com";
+  if (issuer && issuer.includes("session.firebase.google.com")) {
+    endpoint = "https://www.googleapis.com/identitytoolkit/v3/relyingparty/publicKeys";
+  }
   if (publicKeysCache && Date.now() < publicKeysCacheExpiry) {
     return publicKeysCache;
   }
-  const response = await fetch(
-    "https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com"
-  );
+  console.log(`[fetchPublicKeys] Fetching from: ${endpoint}`);
+  const response = await fetch(endpoint);
   if (!response.ok) {
-    throw new Error("Failed to fetch Firebase public keys");
+    throw new Error(`Failed to fetch Firebase public keys from ${endpoint}`);
   }
   publicKeysCache = await response.json();
   publicKeysCacheExpiry = Date.now() + 36e5;
+  console.log(`[fetchPublicKeys] Fetched ${Object.keys(publicKeysCache || {}).length} keys`);
   return publicKeysCache;
 }
 function base64UrlDecode(str) {
@@ -217,13 +242,20 @@ async function verifyIdToken(idToken) {
     if (payload.sub.length > 128) {
       throw new Error("Subject too long");
     }
-    const publicKeys = await fetchPublicKeys();
-    const publicKeyPem = publicKeys[header.kid];
+    let publicKeys = await fetchPublicKeys(payload.iss);
+    let publicKeyPem = publicKeys[header.kid];
     if (!publicKeyPem) {
-      const availableKids = Object.keys(publicKeys).join(", ");
-      throw new Error(
-        `Public key not found for kid: ${header.kid}. Available kids: ${availableKids}. This might indicate a key rotation issue or the token is from a different Firebase project.`
-      );
+      console.log(`[verifyIdToken] Key ${header.kid} not found in cache, refreshing keys...`);
+      publicKeysCache = null;
+      publicKeysCacheExpiry = 0;
+      publicKeys = await fetchPublicKeys(payload.iss);
+      publicKeyPem = publicKeys[header.kid];
+      if (!publicKeyPem) {
+        const availableKids = Object.keys(publicKeys).join(", ");
+        throw new Error(
+          `Public key not found for kid: ${header.kid}. Available kids: ${availableKids}. This might indicate the token is from a different Firebase project or was signed with a very old key.`
+        );
+      }
     }
     const publicKey = await importPublicKeyFromX509(publicKeyPem);
     const isValid = await verifySignature(idToken, publicKey);
@@ -822,14 +854,17 @@ export {
   FieldValue,
   addDocument,
   batchWrite,
+  clearConfig,
   clearTokenCache,
   deleteDocument,
   getAdminAccessToken,
   getAuth,
+  getConfig,
   getDocument,
   getProjectId,
   getServiceAccount,
   getUserFromToken,
+  initializeApp,
   queryDocuments,
   setDocument,
   updateDocument,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prmichaelsen/firebase-admin-sdk-v8",
-  "version": "2.0.2",
+  "version": "2.0.5",
   "description": "Firebase Admin SDK for Cloudflare Workers and edge runtimes using REST APIs",
   "main": "dist/index.js",
   "module": "dist/index.mjs",