@quatrain/auth 1.2.9 → 1.2.10

package/dist/AbstractAuthAdapter.d.ts

@@ -109,4 +109,10 @@ export declare abstract class AbstractAuthAdapter implements AuthInterface {
      * @param redirectTo - Optional redirect destination.
      */
     recoverPassword(email: string, redirectTo?: string): Promise<any>;
+    /**
+     * Returns the pluggable endpoint handler function for this adapter, if any.
+     *
+     * @returns The EndpointHandler callback or null.
+     */
+    getEndpointHandler(): any;
 }

package/dist/AbstractAuthAdapter.js

@@ -82,6 +82,14 @@ class AbstractAuthAdapter {
     recoverPassword(email, redirectTo) {
         throw new Error('Password recovery not implemented for this adapter');
     }
+    /**
+     * Returns the pluggable endpoint handler function for this adapter, if any.
+     *
+     * @returns The EndpointHandler callback or null.
+     */
+    getEndpointHandler() {
+        return null;
+    }
 }
 exports.AbstractAuthAdapter = AbstractAuthAdapter;
 /** The `User` class reference to be used by the adapter. */

package/dist/AbstractOAuthAdapter.d.ts

@@ -0,0 +1,95 @@
+import { AbstractAuthAdapter } from './AbstractAuthAdapter';
+import { AuthParameters } from './Auth';
+import { User } from '@quatrain/backend';
+/**
+ * Abstract class summarizing typical OAuth2 Web Application Flows.
+ * Extend this to implement providers like GitHub, GitLab, Google, etc.
+ */
+export declare abstract class AbstractOAuthAdapter extends AbstractAuthAdapter {
+    protected abstract _authorizationEndpoint: string;
+    protected abstract _tokenEndpoint: string;
+    protected abstract _userProfileEndpoint: string;
+    constructor(params?: AuthParameters);
+    /**
+     * Returns the authorization redirect URL.
+     *
+     * @param redirectUri - The callback URL.
+     * @param scopes - The requested authorization scopes.
+     * @param state - The state parameters for CSRF protection.
+     * @returns The generated authorization URL.
+     */
+    getAuthorizationUrl(redirectUri?: string, scopes?: string[], state?: string): string;
+    /**
+     * Exchanges the temporary authorization code for an access token packet.
+     *
+     * @param code - The temporary auth code.
+     * @param redirectUri - Optional redirect URL context.
+     * @returns Access token payload.
+     */
+    exchangeCodeForToken(code: string, redirectUri?: string): Promise<any>;
+    /**
+     * Registers a new user account (unsupported for OAuth adapters).
+     *
+     * @param user - Target user entity.
+     * @param clearPassword - Optional cleartext password.
+     * @returns Throws an error indicating registration is unsupported.
+     */
+    register(user: User, clearPassword?: string): Promise<any>;
+    /**
+     * Performs user signup with credentials (unsupported for OAuth adapters).
+     *
+     * @param login - Login identifier string.
+     * @param password - Password string.
+     * @returns Throws an error indicating signup should use exchangeCodeForToken.
+     */
+    signup(login: string, password: string): Promise<any>;
+    /**
+     * Signs out the specified user session.
+     *
+     * @param user - Target user entity.
+     * @returns Promise resolving to true.
+     */
+    signout(user: User): Promise<any>;
+    /**
+     * Updates user profile attributes in the auth store.
+     *
+     * @param user - Target user entity.
+     * @param updatable - Attributes payload to update.
+     * @returns Promise resolving to true.
+     */
+    update(user: User, updatable: any): Promise<any>;
+    /**
+     * Deletes a user account from the auth store.
+     *
+     * @param user - Target user entity.
+     * @returns Promise resolving to true.
+     */
+    delete(user: User): Promise<any>;
+    /**
+     * Refreshes an expired access token using a refresh token string.
+     *
+     * @param refreshToken - Target refresh token.
+     * @returns Throws an error if refresh token logic is not implemented by the provider.
+     */
+    refreshToken(refreshToken: string): Promise<any>;
+    /**
+     * Revokes the access token (noop default).
+     *
+     * @param token - Target token to revoke.
+     */
+    revokeAuthToken(token: string): Promise<any>;
+    /**
+     * Inject custom claims (not supported by default).
+     *
+     * @param id - Target user ID.
+     * @param claims - Payload claims.
+     */
+    setCustomUserClaims(id: string, claims: any): Promise<any>;
+    /**
+     * Retrieves and validates an auth token payload for the given raw token string.
+     *
+     * @param token - Raw authorization token string.
+     * @returns The resolved token payload or user claims.
+     */
+    abstract getAuthToken(token: string): any;
+}

package/dist/AbstractOAuthAdapter.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractOAuthAdapter = void 0;
+const AbstractAuthAdapter_1 = require("./AbstractAuthAdapter");
+const nativeFetch = __importStar(require("node-fetch-native"));
+/**
+ * Abstract class summarizing typical OAuth2 Web Application Flows.
+ * Extend this to implement providers like GitHub, GitLab, Google, etc.
+ */
+class AbstractOAuthAdapter extends AbstractAuthAdapter_1.AbstractAuthAdapter {
+    constructor(params = {}) {
+        super(params);
+    }
+    /**
+     * Returns the authorization redirect URL.
+     *
+     * @param redirectUri - The callback URL.
+     * @param scopes - The requested authorization scopes.
+     * @param state - The state parameters for CSRF protection.
+     * @returns The generated authorization URL.
+     */
+    getAuthorizationUrl(redirectUri, scopes = [], state) {
+        var _a;
+        const clientId = (_a = this._params.config) === null || _a === void 0 ? void 0 : _a.clientId;
+        if (!clientId) {
+            throw new Error(`[${this.constructor.name}] Client ID is not configured.`);
+        }
+        let url = `${this._authorizationEndpoint}?client_id=${clientId}`;
+        if (scopes.length > 0) {
+            url += `&scope=${encodeURIComponent(scopes.join(' '))}`;
+        }
+        if (redirectUri) {
+            url += `&redirect_uri=${encodeURIComponent(redirectUri)}`;
+        }
+        if (state) {
+            url += `&state=${encodeURIComponent(state)}`;
+        }
+        return url;
+    }
+    /**
+     * Exchanges the temporary authorization code for an access token packet.
+     *
+     * @param code - The temporary auth code.
+     * @param redirectUri - Optional redirect URL context.
+     * @returns Access token payload.
+     */
+    exchangeCodeForToken(code, redirectUri) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const clientId = (_a = this._params.config) === null || _a === void 0 ? void 0 : _a.clientId;
+            const clientSecret = (_b = this._params.config) === null || _b === void 0 ? void 0 : _b.clientSecret;
+            if (!clientId || !clientSecret) {
+                throw new Error(`[${this.constructor.name}] Client ID or Client Secret is not configured.`);
+            }
+            const body = {
+                client_id: clientId,
+                client_secret: clientSecret,
+                code,
+                grant_type: 'authorization_code'
+            };
+            if (redirectUri) {
+                body.redirect_uri = redirectUri;
+            }
+            const response = yield nativeFetch.fetch(this._tokenEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json'
+                },
+                body: JSON.stringify(body)
+            });
+            if (!response.ok) {
+                throw new Error(`[${this.constructor.name}] OAuth token exchange failed: ${response.statusText}`);
+            }
+            const data = yield response.json();
+            if (data.error) {
+                throw new Error(`[${this.constructor.name}] OAuth error: ${data.error_description || data.error}`);
+            }
+            return data; // Access token, scopes, token_type, etc.
+        });
+    }
+    /**
+     * Registers a new user account (unsupported for OAuth adapters).
+     *
+     * @param user - Target user entity.
+     * @param clearPassword - Optional cleartext password.
+     * @returns Throws an error indicating registration is unsupported.
+     */
+    register(user, clearPassword) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new Error(`register is not supported by ${this.constructor.name}`);
+        });
+    }
+    /**
+     * Performs user signup with credentials (unsupported for OAuth adapters).
+     *
+     * @param login - Login identifier string.
+     * @param password - Password string.
+     * @returns Throws an error indicating signup should use exchangeCodeForToken.
+     */
+    signup(login, password) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new Error(`signup is not supported by ${this.constructor.name}. Use exchangeCodeForToken instead.`);
+        });
+    }
+    /**
+     * Signs out the specified user session.
+     *
+     * @param user - Target user entity.
+     * @returns Promise resolving to true.
+     */
+    signout(user) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return true;
+        });
+    }
+    /**
+     * Updates user profile attributes in the auth store.
+     *
+     * @param user - Target user entity.
+     * @param updatable - Attributes payload to update.
+     * @returns Promise resolving to true.
+     */
+    update(user, updatable) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return true;
+        });
+    }
+    /**
+     * Deletes a user account from the auth store.
+     *
+     * @param user - Target user entity.
+     * @returns Promise resolving to true.
+     */
+    delete(user) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return true;
+        });
+    }
+    /**
+     * Refreshes an expired access token using a refresh token string.
+     *
+     * @param refreshToken - Target refresh token.
+     * @returns Throws an error if refresh token logic is not implemented by the provider.
+     */
+    refreshToken(refreshToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new Error(`refreshToken is not implemented for ${this.constructor.name}`);
+        });
+    }
+    /**
+     * Revokes the access token (noop default).
+     *
+     * @param token - Target token to revoke.
+     */
+    revokeAuthToken(token) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return true;
+        });
+    }
+    /**
+     * Inject custom claims (not supported by default).
+     *
+     * @param id - Target user ID.
+     * @param claims - Payload claims.
+     */
+    setCustomUserClaims(id, claims) {
+        return __awaiter(this, void 0, void 0, function* () {
+            throw new Error(`setCustomUserClaims is not supported by ${this.constructor.name}`);
+        });
+    }
+}
+exports.AbstractOAuthAdapter = AbstractOAuthAdapter;

package/dist/Auth.d.ts

@@ -56,4 +56,12 @@ export declare class Auth extends Core {
      * @throws {Error} If the specified alias is unknown.
      */
     static getProvider<T extends AbstractAuthAdapter>(alias?: string): T;
+    /**
+     * Scans all registered auth providers, collects their endpoint handlers,
+     * and registers them dynamically under a common routing root path.
+     *
+     * @param server - The Quatrain ServerAdapter (Astro, Express, etc.).
+     * @param rootPath - The common authentication root segment (defaults to '/api/auth').
+     */
+    static registerEndpoints(server: any, rootPath?: string): void;
 }

package/dist/Auth.js

@@ -42,6 +42,22 @@ class Auth extends core_1.Core {
             throw new Error(`Unknown provider alias: '${alias}'`);
         }
     }
+    /**
+     * Scans all registered auth providers, collects their endpoint handlers,
+     * and registers them dynamically under a common routing root path.
+     *
+     * @param server - The Quatrain ServerAdapter (Astro, Express, etc.).
+     * @param rootPath - The common authentication root segment (defaults to '/api/auth').
+     */
+    static registerEndpoints(server, rootPath = '/api/auth') {
+        for (const [alias, provider] of Object.entries(this._providers)) {
+            const handler = provider.getEndpointHandler();
+            if (handler) {
+                this.info(`Registering pluggable API endpoints for auth provider '${alias}' on '${rootPath}/${alias}'`);
+                server.addEndpoint(handler, `${rootPath}/${alias}`, { adapter: provider });
+            }
+        }
+    }
 }
 exports.Auth = Auth;
 _a = Auth;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { Auth, AuthAction } from './Auth';
 import type { AuthParameters, AuthParametersKeys } from './Auth';
 import { AbstractAuthAdapter } from './AbstractAuthAdapter';
+import { AbstractOAuthAdapter } from './AbstractOAuthAdapter';
 import type { AuthInterface } from './types/AuthInterface';
 import { AuthenticationError } from './AuthenticationError';
-export { Auth, AuthAction, AbstractAuthAdapter, AuthenticationError, };
+export { Auth, AuthAction, AbstractAuthAdapter, AbstractOAuthAdapter, AuthenticationError, };
 export type { AuthParameters, AuthParametersKeys, AuthInterface, };

package/dist/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthenticationError = exports.AbstractAuthAdapter = exports.AuthAction = exports.Auth = void 0;
+exports.AuthenticationError = exports.AbstractOAuthAdapter = exports.AbstractAuthAdapter = exports.AuthAction = exports.Auth = void 0;
 const Auth_1 = require("./Auth");
 Object.defineProperty(exports, "Auth", { enumerable: true, get: function () { return Auth_1.Auth; } });
 Object.defineProperty(exports, "AuthAction", { enumerable: true, get: function () { return Auth_1.AuthAction; } });
 const AbstractAuthAdapter_1 = require("./AbstractAuthAdapter");
 Object.defineProperty(exports, "AbstractAuthAdapter", { enumerable: true, get: function () { return AbstractAuthAdapter_1.AbstractAuthAdapter; } });
+const AbstractOAuthAdapter_1 = require("./AbstractOAuthAdapter");
+Object.defineProperty(exports, "AbstractOAuthAdapter", { enumerable: true, get: function () { return AbstractOAuthAdapter_1.AbstractOAuthAdapter; } });
 const AuthenticationError_1 = require("./AuthenticationError");
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return AuthenticationError_1.AuthenticationError; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/auth",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "license": "AGPL-3.0-only",
   "description": "Auth adapters commons",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
   "dependencies": {
     "@quatrain/api": "^1.1.7",
     "@quatrain/backend": "^1.2.17",
-    "@quatrain/core": "^1.2.16",
+    "@quatrain/core": "^1.2.17",
     "@quatrain/http": "^1.0.4"
   },
   "devDependencies": {

package/src/AbstractAuthAdapter.ts

@@ -158,4 +158,13 @@ export abstract class AbstractAuthAdapter implements AuthInterface {
    recoverPassword(email: string, redirectTo?: string): Promise<any> {
       throw new Error('Password recovery not implemented for this adapter')
    }
+
+   /**
+    * Returns the pluggable endpoint handler function for this adapter, if any.
+    * 
+    * @returns The EndpointHandler callback or null.
+    */
+   public getEndpointHandler(): any {
+      return null
+   }
 }

package/src/AbstractOAuthAdapter.ts

@@ -0,0 +1,182 @@
+import { AbstractAuthAdapter } from './AbstractAuthAdapter'
+import { AuthParameters } from './Auth'
+import { User } from '@quatrain/backend'
+import * as nativeFetch from 'node-fetch-native'
+
+/**
+ * Abstract class summarizing typical OAuth2 Web Application Flows.
+ * Extend this to implement providers like GitHub, GitLab, Google, etc.
+ */
+export abstract class AbstractOAuthAdapter extends AbstractAuthAdapter {
+   protected abstract _authorizationEndpoint: string
+   protected abstract _tokenEndpoint: string
+   protected abstract _userProfileEndpoint: string
+
+   constructor(params: AuthParameters = {}) {
+      super(params)
+   }
+
+   /**
+    * Returns the authorization redirect URL.
+    * 
+    * @param redirectUri - The callback URL.
+    * @param scopes - The requested authorization scopes.
+    * @param state - The state parameters for CSRF protection.
+    * @returns The generated authorization URL.
+    */
+   public getAuthorizationUrl(redirectUri?: string, scopes: string[] = [], state?: string): string {
+      const clientId = this._params.config?.clientId
+      if (!clientId) {
+         throw new Error(`[${this.constructor.name}] Client ID is not configured.`)
+      }
+
+      let url = `${this._authorizationEndpoint}?client_id=${clientId}`
+      if (scopes.length > 0) {
+         url += `&scope=${encodeURIComponent(scopes.join(' '))}`
+      }
+      if (redirectUri) {
+         url += `&redirect_uri=${encodeURIComponent(redirectUri)}`
+      }
+      if (state) {
+         url += `&state=${encodeURIComponent(state)}`
+      }
+      return url
+   }
+
+   /**
+    * Exchanges the temporary authorization code for an access token packet.
+    * 
+    * @param code - The temporary auth code.
+    * @param redirectUri - Optional redirect URL context.
+    * @returns Access token payload.
+    */
+   public async exchangeCodeForToken(code: string, redirectUri?: string): Promise<any> {
+      const clientId = this._params.config?.clientId
+      const clientSecret = this._params.config?.clientSecret
+
+      if (!clientId || !clientSecret) {
+         throw new Error(`[${this.constructor.name}] Client ID or Client Secret is not configured.`)
+      }
+
+      const body: Record<string, string> = {
+         client_id: clientId,
+         client_secret: clientSecret,
+         code,
+         grant_type: 'authorization_code'
+      }
+
+      if (redirectUri) {
+         body.redirect_uri = redirectUri
+      }
+
+      const response = await nativeFetch.fetch(this._tokenEndpoint, {
+         method: 'POST',
+         headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json'
+         },
+         body: JSON.stringify(body)
+      })
+
+      if (!response.ok) {
+         throw new Error(`[${this.constructor.name}] OAuth token exchange failed: ${response.statusText}`)
+      }
+
+      const data = await response.json()
+      if (data.error) {
+         throw new Error(`[${this.constructor.name}] OAuth error: ${data.error_description || data.error}`)
+      }
+
+      return data // Access token, scopes, token_type, etc.
+   }
+
+   /**
+    * Registers a new user account (unsupported for OAuth adapters).
+    * 
+    * @param user - Target user entity.
+    * @param clearPassword - Optional cleartext password.
+    * @returns Throws an error indicating registration is unsupported.
+    */
+   async register(user: User, clearPassword?: string): Promise<any> {
+      throw new Error(`register is not supported by ${this.constructor.name}`)
+   }
+
+   /**
+    * Performs user signup with credentials (unsupported for OAuth adapters).
+    * 
+    * @param login - Login identifier string.
+    * @param password - Password string.
+    * @returns Throws an error indicating signup should use exchangeCodeForToken.
+    */
+   async signup(login: string, password: string): Promise<any> {
+      throw new Error(`signup is not supported by ${this.constructor.name}. Use exchangeCodeForToken instead.`)
+   }
+
+   /**
+    * Signs out the specified user session.
+    * 
+    * @param user - Target user entity.
+    * @returns Promise resolving to true.
+    */
+   async signout(user: User): Promise<any> {
+      return true
+   }
+
+   /**
+    * Updates user profile attributes in the auth store.
+    * 
+    * @param user - Target user entity.
+    * @param updatable - Attributes payload to update.
+    * @returns Promise resolving to true.
+    */
+   async update(user: User, updatable: any): Promise<any> {
+      return true
+   }
+
+   /**
+    * Deletes a user account from the auth store.
+    * 
+    * @param user - Target user entity.
+    * @returns Promise resolving to true.
+    */
+   async delete(user: User): Promise<any> {
+      return true
+   }
+
+   /**
+    * Refreshes an expired access token using a refresh token string.
+    * 
+    * @param refreshToken - Target refresh token.
+    * @returns Throws an error if refresh token logic is not implemented by the provider.
+    */
+   async refreshToken(refreshToken: string): Promise<any> {
+      throw new Error(`refreshToken is not implemented for ${this.constructor.name}`)
+   }
+
+   /**
+    * Revokes the access token (noop default).
+    * 
+    * @param token - Target token to revoke.
+    */
+   async revokeAuthToken(token: string): Promise<any> {
+      return true
+   }
+
+   /**
+    * Inject custom claims (not supported by default).
+    * 
+    * @param id - Target user ID.
+    * @param claims - Payload claims.
+    */
+   async setCustomUserClaims(id: string, claims: any): Promise<any> {
+      throw new Error(`setCustomUserClaims is not supported by ${this.constructor.name}`)
+   }
+
+   /**
+    * Retrieves and validates an auth token payload for the given raw token string.
+    * 
+    * @param token - Raw authorization token string.
+    * @returns The resolved token payload or user claims.
+    */
+   abstract getAuthToken(token: string): any
+}

package/src/Auth.ts

@@ -87,4 +87,21 @@ export class Auth extends Core {
          throw new Error(`Unknown provider alias: '${alias}'`)
       }
    }
+
+    /**
+     * Scans all registered auth providers, collects their endpoint handlers,
+     * and registers them dynamically under a common routing root path.
+     * 
+     * @param server - The Quatrain ServerAdapter (Astro, Express, etc.).
+     * @param rootPath - The common authentication root segment (defaults to '/api/auth').
+     */
+    static registerEndpoints(server: any, rootPath: string = '/api/auth') {
+       for (const [alias, provider] of Object.entries(this._providers)) {
+          const handler = provider.getEndpointHandler()
+          if (handler) {
+             this.info(`Registering pluggable API endpoints for auth provider '${alias}' on '${rootPath}/${alias}'`)
+             server.addEndpoint(handler, `${rootPath}/${alias}`, { adapter: provider })
+          }
+       }
+    }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 import { Auth, AuthAction } from './Auth'
 import type { AuthParameters, AuthParametersKeys } from './Auth'
 import { AbstractAuthAdapter } from './AbstractAuthAdapter'
+import { AbstractOAuthAdapter } from './AbstractOAuthAdapter'
 import type { AuthInterface } from './types/AuthInterface'
 import { AuthenticationError } from './AuthenticationError'
 
@@ -8,6 +9,7 @@ export {
    Auth,
    AuthAction,
    AbstractAuthAdapter,
+   AbstractOAuthAdapter,
    AuthenticationError,
 }