Skip to content

vperms

vperms is the main package. It re-exports the core engine and adds the workspace-scoped facade, validated raw service, request runtime and export helpers.

const DEFAULT_WORKSPACE_ID = "root";
interface VPermsOptions extends VeguiPermsServiceOptions {
workspaceId?: string;
}
function createVPerms(options: VPermsOptions): VPerms;
class VPerms {
constructor(service: VeguiPermsService, workspaceId?: string);
readonly workspaceId: string;
readonly service: VeguiPermsService;
workspace(workspaceId: string): VPerms;
can(subject: SubjectInput, permission: string): Promise<boolean>;
resolvePermissions(subject: SubjectInput): Promise<ResolvedSubject>;
saveSubject(subject: Subject): Promise<Subject>;
deleteSubject(subject: SubjectInput): Promise<boolean>;
setPermission(subject: SubjectInput, permission: string, value: boolean): Promise<PermissionGrant>;
unsetPermission(subject: SubjectInput, permission: string): Promise<boolean>;
}

createVPerms({ adapter, defaultParents?, workspaceId? }) creates a service and an immutable facade, defaulting to root. Each operation delegates directly to service.method(workspaceId, ...). workspace(id) returns a new independent scope over the same service. Workspace IDs are validated as non-empty strings. See Workspaces.

SubjectInput is SubjectId | SubjectRef | SubjectResolver. Every identity method resolves its argument through the shared resolveSubject path, so you can pass a raw id, an explicit { id, type } reference, or a domain object that implements SubjectResolver. See Subjects.

The factories exported by @vperms/client and @vperms/react also use the name createVPerms; those are HTTP/snapshot clients, not this server-side facade.

Values: VeguiPermsAdapter, VeguiPermsMemoryAdapter, SubjectType, SELF_PERMISSIONS_PERMISSION, subjectPermissionsPermission, canResolved, resolveSubjectPermissions, BUILTIN_PERMISSION_LAYER, normalizePermission, resolveSubject, resolveSubjectId, isSubjectRef, isSubjectResolver, normalizeSubjectType, SUBJECT_TYPE_PATTERN.

Types: Subject, SubjectId, SubjectType, SubjectRef, SubjectResolver, SubjectInput, Principal, DefaultParents, PermissionGrant, ResolvedPermission, ResolvedPermissionGrant, ResolvedSubject.

Errors: SubjectNotFoundError, PermissionDeniedError, InvalidSubjectIdError, SubjectResolutionError.

Available directly or through vperms.service. Existing explicit-workspace callers and framework integrations retain this API.

interface VeguiPermsServiceOptions {
adapter: VeguiPermsAdapter;
defaultParents?: DefaultParents;
}
class VeguiPermsService {
constructor(options: VeguiPermsServiceOptions);
can(
workspaceId: string,
subject: SubjectInput,
permission: string,
): Promise<boolean>;
resolvePermissions(
workspaceId: string,
subject: SubjectInput,
): Promise<ResolvedSubject>;
saveSubject(workspaceId: string, subject: Subject): Promise<Subject>;
deleteSubject(workspaceId: string, subject: SubjectInput): Promise<boolean>;
setPermission(
workspaceId: string,
subject: SubjectInput,
permission: string,
value: boolean,
): Promise<PermissionGrant>;
unsetPermission(
workspaceId: string,
subject: SubjectInput,
permission: string,
): Promise<boolean>;
}

can returns false when the subject has no record. It checks direct grants first, then inherited grants, and finally matches SELF_PERMISSIONS_PERMISSION. resolvePermissions throws SubjectNotFoundError when the subject has no record. Every input is validated with Zod; a subject value is normalized with resolveSubjectId.

const WorkspaceIdSchema; // non-empty string
const SubjectIdSchema; // non-empty string
const PermissionSchema; // validates non-empty segments, then lowercases
const SubjectTypeSchema; // canonical lowercase subject type
const SubjectSchema;
const PermissionGrantSchema;
const DefaultParentIdSchema; // rejects a leading "!"
const DefaultParentsSchema;
const ResolvedPermissionSchema;
const ResolvedSubjectSchema;

Each schema infers a Validated* type.

interface Ability {
can(permission: string): Promise<boolean>;
}
const ANONYMOUS_SUBJECT_ID = "anonymous";
function resolveSubjectId(subject: SubjectInput): SubjectId;
function createAbility(
service: VeguiPermsService,
workspaceId: string,
subject: SubjectInput,
): Ability;
function ensureAnonymousSubject(
adapter: VeguiPermsAdapter,
service: VeguiPermsService,
workspaceId: string,
): Promise<Subject>;
interface RequestContextInput {
adapter: VeguiPermsAdapter;
service: VeguiPermsService;
workspaceId: string;
subject: SubjectInput | null | undefined;
}
interface RequestContext {
id: SubjectId;
subject: Subject | undefined;
kind: SubjectType | undefined;
ability: Ability;
}
function resolveRequestContext(
input: RequestContextInput,
): Promise<RequestContext>;

createAbility memoizes can() per permission. resolveRequestContext creates the anonymous subject on demand when subject is null or undefined, otherwise resolves the identity and loads the subject record.

function parsePermissionsExportPath(path: string): PermissionsExportPath;
interface PermissionsExportPath {
path: string;
base: string;
routePattern: string;
param: string;
match(pathname: string): PermissionsExportMatch | null;
}
function exportResolvedSubject(
input: ExportResolvedSubjectInput,
): Promise<ResolvedSubject>;

exportResolvedSubject authorizes the caller before returning anything: self requests require SELF_PERMISSIONS_PERMISSION, other targets require subjectPermissionsPermission(target). It then loads the subject and resolves its permissions. Throws PermissionDeniedError, SubjectNotFoundError or InvalidSubjectIdError.

status = 403. Thrown when the caller may not read the requested permissions. Holds .permission.

status = 404. Thrown when the subject has no record. Holds .subjectId.

status = 400. Thrown when a subject id fails validation. Holds .subjectId.

Thrown when a value cannot be resolved into a subject: it is neither a SubjectRef nor a SubjectResolver, or the resolver methods return invalid values. The message never includes the offending value’s contents.

See Errors for the full reference.