@spinajs/rbac 2.0.522 → 2.0.523

package/lib/mjs/permission-service.d.ts

@@ -0,0 +1,80 @@
+import { Permission } from 'accesscontrol';
+import { Class } from '@spinajs/di';
+import type { User } from './models/User.js';
+export type PermissionVerb = 'create' | 'read' | 'update' | 'delete';
+export type PermissionGrantScope = 'any' | 'own' | 'none';
+/**
+ * Base for per-domain permission services: decides and explains authorization at the
+ * domain layer, BEFORE any effect — the ORM rbac middleware stays the enforcement
+ * backstop. One concrete class per rbac resource; public API is domain-named assert
+ * methods built from the protected primitives below. The rbac User model is the actor —
+ * no wrapper objects.
+ *
+ * Stateless by contract: no instance fields in subclasses. Spinajs DI caches resolved
+ * instances, so `@FromDI()` injection in controllers, `@Autoinject` fields and
+ * `usePermission()` anywhere else share one instance safely.
+ */
+export declare abstract class PermissionService {
+    /** Rbac resource name this service guards — same string the grants config uses. */
+    protected abstract readonly Resource: string;
+    /**
+     * The acting user: explicit argument wins, else the rbac AsyncLocalStorage store.
+     * No user anywhere throws — a permission decision must never silently pass without
+     * an identity.
+     */
+    protected user(user?: User): User;
+    /** Roles the decision runs against — the shared ActiveRole rule against the ambient store. */
+    protected effectiveRoles(user: User): string[];
+    protected grantScope(user: User, verb: PermissionVerb): PermissionGrantScope;
+    /** Single guarded probe against this.Resource — an unknown role answers false. */
+    protected can(roles: string[], permission: string): boolean;
+    /** Resolve acting user + scope, refusing `none` with the (overridable) domain error. */
+    protected assertGrant(verb: PermissionVerb, user?: User): {
+        user: User;
+        scope: 'any' | 'own';
+    };
+    /**
+     * Runs `fn` as the given user, so rbac-scoped ORM queries inside answer "what does
+     * THIS user see" — ownership rules stay stated once, in the query layer. The store's
+     * own user runs in the ambient store untouched; any other user impersonates: User is
+     * swapped and ActiveRole cleared (it belongs to the ambient user only), everything
+     * else in the store kept.
+     */
+    protected withUser<T>(user: User, fn: () => T | Promise<T>): Promise<T>;
+    protected noPermissionError(user: User, verb: PermissionVerb): Error;
+    protected noUserError(): Error;
+    private storage;
+}
+/**
+ * Retrieves a permission service from DI — sugar for domain services and plain
+ * functions down the callstack, so code reads as intent
+ * (`usePermission(ContentEntriesPermission)`) instead of container plumbing.
+ * Answers the same DI-cached instance controllers receive via `@FromDI()`.
+ *
+ * Accepts ONLY PermissionService subclasses — the generic constraint is erased at
+ * runtime, so this is enforced here too instead of degrading into a bare DI.resolve.
+ */
+export declare function usePermission<T extends PermissionService>(type: Class<T>): T;
+/**
+ * THE guarded accesscontrol probe — single home for the AccessControlError semantics
+ * previously copy-pasted into the ORM query middleware and rbac-http's RbacPolicy.
+ * Answers the Permission object (grant attributes stay reachable), or null for a role
+ * unknown to accesscontrol — which throws AccessControlError for any role absent from
+ * the grants map and rejects the whole role array on one unknown member. A genuine
+ * programming error (bad permission name) still propagates loud.
+ */
+export declare function probeGrant(roles: string | string[], permission: string, resource: string): Permission | null;
+/**
+ * THE ActiveRole rule — single home for the narrowing previously inlined in the ORM
+ * query middleware and rbac-http's checkRoutePermission. The session's ActiveRole
+ * applies only to the user it was selected for — matched by id; any other user answers
+ * their full role list.
+ *
+ * The storage parameter is structural (not IRbacAsyncStorage) so both the rbac ALS
+ * store and http's request storage (whose User is `User | null`) fit.
+ */
+export declare function effectiveRoles(user: User, storage?: {
+    User?: User | null;
+    ActiveRole?: string;
+}): string[];
+//# sourceMappingURL=permission-service.d.ts.map

package/lib/mjs/permission-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-service.d.ts","sourceRoot":"","sources":["../../src/permission-service.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAM,MAAM,aAAa,CAAC;AAGxC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AACrE,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,8BAAsB,iBAAiB;IACrC,mFAAmF;IACnF,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE7C;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAWhC;IAED,8FAA8F;IAC9F,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAE7C;IAED,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAU3E;IAED,kFAAkF;IAClF,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE1D;IAED,wFAAwF;IACxF,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,CAS7F;IAED;;;;;;OAMG;IACH,UAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAS5E;IAED,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,GAAG,KAAK,CAEnE;IAED,SAAS,CAAC,WAAW,IAAI,KAAK,CAE7B;IAED,OAAO,CAAC,OAAO;CAGhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAc5G;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAK1G"}

package/lib/mjs/permission-service.js

@@ -0,0 +1,137 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { AccessControl } from 'accesscontrol';
+import { DI } from '@spinajs/di';
+import { Forbidden } from '@spinajs/exceptions';
+/**
+ * Base for per-domain permission services: decides and explains authorization at the
+ * domain layer, BEFORE any effect — the ORM rbac middleware stays the enforcement
+ * backstop. One concrete class per rbac resource; public API is domain-named assert
+ * methods built from the protected primitives below. The rbac User model is the actor —
+ * no wrapper objects.
+ *
+ * Stateless by contract: no instance fields in subclasses. Spinajs DI caches resolved
+ * instances, so `@FromDI()` injection in controllers, `@Autoinject` fields and
+ * `usePermission()` anywhere else share one instance safely.
+ */
+export class PermissionService {
+    /**
+     * The acting user: explicit argument wins, else the rbac AsyncLocalStorage store.
+     * No user anywhere throws — a permission decision must never silently pass without
+     * an identity.
+     */
+    user(user) {
+        if (user) {
+            return user;
+        }
+        const store = this.storage().getStore();
+        if (!store?.User) {
+            throw this.noUserError();
+        }
+        return store.User;
+    }
+    /** Roles the decision runs against — the shared ActiveRole rule against the ambient store. */
+    effectiveRoles(user) {
+        return effectiveRoles(user, this.storage().getStore());
+    }
+    grantScope(user, verb) {
+        const roles = this.effectiveRoles(user);
+        if (this.can(roles, `${verb}Any`)) {
+            return 'any';
+        }
+        if (this.can(roles, `${verb}Own`)) {
+            return 'own';
+        }
+        return 'none';
+    }
+    /** Single guarded probe against this.Resource — an unknown role answers false. */
+    can(roles, permission) {
+        return probeGrant(roles, permission, this.Resource)?.granted ?? false;
+    }
+    /** Resolve acting user + scope, refusing `none` with the (overridable) domain error. */
+    assertGrant(verb, user) {
+        const acting = this.user(user);
+        const scope = this.grantScope(acting, verb);
+        if (scope === 'none') {
+            throw this.noPermissionError(acting, verb);
+        }
+        return { user: acting, scope };
+    }
+    /**
+     * Runs `fn` as the given user, so rbac-scoped ORM queries inside answer "what does
+     * THIS user see" — ownership rules stay stated once, in the query layer. The store's
+     * own user runs in the ambient store untouched; any other user impersonates: User is
+     * swapped and ActiveRole cleared (it belongs to the ambient user only), everything
+     * else in the store kept.
+     */
+    async withUser(user, fn) {
+        const storage = this.storage();
+        const parent = storage.getStore() ?? {};
+        if (parent.User?.Id === user.Id) {
+            return fn();
+        }
+        return storage.run({ ...parent, User: user, ActiveRole: undefined }, async () => fn());
+    }
+    noPermissionError(user, verb) {
+        return new Forbidden(`user ${user.Id} has no ${verb} grant for resource ${this.Resource}`);
+    }
+    noUserError() {
+        return new Forbidden('no acting user: none was given and none is present in the execution context');
+    }
+    storage() {
+        return DI.resolve(AsyncLocalStorage);
+    }
+}
+/**
+ * Retrieves a permission service from DI — sugar for domain services and plain
+ * functions down the callstack, so code reads as intent
+ * (`usePermission(ContentEntriesPermission)`) instead of container plumbing.
+ * Answers the same DI-cached instance controllers receive via `@FromDI()`.
+ *
+ * Accepts ONLY PermissionService subclasses — the generic constraint is erased at
+ * runtime, so this is enforced here too instead of degrading into a bare DI.resolve.
+ */
+export function usePermission(type) {
+    if (typeof type !== 'function' || !(type.prototype instanceof PermissionService)) {
+        throw new Error(`usePermission accepts only PermissionService subclasses, got ${typeof type === 'function' ? type.name : typeof type}`);
+    }
+    return DI.resolve(type);
+}
+/**
+ * THE guarded accesscontrol probe — single home for the AccessControlError semantics
+ * previously copy-pasted into the ORM query middleware and rbac-http's RbacPolicy.
+ * Answers the Permission object (grant attributes stay reachable), or null for a role
+ * unknown to accesscontrol — which throws AccessControlError for any role absent from
+ * the grants map and rejects the whole role array on one unknown member. A genuine
+ * programming error (bad permission name) still propagates loud.
+ */
+export function probeGrant(roles, permission, resource) {
+    const ac = DI.get('AccessControl');
+    if (!ac) {
+        throw new Error('no AccessControl registered in DI — rbac is not bootstrapped');
+    }
+    try {
+        return ac.can(roles)[permission](resource);
+    }
+    catch (err) {
+        if (AccessControl.isAccessControlError(err)) {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * THE ActiveRole rule — single home for the narrowing previously inlined in the ORM
+ * query middleware and rbac-http's checkRoutePermission. The session's ActiveRole
+ * applies only to the user it was selected for — matched by id; any other user answers
+ * their full role list.
+ *
+ * The storage parameter is structural (not IRbacAsyncStorage) so both the rbac ALS
+ * store and http's request storage (whose User is `User | null`) fit.
+ */
+export function effectiveRoles(user, storage) {
+    if (storage?.ActiveRole && storage.User?.Id === user.Id) {
+        return [storage.ActiveRole];
+    }
+    return user.Role;
+}
+//# sourceMappingURL=permission-service.js.map

package/lib/mjs/permission-service.js.map

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