cloudfire-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-Present Connor Skelland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,13 @@
+This software incorporates code from the following third-party components:
+
+-------------------------------------------------------------------------
+
+1.  Component: firebase-admin
+    Copyright 2021 Google Inc.
+
+    This component is licensed under the Apache License, Version 2.0.
+    The full text of the license can be found in the LICENSE file
+    distributed with this software.
+
+    The original source code can be found at:
+    https://github.com/firebase/firebase-admin-node

package/README.md

@@ -0,0 +1,94 @@
+# Cloudfire Auth
+
+A library to make Firebase Auth work in Cloudflare Workers, using native Cloudflare APIs for caching and persistence. The library handles OAuth2 token generation and interactions with the Firebase Auth REST API.
+
+## Features
+
+- 🔥 Firebase Auth compatibility for Cloudflare Workers
+- ⚡ Native Cloudflare KV integration for token caching
+- 🛡️ Full TypeScript support
+- 📦 One dependency, jose for JWT handling
+- 🌐 ESM-only for modern JavaScript environments
+
+## Installation
+
+```bash
+npm install cloudfire-auth
+```
+
+## Quick Start
+
+```typescript
+import { CloudFireAuth, ServiceAccountKey } from "cloudfire-auth";
+
+// Initialize with your Firebase project credentials
+const auth = new CloudFireAuth(
+  "your-firebase-project-id",
+  {
+    // Your Firebase service account key
+    private_key: "-----BEGIN PRIVATE KEY-----\n...",
+    client_email: "firebase-adminsdk-...@your-project.iam.gserviceaccount.com",
+    // ... other service account fields
+  },
+  env.YOUR_KV_NAMESPACE // Optional: KV namespace for token caching
+);
+
+// Verify an ID token
+try {
+  const decodedToken = await auth.verifyIdToken(idToken);
+  console.log("User ID:", decodedToken.uid);
+} catch (error) {
+  console.error("Token verification failed:", error);
+}
+
+// Get user data
+const user = await auth.getUser("user-uid");
+console.log("User email:", user.email);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new CloudFireAuth(projectId: string, serviceAccountKey: ServiceAccountKey, kvNamespace?: KVNamespace)
+```
+
+- `projectId`: Your Firebase project ID
+- `serviceAccountKey`: Firebase service account credentials
+- `kvNamespace`: Optional KV namespace for OAuth2 token caching
+
+### Methods
+
+| Category             | Method                                                               | Status | Description                          |
+| -------------------- | -------------------------------------------------------------------- | ------ | ------------------------------------ |
+| **Authentication**   | `verifyIdToken(idToken: string, checkRevoked?: boolean)`             | ✅     | Verify Firebase ID tokens            |
+|                      | `verifySessionCookie(sessionCookie: string, checkRevoked?: boolean)` | ✅     | Verify session cookies               |
+| **User Management**  | `getUser(uid: string)`                                               | ✅     | Get user by UID                      |
+|                      | `getUserByEmail(email: string)`                                      | ❌     | Get user by email                    |
+|                      | `getUserByPhoneNumber(phoneNumber: string)`                          | ❌     | Get user by phone number             |
+|                      | `getUserByProviderUid(providerId: string, uid: string)`              | ❌     | Get user by provider UID             |
+|                      | `getUsers(identifiers: UserIdentifier[])`                            | ❌     | Get users by identifiers             |
+|                      | `createUser(properties: CreateRequest)`                              | ❌     | Create a new user                    |
+|                      | `updateUser(uid: string, properties: UpdateRequest)`                 | ✅     | Update existing user                 |
+|                      | `deleteUser(uid: string)`                                            | ✅     | Delete a user                        |
+|                      | `deleteUsers(uids: string[])`                                        | ❌     | Delete multiple users                |
+|                      | `listUsers(maxResults?: number, pageToken?: string)`                 | ❌     | List users with pagination           |
+| **Token Management** | `revokeRefreshTokens(uid: string)`                                   | ✅     | Revoke all refresh tokens for a user |
+|                      | `setCustomUserClaims(uid: string, customUserClaims: object \| null)` | ✅     | Set custom claims                    |
+
+## Environment Setup
+
+Your Cloudflare Worker needs these environment variables:
+
+- `FIREBASE_PROJECT_ID`: Your Firebase project ID
+- `FIREBASE_SERVICE_ACCOUNT_KEY`: JSON string of your service account key
+- `AUTH_KV_NAMESPACE`: (Optional) KV namespace for token caching
+
+## License
+
+MIT © Connor Skelland
+
+## Contributing
+
+Issues and pull requests are welcome!

package/dist/CloudFireAuth.d.ts

@@ -0,0 +1,291 @@
+/*! firebase-admin v13.4.0 */
+/*!
+ * Copyright 2021 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Alterations to Firebase Admin SDK Code
+ *
+ * The code covered by the above notice in this file are the method names inside of
+ * the CloudFireAuth class and their corresponding doc headers. The code inside each
+ * of the methods is under the MIT License attached to this project.
+ *
+ * Furthermore the following class methods and their doc headers are also under the MIT
+ * license:
+ *
+ * - getOauth2AccessToken
+ *
+ */
+import type { DecodedIdToken, UserRecord, UserIdentifier, GetUsersResult, ListUsersResult, CreateRequest, UpdateRequest, DeleteUsersResult, ServiceAccountKey } from "./types.js";
+export declare class CloudFireAuth {
+    private projectId;
+    private serviceAccountKey;
+    private oauth2Token?;
+    private kvNamespace?;
+    constructor(serviceAccountKey: ServiceAccountKey, kvNamespace?: KVNamespace);
+    /**
+     * Verifies a Firebase ID token (JWT). If the token is valid, the promise is
+     * fulfilled with the token's decoded claims; otherwise, the promise is
+     * rejected.
+     *
+     * If `checkRevoked` is set to true, first verifies whether the corresponding
+     * user is disabled. If yes, an `auth/user-disabled` error is thrown. If no,
+     * verifies if the session corresponding to the ID token was revoked. If the
+     * corresponding user's session was invalidated, an `auth/id-token-revoked`
+     * error is thrown. If not specified the check is not applied.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/verify-id-tokens | Verify ID Tokens}
+     * for code samples and detailed documentation.
+     *
+     * @param idToken - The ID token to verify.
+     * @param checkRevoked - Whether to check if the ID token was revoked.
+     *   This requires an extra request to the Firebase Auth backend to check
+     *   the `tokensValidAfterTime` time for the corresponding user.
+     *   When not specified, this additional check is not applied.
+     *
+     * @returns A promise fulfilled with the
+     *   token's decoded claims if the ID token is valid; otherwise, a rejected
+     *   promise.
+     */
+    verifyIdToken(idToken: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
+    /**
+     * Gets the user data for the user corresponding to a given `uid`.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` corresponding to the user whose data to fetch.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the provided `uid`.
+     */
+    getUser(uid: string): Promise<UserRecord>;
+    /**
+     * Gets the user data for the user corresponding to a given email.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param email - The email corresponding to the user whose data to
+     *   fetch.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the provided email.
+     */
+    getUserByEmail(email: string): Promise<UserRecord>;
+    /**
+     * Gets the user data for the user corresponding to a given phone number. The
+     * phone number has to conform to the E.164 specification.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param phoneNumber - The phone number corresponding to the user whose
+     *   data to fetch.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the provided phone number.
+     */
+    getUserByPhoneNumber(phoneNumber: string): Promise<UserRecord>;
+    /**
+     * Gets the user data for the user corresponding to a given provider id.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param providerId - The provider ID, for example, "google.com" for the
+     *   Google provider.
+     * @param uid - The user identifier for the given provider.
+     *
+     * @returns A promise fulfilled with the user data corresponding to the
+     *   given provider id.
+     */
+    getUserByProviderUid(providerId: string, uid: string): Promise<UserRecord>;
+    /**
+     * Gets the user data corresponding to the specified identifiers.
+     *
+     * There are no ordering guarantees; in particular, the nth entry in the result list is not
+     * guaranteed to correspond to the nth entry in the input parameters list.
+     *
+     * Only a maximum of 100 identifiers may be supplied. If more than 100 identifiers are supplied,
+     * this method throws a FirebaseAuthError.
+     *
+     * @param identifiers - The identifiers used to indicate which user records should be returned.
+     *     Must not have more than 100 entries.
+     * @returns A promise that resolves to the corresponding user records.
+     * @throws FirebaseAuthError If any of the identifiers are invalid or if more than 100
+     *     identifiers are specified.
+     */
+    getUsers(identifiers: UserIdentifier[]): Promise<GetUsersResult>;
+    /**
+     * Retrieves a list of users (single batch only) with a size of `maxResults`
+     * starting from the offset as specified by `pageToken`. This is used to
+     * retrieve all the users of a specified project in batches.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#list_all_users | List all users}
+     * for code samples and detailed documentation.
+     *
+     * @param maxResults - The page size, 1000 if undefined. This is also
+     *   the maximum allowed limit.
+     * @param pageToken - The next page token. If not specified, returns
+     *   users starting without any offset.
+     * @returns A promise that resolves with
+     *   the current batch of downloaded users and the next page token.
+     */
+    listUsers(maxResults?: number, pageToken?: string): Promise<ListUsersResult>;
+    /**
+     * Creates a new user.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#create_a_user | Create a user}
+     * for code samples and detailed documentation.
+     *
+     * @param properties - The properties to set on the
+     *   new user record to be created.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the newly created user.
+     */
+    createUser(properties: CreateRequest): Promise<UserRecord>;
+    /**
+     * Deletes an existing user.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#delete_a_user | Delete a user}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` corresponding to the user to delete.
+     *
+     * @returns An empty promise fulfilled once the user has been
+     *   deleted.
+     */
+    deleteUser(uid: string): Promise<void>;
+    /**
+     * Deletes the users specified by the given uids.
+     *
+     * Deleting a non-existing user won't generate an error (i.e. this method
+     * is idempotent.) Non-existing users are considered to be successfully
+     * deleted, and are therefore counted in the
+     * `DeleteUsersResult.successCount` value.
+     *
+     * Only a maximum of 1000 identifiers may be supplied. If more than 1000
+     * identifiers are supplied, this method throws a FirebaseAuthError.
+     *
+     * This API is currently rate limited at the server to 1 QPS. If you exceed
+     * this, you may get a quota exceeded error. Therefore, if you want to
+     * delete more than 1000 users, you may need to add a delay to ensure you
+     * don't go over this limit.
+     *
+     * @param uids - The `uids` corresponding to the users to delete.
+     *
+     * @returns A Promise that resolves to the total number of successful/failed
+     *     deletions, as well as the array of errors that corresponds to the
+     *     failed deletions.
+     */
+    deleteUsers(uids: string[]): Promise<DeleteUsersResult>;
+    /**
+     * Updates an existing user.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#update_a_user | Update a user}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` corresponding to the user to update.
+     * @param properties - The properties to update on
+     *   the provided user.
+     *
+     * @returns A promise fulfilled with the
+     *   updated user data.
+     */
+    updateUser(uid: string, properties: UpdateRequest): Promise<UserRecord>;
+    /**
+     * Sets additional developer claims on an existing user identified by the
+     * provided `uid`, typically used to define user roles and levels of
+     * access. These claims should propagate to all devices where the user is
+     * already signed in (after token expiration or when token refresh is forced)
+     * and the next time the user signs in. If a reserved OIDC claim name
+     * is used (sub, iat, iss, etc), an error is thrown. They are set on the
+     * authenticated user's ID token JWT.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/custom-claims |
+     * Defining user roles and access levels}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` of the user to edit.
+     * @param customUserClaims - The developer claims to set. If null is
+     *   passed, existing custom claims are deleted. Passing a custom claims payload
+     *   larger than 1000 bytes will throw an error. Custom claims are added to the
+     *   user's ID token which is transmitted on every authenticated request.
+     *   For profile non-access related user attributes, use database or other
+     *   separate storage systems.
+     * @returns A promise that resolves when the operation completes
+     *   successfully.
+     */
+    setCustomUserClaims(uid: string, customUserClaims: object | null): Promise<void>;
+    /**
+     * Revokes all refresh tokens for an existing user.
+     *
+     * This API will update the user's {@link UserRecord.tokensValidAfterTime} to
+     * the current UTC. It is important that the server on which this is called has
+     * its clock set correctly and synchronized.
+     *
+     * While this will revoke all sessions for a specified user and disable any
+     * new ID tokens for existing sessions from getting minted, existing ID tokens
+     * may remain active until their natural expiration (one hour). To verify that
+     * ID tokens are revoked, use {@link BaseAuth.verifyIdToken}
+     * where `checkRevoked` is set to true.
+     *
+     * @param uid - The `uid` corresponding to the user whose refresh tokens
+     *   are to be revoked.
+     *
+     * @returns An empty promise fulfilled once the user's refresh
+     *   tokens have been revoked.
+     */
+    revokeRefreshTokens(uid: string): Promise<void>;
+    /**
+     * Verifies a Firebase session cookie. Returns a Promise with the cookie claims.
+     * Rejects the promise if the cookie could not be verified.
+     *
+     * If `checkRevoked` is set to true, first verifies whether the corresponding
+     * user is disabled: If yes, an `auth/user-disabled` error is thrown. If no,
+     * verifies if the session corresponding to the session cookie was revoked.
+     * If the corresponding user's session was invalidated, an
+     * `auth/session-cookie-revoked` error is thrown. If not specified the check
+     * is not performed.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-cookies#verify_session_cookie_and_check_permissions |
+     * Verify Session Cookies}
+     * for code samples and detailed documentation
+     *
+     * @param sessionCookie - The session cookie to verify.
+     * @param checkForRevocation -  Whether to check if the session cookie was
+     *   revoked. This requires an extra request to the Firebase Auth backend to
+     *   check the `tokensValidAfterTime` time for the corresponding user.
+     *   When not specified, this additional check is not performed.
+     *
+     * @returns A promise fulfilled with the
+     *   session cookie's decoded claims if the session cookie is valid; otherwise,
+     *   a rejected promise.
+     */
+    verifySessionCookie(sessionCookie: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
+    /**
+     * Gets an OAuth2 access token from Google's OAuth2 server. This token is
+     * required for accessing the Firebase Auth REST API via fetch requests.
+     *
+     * Checks if a token already exists in the KV namespace. If not, it gets a new
+     * token from Google's OAuth2 server, and sets it on the KV namespace.¨
+     *
+     * This code is under the MIT Licence.
+     *
+     * @returns The OAuth2 access token
+     */
+    private getOauth2AccessToken;
+}