@breadstone/archipel-mcp 0.0.1

package/data/packages/platform-authentication/api/index.md

@@ -0,0 +1,508 @@
+---
+title: '@breadstone/archipel-platform-authentication'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-authentication**](../)
+
+---
+
+# @breadstone/archipel-platform-authentication
+
+## Classes
+
+| Class                                                    | Description                                                                                                                                                                                                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [AnonymousAuthGuard](Class.AnonymousAuthGuard)           | The `AnonymousAuthGuard` protects routes using anonymous authentication.                                                                                                                                                                    |
+| [AuthModule](Class.AuthModule)                           | The `AuthModule` handles JWT-based authentication, including token creation and validation.                                                                                                                                                 |
+| [AuthSubjectPort](Class.AuthSubjectPort)                 | Abstract port for resolving authentication subjects by identity. Used by the JWT, Local, and Anonymous strategies.                                                                                                                          |
+| [AuthTokenService](Class.AuthTokenService)               | Generic service responsible for creating JWT access tokens. Builds a base payload from [IAuthSubject](Interface.IAuthSubject) and optionally enriches it via the [TokenEnricherPort](Class.TokenEnricherPort) with product-specific claims. |
+| [ChallengeService](Class.ChallengeService)               | Stores and validates MFA login challenges.                                                                                                                                                                                                  |
+| [GithubAuthGuard](Class.GithubAuthGuard)                 | The `GithubAuthGuard` protects routes using GitHub authentication.                                                                                                                                                                          |
+| [JwtAuthGuard](Class.JwtAuthGuard)                       | The `JwtAuthGuard` protects routes using JWT-based authentication.                                                                                                                                                                          |
+| [JwtPayloadBase](Class.JwtPayloadBase)                   | Abstract base class for JWT payloads. Products extend this to add their own claims (e.g. `profileId`, `isPro`). Used as both a serialization contract and NestJS injection token.                                                           |
+| [LastActiveMiddleware](Class.LastActiveMiddleware)       | Middleware to automatically update the lastActive timestamp for authenticated sessions. Extracts the JWT token from the Authorization header and updates the session asynchronously.                                                        |
+| [LocalAuthGuard](Class.LocalAuthGuard)                   | The `LocalAuthGuard` protects routes using local authentication.                                                                                                                                                                            |
+| [MfaService](Class.MfaService)                           | Orchestrates MFA channels, backup codes, and user preferences.                                                                                                                                                                              |
+| [MfaSubjectPort](Class.MfaSubjectPort)                   | Abstract port for reading and writing MFA state on the underlying subject entity. Used by the MfaService and all MFA channel implementations.                                                                                               |
+| [RolesGuard](Class.RolesGuard)                           | -                                                                                                                                                                                                                                           |
+| [SessionMappingProfile](Class.SessionMappingProfile)     | Mapping profile for Session entity to response transformations.                                                                                                                                                                             |
+| [SessionPersistencePort](Class.SessionPersistencePort)   | Abstract port for persisting and querying sessions. Used by the SessionService and LastActiveMiddleware.                                                                                                                                    |
+| [SessionResponse](Class.SessionResponse)                 | The `SessionResponse` class.                                                                                                                                                                                                                |
+| [SessionService](Class.SessionService)                   | Manages user sessions via the [SessionPersistencePort](Class.SessionPersistencePort).                                                                                                                                                       |
+| [SocialAuthGuard](Class.SocialAuthGuard)                 | -                                                                                                                                                                                                                                           |
+| [SocialAuthPort](Class.SocialAuthPort)                   | Abstract port for resolving or creating subjects from social / OAuth profiles. Used by all social strategies (GitHub, Google, Microsoft, Apple).                                                                                            |
+| [TokenEnricherPort](Class.TokenEnricherPort)             | Abstract port for enriching JWT claims with product-specific data. This is an optional port: when not provided, the token contains only base claims.                                                                                        |
+| [VerificationService](Class.VerificationService)         | Manages email / PIN verification tokens via the [VerificationSubjectPort](Class.VerificationSubjectPort).                                                                                                                                   |
+| [VerificationSubjectPort](Class.VerificationSubjectPort) | Abstract port for verifiable subject persistence. Used by the VerificationService to manage email/PIN verification.                                                                                                                         |
+
+## Interfaces
+
+| Interface                                              | Description                                                                                                                                                         |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [IAuthModuleOptions](Interface.IAuthModuleOptions)     | Options for configuring the `AuthModule`.                                                                                                                           |
+| [IAuthSubject](Interface.IAuthSubject)                 | Generic authentication subject returned by the [AuthSubjectPort](Class.AuthSubjectPort). Represents any entity that can authenticate (user, service account, etc.). |
+| [IMfaChallengePayload](Interface.IMfaChallengePayload) | Represents the MFA challenge payload encoded in a challenge token.                                                                                                  |
+| [IMfaChallengeState](Interface.IMfaChallengeState)     | -                                                                                                                                                                   |
+| [IMfaConfirmation](Interface.IMfaConfirmation)         | Represents the activation result for multi-factor authentication.                                                                                                   |
+| [IMfaSetup](Interface.IMfaSetup)                       | Represents the data required to onboard a multi-factor authenticator.                                                                                               |
+| [IMfaSubject](Interface.IMfaSubject)                   | Represents an MFA-enabled subject. Contains the data the MFA subsystem needs to read and write MFA state on the underlying user-like entity.                        |
+| [IMfaSubjectUpdate](Interface.IMfaSubjectUpdate)       | Data payload for updating MFA state on the underlying entity. All properties are optional — only the provided ones are applied.                                     |
+| [ISessionRecord](Interface.ISessionRecord)             | Represents a persisted session record.                                                                                                                              |
+| [ISignInResult](Interface.ISignInResult)               | Represents the outcome of a sign-in attempt.                                                                                                                        |
+| [ISocialProfile](Interface.ISocialProfile)             | Profile data received from a social / OAuth provider.                                                                                                               |
+| [IStoreSessionArgs](Interface.IStoreSessionArgs)       | Arguments for storing a new session.                                                                                                                                |
+| [IVerifiableSubject](Interface.IVerifiableSubject)     | Represents a verifiable authentication subject. Used by the [VerificationService](Class.VerificationService) to verify email / PIN.                                 |
+
+## Variables
+
+### AUTH_APPLE_CALLBACK_URL
+
+```ts
+const AUTH_APPLE_CALLBACK_URL: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:109](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L109)
+
+Apple Sign-In callback URL.
+
+---
+
+### AUTH_APPLE_CLIENT_ID
+
+```ts
+const AUTH_APPLE_CLIENT_ID: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:100](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L100)
+
+Apple Sign-In client (service) ID.
+
+---
+
+### AUTH_APPLE_KEY_ID
+
+```ts
+const AUTH_APPLE_KEY_ID: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:106](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L106)
+
+Apple Sign-In key ID.
+
+---
+
+### AUTH_APPLE_PRIVATE_KEY
+
+```ts
+const AUTH_APPLE_PRIVATE_KEY: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:97](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L97)
+
+Apple Sign-In private key (PEM string).
+
+---
+
+### AUTH_APPLE_TEAM_ID
+
+```ts
+const AUTH_APPLE_TEAM_ID: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:103](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L103)
+
+Apple developer team ID.
+
+---
+
+### AUTH_GITHUB_CLIENT_ID
+
+```ts
+const AUTH_GITHUB_CLIENT_ID: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:116](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L116)
+
+GitHub OAuth client ID.
+
+---
+
+### AUTH_GITHUB_CLIENT_SECRET
+
+```ts
+const AUTH_GITHUB_CLIENT_SECRET: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:119](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L119)
+
+GitHub OAuth client secret.
+
+---
+
+### AUTH_GOOGLE_CALLBACK_URL
+
+```ts
+const AUTH_GOOGLE_CALLBACK_URL: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:74](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L74)
+
+Google OAuth2 callback URL.
+
+---
+
+### AUTH_GOOGLE_CLIENT_ID
+
+```ts
+const AUTH_GOOGLE_CLIENT_ID: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L68)
+
+Google OAuth2 client ID.
+
+---
+
+### AUTH_GOOGLE_CLIENT_SECRET
+
+```ts
+const AUTH_GOOGLE_CLIENT_SECRET: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:71](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L71)
+
+Google OAuth2 client secret.
+
+---
+
+### AUTH_JWT_EXPIRES_IN
+
+```ts
+const AUTH_JWT_EXPIRES_IN: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L15)
+
+Lifetime of access tokens (e.g. `'15m'`, `'1h'`).
+
+---
+
+### AUTH_JWT_SECRET
+
+```ts
+const AUTH_JWT_SECRET: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:12](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L12)
+
+Secret used to sign JWTs.
+
+---
+
+### AUTH_MFA_CHALLENGE_EXPIRES_IN
+
+```ts
+const AUTH_MFA_CHALLENGE_EXPIRES_IN: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:28](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L28)
+
+How long an MFA challenge stays valid (e.g. `'5m'`).
+
+---
+
+### AUTH_MFA_EMAIL_CODE_TTL
+
+```ts
+const AUTH_MFA_EMAIL_CODE_TTL: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:48](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L48)
+
+Time-to-live for email OTP codes (e.g. `'10m'`).
+
+---
+
+### AUTH_MFA_EMAIL_MIN_RESEND
+
+```ts
+const AUTH_MFA_EMAIL_MIN_RESEND: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:51](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L51)
+
+Minimum interval between email OTP resend requests (e.g. `'30s'`).
+
+---
+
+### AUTH_MFA_ENCRYPTION_KEY
+
+```ts
+const AUTH_MFA_ENCRYPTION_KEY: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L25)
+
+AES encryption key used to encrypt MFA secrets at rest.
+
+---
+
+### AUTH_MFA_MAX_ATTEMPTS
+
+```ts
+const AUTH_MFA_MAX_ATTEMPTS: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:31](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L31)
+
+Maximum number of failed MFA attempts before lockout.
+
+---
+
+### AUTH_MFA_PUSH_CODE_TTL
+
+```ts
+const AUTH_MFA_PUSH_CODE_TTL: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:58](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L58)
+
+Time-to-live for push OTP codes (e.g. `'10m'`).
+
+---
+
+### AUTH_MFA_PUSH_MIN_RESEND
+
+```ts
+const AUTH_MFA_PUSH_MIN_RESEND: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:61](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L61)
+
+Minimum interval between push OTP resend requests (e.g. `'30s'`).
+
+---
+
+### AUTH_MFA_SMS_CODE_TTL
+
+```ts
+const AUTH_MFA_SMS_CODE_TTL: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:38](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L38)
+
+Time-to-live for SMS OTP codes (e.g. `'10m'`).
+
+---
+
+### AUTH_MFA_SMS_MIN_RESEND
+
+```ts
+const AUTH_MFA_SMS_MIN_RESEND: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:41](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L41)
+
+Minimum interval between SMS resend requests (e.g. `'30s'`).
+
+---
+
+### AUTH_MICROSOFT_CALLBACK_URL
+
+```ts
+const AUTH_MICROSOFT_CALLBACK_URL: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:87](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L87)
+
+Microsoft OAuth2 callback URL.
+
+---
+
+### AUTH_MICROSOFT_CLIENT_ID
+
+```ts
+const AUTH_MICROSOFT_CLIENT_ID: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:81](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L81)
+
+Microsoft OAuth2 client ID.
+
+---
+
+### AUTH_MICROSOFT_CLIENT_SECRET
+
+```ts
+const AUTH_MICROSOFT_CLIENT_SECRET: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:84](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L84)
+
+Microsoft OAuth2 client secret.
+
+---
+
+### AUTH_MICROSOFT_TENANT
+
+```ts
+const AUTH_MICROSOFT_TENANT: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:90](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L90)
+
+Microsoft tenant ID or `'common'` for multi-tenant.
+
+---
+
+### AUTH_VERIFY_JWT_EXPIRES_IN
+
+```ts
+const AUTH_VERIFY_JWT_EXPIRES_IN: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L18)
+
+Lifetime of email-verification JWTs.
+
+---
+
+### PLATFORM_AUTHENTICATION_CONFIG_ENTRIES
+
+```ts
+const PLATFORM_AUTHENTICATION_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:133](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L133)
+
+All configuration entries required by `platform-authentication`.
+
+---
+
+### ROLES_KEY
+
+```ts
+const ROLES_KEY: 'use_roles' = 'use_roles';
+```
+
+Defined in: [libs/platform-authentication/src/decorators/RolesDecorator.ts:12](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/decorators/RolesDecorator.ts#L12)
+
+Represents the key for the `UseRoles` decorator.
+
+---
+
+### SEED_ANONYMOUS_USERNAME
+
+```ts
+const SEED_ANONYMOUS_USERNAME: IConfigKey<string>;
+```
+
+Defined in: [libs/platform-authentication/src/env.ts:126](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/env.ts#L126)
+
+Username used for the anonymous seed user.
+
+---
+
+### SESSION_LIST_MAPPING_KEY
+
+```ts
+const SESSION_LIST_MAPPING_KEY: IMappingKey<ISessionMappingInput[], SessionResponse[]>;
+```
+
+Defined in: [libs/platform-authentication/src/mappers/SessionMappingProfile.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/mappers/SessionMappingProfile.ts#L29)
+
+Type-safe mapping key for Session entity list to response list transformation.
+
+---
+
+### SESSION_MAPPING_KEY
+
+```ts
+const SESSION_MAPPING_KEY: IMappingKey<ISessionMappingInput, SessionResponse>;
+```
+
+Defined in: [libs/platform-authentication/src/mappers/SessionMappingProfile.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/mappers/SessionMappingProfile.ts#L20)
+
+Type-safe mapping key for Session entity to response transformation.
+
+---
+
+### User
+
+```ts
+const User: (...dataOrPipes) => ParameterDecorator;
+```
+
+Defined in: [libs/platform-authentication/src/decorators/UserDecorator.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/decorators/UserDecorator.ts#L13)
+
+Represents the `User` decorator.
+
+#### Parameters
+
+| Parameter        | Type        |
+| ---------------- | ----------- |
+| ...`dataOrPipes` | `unknown`[] |
+
+#### Returns
+
+`ParameterDecorator`
+
+## Functions
+
+### socialAuthGuardFactory()
+
+```ts
+function socialAuthGuardFactory(provider): SocialAuthGuard;
+```
+
+Defined in: [libs/platform-authentication/src/guards/SocialAuthGuard.ts:42](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/guards/SocialAuthGuard.ts#L42)
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `provider` | `string` |
+
+#### Returns
+
+[`SocialAuthGuard`](Class.SocialAuthGuard)
+
+---
+
+### Token()
+
+```ts
+function Token(): Function;
+```
+
+Defined in: [libs/platform-authentication/src/decorators/TokenDecorator.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/decorators/TokenDecorator.ts#L14)
+
+Represents the `Token` decorator.
+
+#### Returns
+
+`Function`
+
+---
+
+### UseRoles()
+
+```ts
+function UseRoles(...roles): Function;
+```
+
+Defined in: [libs/platform-authentication/src/decorators/RolesDecorator.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-authentication/src/decorators/RolesDecorator.ts#L20)
+
+Represents the `UseRoles` decorator.
+
+#### Parameters
+
+| Parameter  | Type       |
+| ---------- | ---------- |
+| ...`roles` | `string`[] |
+
+#### Returns
+
+`Function`