Subjects
A subject is anything that can be granted permissions: a user, a team, a
service account, a bot, or the anonymous visitor. The scoped VPerms API
persists them in the default root authorization domain unless another
workspace is selected.
Your application owns its subjects. vPerms only needs to know how to identify them.
The Subject type
Section titled “The Subject type”import type { Subject } from "vperms";
interface Subject { id: string; type: string; parents: string[];}idis the subject identifier. It must be a non-empty string and is unique within a workspace. IDs are opaque and case-sensitive: vPerms never lowercases or rewrites them.typeclassifies the subject. Type defaults can attach virtual parents to whole types.parentslists the ids this subject inherits permissions from. See Inheritance for how parents are resolved and how the!negation prefix works.
Subject types are extensible
Section titled “Subject types are extensible”SubjectType exposes the built-in identifiers as constants:
| Member | Value | Typical use |
|---|---|---|
User |
"user" |
Human accounts. |
Service |
"service" |
Machine-to-machine callers. |
Group |
"group" |
Roles and teams that hold grants. |
Anon |
"anon" |
The anonymous, unauthenticated user. |
The list is not closed. Any canonical lowercase identifier is a valid
subject type, so an application can define team, bot, service_account or
whatever its domain needs. Types are normalized to lowercase; invalid
identifiers are rejected.
import { SubjectType } from "vperms";
const group = { id: "developers", type: SubjectType.Group, parents: [],};Subject types are not roles. A type groups subjects that share default
parents; permissions are granted to individual subjects and inherited through
parents. A parent may reference a subject of any type.
SubjectResolver
Section titled “SubjectResolver”SubjectResolver is the interface an application domain class implements so
vPerms can identify it:
import type { SubjectResolver } from "vperms";
interface SubjectResolver<TType extends string = string> { getSubjectId(): string; getSubjectType(): TType;}class User implements SubjectResolver<"user"> { constructor( public id: string, public email: string, ) {}
getSubjectId() { return this.id; }
getSubjectType() { return "user" as const; }}
const user = new User("123", "john@example.com");
await vperms.can(user, "posts.read");vPerms resolves the object to { id: "123", type: "user" } internally and only
ever derives that identity. It never copies email, name or any other domain
state into persistence, and it does not create subjects automatically.
The type parameter preserves the literal type: SubjectResolver<"user"> keeps
"user" rather than widening it to string.
getSubjectType() is explicit on purpose. Application classes are free to use a
property such as user.type for unrelated domain semantics; vPerms does not
guess a type from constructor.name, a global registry, or a .type property.
Principal<TType> extends SubjectResolver<TType>. Every Principal is
resolvable as a subject, but implementing SubjectResolver does not imply
authentication — that distinction belongs to your application.
SubjectRef
Section titled “SubjectRef”SubjectRef is the minimal canonical representation vPerms works with:
import type { SubjectRef } from "vperms";
interface SubjectRef<TType extends string = string> { id: string; type: TType;}Explicit references keep working and are the right choice across serialization and process boundaries: HTTP payloads, workers, queues, JSON that lost its prototype, or integrations that do not own the domain class.
await vperms.can({ id: "123", type: "user" }, "posts.read");Resolution precedence
Section titled “Resolution precedence”Every identity method on the scoped VPerms facade passes its argument through
the same resolver, in this order:
- An explicit
SubjectRef(an object withidandtype). - A
SubjectResolver(an object withgetSubjectId()andgetSubjectType()). - Otherwise,
SubjectResolutionError.
If an object exposes both, the explicit id/type wins. Raw subject id strings
continue to address persisted records directly; they are not resolved into a
typed reference.
The anonymous subject
Section titled “The anonymous subject”When an integration’s subject resolver returns null or undefined, the
request is treated as anonymous. The reserved id is exported as
ANONYMOUS_SUBJECT_ID:
import { ANONYMOUS_SUBJECT_ID } from "vperms";
console.log(ANONYMOUS_SUBJECT_ID); // "anonymous"The anonymous subject is created on demand with SubjectType.Anon the first
time it is needed (for example, by resolveRequestContext), so it can receive
grants just like any other subject. See
Middleware and requests for the request context.
Workspaces
Section titled “Workspaces”Most applications only need root. Workspaces isolate complete applications,
not modules/features. For independent applications sharing an adapter, the same
subject ID in two workspaces represents two independent records:
await vperms.workspace("app-a").saveSubject({ id: "user", type: SubjectType.User, parents: [] });await vperms.workspace("app-b").saveSubject({ id: "user", type: SubjectType.User, parents: [] });Workspace and subject IDs are case-sensitive, non-empty strings. See Workspaces for scoping and the advanced raw API.
Validation
Section titled “Validation”Subjects are validated by SubjectSchema before they reach an adapter:
idis a non-empty string (SubjectIdSchema).typeis a canonical identifier, normalized to lowercase.parentsis an array of ids; the!prefix is allowed in stored parents (it is a negation directive), but not in default parents.
Invalid input throws a ZodError; unresolvable subject values throw a
SubjectResolutionError (see Errors).