Getting Started

vperms (VeguiPerms) is an open-source authorization library based on hierarchical, dot-separated permissions such as workspaces.create, workspaces.1.read, or workspaces.1.*.

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

bun add vperms

Your first permission check

import {
  SubjectType,
  VeguiPermsMemoryAdapter,
  VeguiPermsService,
} from "vperms";

const vperms = new VeguiPermsService({
  adapter: new VeguiPermsMemoryAdapter(),
});

await vperms.saveSubject("workspace", {
  id: "user",
  type: SubjectType.User,
  parents: ["developers"],
});
await vperms.saveSubject("workspace", {
  id: "developers",
  type: SubjectType.Group,
  parents: [],
});
await vperms.setPermission("workspace", "developers", "workspaces.1.*", true);

await vperms.can("workspace", "user", "workspaces.1.read"); // true (inherited)
await vperms.can("workspace", "user", "workspaces.2.read"); // false

Packages

VeguiPerms is a monorepo. Install only what you need:

Package	Description
vperms	Application-facing service, 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

• Concepts — subjects, permissions, grants, inheritance and resolution.
• Guides — the core engine, the service, 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.

Requirements

• Bun 1.x to build and test the repository.
• Node.js 18+ is supported at runtime; the package is published as runtime-neutral ESM.