@vperms/express

Middleware

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

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

interface PermissionsExportOptions {
  path: string;
}

function vpermsMiddleware(
  options: VpermsMiddlewareOptions,
): RequestHandler;

Hydrates req.ability, req.subject and req.kind on each request, serves the export endpoint when configured, and forwards errors with next(error).

Request augmentation

interface RequestAbility {
  can(permission: string): Promise<boolean>;
}

declare global {
  namespace Express {
    interface Request {
      ability: RequestAbility;
      subject?: Subject;
      kind?: SubjectType;
    }
  }
}

Guards

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

function hasPermission(...inputs: PermissionInput[]): RequestHandler; // ALL
function hasAnyPermission(...inputs: PermissionInput[]): RequestHandler; // ANY

Both respond 403 via res.sendStatus(403) when denied, and throw if vpermsMiddleware was not registered first.

Export

ANONYMOUS_SUBJECT_ID.