@xtaskjs/security 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# @xtaskjs/security
+
+Security integration package for xtaskjs.
+
+## Installation
+```bash
+npm install @xtaskjs/security passport passport-jwt reflect-metadata
+```
+
+## What It Provides
+- Passport-backed JWT and JWE authentication.
+- Authorization decorators for controller routes.
+- DI tokens for auth services, Passport, and the lifecycle manager.
+- Lifecycle initialization integrated with `CreateApplication()` and `app.close()`.
+
+## Register Strategies
+```typescript
+import { registerJwtStrategy, registerJweStrategy } from "@xtaskjs/security";
+
+registerJwtStrategy({
+  name: "default",
+  default: true,
+  secretOrKey: process.env.JWT_SECRET,
+});
+
+registerJweStrategy({
+  name: "encrypted",
+  decryptionKey: process.env.JWE_SECRET,
+});
+```
+
+## Validate Callbacks
+Use `validate` to enforce application-specific claims and load the current user from your DI container.
+
+```typescript
+import { registerJwtStrategy } from "@xtaskjs/security";
+import { CreateApplication } from "@xtaskjs/core";
+
+class UserDirectory {
+  async findActiveUser(id: string) {
+    return id === "alice" ? { id: "alice", roles: ["admin"] } : undefined;
+  }
+}
+
+registerJwtStrategy({
+  name: "default",
+  default: true,
+  secretOrKey: process.env.JWT_SECRET,
+  validate: async (payload, context) => {
+    if (payload.tenant !== "xtaskjs") {
+      return false;
+    }
+
+    const userDirectory = context.container?.get(UserDirectory);
+    const user = await userDirectory?.findActiveUser(String(payload.sub || ""));
+    if (!user) {
+      return false;
+    }
+
+    return {
+      sub: user.id,
+      roles: user.roles,
+      claims: payload,
+    };
+  },
+});
+
+await CreateApplication();
+```
+
+## Secure Controllers
+```typescript
+import { Controller, Get } from "@xtaskjs/common";
+import { Authenticated, Roles, AllowAnonymous } from "@xtaskjs/security";
+
+@Controller("admin")
+@Authenticated()
+class AdminController {
+  @Get("/profile")
+  @Roles("admin")
+  profile(req: any) {
+    return {
+      user: req.user,
+      auth: req.auth,
+    };
+  }
+
+  @Get("/health")
+  @AllowAnonymous()
+  health() {
+    return { ok: true };
+  }
+}
+```
+
+## DI Integration
+```typescript
+import { Service } from "@xtaskjs/core";
+import {
+  InjectAuthenticationService,
+  InjectAuthorizationService,
+  SecurityAuthenticationService,
+  SecurityAuthorizationService,
+} from "@xtaskjs/security";
+
+@Service()
+class SecurityAwareService {
+  constructor(
+    @InjectAuthenticationService()
+    private readonly authentication: SecurityAuthenticationService,
+    @InjectAuthorizationService()
+    private readonly authorization: SecurityAuthorizationService
+  ) {}
+}
+```

package/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: ["next/babel"],
+};

package/index.ts

@@ -0,0 +1 @@
+export * from "./src";

package/jest.config.js

@@ -0,0 +1,18 @@
+/** @type {import("jest").Config} **/
+module.exports = {
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        tsconfig: "<rootDir>/tsconfig.test.json",
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^@xtaskjs/common$": "<rootDir>/../common/src/index.ts",
+    "^@xtaskjs/common/(.*)$": "<rootDir>/../common/src/$1",
+    "^@xtaskjs/core$": "<rootDir>/../core/src/index.ts",
+    "^@xtaskjs/core/(.*)$": "<rootDir>/../core/src/$1"
+  },
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@xtaskjs/security",
+  "version": "1.0.0",
+  "description": "xtaskjs security integration package",
+  "author": "Javier Rodriguez Soler",
+  "homepage": "https://xtaskjs.com",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "jest --passWithNoTests",
+    "test:coverage": "jest --coverage --runInBand",
+    "coverage:open": "xdg-open coverage/lcov-report/index.html"
+  },
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/xtaskjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xtaskjs/xtaskjs.git",
+    "directory": "packages/security"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@xtaskjs/common": "^1.0.13",
+    "@xtaskjs/core": "^1.0.13",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.1",
+    "passport-strategy": "^1.0.0"
+  },
+  "peerDependencies": {
+    "reflect-metadata": "^0.1.12 || ^0.2.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.1.2",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.1.3",
+    "nodemon": "^3.1.10",
+    "ts-jest": "^29.4.4",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.2"
+  }
+}

package/src/authentication.ts

@@ -0,0 +1,27 @@
+import { RouteExecutionContext } from "@xtaskjs/common";
+import { UnauthorizedError } from "@xtaskjs/core";
+import { getSecurityLifecycleManager } from "./lifecycle";
+import { SecurityAuthenticationResult } from "./types";
+
+export class SecurityAuthenticationService {
+  async authenticate(
+    context: RouteExecutionContext,
+    strategyNames?: string | string[]
+  ): Promise<SecurityAuthenticationResult> {
+    const result = await getSecurityLifecycleManager().authenticateContext(context, strategyNames);
+    if (!result.success) {
+      throw new UnauthorizedError(result.challenge?.message || "Unauthorized", {
+        message: result.challenge?.message || "Unauthorized",
+      });
+    }
+    return result;
+  }
+
+  async authenticateRequest(
+    request: any,
+    response?: any,
+    strategyNames?: string | string[]
+  ): Promise<SecurityAuthenticationResult> {
+    return getSecurityLifecycleManager().authenticateRequest(request, response, strategyNames);
+  }
+}

package/src/authorization.ts

@@ -0,0 +1,66 @@
+import { RouteAuthenticationContext, RouteExecutionContext } from "@xtaskjs/common";
+import { SecurityRoleMatchingMode } from "./types";
+
+const normalizeRoles = (input: unknown): string[] => {
+  if (Array.isArray(input)) {
+    return input
+      .map((value) => String(value || "").trim())
+      .filter((value) => value.length > 0);
+  }
+
+  if (typeof input === "string") {
+    return input
+      .split(/[\s,]+/)
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0);
+  }
+
+  return [];
+};
+
+export class SecurityAuthorizationService {
+  getRoles(source: RouteExecutionContext | RouteAuthenticationContext | any): string[] {
+    if (!source) {
+      return [];
+    }
+
+    if (Array.isArray(source.roles)) {
+      return normalizeRoles(source.roles);
+    }
+
+    if (source.auth && Array.isArray(source.auth.roles)) {
+      return normalizeRoles(source.auth.roles);
+    }
+
+    if (Array.isArray(source.user?.roles) || typeof source.user?.roles === "string") {
+      return normalizeRoles(source.user.roles);
+    }
+
+    if (Array.isArray(source.claims?.roles) || typeof source.claims?.roles === "string") {
+      return normalizeRoles(source.claims.roles);
+    }
+
+    if (typeof source.claims?.scope === "string") {
+      return normalizeRoles(source.claims.scope);
+    }
+
+    return [];
+  }
+
+  isAuthorized(
+    source: RouteExecutionContext | RouteAuthenticationContext | any,
+    requiredRoles: string[],
+    mode: SecurityRoleMatchingMode = "any"
+  ): boolean {
+    if (requiredRoles.length === 0) {
+      return true;
+    }
+
+    const grantedRoles = new Set(this.getRoles(source));
+    if (mode === "all") {
+      return requiredRoles.every((role) => grantedRoles.has(role));
+    }
+
+    return requiredRoles.some((role) => grantedRoles.has(role));
+  }
+}

package/src/configuration.ts

@@ -0,0 +1,90 @@
+import {
+  JweSecurityStrategyOptions,
+  JwtSecurityStrategyOptions,
+  RegisteredJweSecurityStrategyOptions,
+  RegisteredJwtSecurityStrategyOptions,
+  RegisteredSecurityStrategyOptions,
+} from "./types";
+
+const DEFAULT_STRATEGY_NAME = "default";
+const registeredStrategies = new Map<string, RegisteredSecurityStrategyOptions>();
+
+const resolveStrategyName = (
+  kind: RegisteredSecurityStrategyOptions["kind"],
+  requestedName?: string
+): string => {
+  if (typeof requestedName === "string" && requestedName.trim().length > 0) {
+    return requestedName.trim();
+  }
+
+  if (!registeredStrategies.has(DEFAULT_STRATEGY_NAME)) {
+    return DEFAULT_STRATEGY_NAME;
+  }
+
+  return `${kind}-${registeredStrategies.size + 1}`;
+};
+
+export const registerJwtStrategy = (
+  options: JwtSecurityStrategyOptions
+): RegisteredJwtSecurityStrategyOptions => {
+  const name = resolveStrategyName("jwt", options.name);
+  const definition: RegisteredJwtSecurityStrategyOptions = {
+    ...options,
+    kind: "jwt",
+    name,
+  };
+  registeredStrategies.set(name, definition);
+  return definition;
+};
+
+export const registerJweStrategy = (
+  options: JweSecurityStrategyOptions
+): RegisteredJweSecurityStrategyOptions => {
+  const name = resolveStrategyName("jwe", options.name);
+  const definition: RegisteredJweSecurityStrategyOptions = {
+    ...options,
+    kind: "jwe",
+    name,
+  };
+  registeredStrategies.set(name, definition);
+  return definition;
+};
+
+export const getRegisteredSecurityStrategies = (): RegisteredSecurityStrategyOptions[] => {
+  return Array.from(registeredStrategies.values());
+};
+
+export const clearRegisteredSecurityStrategies = (): void => {
+  registeredStrategies.clear();
+};
+
+export const getDefaultSecurityStrategyName = (): string | undefined => {
+  const explicitDefault = Array.from(registeredStrategies.values()).find(
+    (definition) => definition.default === true
+  );
+  if (explicitDefault) {
+    return explicitDefault.name;
+  }
+
+  if (registeredStrategies.size === 1) {
+    return Array.from(registeredStrategies.keys())[0];
+  }
+
+  if (registeredStrategies.has(DEFAULT_STRATEGY_NAME)) {
+    return DEFAULT_STRATEGY_NAME;
+  }
+
+  return undefined;
+};
+
+export const JwtSecurityStrategy = (options: JwtSecurityStrategyOptions): ClassDecorator => {
+  return () => {
+    registerJwtStrategy(options);
+  };
+};
+
+export const JweSecurityStrategy = (options: JweSecurityStrategyOptions): ClassDecorator => {
+  return () => {
+    registerJweStrategy(options);
+  };
+};

package/src/decorators.ts

@@ -0,0 +1,79 @@
+import { UseGuards } from "@xtaskjs/common";
+import { authenticationGuard, authorizationGuard } from "./guards";
+import {
+  normalizeStrategies,
+  setAllowAnonymousMetadata,
+  setAuthenticatedMetadata,
+  setRolesMetadata,
+} from "./metadata";
+import { AuthenticatedOptions, RolesOptions } from "./types";
+
+const applyDecorator = (
+  decorator: MethodDecorator & ClassDecorator,
+  target: any,
+  propertyKey?: string | symbol,
+  descriptor?: PropertyDescriptor
+): void => {
+  if (propertyKey === undefined) {
+    decorator(target);
+    return;
+  }
+
+  decorator(target, propertyKey, descriptor!);
+};
+
+const normalizeAuthenticatedOptions = (
+  value?: string | string[] | AuthenticatedOptions
+): AuthenticatedOptions => {
+  if (!value) {
+    return {};
+  }
+
+  if (typeof value === "string" || Array.isArray(value)) {
+    return { strategies: value };
+  }
+
+  return value;
+};
+
+export const Authenticated = (
+  value?: string | string[] | AuthenticatedOptions
+): MethodDecorator & ClassDecorator => {
+  const options = normalizeAuthenticatedOptions(value);
+  const strategies = normalizeStrategies(options.strategies);
+  const guardDecorator = UseGuards(authenticationGuard);
+
+  return (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => {
+    setAuthenticatedMetadata(target, propertyKey, strategies);
+    applyDecorator(guardDecorator, target, propertyKey, descriptor);
+  };
+};
+
+export const Auth = Authenticated;
+
+const normalizeRolesOptions = (value: RolesOptions | string, roles: string[]): RolesOptions => {
+  if (typeof value === "string") {
+    return { roles: [value, ...roles] };
+  }
+
+  return value;
+};
+
+export const Roles = (
+  value: RolesOptions | string,
+  ...roles: string[]
+): MethodDecorator & ClassDecorator => {
+  const options = normalizeRolesOptions(value, roles);
+  const guardDecorator = UseGuards(authorizationGuard);
+
+  return (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => {
+    setRolesMetadata(target, propertyKey, options);
+    applyDecorator(guardDecorator, target, propertyKey, descriptor);
+  };
+};
+
+export const AllowAnonymous = (): MethodDecorator & ClassDecorator => {
+  return (target: any, propertyKey?: string | symbol) => {
+    setAllowAnonymousMetadata(target, propertyKey);
+  };
+};

package/src/guards.ts

@@ -0,0 +1,58 @@
+import { GuardLike, RouteExecutionContext } from "@xtaskjs/common";
+import { ForbiddenError } from "@xtaskjs/core";
+import { SecurityAuthenticationService } from "./authentication";
+import { SecurityAuthorizationService } from "./authorization";
+import { resolveSecurityMetadata } from "./metadata";
+
+const AUTHENTICATION_GUARD_STATE_KEY = "xtask:security:authentication-checked";
+const AUTHORIZATION_GUARD_STATE_KEY = "xtask:security:authorization-checked";
+
+const authenticationService = new SecurityAuthenticationService();
+const authorizationService = new SecurityAuthorizationService();
+
+export const authenticationGuard: GuardLike = {
+  async canActivate(context: RouteExecutionContext): Promise<boolean> {
+    if (context.state[AUTHENTICATION_GUARD_STATE_KEY]) {
+      return true;
+    }
+
+    const metadata = resolveSecurityMetadata(context.controller?.constructor, context.handler);
+    if (metadata.allowAnonymous) {
+      context.state[AUTHENTICATION_GUARD_STATE_KEY] = true;
+      return true;
+    }
+
+    await authenticationService.authenticate(context, metadata.strategies);
+    context.state[AUTHENTICATION_GUARD_STATE_KEY] = true;
+    return true;
+  },
+};
+
+export const authorizationGuard: GuardLike = {
+  async canActivate(context: RouteExecutionContext): Promise<boolean> {
+    if (context.state[AUTHORIZATION_GUARD_STATE_KEY]) {
+      return true;
+    }
+
+    const metadata = resolveSecurityMetadata(context.controller?.constructor, context.handler);
+    if (metadata.allowAnonymous || metadata.roles.length === 0) {
+      context.state[AUTHORIZATION_GUARD_STATE_KEY] = true;
+      return true;
+    }
+
+    if (!context.auth.isAuthenticated) {
+      await authenticationGuard.canActivate(context);
+    }
+
+    if (!authorizationService.isAuthorized(context.auth, metadata.roles, metadata.roleMode)) {
+      throw new ForbiddenError("Forbidden", {
+        message: "Forbidden",
+        requiredRoles: metadata.roles,
+        actualRoles: context.auth.roles,
+      });
+    }
+
+    context.state[AUTHORIZATION_GUARD_STATE_KEY] = true;
+    return true;
+  },
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+import "reflect-metadata";
+
+export * from "./types";
+export * from "./tokens";
+export * from "./configuration";
+export * from "./authentication";
+export * from "./authorization";
+export * from "./decorators";
+export * from "./guards";
+export * from "./lifecycle";