added createSessionCookie

Author: Code-Hex

package.json

@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "test": "vitest run",
+    "test-with-emulator": "firebase emulators:exec --project example-project12345 'vitest run'",
     "build": "run-p build:*",
     "build:main": "tsc -p tsconfig.main.json",
     "build:module": "tsc -p tsconfig.module.json",
@@ -40,6 +41,7 @@
     "npm-run-all": "^4.1.5",
     "prettier": "^3.2.5",
     "typescript": "^5.3.3",
+    "undici": "^6.6.2",
     "vitest": "^1.3.0",
     "wrangler": "^3.28.3"
   },

pnpm-lock.yaml

@@ -0,0 +1,69 @@
+/** Http method type definition. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD';
+/** API callback function type definition. */
+export type ApiCallbackFunction = (data: object) => void;
+
+/**
+ * Class that defines all the settings for the backend API endpoint.
+ *
+ * @param endpoint - The Firebase Auth backend endpoint.
+ * @param httpMethod - The http method for that endpoint.
+ * @constructor
+ */
+export class ApiSettings {
+  private requestValidator: ApiCallbackFunction;
+  private responseValidator: ApiCallbackFunction;
+
+  constructor(
+    private version: 'v1' | 'v2',
+    private endpoint: string,
+    private httpMethod: HttpMethod = 'POST'
+  ) {
+    this.setRequestValidator(null).setResponseValidator(null);
+  }
+
+  /** @returns The backend API resource version. */
+  public getVersion(): 'v1' | 'v2' {
+    return this.version;
+  }
+
+  /** @returns The backend API endpoint. */
+  public getEndpoint(): string {
+    return this.endpoint;
+  }
+
+  /** @returns The request HTTP method. */
+  public getHttpMethod(): HttpMethod {
+    return this.httpMethod;
+  }
+
+  /**
+   * @param requestValidator - The request validator.
+   * @returns The current API settings instance.
+   */
+  public setRequestValidator(requestValidator: ApiCallbackFunction | null): ApiSettings {
+    const nullFunction: ApiCallbackFunction = () => undefined;
+    this.requestValidator = requestValidator || nullFunction;
+    return this;
+  }
+
+  /** @returns The request validator. */
+  public getRequestValidator(): ApiCallbackFunction {
+    return this.requestValidator;
+  }
+
+  /**
+   * @param responseValidator - The response validator.
+   * @returns The current API settings instance.
+   */
+  public setResponseValidator(responseValidator: ApiCallbackFunction | null): ApiSettings {
+    const nullFunction: ApiCallbackFunction = () => undefined;
+    this.responseValidator = responseValidator || nullFunction;
+    return this;
+  }
+
+  /** @returns The response validator. */
+  public getResponseValidator(): ApiCallbackFunction {
+    return this.responseValidator;
+  }
+}

src/api-requests.ts

@@ -0,0 +1,64 @@
+import { ApiSettings } from './api-requests';
+import { BaseClient } from './client';
+import type { EmulatorEnv } from './emulator';
+import { AuthClientErrorCode, FirebaseAuthError } from './errors';
+import { isNonEmptyString, isNumber } from './validator';
+
+/** Minimum allowed session cookie duration in seconds (5 minutes). */
+const MIN_SESSION_COOKIE_DURATION_SECS = 5 * 60;
+
+/** Maximum allowed session cookie duration in seconds (2 weeks). */
+const MAX_SESSION_COOKIE_DURATION_SECS = 14 * 24 * 60 * 60;
+
+/**
+ * Instantiates the createSessionCookie endpoint settings.
+ *
+ * @internal
+ */
+export const FIREBASE_AUTH_CREATE_SESSION_COOKIE = new ApiSettings('v1', ':createSessionCookie', 'POST')
+  // Set request validator.
+  .setRequestValidator((request: any) => {
+    // Validate the ID token is a non-empty string.
+    if (!isNonEmptyString(request.idToken)) {
+      throw new FirebaseAuthError(AuthClientErrorCode.INVALID_ID_TOKEN);
+    }
+    // Validate the custom session cookie duration.
+    if (
+      !isNumber(request.validDuration) ||
+      request.validDuration < MIN_SESSION_COOKIE_DURATION_SECS ||
+      request.validDuration > MAX_SESSION_COOKIE_DURATION_SECS
+    ) {
+      throw new FirebaseAuthError(AuthClientErrorCode.INVALID_SESSION_COOKIE_DURATION);
+    }
+  })
+  // Set response validator.
+  .setResponseValidator((response: any) => {
+    // Response should always contain the session cookie.
+    if (!isNonEmptyString(response.sessionCookie)) {
+      throw new FirebaseAuthError(AuthClientErrorCode.INTERNAL_ERROR);
+    }
+  });
+
+export class AuthApiClient extends BaseClient {
+  /**
+   * Creates a new Firebase session cookie with the specified duration that can be used for
+   * session management (set as a server side session cookie with custom cookie policy).
+   * The session cookie JWT will have the same payload claims as the provided ID token.
+   *
+   * @param idToken - The Firebase ID token to exchange for a session cookie.
+   * @param expiresIn - The session cookie duration in milliseconds.
+   * @param - An optional parameter specifying the environment in which the function is running.
+   *   If the function is running in an emulator environment, this should be set to `EmulatorEnv`.
+   *   If not specified, the function will assume it is running in a production environment.
+   *
+   * @returns A promise that resolves on success with the created session cookie.
+   */
+  public async createSessionCookie(idToken: string, expiresIn: number, env?: EmulatorEnv): Promise<string> {
+    const request = {
+      idToken,
+      // Convert to seconds.
+      validDuration: expiresIn / 1000,
+    };
+    return await this.fetch(FIREBASE_AUTH_CREATE_SESSION_COOKIE, request, env);
+  }
+}

src/auth-api-requests.ts

@@ -1,17 +1,22 @@
+import { AuthApiClient } from './auth-api-requests';
 import type { EmulatorEnv } from './emulator';
 import { useEmulator } from './emulator';
+import { AuthClientErrorCode, FirebaseAuthError } from './errors';
 import type { KeyStorer } from './key-store';
 import type { FirebaseIdToken, FirebaseTokenVerifier } from './token-verifier';
 import { createIdTokenVerifier, createSessionCookieVerifier } from './token-verifier';
+import { isNonNullObject, isNumber } from './validator';
 
 export class BaseAuth {
   /** @internal */
   protected readonly idTokenVerifier: FirebaseTokenVerifier;
   protected readonly sessionCookieVerifier: FirebaseTokenVerifier;
+  private readonly authApiClient: AuthApiClient;
 
   constructor(projectId: string, keyStore: KeyStorer) {
     this.idTokenVerifier = createIdTokenVerifier(projectId, keyStore);
     this.sessionCookieVerifier = createSessionCookieVerifier(projectId, keyStore);
+    this.authApiClient = new AuthApiClient(projectId);
   }
 
   /**
@@ -31,6 +36,38 @@ export class BaseAuth {
     return this.idTokenVerifier.verifyJWT(idToken, isEmulator);
   }
 
+  /**
+   * 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.
+   * @param env - An optional parameter specifying the environment in which the function is running.
+   *   If the function is running in an emulator environment, this should be set to `EmulatorEnv`.
+   *   If not specified, the function will assume it is running in a production environment.
+   *
+   * @returns A promise that resolves on success with the
+   *   created session cookie.
+   */
+  public createSessionCookie(
+    idToken: string,
+    sessionCookieOptions: SessionCookieOptions,
+    env?: EmulatorEnv
+  ): Promise<string> {
+    // Return rejected promise if expiresIn is not available.
+    if (!isNonNullObject(sessionCookieOptions) || !isNumber(sessionCookieOptions.expiresIn)) {
+      return Promise.reject(new FirebaseAuthError(AuthClientErrorCode.INVALID_SESSION_COOKIE_DURATION));
+    }
+    return this.authApiClient.createSessionCookie(idToken, sessionCookieOptions.expiresIn, env);
+  }
+
   /**
    * Verifies a Firebase session cookie. Returns a Promise with the cookie claims.
    * Rejects the promise if the cookie could not be verified.
@@ -47,6 +84,9 @@ export class BaseAuth {
    * for code samples and detailed documentation
    *
    * @param sessionCookie - The session cookie to verify.
+   * @param env - An optional parameter specifying the environment in which the function is running.
+   *   If the function is running in an emulator environment, this should be set to `EmulatorEnv`.
+   *   If not specified, the function will assume it is running in a production environment.
    *
    * @returns A promise fulfilled with the
    *   session cookie's decoded claims if the session cookie is valid; otherwise,
@@ -57,3 +97,15 @@ export class BaseAuth {
     return this.sessionCookieVerifier.verifyJWT(sessionCookie, isEmulator);
   }
 }
+
+/**
+ * Interface representing the session cookie options needed for the
+ * {@link BaseAuth.createSessionCookie} method.
+ */
+export interface SessionCookieOptions {
+  /**
+   * The session cookie custom expiration in milliseconds. The minimum allowed is
+   * 5 minutes and the maxium allowed is 2 weeks.
+   */
+  expiresIn: number;
+}