Skip to content

Getting Started

vperms (VeguiPerms) is an open-source authorization library based on hierarchical, case-insensitive permissions such as app.billing.read, app.billing.write, or app.billing.*.

Permissions are stored as grants (allow or deny), attached to subjects (users, services, groups). Subjects inherit grants from their parents, and virtual default parents can apply to every subject automatically. The engine resolves the whole effective permission set with a deterministic precedence, so evaluation is consistent on the server and in the browser.

Terminal window
bun add vperms
import {
SubjectType,
VeguiPermsMemoryAdapter,
createVPerms,
} from "vperms";
const adapter = new VeguiPermsMemoryAdapter();
const vperms = createVPerms({ adapter });
const user = "user";
await vperms.saveSubject({
id: user,
type: SubjectType.User,
parents: [],
});
await vperms.setPermission(user, "posts.read", true);
await vperms.can(user, "posts.read"); // true
await vperms.can(user, "POSTS.READ"); // true (case-insensitive)
await vperms.can(user, "posts.write"); // false

Your application owns its subjects. Implement SubjectResolver on a domain class and vPerms can identify it directly:

import type { SubjectResolver } from "vperms";
class User implements SubjectResolver<"user"> {
constructor(
public id: string,
public email: string,
) {}
getSubjectId() {
return this.id;
}
getSubjectType() {
return "user" as const;
}
}
const user = new User("123", "john@example.com");
await vperms.can(user, "posts.read");

vPerms only derives { id: "123", type: "user" }; it never persists the rest of the object. See Subjects for SubjectRef, custom subject types and resolution precedence.

VeguiPerms is a monorepo. Install only what you need:

Package Description
vperms Scoped VPerms API, validation and public types.
@vperms/core Pure permission engine (matching, inheritance, resolution).
@vperms/client Framework-independent resolved-permission client.
@vperms/react React and React Server Component bindings.
@vperms/express Express middleware and route guards.
@vperms/hono Hono middleware and route guards.
@vperms/nest NestJS module, guard, decorators.
@vperms/next Next.js integration (Server Components, Route Handlers, RSC).
@vperms/sql-adapter Dialect-agnostic SQL base adapter.
@vperms/drizzle-adapter SQLite, MySQL and Postgres adapters via Drizzle ORM.
@vperms/mongodb-adapter MongoDB adapter.
  • Concepts — subjects, permissions, grants, inheritance and resolution.
  • VPerms guide — the scoped API, the core engine, exporting resolved permissions and writing a custom adapter.
  • Adapters — persistence backends.
  • Integrations — HTTP frameworks and the browser client.
  • API Reference — the exported surface of every package.
  • Bun 1.x to build and test the repository.
  • Node.js 18+ is supported at runtime; the package is published as runtime-neutral ESM.