@tstdl/base 0.93.178 → 0.93.180

package/api/response.js

@@ -1,7 +1,7 @@
-import { SecretRequirementsError } from '../authentication/errors/secret-requirements.error.js';
+import { PasswordRequirementsError } from '../authentication/errors/password-requirements.error.js';
 import { formatError } from '../errors/index.js';
 import { SchemaError } from '../schema/schema.error.js';
-import { ApiError, BadRequestError, ForbiddenError, InvalidCredentialsError, InvalidTokenError, MaxBytesExceededError, MethodNotAllowedError, NotFoundError, NotImplementedError, NotSupportedError, UnauthorizedError, UnsupportedMediaTypeError } from '../errors/index.js';
+import { ApiError, BadRequestError, ForbiddenError, InvalidCredentialsError, InvalidTokenError, MaxBytesExceededError, MethodNotAllowedError, NotFoundError, NotImplementedError, NotSupportedError, TooManyRequestsError, UnauthorizedError, UnsupportedMediaTypeError } from '../errors/index.js';
 import { assertString, isDefined, isFunction, isObject, isString } from '../utils/type-guards.js';
 import { deserializeSchemaError, serializeSchemaError } from './default-error-handlers.js';
 const errorHandlers = new Map();
@@ -99,7 +99,8 @@ registerErrorHandler(NotFoundError, 404, () => undefined, (_, error) => new NotF
 registerErrorHandler(NotImplementedError, 501, () => undefined, (_, error) => new NotImplementedError(error.message));
 registerErrorHandler(NotSupportedError, 400, () => undefined, (_, error) => new NotSupportedError(error.message));
 registerErrorHandler(SchemaError, 400, serializeSchemaError, (data, error) => deserializeSchemaError(error.message, data));
-registerErrorHandler(SecretRequirementsError, 403, () => undefined, (_, error) => new SecretRequirementsError(error.message));
+registerErrorHandler(PasswordRequirementsError, 403, () => undefined, (_, error) => new PasswordRequirementsError(error.message));
+registerErrorHandler(TooManyRequestsError, 429, () => undefined, (_, error) => new TooManyRequestsError(error.message));
 registerErrorHandler(UnauthorizedError, 401, () => undefined, (_, error) => new UnauthorizedError(error.message));
 registerErrorHandler(UnsupportedMediaTypeError, 415, () => undefined, (_, error) => new UnsupportedMediaTypeError(error.message));
 // biome-ignore-end lint/style/noMagicNumbers: http status codes

package/api/server/gateway.js

@@ -15,6 +15,7 @@ import 'urlpattern-polyfill';
 import { Auditor } from '../../audit/auditor.js';
 import { ActorType } from '../../audit/types.js';
 import { NIL_UUID } from '../../constants.js';
+import { isDevMode } from '../../core.js';
 import { BadRequestError, InvalidTokenError, NotFoundError, NotImplementedError } from '../../errors/index.js';
 import { HttpServerResponse } from '../../http/server/index.js';
 import { inject, injectArgument, resolveArgumentType, Singleton } from '../../injector/index.js';
@@ -23,11 +24,12 @@ import { Schema } from '../../schema/index.js';
 import { DataStreamSource } from '../../sse/data-stream-source.js';
 import { DataStream } from '../../sse/data-stream.js';
 import { ServerSentEventsSource } from '../../sse/server-sent-events-source.js';
+import { ServerSentEvents } from '../../sse/server-sent-events.js';
 import { toArray } from '../../utils/array/array.js';
 import { composeAsyncMiddleware } from '../../utils/middleware.js';
 import { mapObjectValues } from '../../utils/object/object.js';
 import { deferThrow } from '../../utils/throw.js';
-import { isArray, isBlob, isDefined, isNotNull, isNotNullOrUndefined, isNull, isNullOrUndefined, isObject, isReadableStream, isUint8Array, isUndefined } from '../../utils/type-guards.js';
+import { isArray, isBlob, isDefined, isNotInstanceOf, isNotNull, isNotNullOrUndefined, isNull, isNullOrUndefined, isObject, isReadableStream, isUint8Array, isUndefined } from '../../utils/type-guards.js';
 import { mebibyte } from '../../utils/units.js';
 import { logAndGetErrorResponse } from '../response.js';
 import { normalizedApiDefinition, normalizedApiDefinitionEndpointsEntries } from '../types.js';
@@ -242,19 +244,23 @@ let ApiGateway = ApiGateway_1 = class ApiGateway {
             context.response.update(result);
         }
         else {
+            const endpointDefinitionResult = context.endpoint.definition.result;
+            if (isDevMode() && isDefined(endpointDefinitionResult) && isNotInstanceOf(endpointDefinitionResult, DataStream) && isNotInstanceOf(endpointDefinitionResult, ServerSentEvents)) {
+                Schema.assert(endpointDefinitionResult, result);
+            }
             context.response.body = match(result)
                 .when(isUint8Array, (buffer) => ({ buffer }))
                 .when(isBlob, (value) => ({ stream: value.stream() }))
                 .when((isReadableStream), (stream) => ({ stream }))
                 .when((value) => value instanceof ServerSentEventsSource, (events) => ({ events }))
-                .when(() => (context.endpoint.definition.result == DataStream), (value) => {
+                .when(() => (endpointDefinitionResult == DataStream), (value) => {
                 const errorFormatter = (error) => {
                     const { errorResponse } = logAndGetErrorResponse(this.#logger, this.#supressedErrors, error);
                     return errorResponse.error;
                 };
                 return ({ events: DataStreamSource.fromIterable(value, { errorFormatter, ...context.endpoint.definition.dataStream }).eventSource });
             })
-                .when(() => (context.endpoint.definition.result == String), (text) => ({ text: text }))
+                .when(() => (endpointDefinitionResult == String), (text) => ({ text: text }))
                 .otherwise((json) => ({ json }));
         }
         await next();

package/audit/auditor.d.ts

@@ -35,7 +35,7 @@ export type AuditorArgument = string | string[] | {
      */
     context?: Partial<AuditPayload>;
 };
-type AuditEvents = Record<string, UndefinableJsonObject>;
+export type AuditEvents = Record<string, UndefinableJsonObject>;
 /**
  * A service for logging audit events.
  * It provides a structured way to record activities within the system.
@@ -124,4 +124,3 @@ export declare class Auditor<Events extends AuditEvents = AuditEvents> implement
      */
     critical<const E extends Extract<keyof Events, string>>(action: E, data?: AuditPayload<Events[E]>): Promise<void>;
 }
-export {};

package/audit/drizzle/{0000_lumpy_thunderball.sql → 0000_shallow_elektra.sql}

@@ -2,7 +2,7 @@ CREATE TYPE "audit"."actor_type" AS ENUM('anonymous', 'system', 'api-key', 'subj
 CREATE TYPE "audit"."audit_outcome" AS ENUM('pending', 'success', 'cancelled', 'failure', 'denied');--> statement-breakpoint
 CREATE TYPE "audit"."audit_severity" AS ENUM('info', 'warn', 'error', 'critical');--> statement-breakpoint
 CREATE TABLE "audit"."event" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"id" uuid PRIMARY KEY DEFAULT uuidv7() NOT NULL,
 	"timestamp" timestamp with time zone NOT NULL,
 	"tenant_id" uuid,
 	"correlation_id" uuid,

package/audit/drizzle/meta/0000_snapshot.json

@@ -1,5 +1,5 @@
 {
-  "id": "e6910cc2-1674-462e-be27-f94e3372393f",
+  "id": "ae3f33c2-9768-4d5d-8878-7779bf73b52a",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -13,7 +13,7 @@
           "type": "uuid",
           "primaryKey": true,
           "notNull": true,
-          "default": "gen_random_uuid()"
+          "default": "uuidv7()"
         },
         "timestamp": {
           "name": "timestamp",

package/audit/drizzle/meta/_journal.json

@@ -5,8 +5,8 @@
     {
       "idx": 0,
       "version": "7",
-      "when": 1768666123825,
-      "tag": "0000_lumpy_thunderball",
+      "when": 1774646420544,
+      "tag": "0000_shallow_elektra",
       "breakpoints": true
     }
   ]

package/authentication/README.md

@@ -1,6 +1,6 @@
 # @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.
+A comprehensive, secure, and type-safe authentication module providing JWT-based session management, password and passkey handling, and extensible hooks for both server and client environments.
 
 ## Table of Contents
 
@@ -16,7 +16,7 @@ A comprehensive, secure, and type-safe authentication module providing JWT-based
 - [🔧 Advanced Topics](#-advanced-topics)
   - [Custom Token Payloads & Authentication Data](#custom-token-payloads--authentication-data)
   - [Impersonation](#impersonation)
-  - [Secret Validation](#secret-validation)
+  - [Password Validation](#password-validation)
   - [HTTP Client Middleware](#http-client-middleware)
 - [📚 API](#-api)
 
@@ -28,8 +28,9 @@ A comprehensive, secure, and type-safe authentication module providing JWT-based
 - **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.
+- **Password Management**: Includes flows for changing passwords and secure, token-based password resets.
+- **Audit Logging**: Automatically logs security events (login success/failure, password changes, TOTP enrollment/verification) via the `@tstdl/base/audit` system.
+- **TOTP Multi-Factor Authentication**: Built-in support for Time-Based One-Time Passwords (TOTP) with authenticator apps, recovery codes, and rate-limited multi-step login flows.
 - **Extensible**: Abstract classes allow you to inject custom logic for subject resolution, token payload enrichment, and permission checks.
 
 ## Core Concepts
@@ -46,9 +47,9 @@ The module uses a polymorphic `Subject` system to represent different types of e
 
 The server component revolves around the `AuthenticationService`. It handles:
 
-- **Credential Storage**: Manages the `AuthenticationCredentials` entity (subject, hash, salt).
+- **Password Storage**: Manages the `AuthenticationPassword` entity (subject, hash, salt).
 - **Session Tracking**: Manages the `AuthenticationSession` entity, allowing for server-side session revocation.
-- **Token Issuance**: Generates signed JWTs using configured secrets.
+- **Token Issuance**: Generates signed JWTs using configured signing keys.
 - **Validation**: Verifies tokens and handles the refresh flow.
 
 ### Client-Side Architecture
@@ -57,6 +58,7 @@ 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).
+- **MFA Support**: Handles the multi-step login flow when TOTP is enabled.
 - **State**: Provides reactive signals like `isLoggedIn`, `token`, and `subjectId`.
 
 ### Extensibility Hooks
@@ -96,8 +98,8 @@ To integrate this module with your application, implement the `AuthenticationAnc
         return {};
       }
 
-      // Handle secret reset (e.g., send email)
-      override async handleInitSecretReset(data: any): Promise<void> {
+      // Handle password reset (e.g., send email)
+      override async handleInitPasswordReset(data: any): Promise<void> {
         console.log(`Send reset email to ${data.subject.id} with token ${data.token}`);
       }
 
@@ -172,6 +174,48 @@ To integrate this module with your application, implement the `AuthenticationAnc
 
 ## 🔧 Advanced Topics
 
+### TOTP Multi-Factor Authentication
+
+The module supports a two-step login flow for accounts with TOTP enabled.
+
+#### 1. Enrollment (with Proof of Possession)
+
+Users must verify a code from their authenticator app before TOTP is activated.
+
+```typescript
+// Client
+const { secret, uri } = await authService.initEnrollTotp();
+// ... Display QR code using the URI or manual entry using the secret ...
+
+// Submit the first code to complete enrollment and get recovery codes
+const { recoveryCodes } = await authService.completeEnrollTotp(userEnteredToken);
+```
+
+#### 2. Multi-Step Login
+
+When a user logs in with their password, the `login` method may return a TOTP challenge.
+
+```typescript
+// Client
+const result = await authService.login(email, password);
+
+if (result?.type == 'totp') {
+  const challengeToken = result.challengeToken;
+  // ... Prompt user for 6-digit code or recovery code ...
+  await authService.verifyTotpLogin(challengeToken, userEnteredCodeOrRecoveryCode);
+}
+
+// User is now logged in
+```
+
+#### 3. Disenrollment
+
+Users can disable TOTP by providing a valid code.
+
+```typescript
+await authService.disableTotp(userEnteredCodeOrRecoveryCode);
+```
+
 ### Custom Token Payloads & Authentication Data
 
 You can strongly type the extra data in your JWTs and the data passed during login.
@@ -217,23 +261,23 @@ if (authService.impersonated()) {
 await authService.unimpersonate();
 ```
 
-### Secret Validation
+### Password Validation
 
-By default, the module checks for password strength and known data breaches (pwned passwords). You can override this by implementing `AuthenticationSecretRequirementsValidator`.
+By default, the module checks for password strength and known data breaches (pwned passwords). You can override this by implementing `AuthenticationPasswordRequirementsValidator`.
 
 ```typescript
-import { AuthenticationSecretRequirementsValidator, type SecretCheckResult, type SecretTestResult } from '@tstdl/base/authentication/server';
+import { AuthenticationPasswordRequirementsValidator, type PasswordCheckResult, type PasswordTestResult } 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> {
+@Singleton({ alias: AuthenticationPasswordRequirementsValidator })
+export class MyPasswordValidator extends AuthenticationPasswordRequirementsValidator {
+  override async checkPasswordRequirements(password: string): Promise<PasswordCheckResult> {
     // 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) {
+  override async testPasswordRequirements(password: string): Promise<PasswordTestResult> {
+    if (password.length < 10) {
       return { success: false, reason: 'Too short' };
     }
     return { success: true };
@@ -243,7 +287,7 @@ export class MySecretValidator extends AuthenticationSecretRequirementsValidator
 
 ### HTTP Client Middleware
 
-If `registerMiddleware: true` is passed to `configureAuthenticationClient`, the `waitForAuthenticationCredentialsMiddleware` is registered.
+If `registerMiddleware: true` is passed to `configureAuthenticationClient`, the `waitForAuthenticationPasswordMiddleware` 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:
 
@@ -255,34 +299,35 @@ This middleware intercepts all outgoing HTTP requests made via `@tstdl/base/http
 
 ### 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).                  |
+| Class/Function                                | Description                                                                            |
+| :-------------------------------------------- | :------------------------------------------------------------------------------------- |
+| `AuthenticationService`                       | Main service for password verification, token issuance, and session management.        |
+| `AuthenticationAncillaryService`              | Abstract class for hooks (resolve subjects, payload generation, impersonation checks). |
+| `AuthenticationPasswordRequirementsValidator` | Abstract class for validating password strength/requirements.                          |
+| `configureAuthenticationServer`               | Configures the server module (signing keys, 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.  |
+| Class/Function                            | Description                                                             |
+| :---------------------------------------- | :---------------------------------------------------------------------- |
+| `AuthenticationClientService`             | Main client service. Handles login, logout, refresh, and state signals. |
+| `configureAuthenticationClient`           | Configures the client module and optional middleware.                   |
+| `waitForAuthenticationPasswordMiddleware` | 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.        |
+| 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.            |
+| `InitPasswordResetData`  | Data required to initiate a password reset.  |
+| `PasswordCheckResult`    | Result of a password strength check.         |
+| `AuthenticationPassword` | Database entity for user passwords.          |
+| `AuthenticationSession`  | Database entity for active sessions.         |
+| `AuthenticationTotp`     | Database entity for TOTP configuration.      |