@quatrain/auth-firebase 1.2.2 → 1.2.4

package/dist/FirebaseAuthAdapter.d.ts

@@ -1,7 +1,25 @@
 import { User } from '@quatrain/backend';
 import { AbstractAuthAdapter, AuthParameters } from '@quatrain/auth';
+import { ApiMiddleware } from '@quatrain/api';
 import { UpdateRequest } from 'firebase-admin/auth';
+/**
+ * Authentication adapter implementing the Google Firebase Auth ecosystem.
+ * Handles server-side validation of JWTs and admin functions via `firebase-admin`.
+ */
 export declare class FirebaseAuthAdapter extends AbstractAuthAdapter {
+    /**
+     * Bootstraps the adapter using Firebase credentials.
+     *
+     * @param config - Firebase admin SDK configuration block.
+     * @returns The adapter instance.
+     */
+    static factory(config: any): FirebaseAuthAdapter;
+    /**
+     * Express middleware that intercepts and verifies incoming Firebase JWT Bearer tokens.
+     *
+     * @returns The validation middleware function.
+     */
+    middleware(): ApiMiddleware;
     constructor(params?: AuthParameters);
     /**
      * Register new user in authentication
@@ -9,12 +27,58 @@ export declare class FirebaseAuthAdapter extends AbstractAuthAdapter {
      * @returns user unique id
      */
     register(user: User, clearPassword?: string): Promise<string>;
+    /**
+     * Verifies a Firebase ID token using the admin SDK.
+     *
+     * @param bearer - The JWT token string.
+     * @returns A promise resolving to the decoded token object.
+     */
     getAuthToken(bearer: string): Promise<import("firebase-admin/auth").DecodedIdToken>;
+    /**
+     * User authentication flow (Not natively supported on Firebase Admin Server SDK).
+     * Usually handled on the client.
+     *
+     * @param login - Email address.
+     * @param password - Plain password.
+     */
     signup(login: string, password: string): Promise<void>;
+    /**
+     * Signs out the user (No-op in server-side stateless Firebase admin).
+     *
+     * @param user - Target user.
+     */
     signout(user: User): Promise<any>;
+    /**
+     * Modifies an existing user's attributes in the Firebase Auth registry.
+     *
+     * @param user - Target user.
+     * @param updatable - Properties to modify (e.g. displayName, disabled status).
+     */
     update(user: User, updatable: UpdateRequest): Promise<any>;
+    /**
+     * Completely removes a user from the Firebase Auth registry.
+     *
+     * @param user - Target user.
+     */
     delete(user: User): Promise<any>;
+    /**
+     * Revokes a specific access token.
+     *
+     * @param token - The token string.
+     */
     revokeAuthToken(token: string): Promise<void>;
+    /**
+     * Updates the custom JWT claims embedded in a user's Firebase token.
+     *
+     * @param id - User UID.
+     * @param claims - Claims dictionary.
+     */
     setCustomUserClaims(id: string, claims: any): Promise<void>;
+    /**
+     * Requests a new ID token using a refresh token via Google Secure Token API.
+     *
+     * @param refreshToken - The active refresh token.
+     * @returns The generated token payload.
+     */
     refreshToken(refreshToken: string): Promise<any>;
 }

package/dist/FirebaseAuthAdapter.js

@@ -47,10 +47,48 @@ const auth_1 = require("@quatrain/auth");
 const auth_2 = require("firebase-admin/auth");
 const app_1 = require("firebase-admin/app");
 const nativeFetch = __importStar(require("node-fetch-native"));
+/**
+ * Authentication adapter implementing the Google Firebase Auth ecosystem.
+ * Handles server-side validation of JWTs and admin functions via `firebase-admin`.
+ */
 class FirebaseAuthAdapter extends auth_1.AbstractAuthAdapter {
+    /**
+     * Bootstraps the adapter using Firebase credentials.
+     *
+     * @param config - Firebase admin SDK configuration block.
+     * @returns The adapter instance.
+     */
+    static factory(config) {
+        return new FirebaseAuthAdapter({ config });
+    }
+    /**
+     * Express middleware that intercepts and verifies incoming Firebase JWT Bearer tokens.
+     *
+     * @returns The validation middleware function.
+     */
+    middleware() {
+        return (req, res) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const bearer = (((_a = req.headers) === null || _a === void 0 ? void 0 : _a.authorization) || '').split(' ')[1] || '';
+            if (bearer) {
+                try {
+                    const user = yield this.getAuthToken(bearer);
+                    if (user) {
+                        return true; // Authorized
+                    }
+                }
+                catch (e) {
+                    auth_1.Auth.error(`[FirebaseAuthAdapter] Middleware token verification failed: ${e.message}`);
+                }
+            }
+            res.setHeader('WWW-Authenticate', 'Bearer realm="Core API"');
+            res.status(401).send('Authentication required.');
+            return false;
+        });
+    }
     constructor(params = {}) {
         super(params);
-        if ((0, app_1.getApps)().length === 0) {
+        if ((0, app_1.getApps)().length === 0 && params.config) {
             (0, app_1.initializeApp)(params.config);
         }
     }
@@ -80,17 +118,41 @@ class FirebaseAuthAdapter extends auth_1.AbstractAuthAdapter {
             }
         });
     }
+    /**
+     * Verifies a Firebase ID token using the admin SDK.
+     *
+     * @param bearer - The JWT token string.
+     * @returns A promise resolving to the decoded token object.
+     */
     getAuthToken(bearer) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield (0, auth_2.getAuth)().verifyIdToken(bearer);
         });
     }
+    /**
+     * User authentication flow (Not natively supported on Firebase Admin Server SDK).
+     * Usually handled on the client.
+     *
+     * @param login - Email address.
+     * @param password - Plain password.
+     */
     signup(login, password) {
         return __awaiter(this, void 0, void 0, function* () { });
     }
+    /**
+     * Signs out the user (No-op in server-side stateless Firebase admin).
+     *
+     * @param user - Target user.
+     */
     signout(user) {
         return __awaiter(this, void 0, void 0, function* () { });
     }
+    /**
+     * Modifies an existing user's attributes in the Firebase Auth registry.
+     *
+     * @param user - Target user.
+     * @param updatable - Properties to modify (e.g. displayName, disabled status).
+     */
     update(user, updatable) {
         return __awaiter(this, void 0, void 0, function* () {
             auth_1.Auth.log('auth data to update', JSON.stringify(updatable));
@@ -103,17 +165,39 @@ class FirebaseAuthAdapter extends auth_1.AbstractAuthAdapter {
             catch (e) { }
         });
     }
+    /**
+     * Completely removes a user from the Firebase Auth registry.
+     *
+     * @param user - Target user.
+     */
     delete(user) {
         return __awaiter(this, void 0, void 0, function* () {
             return yield (0, auth_2.getAuth)().deleteUser(user.uid);
         });
     }
+    /**
+     * Revokes a specific access token.
+     *
+     * @param token - The token string.
+     */
     revokeAuthToken(token) {
         return __awaiter(this, void 0, void 0, function* () { });
     }
+    /**
+     * Updates the custom JWT claims embedded in a user's Firebase token.
+     *
+     * @param id - User UID.
+     * @param claims - Claims dictionary.
+     */
     setCustomUserClaims(id, claims) {
         return __awaiter(this, void 0, void 0, function* () { });
     }
+    /**
+     * Requests a new ID token using a refresh token via Google Secure Token API.
+     *
+     * @param refreshToken - The active refresh token.
+     * @returns The generated token payload.
+     */
     refreshToken(refreshToken) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this._params.config.apiKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/auth-firebase",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "license": "AGPL-3.0-only",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,8 +22,9 @@
     "@quatrain/core": "^1.2.5"
   },
   "dependencies": {
-    "@quatrain/auth": "^1.2.1",
-    "@quatrain/backend": "^1.2.5",
+    "@quatrain/api": "^1.1.5",
+    "@quatrain/auth": "^1.2.2",
+    "@quatrain/backend": "^1.2.6",
     "@quatrain/core": "^1.2.5",
     "firebase-admin": "^13.0.1",
     "node-fetch-native": "^1.6.4"

package/src/FirebaseAuthAdapter.ts

@@ -5,14 +5,55 @@ import {
    AuthenticationError,
    AuthParameters,
 } from '@quatrain/auth'
+import { ApiMiddleware, ApiRequest, ApiResponse } from '@quatrain/api'
 import { CreateRequest, UpdateRequest, getAuth } from 'firebase-admin/auth'
 import { getApps, initializeApp } from 'firebase-admin/app'
 import * as nativeFetch from 'node-fetch-native'
 
+/**
+ * Authentication adapter implementing the Google Firebase Auth ecosystem.
+ * Handles server-side validation of JWTs and admin functions via `firebase-admin`.
+ */
 export class FirebaseAuthAdapter extends AbstractAuthAdapter {
+   /**
+    * Bootstraps the adapter using Firebase credentials.
+    * 
+    * @param config - Firebase admin SDK configuration block.
+    * @returns The adapter instance.
+    */
+   static factory(config: any): FirebaseAuthAdapter {
+      return new FirebaseAuthAdapter({ config })
+   }
+
+   /**
+    * Express middleware that intercepts and verifies incoming Firebase JWT Bearer tokens.
+    * 
+    * @returns The validation middleware function.
+    */
+   public middleware(): ApiMiddleware {
+      return async (req: ApiRequest, res: ApiResponse): Promise<boolean> => {
+         const bearer = ((req.headers?.authorization as string) || '').split(' ')[1] || ''
+         
+         if (bearer) {
+            try {
+               const user = await this.getAuthToken(bearer)
+               if (user) {
+                  return true // Authorized
+               }
+            } catch(e) {
+               Auth.error(`[FirebaseAuthAdapter] Middleware token verification failed: ${(e as Error).message}`)
+            }
+         }
+
+         res.setHeader('WWW-Authenticate', 'Bearer realm="Core API"')
+         res.status(401).send('Authentication required.')
+         return false
+      }
+   }
+
    constructor(params: AuthParameters = {}) {
       super(params)
-      if (getApps().length === 0) {
+      if (getApps().length === 0 && params.config) {
          initializeApp(params.config)
       }
    }
@@ -48,14 +89,38 @@ export class FirebaseAuthAdapter extends AbstractAuthAdapter {
       }
    }
 
+   /**
+    * Verifies a Firebase ID token using the admin SDK.
+    * 
+    * @param bearer - The JWT token string.
+    * @returns A promise resolving to the decoded token object.
+    */
    async getAuthToken(bearer: string) {
       return await getAuth().verifyIdToken(bearer)
    }
 
+   /**
+    * User authentication flow (Not natively supported on Firebase Admin Server SDK).
+    * Usually handled on the client.
+    * 
+    * @param login - Email address.
+    * @param password - Plain password.
+    */
    async signup(login: string, password: string) {}
 
+   /**
+    * Signs out the user (No-op in server-side stateless Firebase admin).
+    * 
+    * @param user - Target user.
+    */
    async signout(user: User): Promise<any> {}
 
+   /**
+    * Modifies an existing user's attributes in the Firebase Auth registry.
+    * 
+    * @param user - Target user.
+    * @param updatable - Properties to modify (e.g. displayName, disabled status).
+    */
    async update(user: User, updatable: UpdateRequest): Promise<any> {
       Auth.log('auth data to update', JSON.stringify(updatable))
 
@@ -67,14 +132,36 @@ export class FirebaseAuthAdapter extends AbstractAuthAdapter {
       } catch (e) {}
    }
 
+   /**
+    * Completely removes a user from the Firebase Auth registry.
+    * 
+    * @param user - Target user.
+    */
    async delete(user: User): Promise<any> {
       return await getAuth().deleteUser(user.uid)
    }
 
+   /**
+    * Revokes a specific access token.
+    * 
+    * @param token - The token string.
+    */
    async revokeAuthToken(token: string) {}
 
+   /**
+    * Updates the custom JWT claims embedded in a user's Firebase token.
+    * 
+    * @param id - User UID.
+    * @param claims - Claims dictionary.
+    */
    async setCustomUserClaims(id: string, claims: any) {}
 
+   /**
+    * Requests a new ID token using a refresh token via Google Secure Token API.
+    * 
+    * @param refreshToken - The active refresh token.
+    * @returns The generated token payload.
+    */
    async refreshToken(refreshToken: string): Promise<any> {
       if (!this._params.config.apiKey) {
          Auth.warn(`Can't get refresh token, no API key provided`)