@tstdl/base 0.93.139 → 0.93.141

package/audit/module.js

@@ -1,5 +1,5 @@
 import { inject, Injector } from '../injector/index.js';
-import { Database, migrate } from '../orm/server/index.js';
+import { Database, migrate, registerDatabaseMigration } from '../orm/server/index.js';
 /**
  * Configuration for {@link configureAudit}.
  */
@@ -9,6 +9,11 @@ export class AuditModuleConfig {
      * If not provided, the global database configuration is used.
      */
     database;
+    /**
+     * Whether to automatically run database migrations when the application starts.
+     * Defaults to `true`.
+     */
+    autoMigrate;
 }
 /**
  * Configures audit server services.
@@ -17,6 +22,9 @@ export class AuditModuleConfig {
 export function configureAudit({ injector, ...config } = {}) {
     const targetInjector = injector ?? Injector;
     targetInjector.register(AuditModuleConfig, { useValue: config });
+    if (config.autoMigrate != false) {
+        registerDatabaseMigration('Audit', migrateAuditSchema, { injector });
+    }
 }
 /**
  * Migrates the audit database schema to the latest version.

package/authentication/README.md

@@ -0,0 +1,288 @@
+# @tstdl/base/authentication
+
+A comprehensive, secure, and type-safe authentication module providing JWT-based session management, credential handling, and extensible hooks for both server and client environments.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Subject System](#subject-system)
+  - [Server-Side Architecture](#server-side-architecture)
+  - [Client-Side Architecture](#client-side-architecture)
+  - [Extensibility Hooks](#extensibility-hooks)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Server Setup](#server-setup)
+  - [Client Setup](#client-setup)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Custom Token Payloads & Authentication Data](#custom-token-payloads--authentication-data)
+  - [Impersonation](#impersonation)
+  - [Secret Validation](#secret-validation)
+  - [HTTP Client Middleware](#http-client-middleware)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Full-Stack Solution**: Provides synchronized services for both Node.js servers and browser clients.
+- **Secure by Design**: Uses PBKDF2 for password hashing, secure random salts, and timing-safe comparisons.
+- **JWT Sessions**: Implements access tokens (short-lived) and refresh tokens (long-lived, database-backed) with automatic rotation.
+- **Reactive Client State**: The client service exposes authentication state (token, session, subject) via Signals and RxJS Observables.
+- **Impersonation**: Built-in support for administrators to securely log in as other users.
+- **Subject Diversity**: Supports `User`, `ServiceAccount`, and `SystemAccount` types out of the box.
+- **Secret Management**: Includes flows for changing passwords and secure, token-based password resets.
+- **Audit Logging**: Automatically logs security events (login success/failure, password changes) via the `@tstdl/base/audit` system.
+- **Extensible**: Abstract classes allow you to inject custom logic for subject resolution, token payload enrichment, and permission checks.
+
+## Core Concepts
+
+### Subject System
+
+The module uses a polymorphic `Subject` system to represent different types of entities that can authenticate:
+
+- **User**: A human user belonging to a tenant.
+- **ServiceAccount**: A non-human account, typically for API integrations.
+- **SystemAccount**: A built-in system account for internal tasks.
+
+### Server-Side Architecture
+
+The server component revolves around the `AuthenticationService`. It handles:
+
+- **Credential Storage**: Manages the `AuthenticationCredentials` entity (subject, hash, salt).
+- **Session Tracking**: Manages the `AuthenticationSession` entity, allowing for server-side session revocation.
+- **Token Issuance**: Generates signed JWTs using configured secrets.
+- **Validation**: Verifies tokens and handles the refresh flow.
+
+### Client-Side Architecture
+
+The `AuthenticationClientService` manages the lifecycle in the browser:
+
+- **Storage**: Persists tokens securely in `localStorage`.
+- **Auto-Refresh**: Automatically refreshes the access token before expiration using a synchronized lock mechanism (works across tabs).
+- **State**: Provides reactive signals like `isLoggedIn`, `token`, and `subjectId`.
+
+### Extensibility Hooks
+
+To integrate this module with your application, implement the `AuthenticationAncillaryService`. This service bridges generic authentication logic with your domain-specific subjects (Users, etc.).
+
+## 🚀 Basic Usage
+
+### Server Setup
+
+1.  **Implement the Ancillary Service**
+    Create a service to resolve subjects and define token payloads.
+
+    ```typescript
+    import { AuthenticationAncillaryService, type GetTokenPayloadContext } from '@tstdl/base/authentication/server';
+    import { Subject, type SubjectInput, User } from '@tstdl/base/authentication';
+    import { Singleton, inject } from '@tstdl/base/injector';
+    import { UserService } from './user.service.js';
+
+    @Singleton()
+    export class AppAuthenticationAncillaryService extends AuthenticationAncillaryService {
+      readonly #userService = inject(UserService);
+
+      // Resolve a login identifier (e.g., email) to actual Subject entities
+      override async resolveSubjects({ tenantId, subject }: SubjectInput): Promise<Subject[]> {
+        const user = await this.#userService.findByEmail(subject, tenantId);
+        return user ? [user] : [];
+      }
+
+      // Add custom data to the JWT payload
+      override async getTokenPayload(subject: Subject, _data: void, _context: GetTokenPayloadContext): Promise<Record<string, unknown>> {
+        // You can check the type and add specific data
+        if (subject instanceof User) {
+          return { role: subject.role };
+        }
+
+        return {};
+      }
+
+      // Handle secret reset (e.g., send email)
+      override async handleInitSecretReset(data: any): Promise<void> {
+        console.log(`Send reset email to ${data.subject.id} with token ${data.token}`);
+      }
+
+      // Define impersonation rules
+      override async canImpersonate(token: any, subject: Subject): Promise<boolean> {
+        return token.role == 'admin';
+      }
+    }
+    ```
+
+2.  **Configure the Server**
+    Register the module in your application bootstrap.
+
+    ```typescript
+    import { configureAuthenticationServer, migrateAuthenticationSchema } from '@tstdl/base/authentication/server';
+    import { AppAuthenticationAncillaryService } from './app-authentication-ancillary.service.js';
+
+    // Run migrations for authentication tables
+    await migrateAuthenticationSchema();
+
+    configureAuthenticationServer({
+      authenticationAncillaryService: AppAuthenticationAncillaryService,
+      serviceOptions: {
+        // In production, load these from environment variables!
+        secret: 'super-secure-random-string-for-signing-tokens-at-least-64-chars',
+        tokenTimeToLive: 15 * 60 * 1000, // 15 minutes
+      },
+    });
+    ```
+
+### Client Setup
+
+1.  **Configure the Client**
+    Register the client module.
+
+    ```typescript
+    import { configureAuthenticationClient } from '@tstdl/base/authentication';
+
+    configureAuthenticationClient({
+      registerMiddleware: true, // Automatically attaches tokens to outgoing requests
+    });
+    ```
+
+2.  **Use the Service**
+    Inject `AuthenticationClientService` to manage login state.
+
+    ```typescript
+    import { AuthenticationClientService } from '@tstdl/base/authentication';
+    import { inject } from '@tstdl/base/injector';
+    import { effect } from '@tstdl/base/signals';
+
+    const authService = inject(AuthenticationClientService);
+
+    // React to state changes using Signals
+    effect(() => {
+      if (authService.isLoggedIn()) {
+        console.log(`User logged in with ID: ${authService.subjectId()}`);
+      } else {
+        console.log('User is guest');
+      }
+    });
+
+    // Perform login
+    async function login(email: string, pass: string) {
+      try {
+        await authService.login(email, pass);
+      } catch (error) {
+        console.error('Login failed', error);
+      }
+    }
+    ```
+
+## 🔧 Advanced Topics
+
+### Custom Token Payloads & Authentication Data
+
+You can strongly type the extra data in your JWTs and the data passed during login.
+
+```typescript
+import { Subject } from '@tstdl/base/authentication';
+
+// Define types
+type MyTokenPayload = { role: 'admin' | 'user'; tenantId: string };
+type MyAuthData = { tenantId: string }; // Data sent from client during login
+
+// Server: Extend Ancillary Service
+class MyAncillary extends AuthenticationAncillaryService<MyTokenPayload, MyAuthData> {
+  override async getTokenPayload(subject: Subject, data: MyAuthData): Promise<MyTokenPayload> {
+    // ... load data using subject.id or subject entity directly
+    return { role: 'admin', tenantId: data.tenantId };
+  }
+}
+
+// Client: Inject with generics
+const authService = inject<AuthenticationClientService<MyTokenPayload, MyAuthData>>(AuthenticationClientService);
+
+// Now typed:
+await authService.login('user@example.com', 'password', { tenantId: '123' });
+const role = authService.token()?.role; // Typed as 'admin' | 'user'
+```
+
+### Impersonation
+
+Administrators can log in as other users without knowing their password. This creates a nested session where the original admin session is preserved.
+
+```typescript
+// Client
+const targetSubjectId = '...';
+await authService.impersonate(targetSubjectId);
+
+// Check status
+if (authService.impersonated()) {
+  console.log(`Impersonating ${authService.subjectId()} by ${authService.impersonator()}`);
+}
+
+// Return to admin session
+await authService.unimpersonate();
+```
+
+### Secret Validation
+
+By default, the module checks for password strength and known data breaches (pwned passwords). You can override this by implementing `AuthenticationSecretRequirementsValidator`.
+
+```typescript
+import { AuthenticationSecretRequirementsValidator, type SecretCheckResult, type SecretTestResult } from '@tstdl/base/authentication/server';
+import { Singleton } from '@tstdl/base/injector';
+
+@Singleton({ alias: AuthenticationSecretRequirementsValidator })
+export class MySecretValidator extends AuthenticationSecretRequirementsValidator {
+  override async checkSecretRequirements(secret: string): Promise<SecretCheckResult> {
+    // Custom logic (e.g. using zxcvbn or similar)
+    return { strength: 4, pwned: 0, warnings: [], suggestions: [] };
+  }
+
+  override async testSecretRequirements(secret: string): Promise<SecretTestResult> {
+    if (secret.length < 10) {
+      return { success: false, reason: 'Too short' };
+    }
+    return { success: true };
+  }
+}
+```
+
+### HTTP Client Middleware
+
+If `registerMiddleware: true` is passed to `configureAuthenticationClient`, the `waitForAuthenticationCredentialsMiddleware` is registered.
+
+This middleware intercepts all outgoing HTTP requests made via `@tstdl/base/http`. If the request endpoint requires credentials (as defined in the API definition), the middleware will:
+
+1.  Check if a valid token exists.
+2.  If the token is expired or missing, it waits for the `AuthenticationClientService` to refresh or acquire a token.
+3.  Once valid, the request proceeds.
+
+## 📚 API
+
+### Server-Side (`@tstdl/base/authentication/server`)
+
+| Class/Function                              | Description                                                                           |
+| :------------------------------------------ | :------------------------------------------------------------------------------------ |
+| `AuthenticationService`                     | Main service for credential verification, token issuance, and session management.     |
+| `AuthenticationAncillaryService`            | Abstract class for hooks (resolve subjects, payload generation, impersonation checks).|
+| `AuthenticationSecretRequirementsValidator` | Abstract class for validating password strength/requirements.                         |
+| `configureAuthenticationServer`             | Configures the server module (secrets, options, ancillary service).                   |
+| `migrateAuthenticationSchema`               | Runs database migrations for authentication tables.                                   |
+| `AuthenticationApiController`               | The API controller implementation (automatically registered).                         |
+| `SubjectService`                            | Service for managing subjects (User, ServiceAccount, SystemAccount).                  |
+
+### Client-Side (`@tstdl/base/authentication`)
+
+| Class/Function                               | Description                                                             |
+| :------------------------------------------- | :---------------------------------------------------------------------- |
+| `AuthenticationClientService`                | Main client service. Handles login, logout, refresh, and state signals. |
+| `configureAuthenticationClient`              | Configures the client module and optional middleware.                   |
+| `waitForAuthenticationCredentialsMiddleware` | HTTP middleware that pauses requests until a valid token is available.  |
+
+### Models & Types (`@tstdl/base/authentication`)
+
+| Type/Class                  | Description                                 |
+| :-------------------------- | :------------------------------------------ |
+| `Subject`                   | Base entity for Users, ServiceAccounts, etc.|
+| `User`                      | Subject type representing a person.         |
+| `ServiceAccount`            | Subject type representing a non-human user. |
+| `SystemAccount`             | Subject type representing a system user.    |
+| `TokenPayload`              | The structure of the JWT payload.           |
+| `InitSecretResetData`       | Data required to initiate a password reset. |
+| `SecretCheckResult`         | Result of a password strength check.        |
+| `AuthenticationCredentials` | Database entity for user credentials.       |
+| `AuthenticationSession`     | Database entity for active sessions.        |

package/authentication/client/authentication.service.d.ts

@@ -1,3 +1,4 @@
+import { type Observable } from 'rxjs';
 import type { AfterResolve } from '../../injector/index.js';
 import { afterResolve } from '../../injector/index.js';
 import type { Record } from '../../types/index.js';
@@ -22,10 +23,10 @@ export declare class AuthenticationClientService<AdditionalTokenPayload extends
     private readonly errorSubject;
     private readonly tokenUpdateBus;
     private readonly loggedOutBus;
-    private readonly forceRefreshToken;
     private readonly lock;
     private readonly logger;
     private readonly disposeSignal;
+    private readonly forceRefreshRequested;
     private clockOffset;
     private initialized;
     private refreshLoopPromise;
@@ -33,7 +34,7 @@ export declare class AuthenticationClientService<AdditionalTokenPayload extends
      * Observable for authentication errors.
      * Emits when a refresh fails.
      */
-    readonly error$: import("rxjs").Observable<Error>;
+    readonly error$: Observable<Error>;
     /** Current token */
     readonly token: import("../../signals/api.js").WritableSignal<TokenPayload<AdditionalTokenPayload> | undefined>;
     /** Current raw token */
@@ -55,23 +56,23 @@ export declare class AuthenticationClientService<AdditionalTokenPayload extends
     /** Whether the user is impersonated */
     readonly impersonated: import("../../signals/api.js").Signal<boolean>;
     /** Current token */
-    readonly token$: import("rxjs").Observable<TokenPayload<AdditionalTokenPayload> | undefined>;
+    readonly token$: Observable<TokenPayload<AdditionalTokenPayload> | undefined>;
     /** Emits when token is available (not undefined) */
-    readonly definedToken$: import("rxjs").Observable<Exclude<TokenPayload<AdditionalTokenPayload>, void | undefined>>;
+    readonly definedToken$: Observable<Exclude<TokenPayload<AdditionalTokenPayload>, void | undefined>>;
     /** Emits when a valid token is available (not undefined and not expired) */
-    readonly validToken$: import("rxjs").Observable<Exclude<TokenPayload<AdditionalTokenPayload>, void | undefined>>;
+    readonly validToken$: Observable<Exclude<TokenPayload<AdditionalTokenPayload>, void | undefined>>;
     /** Current subject */
-    readonly subjectId$: import("rxjs").Observable<string | undefined>;
+    readonly subjectId$: Observable<string | undefined>;
     /** Emits when subject is available */
-    readonly definedSubjectId$: import("rxjs").Observable<string>;
+    readonly definedSubjectId$: Observable<string>;
     /** Current session id */
-    readonly sessionId$: import("rxjs").Observable<string | undefined>;
+    readonly sessionId$: Observable<string | undefined>;
     /** Emits when session id is available */
-    readonly definedSessionId$: import("rxjs").Observable<string>;
+    readonly definedSessionId$: Observable<string>;
     /** Whether the user is logged in */
-    readonly isLoggedIn$: import("rxjs").Observable<boolean>;
+    readonly isLoggedIn$: Observable<boolean>;
     /** Emits when the user logs out */
-    readonly loggedOut$: import("rxjs").Observable<void>;
+    readonly loggedOut$: Observable<void>;
     private get authenticationData();
     private set authenticationData(value);
     private get impersonatorAuthenticationData();

package/authentication/client/authentication.service.js

@@ -7,8 +7,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { Subject, filter, firstValueFrom, map, race, skip, takeUntil, timer } from 'rxjs';
-import { CancellationSignal, CancellationToken } from '../../cancellation/token.js';
+import { Subject, filter, firstValueFrom, from, map, race, skip, takeUntil, timer } from 'rxjs';
+import { CancellationSignal } from '../../cancellation/token.js';
 import { BadRequestError } from '../../errors/bad-request.error.js';
 import { ForbiddenError } from '../../errors/forbidden.error.js';
 import { formatError } from '../../errors/index.js';
@@ -25,7 +25,7 @@ import { computed, signal, toObservable } from '../../signals/api.js';
 import { currentTimestampSeconds } from '../../utils/date-time.js';
 import { timeout } from '../../utils/timing.js';
 import { assertDefinedPass, isDefined, isInstanceOf, isNotFunction, isNullOrUndefined, isUndefined } from '../../utils/type-guards.js';
-import { millisecondsPerMinute, millisecondsPerSecond } from '../../utils/units.js';
+import { millisecondsPerMinute, millisecondsPerSecond, secondsPerHour } from '../../utils/units.js';
 import { AUTHENTICATION_API_CLIENT, INITIAL_AUTHENTICATION_DATA } from './tokens.js';
 const tokenStorageKey = 'AuthenticationService:token';
 const rawTokenStorageKey = 'AuthenticationService:raw-token';
@@ -37,7 +37,7 @@ const tokenUpdateBusName = 'AuthenticationService:tokenUpdate';
 const loggedOutBusName = 'AuthenticationService:loggedOut';
 const refreshLockResource = 'AuthenticationService:refresh';
 const maxRefreshDelay = 15 * millisecondsPerMinute;
-const lockTimeout = 10000;
+const lockTimeout = 10_000;
 const logoutTimeout = 150;
 const unrecoverableErrors = [
     InvalidTokenError,
@@ -66,10 +66,10 @@ let AuthenticationClientService = class AuthenticationClientService {
     errorSubject = new Subject();
     tokenUpdateBus = inject((MessageBus), tokenUpdateBusName);
     loggedOutBus = inject((MessageBus), loggedOutBusName);
-    forceRefreshToken = new CancellationToken();
     lock = inject(Lock, refreshLockResource);
     logger = inject(Logger, 'AuthenticationService');
-    disposeSignal = inject(CancellationSignal).createChild();
+    disposeSignal = inject(CancellationSignal).fork();
+    forceRefreshRequested = signal(false);
     clockOffset = 0;
     initialized = false;
     refreshLoopPromise;
@@ -198,7 +198,7 @@ let AuthenticationClientService = class AuthenticationClientService {
         if (!this.initialized) {
             return;
         }
-        this.disposeSignal.set();
+        this.disposeSignal.dispose();
         await this.refreshLoopPromise;
         this.errorSubject.complete();
         await this.loggedOutBus.dispose();
@@ -240,7 +240,7 @@ let AuthenticationClientService = class AuthenticationClientService {
         }
         finally {
             // Always clear the local token, even if the server call fails.
-            this.forceRefreshToken.unset();
+            this.forceRefreshRequested.set(false);
             this.setNewToken(undefined);
             this.loggedOutBus.publishAndForget();
         }
@@ -253,7 +253,7 @@ let AuthenticationClientService = class AuthenticationClientService {
         if (isDefined(data)) {
             this.setAdditionalData(data);
         }
-        this.forceRefreshToken.set();
+        this.forceRefreshRequested.set(true);
     }
     /**
      * Refresh the token.
@@ -393,11 +393,11 @@ let AuthenticationClientService = class AuthenticationClientService {
                 if (isUndefined(token)) {
                     // Wait for login or dispose.
                     // We ignore forceRefreshToken here because we can't refresh without a token.
-                    await firstValueFrom(race([this.definedToken$, this.disposeSignal]), { defaultValue: undefined });
+                    await firstValueFrom(race([this.definedToken$, from(this.disposeSignal)]), { defaultValue: undefined });
                     continue;
                 }
                 const now = this.estimatedServerTimestampSeconds();
-                const forceRefresh = this.forceRefreshToken.isSet;
+                const forceRefresh = this.forceRefreshRequested();
                 const refreshBufferSeconds = calculateRefreshBufferSeconds(token);
                 const needsRefresh = forceRefresh || (now >= (token.exp - refreshBufferSeconds));
                 if (needsRefresh) {
@@ -406,12 +406,12 @@ let AuthenticationClientService = class AuthenticationClientService {
                         const currentNow = this.estimatedServerTimestampSeconds();
                         const currentRefreshBufferSeconds = isDefined(currentToken) ? calculateRefreshBufferSeconds(currentToken) : 0;
                         // Passive Sync: Check if another tab refreshed the token while we were waiting for the lock (or trying to get it)
-                        const stillNeedsRefresh = isDefined(currentToken) && (forceRefresh || (currentNow >= (currentToken.exp - currentRefreshBufferSeconds)));
+                        const stillNeedsRefresh = isDefined(currentToken) && (this.forceRefreshRequested() || (currentNow >= (currentToken.exp - currentRefreshBufferSeconds)));
                         if (stillNeedsRefresh) {
                             await this.refresh();
                         }
-                        if (forceRefresh && (this.token() != currentToken)) {
-                            this.forceRefreshToken.unset();
+                        if (this.forceRefreshRequested() && (this.token() != currentToken)) {
+                            this.forceRefreshRequested.set(false);
                         }
                     });
                     if (!lockResult.success) {
@@ -419,10 +419,10 @@ let AuthenticationClientService = class AuthenticationClientService {
                         const changeReason = await firstValueFrom(race([
                             timer(5000).pipe(map(() => 'timer')),
                             this.token$.pipe(filter((t) => t != token), map(() => 'token')),
-                            this.disposeSignal,
+                            from(this.disposeSignal),
                         ]), { defaultValue: undefined });
                         if (changeReason == 'token') {
-                            this.forceRefreshToken.unset();
+                            this.forceRefreshRequested.set(false);
                         }
                         continue;
                     }
@@ -431,11 +431,11 @@ let AuthenticationClientService = class AuthenticationClientService {
                 const currentRefreshBufferSeconds = isDefined(currentToken) ? calculateRefreshBufferSeconds(currentToken) : 0;
                 const delay = Math.min(maxRefreshDelay, ((currentToken?.exp ?? 0) - this.estimatedServerTimestampSeconds() - currentRefreshBufferSeconds) * millisecondsPerSecond);
                 const wakeUpSignals = [
-                    this.disposeSignal,
+                    from(this.disposeSignal),
                     this.token$.pipe(filter((t) => t != currentToken)),
                 ];
                 if (!forceRefresh) {
-                    wakeUpSignals.push(this.forceRefreshToken);
+                    wakeUpSignals.push(toObservable(this.forceRefreshRequested).pipe(filter((v) => v)));
                 }
                 if (delay > 0) {
                     await firstValueFrom(race([timer(delay), ...wakeUpSignals]), { defaultValue: undefined });
@@ -449,9 +449,9 @@ let AuthenticationClientService = class AuthenticationClientService {
                 const currentToken = this.token();
                 await firstValueFrom(race([
                     timer(2500),
-                    this.disposeSignal.set$,
+                    from(this.disposeSignal),
                     this.token$.pipe(filter((t) => t != currentToken)),
-                    this.forceRefreshToken.set$.pipe(skip(this.forceRefreshToken.isSet ? 1 : 0)),
+                    toObservable(this.forceRefreshRequested).pipe(filter((requested) => requested), skip(this.forceRefreshRequested() ? 1 : 0)),
                 ]), { defaultValue: undefined });
             }
         }
@@ -536,7 +536,7 @@ AuthenticationClientService = __decorate([
 ], AuthenticationClientService);
 export { AuthenticationClientService };
 function calculateRefreshBufferSeconds(token) {
-    const iat = token.iat ?? (token.exp - 3600);
+    const iat = token.iat ?? (token.exp - secondsPerHour);
     const lifetime = token.exp - iat;
     return (lifetime * 0.1) + 5;
 }

package/authentication/client/http-client.middleware.js

@@ -17,10 +17,10 @@ export function waitForAuthenticationCredentialsMiddleware(authenticationService
             while (!authenticationService.hasValidToken && authenticationService.isLoggedIn()) {
                 const race$ = race([
                     authenticationService.validToken$,
-                    request.abortSignal,
+                    request.cancellationSignal,
                 ]);
                 await firstValueFrom(race$.pipe(timeout(30000))).catch(() => undefined);
-                if (request.abortSignal.isSet) {
+                if (request.cancellationSignal.isSet) {
                     break;
                 }
             }

package/authentication/server/module.d.ts

@@ -25,6 +25,11 @@ export declare class AuthenticationModuleConfig {
      * Override default {@link AuthenticationAncillaryService}.
      */
     authenticationAncillaryService?: InjectionToken<AuthenticationAncillaryService<any, any, any>>;
+    /**
+     * Whether to automatically run database migrations when the application starts.
+     * Defaults to `true`.
+     */
+    autoMigrate?: boolean;
 }
 /**
  * Configures authentication server services.

package/authentication/server/module.js

@@ -2,7 +2,7 @@ import { ApiRequestTokenProvider } from '../../api/server/api-request-token.prov
 import { inject } from '../../injector/index.js';
 import { Injector } from '../../injector/injector.js';
 import { isProvider } from '../../injector/provider.js';
-import { Database, migrate } from '../../orm/server/index.js';
+import { Database, migrate, registerDatabaseMigration } from '../../orm/server/index.js';
 import { isDefined } from '../../utils/type-guards.js';
 import { AuthenticationAncillaryService } from './authentication-ancillary.service.js';
 import { AuthenticationApiRequestTokenProvider } from './authentication-api-request-token.provider.js';
@@ -28,6 +28,11 @@ export class AuthenticationModuleConfig {
      * Override default {@link AuthenticationAncillaryService}.
      */
     authenticationAncillaryService;
+    /**
+     * Whether to automatically run database migrations when the application starts.
+     * Defaults to `true`.
+     */
+    autoMigrate;
 }
 /**
  * Configures authentication server services.
@@ -44,6 +49,9 @@ export function configureAuthenticationServer({ injector, ...config }) {
     if (isDefined(config.authenticationAncillaryService)) {
         targetInjector.registerSingleton(AuthenticationAncillaryService, { useToken: config.authenticationAncillaryService });
     }
+    if (config.autoMigrate != false) {
+        registerDatabaseMigration('Authentication', migrateAuthenticationSchema, { injector });
+    }
 }
 /**
  * Migrates the authentication schema.

package/authentication/tests/authentication.api-controller.test.js

@@ -25,7 +25,7 @@ describe('AuthenticationApiController Integration', () => {
             clear: vi.fn(() => storage.clear()),
         };
         ({ injector, database } = await setupIntegrationTest({
-            modules: { authentication: true, audit: true, keyValueStore: true, test: true, api: true, webServer: true },
+            modules: { authentication: true, audit: true, keyValueStore: true, signals: true, api: true, webServer: true },
             authenticationAncillaryService: DefaultAuthenticationAncillaryService,
         }));
         await runInInjectionContext(injector, async () => {

package/authentication/tests/authentication.api-request-token.provider.test.js

@@ -11,7 +11,7 @@ describe('AuthenticationApiRequestTokenProvider', () => {
     let tokenProvider;
     const tenantId = crypto.randomUUID();
     beforeAll(async () => {
-        ({ injector } = await setupIntegrationTest({ modules: { authentication: true, test: true } }));
+        ({ injector } = await setupIntegrationTest({ modules: { authentication: true, signals: true } }));
         authenticationService = await injector.resolveAsync(AuthenticationService);
         subjectService = await injector.resolveAsync(SubjectService);
         tokenProvider = injector.resolve(AuthenticationApiRequestTokenProvider);

package/authentication/tests/authentication.client-error-handling.test.js

@@ -68,7 +68,8 @@ describe('AuthenticationClientService Error Handling & Stuck States', () => {
         injector.register(CancellationSignal, { useValue: disposeToken.signal });
     });
     afterEach(async () => {
-        await service.dispose();
+        disposeToken.set();
+        await injector.dispose();
     });
     function setupServiceWithToken(iatOffset = -10, expOffset = 5) {
         const now = Math.floor(Date.now() / 1000);

package/authentication/tests/authentication.client-service-refresh.test.js

@@ -16,6 +16,7 @@ describe('AuthenticationClientService Refresh Loop Reproduction', () => {
     let mockLock;
     let mockMessageBus;
     let mockLogger;
+    let disposeToken;
     beforeEach(() => {
         const storage = new Map();
         globalThis.localStorage = {
@@ -56,11 +57,12 @@ describe('AuthenticationClientService Refresh Loop Reproduction', () => {
         injector.register(Lock, { useValue: mockLock });
         injector.register(MessageBus, { useValue: mockMessageBus });
         injector.register(Logger, { useValue: mockLogger });
-        const disposeToken = new CancellationToken();
+        disposeToken = new CancellationToken();
         injector.register(CancellationSignal, { useValue: disposeToken.signal });
     });
     afterEach(async () => {
-        await service.dispose();
+        disposeToken.set();
+        await injector.dispose();
     });
     test('Zombie Timer: loop should wake up immediately when token changes', async () => {
         // 1. Mock a long expiration
@@ -91,7 +93,7 @@ describe('AuthenticationClientService Refresh Loop Reproduction', () => {
         // Wait for loop to attempt refresh and fail
         await timeout(50);
         expect(mockApiClient.refresh).toHaveBeenCalled();
-        expect(service.forceRefreshToken.isSet).toBe(true); // Should STILL be set
+        expect(service.forceRefreshRequested()).toBe(true); // Should STILL be set
     });
     test('Lock Contention Backoff: should wait 5 seconds and not busy-loop', async () => {
         const now = Math.floor(Date.now() / 1000);

package/authentication/tests/authentication.client-service.test.js

@@ -25,7 +25,7 @@ describe('AuthenticationClientService Integration', () => {
             clear: vi.fn(() => storage.clear()),
         };
         ({ injector, database } = await setupIntegrationTest({
-            modules: { authentication: true, audit: true, keyValueStore: true, test: true, api: true, webServer: true },
+            modules: { authentication: true, audit: true, keyValueStore: true, signals: true, api: true, webServer: true },
             authenticationAncillaryService: DefaultAuthenticationAncillaryService,
         }));
         await runInInjectionContext(injector, async () => {