@xtaskjs/security 1.0.0 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 1.0.3 (2026-03-14)
+
+**Note:** Version bump only for package @xtaskjs/security
+
+
+
+
+
+## 1.0.2 (2026-03-14)
+
+**Note:** Version bump only for package @xtaskjs/security
+
+
+
+
+
+## 1.0.1 (2026-03-14)
+
+**Note:** Version bump only for package @xtaskjs/security

package/dist/authentication.d.ts

@@ -0,0 +1,6 @@
+import { RouteExecutionContext } from "@xtaskjs/common";
+import { SecurityAuthenticationResult } from "./types";
+export declare class SecurityAuthenticationService {
+    authenticate(context: RouteExecutionContext, strategyNames?: string | string[]): Promise<SecurityAuthenticationResult>;
+    authenticateRequest(request: any, response?: any, strategyNames?: string | string[]): Promise<SecurityAuthenticationResult>;
+}

package/dist/authentication.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityAuthenticationService = void 0;
+const core_1 = require("@xtaskjs/core");
+const lifecycle_1 = require("./lifecycle");
+class SecurityAuthenticationService {
+    async authenticate(context, strategyNames) {
+        const result = await (0, lifecycle_1.getSecurityLifecycleManager)().authenticateContext(context, strategyNames);
+        if (!result.success) {
+            throw new core_1.UnauthorizedError(result.challenge?.message || "Unauthorized", {
+                message: result.challenge?.message || "Unauthorized",
+            });
+        }
+        return result;
+    }
+    async authenticateRequest(request, response, strategyNames) {
+        return (0, lifecycle_1.getSecurityLifecycleManager)().authenticateRequest(request, response, strategyNames);
+    }
+}
+exports.SecurityAuthenticationService = SecurityAuthenticationService;

package/dist/authorization.d.ts

@@ -0,0 +1,6 @@
+import { RouteAuthenticationContext, RouteExecutionContext } from "@xtaskjs/common";
+import { SecurityRoleMatchingMode } from "./types";
+export declare class SecurityAuthorizationService {
+    getRoles(source: RouteExecutionContext | RouteAuthenticationContext | any): string[];
+    isAuthorized(source: RouteExecutionContext | RouteAuthenticationContext | any, requiredRoles: string[], mode?: SecurityRoleMatchingMode): boolean;
+}

package/dist/authorization.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityAuthorizationService = void 0;
+const normalizeRoles = (input) => {
+    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 [];
+};
+class SecurityAuthorizationService {
+    getRoles(source) {
+        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, requiredRoles, mode = "any") {
+        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));
+    }
+}
+exports.SecurityAuthorizationService = SecurityAuthorizationService;

package/dist/configuration.d.ts

@@ -0,0 +1,8 @@
+import { JweSecurityStrategyOptions, JwtSecurityStrategyOptions, RegisteredJweSecurityStrategyOptions, RegisteredJwtSecurityStrategyOptions, RegisteredSecurityStrategyOptions } from "./types";
+export declare const registerJwtStrategy: (options: JwtSecurityStrategyOptions) => RegisteredJwtSecurityStrategyOptions;
+export declare const registerJweStrategy: (options: JweSecurityStrategyOptions) => RegisteredJweSecurityStrategyOptions;
+export declare const getRegisteredSecurityStrategies: () => RegisteredSecurityStrategyOptions[];
+export declare const clearRegisteredSecurityStrategies: () => void;
+export declare const getDefaultSecurityStrategyName: () => string | undefined;
+export declare const JwtSecurityStrategy: (options: JwtSecurityStrategyOptions) => ClassDecorator;
+export declare const JweSecurityStrategy: (options: JweSecurityStrategyOptions) => ClassDecorator;

package/dist/configuration.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JweSecurityStrategy = exports.JwtSecurityStrategy = exports.getDefaultSecurityStrategyName = exports.clearRegisteredSecurityStrategies = exports.getRegisteredSecurityStrategies = exports.registerJweStrategy = exports.registerJwtStrategy = void 0;
+const DEFAULT_STRATEGY_NAME = "default";
+const registeredStrategies = new Map();
+const resolveStrategyName = (kind, requestedName) => {
+    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}`;
+};
+const registerJwtStrategy = (options) => {
+    const name = resolveStrategyName("jwt", options.name);
+    const definition = {
+        ...options,
+        kind: "jwt",
+        name,
+    };
+    registeredStrategies.set(name, definition);
+    return definition;
+};
+exports.registerJwtStrategy = registerJwtStrategy;
+const registerJweStrategy = (options) => {
+    const name = resolveStrategyName("jwe", options.name);
+    const definition = {
+        ...options,
+        kind: "jwe",
+        name,
+    };
+    registeredStrategies.set(name, definition);
+    return definition;
+};
+exports.registerJweStrategy = registerJweStrategy;
+const getRegisteredSecurityStrategies = () => {
+    return Array.from(registeredStrategies.values());
+};
+exports.getRegisteredSecurityStrategies = getRegisteredSecurityStrategies;
+const clearRegisteredSecurityStrategies = () => {
+    registeredStrategies.clear();
+};
+exports.clearRegisteredSecurityStrategies = clearRegisteredSecurityStrategies;
+const getDefaultSecurityStrategyName = () => {
+    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;
+};
+exports.getDefaultSecurityStrategyName = getDefaultSecurityStrategyName;
+const JwtSecurityStrategy = (options) => {
+    return () => {
+        (0, exports.registerJwtStrategy)(options);
+    };
+};
+exports.JwtSecurityStrategy = JwtSecurityStrategy;
+const JweSecurityStrategy = (options) => {
+    return () => {
+        (0, exports.registerJweStrategy)(options);
+    };
+};
+exports.JweSecurityStrategy = JweSecurityStrategy;

package/dist/decorators.d.ts

@@ -0,0 +1,5 @@
+import { AuthenticatedOptions, RolesOptions } from "./types";
+export declare const Authenticated: (value?: string | string[] | AuthenticatedOptions) => MethodDecorator & ClassDecorator;
+export declare const Auth: (value?: string | string[] | AuthenticatedOptions) => MethodDecorator & ClassDecorator;
+export declare const Roles: (value: RolesOptions | string, ...roles: string[]) => MethodDecorator & ClassDecorator;
+export declare const AllowAnonymous: () => MethodDecorator & ClassDecorator;

package/dist/decorators.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AllowAnonymous = exports.Roles = exports.Auth = exports.Authenticated = void 0;
+const common_1 = require("@xtaskjs/common");
+const guards_1 = require("./guards");
+const metadata_1 = require("./metadata");
+const applyDecorator = (decorator, target, propertyKey, descriptor) => {
+    if (propertyKey === undefined) {
+        decorator(target);
+        return;
+    }
+    decorator(target, propertyKey, descriptor);
+};
+const normalizeAuthenticatedOptions = (value) => {
+    if (!value) {
+        return {};
+    }
+    if (typeof value === "string" || Array.isArray(value)) {
+        return { strategies: value };
+    }
+    return value;
+};
+const Authenticated = (value) => {
+    const options = normalizeAuthenticatedOptions(value);
+    const strategies = (0, metadata_1.normalizeStrategies)(options.strategies);
+    const guardDecorator = (0, common_1.UseGuards)(guards_1.authenticationGuard);
+    return (target, propertyKey, descriptor) => {
+        (0, metadata_1.setAuthenticatedMetadata)(target, propertyKey, strategies);
+        applyDecorator(guardDecorator, target, propertyKey, descriptor);
+    };
+};
+exports.Authenticated = Authenticated;
+exports.Auth = exports.Authenticated;
+const normalizeRolesOptions = (value, roles) => {
+    if (typeof value === "string") {
+        return { roles: [value, ...roles] };
+    }
+    return value;
+};
+const Roles = (value, ...roles) => {
+    const options = normalizeRolesOptions(value, roles);
+    const guardDecorator = (0, common_1.UseGuards)(guards_1.authorizationGuard);
+    return (target, propertyKey, descriptor) => {
+        (0, metadata_1.setRolesMetadata)(target, propertyKey, options);
+        applyDecorator(guardDecorator, target, propertyKey, descriptor);
+    };
+};
+exports.Roles = Roles;
+const AllowAnonymous = () => {
+    return (target, propertyKey) => {
+        (0, metadata_1.setAllowAnonymousMetadata)(target, propertyKey);
+    };
+};
+exports.AllowAnonymous = AllowAnonymous;

package/dist/guards.d.ts

@@ -0,0 +1,3 @@
+import { GuardLike } from "@xtaskjs/common";
+export declare const authenticationGuard: GuardLike;
+export declare const authorizationGuard: GuardLike;

package/dist/guards.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizationGuard = exports.authenticationGuard = void 0;
+const core_1 = require("@xtaskjs/core");
+const authentication_1 = require("./authentication");
+const authorization_1 = require("./authorization");
+const metadata_1 = require("./metadata");
+const AUTHENTICATION_GUARD_STATE_KEY = "xtask:security:authentication-checked";
+const AUTHORIZATION_GUARD_STATE_KEY = "xtask:security:authorization-checked";
+const authenticationService = new authentication_1.SecurityAuthenticationService();
+const authorizationService = new authorization_1.SecurityAuthorizationService();
+exports.authenticationGuard = {
+    async canActivate(context) {
+        if (context.state[AUTHENTICATION_GUARD_STATE_KEY]) {
+            return true;
+        }
+        const metadata = (0, metadata_1.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;
+    },
+};
+exports.authorizationGuard = {
+    async canActivate(context) {
+        if (context.state[AUTHORIZATION_GUARD_STATE_KEY]) {
+            return true;
+        }
+        const metadata = (0, metadata_1.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 exports.authenticationGuard.canActivate(context);
+        }
+        if (!authorizationService.isAuthorized(context.auth, metadata.roles, metadata.roleMode)) {
+            throw new core_1.ForbiddenError("Forbidden", {
+                message: "Forbidden",
+                requiredRoles: metadata.roles,
+                actualRoles: context.auth.roles,
+            });
+        }
+        context.state[AUTHORIZATION_GUARD_STATE_KEY] = true;
+        return true;
+    },
+};

package/{src/index.ts → dist/index.d.ts}

@@ -1,5 +1,4 @@
 import "reflect-metadata";
-
 export * from "./types";
 export * from "./tokens";
 export * from "./configuration";
@@ -7,4 +6,4 @@ export * from "./authentication";
 export * from "./authorization";
 export * from "./decorators";
 export * from "./guards";
-export * from "./lifecycle";
+export * from "./lifecycle";

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+__exportStar(require("./types"), exports);
+__exportStar(require("./tokens"), exports);
+__exportStar(require("./configuration"), exports);
+__exportStar(require("./authentication"), exports);
+__exportStar(require("./authorization"), exports);
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./guards"), exports);
+__exportStar(require("./lifecycle"), exports);

package/dist/lifecycle.d.ts

@@ -0,0 +1,25 @@
+import { RouteExecutionContext } from "@xtaskjs/common";
+import { Container } from "@xtaskjs/core";
+import { SecurityAuthenticationResult } from "./types";
+export declare class SecurityLifecycleManager {
+    private passportInstance;
+    private readonly strategyDefinitions;
+    private container?;
+    initialize(container?: Container): Promise<void>;
+    destroy(): Promise<void>;
+    getPassport(): any;
+    authenticateContext(context: RouteExecutionContext, strategyNames?: string | string[]): Promise<SecurityAuthenticationResult>;
+    authenticateRequest(request: any, _response?: any, strategyNames?: string | string[]): Promise<SecurityAuthenticationResult>;
+    private resolveStrategyNames;
+    private registerJwtStrategy;
+    private runPassportStrategy;
+    private registerContainerBindings;
+}
+export declare const initializeSecurityIntegration: (container?: Container) => Promise<void>;
+export declare const shutdownSecurityIntegration: () => Promise<void>;
+export declare const getSecurityLifecycleManager: () => SecurityLifecycleManager;
+export declare const resetSecurityIntegration: () => Promise<void>;
+export declare const InjectAuthenticationService: () => ParameterDecorator & PropertyDecorator;
+export declare const InjectAuthorizationService: () => ParameterDecorator & PropertyDecorator;
+export declare const InjectPassport: () => ParameterDecorator & PropertyDecorator;
+export declare const InjectSecurityLifecycleManager: () => ParameterDecorator & PropertyDecorator;