Skip to content

Permissions and patterns

Permissions are case-insensitive dot-separated segments, for example app.billing.read, app.billing.*, or posts.comments.delete. Segments may contain any character except ., and a permission cannot have empty segments:

^[^.]+(?:\.[^.]+)*$ // PermissionSchema

Granted permissions act as patterns: a granted permission implies a requested one when every segment matches. A segment is a match when it is equal, or when the granted segment is * (matches any single segment). A trailing * matches any number of remaining segments, including none.

Granted Requested Allowed
workspaces.1.read workspaces.1.read yes
workspaces.1.* workspaces.1.read yes
workspaces.*.read workspaces.7.read yes
workspaces.* workspaces.7.create yes
workspaces.1.* workspaces.2.read no
workspaces.1 workspaces.1.read no

Permission paths use locale-independent String.toLowerCase() normalization. Posts.Read, POSTS.READ and posts.read are the same permission. The service validates and stores lowercase paths; resolved snapshots also contain lowercase paths. Core matching and client-side evaluation normalize both sides, so older mixed-case grants and snapshots work too. Whitespace is not trimmed, and * keeps its existing wildcard meaning.

await vperms.setPermission("user", "Posts.Read", true);
await vperms.can("user", "POSTS.READ"); // true
await vperms.unsetPermission("user", "posts.READ"); // removes posts.read

Existing case variants are deduplicated during resolution using the usual precedence (including deny winning equal-priority ties). A service update removes legacy case variants before writing the canonical grant; removal deletes all case variants. Direct adapter writes are raw persistence operations; use VPerms for normalized writes, or normalize paths yourself with normalizePermission(permission) from vperms or @vperms/core.

Subject IDs and workspace IDs are not normalized. However, any identifier embedded inside a permission path follows the path’s case-insensitive semantics, including vperms.subject.<subjectId>.permissions.

The matcher is exported from @vperms/core:

import { matchesPattern } from "@vperms/core";
matchesPattern("workspaces.1.*", "workspaces.1.read"); // true
matchesPattern("workspaces.*.read", "workspaces.7.read"); // true
matchesPattern("workspaces.1.*", "workspaces.2.read"); // false

matchesPattern(grantPattern, permission) is a pure, synchronous segment comparison. It performs no inheritance and knows nothing about grants or denies.

When several grants match the same requested permission, the engine must decide which one wins. It scores each pattern with permissionSpecificity:

  • an exact segment adds 2,
  • an inner * adds 1,
  • a trailing * adds 0.
import { permissionSpecificity } from "@vperms/core";
permissionSpecificity("workspaces.1.read"); // 6
permissionSpecificity("workspaces.*.read"); // 5
permissionSpecificity("workspaces.1.*"); // 4
permissionSpecificity("workspaces.*"); // 2

More specific patterns win over broader wildcards. See Resolution for the full precedence order and how specificity combines with inheritance depth and source layer.

matchPermission(grants, permission) returns the value of the best matching grant, or null when nothing matches:

import { matchPermission } from "@vperms/core";
const grants = [
{ workspaceId: "root", subjectId: "user", permission: "workspaces.*", value: true },
{ workspaceId: "root", subjectId: "user", permission: "workspaces.1.*", value: false },
];
matchPermission(grants, "workspaces.1.read"); // false (more specific deny)
matchPermission(grants, "workspaces.2.read"); // true
matchPermission(grants, "posts.read"); // null

Grants are sorted with compareGrants first, so the result does not depend on the order of the array.

VeguiPerms reserves a small permission namespace for reading resolved permissions:

  • vperms.subject.me.permissions — always granted to every subject (at the lowest priority, so a deny can override it). Lets a subject read its own resolved permission set.
  • vperms.subject.<subjectId>.permissions — permission to read another subject’s resolved set. Normal wildcards apply, e.g. vperms.subject.*.permissions.
import { subjectPermissionsPermission } from "vperms";
subjectPermissionsPermission("user"); // "vperms.subject.user.permissions"

See Exporting resolved permissions.