vona-module-a-rbac 5.0.1

package/src/bean/event.policyInvalidated.ts

@@ -0,0 +1,17 @@
+import { BeanEventBase, Event } from 'vona-module-a-event';
+
+export type TypeRbacPolicyInvalidationKind = 'policy' | 'role' | 'scopeTopology';
+
+export interface TypeEventPolicyInvalidatedData {
+  kind: TypeRbacPolicyInvalidationKind;
+  removedRoleIds?: string[];
+  removedScopeIds?: string[];
+}
+
+export type TypeEventPolicyInvalidatedResult = void;
+
+@Event()
+export class EventPolicyInvalidated extends BeanEventBase<
+  TypeEventPolicyInvalidatedData,
+  TypeEventPolicyInvalidatedResult
+> {}

package/src/bean/event.resolvePolicy.ts

@@ -0,0 +1,13 @@
+import { BeanEventBase, Event } from 'vona-module-a-event';
+
+import type { IRbacPolicyDecision, IRbacPolicyRequest } from '../types/rbac.ts';
+
+export type TypeEventResolvePolicyData = IRbacPolicyRequest;
+
+export type TypeEventResolvePolicyResult = IRbacPolicyDecision | undefined;
+
+@Event()
+export class EventResolvePolicy extends BeanEventBase<
+  TypeEventResolvePolicyData,
+  TypeEventResolvePolicyResult
+> {}

package/src/bean/guard.rbac.ts

@@ -0,0 +1,102 @@
+import type { IDecoratorGuardOptions } from 'vona-module-a-aspect';
+
+import { Guard, GuardBase } from 'vona-module-a-aspect';
+
+import type {
+  IRbacActionDescriptor,
+  IRbacPolicyDecision,
+  IRbacScopeTerm,
+  TypeRbacDataScope,
+} from '../types/rbac.ts';
+
+import { clearRbacDecision, createRbacAllScopeDecision, setRbacDecision } from '../lib/rbac.ts';
+
+export interface IGuardOptionsRbac extends IDecoratorGuardOptions {
+  dataScope?: boolean;
+  dataScopeField?: string;
+  dataScopeMineField?: string;
+  actionInherit?: string;
+}
+
+@Guard<IGuardOptionsRbac>({
+  dataScopeField: 'departmentId',
+  dataScopeMineField: 'userIdOwner',
+})
+export class GuardRbac extends GuardBase {
+  async check(options: IGuardOptionsRbac): Promise<boolean> {
+    clearRbacDecision(this.ctx);
+    const action = this.bean.rbacCatalog.getAction(this.ctx.route);
+    if (!action) return false;
+    const effectiveAction = { ...action, options: { ...action.options, ...options } };
+    if (await this.bean.rbacScope.isUnrestricted()) {
+      setRbacDecision(this.ctx, createRbacAllScopeDecision(effectiveAction));
+      return true;
+    }
+
+    const decision = await this.scope.event.resolvePolicy.emit(
+      {
+        action: effectiveAction,
+        policyActionKey: action.actionInheritKey ?? action.actionKey,
+      },
+      async () => undefined,
+    );
+    if (!this.isValidDecision(decision, effectiveAction) || !decision.allowed) return false;
+    setRbacDecision(this.ctx, { ...decision, action: effectiveAction });
+    return true;
+  }
+
+  private isValidDecision(
+    decision: unknown,
+    action: IRbacActionDescriptor,
+  ): decision is IRbacPolicyDecision {
+    if (!decision || typeof decision !== 'object') return false;
+    const value = decision as Partial<IRbacPolicyDecision>;
+    if (typeof value.allowed !== 'boolean' || value.actionKey !== action.actionKey) return false;
+    if (!this.isValidAction(value.action, action)) return false;
+    if (value.revision !== undefined && typeof value.revision !== 'string') return false;
+    if (value.terms !== undefined && !this.isValidTerms(value.terms)) return false;
+    return !value.allowed || !action.options.dataScope || this.isValidTerms(value.terms);
+  }
+
+  private isValidAction(value: unknown, action: IRbacActionDescriptor): boolean {
+    if (!value || typeof value !== 'object') return false;
+    const descriptor = value as Partial<IRbacActionDescriptor>;
+    return (
+      descriptor.actionKey === action.actionKey &&
+      descriptor.actionInheritKey === action.actionInheritKey &&
+      descriptor.controllerBeanFullName === action.controllerBeanFullName &&
+      descriptor.action === action.action
+    );
+  }
+
+  private isValidTerms(value: unknown): value is IRbacScopeTerm[] {
+    return Array.isArray(value) && value.length > 0 && value.every(term => this.isValidTerm(term));
+  }
+
+  private isValidTerm(value: unknown): value is IRbacScopeTerm {
+    if (!value || typeof value !== 'object') return false;
+    const term = value as {
+      dataScope?: unknown;
+      departmentIds?: unknown;
+      ownerId?: unknown;
+    };
+    if (term.dataScope === 'all') return true;
+    if (term.dataScope === 'mine') {
+      return typeof term.ownerId === 'string' && term.ownerId.length > 0;
+    }
+    if (!this.isDepartmentDataScope(term.dataScope)) return false;
+    return (
+      Array.isArray(term.departmentIds) &&
+      term.departmentIds.length > 0 &&
+      term.departmentIds.every(id => typeof id === 'string' && id.length > 0)
+    );
+  }
+
+  private isDepartmentDataScope(
+    value: unknown,
+  ): value is Exclude<TypeRbacDataScope, 'all' | 'mine'> {
+    return ['customDepartments', 'ownDepartment', 'ownDepartmentAndDescendants'].includes(
+      value as Exclude<TypeRbacDataScope, 'all' | 'mine'>,
+    );
+  }
+}

package/src/bean/index.ts

@@ -0,0 +1,5 @@
+export * from './bean.rbacCatalog.ts';
+export * from './bean.rbacScope.ts';
+export * from './event.policyInvalidated.ts';
+export * from './event.resolvePolicy.ts';
+export * from './guard.rbac.ts';

package/src/config/config.ts

@@ -0,0 +1,10 @@
+import type { VonaApplication } from 'vona';
+import type { IServiceRecord } from 'vona-module-a-bean';
+
+export function config(_app: VonaApplication) {
+  return {
+    adapter: {
+      rbacScope: 'admin-rbac:rbacScopeAdapter' as keyof IServiceRecord,
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/index.ts';
+export * from './types/index.ts';
+export * from './.metadata/index.ts';

package/src/lib/index.ts

@@ -0,0 +1 @@
+export * from './rbac.ts';

package/src/lib/rbac.ts

@@ -0,0 +1,46 @@
+import type { VonaContext } from 'vona';
+
+import type { IRbacCapability, IRbacPolicyDecision } from '../types/rbac.ts';
+
+export const SymbolRbacDecision = Symbol('SymbolRbacDecision');
+
+export function createRbacAllScopeDecision(
+  action: IRbacPolicyDecision['action'],
+): IRbacPolicyDecision {
+  return { allowed: true, actionKey: action.actionKey, action, terms: [{ dataScope: 'all' }] };
+}
+
+export function createRbacCapability(key: string, allowed: boolean): IRbacCapability {
+  return { key, allowed };
+}
+
+export function isRbacCapability(value: unknown): value is IRbacCapability {
+  if (!value || typeof value !== 'object') return false;
+  const capability = value as Partial<IRbacCapability>;
+  return (
+    Object.keys(capability).every(key => key === 'key' || key === 'allowed') &&
+    typeof capability.key === 'string' &&
+    capability.key.length > 0 &&
+    typeof capability.allowed === 'boolean'
+  );
+}
+
+export function hasRbacAllScope(decision: IRbacPolicyDecision): boolean {
+  return decision.terms?.some(term => term.dataScope === 'all') === true;
+}
+
+export function rbacActionKey(controllerBeanFullName: string, action: string): string {
+  return `${controllerBeanFullName}#${action}`;
+}
+
+export function getRbacDecision(ctx: VonaContext): IRbacPolicyDecision | undefined {
+  return ctx[SymbolRbacDecision];
+}
+
+export function setRbacDecision(ctx: VonaContext, decision: IRbacPolicyDecision): void {
+  ctx[SymbolRbacDecision] = decision;
+}
+
+export function clearRbacDecision(ctx: VonaContext): void {
+  delete ctx[SymbolRbacDecision];
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './rbac.ts';
+export * from './scope.ts';

package/src/types/rbac.ts

@@ -0,0 +1,46 @@
+import type { ContextRoute } from 'vona-module-a-web';
+
+import type { IGuardOptionsRbac } from '../bean/guard.rbac.ts';
+
+export type TypeRbacDataScope =
+  | 'all'
+  | 'customDepartments'
+  | 'ownDepartment'
+  | 'ownDepartmentAndDescendants'
+  | 'mine';
+
+export interface IRbacActionDescriptor {
+  actionKey: string;
+  controllerBeanFullName: string;
+  action: string;
+  actionInheritKey?: string;
+  route: ContextRoute;
+  options: IGuardOptionsRbac;
+}
+
+export interface IRbacPolicyRequest {
+  action: IRbacActionDescriptor;
+  policyActionKey: string;
+}
+
+export type IRbacScopeTerm =
+  | { dataScope: 'all' }
+  | {
+      dataScope: 'customDepartments' | 'ownDepartment' | 'ownDepartmentAndDescendants';
+      departmentIds: string[];
+    }
+  | { dataScope: 'mine'; ownerId: string };
+
+export interface IRbacPolicyDecision {
+  allowed: boolean;
+  actionKey: string;
+  action: IRbacActionDescriptor;
+  terms?: IRbacScopeTerm[];
+  revision?: string;
+}
+
+/** A server-derived UX hint; it never grants backend authority. */
+export interface IRbacCapability {
+  key: string;
+  allowed: boolean;
+}

package/src/types/scope.ts

@@ -0,0 +1,27 @@
+import type { TableIdentity } from 'table-identity';
+import type { IOpenapiPermissionActionRbac } from 'vona-module-a-openapi';
+import type { TypeModelWhere } from 'vona-module-a-orm';
+
+import type { IRbacActionDescriptor, IRbacPolicyDecision } from './rbac.ts';
+
+export type IRbacScopeOwnerValues = Record<string, TableIdentity | null | undefined>;
+
+export interface IRbacScopeAdapter {
+  isUnrestricted(): Promise<boolean>;
+  ownerValues(
+    action: IRbacActionDescriptor,
+    decision: IRbacPolicyDecision,
+  ): Promise<IRbacScopeOwnerValues>;
+}
+
+export interface IRbacScopeAccess {
+  action: IRbacActionDescriptor;
+  decision: IRbacPolicyDecision;
+  unrestricted: boolean;
+  ownerValues(): Record<string, TableIdentity | null | undefined>;
+  where(callerWhere?: TypeModelWhere<any>): TypeModelWhere<any> | undefined;
+  checkEntry(entry: object | undefined): void;
+  checkEntries(entries: readonly object[]): void;
+  /** A safe permission projection for Resource permission consumers. */
+  permissionProjection(): IOpenapiPermissionActionRbac;
+}