@quatrain/auth 1.2.1 → 1.2.2

package/dist/AbstractAuthAdapter.d.ts

@@ -1,22 +1,98 @@
 import { AuthParameters, AuthParametersKeys } from './Auth';
 import { User } from '@quatrain/backend';
 import { AuthInterface } from './types/AuthInterface';
+/**
+ * Abstract base class that defines the contract for all authentication adapters.
+ * Implementations should adapt standard authentication methods to specific providers
+ * (e.g. Firebase, Supabase, basic auth).
+ */
 export declare abstract class AbstractAuthAdapter implements AuthInterface {
+    /** The `User` class reference to be used by the adapter. */
     static UserClass: typeof User;
     protected _alias: string;
     protected _params: AuthParameters;
     constructor(params?: AuthParameters);
+    /**
+     * Assigns a configuration parameter for the adapter.
+     *
+     * @param key - The parameter key.
+     * @param value - The parameter value.
+     */
     setParam(key: AuthParametersKeys, value: any): void;
+    /**
+     * Retrieves a configuration parameter.
+     *
+     * @param key - The parameter key to fetch.
+     * @returns The corresponding configuration value.
+     */
     getParam(key: AuthParametersKeys): any;
     set alias(alias: string);
     get alias(): string;
+    /**
+     * Registers a new user directly in the authentication provider.
+     *
+     * @param user - The User object.
+     * @param clearPassword - The plaintext password.
+     * @returns A promise resolving to the registration response.
+     */
     abstract register(user: User, clearPassword?: string): Promise<any>;
+    /**
+     * Authenticates a user by login and password (generates tokens).
+     *
+     * @param login - User's email or login name.
+     * @param password - Plaintext password.
+     * @returns A promise resolving to the token payload.
+     */
     abstract signup(login: string, password: string): Promise<any>;
+    /**
+     * Terminates the current authentication session.
+     *
+     * @param user - The User footprint.
+     * @returns A promise resolving to the provider's signout response.
+     */
     abstract signout(user: User): Promise<any>;
+    /**
+     * Updates user credentials or metadata within the external auth provider.
+     *
+     * @param user - The User to modify.
+     * @param updatable - The delta payload of properties to update.
+     * @returns A promise resolving when the update completes.
+     */
     abstract update(user: User, updatable: any): Promise<any>;
+    /**
+     * Hard-deletes a user from the authentication provider.
+     *
+     * @param user - The User to delete.
+     * @returns A promise resolving on successful deletion.
+     */
     abstract delete(user: User): Promise<any>;
+    /**
+     * Validates and decodes an incoming authentication token.
+     *
+     * @param token - The raw token string (e.g. JWT).
+     * @returns The decoded token data payload.
+     */
     abstract getAuthToken(token: string): any;
+    /**
+     * Refreshes an expired access token using a valid refresh token.
+     *
+     * @param refreshToken - The refresh token string.
+     * @returns A promise resolving to the new access token payload.
+     */
     abstract refreshToken(refreshToken: string): Promise<any>;
+    /**
+     * Invalidates a specific access token explicitly.
+     *
+     * @param token - The token string to revoke.
+     * @returns Action response from the provider.
+     */
     abstract revokeAuthToken(token: string): any;
+    /**
+     * Injects custom claims (e.g. role, tenant info) into the user's token structure.
+     *
+     * @param id - The user ID.
+     * @param claims - The payload of claims to merge.
+     * @returns Action response from the provider.
+     */
     abstract setCustomUserClaims(id: string, claims: any): any;
 }

package/dist/AbstractAuthAdapter.js

@@ -2,15 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AbstractAuthAdapter = void 0;
 const backend_1 = require("@quatrain/backend");
+/**
+ * Abstract base class that defines the contract for all authentication adapters.
+ * Implementations should adapt standard authentication methods to specific providers
+ * (e.g. Firebase, Supabase, basic auth).
+ */
 class AbstractAuthAdapter {
     constructor(params = {}) {
         this._alias = '';
         this._params = {};
         this._params = params;
     }
+    /**
+     * Assigns a configuration parameter for the adapter.
+     *
+     * @param key - The parameter key.
+     * @param value - The parameter value.
+     */
     setParam(key, value) {
         this._params[key] = value;
     }
+    /**
+     * Retrieves a configuration parameter.
+     *
+     * @param key - The parameter key to fetch.
+     * @returns The corresponding configuration value.
+     */
     getParam(key) {
         return this._params[key];
     }
@@ -22,4 +39,5 @@ class AbstractAuthAdapter {
     }
 }
 exports.AbstractAuthAdapter = AbstractAuthAdapter;
+/** The `User` class reference to be used by the adapter. */
 AbstractAuthAdapter.UserClass = backend_1.User;

package/dist/Auth.d.ts

@@ -26,11 +26,32 @@ export interface AuthAdapter extends AbstractAuthAdapter {
 export type AuthRegistry<T extends AbstractAuthAdapter> = {
     [x: string]: T;
 };
+/**
+ * Global authentication manager handling registration and retrieval
+ * of diverse Auth providers (adapters) via an alias registry.
+ */
 export declare class Auth extends Core {
+    /** The fallback provider alias. */
     static defaultProvider: string;
+    /** Core logger dedicated to Auth actions. */
     static logger: any;
+    /** Standardized error message for duplicate email constraint violations. */
     static ERROR_EMAIL_EXISTS: string;
     protected static _providers: AuthRegistry<any>;
+    /**
+     * Registers a configured auth provider into the global context.
+     *
+     * @param provider - Instantiated auth adapter.
+     * @param alias - Short identifier name.
+     * @param setDefault - If true, marks this adapter as the fallback provider.
+     */
     static addProvider(provider: AbstractAuthAdapter, alias: string, setDefault?: boolean): void;
+    /**
+     * Fetches a registered provider by its alias.
+     *
+     * @param alias - Requested provider identifier. Defaults to `defaultProvider`.
+     * @returns The corresponding auth adapter.
+     * @throws {Error} If the specified alias is unknown.
+     */
     static getProvider<T extends AbstractAuthAdapter>(alias?: string): T;
 }

package/dist/Auth.js

@@ -9,13 +9,31 @@ var AuthAction;
     AuthAction["SIGNUP"] = "signup";
     AuthAction["SIGNOUT"] = "signout";
 })(AuthAction || (exports.AuthAction = AuthAction = {}));
+/**
+ * Global authentication manager handling registration and retrieval
+ * of diverse Auth providers (adapters) via an alias registry.
+ */
 class Auth extends core_1.Core {
+    /**
+     * Registers a configured auth provider into the global context.
+     *
+     * @param provider - Instantiated auth adapter.
+     * @param alias - Short identifier name.
+     * @param setDefault - If true, marks this adapter as the fallback provider.
+     */
     static addProvider(provider, alias, setDefault = false) {
         this._providers[alias] = provider;
         if (setDefault) {
             this.defaultProvider = alias;
         }
     }
+    /**
+     * Fetches a registered provider by its alias.
+     *
+     * @param alias - Requested provider identifier. Defaults to `defaultProvider`.
+     * @returns The corresponding auth adapter.
+     * @throws {Error} If the specified alias is unknown.
+     */
     static getProvider(alias = this.defaultProvider) {
         if (this._providers[alias]) {
             return this._providers[alias];
@@ -27,7 +45,10 @@ class Auth extends core_1.Core {
 }
 exports.Auth = Auth;
 _a = Auth;
+/** The fallback provider alias. */
 Auth.defaultProvider = 'default';
+/** Core logger dedicated to Auth actions. */
 Auth.logger = _a.addLogger('Auth');
+/** Standardized error message for duplicate email constraint violations. */
 Auth.ERROR_EMAIL_EXISTS = `User email already exists`;
 Auth._providers = {};

package/dist/AuthenticationError.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Standard exception representing authentication failures, invalid credentials,
+ * or token expiration events.
+ */
 export declare class AuthenticationError extends Error {
 }

package/dist/AuthenticationError.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthenticationError = void 0;
+/**
+ * Standard exception representing authentication failures, invalid credentials,
+ * or token expiration events.
+ */
 class AuthenticationError extends Error {
 }
 exports.AuthenticationError = AuthenticationError;

package/dist/MockAuthAdapter.d.ts

@@ -9,16 +9,76 @@ export declare class MockAuthAdapter extends AbstractAuthAdapter {
     private tokens;
     private refreshTokens;
     constructor(params?: AuthParameters);
+    /**
+     * Mock registration. Stores the user in memory mapped by email.
+     *
+     * @param user - Target user.
+     * @param clearPassword - Ignored in mock context.
+     * @returns A mock success promise.
+     */
     register(user: User, clearPassword?: string): Promise<any>;
+    /**
+     * Mock signup. Generates mock JWT tokens assuming the login is valid.
+     *
+     * @param login - Mock user identifier.
+     * @param password - Mock password.
+     * @returns Emulated auth response payload.
+     */
     signup(login: string, password: string): Promise<any>;
+    /**
+     * Deletes active tokens tied to the provided mock user.
+     *
+     * @param user - User instance to sign out.
+     */
     signout(user: User): Promise<any>;
+    /**
+     * Mock user state update in memory.
+     *
+     * @param user - Target user.
+     * @param updatable - Property modifications.
+     */
     update(user: User, updatable: any): Promise<any>;
+    /**
+     * Evicts the user and all associated mock tokens from memory.
+     *
+     * @param user - User instance to delete.
+     */
     delete(user: User): Promise<any>;
+    /**
+     * Reads the cached token data payload.
+     *
+     * @param token - Raw mock token string.
+     */
     getAuthToken(token: string): any;
+    /**
+     * Cycles an old refresh token for a completely new session pair.
+     *
+     * @param refreshToken - Active mock refresh token string.
+     */
     refreshToken(refreshToken: string): Promise<any>;
+    /**
+     * Blacklists a specific access token.
+     *
+     * @param token - Target mock token to drop.
+     */
     revokeAuthToken(token: string): any;
+    /**
+     * Manually appends structural role claims onto a registered mock user.
+     *
+     * @param id - Mock user ID.
+     * @param claims - Payload to merge.
+     */
     setCustomUserClaims(id: string, claims: any): any;
+    /**
+     * Test utility: Flushes all internal registers.
+     */
     clearAll(): void;
+    /**
+     * Test utility: Retrieves user instance by its stored key (email).
+     */
     getUserByEmail(email: string): User | undefined;
+    /**
+     * Test utility: Asserts the existence of an active token.
+     */
     hasToken(token: string): boolean;
 }

package/dist/MockAuthAdapter.js

@@ -21,6 +21,13 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
         this.tokens = new Map();
         this.refreshTokens = new Map();
     }
+    /**
+     * Mock registration. Stores the user in memory mapped by email.
+     *
+     * @param user - Target user.
+     * @param clearPassword - Ignored in mock context.
+     * @returns A mock success promise.
+     */
     register(user, clearPassword) {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.registeredUsers.has(user._.email)) {
@@ -30,6 +37,13 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
             return { success: true, user };
         });
     }
+    /**
+     * Mock signup. Generates mock JWT tokens assuming the login is valid.
+     *
+     * @param login - Mock user identifier.
+     * @param password - Mock password.
+     * @returns Emulated auth response payload.
+     */
     signup(login, password) {
         return __awaiter(this, void 0, void 0, function* () {
             const user = this.registeredUsers.get(login);
@@ -48,6 +62,11 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
             };
         });
     }
+    /**
+     * Deletes active tokens tied to the provided mock user.
+     *
+     * @param user - User instance to sign out.
+     */
     signout(user) {
         return __awaiter(this, void 0, void 0, function* () {
             // Remove all tokens associated with this user
@@ -59,6 +78,12 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
             return { success: true };
         });
     }
+    /**
+     * Mock user state update in memory.
+     *
+     * @param user - Target user.
+     * @param updatable - Property modifications.
+     */
     update(user, updatable) {
         return __awaiter(this, void 0, void 0, function* () {
             const existingUser = this.registeredUsers.get(user._.email);
@@ -70,6 +95,11 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
             return { success: true, user: updatedUser };
         });
     }
+    /**
+     * Evicts the user and all associated mock tokens from memory.
+     *
+     * @param user - User instance to delete.
+     */
     delete(user) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.registeredUsers.has(user._.email)) {
@@ -80,6 +110,11 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
             return { success: true };
         });
     }
+    /**
+     * Reads the cached token data payload.
+     *
+     * @param token - Raw mock token string.
+     */
     getAuthToken(token) {
         const tokenData = this.tokens.get(token);
         if (!tokenData) {
@@ -87,6 +122,11 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
         }
         return tokenData;
     }
+    /**
+     * Cycles an old refresh token for a completely new session pair.
+     *
+     * @param refreshToken - Active mock refresh token string.
+     */
     refreshToken(refreshToken) {
         return __awaiter(this, void 0, void 0, function* () {
             const oldToken = this.refreshTokens.get(refreshToken);
@@ -113,6 +153,11 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
             };
         });
     }
+    /**
+     * Blacklists a specific access token.
+     *
+     * @param token - Target mock token to drop.
+     */
     revokeAuthToken(token) {
         if (!this.tokens.has(token)) {
             throw new Error('Token not found');
@@ -127,6 +172,12 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
         }
         return { success: true };
     }
+    /**
+     * Manually appends structural role claims onto a registered mock user.
+     *
+     * @param id - Mock user ID.
+     * @param claims - Payload to merge.
+     */
     setCustomUserClaims(id, claims) {
         // Find user by id and set custom claims
         for (const [email, user] of this.registeredUsers.entries()) {
@@ -139,14 +190,23 @@ class MockAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
         throw new Error('User not found');
     }
     // Helper methods for testing
+    /**
+     * Test utility: Flushes all internal registers.
+     */
     clearAll() {
         this.registeredUsers.clear();
         this.tokens.clear();
         this.refreshTokens.clear();
     }
+    /**
+     * Test utility: Retrieves user instance by its stored key (email).
+     */
     getUserByEmail(email) {
         return this.registeredUsers.get(email);
     }
+    /**
+     * Test utility: Asserts the existence of an active token.
+     */
     hasToken(token) {
         return this.tokens.has(token);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/auth",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "license": "AGPL-3.0-only",
   "description": "Auth adapters commons",
   "main": "dist/index.js",
@@ -20,8 +20,8 @@
   },
   "author": "Quatrain Développement SAS <developers@quatrain.com>",
   "dependencies": {
-    "@quatrain/backend": "^1.1.37",
-    "@quatrain/core": "^1.1.52"
+    "@quatrain/backend": "^1.2.6",
+    "@quatrain/core": "^1.2.5"
   },
   "devDependencies": {
     "@tsconfig/recommended": "^1.0.1",

package/src/AbstractAuthAdapter.ts

@@ -2,7 +2,13 @@ import { AuthParameters, AuthParametersKeys } from './Auth'
 import { User } from '@quatrain/backend'
 import { AuthInterface } from './types/AuthInterface'
 
+/**
+ * Abstract base class that defines the contract for all authentication adapters.
+ * Implementations should adapt standard authentication methods to specific providers
+ * (e.g. Firebase, Supabase, basic auth).
+ */
 export abstract class AbstractAuthAdapter implements AuthInterface {
+   /** The `User` class reference to be used by the adapter. */
    static UserClass = User
    protected _alias: string = ''
    protected _params: AuthParameters = {}
@@ -11,10 +17,22 @@ export abstract class AbstractAuthAdapter implements AuthInterface {
       this._params = params
    }
 
+   /**
+    * Assigns a configuration parameter for the adapter.
+    * 
+    * @param key - The parameter key.
+    * @param value - The parameter value.
+    */
    setParam(key: AuthParametersKeys, value: any) {
       this._params[key] = value
    }
 
+   /**
+    * Retrieves a configuration parameter.
+    * 
+    * @param key - The parameter key to fetch.
+    * @returns The corresponding configuration value.
+    */
    getParam(key: AuthParametersKeys) {
       return this._params[key]
    }
@@ -27,21 +45,79 @@ export abstract class AbstractAuthAdapter implements AuthInterface {
       return this._alias
    }
 
+   /**
+    * Registers a new user directly in the authentication provider.
+    * 
+    * @param user - The User object.
+    * @param clearPassword - The plaintext password.
+    * @returns A promise resolving to the registration response.
+    */
    abstract register(user: User, clearPassword?: string): Promise<any>
 
+   /**
+    * Authenticates a user by login and password (generates tokens).
+    * 
+    * @param login - User's email or login name.
+    * @param password - Plaintext password.
+    * @returns A promise resolving to the token payload.
+    */
    abstract signup(login: string, password: string): Promise<any>
 
+   /**
+    * Terminates the current authentication session.
+    * 
+    * @param user - The User footprint.
+    * @returns A promise resolving to the provider's signout response.
+    */
    abstract signout(user: User): Promise<any>
 
+   /**
+    * Updates user credentials or metadata within the external auth provider.
+    * 
+    * @param user - The User to modify.
+    * @param updatable - The delta payload of properties to update.
+    * @returns A promise resolving when the update completes.
+    */
    abstract update(user: User, updatable: any): Promise<any>
 
+   /**
+    * Hard-deletes a user from the authentication provider.
+    * 
+    * @param user - The User to delete.
+    * @returns A promise resolving on successful deletion.
+    */
    abstract delete(user: User): Promise<any>
 
+   /**
+    * Validates and decodes an incoming authentication token.
+    * 
+    * @param token - The raw token string (e.g. JWT).
+    * @returns The decoded token data payload.
+    */
    abstract getAuthToken(token: string): any
 
+   /**
+    * Refreshes an expired access token using a valid refresh token.
+    * 
+    * @param refreshToken - The refresh token string.
+    * @returns A promise resolving to the new access token payload.
+    */
    abstract refreshToken(refreshToken: string): Promise<any>
 
+   /**
+    * Invalidates a specific access token explicitly.
+    * 
+    * @param token - The token string to revoke.
+    * @returns Action response from the provider.
+    */
    abstract revokeAuthToken(token: string): any
 
+   /**
+    * Injects custom claims (e.g. role, tenant info) into the user's token structure.
+    * 
+    * @param id - The user ID.
+    * @param claims - The payload of claims to merge.
+    * @returns Action response from the provider.
+    */
    abstract setCustomUserClaims(id: string, claims: any): any
 }

package/src/Auth.ts

@@ -35,15 +35,29 @@ export interface AuthAdapter extends AbstractAuthAdapter {}
 
 export type AuthRegistry<T extends AbstractAuthAdapter> = { [x: string]: T }
 
+/**
+ * Global authentication manager handling registration and retrieval 
+ * of diverse Auth providers (adapters) via an alias registry.
+ */
 export class Auth extends Core {
+   /** The fallback provider alias. */
    static defaultProvider = 'default'
+   /** Core logger dedicated to Auth actions. */
    static logger = this.addLogger('Auth')
 
 
+   /** Standardized error message for duplicate email constraint violations. */
    static ERROR_EMAIL_EXISTS = `User email already exists`
 
    protected static _providers: AuthRegistry<any> = {}
 
+   /**
+    * Registers a configured auth provider into the global context.
+    * 
+    * @param provider - Instantiated auth adapter.
+    * @param alias - Short identifier name.
+    * @param setDefault - If true, marks this adapter as the fallback provider.
+    */
    static addProvider(
       provider: AbstractAuthAdapter,
       alias: string,
@@ -55,6 +69,13 @@ export class Auth extends Core {
       }
    }
 
+   /**
+    * Fetches a registered provider by its alias.
+    * 
+    * @param alias - Requested provider identifier. Defaults to `defaultProvider`.
+    * @returns The corresponding auth adapter.
+    * @throws {Error} If the specified alias is unknown.
+    */
    static getProvider<T extends AbstractAuthAdapter>(
       alias: string = this.defaultProvider
    ): T {

package/src/AuthenticationError.ts

@@ -1 +1,5 @@
+/**
+ * Standard exception representing authentication failures, invalid credentials,
+ * or token expiration events.
+ */
 export class AuthenticationError extends Error {}

package/src/MockAuthAdapter.ts

@@ -14,6 +14,13 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       super(params)
    }
 
+   /**
+    * Mock registration. Stores the user in memory mapped by email.
+    * 
+    * @param user - Target user.
+    * @param clearPassword - Ignored in mock context.
+    * @returns A mock success promise.
+    */
    async register(user: User, clearPassword?: string): Promise<any> {
       if (this.registeredUsers.has(user._.email)) {
          throw new Error('User email already exists')
@@ -22,6 +29,13 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       return { success: true, user }
    }
 
+   /**
+    * Mock signup. Generates mock JWT tokens assuming the login is valid.
+    * 
+    * @param login - Mock user identifier.
+    * @param password - Mock password.
+    * @returns Emulated auth response payload.
+    */
    async signup(login: string, password: string): Promise<any> {
       const user = this.registeredUsers.get(login)
       if (!user) {
@@ -42,6 +56,11 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       }
    }
 
+   /**
+    * Deletes active tokens tied to the provided mock user.
+    * 
+    * @param user - User instance to sign out.
+    */
    async signout(user: User): Promise<any> {
       // Remove all tokens associated with this user
       for (const [token, data] of this.tokens.entries()) {
@@ -52,6 +71,12 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       return { success: true }
    }
 
+   /**
+    * Mock user state update in memory.
+    * 
+    * @param user - Target user.
+    * @param updatable - Property modifications.
+    */
    async update(user: User, updatable: any): Promise<any> {
       const existingUser = this.registeredUsers.get(user._.email)
       if (!existingUser) {
@@ -64,6 +89,11 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       return { success: true, user: updatedUser }
    }
 
+   /**
+    * Evicts the user and all associated mock tokens from memory.
+    * 
+    * @param user - User instance to delete.
+    */
    async delete(user: User): Promise<any> {
       if (!this.registeredUsers.has(user._.email)) {
          throw new Error('User not found')
@@ -75,6 +105,11 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       return { success: true }
    }
 
+   /**
+    * Reads the cached token data payload.
+    * 
+    * @param token - Raw mock token string.
+    */
    getAuthToken(token: string): any {
       const tokenData = this.tokens.get(token)
       if (!tokenData) {
@@ -83,6 +118,11 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       return tokenData
    }
 
+   /**
+    * Cycles an old refresh token for a completely new session pair.
+    * 
+    * @param refreshToken - Active mock refresh token string.
+    */
    async refreshToken(refreshToken: string): Promise<any> {
       const oldToken = this.refreshTokens.get(refreshToken)
       if (!oldToken) {
@@ -113,6 +153,11 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       }
    }
 
+   /**
+    * Blacklists a specific access token.
+    * 
+    * @param token - Target mock token to drop.
+    */
    revokeAuthToken(token: string): any {
       if (!this.tokens.has(token)) {
          throw new Error('Token not found')
@@ -134,6 +179,12 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
       return { success: true }
    }
 
+   /**
+    * Manually appends structural role claims onto a registered mock user.
+    * 
+    * @param id - Mock user ID.
+    * @param claims - Payload to merge.
+    */
    setCustomUserClaims(id: string, claims: any): any {
       // Find user by id and set custom claims
       for (const [email, user] of this.registeredUsers.entries()) {
@@ -146,16 +197,25 @@ export class MockAuthAdapter extends AbstractAuthAdapter {
    }
 
    // Helper methods for testing
+   /**
+    * Test utility: Flushes all internal registers.
+    */
    clearAll(): void {
       this.registeredUsers.clear()
       this.tokens.clear()
       this.refreshTokens.clear()
    }
 
+   /**
+    * Test utility: Retrieves user instance by its stored key (email).
+    */
    getUserByEmail(email: string): User | undefined {
       return this.registeredUsers.get(email)
    }
 
+   /**
+    * Test utility: Asserts the existence of an active token.
+    */
    hasToken(token: string): boolean {
       return this.tokens.has(token)
    }