@hazeljs/auth 0.2.0-beta.58 → 0.2.0-beta.59

package/dist/guards/tenant.guard.d.ts

@@ -0,0 +1,54 @@
+import { CanActivate, Type } from '@hazeljs/core';
+export interface TenantGuardOptions {
+    /**
+     * Where to read the expected tenant ID from the incoming request.
+     *
+     * - `'param'`   — URL segment, e.g. `/orgs/:tenantId/products`  (default)
+     * - `'header'`  — HTTP header, e.g. `X-Tenant-ID`
+     * - `'query'`   — Query string, e.g. `?tenantId=acme`
+     *
+     * @default 'param'
+     */
+    source?: 'param' | 'header' | 'query';
+    /**
+     * Name of the param / header / query key that carries the tenant ID.
+     * @default 'tenantId'
+     */
+    key?: string;
+    /**
+     * Field on the authenticated user object that holds the user's tenant ID.
+     * @default 'tenantId'
+     */
+    userField?: string;
+}
+/**
+ * Factory that returns a guard enforcing tenant-level isolation.
+ *
+ * Compares the tenant ID carried by the request (from a URL param, header,
+ * or query param) against the tenant ID stored on the authenticated user
+ * (from the JWT payload).  Returns 403 if they do not match.
+ *
+ * Must be used after JwtAuthGuard so that `req.user` is populated.
+ *
+ * @example
+ * ```ts
+ * // URL param: GET /orgs/:tenantId/invoices
+ * @UseGuards(JwtAuthGuard, TenantGuard())
+ * @Controller('/orgs/:tenantId/invoices')
+ * export class InvoicesController {}
+ *
+ * // Header: X-Org-ID
+ * @UseGuards(JwtAuthGuard, TenantGuard({ source: 'header', key: 'x-org-id' }))
+ * @Controller('/invoices')
+ * export class InvoicesController {}
+ *
+ * // Superadmins bypass tenant check:
+ * @UseGuards(JwtAuthGuard, TenantGuard({ bypassRoles: ['superadmin'] }))
+ * @Controller('/orgs/:tenantId/invoices')
+ * export class InvoicesController {}
+ * ```
+ */
+export declare function TenantGuard(options?: TenantGuardOptions & {
+    bypassRoles?: string[];
+}): Type<CanActivate>;
+//# sourceMappingURL=tenant.guard.d.ts.map

package/dist/guards/tenant.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.guard.d.ts","sourceRoot":"","sources":["../../src/guards/tenant.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,WAAW,EAAoB,IAAI,EAAkB,MAAM,eAAe,CAAC;AAIhG,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IAEtC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAkB,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC5D,IAAI,CAAC,WAAW,CAAC,CAsEnB"}

package/dist/guards/tenant.guard.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantGuard = TenantGuard;
+const core_1 = require("@hazeljs/core");
+const tenant_context_1 = require("../tenant/tenant-context");
+/**
+ * Factory that returns a guard enforcing tenant-level isolation.
+ *
+ * Compares the tenant ID carried by the request (from a URL param, header,
+ * or query param) against the tenant ID stored on the authenticated user
+ * (from the JWT payload).  Returns 403 if they do not match.
+ *
+ * Must be used after JwtAuthGuard so that `req.user` is populated.
+ *
+ * @example
+ * ```ts
+ * // URL param: GET /orgs/:tenantId/invoices
+ * @UseGuards(JwtAuthGuard, TenantGuard())
+ * @Controller('/orgs/:tenantId/invoices')
+ * export class InvoicesController {}
+ *
+ * // Header: X-Org-ID
+ * @UseGuards(JwtAuthGuard, TenantGuard({ source: 'header', key: 'x-org-id' }))
+ * @Controller('/invoices')
+ * export class InvoicesController {}
+ *
+ * // Superadmins bypass tenant check:
+ * @UseGuards(JwtAuthGuard, TenantGuard({ bypassRoles: ['superadmin'] }))
+ * @Controller('/orgs/:tenantId/invoices')
+ * export class InvoicesController {}
+ * ```
+ */
+function TenantGuard(options = {}) {
+    const { source = 'param', key = 'tenantId', userField = 'tenantId', bypassRoles = [] } = options;
+    let TenantGuardMixin = class TenantGuardMixin {
+        canActivate(context) {
+            const req = context.switchToHttp().getRequest();
+            const ctx = context.switchToHttp().getContext();
+            const user = req.user;
+            if (!user) {
+                const err = Object.assign(new Error('Unauthorized'), { status: 401 });
+                throw err;
+            }
+            // Privileged roles can bypass the tenant check entirely.
+            // Still seed the context so their own queries are naturally scoped.
+            if (bypassRoles.includes(user.role)) {
+                const bypassTenantId = user[userField];
+                if (bypassTenantId)
+                    tenant_context_1.TenantContext.enterWith(bypassTenantId);
+                return true;
+            }
+            const userTenantId = user[userField];
+            if (!userTenantId) {
+                const err = Object.assign(new Error(`User is not associated with any tenant (missing "${userField}")`), { status: 403 });
+                throw err;
+            }
+            // Extract the request-level tenant ID from the configured source.
+            let requestTenantId;
+            switch (source) {
+                case 'param':
+                    requestTenantId = ctx.params?.[key];
+                    break;
+                case 'header':
+                    requestTenantId = ctx.headers?.[key.toLowerCase()];
+                    break;
+                case 'query':
+                    requestTenantId = ctx.query?.[key];
+                    break;
+            }
+            if (!requestTenantId) {
+                const err = Object.assign(new Error(`Tenant ID not found in request ${source} "${key}"`), {
+                    status: 400,
+                });
+                throw err;
+            }
+            if (userTenantId !== requestTenantId) {
+                const err = Object.assign(new Error('Access denied: resource belongs to a different tenant'), { status: 403 });
+                throw err;
+            }
+            // Seed AsyncLocalStorage so repositories can call tenantCtx.requireId()
+            // without needing tenantId passed through every function parameter.
+            tenant_context_1.TenantContext.enterWith(userTenantId);
+            return true;
+        }
+    };
+    TenantGuardMixin = __decorate([
+        (0, core_1.Injectable)()
+    ], TenantGuardMixin);
+    return TenantGuardMixin;
+}

package/dist/index.d.ts

@@ -1,8 +1,18 @@
 /**
  * @hazeljs/auth - Authentication module for HazelJS
  */
-export { AuthGuard } from './auth.guard';
+export { AuthGuard, Auth } from './auth.guard';
 export { AuthService } from './auth.service';
+export type { AuthUser } from './auth.service';
 export { JwtModule } from './jwt/jwt.module';
 export { JwtService } from './jwt/jwt.service';
+export { JwtAuthGuard } from './guards/jwt-auth.guard';
+export { RoleGuard } from './guards/role.guard';
+export type { RoleGuardOptions } from './guards/role.guard';
+export { TenantGuard } from './guards/tenant.guard';
+export type { TenantGuardOptions } from './guards/tenant.guard';
+export { TenantContext } from './tenant/tenant-context';
+export { RoleHierarchy, DEFAULT_ROLE_HIERARCHY } from './utils/role-hierarchy';
+export type { RoleHierarchyMap } from './utils/role-hierarchy';
+export { CurrentUser } from './decorators/current-user.decorator';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC/E,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/index.js

@@ -3,12 +3,26 @@
  * @hazeljs/auth - Authentication module for HazelJS
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JwtService = exports.JwtModule = exports.AuthService = exports.AuthGuard = void 0;
+exports.CurrentUser = exports.DEFAULT_ROLE_HIERARCHY = exports.RoleHierarchy = exports.TenantContext = exports.TenantGuard = exports.RoleGuard = exports.JwtAuthGuard = exports.JwtService = exports.JwtModule = exports.AuthService = exports.Auth = exports.AuthGuard = void 0;
 var auth_guard_1 = require("./auth.guard");
 Object.defineProperty(exports, "AuthGuard", { enumerable: true, get: function () { return auth_guard_1.AuthGuard; } });
+Object.defineProperty(exports, "Auth", { enumerable: true, get: function () { return auth_guard_1.Auth; } });
 var auth_service_1 = require("./auth.service");
 Object.defineProperty(exports, "AuthService", { enumerable: true, get: function () { return auth_service_1.AuthService; } });
 var jwt_module_1 = require("./jwt/jwt.module");
 Object.defineProperty(exports, "JwtModule", { enumerable: true, get: function () { return jwt_module_1.JwtModule; } });
 var jwt_service_1 = require("./jwt/jwt.service");
 Object.defineProperty(exports, "JwtService", { enumerable: true, get: function () { return jwt_service_1.JwtService; } });
+var jwt_auth_guard_1 = require("./guards/jwt-auth.guard");
+Object.defineProperty(exports, "JwtAuthGuard", { enumerable: true, get: function () { return jwt_auth_guard_1.JwtAuthGuard; } });
+var role_guard_1 = require("./guards/role.guard");
+Object.defineProperty(exports, "RoleGuard", { enumerable: true, get: function () { return role_guard_1.RoleGuard; } });
+var tenant_guard_1 = require("./guards/tenant.guard");
+Object.defineProperty(exports, "TenantGuard", { enumerable: true, get: function () { return tenant_guard_1.TenantGuard; } });
+var tenant_context_1 = require("./tenant/tenant-context");
+Object.defineProperty(exports, "TenantContext", { enumerable: true, get: function () { return tenant_context_1.TenantContext; } });
+var role_hierarchy_1 = require("./utils/role-hierarchy");
+Object.defineProperty(exports, "RoleHierarchy", { enumerable: true, get: function () { return role_hierarchy_1.RoleHierarchy; } });
+Object.defineProperty(exports, "DEFAULT_ROLE_HIERARCHY", { enumerable: true, get: function () { return role_hierarchy_1.DEFAULT_ROLE_HIERARCHY; } });
+var current_user_decorator_1 = require("./decorators/current-user.decorator");
+Object.defineProperty(exports, "CurrentUser", { enumerable: true, get: function () { return current_user_decorator_1.CurrentUser; } });

package/dist/tenant/tenant-context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Provides request-scoped tenant context via AsyncLocalStorage.
+ *
+ * ─── Why two layers? ──────────────────────────────────────────────────────────
+ * TenantGuard enforces isolation at the HTTP layer — it rejects requests where
+ * the JWT tenant doesn't match the route tenant.  That's necessary but not
+ * sufficient: a bug in service code could still query another tenant's rows if
+ * the guard is misconfigured or skipped.
+ *
+ * TenantContext closes that gap at the DATA layer.  After the guard validates
+ * the request, it calls TenantContext.enterWith(tenantId) which seeds an
+ * AsyncLocalStorage store for the remainder of the request's async call chain.
+ * Every repository/service that injects TenantContext can then call
+ * requireId() without receiving tenantId as a function parameter.
+ *
+ * ─── Usage in a repository ───────────────────────────────────────────────────
+ * ```ts
+ * @Service()
+ * export class OrdersRepository {
+ *   constructor(private readonly tenantCtx: TenantContext) {}
+ *
+ *   findAll() {
+ *     const tenantId = this.tenantCtx.requireId();
+ *     return db.query('SELECT * FROM orders WHERE tenant_id = $1', [tenantId]);
+ *   }
+ *
+ *   findById(id: string) {
+ *     const tenantId = this.tenantCtx.requireId();
+ *     // Even a direct ID lookup is scoped — prevents horizontal privilege escalation
+ *     return db.query(
+ *       'SELECT * FROM orders WHERE id = $1 AND tenant_id = $2',
+ *       [id, tenantId]
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * ─── How it propagates ────────────────────────────────────────────────────────
+ * Node.js AsyncLocalStorage propagates through the async call graph.
+ * TenantGuard calls enterWith() during guard execution; because the route
+ * handler is called afterwards in the same async chain, it (and everything
+ * it awaits) automatically has access to the stored tenant ID.
+ */
+export declare class TenantContext {
+    /**
+     * Returns the current tenant ID, or `undefined` if called outside a
+     * request context (e.g. during startup or in a background job).
+     */
+    getId(): string | undefined;
+    /**
+     * Returns the current tenant ID and throws if it is not set.
+     *
+     * Use this in any repository or service method that must never run without
+     * a tenant — it acts as a last-resort safety net even if the guard was
+     * accidentally omitted on a route.
+     */
+    requireId(): string;
+    /**
+     * Seeds the current async context with the given tenant ID.
+     *
+     * Called internally by TenantGuard after it validates the request.
+     * Unlike `run()`, `enterWith` propagates through the rest of the current
+     * async execution chain without requiring a wrapping callback — which
+     * makes it the right tool for seeding from within a guard.
+     */
+    static enterWith(tenantId: string): void;
+    /**
+     * Wraps a callback so that everything inside it (and all async operations
+     * it spawns) runs with the given tenant ID in context.
+     *
+     * Use this when you need explicit scoping, e.g. in background jobs or tests:
+     *
+     * ```ts
+     * await TenantContext.run('acme', async () => {
+     *   await ordersService.processPendingOrders();
+     * });
+     * ```
+     */
+    static run<T>(tenantId: string, fn: () => T): T;
+}
+//# sourceMappingURL=tenant-context.d.ts.map

package/dist/tenant/tenant-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.d.ts","sourceRoot":"","sources":["../../src/tenant/tenant-context.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,aAAa;IACxB;;;OAGG;IACH,KAAK,IAAI,MAAM,GAAG,SAAS;IAI3B;;;;;;OAMG;IACH,SAAS,IAAI,MAAM;IAanB;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;CAGhD"}

package/dist/tenant/tenant-context.js

@@ -0,0 +1,108 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantContext = void 0;
+const async_hooks_1 = require("async_hooks");
+const core_1 = require("@hazeljs/core");
+const storage = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Provides request-scoped tenant context via AsyncLocalStorage.
+ *
+ * ─── Why two layers? ──────────────────────────────────────────────────────────
+ * TenantGuard enforces isolation at the HTTP layer — it rejects requests where
+ * the JWT tenant doesn't match the route tenant.  That's necessary but not
+ * sufficient: a bug in service code could still query another tenant's rows if
+ * the guard is misconfigured or skipped.
+ *
+ * TenantContext closes that gap at the DATA layer.  After the guard validates
+ * the request, it calls TenantContext.enterWith(tenantId) which seeds an
+ * AsyncLocalStorage store for the remainder of the request's async call chain.
+ * Every repository/service that injects TenantContext can then call
+ * requireId() without receiving tenantId as a function parameter.
+ *
+ * ─── Usage in a repository ───────────────────────────────────────────────────
+ * ```ts
+ * @Service()
+ * export class OrdersRepository {
+ *   constructor(private readonly tenantCtx: TenantContext) {}
+ *
+ *   findAll() {
+ *     const tenantId = this.tenantCtx.requireId();
+ *     return db.query('SELECT * FROM orders WHERE tenant_id = $1', [tenantId]);
+ *   }
+ *
+ *   findById(id: string) {
+ *     const tenantId = this.tenantCtx.requireId();
+ *     // Even a direct ID lookup is scoped — prevents horizontal privilege escalation
+ *     return db.query(
+ *       'SELECT * FROM orders WHERE id = $1 AND tenant_id = $2',
+ *       [id, tenantId]
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * ─── How it propagates ────────────────────────────────────────────────────────
+ * Node.js AsyncLocalStorage propagates through the async call graph.
+ * TenantGuard calls enterWith() during guard execution; because the route
+ * handler is called afterwards in the same async chain, it (and everything
+ * it awaits) automatically has access to the stored tenant ID.
+ */
+let TenantContext = class TenantContext {
+    /**
+     * Returns the current tenant ID, or `undefined` if called outside a
+     * request context (e.g. during startup or in a background job).
+     */
+    getId() {
+        return storage.getStore()?.tenantId;
+    }
+    /**
+     * Returns the current tenant ID and throws if it is not set.
+     *
+     * Use this in any repository or service method that must never run without
+     * a tenant — it acts as a last-resort safety net even if the guard was
+     * accidentally omitted on a route.
+     */
+    requireId() {
+        const id = this.getId();
+        if (!id) {
+            throw Object.assign(new Error('TenantContext: no tenant ID found. ' + 'Ensure TenantGuard is applied to the route.'), { status: 500 });
+        }
+        return id;
+    }
+    /**
+     * Seeds the current async context with the given tenant ID.
+     *
+     * Called internally by TenantGuard after it validates the request.
+     * Unlike `run()`, `enterWith` propagates through the rest of the current
+     * async execution chain without requiring a wrapping callback — which
+     * makes it the right tool for seeding from within a guard.
+     */
+    static enterWith(tenantId) {
+        storage.enterWith({ tenantId });
+    }
+    /**
+     * Wraps a callback so that everything inside it (and all async operations
+     * it spawns) runs with the given tenant ID in context.
+     *
+     * Use this when you need explicit scoping, e.g. in background jobs or tests:
+     *
+     * ```ts
+     * await TenantContext.run('acme', async () => {
+     *   await ordersService.processPendingOrders();
+     * });
+     * ```
+     */
+    static run(tenantId, fn) {
+        return storage.run({ tenantId }, fn);
+    }
+};
+exports.TenantContext = TenantContext;
+exports.TenantContext = TenantContext = __decorate([
+    (0, core_1.Injectable)()
+], TenantContext);

package/dist/utils/role-hierarchy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Describes which roles a given role "inherits".
+ *
+ * Example: `{ superadmin: ['admin'], admin: ['manager'], manager: ['user'] }`
+ * means superadmin implicitly satisfies any check for admin, manager, or user.
+ */
+export type RoleHierarchyMap = Record<string, string[]>;
+/**
+ * A sensible default hierarchy for most applications.
+ * Override by passing your own map to RoleHierarchy or to RoleGuard.
+ *
+ *   superadmin → admin → manager → user
+ */
+export declare const DEFAULT_ROLE_HIERARCHY: RoleHierarchyMap;
+/**
+ * Resolves inherited roles so that a higher-level role implicitly satisfies
+ * requirements for any role it inherits.
+ *
+ * @example
+ * ```ts
+ * const h = new RoleHierarchy({ admin: ['editor'], editor: ['viewer'] });
+ *
+ * h.satisfies('admin', 'viewer')  // true  — admin → editor → viewer
+ * h.satisfies('editor', 'admin')  // false — editor does not inherit admin
+ * h.resolve('admin')              // Set { 'admin', 'editor', 'viewer' }
+ * ```
+ */
+export declare class RoleHierarchy {
+    private readonly map;
+    constructor(map?: RoleHierarchyMap);
+    /**
+     * Returns true if `userRole` satisfies the `requiredRole` check, either
+     * directly (same role) or via inheritance.
+     */
+    satisfies(userRole: string, requiredRole: string): boolean;
+    /**
+     * Returns the complete set of roles that `role` covers (itself plus all
+     * transitively inherited roles).
+     */
+    resolve(role: string): Set<string>;
+}
+//# sourceMappingURL=role-hierarchy.d.ts.map

package/dist/utils/role-hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-hierarchy.d.ts","sourceRoot":"","sources":["../../src/utils/role-hierarchy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,gBAKpC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,GAAE,gBAAyC;IAE3E;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAI1D;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;CAcnC"}

package/dist/utils/role-hierarchy.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleHierarchy = exports.DEFAULT_ROLE_HIERARCHY = void 0;
+/**
+ * A sensible default hierarchy for most applications.
+ * Override by passing your own map to RoleHierarchy or to RoleGuard.
+ *
+ *   superadmin → admin → manager → user
+ */
+exports.DEFAULT_ROLE_HIERARCHY = {
+    superadmin: ['admin'],
+    admin: ['manager'],
+    manager: ['user'],
+    user: [],
+};
+/**
+ * Resolves inherited roles so that a higher-level role implicitly satisfies
+ * requirements for any role it inherits.
+ *
+ * @example
+ * ```ts
+ * const h = new RoleHierarchy({ admin: ['editor'], editor: ['viewer'] });
+ *
+ * h.satisfies('admin', 'viewer')  // true  — admin → editor → viewer
+ * h.satisfies('editor', 'admin')  // false — editor does not inherit admin
+ * h.resolve('admin')              // Set { 'admin', 'editor', 'viewer' }
+ * ```
+ */
+class RoleHierarchy {
+    constructor(map = exports.DEFAULT_ROLE_HIERARCHY) {
+        this.map = map;
+    }
+    /**
+     * Returns true if `userRole` satisfies the `requiredRole` check, either
+     * directly (same role) or via inheritance.
+     */
+    satisfies(userRole, requiredRole) {
+        return this.resolve(userRole).has(requiredRole);
+    }
+    /**
+     * Returns the complete set of roles that `role` covers (itself plus all
+     * transitively inherited roles).
+     */
+    resolve(role) {
+        const visited = new Set();
+        const queue = [role];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (!visited.has(current)) {
+                visited.add(current);
+                (this.map[current] ?? []).forEach((child) => queue.push(child));
+            }
+        }
+        return visited;
+    }
+}
+exports.RoleHierarchy = RoleHierarchy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazeljs/auth",
-  "version": "0.2.0-beta.58",
+  "version": "0.2.0-beta.59",
   "description": "Authentication and JWT module for HazelJS framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,5 +51,5 @@
   "peerDependencies": {
     "@hazeljs/core": ">=0.2.0-beta.0"
   },
-  "gitHead": "ce3821b373043284ac4847315371efb137dc860d"
+  "gitHead": "f6d8ee8162a40e2298ccce46d843269838bbe6ff"
 }