cloudfire-auth 0.1.0 → 0.3.0

package/README.md

@@ -19,17 +19,20 @@ npm install cloudfire-auth
 ## Quick Start
 
 ```typescript
-import { CloudFireAuth, ServiceAccountKey } from "cloudfire-auth";
+import { CloudFireAuth } from "cloudfire-auth";
+
+// It is best practice to store your service account key separately and
+// load it from a secure source.
+const serviceAccountKey = {
+  // Your Firebase service account key
+  private_key: "-----BEGIN PRIVATE KEY-----\n...",
+  client_email: "firebase-adminsdk-...@your-project.iam.gserviceaccount.com",
+  // ... other service account fields
+};
 
 // 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
-  },
+  serviceAccountKey,
   env.YOUR_KV_NAMESPACE // Optional: KV namespace for token caching
 );
 
@@ -51,37 +54,47 @@ console.log("User email:", user.email);
 ### Constructor
 
 ```typescript
-new CloudFireAuth(projectId: string, serviceAccountKey: ServiceAccountKey, kvNamespace?: KVNamespace)
+new CloudFireAuth(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                    |
+| Category                   | Method                                                                                                       | Status | Description                             |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------- |
+| **Authentication**         | `verifyIdToken(idToken: string, checkRevoked?: boolean)`                                                     | ✅     | Verify Firebase ID tokens               |
+|                            | `verifySessionCookie(sessionCookie: string, checkRevoked?: boolean)`                                         | ✅     | Verify session cookies                  |
+|                            | `createSessionCookie(idToken: string, sessionCookieOptions: SessionCookieOptions)`                           | ❌     | Create session cookie from ID token     |
+|                            | `createCustomToken(uid: string, developerClaims?: object)`                                                   | ❌     | Create custom token for client SDK      |
+| **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              |
+|                            | `importUsers(users: UserImportRecord[], options?: UserImportOptions)`                                        | ❌     | Bulk import users with password hashes  |
+| **Token Management**       | `revokeRefreshTokens(uid: string)`                                                                           | ✅     | Revoke all refresh tokens for a user    |
+|                            | `setCustomUserClaims(uid: string, customUserClaims: object \| null)`                                         | ✅     | Set custom claims                       |
+| **Email Actions**          | `generatePasswordResetLink(email: string, actionCodeSettings?: ActionCodeSettings)`                          | ❌     | Generate password reset link            |
+|                            | `generateEmailVerificationLink(email: string, actionCodeSettings?: ActionCodeSettings)`                      | ❌     | Generate email verification link        |
+|                            | `generateVerifyAndChangeEmailLink(email: string, newEmail: string, actionCodeSettings?: ActionCodeSettings)` | ❌     | Generate email change verification link |
+|                            | `generateSignInWithEmailLink(email: string, actionCodeSettings: ActionCodeSettings)`                         | ❌     | Generate sign-in with email link        |
+| **Provider Configuration** | `listProviderConfigs(options: AuthProviderConfigFilter)`                                                     | ❌     | List SAML/OIDC provider configurations  |
+|                            | `getProviderConfig(providerId: string)`                                                                      | ❌     | Get provider configuration by ID        |
+|                            | `createProviderConfig(config: AuthProviderConfig)`                                                           | ❌     | Create new provider configuration       |
+|                            | `updateProviderConfig(providerId: string, updatedConfig: UpdateAuthProviderRequest)`                         | ❌     | Update provider configuration           |
+|                            | `deleteProviderConfig(providerId: string)`                                                                   | ❌     | Delete provider configuration           |
 
 ## 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
 

package/dist/CloudFireAuth.d.ts

@@ -14,6 +14,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * You can find the code taken from the Firebase Admin SDK in this location of
+ * the firebase-admin 13.4.0 npm package:
+ *
+ * firebase-admin/lib/auth/base-auth.d.ts
+ */
 /**
  * Alterations to Firebase Admin SDK Code
  *
@@ -27,13 +33,30 @@
  * - getOauth2AccessToken
  *
  */
-import type { DecodedIdToken, UserRecord, UserIdentifier, GetUsersResult, ListUsersResult, CreateRequest, UpdateRequest, DeleteUsersResult, ServiceAccountKey } from "./types.js";
+import type { DecodedIdToken, UserRecord, UserIdentifier, GetUsersResult, ListUsersResult, CreateRequest, UpdateRequest, DeleteUsersResult, ServiceAccountKey, SessionCookieOptions, ActionCodeSettings, AuthProviderConfig, UpdateAuthProviderRequest, AuthProviderConfigFilter, ListProviderConfigResults, UserImportRecord, UserImportOptions, UserImportResult } from "./types.js";
 export declare class CloudFireAuth {
     private projectId;
     private serviceAccountKey;
     private oauth2Token?;
     private kvNamespace?;
     constructor(serviceAccountKey: ServiceAccountKey, kvNamespace?: KVNamespace);
+    /**
+     * Creates a new Firebase custom token (JWT) that can be sent back to a client
+     * device to use to sign in with the client SDKs' `signInWithCustomToken()`
+     * methods. (Tenant-aware instances will also embed the tenant ID in the
+     * token.)
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/create-custom-tokens | Create Custom Tokens}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` to use as the custom token's subject.
+     * @param developerClaims - Optional additional claims to include
+     *   in the custom token's payload.
+     *
+     * @returns A promise fulfilled with a custom token for the
+     *   provided `uid` and payload.
+     */
+    createCustomToken(uid: string, developerClaims?: object): Promise<string>;
     /**
      * 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
@@ -250,6 +273,42 @@ export declare class CloudFireAuth {
      *   tokens have been revoked.
      */
     revokeRefreshTokens(uid: string): Promise<void>;
+    /**
+     * Imports the provided list of users into Firebase Auth.
+     * A maximum of 1000 users are allowed to be imported one at a time.
+     * When importing users with passwords,
+     * {@link UserImportOptions} are required to be
+     * specified.
+     * This operation is optimized for bulk imports and will ignore checks on `uid`,
+     * `email` and other identifier uniqueness which could result in duplications.
+     *
+     * @param users - The list of user records to import to Firebase Auth.
+     * @param options - The user import options, required when the users provided include
+     *   password credentials.
+     * @returns A promise that resolves when
+     *   the operation completes with the result of the import. This includes the
+     *   number of successful imports, the number of failed imports and their
+     *   corresponding errors.
+     */
+    importUsers(users: UserImportRecord[], options?: UserImportOptions): Promise<UserImportResult>;
+    /**
+     * Creates a new Firebase session cookie with the specified options. The created
+     * JWT string can be set as a server-side session cookie with a custom cookie
+     * policy, and be used for session management. The session cookie JWT will have
+     * the same payload claims as the provided ID token.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-cookies | Manage Session Cookies}
+     * for code samples and detailed documentation.
+     *
+     * @param idToken - The Firebase ID token to exchange for a session
+     *   cookie.
+     * @param sessionCookieOptions - The session
+     *   cookie options which includes custom session duration.
+     *
+     * @returns A promise that resolves on success with the
+     *   created session cookie.
+     */
+    createSessionCookie(idToken: string, sessionCookieOptions: SessionCookieOptions): Promise<string>;
     /**
      * Verifies a Firebase session cookie. Returns a Promise with the cookie claims.
      * Rejects the promise if the cookie could not be verified.
@@ -276,6 +335,250 @@ export declare class CloudFireAuth {
      *   a rejected promise.
      */
     verifySessionCookie(sessionCookie: string, checkRevoked?: boolean): Promise<DecodedIdToken>;
+    /**
+     * Generates the out of band email action link to reset a user's password.
+     * The link is generated for the user with the specified email address. The
+     * optional  {@link ActionCodeSettings} object
+     * defines whether the link is to be handled by a mobile app or browser and the
+     * additional state information to be passed in the deep link, etc.
+     *
+     * @example
+     * ```javascript
+     * var actionCodeSettings = {
+     *   url: 'https://www.example.com/?email=user@example.com',
+     *   iOS: {
+     *     bundleId: 'com.example.ios'
+     *   },
+     *   android: {
+     *     packageName: 'com.example.android',
+     *     installApp: true,
+     *     minimumVersion: '12'
+     *   },
+     *   handleCodeInApp: true,
+     *   linkDomain: 'project-id.firebaseapp.com'
+     * };
+     * admin.auth()
+     *     .generatePasswordResetLink('user@example.com', actionCodeSettings)
+     *     .then(function(link) {
+     *       // The link was successfully generated.
+     *     })
+     *     .catch(function(error) {
+     *       // Some error occurred, you can inspect the code: error.code
+     *     });
+     * ```
+     *
+     * @param email - The email address of the user whose password is to be
+     *   reset.
+     * @param actionCodeSettings - The action
+     *     code settings. If specified, the state/continue URL is set as the
+     *     "continueUrl" parameter in the password reset link. The default password
+     *     reset landing page will use this to display a link to go back to the app
+     *     if it is installed.
+     *     If the actionCodeSettings is not specified, no URL is appended to the
+     *     action URL.
+     *     The state URL provided must belong to a domain that is whitelisted by the
+     *     developer in the console. Otherwise an error is thrown.
+     *     Mobile app redirects are only applicable if the developer configures
+     *     and accepts the Firebase Dynamic Links terms of service.
+     *     The Android package name and iOS bundle ID are respected only if they
+     *     are configured in the same Firebase Auth project.
+     * @returns A promise that resolves with the generated link.
+     */
+    generatePasswordResetLink(email: string, actionCodeSettings?: ActionCodeSettings): Promise<string>;
+    /**
+     * Generates the out of band email action link to verify the user's ownership
+     * of the specified email. The {@link ActionCodeSettings} object provided
+     * as an argument to this method defines whether the link is to be handled by a
+     * mobile app or browser along with additional state information to be passed in
+     * the deep link, etc.
+     *
+     * @example
+     * ```javascript
+     * var actionCodeSettings = {
+     *   url: 'https://www.example.com/cart?email=user@example.com&cartId=123',
+     *   iOS: {
+     *     bundleId: 'com.example.ios'
+     *   },
+     *   android: {
+     *     packageName: 'com.example.android',
+     *     installApp: true,
+     *     minimumVersion: '12'
+     *   },
+     *   handleCodeInApp: true,
+     *   linkDomain: 'project-id.firebaseapp.com'
+     * };
+     * admin.auth()
+     *     .generateEmailVerificationLink('user@example.com', actionCodeSettings)
+     *     .then(function(link) {
+     *       // The link was successfully generated.
+     *     })
+     *     .catch(function(error) {
+     *       // Some error occurred, you can inspect the code: error.code
+     *     });
+     * ```
+     *
+     * @param email - The email account to verify.
+     * @param actionCodeSettings - The action
+     *     code settings. If specified, the state/continue URL is set as the
+     *     "continueUrl" parameter in the email verification link. The default email
+     *     verification landing page will use this to display a link to go back to
+     *     the app if it is installed.
+     *     If the actionCodeSettings is not specified, no URL is appended to the
+     *     action URL.
+     *     The state URL provided must belong to a domain that is whitelisted by the
+     *     developer in the console. Otherwise an error is thrown.
+     *     Mobile app redirects are only applicable if the developer configures
+     *     and accepts the Firebase Dynamic Links terms of service.
+     *     The Android package name and iOS bundle ID are respected only if they
+     *     are configured in the same Firebase Auth project.
+     * @returns A promise that resolves with the generated link.
+     */
+    generateEmailVerificationLink(email: string, actionCodeSettings?: ActionCodeSettings): Promise<string>;
+    /**
+     * Generates an out-of-band email action link to verify the user's ownership
+     * of the specified email. The {@link ActionCodeSettings} object provided
+     * as an argument to this method defines whether the link is to be handled by a
+     * mobile app or browser along with additional state information to be passed in
+     * the deep link, etc.
+     *
+     * @param email - The current email account.
+     * @param newEmail - The email address the account is being updated to.
+     * @param actionCodeSettings - The action
+     *     code settings. If specified, the state/continue URL is set as the
+     *     "continueUrl" parameter in the email verification link. The default email
+     *     verification landing page will use this to display a link to go back to
+     *     the app if it is installed.
+     *     If the actionCodeSettings is not specified, no URL is appended to the
+     *     action URL.
+     *     The state URL provided must belong to a domain that is authorized
+     *     in the console, or an error will be thrown.
+     *     Mobile app redirects are only applicable if the developer configures
+     *     and accepts the Firebase Dynamic Links terms of service.
+     *     The Android package name and iOS bundle ID are respected only if they
+     *     are configured in the same Firebase Auth project.
+     * @returns A promise that resolves with the generated link.
+     */
+    generateVerifyAndChangeEmailLink(email: string, newEmail: string, actionCodeSettings?: ActionCodeSettings): Promise<string>;
+    /**
+     * Generates the out of band email action link to verify the user's ownership
+     * of the specified email. The {@link ActionCodeSettings} object provided
+     * as an argument to this method defines whether the link is to be handled by a
+     * mobile app or browser along with additional state information to be passed in
+     * the deep link, etc.
+     *
+     * @example
+     * ```javascript
+     * var actionCodeSettings = {
+     *   url: 'https://www.example.com/cart?email=user@example.com&cartId=123',
+     *   iOS: {
+     *     bundleId: 'com.example.ios'
+     *   },
+     *   android: {
+     *     packageName: 'com.example.android',
+     *     installApp: true,
+     *     minimumVersion: '12'
+     *   },
+     *   handleCodeInApp: true,
+     *   linkDomain: 'project-id.firebaseapp.com'
+     * };
+     * admin.auth()
+     *     .generateEmailVerificationLink('user@example.com', actionCodeSettings)
+     *     .then(function(link) {
+     *       // The link was successfully generated.
+     *     })
+     *     .catch(function(error) {
+     *       // Some error occurred, you can inspect the code: error.code
+     *     });
+     * ```
+     *
+     * @param email - The email account to verify.
+     * @param actionCodeSettings - The action
+     *     code settings. If specified, the state/continue URL is set as the
+     *     "continueUrl" parameter in the email verification link. The default email
+     *     verification landing page will use this to display a link to go back to
+     *     the app if it is installed.
+     *     If the actionCodeSettings is not specified, no URL is appended to the
+     *     action URL.
+     *     The state URL provided must belong to a domain that is whitelisted by the
+     *     developer in the console. Otherwise an error is thrown.
+     *     Mobile app redirects are only applicable if the developer configures
+     *     and accepts the Firebase Dynamic Links terms of service.
+     *     The Android package name and iOS bundle ID are respected only if they
+     *     are configured in the same Firebase Auth project.
+     * @returns A promise that resolves with the generated link.
+     */
+    generateSignInWithEmailLink(email: string, actionCodeSettings: ActionCodeSettings): Promise<string>;
+    /**
+     * Returns the list of existing provider configurations matching the filter
+     * provided. At most, 100 provider configs can be listed at a time.
+     *
+     * SAML and OIDC provider support requires Google Cloud's Identity Platform
+     * (GCIP). To learn more about GCIP, including pricing and features,
+     * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}.
+     *
+     * @param options - The provider config filter to apply.
+     * @returns A promise that resolves with the list of provider configs meeting the
+     *   filter requirements.
+     */
+    listProviderConfigs(options: AuthProviderConfigFilter): Promise<ListProviderConfigResults>;
+    /**
+     * Looks up an Auth provider configuration by the provided ID.
+     * Returns a promise that resolves with the provider configuration
+     * corresponding to the provider ID specified. If the specified ID does not
+     * exist, an `auth/configuration-not-found` error is thrown.
+     *
+     * SAML and OIDC provider support requires Google Cloud's Identity Platform
+     * (GCIP). To learn more about GCIP, including pricing and features,
+     * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}.
+     *
+     * @param providerId - The provider ID corresponding to the provider
+     *     config to return.
+     * @returns A promise that resolves
+     *     with the configuration corresponding to the provided ID.
+     */
+    getProviderConfig(providerId: string): Promise<AuthProviderConfig>;
+    /**
+     * Deletes the provider configuration corresponding to the provider ID passed.
+     * If the specified ID does not exist, an `auth/configuration-not-found` error
+     * is thrown.
+     *
+     * SAML and OIDC provider support requires Google Cloud's Identity Platform
+     * (GCIP). To learn more about GCIP, including pricing and features,
+     * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}.
+     *
+     * @param providerId - The provider ID corresponding to the provider
+     *     config to delete.
+     * @returns A promise that resolves on completion.
+     */
+    deleteProviderConfig(providerId: string): Promise<void>;
+    /**
+     * Returns a promise that resolves with the updated `AuthProviderConfig`
+     * corresponding to the provider ID specified.
+     * If the specified ID does not exist, an `auth/configuration-not-found` error
+     * is thrown.
+     *
+     * SAML and OIDC provider support requires Google Cloud's Identity Platform
+     * (GCIP). To learn more about GCIP, including pricing and features,
+     * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}.
+     *
+     * @param providerId - The provider ID corresponding to the provider
+     *     config to update.
+     * @param updatedConfig - The updated configuration.
+     * @returns A promise that resolves with the updated provider configuration.
+     */
+    updateProviderConfig(providerId: string, updatedConfig: UpdateAuthProviderRequest): Promise<AuthProviderConfig>;
+    /**
+     * Returns a promise that resolves with the newly created `AuthProviderConfig`
+     * when the new provider configuration is created.
+     *
+     * SAML and OIDC provider support requires Google Cloud's Identity Platform
+     * (GCIP). To learn more about GCIP, including pricing and features,
+     * see the {@link https://cloud.google.com/identity-platform | GCIP documentation}.
+     *
+     * @param config - The provider configuration to create.
+     * @returns A promise that resolves with the created provider configuration.
+     */
+    createProviderConfig(config: AuthProviderConfig): Promise<AuthProviderConfig>;
     /**
      * Gets an OAuth2 access token from Google's OAuth2 server. This token is
      * required for accessing the Firebase Auth REST API via fetch requests.