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:
^[^.]+(?:\.[^.]+)*$ // PermissionSchemaGranted 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 |
Normalization
Section titled “Normalization”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"); // trueawait vperms.unsetPermission("user", "posts.READ"); // removes posts.readExisting 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.
matchesPattern
Section titled “matchesPattern”The matcher is exported from @vperms/core:
import { matchesPattern } from "@vperms/core";
matchesPattern("workspaces.1.*", "workspaces.1.read"); // truematchesPattern("workspaces.*.read", "workspaces.7.read"); // truematchesPattern("workspaces.1.*", "workspaces.2.read"); // falsematchesPattern(grantPattern, permission) is a pure, synchronous segment
comparison. It performs no inheritance and knows nothing about grants or
denies.
Specificity
Section titled “Specificity”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"); // 6permissionSpecificity("workspaces.*.read"); // 5permissionSpecificity("workspaces.1.*"); // 4permissionSpecificity("workspaces.*"); // 2More specific patterns win over broader wildcards. See Resolution for the full precedence order and how specificity combines with inheritance depth and source layer.
Matching a permission against grants
Section titled “Matching a permission against grants”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"); // truematchPermission(grants, "posts.read"); // nullGrants are sorted with compareGrants first, so the result does not depend on
the order of the array.
Reserved permissions
Section titled “Reserved permissions”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"