@tstdl/base 0.93.139 → 0.93.141

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.).                            |