@tstdl/base 0.93.138 → 0.93.140

package/object-storage/README.md

@@ -0,0 +1,300 @@
+# @tstdl/base/object-storage
+
+A flexible and extensible module for handling object storage, providing a strong abstraction layer over concrete implementations like S3. It simplifies file management with module-based isolation, automatic lifecycle management, and seamless dependency injection integration.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Configuration](#configuration)
+  - [Injecting and Using ObjectStorage](#injecting-and-using-objectstorage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Lifecycle Management (Expiration)](#lifecycle-management-expiration)
+  - [Pre-signed URLs](#pre-signed-urls)
+  - [Streaming I/O](#streaming-io)
+  - [Listing Objects](#listing-objects)
+  - [Moving and Copying](#moving-and-copying)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Abstract `ObjectStorage` Interface**: Decouples your application logic from specific storage vendors.
+- **S3-Compatible Implementation**: Includes a robust `S3ObjectStorage` implementation working with AWS S3, MinIO, Google Cloud Storage (via S3 interoperability), etc.
+- **Google Cloud Storage Implementation**: Native `GoogleObjectStorage` implementation for direct GCS support.
+- **Module-based Isolation**: Organizes objects into logical "modules". These map to either key prefixes in a shared bucket or separate buckets per module.
+- **Automatic Lifecycle Management**: Configure object expiration policies (e.g., delete temp files after 24h) directly via injection tokens.
+- **Stream Support**: Native support for `ReadableStream` and `Uint8Array` for memory-efficient handling of large files.
+- **Pre-signed URLs**: Generate secure, temporary URLs for direct client-side uploads and downloads.
+- **Dependency Injection**: Designed for `@tstdl/base/injector`, allowing context-aware resolution of storage instances.
+
+## Core Concepts
+
+### ObjectStorage
+
+The central abstract class defining the contract for storage operations (upload, download, delete, exists, etc.). You rarely instantiate this directly; instead, you request it via dependency injection.
+
+### Modules
+
+A **Module** is a logical namespace for a collection of objects (e.g., `user-avatars`, `invoices`, `temp-uploads`).
+
+- **Shared Bucket Mode**: Modules are treated as directory prefixes within a single S3 bucket (e.g., `my-bucket/user-avatars/image.png`).
+- **Bucket-Per-Module Mode**: Each module gets its own dedicated S3 bucket (e.g., bucket `user-avatars` contains `image.png`).
+
+### ObjectStorageProvider
+
+A factory responsible for creating `ObjectStorage` instances for specific modules. The `S3ObjectStorageProvider` handles the creation of S3 clients and ensures buckets exist.
+
+### ObjectStorageObject
+
+Represents a stored file. It provides methods to access metadata, size, content, and resource URIs without loading the entire file into memory immediately.
+
+## 🚀 Basic Usage
+
+### Configuration
+
+#### S3 (AWS, MinIO, etc.)
+
+Configure the S3 provider at your application's entry point (e.g., `bootstrap.ts`).
+
+```typescript
+import { configureS3ObjectStorage } from '@tstdl/base/object-storage';
+
+// Option A: Single Shared Bucket (Recommended for most use cases)
+configureS3ObjectStorage({
+  endpoint: 'http://localhost:9000', // S3 Endpoint
+  accessKey: 'minioadmin',
+  secretKey: 'minioadmin',
+  bucket: 'my-app-storage', // All modules will be subfolders in this bucket
+  forcePathStyle: true, // Required for local s3 server
+});
+
+// Option B: Bucket Per Module
+// configureS3ObjectStorage({
+//   endpoint: '...',
+//   accessKey: '...',
+//   secretKey: '...',
+//   bucketPerModule: true // Each module creates a new bucket
+// });
+```
+
+#### Google Cloud Storage
+
+```typescript
+import { configureGoogleObjectStorage } from '@tstdl/base/object-storage/google';
+
+configureGoogleObjectStorage({
+  projectId: 'my-project-id',
+  keyFilename: '/path/to/keyfile.json',
+  bucket: 'my-app-storage',
+});
+```
+
+### Injecting and Using ObjectStorage
+
+Inject `ObjectStorage` into your services using the module name as the injection argument.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+
+@Singleton()
+export class ProfilePictureService {
+  // Inject storage specifically for the 'profile-pictures' module
+  readonly #storage = inject(ObjectStorage, 'profile-pictures');
+
+  async savePicture(userId: string, content: Uint8Array): Promise<void> {
+    const key = `${userId}.jpg`;
+
+    // Upload content
+    await this.#storage.uploadObject(key, content, {
+      contentType: 'image/jpeg',
+      metadata: { userId },
+    });
+  }
+
+  async getPicture(userId: string): Promise<Uint8Array> {
+    const key = `${userId}.jpg`;
+
+    // Check existence
+    if (!(await this.#storage.exists(key))) {
+      throw new Error('Picture not found');
+    }
+
+    // Download content
+    return this.#storage.getContent(key);
+  }
+
+  async deletePicture(userId: string): Promise<void> {
+    await this.#storage.deleteObject(`${userId}.jpg`);
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Lifecycle Management (Expiration)
+
+You can configure objects to automatically expire (be deleted) after a certain duration. This is configured when injecting the storage instance. The implementation (e.g., S3) will apply lifecycle rules to the bucket.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+import { secondsPerDay } from '@tstdl/base/utils';
+
+@Singleton()
+export class TemporaryUploadService {
+  // Objects in 'temp-files' will be deleted 1 day after creation
+  readonly #tempStorage = inject(ObjectStorage, {
+    module: 'temp-files',
+    configuration: {
+      lifecycle: {
+        expiration: {
+          after: 1 * secondsPerDay,
+        },
+      },
+    },
+  });
+
+  async saveTempFile(filename: string, data: Uint8Array): Promise<void> {
+    await this.#tempStorage.uploadObject(filename, data);
+  }
+}
+```
+
+### Pre-signed URLs
+
+Offload bandwidth from your server by generating pre-signed URLs that allow clients to upload or download directly to/from the storage provider.
+
+```typescript
+import { inject, Singleton } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+import { millisecondsPerMinute, now } from '@tstdl/base/utils';
+
+@Singleton()
+export class DownloadService {
+  readonly #storage = inject(ObjectStorage, 'reports');
+
+  async getDownloadLink(reportId: string): Promise<string> {
+    const key = `${reportId}.pdf`;
+    const expiration = now().getTime() + 15 * millisecondsPerMinute;
+
+    // Generate a URL valid for 15 minutes
+    return this.#storage.getDownloadUrl(key, expiration, {
+      'response-content-disposition': 'attachment; filename="report.pdf"',
+    });
+  }
+
+  async getUploadLink(reportId: string): Promise<string> {
+    const key = `${reportId}.pdf`;
+    const expiration = now().getTime() + 15 * millisecondsPerMinute;
+
+    // Generate a PUT URL for uploading
+    return this.#storage.getUploadUrl(key, expiration, {
+      contentType: 'application/pdf',
+      contentLength: 1024 * 1024 * 5, // 5MB expected size
+    });
+  }
+}
+```
+
+### Streaming I/O
+
+For large files, use streams to avoid loading the entire file into memory.
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+
+class LargeFileService {
+  readonly #storage = inject(ObjectStorage, 'backups');
+
+  async uploadStream(filename: string, stream: ReadableStream<Uint8Array>, size: number): Promise<void> {
+    await this.#storage.uploadObject(filename, stream, {
+      contentLength: size,
+    });
+  }
+
+  async streamDownload(filename: string): Promise<ReadableStream<Uint8Array>> {
+    return this.#storage.getContentStream(filename);
+  }
+}
+```
+
+### Listing Objects
+
+Use `getObjectsCursor()` to iterate over objects efficiently using an async iterable.
+
+```typescript
+async function listAllFiles(storage: ObjectStorage) {
+  for await (const obj of storage.getObjectsCursor()) {
+    console.log(`Found file: ${obj.key}, Size: ${await obj.getContentLength()}`);
+  }
+}
+```
+
+### Moving and Copying
+
+You can move or copy objects within the same module or across different modules (and buckets).
+
+```typescript
+import { inject } from '@tstdl/base/injector';
+import { ObjectStorage } from '@tstdl/base/object-storage';
+
+class FileOrganizer {
+  readonly #inbox = inject(ObjectStorage, 'inbox');
+  readonly #archive = inject(ObjectStorage, 'archive');
+
+  async archiveFile(filename: string): Promise<void> {
+    // Move from 'inbox' module to 'archive' module
+    await this.#inbox.moveObject(filename, [this.#archive, `2024/${filename}`]);
+  }
+
+  async duplicateInInbox(filename: string): Promise<void> {
+    // Copy within the same module
+    await this.#inbox.copyObject(filename, `copy_of_${filename}`);
+  }
+}
+```
+
+## 📚 API
+
+### `ObjectStorage` (Abstract Class)
+
+| Method                                         | Description                                             |
+| :--------------------------------------------- | :------------------------------------------------------ |
+| `exists(key: string): Promise<boolean>`        | Checks if an object exists.                             |
+| `uploadObject(key, content, options?)`         | Uploads data (`Uint8Array` or `ReadableStream`).        |
+| `getContent(key): Promise<Uint8Array>`         | Downloads the full object content into memory.          |
+| `getContentStream(key): ReadableStream`        | Gets a stream of the object content.                    |
+| `getDownloadUrl(key, expiration, headers?)`    | Generates a pre-signed download URL.                    |
+| `getUploadUrl(key, expiration, options?)`      | Generates a pre-signed upload URL.                      |
+| `deleteObject(key): Promise<void>`             | Deletes a single object.                                |
+| `deleteObjects(keys): Promise<void>`           | Deletes multiple objects.                               |
+| `copyObject(source, dest, options?)`           | Copies an object (intra- or inter-module).              |
+| `moveObject(source, dest, options?)`           | Moves an object (copy + delete).                        |
+| `getObjects(): Promise<ObjectStorageObject[]>` | Lists all objects in the module.                        |
+| `getObjectsCursor(): AsyncIterable`            | Iterates over objects efficiently.                      |
+| `getObject(key): Promise<ObjectStorageObject>` | Gets a handle to an object without downloading content. |
+
+### `S3ObjectStorageProviderConfig`
+
+| Property          | Type      | Description                                                                    |
+| :---------------- | :-------- | :----------------------------------------------------------------------------- |
+| `endpoint`        | `string`  | S3 API endpoint (e.g., `https://s3.amazonaws.com` or `http://localhost:9000`). |
+| `region`          | `string`  | S3 Region (e.g., `us-east-1`).                                                 |
+| `accessKey`       | `string`  | S3 Access Key ID.                                                              |
+| `secretKey`       | `string`  | S3 Secret Access Key.                                                          |
+| `bucket`          | `string`  | Name of the shared bucket. Mutually exclusive with `bucketPerModule`.          |
+| `bucketPerModule` | `boolean` | If true, creates a separate bucket for each module.                            |
+| `forcePathStyle`  | `boolean` | Whether to use path-style addressing. Useful for local s3 server.              |
+
+### `ObjectStorageObject`
+
+| Method                                   | Description                                |
+| :--------------------------------------- | :----------------------------------------- |
+| `getContentLength(): Promise<number>`    | Returns the size of the object in bytes.   |
+| `getMetadata(): Promise<ObjectMetadata>` | Returns user-defined metadata.             |
+| `getContent(): Promise<Uint8Array>`      | Downloads content.                         |
+| `getContentStream(): ReadableStream`     | Streams content.                           |
+| `getResourceUri(): Promise<string>`      | Returns the URI (e.g., `s3://bucket/key`). |

package/openid-connect/README.md

@@ -0,0 +1,274 @@
+# OpenID Connect
+
+A robust, type-safe OpenID Connect (OIDC) client implementation for TypeScript applications. It simplifies integration with OIDC providers by handling configuration discovery, secure state management, PKCE, and token exchanges.
+
+## Table of Contents
+
+- [Features](#-features)
+- [Core Concepts](#core-concepts)
+- [Prerequisites](#prerequisites)
+- [🚀 Basic Usage](#-basic-usage)
+  - [1. Setup & Configuration](#1-setup--configuration)
+  - [2. Initiating Authorization (Login)](#2-initiating-authorization-login)
+  - [3. Handling the Callback](#3-handling-the-callback)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Client Credentials Flow](#client-credentials-flow)
+  - [Refreshing Tokens](#refreshing-tokens)
+  - [Fetching User Info](#fetching-user-info)
+  - [Custom State Data](#custom-state-data)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Auto-Discovery**: Automatically fetches and caches provider configuration from `.well-known/openid-configuration`.
+- **Secure by Default**: Implements Authorization Code Flow with **PKCE** (Proof Key for Code Exchange, SHA-256) and cryptographically secure state generation.
+- **State Persistence**: Persists authorization state via the ORM to securely validate callbacks and prevent CSRF/replay attacks.
+- **Multiple Flows**: Supports Authorization Code and Client Credentials flows.
+- **Automated Authentication**: Supports both `body` and `basic-auth` authentication methods for token endpoints.
+- **Token Management**: Simple methods to exchange codes for tokens, refresh existing tokens, and fetch user info.
+- **Type-Safe**: Full TypeScript support for token responses and custom state data.
+
+## Core Concepts
+
+### OidcService
+
+The central service class. It orchestrates the entire flow: fetching configuration, generating secure parameters, storing state in the database, and communicating with the OIDC provider to exchange tokens.
+
+### OidcState
+
+An entity model used to persist the state of an authentication attempt. It stores:
+
+- The generated `state` string (for CSRF protection).
+- The `codeVerifier` (for PKCE).
+- Configuration details (endpoint, client ID).
+- Optional custom `data` attached to the flow.
+
+This entity must be registered with your ORM configuration so the service can save and retrieve it during the callback phase.
+
+## Prerequisites
+
+This module relies on the `@tstdl/base/orm` module to store the `OidcState`. Ensure your application has the ORM configured and the `OidcState` entity is included in your database schema.
+
+## 🚀 Basic Usage
+
+This example demonstrates the standard **Authorization Code Flow** with PKCE, commonly used for user login.
+
+### 1. Setup & Configuration
+
+Ensure `OidcState` is registered in your ORM configuration (e.g., in your `bootstrap.ts` or module configuration).
+
+```ts
+import { configureOrm } from '@tstdl/base/orm/server';
+import { OidcState } from '@tstdl/base/openid-connect';
+
+// In your bootstrap/configuration file
+configureOrm({
+  // ... connection settings
+  entities: [
+    // ... other entities
+    OidcState, // <--- Register the OidcState entity
+  ],
+});
+```
+
+### 2. Initiating Authorization (Login)
+
+When a user clicks "Login", generate the authorization URL. This creates a state record in the database.
+
+```ts
+import { inject } from '@tstdl/base/injector';
+import { OidcService } from '@tstdl/base/openid-connect';
+import { millisecondsPerMinute } from '@tstdl/base/utils/units';
+
+class AuthService {
+  // Inject the OidcService. You can type the generic to define custom data stored in state.
+  readonly oidcService = inject(OidcService<void>);
+
+  async getLoginUrl(): Promise<string> {
+    const result = await this.oidcService.initAuthorization({
+      endpoint: 'https://accounts.google.com', // The OIDC provider URL
+      clientId: 'my-client-id',
+      clientSecret: 'my-client-secret',
+      scope: 'openid profile email',
+      expiration: 5 * millisecondsPerMinute, // How long the login attempt is valid
+      data: undefined, // No custom data for this example
+    });
+
+    // Construct the URL to redirect the user to
+    const url = new URL(result.authorizationEndpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', result.clientId);
+    url.searchParams.set('scope', result.scope);
+    url.searchParams.set('redirect_uri', 'https://myapp.com/callback');
+    url.searchParams.set('state', result.state);
+    url.searchParams.set('code_challenge', result.codeChallenge);
+    url.searchParams.set('code_challenge_method', result.codeChallengeMethod);
+
+    return url.toString();
+  }
+}
+```
+
+### 3. Handling the Callback
+
+When the user is redirected back to your application (e.g., `https://myapp.com/callback?code=...&state=...`), validate the state and exchange the code for tokens.
+
+```ts
+import { inject } from '@tstdl/base/injector';
+import { OidcService } from '@tstdl/base/openid-connect';
+
+class CallbackController {
+  readonly oidcService = inject(OidcService<void>);
+
+  async handleCallback(code: string, state: string): Promise<void> {
+    // 1. Validate and retrieve the stored state.
+    // This throws if the state is invalid, expired, or missing.
+    // It also deletes the state from the DB to prevent replay attacks.
+    const storedState = await this.oidcService.validateState(state);
+
+    // 2. Exchange the authorization code for tokens
+    const tokenResponse = await this.oidcService.getToken({
+      grantType: 'authorization_code',
+      endpoint: storedState.endpoint,
+      clientId: storedState.clientId,
+      clientSecret: storedState.clientSecret,
+      code: code,
+      codeVerifier: storedState.codeVerifier, // Retrieved from DB
+      redirectUri: 'https://myapp.com/callback',
+      authType: 'body', // or 'basic-auth' depending on provider
+    });
+
+    console.log('Access Token:', tokenResponse.accessToken);
+    console.log('ID Token:', tokenResponse.idToken);
+  }
+}
+```
+
+## 🔧 Advanced Topics
+
+### Client Credentials Flow
+
+Used for machine-to-machine communication where no user is involved.
+
+```ts
+const token = await oidcService.getToken({
+  grantType: 'client_credentials',
+  endpoint: 'https://auth.example.com',
+  clientId: 'service-account-id',
+  clientSecret: 'service-account-secret',
+  scope: 'api:read',
+});
+```
+
+### Refreshing Tokens
+
+If you received a `refresh_token` in the initial flow, you can use it to get a new access token.
+
+```ts
+const newToken = await oidcService.refreshToken({
+  endpoint: 'https://accounts.google.com',
+  clientId: 'my-client-id',
+  clientSecret: 'my-client-secret',
+  refreshToken: 'existing-refresh-token',
+});
+```
+
+### Fetching User Info
+
+Retrieve the user's profile information using the `userinfo_endpoint` discovered from the configuration.
+
+```ts
+const userInfo = await oidcService.getUserInfo(
+  'https://accounts.google.com',
+  tokenResponse, // The object returned from getToken
+);
+
+console.log(userInfo);
+```
+
+### Custom State Data
+
+You can attach custom data to the `OidcState` when initializing authorization. This is useful for remembering where to redirect the user after login, storing a nonce, or keeping track of the original request's context.
+
+```ts
+type MyCustomData = { returnUrl: string };
+
+// Define a service or inject directly with the desired type
+const oidcService = inject(OidcService<MyCustomData>);
+
+// Initialize
+const result = await oidcService.initAuthorization({
+  // ... other params
+  data: { returnUrl: '/dashboard/settings' },
+});
+
+// ... later in callback ...
+
+const storedState = await oidcService.validateState(state);
+const returnUrl = storedState.data.returnUrl; // Properly typed as string
+```
+
+### Additional Parameters and Auth Types
+
+Some OIDC providers require additional parameters during token exchange or use a different authentication method.
+
+```ts
+const tokenResponse = await oidcService.getToken({
+  grantType: 'authorization_code',
+  // ...
+  authType: 'basic-auth', // Uses HTTP Basic Auth (clientId:clientSecret)
+}, {
+  // Additional form-data parameters (some providers require 'resource')
+  resource: 'https://api.example.com',
+});
+```
+
+## ⚠️ Error Handling
+
+The `OidcService` utilizes standard errors from the library:
+
+- `ForbiddenError`: Thrown by `validateState` if the state is missing, invalid, or already used (to prevent replay attacks).
+- `NotImplementedError`: Thrown if an unsupported grant type or authentication type is requested.
+- `Error`: Thrown if required endpoints (like `userinfo_endpoint`) are not present in the provider's configuration.
+
+Always wrap callback logic in a `try...catch` block to handle these cases gracefully.
+
+## 📚 API
+
+### Services
+
+| Class                            | Description                                                                                                                                  |
+| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OidcService<Data>`              | Main service for OIDC operations. Handles state creation, validation, token exchange, and user info retrieval.                                |
+| `OidcConfigurationService`       | Fetches OIDC configuration from the provider's well-known endpoint.                                                                          |
+| `CachedOidcConfigurationService` | A cached implementation of `OidcConfigurationService`. Used by default with a 5-minute cache duration (configurable via dependency injection). |
+
+### OidcService Methods
+
+| Method                                      | Description                                                                                                                           |
+| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ |
+| `initAuthorization(params)`                 | Discovers configuration, creates a secure state in the DB, and returns data to build the redirect URL.                                |
+| `validateState(state)`                      | Attempts to load a state by its value, then **deletes it**. Throws if not found. Essential for security.                              |
+| `getState(state)`                           | Just retrieves the state without deleting it.                                                                                         |
+| `deleteState(state)`                        | Manually removes a state from the database.                                                                                           |
+| `getToken(params, additionalData?)`         | Exchanges a code (or credentials) for tokens. Supports `authorization_code` and `client_credentials`.                                |
+| `refreshToken(params)`                      | Uses a refresh token to obtain a new set of tokens.                                                                                   |
+| `getUserInfo(endpoint, token)`              | Fetches the user's profile information using the access token.                                                                        |
+| `oidcConfigurationService.getConfiguration` | Directly fetches (and potentially caches) the OIDC provider's configuration.                                                          |
+
+### Models
+
+| Class             | Description                                                                                                                            |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| `OidcState<Data>` | Database entity representing the authorization state. Must be registered with ORM. Uses the `oidc` schema and `state` table by default. |
+
+### Types & Interfaces
+
+| Type                         | Description                                                                                      |
+| :--------------------------- | :----------------------------------------------------------------------------------------------- |
+| `OidcInitParameters<Data>`   | Parameters for `initAuthorization` (endpoint, client details, scope, expiration, custom data).   |
+| `OidcInitResult`             | Result of initialization, containing `authorizationEndpoint`, `state`, and PKCE `codeChallenge`. |
+| `OidcToken<Raw>`             | Represents the token response, including `accessToken`, `idToken`, `refreshToken`, and `raw` JSON. |
+| `OidcGetTokenParameters`     | Union type for token requests. Includes `authType` (`body` \| `basic-auth`).                      |
+| `OidcRefreshTokenParameters` | Parameters for refreshing a token.                                                               |
+| `OidcConfiguration`          | Discovered provider endpoints (authorization, token, userInfo, etc.).                            |