Tenants, teams and scoped roles

A role in a real SaaS application is rarely global. Alice is an admin of Acme and a viewer of Globex; a portal contact sees only their own customer's invoices; the design team edits everything in the design folder; Bob shared one document with Carol; Acme's admin invented a "Billing Manager" role nobody coded. PermDock models all four with one addition to the subject: a list of memberships, each naming a scope and the roles held there. Roles declared with role() say where they apply; grants stay exactly as they are; the tenant condition you used to repeat on every grant becomes part of the role. Authentication, tenant objects, invitations and membership storage stay with your auth provider; PermDock reads the result. Why this model compares it with authorization engines and auth providers.

MembershipsCopy Anchor Link

type Membership = {
  scope?: string; // a declared scope name: 'organization', 'customer'
  id?: string; // the instance of that scope
  within?: Record<string, string>; // the id of every ancestor scope: { organization: 'o_acme' }
  on?: { resource: string; id: string }; // a resource-scoped role: "editor on document d_123"
  roles: string[]; // declared role names, or tenant-defined custom role names
  via?: string; // the membership kind: 'staff', 'contact', 'group:<scim id>'; a role's `for` lists the kinds that hold it
  expiresAt?: number; // Unix seconds; time-bound access
  x?: AppData; // the application's own data: a department, a seat label
};

type Principal = {
  id: string;
  kind?: "user" | "service" | "workload";
  roles?: string[]; // global roles, unchanged
  memberships?: Membership[];
  tenant?: string; // the active tenant for this request
  issuer?: string; // `iss`; identity is issuer + id
  assurance?: { acr?: string; amr?: string[]; authTime?: number };
  binding?: Binding; // RFC 7800 `cnf` members
  [k: string]: unknown;
};

• roles on the principal keeps meaning global roles, so every existing sample and every single-tenant app is unchanged.
• A membership names one instance of a named scope (scope, id, and the ancestors' ids in within) or one resource (on). The { tenant } and { tenant, team } input shapes still work: they are the first and second declared scope and are normalised when the subject is resolved. A malformed entry is dropped (fail-closed, reported by permdock doctor PD025).
• tenant on the principal is the active tenant, an instance of the first scope: the one this request is about, taken from the URL, a header the server resolved, or the provider's active organisation. A value with no matching membership makes tenant-scoped roles contribute nothing. There is never a default tenant; an absent value means "no tenant", and tenant-scoped grants do not match (threat model).
• Memberships come only from verified material: a subjectFrom* provider, the policy's subject or context function, or a MembershipSource. Never from a model argument, an unsigned header, a request body or a CLI flag. This is invariant 13 extended to memberships.
• x is data the application owns about a membership. It is plain JSON from the same trusted sources, checked by definePolicy(…, { x: { membership } }). An invalid x is dropped with an on('auth') event of reason schema, and the membership stays. Conditions, RLS and role listings never read it, and the Supabase token hook never writes it into claims, so it costs nothing against the claim size budget. It reaches the client in the snapshot's principal.memberships and through permdock.memberships(). The Supabase sources read it from a jsonb column: fromTable({ columns: { x: 'meta' } }) or fromJunction({ x: 'meta' }).
• Identifiers, never display names. A team id is the provider's or SCIM group id; a display name is editable by any group owner and not unique across tenants (JWT authorization claims).

// what a provider produces for Alice
{
  id: 'u_alice',
  roles: [],                                             // no global roles
  tenant: 'o_acme',                                      // active for this request
  memberships: [
    { scope: 'tenant', id: 'o_acme',   roles: ['admin'] },
    { scope: 'tenant', id: 'o_globex', roles: ['viewer'] },
    { scope: 'team', id: 't_design', within: { tenant: 'o_acme' }, roles: ['lead'], via: 'group:9f2c' },
    { on: { resource: 'document', id: 'd_123' }, roles: ['editor'], expiresAt: 1789000000 },
  ],
}

Scoped role declarationsCopy Anchor Link

role() gains a third argument that says where the role applies:

import { definePolicy, role, allow, deny } from "permdock";

const viewer = role(
  "viewer",
  [allow([permissions.post.read, permissions.post.list])],
  { on: "tenant" },
);
const admin = role(
  "admin",
  [
    ...viewer.grants,
    allow(permissions.post.delete),
    allow(permissions.member.invite),
  ],
  { on: "tenant" },
);
const lead = role("lead", [allow(permissions.post.publish)], { on: "team" });
const editor = role("editor", [allow(permissions.document.update)], {
  on: permissions.document,
});
const owner = role(
  "owner",
  [allow(permissions.org.delete, { approval: "human" })],
  { on: "tenant", assignable: false },
);
const support = role("support", [allow(permissions.post.read)]); // global, unchanged

export const policy = definePolicy(permissions, {
  roles: [viewer, admin, lead, editor, owner, support],
  scopes: {
    tenant: { key: "orgId" }, // the first scope: what the active tenant selects
    team: { key: "teamId", within: "tenant" }, // every later scope names its parent
  },
  subject: subjectFromClerk, // or your own mapper; see "Where memberships come from"
});

Scope names, their order, the aliases and the no-cascade rule are on named scopes. Two more options:

• assignable (default true for scoped roles, false for global roles) marks a role a tenant admin may hand out and compose into custom roles. owner above is held but never handed out.
• exclusiveWith: ['approver'] is data on role() / RoleBinding (INCITS 359 static separation of duty). Evaluation does not change. permdock doctor check PD018 and separationConflicts(policy, memberships) report conflicts.

Scope keys and typingCopy Anchor Link

Every resource an instance grant on scope S references declares a memberOf: S relation on the scope's key; definePolicy throws when one is missing, so where() and RLS always narrow the rows. A resource no scoped grant touches is global by construction (a plan catalogue everyone reads). Collection actions (post.create, post.list) have no row, so they require the active tenant to be one of the subject's memberships holding the role; that is what stops "create in a tenant I can see but do not belong to".

The where: { orgId: principal.orgId } convention still works and still compiles; scoped roles are the shorter, un-forgettable form of the same condition. A grant may carry both (a tenant admin may only publish unpublished posts: allow(permissions.post.publish, { where: { published: false } }) on a tenant-scoped role).

Resource roles and parentsCopy Anchor Link

A resource role follows a declared parent chain:

export const permissions = definePermissions({
  project: resource(Project, { id: "id", actions: ["read", "update"] }),
  folder: resource(Folder, {
    id: "id",
    actions: ["read", "update"],
    parent: { field: "projectId", resource: "project" },
  }),
  document: resource(Document, {
    id: "id",
    actions: ["read", "update", "share"],
    parent: { field: "folderId", resource: "folder" },
  }),
});

const editor = role(
  "editor",
  [allow([permissions.document.update, permissions.folder.update])],
  { on: [permissions.folder, permissions.document] },
);

An editor membership on folder f_1 matches document.update for a document whose folderId is f_1. Matching is keyed by the membership's resource: the row's own id field identifies it only when the row is of that resource, and a descendant row matches through the parent field of that resource on its chain, so a document whose id happens to be f_1 does not match. A membership on the role's resource or one of its ancestors counts (a project editor edits the documents of its folders when the document row carries projectId); a membership on an unrelated resource never does. The chain is finite because it is typed: document to folder to project, three hops, declared once. parent.resource is the parent name string, not a reference; a resource declares at most one parent; the name is resolved at definePolicy after any mergePermissions. When the membership's resource is self-parented (folders in folders) and the instance has a relations source, a membership on a folder also matches its subfolders and rows whose parent is one of them, walked up to the default depth and stopped by restricted rows; without a source it matches that folder and its typed descendants only. RLS applies the membership to the named instance and its typed descendants, not to subfolders (relationships). The row must carry the parent field; a missing parent field is a non-match, never a walk-up query.

A share link is a principal holding exactly one such membership, { on, roles, via: 'link' }, from a signed capability (link capabilities).

Grants over several referencesCopy Anchor Link

allow and deny accept an array of references so a role does not repeat a condition per action:

allow([permissions.post.read, permissions.post.list, permissions.comment.read]);
allow(listPermissions(permissions.post)); // everything on one resource
allow([permissions.post.update, permissions.post.delete], {
  where: { authorId: principal.id },
});

Each reference becomes its own grant in the normalised policy, the catalog and the snapshot; the array is declaration sugar only, and permdock collect sees the individual leaves. Strings never appear; listPermissions returns references.

EvaluationCopy Anchor Link

The policy rules gain one step between collecting grants and applying deny-overrides:

1. Collect candidate grants: every grant of every global role in principal.roles, plus every grant of every scoped role held by a membership, plus the grants that custom roles resolve to (below).
2. Scope match. Drop a grant whose role is scoped unless a membership of exactly that scope matches the request (no cascade): the membership sits inside the active tenant; the row's key for the scope equals the membership id and each declared ancestor key equals its within entry; or, for a resource role, the row is the membership's resource or a descendant through declared parents. Expired memberships (expiresAt in the past) contribute nothing: no roles, no tenant in tenants(), no active tenant, and no authority in assignableRoles() or decideRoleChange. For collection actions, the active tenant must be one of the membership tenants holding the role.
3. Any matching deny wins. Deny overrides allow across scopes: a global deny beats a tenant allow; a tenant deny beats a team allow.
4. Any matching allow grants (or approval-required). Allows OR together across scopes.
5. Nothing matched: denied. Reasons gain tenant-mismatch (the row belongs to another tenant), no-membership (the active tenant is not one of the subject's), scope (the role is held but not for this row) and expired-membership.
6. Intersect with delegation, unchanged.

can() still never throws and a subject with memberships and no active tenant is simply denied everything tenant-scoped. simulate accepts { roles, memberships, tenant } so a test or a "view as" screen can ask "what would a Globex viewer see" without a real membership (UI).

Organisation roles with team reachCopy Anchor Link

A role held at the organisation that reaches only the rows of the principal's teams is an organisation role with an in condition on the team key. It needs no team-scoped role, and holding a team membership alone grants nothing through it.

role(roles.manager, [
  allow([permissions.job.read, permissions.job.update], {
    where: { teamId: { in: principal.claims.team_ids } },
  }),
]); // on: 'organization'

• In-process, the list comes from the subject: principal.claims.team_ids from a verified token, or a principal attribute such as principal.teamIds that subject() loads. A missing or non-array value matches no row.

• Snapshots bind the list to the subject's value when they are built, because the snapshot principal carries only id, roles, plans, tenant and memberships. fromSnapshot(snapshot).decide therefore agrees with decide; a team change reaches the client with the next snapshot.

• RLS compiles it in set form in both database and jwt mode: "teamId" = any (array(... auth.jwt() -> 'team_ids' ...)), one uncorrelated array per statement, never a per-row helper call. Only principal.claims.* refs compile to SQL, so name the claim, not an attribute.

• Supabase writes the claim through supabase.hook.claims with a function that reads the same membership rule as the helpers (custom claims):

  Copy Text

  create function app.team_ids(user_id uuid) returns jsonb
  language sql stable as $$
    select to_jsonb(array(select permdock.member_team_ids_for(user_id)))
  $$;

  member_team_ids_for exists when the team scope has a memberships source. The claim is as fresh as the token: a change to that source table bumps authz_ver, so a fresh permission denies with stale-credentials until the next refresh carries the new list (authorization version).

Tenant-defined custom rolesCopy Anchor Link

A tenant admin wants a "Billing Manager" role. The policy did not declare it and must not have to. A custom role is data, composed from declared roles, from single permissions, or both:

type CustomRole = {
  tenant: string; // the instance of the first scope that owns it
  scope?: string; // the scope it is held at; default the first scope
  id?: string; // pins it to one instance of `scope`
  name: string; // 'billing-manager'; unique within the tenant
  includes?: string[]; // declared roles: ['billing-viewer', 'invoice-payer']
  grants?: { permission: string; effect?: "allow" | "deny" }[]; // declared permission keys
  meta?: Record<string, unknown>;
};

• A custom role never exceeds its ceiling: the allows of the declared roles marked assignable in its scope (scope, the first scope by default; the input shape team means the second). Its effective grants are its included roles' grants plus its own allows, minus its own denies, intersected with the ceiling. Anything outside is dropped (fewer grants, never more), and validateCustomRole and permdock doctor PD023 name each dropped key.
• A custom-role grant carries no condition, approval or limit of its own. It inherits those of the declared grant it comes from, so every condition was reviewed in code.
• RoleSource.assignable(tenant) may return a subset of the declared assignable roles: a Starter plan without billing-manager, a regulated tenant without data-exporter. This is Clerk's role-set idea and the entitlements-are-roles rule applied to assignability; the plan is an input, PermDock never reads billing.
• Who may hand out which role is itself a permission (permissions.member.assignRole) plus the rule that you cannot hand out what you do not hold: permdock.assignableRoles() and permdock.assignablePermissions() intersect the ceiling (narrowed by RoleSource.assignable) with what the subject holds there. Holding a role or a permission marked meta.manageRoles: true lifts that intersection.

Custom roles has the resolution rules, the ceiling, the matrix-editor recipe and how snapshots carry the result.

InterfacesCopy Anchor Link

interface RoleSource {
  rolesFor(
    tenant: string,
    context?: { held: string[] }, // the role names the subject holds in that tenant
  ): CustomRole[] | Promise<CustomRole[]>;
  assignable?(tenant: string): string[] | Promise<string[]>; // defaults to every declared assignable role
}

interface MembershipSource {
  membershipsFor(
    principal: { id: string; kind?: string },
    options: { tenant?: string },
  ): Membership[] | Promise<Membership[]>;
  list?(query: {
    scope: string;
    id: string;
  }): MemberEntry[] | Promise<MemberEntry[]>;
  version?(principal: {
    id: string;
  }): number | undefined | Promise<number | undefined>;
  readonly claimsFirst?: boolean;
}

Both are subject inputs, the same trust class as the policy's subject and context functions: they run once per createPermDock, their results are frozen into the subject, and they are the only two interfaces on the extension interfaces page that may influence an outcome. Neither is a store: PermDock never writes a membership or a custom role. memoryRoleSource(customRoles) and the default membership source (whatever subject and context returned) ship in the package. permdock/cloud does not implement either, so the Cloud never joins the decision path (invariant 15). Provider role sources: Better Auth organizationRole (dynamicAccessControl), a Supabase role_permissions table, WorkOS organization roles, Clerk custom roles and role sets, Auth0 Organization Roles, your own table; each is a RoleSource whose conformance the testing runners check.

Every adapter's createPermDock accepts memberships (a MembershipSource, or an array composed and de-duplicated by composeMemberships), customRoles (a RoleSource) and entitlements (an EntitlementSource whose plan names join principal.plans for the active tenant) next to store and sink; the shared set is the InstanceOptions type. claimsFirst(sources) keeps the verified token's memberships and reads the sources only when the token was truncated; with a version, token memberships behind it deny the policy's fresh permissions with stale-credentials, or with onStale: 'reread' are replaced by the sources' memberships. A membership may carry managedBy: 'idp' (the identity provider owns it; decideRoleChange refuses to change it with externally-managed) and entitlements (seats that plan() grantees match inside the active tenant). The Supabase token hook page shows the SQL sources and the claims they compile to; core takes createPermDock(policy, user, { tenant, memberships, customRoles, actor, delegation }).

Where memberships come fromCopy Anchor Link

A membership table that stores a role id instead of a role name works too: the permdock/supabase sources and the RLS mappings read the key through the app's roles table (token hook). The same goes for a membership table that names a profile instead of a login, such as portal contacts whose login is contact_profiles.user_id: the sources read the user id through the profile table, and re-linking the profile to another login moves its memberships.

The authentication page carries the full provider table; each provider page has a "Memberships" section.

Instance methods for tenancyCopy Anchor Link

The instance stays frozen and request-scoped; tenancy adds derived instances and read-only introspection:

await permdock.tenant("o_globex").assert(permissions.post.update, post); // a derived instance with another active tenant
permdock.team("t_design").can(permissions.post.publish); // scope a team for collection actions and checks without a row

permdock.memberships(); // Membership[]           for org lists and role chips
permdock.tenants(); // string[]               tenants the subject belongs to
permdock.heldRoles({ tenant: "o_acme" }); // Role[]        roles held there, custom roles resolved
permdock.heldRoles({ scope: "customer", id: "c_7" }); // Role[]  roles on one scope instance's memberships
permdock.audiences(); // string[]              meta.audience of the roles held in the active tenant
permdock.assignableRoles(); // Role[]                roles the subject may hand out in the active tenant
permdock.assignablePermissions(); // Permission[]          the custom-role ceiling the subject may hand out there
permdock.decideRoleChange(change); // RoleChangeDecision    may the subject assign, revoke or transfer this role

heldRoles and assignableRoles are ranked by the policy's assigns graph, so a role chip list shows rank without hard-coded names. decideRoleChange and the ownership rules behind it are on ownership.

tenant() and team() return new frozen instances (invariant 7); they never mutate the original and they re-run nothing, because memberships were loaded once. Switching a tenant the subject does not belong to yields an instance where every tenant-scoped check is denied with no-membership. On the client the same methods exist on the snapshot-backed instance and back useTenant, useMemberships, useRoles, useAssignableRoles and useAssignablePermissions (UI).

Portable compilationCopy Anchor Link

Scope matching is data, so it compiles like any other condition (invariant 6). One node is added to the condition AST:

{ "op": "memberOf", "scope": "tenant",   "field": "orgId", "roles": ["admin", "viewer"] }
{ "op": "memberOf", "scope": "customer", "field": "customer_id", "roles": ["contact"] }
{ "op": "memberOf", "scope": "resource", "resource": "folder", "field": "folderId", "roles": ["editor"], "parents": [{ "field": "projectId", "resource": "project" }] }

A parents entry is either keyed ({ field, resource }: only a membership on that resource matches the field) or a bare field name (a membership on any resource whose id equals the field). Prefer the keyed form; the bare form exists for conditions written before it and matches the older behaviour. Membership expiresAt is Unix seconds, in memory and in a mapped expires_at column.

Membership checks have a dedicated memberOf AST node, and the membership table is a per-scope mapping on the RLS adapter, one table per scope and one per mapped resource (memberships: { scopes: { organization: ..., customer: ... }, resource: { document: ... } }). permdock rls import recognises both IN (select ...) and EXISTS (select 1 ...) forms as memberOf when the subquery matches a declared mapping. Custom roles do not add a node: with permdock rls generate --custom-roles, the helpers resolve a custom role name to grant keys through the ceiling of assignable declared roles, so the generated policies stay a closed vocabulary (custom roles).

Snapshots, decisions and the catalogCopy Anchor Link

• The snapshot carries subject.memberships, subject.tenant, vocabulary.roles / vocabulary.plans, the ordered scopes, and per grant to plus scope (a scope name or { resource }) and the membership it came from. A snapshot is scoped to the active tenant by default, so a member of ten organisations ships the grants of one; snapshot({ tenants: 'all' }) opts into every membership for a local tenant switcher. simulated: true marks a snapshot produced by simulate so the decision endpoint refuses to act on its tokens (snapshots, wire formats).
• Decision events gain tenant, membership (the matching entry) and via, so a sink can answer "which team grant let this happen" and a tenant-scoped audit log is a filter on tenant (audit).
• Catalog roles carry on (a scope name or resource) and assignable, and the catalog lists the policy's scopes in order. permdock usage reports a scoped role that no membership source could ever fill (a team role with no team source configured).
• AuthZEN: memberships travel under subject.properties.memberships, the active tenant under context.tenant; the authzen adapter and the hosted ADS publish per-tenant metadata at /.well-known/authzen-configuration/<tenant> (AuthZEN).

Validation and trust classesCopy Anchor Link

Adjacent SaaS featuresCopy Anchor Link

Vocabulary for reviewersCopy Anchor Link

For teams that audit against INCITS 359-2012 (the NIST RBAC standard): a request-scoped PermDock with an active tenant is a session with an activated role set; grant spread (...viewer.grants) is a limited role hierarchy (no general hierarchy is offered on purpose); memberships are user assignments with a scope; custom roles are administrator-composed roles constrained to permission assignments the code declared; static separation of duty is reported by PD018 and separationConflicts, never enforced at evaluation, and dynamic separation of duty (two roles not active in one session) is not planned. On the token side, roles and groups follow RFC 9068 and SCIM (JWT authorization claims).

Why this modelCopy Anchor Link

Authorization engines converge on the same shape. Permit.io, Oso Cloud (has_role(user, "admin", org)), OpenFGA and SpiceDB (organization#admin, team#member usersets) and Cerbos (scoped policies) all treat a role as a relation between a subject and a scope, never a bare string. Tenant-defined roles are always composed from a vocabulary the code declared (Oso grants_permission facts, an OpenFGA role type, Better Auth dynamicAccessControl), and parent derivation is declared one hop at a time (Permit role derivation, Oso role if role on "parent"). PermDock takes all three: a Membership names the scope, role(name, grants, { on }) puts the scope on the role instead of on every grant, a custom role composes and never widens, and parent is typed so the chain is finite. Repeating the tenant condition on every grant, not the declaration syntax, is where cross-tenant bugs come from; scoping the role removes the repetition without a fluent builder.

Auth providers own the rest. Clerk, Auth0, WorkOS, Stytch, Kinde, Descope and Better Auth all own the tenant object, membership rows, invitations, the active-tenant selection and the group-to-role mapping, and expose the result as claims or a session; none evaluates a condition on a row. Clerk's role sets (which roles an organization or plan may assign) map to RoleSource.assignable(tenant), and Better Auth's "cannot grant a role you do not hold" rule maps to permdock.assignableRoles(). Entitlement platforms such as Stigg and Schematic answer "may this tenant use this capability" and are an input to subject and assignable, not a role model.

Scope and tenant ids compare as exact text, and PermDock never lower-cases them. Lowering would merge ids that differ only in case, such as Clerk's case-sensitive org_… ids, and give one tenant's members another tenant's rows; exact comparison fails closed instead. Postgres already prints uuid::text in lower case, so a producer that emits uuid::text into claims and membership rows gets the same id decide and the SQL helpers compare (RLS).

No standard tenant claim exists: Entra uses tid, Auth0, WorkOS and Clerk org_id, Google hd, Supabase deployments conventionally tenant_id, and Descope a tenants object keyed by tenant id. The mapping stays configuration (claims.tenant), and an absent tenant claim means no tenant, never a default. SCIM groups have no tenant attribute either, and nested groups are provider-specific (Entra does not expand them in members.value filters).

PermDock deliberately leaves out storing memberships, invitations or tenant objects (a hosted store would sit on the decision path); nested groups, arbitrary-depth trees and cross-tenant graphs, which permdock/pdp hands to a Zanzibar engine with one tuple per resource membership; and global module augmentation or a $Infer accessor for provider principal types, which generics filled from a Standard Schema replace.