@flusys/ng-auth 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -0,0 +1,775 @@
+# @flusys/ng-auth Package Guide
+
+## Overview
+
+`@flusys/ng-auth` provides complete authentication functionality including login, registration, token management, company/branch selection, user administration, and permission handling.
+
+**Package:** `@flusys/ng-auth`
+**Dependencies:** ng-core, ng-shared, ng-layout
+**Build:** `npm run build:ng-auth`
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        ng-auth                               │
+├─────────────────────────────────────────────────────────────┤
+│  Services                                                    │
+│  ├── AuthApiService      (login, register, refresh, logout) │
+│  ├── AuthStateService    (signal-based state management)    │
+│  ├── AuthInitService     (session restoration on refresh)   │
+│  ├── TokenRefreshStateService (concurrent refresh handling) │
+│  ├── UserApiService      (user CRUD)                        │
+│  ├── CompanyApiService   (company CRUD)                     │
+│  ├── BranchApiService    (branch CRUD)                      │
+│  └── UserPermissionApiService (permission assignments)      │
+├─────────────────────────────────────────────────────────────┤
+│  Guards                                                      │
+│  ├── authGuard           (requires authentication)          │
+│  ├── guestGuard          (allows only unauthenticated)      │
+│  └── companyFeatureGuard (requires company feature enabled) │
+├─────────────────────────────────────────────────────────────┤
+│  Interceptors                                                │
+│  ├── authInterceptor     (adds JWT + tenant headers)        │
+│  └── tokenRefreshInterceptor (handles 401 + token refresh)  │
+├─────────────────────────────────────────────────────────────┤
+│  Adapters (Provider Interface Pattern)                       │
+│  ├── AuthLayoutStateAdapter  → LAYOUT_AUTH_STATE            │
+│  ├── AuthLayoutApiAdapter    → LAYOUT_AUTH_API              │
+│  ├── AuthUserProviderAdapter → USER_PROVIDER                │
+│  ├── AuthCompanyApiProviderAdapter → COMPANY_API_PROVIDER   │
+│  └── AuthUserPermissionProviderAdapter → USER_PERMISSION_PROVIDER │
+├─────────────────────────────────────────────────────────────┤
+│  Constants                                                   │
+│  └── AUTH_ENDPOINTS          (endpoint path definitions)    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Services
+
+### AuthApiService
+
+HTTP client for authentication endpoints.
+
+```typescript
+import { AuthApiService } from '@flusys/ng-auth';
+
+const authApi = inject(AuthApiService);
+
+// Authentication
+authApi.login({ email, password });           // POST /auth/login
+authApi.register({ name, email, password });  // POST /auth/register
+authApi.refresh();                            // POST /auth/refresh
+authApi.logout();                             // POST /auth/logout
+authApi.me();                                 // GET /auth/me
+
+// Company/Branch selection
+authApi.select({ companyId, branchId, sessionId });  // POST /auth/select
+authApi.switchCompany({ companyId, branchId });      // POST /auth/switch-company
+
+// Password management
+authApi.changePassword({ currentPassword, newPassword });
+authApi.forgotPassword({ email });
+authApi.resetPassword({ token, newPassword });
+```
+
+### AuthStateService
+
+Signal-based centralized auth state management with auto-persistence.
+
+```typescript
+import { AuthStateService } from '@flusys/ng-auth';
+
+const authState = inject(AuthStateService);
+
+// Read-only signals
+authState.user();                    // Signal<IUserInfo | null>
+authState.accessToken();             // Signal<string | null>
+authState.company();                 // Signal<ICompanyInfo | null>
+authState.branch();                  // Signal<IBranchInfo | null>
+authState.availableCompanies();      // Signal<ICompanyWithBranches[]>
+authState.selectionSessionId();      // Signal<string | null>
+
+// Computed signals
+authState.isAuthenticated();         // Signal<boolean>
+authState.requiresCompanySelection(); // Signal<boolean>
+authState.userName();                // Signal<string>
+authState.companyName();             // Signal<string>
+authState.branchName();              // Signal<string>
+authState.tenantId();                // Signal<string | null>
+
+// State mutations
+authState.setLoginState(response);   // After successful login
+authState.setSelectionState(response); // After company/branch selection
+authState.clearSelectionState();     // Clear pending selection
+authState.resetState();              // Full logout
+authState.navigateToLogin(returnUrl?);
+authState.navigateAfterLogin();
+```
+
+**Auto-persistence:** Tokens and company/branch IDs are automatically saved to localStorage via effects.
+
+### AuthInitService
+
+Handles session restoration on page refresh.
+
+```typescript
+import { AuthInitService } from '@flusys/ng-auth';
+
+const authInit = inject(AuthInitService);
+
+// Signals
+authInit.initialized();  // Signal<boolean>
+authInit.loading();      // Signal<boolean>
+authInit.error();        // Signal<string | null>
+
+// Restore session (called by appInitGuard)
+authInit.initialize().subscribe({
+  next: (user) => console.log('Session restored:', user),
+  error: (err) => console.log('No session or expired')
+});
+```
+
+**Flow:**
+1. Attempts `POST /auth/refresh` with httpOnly cookie
+2. On success, calls `GET /auth/me` to get user info
+3. Updates AuthStateService with restored session
+4. Caches result to prevent duplicate calls
+
+### Resource API Services
+
+All extend `ApiResourceService` from ng-shared with signal-based state.
+
+```typescript
+import { UserApiService, CompanyApiService, BranchApiService } from '@flusys/ng-auth';
+
+// Common signals (from ApiResourceService)
+service.data();      // Signal<T[]>
+service.isLoading(); // Signal<boolean>
+service.error();     // Signal<string | null>
+
+// Common methods
+await service.insertAsync(data);        // Create
+await service.updateAsync(data);        // Update
+await service.deleteAsync(id);          // Delete
+await service.fetchByIdAsync(id);       // Get one
+service.fetchList(search, options);     // Get list with pagination
+```
+
+**UserApiService** - Endpoint: `administration/users`
+```typescript
+userApi.verifyEmail(userId);
+userApi.verifyPhone(userId);
+userApi.updateStatus(userId, status);
+userApi.updateProfile(data);
+```
+
+**CompanyApiService** - Endpoint: `administration/company`
+
+**BranchApiService** - Endpoint: `administration/branch`
+```typescript
+branchApi.currentCompanyId();     // Signal for company context
+branchApi.companyBranches();      // Computed: branches filtered by company
+branchApi.setCurrentCompanyId(id);
+branchApi.insertBranch(data);     // Auto-sets companyId
+branchApi.fetchByCompany(companyId);
+```
+
+### UserPermissionApiService
+
+Manages user-to-company and user-to-branch permission assignments.
+
+```typescript
+import { UserPermissionApiService } from '@flusys/ng-auth';
+
+const permApi = inject(UserPermissionApiService);
+
+// Company permissions
+permApi.assignUserCompanies({
+  userId: 'user-1',
+  items: [
+    { targetId: 'company-1', isAdd: true },   // Assign
+    { targetId: 'company-2', isAdd: false }   // Revoke
+  ]
+});
+permApi.getUserCompanies(userId);             // Get user's companies
+permApi.assignUserToCompany(userId, companyId);   // Single assign
+permApi.revokeUserFromCompany(userId, companyId); // Single revoke
+
+// Branch permissions
+permApi.assignUserBranches({
+  userId: 'user-1',
+  items: [
+    { targetId: 'branch-1', isAdd: true }
+  ]
+});
+permApi.getUserBranches(userId);              // Get user's branches
+permApi.assignUserToBranch(userId, branchId);
+permApi.revokeUserFromBranch(userId, branchId);
+```
+
+**Backend Endpoints:**
+- `POST /administration/permissions/user-company/assign`
+- `GET /administration/permissions/user-company?userId=xxx`
+- `POST /administration/permissions/user-branch/assign`
+- `GET /administration/permissions/user-branch?userId=xxx`
+
+---
+
+## Guards
+
+### authGuard
+
+Protects routes requiring authentication.
+
+```typescript
+import { authGuard } from '@flusys/ng-auth';
+
+{
+  path: 'dashboard',
+  canActivate: [authGuard],
+  loadComponent: () => import('./dashboard.component')
+}
+```
+
+**Checks:**
+1. User is authenticated
+2. If company feature enabled: company AND branch are selected
+3. Redirects to `/auth/login` with `returnUrl` if checks fail
+
+### guestGuard
+
+Protects auth routes (login, register) from authenticated users.
+
+```typescript
+import { guestGuard } from '@flusys/ng-auth';
+
+{
+  path: 'auth/login',
+  canActivate: [guestGuard],
+  loadComponent: () => import('./login.component')
+}
+```
+
+**Behavior:**
+1. Restores session via `AuthInitService.initialize()` first
+2. If authenticated AND company selected: redirects to home or returnUrl
+3. If selection pending: allows access (login handles Step 2)
+4. If not authenticated: allows access
+
+### companyFeatureGuard
+
+Enables/disables company management routes based on config.
+
+```typescript
+import { companyFeatureGuard } from '@flusys/ng-auth';
+
+{
+  path: 'administration/company',
+  canActivate: [authGuard, companyFeatureGuard],
+  loadComponent: () => import('./company-list.component')
+}
+```
+
+**Checks:** `services.auth.enabled` in APP_CONFIG. Redirects to `/` if disabled.
+
+---
+
+## Interceptors
+
+### authInterceptor
+
+Adds authentication headers to HTTP requests.
+
+```typescript
+import { authInterceptor } from '@flusys/ng-auth';
+
+provideHttpClient(
+  withInterceptors([authInterceptor, ...])
+)
+```
+
+**Adds:**
+- `Authorization: Bearer {token}` if token exists
+- Tenant header if multi-tenant enabled
+- `withCredentials: true` for auth endpoints (cookie support)
+
+### tokenRefreshInterceptor
+
+Handles 401 responses and token refresh.
+
+```typescript
+import { tokenRefreshInterceptor } from '@flusys/ng-auth';
+
+provideHttpClient(
+  withInterceptors([authInterceptor, tokenRefreshInterceptor, ...])
+)
+```
+
+**Behavior:**
+1. Intercepts 401 Unauthorized responses
+2. Skips refresh for: `/auth/refresh`, `/auth/login`, `/auth/register`, `/auth/select`
+3. Uses `TokenRefreshStateService` to queue concurrent requests during refresh
+4. On success: updates token, retries original request
+5. On failure: logs out, shows error, redirects to login
+
+---
+
+## Constants
+
+### AUTH_ENDPOINTS
+
+Centralized endpoint definitions used by interceptors.
+
+```typescript
+import { AUTH_ENDPOINTS, isAuthEndpoint, isEndpoint } from '@flusys/ng-auth';
+
+// Endpoint constants
+AUTH_ENDPOINTS.LOGIN          // '/auth/login'
+AUTH_ENDPOINTS.LOGOUT         // '/auth/logout'
+AUTH_ENDPOINTS.REFRESH        // '/auth/refresh'
+AUTH_ENDPOINTS.REGISTER       // '/auth/register'
+AUTH_ENDPOINTS.SELECT         // '/auth/select'
+AUTH_ENDPOINTS.SWITCH_COMPANY // '/auth/switch-company'
+
+// Helper functions
+isAuthEndpoint(url);           // Check if URL is any auth endpoint
+isEndpoint(url, endpoint);     // Check if URL matches specific endpoint
+```
+
+---
+
+## Provider Adapters
+
+ng-auth implements provider interfaces from ng-shared, enabling ng-iam and ng-storage to access auth data without direct dependencies.
+
+### provideAuthProviders()
+
+Registers provider adapters for ng-iam/ng-storage.
+
+```typescript
+import { provideAuthProviders } from '@flusys/ng-auth';
+
+// app.config.ts
+providers: [
+  ...provideAuthProviders()
+]
+```
+
+**Registers:**
+- `USER_PROVIDER` → `AuthUserProviderAdapter` (user list for ng-iam)
+- `COMPANY_API_PROVIDER` → `AuthCompanyApiProviderAdapter` (company list for ng-iam)
+- `USER_PERMISSION_PROVIDER` → `AuthUserPermissionProviderAdapter` (permission queries)
+
+### provideAuthLayoutIntegration()
+
+Bridges ng-auth to ng-layout components.
+
+```typescript
+import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
+
+// app.config.ts
+providers: [
+  ...provideAuthLayoutIntegration()
+]
+```
+
+**Registers:**
+- `LAYOUT_AUTH_STATE` → `AuthLayoutStateAdapter` (user/company/branch signals)
+- `LAYOUT_AUTH_API` → `AuthLayoutApiAdapter` (logout, switch company, etc.)
+
+**AuthLayoutApiAdapter Methods:**
+```typescript
+logOut();
+navigateLogin(withUrl?: boolean);
+switchCompany(companyId, branchId);  // Triggers page reload
+getUserCompanies();                   // User's permitted companies
+getCompanyBranches(companyId);        // User's permitted branches
+```
+
+---
+
+## Pages
+
+### Authentication Pages
+
+**LoginPageComponent** (`/auth/login`)
+- Multi-step login: Step 1 = credentials, Step 2 = company/branch selection (if needed)
+- Visual step indicator
+- Auto-selects if only one company/branch available
+- Stores returnUrl for post-login redirect
+
+**RegisterPageComponent** (`/auth/register`)
+- User registration with optional company creation
+- Email/password validation
+- Terms acceptance
+
+### Administration Pages
+
+**AdministrationPageComponent** (`/administration`)
+- Tabbed interface: Users, Companies, Branches
+- Company/Branch tabs require company feature enabled
+
+**User Management:**
+- `UserListComponent` - LazyLoad datatable with Edit, Delete, Permission actions
+- `UserFormComponent` - Create/edit user form
+
+**Company Management:**
+- `CompanyListComponent` - Company CRUD
+- `CompanyFormComponent` - Create/edit company
+
+**Branch Management:**
+- `BranchListComponent` - Branch CRUD filtered by company
+- `BranchFormComponent` - Create/edit branch
+
+---
+
+## Dialog Components
+
+### UserCompanyPermissionDialogComponent
+
+Manages user-to-company assignments with checkboxes.
+
+```typescript
+import { UserCompanyPermissionDialogComponent } from '@flusys/ng-auth';
+
+@Component({
+  imports: [UserCompanyPermissionDialogComponent],
+  template: `
+    <lib-user-company-permission-dialog
+      [visible]="showDialog()"
+      [user]="selectedUser()"
+      (closed)="showDialog.set(false)"
+      (permissionsChanged)="reloadData()" />
+  `
+})
+```
+
+**Features:**
+- Shows all companies with checkboxes
+- Pre-checks assigned companies
+- Immediate save on toggle (no Save button)
+- Toast notifications for success/error
+
+### UserBranchPermissionDialogComponent
+
+Manages user-to-branch assignments with company filtering.
+
+```typescript
+import { UserBranchPermissionDialogComponent } from '@flusys/ng-auth';
+
+@Component({
+  imports: [UserBranchPermissionDialogComponent],
+  template: `
+    <lib-user-branch-permission-dialog
+      [visible]="showDialog()"
+      [user]="selectedUser()"
+      (closed)="showDialog.set(false)"
+      (permissionsChanged)="reloadData()" />
+  `
+})
+```
+
+**Features:**
+- Shows only companies where user has company-level permissions
+- User selects company → branches load
+- Immediate save on toggle
+- Scoped to user's permitted companies
+
+**Workflow:**
+1. Dialog opens → Loads user's permitted companies
+2. User selects company → Loads branches for that company
+3. User toggles branch checkboxes → Immediately assigns/revokes
+
+---
+
+## Routes
+
+### AUTH_ROUTES
+
+Public authentication routes.
+
+```typescript
+import { AUTH_ROUTES } from '@flusys/ng-auth';
+
+// Routes: /auth/login, /auth/register
+{ path: 'auth', children: AUTH_ROUTES }
+```
+
+### ADMINISTRATION_ROUTES
+
+Protected administration routes.
+
+```typescript
+import { ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
+
+// Routes: /administration/users/*, /administration/company/*, /administration/branch/*
+{
+  path: 'administration',
+  canActivate: [authGuard],
+  children: ADMINISTRATION_ROUTES
+}
+```
+
+---
+
+## Setup
+
+### app.config.ts
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
+import { APP_CONFIG, errorCatchingInterceptor } from '@flusys/ng-core';
+import {
+  authInterceptor,
+  tokenRefreshInterceptor,
+  provideAuthLayoutIntegration,
+  provideAuthProviders
+} from '@flusys/ng-auth';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withFetch(),
+      withInterceptors([
+        authInterceptor,
+        tokenRefreshInterceptor,
+        errorCatchingInterceptor
+      ])
+    ),
+    { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
+    ...provideAuthLayoutIntegration(),
+    ...provideAuthProviders()
+  ]
+};
+```
+
+### app.routes.ts
+
+```typescript
+import { Routes } from '@angular/router';
+import { authGuard, guestGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
+
+export const routes: Routes = [
+  { path: 'auth', children: AUTH_ROUTES },
+  {
+    path: '',
+    canActivate: [authGuard],
+    children: [
+      { path: 'dashboard', loadComponent: () => import('./dashboard.component') },
+      { path: 'administration', children: ADMINISTRATION_ROUTES }
+    ]
+  }
+];
+```
+
+---
+
+## Interfaces
+
+### Request DTOs
+
+```typescript
+interface ILoginRequest { email: string; password: string; }
+interface IRegistrationRequest { name: string; email: string; password: string; phone?: string; }
+interface ISelectRequest { companyId: string; branchId?: string; sessionId: string; }
+interface ISwitchCompanyRequest { companyId: string; branchId: string; }
+interface IChangePasswordRequest { currentPassword: string; newPassword: string; }
+```
+
+### Response DTOs
+
+```typescript
+interface ILoginResponse {
+  accessToken: string;
+  user: IUserInfo;
+  requiresSelection?: boolean;
+  sessionId?: string;
+  companies?: ICompanyWithBranches[];
+  expiresAt?: number;
+}
+
+interface ICompanySelectionResponse {
+  accessToken: string;
+  user: IUserInfo;
+  company: ICompanyInfo;
+  branch: IBranchInfo;
+}
+
+interface IMeResponse extends IUserInfo {}
+interface IRefreshTokenResponse { accessToken: string; }
+```
+
+### Entity DTOs
+
+```typescript
+interface IUser {
+  id: string;
+  name: string;
+  email: string;
+  phone?: string;
+  profilePictureId?: string;
+  isActive: boolean;
+  isEmailVerified: boolean;
+  isPhoneVerified: boolean;
+  lastLoginAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface ICompany {
+  id: string;
+  name: string;
+  slug: string;
+  logoId?: string;
+  address?: string;
+  phone?: string;
+  email?: string;
+  website?: string;
+  isActive: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface IBranch {
+  id: string;
+  name: string;
+  slug: string;
+  companyId: string;
+  parentId?: string;
+  logoId?: string;
+  address?: string;
+  phone?: string;
+  email?: string;
+  isActive: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### Permission DTOs
+
+```typescript
+interface IPermissionItem { targetId: string; isAdd: boolean; }
+interface IAssignUserCompanyRequest { userId: string; items: IPermissionItem[]; }
+interface IAssignUserBranchRequest { userId: string; items: IPermissionItem[]; }
+interface IBatchOperationResponse { success: boolean; message: string; }
+interface IUserCompanyPermission { id: string; userId: string; companyId: string; companyName: string; companySlug: string; }
+interface IUserBranchPermission { id: string; userId: string; branchId: string; branchName: string; branchSlug: string; companyId: string; }
+```
+
+---
+
+## Best Practices
+
+### Component Organization
+
+```
+projects/ng-auth/
+├── components/                    ← Shared dialogs
+│   ├── user-company-permission-dialog.component.ts
+│   └── user-branch-permission-dialog.component.ts
+├── pages/                         ← Route-specific pages
+│   ├── login/
+│   ├── register/
+│   └── users/
+├── services/
+├── guards/
+├── interceptors/
+└── adapters/
+```
+
+**Rule:** Dialog components go in `components/`, page components go in `pages/`.
+
+### Permission Filtering Pattern
+
+When building permission UI, filter by user's permitted scope:
+
+```typescript
+// ✅ CORRECT - Filter by user's permitted companies
+const response = await firstValueFrom(permApi.getUserCompanies(userId));
+const userCompanies = response.data;
+
+// ❌ WRONG - Don't show all companies
+const allCompanies = await companyApi.fetchList(); // Security risk
+```
+
+### Token Management
+
+- Use httpOnly cookies for refresh tokens (backend)
+- Access tokens stored in memory via AuthStateService
+- TokenRefreshInterceptor handles automatic refresh
+- Auto-persistence for company/branch selection
+
+### Multi-Company Flow
+
+1. Login → Check if `requiresSelection: true`
+2. If yes → Show Step 2 (company/branch selection)
+3. Auto-select if only one company/branch
+4. Save selection → Navigate to dashboard
+
+---
+
+## Common Issues
+
+### Guards Not Working
+
+**Problem:** Routes accessible without authentication.
+
+**Solution:** Ensure authGuard is on parent route and session is restored:
+```typescript
+{
+  path: '',
+  canActivate: [authGuard],  // Parent guard
+  children: [...]
+}
+```
+
+### Token Not Sent
+
+**Problem:** 401 on all requests.
+
+**Solution:** Ensure interceptor order is correct:
+```typescript
+withInterceptors([
+  authInterceptor,         // First: adds token
+  tokenRefreshInterceptor, // Second: handles 401
+  errorCatchingInterceptor // Last: shows errors
+])
+```
+
+### Layout Not Showing User
+
+**Problem:** User info missing from topbar.
+
+**Solution:** Ensure layout integration is provided:
+```typescript
+providers: [
+  ...provideAuthLayoutIntegration()
+]
+```
+
+### Company Switcher Shows All Companies
+
+**Problem:** Switcher shows companies user doesn't have access to.
+
+**Solution:** `AuthLayoutApiAdapter.getUserCompanies()` uses `UserPermissionApiService.getUserCompanies(userId)` internally - ensure user has company permissions assigned.
+
+---
+
+## See Also
+
+- [CORE-GUIDE.md](./CORE-GUIDE.md) - APP_CONFIG configuration
+- [SHARED-GUIDE.md](./SHARED-GUIDE.md) - Provider interfaces
+- [LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md) - Layout integration
+- [IAM-GUIDE.md](./IAM-GUIDE.md) - Permission management
+- [../FLUSYS_NEST/docs/AUTH-GUIDE.md](../../FLUSYS_NEST/docs/AUTH-GUIDE.md) - Backend auth module
+
+---
+
+**Last Updated:** 2026-02-07
+**Package Version:** 1.0.1
+**Angular Version:** 21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/ng-auth",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Authentication module for FLUSYS Angular applications",
   "license": "MIT",
   "peerDependencies": {
@@ -8,9 +8,9 @@
     "@angular/core": "^21.0.0",
     "@angular/forms": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@flusys/ng-core": "^0.1.0-beta.1",
-    "@flusys/ng-layout": "^0.1.0-beta.1",
-    "@flusys/ng-shared": "^0.1.0-beta.1",
+    "@flusys/ng-core": "^0.1.0-beta.3",
+    "@flusys/ng-layout": "^0.1.0-beta.3",
+    "@flusys/ng-shared": "^0.1.0-beta.3",
     "@primeuix/themes": "^1.0.0",
     "primeicons": "^7.0.0",
     "primeng": "^21.0.0"