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.
createVPerms and VPerms (recommended)
Section titled “createVPerms and VPerms (recommended)”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.
Re-exports
Section titled “Re-exports”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.
VeguiPermsService (advanced raw API)
Section titled “VeguiPermsService (advanced raw API)”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.
Schemas
Section titled “Schemas”const WorkspaceIdSchema; // non-empty stringconst SubjectIdSchema; // non-empty stringconst PermissionSchema; // validates non-empty segments, then lowercasesconst SubjectTypeSchema; // canonical lowercase subject typeconst SubjectSchema;const PermissionGrantSchema;const DefaultParentIdSchema; // rejects a leading "!"const DefaultParentsSchema;const ResolvedPermissionSchema;const ResolvedSubjectSchema;Each schema infers a Validated* type.
Request runtime
Section titled “Request runtime”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.
Export
Section titled “Export”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.
Errors
Section titled “Errors”PermissionDeniedError
Section titled “PermissionDeniedError”status = 403. Thrown when the caller may not read the requested permissions.
Holds .permission.
SubjectNotFoundError
Section titled “SubjectNotFoundError”status = 404. Thrown when the subject has no record. Holds .subjectId.
InvalidSubjectIdError
Section titled “InvalidSubjectIdError”status = 400. Thrown when a subject id fails validation. Holds .subjectId.
SubjectResolutionError
Section titled “SubjectResolutionError”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.