@acorex/platform 20.6.3 → 20.6.5

package/auth/index.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, TemplateRef, ViewContainerRef, ModuleWithProviders, Injector } from '@angular/core';
+import { InjectionToken, TemplateRef, ViewContainerRef, ModuleWithProviders, Injector, Type } from '@angular/core';
 import { Observable } from 'rxjs';
 import { AXPLogoConfig, AXPExpressionEvaluatorScopeProvider, AXPExpressionEvaluatorScopeProviderContext } from '@acorex/platform/core';
 import { CanActivateFn } from '@angular/router';
@@ -355,5 +355,230 @@ declare class AXPUnauthenticatedError extends Error {
     } | undefined);
 }
 
-export { AXPAuthGuard, AXPAuthModule, AXPAuthStrategy, AXPAuthStrategyRegistryService, AXPFeatureDirective, AXPFeatureGuard, AXPPermissionDefinitionBuilder, AXPPermissionDefinitionGroupBuilder, AXPPermissionDefinitionProviderContext, AXPPermissionDefinitionService, AXPPermissionDirective, AXPPermissionEvaluatorScopeProvider, AXPPermissionGuard, AXPSessionContext, AXPSessionService, AXPSessionStatus, AXPUnauthenticatedError, AXPUnauthorizedError, AXP_APPLICATION_LOADER, AXP_FEATURE_LOADER, AXP_PERMISSION_DEFINITION_PROVIDER, AXP_PERMISSION_LOADER, AXP_TENANT_LOADER, JwtUtil, PkceUtil, TimeUtil, initializeAppState };
-export type { AXPApplication, AXPApplicationLoader, AXPAuthModuleConfigs, AXPBaseCredentials, AXPFeature, AXPFeatureLoader, AXPPermission, AXPPermissionDefinition, AXPPermissionDefinitionProvider, AXPPermissionGroupDefinition, AXPPermissionLoader, AXPSessionData, AXPSignInResult, AXPTenant, AXPTenantLoader, AXPTokenResult, AXPUser };
+/**
+ * Supported content types for challenge display
+ */
+type AXPChallengeContentType = 'image-url' | 'image-base64' | 'text' | 'audio-url';
+/**
+ * Challenge data returned from the server
+ * Contains all information needed to display and submit a challenge
+ */
+interface AXPLoginChallengeData {
+    /**
+     * Unique identifier for this challenge
+     * Must be sent back with credentials when submitting login
+     */
+    id: string;
+    /**
+     * The challenge content to display
+     * Could be an image URL, base64 encoded image, text, or audio URL
+     */
+    content: string;
+    /**
+     * Type of content for proper rendering
+     */
+    contentType: AXPChallengeContentType;
+    /**
+     * When this challenge expires (optional)
+     * After expiration, a new challenge should be fetched
+     */
+    expiresAt?: Date;
+    /**
+     * Additional metadata from server (optional)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of checking a login error response
+ * Determines if a challenge should be displayed
+ */
+interface AXPChallengeCheckResult {
+    /**
+     * Whether a challenge is required
+     */
+    required: boolean;
+    /**
+     * Optional message to display to the user
+     */
+    message?: string;
+    /**
+     * Additional data from server that may be needed for getChallenge()
+     * For example: sessionId, attemptId, etc.
+     */
+    serverData?: Record<string, unknown>;
+}
+
+/**
+ * Base class for login challenge UI components
+ *
+ * Providers can extend this class to create custom challenge UIs.
+ * The login component will render this component and listen to its outputs.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'my-captcha-challenge',
+ *   template: `
+ *     <div class="captcha-container">
+ *       <img [src]="'data:image/png;base64,' + challengeData().content" />
+ *       <input
+ *         type="text"
+ *         [value]="response()"
+ *         (input)="onResponseChange($event)"
+ *       />
+ *       <button (click)="onRefreshClick()">Refresh</button>
+ *     </div>
+ *   `
+ * })
+ * export class MyCaptchaChallengeComponent extends AXPLoginChallengeComponentBase {
+ *   response = signal('');
+ *
+ *   onResponseChange(event: Event) {
+ *     const value = (event.target as HTMLInputElement).value;
+ *     this.response.set(value);
+ *     this.responseChange.emit(value);
+ *   }
+ *
+ *   onRefreshClick() {
+ *     this.refreshRequest.emit();
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AXPLoginChallengeComponentBase {
+    /**
+     * Challenge data to display
+     * Contains the image/content and metadata from the server
+     */
+    challengeData: i0.InputSignal<AXPLoginChallengeData>;
+    /**
+     * Whether the challenge is currently loading (e.g., refreshing)
+     */
+    isLoading: i0.InputSignal<boolean>;
+    /**
+     * Emits when the user enters or changes their response
+     * The login component will capture this value and include it in credentials
+     */
+    responseChange: i0.OutputEmitterRef<string>;
+    /**
+     * Emits when the user requests a new challenge (e.g., clicks refresh button)
+     * The login component will call provider.refreshChallenge()
+     */
+    refreshRequest: i0.OutputEmitterRef<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPLoginChallengeComponentBase, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<AXPLoginChallengeComponentBase, "ng-component", never, { "challengeData": { "alias": "challengeData"; "required": true; "isSignal": true; }; "isLoading": { "alias": "isLoading"; "required": false; "isSignal": true; }; }, { "responseChange": "responseChange"; "refreshRequest": "refreshRequest"; }, never, never, true, never>;
+}
+
+/**
+ * Abstract base class for login challenge providers
+ *
+ * Implement this class to create custom challenge mechanisms like:
+ * - Image CAPTCHA
+ * - reCAPTCHA
+ * - SMS verification
+ * - Email verification
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class MyImageCaptchaProvider extends AXPLoginChallengeProvider {
+ *   readonly name = 'image-captcha';
+ *
+ *   checkResponse(error: unknown): AXPChallengeCheckResult | null {
+ *     if (error instanceof HttpErrorResponse) {
+ *       if (error.error?.requiresCaptcha) {
+ *         return { required: true };
+ *       }
+ *     }
+ *     return null;
+ *   }
+ *
+ *   async getChallenge(): Promise<AXPLoginChallengeData> {
+ *     const response = await this.http.get('/api/captcha').toPromise();
+ *     return {
+ *       id: response.id,
+ *       content: response.image,
+ *       contentType: 'image-base64'
+ *     };
+ *   }
+ *
+ *   async refreshChallenge(): Promise<AXPLoginChallengeData> {
+ *     return this.getChallenge();
+ *   }
+ *
+ *   getChallengeComponent(): Type<AXPLoginChallengeComponentBase> {
+ *     return MyCaptchaChallengeComponent;
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AXPLoginChallengeProvider {
+    /**
+     * Unique name identifier for this provider
+     */
+    abstract readonly name: string;
+    /**
+     * Checks the login error response to determine if a challenge is required
+     *
+     * This method is called after a failed login attempt. The implementation
+     * should inspect the error and return a result indicating whether a
+     * challenge should be displayed.
+     *
+     * @param error - The error from the failed login attempt (type varies by implementation)
+     * @returns Challenge check result, or null if this provider doesn't handle this error
+     */
+    abstract checkResponse(error: unknown): AXPChallengeCheckResult | null;
+    /**
+     * Fetches a new challenge from the server
+     *
+     * Called when checkResponse indicates a challenge is required.
+     * Should make an API call to get challenge data (e.g., CAPTCHA image).
+     *
+     * @param serverData - Optional data from checkResponse result that may be needed
+     * @returns Promise resolving to challenge data for display
+     */
+    abstract getChallenge(serverData?: Record<string, unknown>): Promise<AXPLoginChallengeData>;
+    /**
+     * Fetches a fresh challenge, replacing the current one
+     *
+     * Called when user requests a new challenge (e.g., clicks "new image" button).
+     * Typically delegates to getChallenge() but may have different behavior.
+     *
+     * @returns Promise resolving to new challenge data
+     */
+    abstract refreshChallenge(): Promise<AXPLoginChallengeData>;
+    /**
+     * Returns the component type for rendering the challenge UI
+     *
+     * Override this method to provide a custom challenge UI component.
+     * If not overridden (returns null), the login component will use
+     * a default built-in UI.
+     *
+     * @returns Component type extending AXPLoginChallengeComponentBase, or null for default UI
+     */
+    getChallengeComponent(): Type<AXPLoginChallengeComponentBase> | null;
+}
+
+/**
+ * Injection token for the login challenge provider
+ *
+ * This token is optional - if not provided, no challenge mechanism will be used.
+ *
+ * @example
+ * ```typescript
+ * // In your app module or provider configuration:
+ * providers: [
+ *   {
+ *     provide: AXP_LOGIN_CHALLENGE_PROVIDER,
+ *     useClass: MyImageCaptchaProvider
+ *   }
+ * ]
+ *
+ * // In a component:
+ * private challengeProvider = inject(AXP_LOGIN_CHALLENGE_PROVIDER, { optional: true });
+ * ```
+ */
+declare const AXP_LOGIN_CHALLENGE_PROVIDER: InjectionToken<AXPLoginChallengeProvider>;
+
+export { AXPAuthGuard, AXPAuthModule, AXPAuthStrategy, AXPAuthStrategyRegistryService, AXPFeatureDirective, AXPFeatureGuard, AXPLoginChallengeComponentBase, AXPLoginChallengeProvider, AXPPermissionDefinitionBuilder, AXPPermissionDefinitionGroupBuilder, AXPPermissionDefinitionProviderContext, AXPPermissionDefinitionService, AXPPermissionDirective, AXPPermissionEvaluatorScopeProvider, AXPPermissionGuard, AXPSessionContext, AXPSessionService, AXPSessionStatus, AXPUnauthenticatedError, AXPUnauthorizedError, AXP_APPLICATION_LOADER, AXP_FEATURE_LOADER, AXP_LOGIN_CHALLENGE_PROVIDER, AXP_PERMISSION_DEFINITION_PROVIDER, AXP_PERMISSION_LOADER, AXP_TENANT_LOADER, JwtUtil, PkceUtil, TimeUtil, initializeAppState };
+export type { AXPApplication, AXPApplicationLoader, AXPAuthModuleConfigs, AXPBaseCredentials, AXPChallengeCheckResult, AXPChallengeContentType, AXPFeature, AXPFeatureLoader, AXPLoginChallengeData, AXPPermission, AXPPermissionDefinition, AXPPermissionDefinitionProvider, AXPPermissionGroupDefinition, AXPPermissionLoader, AXPSessionData, AXPSignInResult, AXPTenant, AXPTenantLoader, AXPTokenResult, AXPUser };

package/fesm2022/acorex-platform-auth.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, Injector, Injectable, signal, inject, Input, Directive, provideAppInitializer, Optional, Inject, NgModule } from '@angular/core';
+import { InjectionToken, Injector, Injectable, signal, inject, Input, Directive, provideAppInitializer, Optional, Inject, NgModule, input, output, Component } from '@angular/core';
 import { of, map, BehaviorSubject, shareReplay, defaultIfEmpty, switchMap, filter, firstValueFrom, first } from 'rxjs';
 import { AXPBroadcastEventService } from '@acorex/platform/core';
 import { isEmpty } from 'lodash-es';
@@ -984,9 +984,169 @@ class TimeUtil {
 }
 //#endregion
 
+//#region ----   Challenge Data Types   ----
+//#endregion
+
+//#region ----   Abstract Challenge Provider   ----
+/**
+ * Abstract base class for login challenge providers
+ *
+ * Implement this class to create custom challenge mechanisms like:
+ * - Image CAPTCHA
+ * - reCAPTCHA
+ * - SMS verification
+ * - Email verification
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class MyImageCaptchaProvider extends AXPLoginChallengeProvider {
+ *   readonly name = 'image-captcha';
+ *
+ *   checkResponse(error: unknown): AXPChallengeCheckResult | null {
+ *     if (error instanceof HttpErrorResponse) {
+ *       if (error.error?.requiresCaptcha) {
+ *         return { required: true };
+ *       }
+ *     }
+ *     return null;
+ *   }
+ *
+ *   async getChallenge(): Promise<AXPLoginChallengeData> {
+ *     const response = await this.http.get('/api/captcha').toPromise();
+ *     return {
+ *       id: response.id,
+ *       content: response.image,
+ *       contentType: 'image-base64'
+ *     };
+ *   }
+ *
+ *   async refreshChallenge(): Promise<AXPLoginChallengeData> {
+ *     return this.getChallenge();
+ *   }
+ *
+ *   getChallengeComponent(): Type<AXPLoginChallengeComponentBase> {
+ *     return MyCaptchaChallengeComponent;
+ *   }
+ * }
+ * ```
+ */
+class AXPLoginChallengeProvider {
+    /**
+     * Returns the component type for rendering the challenge UI
+     *
+     * Override this method to provide a custom challenge UI component.
+     * If not overridden (returns null), the login component will use
+     * a default built-in UI.
+     *
+     * @returns Component type extending AXPLoginChallengeComponentBase, or null for default UI
+     */
+    getChallengeComponent() {
+        return null;
+    }
+}
+//#endregion
+
+//#region ----   Injection Token   ----
+/**
+ * Injection token for the login challenge provider
+ *
+ * This token is optional - if not provided, no challenge mechanism will be used.
+ *
+ * @example
+ * ```typescript
+ * // In your app module or provider configuration:
+ * providers: [
+ *   {
+ *     provide: AXP_LOGIN_CHALLENGE_PROVIDER,
+ *     useClass: MyImageCaptchaProvider
+ *   }
+ * ]
+ *
+ * // In a component:
+ * private challengeProvider = inject(AXP_LOGIN_CHALLENGE_PROVIDER, { optional: true });
+ * ```
+ */
+const AXP_LOGIN_CHALLENGE_PROVIDER = new InjectionToken('AXP_LOGIN_CHALLENGE_PROVIDER');
+//#endregion
+
+//#region ----   Base Challenge Component   ----
+/**
+ * Base class for login challenge UI components
+ *
+ * Providers can extend this class to create custom challenge UIs.
+ * The login component will render this component and listen to its outputs.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'my-captcha-challenge',
+ *   template: `
+ *     <div class="captcha-container">
+ *       <img [src]="'data:image/png;base64,' + challengeData().content" />
+ *       <input
+ *         type="text"
+ *         [value]="response()"
+ *         (input)="onResponseChange($event)"
+ *       />
+ *       <button (click)="onRefreshClick()">Refresh</button>
+ *     </div>
+ *   `
+ * })
+ * export class MyCaptchaChallengeComponent extends AXPLoginChallengeComponentBase {
+ *   response = signal('');
+ *
+ *   onResponseChange(event: Event) {
+ *     const value = (event.target as HTMLInputElement).value;
+ *     this.response.set(value);
+ *     this.responseChange.emit(value);
+ *   }
+ *
+ *   onRefreshClick() {
+ *     this.refreshRequest.emit();
+ *   }
+ * }
+ * ```
+ */
+class AXPLoginChallengeComponentBase {
+    constructor() {
+        //#region ----   Inputs   ----
+        /**
+         * Challenge data to display
+         * Contains the image/content and metadata from the server
+         */
+        this.challengeData = input.required(...(ngDevMode ? [{ debugName: "challengeData" }] : []));
+        /**
+         * Whether the challenge is currently loading (e.g., refreshing)
+         */
+        this.isLoading = input(false, ...(ngDevMode ? [{ debugName: "isLoading" }] : []));
+        //#endregion
+        //#region ----   Outputs   ----
+        /**
+         * Emits when the user enters or changes their response
+         * The login component will capture this value and include it in credentials
+         */
+        this.responseChange = output();
+        /**
+         * Emits when the user requests a new challenge (e.g., clicks refresh button)
+         * The login component will call provider.refreshChallenge()
+         */
+        this.refreshRequest = output();
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPLoginChallengeComponentBase, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "20.3.12", type: AXPLoginChallengeComponentBase, isStandalone: true, selector: "ng-component", inputs: { challengeData: { classPropertyName: "challengeData", publicName: "challengeData", isSignal: true, isRequired: true, transformFunction: null }, isLoading: { classPropertyName: "isLoading", publicName: "isLoading", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { responseChange: "responseChange", refreshRequest: "refreshRequest" }, ngImport: i0, template: '', isInline: true }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.12", ngImport: i0, type: AXPLoginChallengeComponentBase, decorators: [{
+            type: Component,
+            args: [{
+                    template: '',
+                    standalone: true,
+                }]
+        }], propDecorators: { challengeData: [{ type: i0.Input, args: [{ isSignal: true, alias: "challengeData", required: true }] }], isLoading: [{ type: i0.Input, args: [{ isSignal: true, alias: "isLoading", required: false }] }], responseChange: [{ type: i0.Output, args: ["responseChange"] }], refreshRequest: [{ type: i0.Output, args: ["refreshRequest"] }] } });
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { AXPAuthGuard, AXPAuthModule, AXPAuthStrategy, AXPAuthStrategyRegistryService, AXPFeatureDirective, AXPFeatureGuard, AXPPermissionDefinitionBuilder, AXPPermissionDefinitionGroupBuilder, AXPPermissionDefinitionProviderContext, AXPPermissionDefinitionService, AXPPermissionDirective, AXPPermissionEvaluatorScopeProvider, AXPPermissionGuard, AXPSessionContext, AXPSessionService, AXPSessionStatus, AXPUnauthenticatedError, AXPUnauthorizedError, AXP_APPLICATION_LOADER, AXP_FEATURE_LOADER, AXP_PERMISSION_DEFINITION_PROVIDER, AXP_PERMISSION_LOADER, AXP_TENANT_LOADER, JwtUtil, PkceUtil, TimeUtil, initializeAppState };
+export { AXPAuthGuard, AXPAuthModule, AXPAuthStrategy, AXPAuthStrategyRegistryService, AXPFeatureDirective, AXPFeatureGuard, AXPLoginChallengeComponentBase, AXPLoginChallengeProvider, AXPPermissionDefinitionBuilder, AXPPermissionDefinitionGroupBuilder, AXPPermissionDefinitionProviderContext, AXPPermissionDefinitionService, AXPPermissionDirective, AXPPermissionEvaluatorScopeProvider, AXPPermissionGuard, AXPSessionContext, AXPSessionService, AXPSessionStatus, AXPUnauthenticatedError, AXPUnauthorizedError, AXP_APPLICATION_LOADER, AXP_FEATURE_LOADER, AXP_LOGIN_CHALLENGE_PROVIDER, AXP_PERMISSION_DEFINITION_PROVIDER, AXP_PERMISSION_LOADER, AXP_TENANT_LOADER, JwtUtil, PkceUtil, TimeUtil, initializeAppState };
 //# sourceMappingURL=acorex-platform-auth.mjs.map