@vc-shell/framework 1.1.98-rc.5 → 1.1.99-alpha.1

package/core/providers/README.md

@@ -0,0 +1,176 @@
+# Authentication Providers
+
+This directory contains authentication provider implementations for the vc-shell framework.
+
+## Overview
+
+The vc-shell framework uses a pluggable authentication system that allows you to implement custom authentication logic while maintaining compatibility with all framework pages (Login, ResetPassword, ChangePassword, Invite).
+
+## Available Providers
+
+### PlatformAuthProvider (Default)
+
+The default authentication provider that uses VirtoCommerce Platform API for authentication.
+
+```typescript
+import { PlatformAuthProvider } from "@vc-shell/framework";
+
+const authProvider = new PlatformAuthProvider();
+```
+
+This provider is used automatically if no custom provider is specified.
+
+## Creating a Custom Provider
+
+To create a custom authentication provider, implement the `IAuthProvider` interface:
+
+```typescript
+import { IAuthProvider, UserDetail, SignInResult } from "@vc-shell/framework";
+import { computed, ref } from "vue";
+
+export class CustomAuthProvider implements IAuthProvider {
+  private _user = ref<UserDetail | undefined>();
+  private _loading = ref(false);
+
+  get user() {
+    return computed(() => this._user.value);
+  }
+
+  get loading() {
+    return computed(() => this._loading.value);
+  }
+
+  get isAuthenticated() {
+    return computed(() => this._user.value?.userName != null);
+  }
+
+  get isAdministrator() {
+    return computed(() => this._user.value?.isAdministrator);
+  }
+
+  async loadUser(): Promise<UserDetail> {
+    // Your custom logic to load user
+    // Example: from localStorage, file, custom API, etc.
+  }
+
+  async signIn(username: string, password: string): Promise<SignInResult> {
+    // Your custom sign-in logic
+  }
+
+  async signOut(): Promise<void> {
+    // Your custom sign-out logic
+  }
+
+  // Implement other required methods...
+}
+```
+
+See `example-custom-auth-provider.ts` for a complete implementation example.
+
+## Required Methods
+
+All authentication providers must implement the following methods:
+
+### Core Methods
+- `loadUser()` - Load current authenticated user
+- `signIn(username, password)` - Authenticate user with credentials
+- `signOut()` - Sign out current user
+
+### Password Management Methods
+- `validateToken(userId, token)` - Validate password reset token
+- `validatePassword(password)` - Validate password strength
+- `resetPasswordByToken(userId, password, token)` - Reset password using token
+- `requestPasswordReset(loginOrEmail)` - Request password reset email
+- `changeUserPassword(oldPassword, newPassword)` - Change current user password
+
+### Additional Methods
+- `getLoginType()` - Get available login types (e.g., local, external)
+
+### Properties
+- `user` - Current user details (ComputedRef)
+- `loading` - Loading state (ComputedRef)
+- `isAuthenticated` - Authentication status (ComputedRef)
+- `isAdministrator` - Administrator status (ComputedRef)
+
+## Using a Custom Provider
+
+To use a custom authentication provider in your application:
+
+```typescript
+import VirtoShellFramework from "@vc-shell/framework";
+import { CustomAuthProvider } from "./auth/custom-provider";
+
+const app = createApp(App);
+const customAuthProvider = new CustomAuthProvider();
+
+app.use(VirtoShellFramework, {
+  router,
+  authProvider: customAuthProvider, // Pass your custom provider
+  i18n: {
+    locale: "en",
+    fallbackLocale: "en",
+  },
+});
+```
+
+## Type Safety
+
+All providers use the same types from the platform API:
+- `UserDetail` - User information
+- `SignInResult` - Sign-in result
+- `SecurityResult` - Security operation result
+- `IdentityResult` - Identity validation result
+- `LoginType` - Login type enumeration
+
+This ensures compatibility across all authentication pages and interceptors.
+
+## Integration with Framework
+
+The authentication provider integrates with:
+
+1. **Login Pages** - All auth pages (Login, ResetPassword, ChangePassword, Invite) automatically use the provided auth provider
+2. **HTTP Interceptors** - Automatically handles 401 errors and redirects to login
+3. **Route Guards** - Checks authentication status before route navigation
+4. **Composables** - Available via `useUser()` and `useUserManagement()` composables
+
+## Example Use Cases
+
+### File-based Authentication
+```typescript
+class FileAuthProvider implements IAuthProvider {
+  async signIn(username: string, password: string) {
+    const credentials = await fetch("/auth-data.json");
+    const users = await credentials.json();
+    // Validate against file data
+  }
+}
+```
+
+### Custom API Authentication
+```typescript
+class CustomApiAuthProvider implements IAuthProvider {
+  async signIn(username: string, password: string) {
+    const response = await fetch("https://my-custom-api.com/auth", {
+      method: "POST",
+      body: JSON.stringify({ username, password }),
+    });
+    // Handle custom API response
+  }
+}
+```
+
+### OAuth/OIDC Provider
+```typescript
+class OAuthAuthProvider implements IAuthProvider {
+  async signIn(username: string, password: string) {
+    // Redirect to OAuth provider
+    window.location.href = "https://oauth-provider.com/authorize";
+  }
+}
+```
+
+## Backward Compatibility
+
+If no custom provider is specified, the framework automatically uses `PlatformAuthProvider`, ensuring full backward compatibility with existing applications.
+
+

package/core/providers/auth-provider-manager.ts

@@ -0,0 +1,74 @@
+import { IAuthProvider } from "../types/auth-provider";
+import { PlatformAuthProvider } from "./platform-auth-provider";
+
+/**
+ * Global auth provider manager
+ * Provides access to auth provider before Vue app context is available
+ * This is necessary for early initialization scenarios where composables
+ * are called before app.use(VirtoShellFramework)
+ */
+class AuthProviderManager {
+  private provider: IAuthProvider | null = null;
+  private defaultProvider: IAuthProvider | null = null;
+  private configureWasCalled = false;
+
+  /**
+   * Set the global auth provider
+   * Should be called via VirtoShellFramework.configure() before any composables
+   * If custom provider is provided, it will replace the default
+   */
+  setProvider(provider: IAuthProvider): void {
+    console.log("[AuthProviderManager] Setting auth provider:", provider.constructor.name);
+    this.configureWasCalled = true;
+    this.provider = provider;
+  }
+
+  /**
+   * Get the global auth provider
+   * Lazy-initializes default PlatformAuthProvider if no custom provider was set
+   */
+  getProvider(): IAuthProvider {
+    // If custom provider was set, use it
+    if (this.provider) {
+      return this.provider;
+    }
+
+    // Lazy-initialize default platform provider only when needed (backward compatibility)
+    if (!this.defaultProvider) {
+      console.log("[AuthProviderManager] Lazy-initializing default PlatformAuthProvider");
+
+      // Show deprecation warning only if configure() was never called
+      if (!this.configureWasCalled) {
+        console.warn(
+          "[AuthProviderManager] DEPRECATION WARNING: " +
+          "Automatic PlatformAuthProvider creation will be removed in a future version. " +
+          "Please use VirtoShellFramework.configure({ authProvider }) explicitly before calling useUser()."
+        );
+      }
+
+      this.defaultProvider = new PlatformAuthProvider();
+    }
+
+    return this.defaultProvider;
+  }
+
+  /**
+   * Check if provider is available
+   */
+  hasProvider(): boolean {
+    return this.provider !== null || this.defaultProvider !== null;
+  }
+
+  /**
+   * Reset manager (for testing)
+   */
+  reset(): void {
+    this.provider = null;
+    this.defaultProvider = null;
+    this.configureWasCalled = false;
+  }
+}
+
+// Global singleton instance
+export const authProviderManager = new AuthProviderManager();
+

package/core/providers/auth-provider-utils.ts

@@ -0,0 +1,26 @@
+import { IAuthProvider } from "../types/auth-provider";
+import { PlatformAuthProvider } from "./platform-auth-provider";
+
+/**
+ * Check if the provider is a platform provider
+ * Centralized logic for determining platform-specific features availability
+ */
+export function isPlatformProvider(provider: IAuthProvider | null | undefined): boolean {
+  return provider instanceof PlatformAuthProvider;
+}
+
+/**
+ * Check if platform-specific features should be enabled
+ * This is the main function to use throughout the framework
+ */
+export function shouldEnablePlatformFeatures(provider: IAuthProvider | null | undefined): boolean {
+  return isPlatformProvider(provider);
+}
+
+/**
+ * Get a safe provider instance with fallback
+ * Handles null/undefined cases gracefully
+ */
+export function getSafeProvider(provider: IAuthProvider | null | undefined): IAuthProvider | null {
+  return provider || null;
+}

package/core/providers/example-custom-auth-provider.ts

@@ -0,0 +1,162 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Example Custom Authentication Provider
+ *
+ * This is an example implementation showing how to create a custom authentication provider.
+ * You can use this as a template to implement your own authentication logic.
+ *
+ * @example
+ * ```typescript
+ * import { CustomAuthProvider } from './auth/custom-provider';
+ *
+ * const customAuthProvider = new CustomAuthProvider();
+ *
+ * app.use(VirtoShellFramework, {
+ *   router,
+ *   authProvider: customAuthProvider,
+ *   i18n: { ... }
+ * });
+ * ```
+ */
+
+import { computed, Ref, ref, ComputedRef } from "vue";
+import {
+  UserDetail,
+  SecurityResult,
+  IdentityResult,
+  LoginType,
+  SignInResult,
+  IIdentityResult,
+} from "../api/platform";
+import { RequestPasswordResult } from "../types";
+import { IAuthProvider } from "../types/auth-provider";
+
+export class CustomAuthProvider implements IAuthProvider {
+
+  private _user: Ref<UserDetail | undefined> = ref();
+  private _loading: Ref<boolean> = ref(false);
+
+  get user(): ComputedRef<UserDetail | undefined> {
+    return computed(() => this._user.value);
+  }
+
+  get loading(): ComputedRef<boolean> {
+    return computed(() => this._loading.value);
+  }
+
+  get isAuthenticated(): ComputedRef<boolean> {
+    return computed(() => this._user.value?.userName != null);
+  }
+
+  get isAdministrator(): ComputedRef<boolean | undefined> {
+    return computed(() => this._user.value?.isAdministrator);
+  }
+
+  async loadUser(): Promise<UserDetail> {
+    // Implement your custom user loading logic
+    // Example: Load from localStorage, custom API, etc.
+    console.debug("[CustomAuthProvider] Loading user...");
+
+    this._loading.value = true;
+
+    try {
+      // Example: Load from localStorage
+      const storedUser = localStorage.getItem("customUser");
+      if (storedUser) {
+        this._user.value = JSON.parse(storedUser) as UserDetail;
+      }
+    } catch (e) {
+      console.error("Failed to load user:", e);
+    } finally {
+      this._loading.value = false;
+    }
+
+    return { ...this._user.value } as UserDetail;
+  }
+
+  async signIn(
+    username: string,
+    password: string,
+  ): Promise<SignInResult | { succeeded: boolean; error?: any; status?: number }> {
+    console.debug("[CustomAuthProvider] Signing in...");
+
+    this._loading.value = true;
+
+    try {
+      // Implement your custom sign-in logic
+      // Example: Validate against local file, custom API, etc.
+
+      // Example implementation:
+      if (username === "demo" && password === "demo") {
+        this._user.value = {
+          userName: username,
+          isAdministrator: true,
+          // ... other user properties
+        } as UserDetail;
+
+        // Store user in localStorage
+        localStorage.setItem("customUser", JSON.stringify(this._user.value));
+
+        return { succeeded: true } as SignInResult;
+      }
+
+      return { succeeded: false, error: "Invalid credentials" };
+    } catch (e: any) {
+      console.error("Sign in failed:", e);
+      return { succeeded: false, error: e.message };
+    } finally {
+      this._loading.value = false;
+    }
+  }
+
+  async signOut(): Promise<void> {
+    console.debug("[CustomAuthProvider] Signing out...");
+
+    this._user.value = undefined;
+    localStorage.removeItem("customUser");
+  }
+
+  async validateToken(userId: string, token: string): Promise<boolean> {
+    // Implement your custom token validation logic
+    console.debug("[CustomAuthProvider] Validating token...");
+    return false;
+  }
+
+  async validatePassword(password: string): Promise<IIdentityResult> {
+    // Implement your custom password validation logic
+    console.debug("[CustomAuthProvider] Validating password...");
+    return { succeeded: true } as IIdentityResult;
+  }
+
+  async resetPasswordByToken(
+    userId: string,
+    password: string,
+    token: string,
+  ): Promise<SecurityResult> {
+    // Implement your custom password reset logic
+    console.debug("[CustomAuthProvider] Resetting password...");
+    return { succeeded: true } as SecurityResult;
+  }
+
+  async requestPasswordReset(loginOrEmail: string): Promise<RequestPasswordResult> {
+    // Implement your custom password reset request logic
+    console.debug("[CustomAuthProvider] Requesting password reset...");
+    return { succeeded: true };
+  }
+
+  async changeUserPassword(
+    oldPassword: string,
+    newPassword: string,
+  ): Promise<SecurityResult | undefined> {
+    // Implement your custom password change logic
+    console.debug("[CustomAuthProvider] Changing password...");
+    return { succeeded: true } as SecurityResult;
+  }
+
+  async getLoginType(): Promise<LoginType[]> {
+    // Return supported login types for your custom provider
+    console.debug("[CustomAuthProvider] Getting login types...");
+    return [];
+  }
+}
+

package/core/providers/index.ts

@@ -0,0 +1,3 @@
+export { PlatformAuthProvider } from "./platform-auth-provider";
+export { authProviderManager } from "./auth-provider-manager";
+

package/core/providers/platform-auth-provider.ts

@@ -0,0 +1,207 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { computed, Ref, ref, ComputedRef } from "vue";
+import {
+  UserDetail,
+  SecurityClient,
+  ResetPasswordConfirmRequest,
+  SecurityResult,
+  ValidatePasswordResetTokenRequest,
+  IdentityResult,
+  ChangePasswordRequest,
+  LoginType,
+  LoginRequest,
+  SignInResult,
+  IIdentityResult,
+  ISecurityResult,
+} from "../api/platform";
+import { RequestPasswordResult } from "../types";
+import { useExternalProvider } from "../../shared/components/sign-in/useExternalProvider";
+import { IAuthProvider } from "../types/auth-provider";
+
+const DEMO_USER = {
+  id: "demo_user_id",
+  userName: "DEMO_USER",
+  isAdministrator: true,
+} as UserDetail;
+
+/**
+ * Platform-based authentication provider
+ * Implements authentication using VirtoCommerce Platform API
+ */
+export class PlatformAuthProvider implements IAuthProvider {
+  private _user: Ref<UserDetail | undefined> = ref();
+  private _loading: Ref<boolean> = ref(false);
+  private securityClient: SecurityClient;
+  private externalSignInStorage: ReturnType<typeof useExternalProvider>["storage"];
+  private externalSignOut: ReturnType<typeof useExternalProvider>["signOut"];
+
+  constructor() {
+    console.log("🔐 [PlatformAuthProvider] Constructor called - using PLATFORM authentication");
+    this.securityClient = new SecurityClient();
+    const { storage, signOut } = useExternalProvider();
+    this.externalSignInStorage = storage;
+    this.externalSignOut = signOut;
+  }
+
+  get user(): ComputedRef<UserDetail | undefined> {
+    return computed(() => this._user.value);
+  }
+
+  get loading(): ComputedRef<boolean> {
+    return computed(() => this._loading.value);
+  }
+
+  get isAuthenticated(): ComputedRef<boolean> {
+    return computed(() => this._user.value?.userName != null);
+  }
+
+  get isAdministrator(): ComputedRef<boolean | undefined> {
+    return computed(() => this._user.value?.isAdministrator);
+  }
+
+  async validateToken(userId: string, token: string): Promise<boolean> {
+    let result = false;
+    try {
+      this._loading.value = true;
+      result = await this.securityClient.validatePasswordResetToken(userId, {
+        token,
+      } as ValidatePasswordResetTokenRequest);
+    } catch (e) {
+      //TODO: log error
+    } finally {
+      this._loading.value = false;
+    }
+    return result;
+  }
+
+  async validatePassword(password: string): Promise<IIdentityResult> {
+    return this.securityClient.validatePassword(password) as Promise<IIdentityResult>;
+  }
+
+  async resetPasswordByToken(userId: string, password: string, token: string): Promise<ISecurityResult> {
+    return this.securityClient.resetPasswordByToken(userId, {
+      newPassword: password,
+      token,
+    } as ResetPasswordConfirmRequest);
+  }
+
+  async signIn(
+    username: string,
+    password: string,
+  ): Promise<SignInResult | { succeeded: boolean; error?: any; status?: number }> {
+    console.debug(`[@vc-shell/framework#PlatformAuthProvider:signIn] - Entry point`);
+
+    // Handle demo mode for platform provider
+    if (window.__DEMO_MODE__) {
+      console.warn("[PlatformAuthProvider] Running in DEMO mode - authentication is mocked");
+      this._user.value = DEMO_USER as UserDetail;
+      return { succeeded: true } as SignInResult;
+    }
+
+    try {
+      this._loading.value = true;
+      const result = await this.securityClient.login(new LoginRequest({ userName: username, password }));
+      return await this.securityClient
+        .getCurrentUser()
+        .then((res) => {
+          if (res) {
+            this._user.value = res;
+            return result;
+          }
+          throw { succeeded: false };
+        })
+        .catch((e) => {
+          throw e;
+        });
+    } catch (e: any) {
+      //TODO: log error
+      console.log(e);
+      return { succeeded: false, error: e.message, status: e.status };
+    } finally {
+      this._loading.value = false;
+    }
+  }
+
+  async signOut(): Promise<void> {
+    console.debug(`[@vc-shell/framework#PlatformAuthProvider:signOut] - Entry point`);
+
+    this._user.value = undefined;
+
+    if (this.externalSignInStorage.value?.providerType) {
+      await this.externalSignOut(this.externalSignInStorage.value.providerType);
+    } else {
+      this.securityClient.logout();
+    }
+  }
+
+  async loadUser(): Promise<UserDetail> {
+    console.debug(`[@vc-shell/framework#PlatformAuthProvider:loadUser] - Entry point`);
+
+    // Handle demo mode for platform provider
+    if (window.__DEMO_MODE__) {
+      console.warn(
+        "[PlatformAuthProvider] Running in DEMO mode. All API calls are disabled. Please add APP_PLATFORM_URL to your application's .env file to enable API calls.",
+      );
+      this._user.value = DEMO_USER as UserDetail;
+      return { ...this._user.value } as UserDetail;
+    }
+
+    try {
+      this._loading.value = true;
+      this._user.value = await this.securityClient.getCurrentUser();
+      console.log("[PlatformAuthProvider]: an user details has been loaded", this._user.value);
+    } catch (e: any) {
+      console.error(e);
+    } finally {
+      this._loading.value = false;
+    }
+
+    return { ...this._user.value } as UserDetail;
+  }
+
+  async requestPasswordReset(loginOrEmail: string): Promise<RequestPasswordResult> {
+    try {
+      this._loading.value = true;
+      await this.securityClient.requestPasswordReset(loginOrEmail);
+      return { succeeded: true };
+    } catch (e) {
+      //TODO: log error
+      return { succeeded: false, error: e as string };
+    } finally {
+      this._loading.value = false;
+    }
+  }
+
+  async changeUserPassword(oldPassword: string, newPassword: string): Promise<SecurityResult | undefined> {
+    let result;
+
+    try {
+      this._loading.value = true;
+      const command = new ChangePasswordRequest({
+        oldPassword,
+        newPassword,
+      });
+
+      result = await this.securityClient.changeCurrentUserPassword(command);
+    } catch (e: any) {
+      return { succeeded: false, errors: [e.message] } as SecurityResult;
+    } finally {
+      this._loading.value = false;
+    }
+
+    return result;
+  }
+
+  async getLoginType(): Promise<LoginType[]> {
+    let result: LoginType[] | null = null;
+    try {
+      result = await this.securityClient.getLoginTypes();
+    } catch (e) {
+      console.error(e);
+      throw e;
+    }
+
+    return result;
+  }
+}
+

package/core/types/auth-provider.ts

@@ -0,0 +1,40 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ComputedRef } from "vue";
+import {
+  SignInResult,
+  IUserDetail,
+  ISecurityResult,
+  ILoginType,
+  IIdentityResult,
+} from "../api/platform";
+import { RequestPasswordResult } from "./index";
+
+/**
+ * Interface for authentication provider
+ * Allows custom authentication implementations while maintaining compatibility with all framework pages
+ */
+export interface IAuthProvider {
+  // Core properties
+  user: ComputedRef<IUserDetail | undefined>;
+  loading: ComputedRef<boolean>;
+  isAuthenticated: ComputedRef<boolean>;
+  isAdministrator: ComputedRef<boolean | undefined>;
+
+  // Core methods
+  loadUser(): Promise<IUserDetail>;
+  signIn(
+    username: string,
+    password: string,
+  ): Promise<SignInResult | { succeeded: boolean; error?: any; status?: number }>;
+  signOut(): Promise<void>;
+
+  // Password management methods
+  validateToken(userId: string, token: string): Promise<boolean>;
+  validatePassword(password: string): Promise<IIdentityResult>;
+  resetPasswordByToken(userId: string, password: string, token: string): Promise<ISecurityResult>;
+  requestPasswordReset(loginOrEmail: string): Promise<RequestPasswordResult>;
+  changeUserPassword(oldPassword: string, newPassword: string): Promise<ISecurityResult | undefined>;
+
+  // Additional methods
+  getLoginType(): Promise<ILoginType[]>;
+}

package/core/types/index.ts

@@ -233,3 +233,5 @@ export interface MenuItemConfig {
   inGroupPriority?: number;
   permissions?: string | string[];
 }
+
+export * from "./auth-provider";