vperms
v0.0.6
Published
VeguiPerms — hierarchical permissions for TypeScript.
Maintainers
Readme
VeguiPerms
Permission to build. vperms is the application-facing VeguiPerms package:
validated authorization, hierarchical permissions, inheritance and portable
resolved snapshots. Written in TypeScript, with ESM support for Bun and Node.js.
Documentation · Service guide · API reference · GitHub
Install
npm install vperms
# or: bun add vpermsQuick start
import { createVPerms, SubjectType, VeguiPermsMemoryAdapter } from "vperms";
const perms = createVPerms({ adapter: new VeguiPermsMemoryAdapter() });
await perms.saveSubject({
id: "developers",
type: SubjectType.Group,
parents: [],
});
await perms.saveSubject({
id: "alice",
type: SubjectType.User,
parents: ["developers"],
});
await perms.setPermission("developers", "projects.1.*", true);
await perms.can("alice", "PROJECTS.1.READ"); // true (case-insensitive)
await perms.can("alice", "projects.2.read"); // falseWorkspaces and advanced access
Most apps only need the default root (DEFAULT_WORKSPACE_ID). Organize features
with billing.*, users.* and admin.*, not separate workspaces. Workspaces
isolate complete applications sharing an adapter:
const appA = perms.workspace("app-a");
const appB = perms.workspace("app-b");
appA.service === appB.service; // true
perms.workspaceId; // "root", unchanged
await perms.service.can(perms.workspaceId, "alice", "projects.1.read");Scopes are immutable; workspaceId and service are readonly. An initial scope
can be selected with createVPerms({ adapter, workspaceId: "my-app" }).
VeguiPermsService remains the low-level API with explicit workspace arguments.
See Workspaces.
What you get
- Case-insensitive, lowercase-normalized permissions, wildcards, explicit allows and denies.
- Workspace isolation, group inheritance, virtual parents and cycle protection.
- Zod-validated inputs and first-class domain-object subjects via
SubjectResolver. resolvePermissions()to export JSON-safe snapshots for client-side UX.- An in-memory adapter, plus SQL and MongoDB adapters.
Add the integration for your stack to authorize requests or render permission-aware interfaces.
Build and coverage badges describe the whole VeguiPerms repository. License: MIT.
