Skip to content

The VPerms API

VPerms is the recommended application-facing API exported by vperms. It binds a workspace once and delegates to VeguiPermsService, which owns validation, permission resolution, inheritance, cycle protection and evaluation; the adapter only persists data.

import {
createVPerms,
type SubjectResolver,
SubjectType,
VeguiPermsMemoryAdapter,
} from "vperms";
const vperms = createVPerms({
adapter: new VeguiPermsMemoryAdapter(),
defaultParents: { global: ["everyone"] },
});
interface VPermsOptions {
adapter: VeguiPermsAdapter;
workspaceId?: string; // defaults to DEFAULT_WORKSPACE_ID ("root")
defaultParents?: DefaultParents;
}

defaultParents is validated with DefaultParentsSchema when the service is constructed. See Inheritance.

Method Returns Description
can(subject, permission) Promise<boolean> Whether the subject may perform the permission.
resolvePermissions(subject) Promise<ResolvedSubject> Full effective permission snapshot.
saveSubject(subject) Promise<Subject> Create or update a subject.
deleteSubject(subject) Promise<boolean> Delete a subject; true when it existed.
setPermission(subject, permission, value) Promise<PermissionGrant> Upsert an allow/deny grant.
unsetPermission(subject, permission) Promise<boolean> Remove a grant; true when it existed.

Methods identifying a subject accept a raw subject id, an explicit SubjectRef, or a domain object implementing SubjectResolver; saveSubject accepts a full record. All public inputs are validated with Zod; invalid input throws a ZodError.

class User implements SubjectResolver<"user"> {
constructor(public id: string, public email: string) {}
getSubjectId() {
return this.id;
}
getSubjectType() {
return "user" as const;
}
}
await vperms.saveSubject({
id: "user",
type: SubjectType.User,
parents: ["developers"],
});
await vperms.saveSubject({ id: "developers", type: SubjectType.Group, parents: [] });
await vperms.setPermission("developers", "posts.read", true);
await vperms.can(new User("user", "user@example.com"), "POSTS.READ"); // true
await vperms.resolvePermissions("user");

can() returns false when the adapter has no record for the subject. resolvePermissions() throws SubjectNotFoundError in that case, because the snapshot needs a subject record. Direct grants short-circuit inheritance; then explicit, type-default and global-default layers are consulted in order.

Permissions are normalized to lowercase on writes and in resolved snapshots. Updating or removing a permission uses the same canonical path regardless of casing. See Permission normalization.

Most applications use root. vperms.workspace(id) creates a new immutable scope over the same service; it never changes the current instance. Use permission paths for application features, not workspaces. See Workspaces for isolated applications.

vperms.service is the readonly escape hatch to the existing low-level VeguiPermsService, whose operations take the workspace ID first:

await vperms.service.can(vperms.workspaceId, "user", "posts.read");

The runtime helpers are shared by all framework integrations. They hydrate a request-scoped context exactly once per request.

import {
createAbility,
resolveRequestContext,
resolveSubjectId,
} from "vperms";
const ability = createAbility(vperms.service, vperms.workspaceId, "user");
await ability.can("posts.read"); // memoized per permission

createAbility(service, workspaceId, subject) returns an Ability whose can(permission) memoizes the promise, so the same permission is never evaluated twice within a request.

resolveRequestContext performs the whole dance:

const context = await resolveRequestContext({
adapter,
service: vperms.service,
workspaceId: vperms.workspaceId,
subject: await getCurrentUser(), // SubjectInput | null
});
context.id; // resolved subject id ("anonymous" when subject was null)
context.subject; // Subject record, or undefined when not persisted
context.kind; // SubjectType, or undefined
context.ability; // Ability

When the resolver returns null/undefined, the anonymous subject is loaded — created on demand with SubjectType.Anon via ensureAnonymousSubject — so defaultParents.byType.anon applies automatically. ANONYMOUS_SUBJECT_ID is "anonymous".

The Ability interface is intentionally minimal:

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

Middleware, guards, decorators and permission-export handlers all reuse the same instance.