@heliosjs/middlewares 9.0.12 → 10.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naumov Oleh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/fingerprint.d.ts

@@ -0,0 +1,15 @@
+import type { FingerprintComponent } from '@heliosjs/core/types';
+export interface UseFingerprintOptions {
+    components?: FingerprintComponent[];
+}
+/**
+ * Controller/method decorator that computes the request fingerprint and attaches
+ * it to request state (`getState('fingerprint')`) so downstream guards and
+ * interceptors can read it. Non-blocking. Optional `components` overrides the
+ * configured/default component set for this scope.
+ *
+ * @example
+ * @UseFingerprint()
+ * class MyController {}
+ */
+export declare function UseFingerprint(options?: UseFingerprintOptions): (target: any, propertyKey?: string, _descriptor?: PropertyDescriptor) => any;

package/dist/fingerprint.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseFingerprint = UseFingerprint;
+const utils_1 = require("@heliosjs/core/utils");
+/**
+ * Controller/method decorator that computes the request fingerprint and attaches
+ * it to request state (`getState('fingerprint')`) so downstream guards and
+ * interceptors can read it. Non-blocking. Optional `components` overrides the
+ * configured/default component set for this scope.
+ *
+ * @example
+ * @UseFingerprint()
+ * class MyController {}
+ */
+function UseFingerprint(options = {}) {
+    const middleware = (req, _res, next) => {
+        (0, utils_1.getOrComputeFingerprint)(req, options.components);
+        return next();
+    };
+    return function (target, propertyKey, _descriptor) {
+        const data = [{ middleware }];
+        if (propertyKey) {
+            (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
+        }
+        else {
+            (0, utils_1.defineMiddlewaresMeta)(data, target);
+        }
+        return target;
+    };
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":";;AAoBA,wCAeC;AA/BD,gDAAsF;AAMtF;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAAC,UAAiC,EAAE;IAChE,MAAM,UAAU,GAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACnD,IAAA,+BAAuB,EAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACjD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO,UAAU,MAAW,EAAE,WAAoB,EAAE,WAAgC;QAClF,MAAM,IAAI,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAC9B,IAAI,WAAW,EAAE,CAAC;YAChB,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,IAAA,6BAAqB,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import 'reflect-metadata';
 export * from './catch';
 export * from './cors';
+export * from './fingerprint';
 export * from './guard';
 export * from './interceptor';
 export * from './pipe';
+export * from './roles';
 export * from './sanitize';
 export * from './status';
 export * from './use';

package/dist/index.js

@@ -17,9 +17,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 require("reflect-metadata");
 __exportStar(require("./catch"), exports);
 __exportStar(require("./cors"), exports);
+__exportStar(require("./fingerprint"), exports);
 __exportStar(require("./guard"), exports);
 __exportStar(require("./interceptor"), exports);
 __exportStar(require("./pipe"), exports);
+__exportStar(require("./roles"), exports);
 __exportStar(require("./sanitize"), exports);
 __exportStar(require("./status"), exports);
 __exportStar(require("./use"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4BAA0B;AAE1B,0CAAwB;AACxB,yCAAuB;AACvB,0CAAwB;AACxB,gDAA8B;AAC9B,yCAAuB;AACvB,6CAA2B;AAC3B,2CAAyB;AACzB,wCAAsB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4BAA0B;AAE1B,0CAAwB;AACxB,yCAAuB;AACvB,gDAA8B;AAC9B,0CAAwB;AACxB,gDAA8B;AAC9B,yCAAuB;AACvB,0CAAwB;AACxB,6CAA2B;AAC3B,2CAAyB;AACzB,wCAAsB"}

package/dist/roles.d.ts

@@ -0,0 +1,30 @@
+import type { GuardFunction } from '@heliosjs/core/types';
+export type RoleMode = 'any' | 'all';
+export interface RolesOptions {
+    mode?: RoleMode;
+    message?: string;
+}
+type RolesArg = string | string[];
+export declare function matchRoles(required: string[], userRoles: string[], mode: RoleMode): boolean;
+export declare function normalizeArgs(args: (RolesArg | RolesOptions)[]): {
+    roles: string[];
+    options: RolesOptions;
+};
+export declare function createRolesGuard(required: string[], options: RolesOptions): GuardFunction;
+/**
+ * Restrict a controller or route to users holding the required role(s).
+ *
+ * Roles are read through the extractor configured via `@Server({ rbac })`.
+ * Default match mode is ANY (the user needs at least one listed role); pass
+ * `{ mode: 'all' }` to require every role. A failing check throws
+ * `ForbiddenError` with `options.message` (default `"Insufficient role"`).
+ *
+ * @example
+ * @Roles('admin')
+ * @example
+ * @Roles('admin', 'editor')                     // ANY
+ * @example
+ * @Roles(['admin', 'editor'], { mode: 'all' })  // ALL
+ */
+export declare function Roles(...args: (RolesArg | RolesOptions)[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export {};

package/dist/roles.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchRoles = matchRoles;
+exports.normalizeArgs = normalizeArgs;
+exports.createRolesGuard = createRolesGuard;
+exports.Roles = Roles;
+const utils_1 = require("@heliosjs/core/utils");
+function matchRoles(required, userRoles, mode) {
+    return mode === 'all'
+        ? required.every((role) => userRoles.includes(role))
+        : required.some((role) => userRoles.includes(role));
+}
+function normalizeArgs(args) {
+    let options = {};
+    let roleArgs = args;
+    const last = args[args.length - 1];
+    const isOptions = typeof last === 'object' && last !== null && !Array.isArray(last);
+    if (isOptions) {
+        options = last;
+        roleArgs = args.slice(0, -1);
+    }
+    const roles = roleArgs.flatMap((arg) => {
+        if (Array.isArray(arg))
+            return arg;
+        if (typeof arg === 'string')
+            return [arg];
+        return [];
+    });
+    return { roles, options };
+}
+function createRolesGuard(required, options) {
+    const mode = options.mode ?? 'any';
+    const message = options.message ?? 'Insufficient role';
+    return async (req) => {
+        const extractor = (0, utils_1.getRolesExtractor)();
+        if (!extractor) {
+            throw new utils_1.InvalidStateError('RBAC extractor not set; configure rbac.getRoles in @Server');
+        }
+        const raw = await extractor(req);
+        const userRoles = raw == null ? [] : Array.isArray(raw) ? raw : [raw];
+        return matchRoles(required, userRoles, mode) ? true : message;
+    };
+}
+/**
+ * Restrict a controller or route to users holding the required role(s).
+ *
+ * Roles are read through the extractor configured via `@Server({ rbac })`.
+ * Default match mode is ANY (the user needs at least one listed role); pass
+ * `{ mode: 'all' }` to require every role. A failing check throws
+ * `ForbiddenError` with `options.message` (default `"Insufficient role"`).
+ *
+ * @example
+ * @Roles('admin')
+ * @example
+ * @Roles('admin', 'editor')                     // ANY
+ * @example
+ * @Roles(['admin', 'editor'], { mode: 'all' })  // ALL
+ */
+function Roles(...args) {
+    const { roles, options } = normalizeArgs(args);
+    const guard = createRolesGuard(roles, options);
+    return function (target, propertyKey, descriptor) {
+        const data = [{ guard }];
+        if (descriptor) {
+            (0, utils_1.defineMiddlewaresMeta)(data, target, propertyKey);
+        }
+        else {
+            (0, utils_1.defineMiddlewaresMeta)(data, target);
+        }
+    };
+}
+//# sourceMappingURL=roles.js.map

package/dist/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heliosjs/middlewares",
-  "version": "9.0.12",
+  "version": "10.0.0",
   "description": "Middlewares for @heliosjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist/*",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "yarn clean && tsc -p tsconfig.build.json",
@@ -29,9 +30,10 @@
     "reflect-metadata": "^0.2.2"
   },
   "peerDependencies": {
-    "@heliosjs/core": "^3.1.13",
-    "typescript": ">=5.0.0",
+    "@heliosjs/core": "^3.2.0",
+    "@types/node": ">=20.0.0",
     "reflect-metadata": "^0.2.2",
-    "@types/node": ">=20.0.0"
-  }
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {}
 }