# luviensoft/luvien-auth architecture

> Architecture diagram of the GitHub repository luviensoft/luvien-auth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luviensoft/luvien-auth
- Repository: https://github.com/luviensoft/luvien-auth

## Overview

@luvien/auth is a NestJS authentication and identity library. An application initiates login through the Nest service; the core service creates OIDC state and PKCE data, redirects to an identity provider, then processes the callback into a mapped identity, local principal, and optional server session. Nest guards resolve sessions and enforce roles. The README also documents JWKS token validation, identity linking, and provider capabilities. The tree supports these subsystems, but unsampled implementation details and some wiring are not inferred.

Main entry points: [`src/core/application/authentication.service.ts`](https://github.com/luviensoft/luvien-auth/blob/main/src/core/application/authentication.service.ts) (Authentication service), [`src/nest/auth.module.ts`](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/auth.module.ts) (Auth module), [`src/nest/auth.service.ts`](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/auth.service.ts) (Auth service), [`src/persistence/in-memory/in-memory-session.manager.ts`](https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-session.manager.ts) (In-memory session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_nest["NestJS Integration"]
  node_auth_module["Auth module<br/>[auth.module.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_auth_guard["Authentication guard"]
  node_role_guard["Authorization guard"]
  node_current_user["Current user decorator"]
  node_require_roles["Role decorator"]
end

subgraph group_core["Authentication Core"]
  node_authentication["Authentication service"]
  node_principal_identity["Principal and identity<br/>[identity.ts]"]
  node_provider_capability["Provider capabilities<br/>[capability.ts]"]
  node_oidc_port["OIDC provider port"]
  node_identity_port["Identity repository port"]
  node_session_port["Session manager port"]
  node_state_port["State store port"]
  node_user_port["User resolver port"]
end

subgraph group_oidc["OIDC Provider"]
  node_pkce["PKCE and state<br/>[oidc.pkce.ts]"]
  node_generic_provider["Generic OIDC provider"]
  node_claim_mapper["Claim and role mapping<br/>[claim-mapper.ts]"]
  node_discovery["OIDC discovery<br/>[oidc.discovery.ts]"]
  node_token_validation["JWKS token validation"]
end

subgraph group_state["Identity And Sessions"]
  node_session_domain["Session model<br/>[session.ts]"]
end

subgraph group_adapters["In-memory Adapters"]
  node_identity_repo[("In-memory identity repository")]
  node_session_manager[("In-memory session manager")]
  node_state_store[("In-memory state store")]
end

node_application(("Application"))
node_idp(("External identity provider"))
node_resolver["Application user resolver"]

node_application -->|"starts login"| node_auth_service
node_application -->|"submits callback"| node_auth_service
node_auth_service -->|"delegates"| node_authentication
node_auth_service -->|"reads and destroys"| node_session_manager
node_authentication -->|"generates PKCE"| node_pkce
node_authentication -->|"requests authorization"| node_oidc_port
node_authentication -->|"saves and consumes"| node_state_port
node_authentication -->|"handles callback"| node_oidc_port
node_authentication -->|"extracts roles"| node_claim_mapper
node_authentication -->|"finds and writes"| node_identity_port
node_authentication -->|"resolves user"| node_user_port
node_authentication -->|"creates session"| node_session_port
node_generic_provider -->|"redirects and exchanges"| node_idp
node_generic_provider -->|"loads metadata"| node_discovery
node_generic_provider -->|"validates tokens"| node_token_validation
node_discovery -->|"fetches metadata"| node_idp
node_token_validation -->|"fetches JWKS"| node_idp
node_role_guard -->|"reads requirements"| node_require_roles
node_auth_guard -->|"loads session"| node_session_manager
node_auth_guard -->|"sets principal"| node_application
node_role_guard -->|"checks principal"| node_auth_guard
node_current_user -->|"exposes principal"| node_application
node_identity_repo -->|"implements"| node_identity_port
node_session_manager -->|"implements"| node_session_port
node_state_store -->|"implements"| node_state_port
node_session_manager -->|"stores"| node_session_domain
node_auth_module -->|"registers"| node_generic_provider
node_auth_module -->|"registers"| node_identity_repo
node_auth_module -->|"registers"| node_session_manager
node_auth_module -->|"registers"| node_state_store
node_auth_module -->|"constructs"| node_authentication
node_auth_module -->|"registers"| node_auth_service
node_auth_module -->|"registers"| node_auth_guard
node_auth_module -->|"registers"| node_role_guard
node_application -.->|"provides implementation"| node_resolver

click node_auth_module "https://github.com/luviensoft/luvien-auth/blob/main/src/nest/auth.module.ts"
click node_auth_service "https://github.com/luviensoft/luvien-auth/blob/main/src/nest/auth.service.ts"
click node_auth_guard "https://github.com/luviensoft/luvien-auth/blob/main/src/nest/guards/authentication.guard.ts"
click node_role_guard "https://github.com/luviensoft/luvien-auth/blob/main/src/nest/guards/authorization.guard.ts"
click node_current_user "https://github.com/luviensoft/luvien-auth/blob/main/src/nest/decorators/current-user.decorator.ts"
click node_require_roles "https://github.com/luviensoft/luvien-auth/blob/main/src/nest/decorators/require-roles.decorator.ts"
click node_authentication "https://github.com/luviensoft/luvien-auth/blob/main/src/core/application/authentication.service.ts"
click node_principal_identity "https://github.com/luviensoft/luvien-auth/blob/main/src/core/domain/identity.ts"
click node_provider_capability "https://github.com/luviensoft/luvien-auth/blob/main/src/core/domain/capability.ts"
click node_oidc_port "https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/oidc-provider.port.ts"
click node_identity_port "https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/identity-repository.port.ts"
click node_session_port "https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/session-manager.port.ts"
click node_state_port "https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/state-store.port.ts"
click node_user_port "https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/user-resolver.port.ts"
click node_pkce "https://github.com/luviensoft/luvien-auth/blob/main/src/protocols/oidc/oidc.pkce.ts"
click node_generic_provider "https://github.com/luviensoft/luvien-auth/blob/main/src/providers/generic-oidc/generic-oidc.provider.ts"
click node_claim_mapper "https://github.com/luviensoft/luvien-auth/blob/main/src/providers/generic-oidc/claim-mapper.ts"
click node_discovery "https://github.com/luviensoft/luvien-auth/blob/main/src/protocols/oidc/oidc.discovery.ts"
click node_identity_repo "https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-identity.repository.ts"
click node_session_manager "https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-session.manager.ts"
click node_state_store "https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-state.store.ts"
click node_session_domain "https://github.com/luviensoft/luvien-auth/blob/main/src/core/domain/session.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_module,node_auth_service,node_auth_guard,node_role_guard,node_current_user,node_require_roles,node_resolver toneBlue
class node_authentication,node_principal_identity,node_provider_capability,node_oidc_port,node_identity_port,node_session_port,node_state_port,node_user_port toneAmber
class node_pkce,node_generic_provider,node_claim_mapper,node_discovery,node_token_validation toneMint
class node_session_domain toneRose
class node_identity_repo,node_session_manager,node_state_store,node_application,node_idp toneIndigo
```

## Components

### NestJS Integration

- [Auth module](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/auth.module.ts): `src/nest/auth.module.ts`
- [Auth service](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/auth.service.ts): `src/nest/auth.service.ts`
- [Authentication guard](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/guards/authentication.guard.ts): `src/nest/guards/authentication.guard.ts`
- [Authorization guard](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/guards/authorization.guard.ts): `src/nest/guards/authorization.guard.ts`
- [Current user decorator](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/decorators/current-user.decorator.ts): `src/nest/decorators/current-user.decorator.ts`
- [Role decorator](https://github.com/luviensoft/luvien-auth/blob/main/src/nest/decorators/require-roles.decorator.ts): `src/nest/decorators/require-roles.decorator.ts`

### Authentication Core

- [Authentication service](https://github.com/luviensoft/luvien-auth/blob/main/src/core/application/authentication.service.ts): `src/core/application/authentication.service.ts`
- [Principal and identity](https://github.com/luviensoft/luvien-auth/blob/main/src/core/domain/identity.ts): `src/core/domain/identity.ts`
- [Provider capabilities](https://github.com/luviensoft/luvien-auth/blob/main/src/core/domain/capability.ts): `src/core/domain/capability.ts`
- [OIDC provider port](https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/oidc-provider.port.ts): `src/core/port/oidc-provider.port.ts`
- [Identity repository port](https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/identity-repository.port.ts): `src/core/port/identity-repository.port.ts`
- [Session manager port](https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/session-manager.port.ts): `src/core/port/session-manager.port.ts`
- [State store port](https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/state-store.port.ts): `src/core/port/state-store.port.ts`
- [User resolver port](https://github.com/luviensoft/luvien-auth/blob/main/src/core/port/user-resolver.port.ts): `src/core/port/user-resolver.port.ts`

### OIDC Provider

- [PKCE and state](https://github.com/luviensoft/luvien-auth/blob/main/src/protocols/oidc/oidc.pkce.ts): `src/protocols/oidc/oidc.pkce.ts`
- [Generic OIDC provider](https://github.com/luviensoft/luvien-auth/blob/main/src/providers/generic-oidc/generic-oidc.provider.ts): `src/providers/generic-oidc/generic-oidc.provider.ts`
- [Claim and role mapping](https://github.com/luviensoft/luvien-auth/blob/main/src/providers/generic-oidc/claim-mapper.ts): `src/providers/generic-oidc/claim-mapper.ts`
- [OIDC discovery](https://github.com/luviensoft/luvien-auth/blob/main/src/protocols/oidc/oidc.discovery.ts): `src/protocols/oidc/oidc.discovery.ts`
- **JWKS token validation**

### Identity And Sessions

- [Session model](https://github.com/luviensoft/luvien-auth/blob/main/src/core/domain/session.ts): `src/core/domain/session.ts`

### In-memory Adapters

- [In-memory identity repository](https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-identity.repository.ts): `src/persistence/in-memory/in-memory-identity.repository.ts`
- [In-memory session manager](https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-session.manager.ts): `src/persistence/in-memory/in-memory-session.manager.ts`
- [In-memory state store](https://github.com/luviensoft/luvien-auth/blob/main/src/persistence/in-memory/in-memory-state.store.ts): `src/persistence/in-memory/in-memory-state.store.ts`

### Other components

- **Application**
- **External identity provider**
- **Application user resolver**

## Connections

- Application → Auth service: starts login
- Application → Auth service: submits callback
- Auth service → Authentication service: delegates
- Auth service → In-memory session manager: reads and destroys
- Authentication service → PKCE and state: generates PKCE
- Authentication service → OIDC provider port: requests authorization
- Authentication service → State store port: saves and consumes
- Authentication service → OIDC provider port: handles callback
- Authentication service → Claim and role mapping: extracts roles
- Authentication service → Identity repository port: finds and writes
- Authentication service → User resolver port: resolves user
- Authentication service → Session manager port: creates session
- Generic OIDC provider → External identity provider: redirects and exchanges
- Generic OIDC provider → OIDC discovery: loads metadata
- Generic OIDC provider → JWKS token validation: validates tokens
- OIDC discovery → External identity provider: fetches metadata
- JWKS token validation → External identity provider: fetches JWKS
- Authorization guard → Role decorator: reads requirements
- Authentication guard → In-memory session manager: loads session
- Authentication guard → Application: sets principal
- Authorization guard → Authentication guard: checks principal
- Current user decorator → Application: exposes principal
- In-memory identity repository → Identity repository port: implements
- In-memory session manager → Session manager port: implements
- In-memory state store → State store port: implements
- In-memory session manager → Session model: stores
- Auth module → Generic OIDC provider: registers
- Auth module → In-memory identity repository: registers
- Auth module → In-memory session manager: registers
- Auth module → In-memory state store: registers
- Auth module → Authentication service: constructs
- Auth module → Auth service: registers
- Auth module → Authentication guard: registers
- Auth module → Authorization guard: registers
- Application → Application user resolver: provides implementation