Packages

@xtaskjs/security

JWT and JWE authentication, authorization decorators, and DI-aware security lifecycle.

npm install @xtaskjs/security passport passport-jwt reflect-metadata Package path: packages/security

Overview

What this package owns in the runtime

Security builds on the core route pipeline. It registers strategies, authenticates requests through Passport-compatible flows, and injects auth state into route execution context for guards and controllers.

What it provides

registerJwtStrategy() and registerJweStrategy() define authentication entry points.
Authenticated, Auth, Roles, and AllowAnonymous decorate public or protected routes.
SecurityAuthenticationService and SecurityAuthorizationService are injected through the container.
Lifecycle integration is automatic when CreateApplication() sees the package.

How it fits

Depends on @xtaskjs/core and @xtaskjs/common route metadata.
Used in node-http and Express security samples, and in this admin session implementation.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

4/5

Security

5/5

HTTP Delivery

3/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Register JWT or JWE strategies and decorate protected controllers so the framework knows what authentication surface to publish.

During CreateApplication()

Security initializes authentication and authorization services, wires Passport-compatible flows, and exposes auth context to the route pipeline.

During app.close()

The security lifecycle manager tears down its state together with the rest of the application runtime.

API Surface

Representative exports from the upstream package

Route decorators

Authenticated
Auth
Roles
AllowAnonymous

Strategy APIs

registerJwtStrategy
registerJweStrategy
JwtSecurityStrategy
JweSecurityStrategy

Injected services

InjectAuthenticationService
InjectAuthorizationService
InjectPassport
InjectSecurityLifecycleManager

Usage

Typical adoption flow

1. Register strategies

Call registerJwtStrategy() or registerJweStrategy() before startup, or use their decorator forms in configuration modules.

2. Protect routes declaratively

Apply Authenticated, Roles, Auth, or AllowAnonymous to controllers and route handlers instead of embedding auth checks in business logic.

3. Inject security services when needed

For advanced flows, inject the authentication, authorization, or lifecycle services from the DI container.

Example

Reference snippet

JWT strategy plus protected controller

import { Controller, Get } from "@xtaskjs/common";
import { Authenticated, Roles, registerJwtStrategy } from "@xtaskjs/security";

registerJwtStrategy({
  name: "default",
  default: true,
  secretOrKey: process.env.JWT_SECRET,
});

@Controller("/admin")
@Authenticated()
export class AdminController {
  @Get("/")
  @Roles("admin")
  dashboard(req: any) {
    return { user: req.user.sub, roles: req.auth.roles };
  }
}

Samples

Official samples to inspect next

Reference samples: 06-security_app and 07-security_express_app