Skip to content

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.

import type { Subject } from "vperms";
interface Subject {
id: string;
type: string;
parents: string[];
}
  • id is 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.
  • type classifies the subject. Type defaults can attach virtual parents to whole types.
  • parents lists the ids this subject inherits permissions from. See Inheritance for how parents are resolved and how the ! negation prefix works.

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 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 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");

Every identity method on the scoped VPerms facade passes its argument through the same resolver, in this order:

  1. An explicit SubjectRef (an object with id and type).
  2. A SubjectResolver (an object with getSubjectId() and getSubjectType()).
  3. 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.

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.

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.

Subjects are validated by SubjectSchema before they reach an adapter:

  • id is a non-empty string (SubjectIdSchema).
  • type is a canonical identifier, normalized to lowercase.
  • parents is 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).