@vperms/nest

Module

interface VPermsModuleOptions {
  adapter: VeguiPermsAdapter;
  resolver: SubjectResolver;
  workspace: string;
  defaultParents?: DefaultParents;
  permissionsExport?: PermissionsExportOptions;
}

interface PermissionsExportOptions {
  path: string;
}

type SubjectResolverResult = SubjectId | Principal | null;
type SubjectResolver =
  (req: Request) => SubjectResolverResult | Promise<SubjectResolverResult>;

class VPermsModule {
  static forRoot(options: VPermsModuleOptions): DynamicModule;
}

Global module. Registers the service and VPermsGuard (as APP_GUARD) and, when permissionsExport is set, a controller that serves the export endpoint.

Tokens

VPERMS_OPTIONS, VPERMS_SERVICE.

Decorators

function Permission(...inputs: PermissionInput[]): MethodDecorator & ClassDecorator;
function AnyPermission(...inputs: PermissionInput[]): MethodDecorator & ClassDecorator;

function Ability(): ParameterDecorator;
function Subject(): ParameterDecorator;
function Kind(): ParameterDecorator;

const PERMISSION_METADATA: symbol;
const ANY_PERMISSION_METADATA: symbol;

type PermissionBuilder = (
  req: Request,
) => string | Promise<string>;
type PermissionInput = string | PermissionBuilder;

Permission/AnyPermission only attach metadata. Ability/Subject/Kind read the hydrated request context; Ability throws when it is absent.

Guards

class VPermsGuard implements CanActivate {}
abstract class AbilityGuard implements CanActivate {
  protected abstract check(
    ability: Ability,
    context: ExecutionContext,
  ): boolean | Promise<boolean>;
  protected getAbility(...): Ability;
  protected getSubject(...): Subject | undefined;
  protected getKind(...): SubjectType | undefined;
}

VPermsGuard hydrates once per request and evaluates @Permission / @AnyPermission metadata. Routes without metadata are untouched.

Request

interface VpermsRequest extends Request {
  ability: Ability;
  subject?: Subject;
  kind?: SubjectType;
}

VPERMS_STATE is the symbol used to store the hydrated RequestContext on the request.