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.
Install
Section titled “Install”bun add vpermsYour first permission check
Section titled “Your first permission check”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"); // trueawait vperms.can(user, "POSTS.READ"); // true (case-insensitive)await vperms.can(user, "posts.write"); // falsePass your own domain objects
Section titled “Pass your own domain objects”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.
Packages
Section titled “Packages”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. |
Where to go next
Section titled “Where to go next”- 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.