# nestjs/authorization architecture

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

- Interactive diagram: https://gitdiagram.com/nestjs/authorization
- Repository: https://github.com/nestjs/authorization

## Overview

This is a NestJS policy-based authorization library. Its main workflow is to declare policy abilities and route requirements, then evaluate those requirements through a guard or the injectable AuthorizationService; denials become transport-appropriate errors and can emit audit events. The graph also includes configurable module setup, policy discovery and user extraction. The README documents support across HTTP, GraphQL, WebSockets, and microservices; source excerpts show transport-specific user/error handling, while some module wiring is supported by the source index rather than an excerpt.

Main entry points: [`lib/guards/authorization.guard.ts`](https://github.com/nestjs/authorization/blob/master/lib/guards/authorization.guard.ts) (Authorization guard), [`lib/services/policy-evaluator.service.ts`](https://github.com/nestjs/authorization/blob/master/lib/services/policy-evaluator.service.ts) (Policy evaluator), [`lib/authorization.service.ts`](https://github.com/nestjs/authorization/blob/master/lib/authorization.service.ts) (Authorization service), [`lib/authorization.module.ts`](https://github.com/nestjs/authorization/blob/master/lib/authorization.module.ts) (Authorization module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_declarations["Policy declarations"]
  node_can_decorator["Can decorator<br/>[can.decorator.ts]"]
  node_policy_decorator["Policy decorator"]
  node_contracts["Policy contracts"]
  node_metadata["Authorization metadata"]
end

subgraph group_evaluation["Policy evaluation"]
  node_registry["Policy registry"]
  node_evaluator["Policy evaluator"]
end

subgraph group_enforcement["Enforcement and transports"]
  node_service["Authorization service"]
  node_guard["Authorization guard"]
  node_user["User extraction<br/>[get-user.util.ts]"]
  node_errors["Authorization errors"]
  node_transport["Transport error mapping"]
  node_interceptor["Error interceptor"]
end

subgraph group_runtime["Module and events"]
  node_module_config["Module configuration"]
  node_module["Authorization module"]
  node_events["Denial events"]
end

node_application(("Nest application"))
node_route["Route handler"]
node_policy["Policy providers"]
node_audit(("Audit consumers"))

node_application -->|"configures"| node_module_config
node_module_config -->|"configures"| node_module
node_module -->|"registers"| node_guard
node_module -->|"registers"| node_interceptor
node_policy_decorator -->|"sets metadata"| node_metadata
node_can_decorator -->|"sets metadata"| node_metadata
node_route -->|"guarded by"| node_guard
node_policy -->|"discovered by"| node_registry
node_guard -->|"extracts user"| node_user
node_guard -->|"requests decision"| node_evaluator
node_service -->|"requests decision"| node_evaluator
node_evaluator -->|"gets policy"| node_registry
node_evaluator -->|"normalizes user"| node_user
node_guard -->|"emits denial"| node_events
node_service -->|"emits denial"| node_events
node_guard -->|"throws denial"| node_errors
node_service -->|"throws denial"| node_errors
node_guard -->|"maps denial"| node_transport
node_interceptor -->|"maps denial"| node_transport
node_events -->|"publishes events"| node_audit
node_can_decorator -->|"uses requirements"| node_contracts
node_evaluator -->|"checks abilities"| node_contracts

click node_can_decorator "https://github.com/nestjs/authorization/blob/master/lib/decorators/can.decorator.ts"
click node_policy_decorator "https://github.com/nestjs/authorization/blob/master/lib/decorators/policy.decorator.ts"
click node_contracts "https://github.com/nestjs/authorization/tree/master/lib/interfaces"
click node_metadata "https://github.com/nestjs/authorization/blob/master/lib/authorization.constants.ts"
click node_module_config "https://github.com/nestjs/authorization/blob/master/lib/authorization.module-definition.ts"
click node_module "https://github.com/nestjs/authorization/blob/master/lib/authorization.module.ts"
click node_registry "https://github.com/nestjs/authorization/blob/master/lib/services/policy-registry.service.ts"
click node_evaluator "https://github.com/nestjs/authorization/blob/master/lib/services/policy-evaluator.service.ts"
click node_service "https://github.com/nestjs/authorization/blob/master/lib/authorization.service.ts"
click node_guard "https://github.com/nestjs/authorization/blob/master/lib/guards/authorization.guard.ts"
click node_user "https://github.com/nestjs/authorization/blob/master/lib/utils/get-user.util.ts"
click node_errors "https://github.com/nestjs/authorization/blob/master/lib/errors/authorization.error.ts"
click node_transport "https://github.com/nestjs/authorization/blob/master/lib/utils/transport-error.util.ts"
click node_interceptor "https://github.com/nestjs/authorization/blob/master/lib/interceptors/authorization-error.interceptor.ts"
click node_events "https://github.com/nestjs/authorization/blob/master/lib/events/authorization-events.service.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_can_decorator,node_policy_decorator,node_contracts,node_metadata toneBlue
class node_registry,node_evaluator toneAmber
class node_service,node_guard,node_user,node_errors,node_transport,node_interceptor,node_route toneMint
class node_module_config,node_module,node_events toneRose
class node_application,node_policy,node_audit toneIndigo
```

## Components

### Policy declarations

- [Can decorator](https://github.com/nestjs/authorization/blob/master/lib/decorators/can.decorator.ts): `lib/decorators/can.decorator.ts`
- [Policy decorator](https://github.com/nestjs/authorization/blob/master/lib/decorators/policy.decorator.ts): `lib/decorators/policy.decorator.ts`
- [Policy contracts](https://github.com/nestjs/authorization/tree/master/lib/interfaces): `lib/interfaces`
- [Authorization metadata](https://github.com/nestjs/authorization/blob/master/lib/authorization.constants.ts): `lib/authorization.constants.ts`

### Policy evaluation

- [Policy registry](https://github.com/nestjs/authorization/blob/master/lib/services/policy-registry.service.ts): `lib/services/policy-registry.service.ts`
- [Policy evaluator](https://github.com/nestjs/authorization/blob/master/lib/services/policy-evaluator.service.ts): `lib/services/policy-evaluator.service.ts`

### Enforcement and transports

- [Authorization service](https://github.com/nestjs/authorization/blob/master/lib/authorization.service.ts): `lib/authorization.service.ts`
- [Authorization guard](https://github.com/nestjs/authorization/blob/master/lib/guards/authorization.guard.ts): `lib/guards/authorization.guard.ts`
- [User extraction](https://github.com/nestjs/authorization/blob/master/lib/utils/get-user.util.ts): `lib/utils/get-user.util.ts`
- [Authorization errors](https://github.com/nestjs/authorization/blob/master/lib/errors/authorization.error.ts): `lib/errors/authorization.error.ts`
- [Transport error mapping](https://github.com/nestjs/authorization/blob/master/lib/utils/transport-error.util.ts): `lib/utils/transport-error.util.ts`
- [Error interceptor](https://github.com/nestjs/authorization/blob/master/lib/interceptors/authorization-error.interceptor.ts): `lib/interceptors/authorization-error.interceptor.ts`

### Module and events

- [Module configuration](https://github.com/nestjs/authorization/blob/master/lib/authorization.module-definition.ts): `lib/authorization.module-definition.ts`
- [Authorization module](https://github.com/nestjs/authorization/blob/master/lib/authorization.module.ts): `lib/authorization.module.ts`
- [Denial events](https://github.com/nestjs/authorization/blob/master/lib/events/authorization-events.service.ts): `lib/events/authorization-events.service.ts`

### Other components

- **Nest application**
- **Route handler**
- **Policy providers**
- **Audit consumers**

## Connections

- Nest application → Module configuration: configures (evidence: `lib/authorization.module-definition.ts`)
- Module configuration → Authorization module: configures (evidence: `lib/authorization.module.ts`)
- Authorization module → Authorization guard: registers (evidence: `lib/authorization.module.ts`)
- Authorization module → Error interceptor: registers (evidence: `lib/authorization.module.ts`)
- Policy decorator → Authorization metadata: sets metadata (evidence: `lib/decorators/policy.decorator.ts`)
- Can decorator → Authorization metadata: sets metadata (evidence: `lib/decorators/can.decorator.ts`)
- Route handler → Authorization guard: guarded by (evidence: `README.md`)
- Policy providers → Policy registry: discovered by (evidence: `lib/services/policy-registry.service.ts`)
- Authorization guard → User extraction: extracts user (evidence: `lib/guards/authorization.guard.ts`)
- Authorization guard → Policy evaluator: requests decision (evidence: `lib/guards/authorization.guard.ts`)
- Authorization service → Policy evaluator: requests decision (evidence: `lib/authorization.service.ts`)
- Policy evaluator → Policy registry: gets policy (evidence: `lib/services/policy-evaluator.service.ts`)
- Policy evaluator → User extraction: normalizes user (evidence: `lib/services/policy-evaluator.service.ts`)
- Authorization guard → Denial events: emits denial (evidence: `lib/guards/authorization.guard.ts`)
- Authorization service → Denial events: emits denial (evidence: `lib/authorization.service.ts`)
- Authorization guard → Authorization errors: throws denial (evidence: `lib/guards/authorization.guard.ts`)
- Authorization service → Authorization errors: throws denial (evidence: `lib/authorization.service.ts`)
- Authorization guard → Transport error mapping: maps denial (evidence: `lib/guards/authorization.guard.ts`)
- Error interceptor → Transport error mapping: maps denial (evidence: `lib/interceptors/authorization-error.interceptor.ts`)
- Denial events → Audit consumers: publishes events (evidence: `lib/events/authorization-events.service.ts`)
- Can decorator → Policy contracts: uses requirements (evidence: `lib/decorators/can.decorator.ts`)
- Policy evaluator → Policy contracts: checks abilities (evidence: `lib/services/policy-evaluator.service.ts`)
