@breadstone/archipel-platform-authentication

Authentication and authorization infrastructure for NestJS applications.

Features

• JWT authentication — Access/refresh token issuance and validation
• Social OAuth — Google, Microsoft, Apple, and GitHub connectors
• MFA/TOTP — Multi-factor authentication with challenge store
• Anonymous sessions — Seeded anonymous user support
• Pluggable ports — All persistence and enrichment via injectable adapters
• NestJS guards & decorators — Ready-made guards for route protection
• Health checks — AuthenticationHealthIndicator for readiness probes (separate /health subpath)

⚠️ Environment Variables

| Variable | Required | Default | Description | | ------------------------------ | -------- | ------- | ----------------------------------------- | | AUTH_JWT_SECRET | yes | - | JWT signing secret | | AUTH_JWT_EXPIRES_IN | yes | - | Access token expiry (e.g. 15m) | | AUTH_VERIFY_JWT_EXPIRES_IN | yes | - | Verification token expiry | | AUTH_GOOGLE_CLIENT_ID | yes | - | Google OAuth client ID | | AUTH_GOOGLE_CLIENT_SECRET | yes | - | Google OAuth client secret | | AUTH_MICROSOFT_CLIENT_ID | yes | - | Microsoft OAuth client ID | | AUTH_MICROSOFT_CLIENT_SECRET | yes | - | Microsoft OAuth client secret | | AUTH_APPLE_PRIVATE_KEY | yes | - | Apple Sign-In private key (PEM) | | AUTH_APPLE_CLIENT_ID | yes | - | Apple Sign-In client (service) ID | | AUTH_APPLE_TEAM_ID | yes | - | Apple developer team ID | | AUTH_APPLE_KEY_ID | yes | - | Apple Sign-In key ID | | AUTH_GITHUB_CLIENT_ID | yes | - | GitHub OAuth client ID | | AUTH_GITHUB_CLIENT_SECRET | yes | - | GitHub OAuth client secret | | SEED_ANONYMOUS_USERNAME | yes | - | Username for the seeded anonymous account |

For the full list (including MFA/OAuth callback defaults), see ../../ENVIRONMENT_VARIABLES.md.

Quick Start

import { AuthModule } from '@breadstone/archipel-platform-authentication';

@Module({
  imports: [
    AuthModule.register({
      authSubject: PrismaAuthSubjectAdapter,
      mfaSubject: PrismaMfaSubjectAdapter,
      sessionPersistence: PrismaSessionAdapter,
      verificationSubject: PrismaVerificationAdapter,
      challengeStore: RedisChallengeStore, // optional — defaults to in-memory
      socialAuth: PrismaSocialAuthAdapter, // optional — enables OAuth
      tokenEnricher: AppTokenEnricherAdapter, // optional — enriches JWT claims
    }),
  ],
})
export class AppModule {}

Import Options

// Main import (module, guards, ports)
import { AuthModule, AuthSubjectPort, SessionPersistencePort } from '@breadstone/archipel-platform-authentication';

// Social auth connectors (tree-shakable sub-exports)
import { GoogleConnector } from '@breadstone/archipel-platform-authentication/connectors/google';
import { MicrosoftConnector } from '@breadstone/archipel-platform-authentication/connectors/microsoft';
import { AppleConnector } from '@breadstone/archipel-platform-authentication/connectors/apple';
import { GithubConnector } from '@breadstone/archipel-platform-authentication/connectors/github';

// MFA/TOTP
import { TotpService } from '@breadstone/archipel-platform-authentication/mfa/totp';

// Health indicator (optional)
import { AuthenticationHealthIndicator } from '@breadstone/archipel-platform-authentication/health';

Ports

| Port | Required | Description | | ------------------------- | -------- | ------------------------------------------------- | | AuthSubjectPort | Yes | User lookup for JWT, Local, and Anonymous | | MfaSubjectPort | Yes | MFA state persistence | | SessionPersistencePort | Yes | Session storage and invalidation | | VerificationSubjectPort | Yes | Email/PIN verification lifecycle | | ChallengeStorePort | No | MFA challenge state. Defaults to in-memory store. | | SocialAuthPort | No | OAuth user creation/linking | | TokenEnricherPort | No | Custom JWT claim injection |

Resource Limits

| Limit | Value | Description | | ------------------------------ | ------ | ---------------------------------------------------------------- | | In-memory challenge store size | 10,000 | InMemoryChallengeStore max entries; oldest evicted on overflow |

Lifecycle

• Shutdown (OnModuleDestroy): InMemoryChallengeStore clears its cleanup interval.

Peer Dependencies

| Package | Required | Notes | | -------------------------------------- | -------- | ----------------------------- | | @nestjs/common | Yes | NestJS core | | @nestjs/jwt | Yes | JWT token handling | | class-validator | Yes | DTO validation | | class-transformer | Yes | DTO transformation | | passport | Yes | Authentication middleware | | passport-jwt | Yes | JWT passport strategy | | google-auth-library | No | Required for Google connector | | @breadstone/archipel-platform-health | No | Required for health indicator | | @nestjs/terminus | No | Required for health indicator |

Documentation

📖 Auth Guide: .docs/guides/authentication-and-authorization.md

Development

# Build
yarn nx build platform-authentication

# Test
yarn nx test platform-authentication

# Lint
yarn nx lint platform-authentication