permdock 0.6.0 → 0.7.0

package/dist/{ownership-DqaJNJPn.js → ownership-Z2LpxsGa.js}

@@ -1,17 +1,19 @@
 import { a as sole, n as isReadonlyArray, r as isRecord } from "./compact-CAf557ZB.js";
 import { n as isForbiddenKey } from "./paths-DXSHAMIa.js";
-import { l as isSqlFunctionField } from "./refs-K6eWUJ0H.js";
+import { u as isSqlFunctionField } from "./refs-CNJBiTFo.js";
+import { c as listPermissions, h as formerKeys } from "./permission-registry-DpPtSKNZ.js";
 import { u as isoAt } from "./time-DkWjdL98.js";
-import { c as rootScope, d as scopeList, l as scopeChain, o as resolveScope } from "./scopes-CUPSjo9q.js";
+import { f as scopeList, l as rootScope, s as resolveScope, u as scopeChain } from "./scopes-BHsc-wp-.js";
 import { t as isoInstant } from "./instant-BluqDvyS.js";
-import { m as findRole, v as listRoles } from "./grantee-hxrUsbpM.js";
-import { r as relationCondition, t as inheritCondition } from "./grantee-conditions-CcXf8hMM.js";
-import { l as partitionsOf, p as scopeField } from "./tenancy-DN2QAx9z.js";
-import { i as configError } from "./errors-CWTY6uih.js";
-import { i as scopeMembershipTable, o as relatedSql, r as scopeColumn } from "./compile-CMqMx_IN.js";
-import { i as qualifySqlTable, t as SQL_IDENT, u as sqlTextArray } from "./sql-B5T1IL83.js";
-import { d as keptKeys, l as roleColumn, u as roleManifest } from "./sources-vs5dGOsS.js";
-import { A as declaredArray, D as sqlType, E as scopeTypeOf, F as quoteQualified, I as quoteTable, L as textArrayLiteral, M as qualified, N as quoteIdent, O as tenantTypeOf, P as quoteLiteral, S as CLAIM, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, i as allowEntry, j as helperSchema, k as CLI, m as memberVia, n as GLOBAL_ROLES, o as rootName, p as liveSessionSql, r as HELPERS, s as signedIn, t as CUSTOM_ROLES, u as globalKindFilterSql, v as subjectClaimSql, x as userIdHelperSql, y as subjectIdSql } from "./shared-BAK8t4Uo.js";
+import { m as findRole, v as listRoles } from "./grantee-BrRANrpT.js";
+import { r as relationCondition, t as inheritCondition } from "./grantee-conditions-C6P1Tvol.js";
+import { l as partitionsOf, p as scopeField } from "./tenancy-CmeBQ6Nv.js";
+import { a as delegatedScopeMap } from "./permdock-BfWEeMqk.js";
+import { i as configError } from "./errors-DpP_U6Bf.js";
+import { d as sqlTextArray, i as qualifySqlTable, t as SQL_IDENT } from "./sql-B96movIM.js";
+import { i as scopeMembershipTable, o as relatedSql, r as scopeColumn } from "./compile-BAEO5bOk.js";
+import { d as keptKeys, l as roleColumn, u as roleManifest } from "./sources-B-zYB4GS.js";
+import { A as quoteQualified, D as qualified, E as helperSchema, F as scopeTypeOf, I as sqlType, L as tenantTypeOf, M as textArrayLiteral, O as quoteIdent, S as CLAIM, T as declaredArray, _ as subjectClaimJsonSql, b as tenantClaimSql, d as keyTenantSql, f as kindFilterSql, h as roleKindSql, i as allowEntry, j as quoteTable, k as quoteLiteral, m as memberVia, n as GLOBAL_ROLES, o as rootName, p as liveSessionSql, r as HELPERS, s as signedIn, t as CUSTOM_ROLES, u as globalKindFilterSql, v as subjectClaimSql, w as CLI, x as userIdHelperSql, y as subjectIdSql } from "./shared-fMKOv8hP.js";
 //#region src/cli/sql/active.ts
 function checkActiveRow(label, row) {
 	quoteTable(row.table);
@@ -699,6 +701,10 @@ function collectGrants(policy) {
 		};
 	});
 }
+/** The declared roles a custom role may draw grants from: the custom-role ceiling. */
+function assignableRoles(policy) {
+	return [...roleNames(policy)].toSorted().filter((name) => policy.rolesByName.get(name)?.assignable ?? listRoles(policy.vocabulary.roles).some((leaf) => leaf.key === name && leaf.assignable));
+}
 /** Declared role names (bindings and `defineRoles` leaves) plus any role a top-level grant names. */
 function roleNames(policy) {
 	const names = new Set(policy.roles.map((item) => item.name));
@@ -1205,7 +1211,7 @@ end;`;
           and ${qualified(ctx, HELPERS.has)}(m.grant_key)
       )`;
 		const match = `c.tenant_id is not distinct from p_tenant and c.scope = p_scope and c.scope_id is not distinct from p_scope_id and c.role = p_role`;
-		const allowEntryOf = custom.levels === true ? "c.permission || coalesce('@' || c.level, '')" : "c.permission";
+		const allowEntryOf = `c.${allowEntry(ctx)}`;
 		const checked = (gate) => `begin
   if p_role = any(${sqlTextArray(custom.declared)}) then
     return query
@@ -1248,7 +1254,7 @@ revoke execute on function ${reader}(text, text, ${tenantType}, text) from publi
 grant execute on function ${reader}(text, text, ${tenantType}, text) to authenticated;`);
 	const trusted = qualified(ctx, READERS.trusted);
 	const signature = `text, text, ${tenantType}, text`;
-	const grants = trustedReaders === void 0 || trustedReaders.length === 0 ? "" : `\ngrant execute on function ${trusted}(${signature}) to ${trustedReaders.map(quoteIdent).join(", ")};`;
+	const grants = trustedReaders === void 0 || trustedReaders.length === 0 ? "" : `\n${trustedReaderGrants(ctx, `${trusted}(${signature})`, trustedReaders)}`;
 	chunks.push(`create or replace function ${trusted}(p_role text, p_scope text, p_tenant ${tenantType} default null, p_scope_id text default null)
 returns table (permission text, effect text)
 language plpgsql
@@ -1301,6 +1307,16 @@ ${indent}  hint = ${quoteLiteral(hint)};`;
 function hasCustomRoleChecksFor(ctx) {
 	return ctx.authorize === "database" && ctx.customRoles !== void 0 && ctx.scopes.length > 0 && ctx.scopes.every((scope) => hasMemberFor(ctx, scope.name));
 }
+/**
+* The grants a `rls.trustedReaders` role needs for one reader: usage on the
+* helper schema, which no client role reaches through these lines, and
+* execute on the function.
+*/
+function trustedReaderGrants(ctx, fn, readers) {
+	const to = readers.map(quoteIdent).join(", ");
+	return `grant usage on schema ${quoteIdent(helperSchema(ctx))} to ${to};
+grant execute on function ${fn} to ${to};`;
+}
 //#endregion
 //#region src/cli/sql/global-roles.ts
 function qualify(name, schema) {
@@ -1328,6 +1344,7 @@ function globalRoleSource(source, schema, alias, roles) {
 		from: `${quoteTable(table)} ${alias}${role.join}${global}`,
 		userSql: `${alias}.${quoteIdent(user)}`,
 		roleSql: role.sql,
+		nullable: role.nullable,
 		role: roleManifest(role),
 		...role.through === void 0 ? {} : { through: role.through },
 		...tenant === void 0 ? {} : { tenant },
@@ -1738,7 +1755,7 @@ ${rows}
   union
   select (ms.id)::${type}, ck.grant_key
 ${rows}
-${customKeysJoin(ctx, scope, entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}
+${customKeysJoin(ctx, scope, entries(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}
   where ${signedIn(ctx)}
     and ms.scope = ${quoteLiteral(scope)}
     and not (r.role = any(${sqlTextArray(custom.declared)}))${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql("ck.grant_key"), sourcesKeep(sources))}`, sources, subjectIdSql(ctx));
@@ -1749,7 +1766,7 @@ ${rows}
   where ${signedIn(ctx)}
     and ms.scope = ${quoteLiteral(scope)}
     and not (r.role = any(${sqlTextArray(custom.declared)}))${narrow}${sourceFilters(ctx, scope, subjectIdSql(ctx), grantPermissionSql("p_grant"), sourcesKeep(sources))}
-${customKeysSql(ctx, scope, entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}`, sources, subjectIdSql(ctx));
+${customKeysSql(ctx, scope, entries(CUSTOM_ROLES.permissions, allowEntry(ctx), " and c.effect = 'allow'"), entries(CUSTOM_ROLES.permissions, "permission", " and c.effect = 'deny'"), entries(CUSTOM_ROLES.includes, "include_role", ""))}`, sources, subjectIdSql(ctx));
 }
 function scopedBody(ctx, scope, type) {
 	if (ctx.authorize !== "database") return sqlBody(claimBody(ctx, scope, type));
@@ -1799,6 +1816,137 @@ revoke execute on function ${fn}(text, text, text) from public;
 grant execute on function ${fn}(text, text, text) to anon, authenticated;`;
 }
 //#endregion
+//#region src/cli/rls/custom-role-by-id.ts
+const PREFIX = "PermDock CLI";
+const col = (name) => `r.${quoteIdent(name)}`;
+/**
+* Custom-role functions keyed by the application's role row
+* (`rls.customRoleWrites.roles.primaryKey`): the tenant, scope, instance and
+* name come from the row, never from the caller. The writers delegate to
+* `permdock_replace_custom_role_grants` (or its trusted variant), so every
+* caller and definition check applies, and keep the stored denies and
+* includes. The reader returns declared allow keys only and is executable by
+* `rls.trustedReaders` alone.
+*/
+function customRoleByIdSql(ctx, trustedReaders) {
+	const custom = ctx.customRoles;
+	const roles = custom?.table;
+	const root = ctx.scopes[0]?.name;
+	if (custom === void 0 || roles?.primaryKey === void 0 || ctx.authorize !== "database" || root === void 0) return "";
+	const pk = roles.primaryKey;
+	if (pk === "") throw configError(`${PREFIX}: rls.customRoleWrites.roles.primaryKey names no column`);
+	const leveled = custom.levels === true;
+	const tenantType = tenantTypeOf(ctx);
+	const table = quoteQualified(roles.table);
+	const idType = `${table}.${quoteIdent(pk)}%type`;
+	const perms = qualified(ctx, CUSTOM_ROLES.permissions);
+	const includes = qualified(ctx, CUSTOM_ROLES.includes);
+	const replace = qualified(ctx, CUSTOM_ROLES.replace);
+	const trustedReplace = qualified(ctx, CUSTOM_ROLES.trustedReplace);
+	const byId = qualified(ctx, CUSTOM_ROLES.replaceById);
+	const trustedById = qualified(ctx, CUSTOM_ROLES.trustedReplaceById);
+	const reader = qualified(ctx, CUSTOM_ROLES.trustedReadById);
+	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
+	const current = (expr) => currentKeyExpr(renames, expr);
+	const declaredKeys = sqlTextArray(custom.permissions ?? []);
+	const declaredRoles = sqlTextArray(custom.declared);
+	const tenant = roles.tenant === void 0 ? `null::${tenantType}` : `${col(roles.tenant)}::${tenantType}`;
+	const scope = rolesTableScope(roles, tenant, root, col);
+	const scopeId = roles.id === void 0 || roles.tenant === void 0 ? "null::text" : `case when ${tenant} is null then null else ${col(roles.id)}::text end`;
+	const skipped = roles.skip === void 0 || roles.tenant === void 0 ? "false" : `(${tenant} is not null and coalesce(${col(roles.skip)}, false))`;
+	const match = "c.tenant_id is not distinct from v_tenant and c.scope = v_scope and c.scope_id is not distinct from v_scope_id and c.role = v_key";
+	const audit = custom.audit;
+	const auditCall = audit === void 0 ? "" : `
+  perform ${quoteQualified(audit.function)}(${[
+		"event_type => 'permdock.custom_role.replaced'",
+		"target_type => 'role'",
+		"record_id => p_role_id::text",
+		"tenant => v_tenant",
+		"metadata => jsonb_build_object('operation', 'replace', 'role', v_key, 'permissions', p_permissions)",
+		...Object.entries(audit.args ?? {}).toSorted(byKey).map(([name, value]) => `${quoteIdent(name)} => ${quoteLiteral(value)}`)
+	].join(", ")});`;
+	const body = (write) => `declare
+  v_tenant ${tenantType};
+  v_scope text;
+  v_scope_id text;
+  v_key text;
+  v_skipped boolean;
+  v_deny text[];
+  v_include text[];
+begin
+  select ${tenant}, ${scope}, ${scopeId}, ${col(roles.key)}::text, ${skipped}
+  into v_tenant, v_scope, v_scope_id, v_key, v_skipped
+  from ${table} r
+  where ${col(pk)} = p_role_id;
+  if not found then
+${raiseSql("    ", "P0002", "'permdock: no role row has id ' || coalesce(p_role_id::text, 'null')", "unknown-role")}
+  end if;
+  if v_skipped or v_key = any(${declaredRoles}) then
+${raiseSql("    ", "22023", "'permdock: ' || coalesce(v_key, 'null') || ' is a declared role, not a custom role'", "declared-role")}
+  end if;
+  select array_agg(c.permission) into v_deny
+  from ${perms} c
+  where ${match} and c.effect = 'deny';
+  select array_agg(c.include_role) into v_include
+  from ${includes} c
+  where ${match};
+  perform ${write}(v_tenant, v_scope, v_scope_id, v_key, p_permissions, v_deny, v_include);${auditCall}
+end;`;
+	const writer = (comment, name, write, member) => `-- ${comment}
+create or replace function ${name}(p_role_id ${idType}, p_permissions text[])
+returns void
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+${body(write)}
+$$;
+${member ? `revoke execute on function ${name}(${idType}, text[]) from public, anon;
+grant execute on function ${name}(${idType}, text[]) to authenticated;` : `revoke execute on function ${name}(${idType}, text[]) from public, anon, authenticated;`}`;
+	const readerEntry = leveled ? `${current("c.permission")} || coalesce('@' || c.level, '')` : current("c.permission");
+	const readerGrant = trustedReaders === void 0 || trustedReaders.length === 0 ? "" : `\n${trustedReaderGrants(ctx, `${reader}(text[], ${tenantType})`, trustedReaders)}`;
+	return `${writer("save a custom role by its row id: the row supplies tenant, scope, instance and name; the caller checks of permdock_replace_custom_role_grants apply, and stored denies and includes stay", byId, replace, true)}
+
+${writer("save a custom role by its row id for a trusted caller: the definition checks without the caller checks", trustedById, trustedReplace, false)}
+
+-- the declared allow keys of custom roles by their row ids as text, for a trusted reader; with p_tenant, an id of another tenant is refused
+create or replace function ${reader}(p_role_ids text[], p_tenant ${tenantType} default null)
+returns table (role_id text, permission text)
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+begin
+  if p_tenant is not null and exists (
+    select 1 from ${table} r
+    where ${col(pk)}::text = any(p_role_ids) and ${tenant} is distinct from p_tenant
+  ) then
+${raiseSql("    ", "42501", "'permdock: a role id belongs to another tenant than ' || p_tenant::text", "not-member")}
+  end if;
+  return query
+  select distinct v.role_id, ${readerEntry}
+  from (
+    select ${col(pk)}::text as role_id, ${tenant} as tenant_id, ${scope} as scope, ${scopeId} as scope_id, ${col(roles.key)}::text as role
+    from ${table} r
+    where ${col(pk)}::text = any(p_role_ids)
+      and not ${skipped}
+      and not (${col(roles.key)}::text = any(${declaredRoles}))
+  ) v
+  join ${perms} c
+    on c.tenant_id is not distinct from v.tenant_id
+    and c.scope = v.scope
+    and c.scope_id is not distinct from v.scope_id
+    and c.role = v.role
+  where c.effect = 'allow'
+    and ${current("c.permission")} = any(${declaredKeys})
+  order by 1, 2;
+end;
+$$;
+revoke execute on function ${reader}(text[], ${tenantType}) from public, anon, authenticated;${readerGrant}`;
+}
+//#endregion
 //#region src/cli/rls/custom-role-cascade.ts
 /** `row.column`, for a trigger's `old` or `new`. */
 function rowColumn(row, name) {
@@ -1830,11 +1978,11 @@ function customRoleCascadeSql(ctx) {
 	const target = quoteTable(qualifySqlTable(table.table));
 	const tenant = (row) => table.tenant === void 0 ? `null::${tenantType}` : `${rowColumn(row, table.tenant)}::${tenantType}`;
 	const scope = (row) => rolesTableScope(table, tenant(row), root, (name) => rowColumn(row, name));
-	const id = (row) => table.id === void 0 ? "null::text" : `${rowColumn(row, table.id)}::text`;
-	const skipped = (row) => table.skip === void 0 ? "false" : `coalesce(${rowColumn(row, table.skip)}, false)`;
+	const id = (row) => table.id === void 0 || table.tenant === void 0 ? "null::text" : `case when ${tenant(row)} is null then null else ${rowColumn(row, table.id)}::text end`;
+	const skipped = (row) => table.skip === void 0 || table.tenant === void 0 ? "false" : `(${tenant(row)} is not null and coalesce(${rowColumn(row, table.skip)}, false))`;
 	const guard = qualified(ctx, CUSTOM_ROLES.guard);
 	const entries = qualified(ctx, CUSTOM_ROLES.entries);
-	const allowEntryOf = custom.levels === true ? "c.permission || coalesce('@' || c.level, '')" : "c.permission";
+	const allowEntryOf = `c.${allowEntry(ctx)}`;
 	return `-- the application's roles table: renames, moves and deletes of a custom role carry its grants and includes
 create or replace function ${fn}()
 returns trigger
@@ -1913,6 +2061,58 @@ create trigger "permdock_custom_role_cascade"
 `;
 }
 //#endregion
+//#region src/cli/rls/custom-role-guard.ts
+/** A column of the roles-table row a trigger sees as `new`. */
+function column(name) {
+	return `new.${quoteIdent(name)}`;
+}
+/**
+* The trigger on the application's roles table (`rls.customRoleWrites.roles`)
+* that refuses a tenant row named like a declared role (`declared-role`) or
+* like a shared custom role (`name-taken`). A row the `skip` column marks is
+* a system role of the tenant and passes. Empty without a tenant column: then
+* no row is a tenant row.
+*/
+function customRoleNameGuardSql(ctx) {
+	const custom = ctx.customRoles;
+	const table = custom?.table;
+	const root = ctx.scopes[0]?.name;
+	if (custom === void 0 || table?.tenant === void 0 || root === void 0) return "";
+	const tenant = `${column(table.tenant)}::${tenantTypeOf(ctx)}`;
+	const skipped = table.skip === void 0 ? "false" : `coalesce(${column(table.skip)}, false)`;
+	const fn = qualified(ctx, CUSTOM_ROLES.nameGuard);
+	const target = quoteTable(qualifySqlTable(table.table));
+	const key = `${column(table.key)}::text`;
+	const scope = rolesTableScope(table, tenant, root, column);
+	return `-- the application's roles table: a tenant row cannot take the name of a declared or a shared role
+create or replace function ${fn}()
+returns trigger
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+begin
+  if ${tenant} is null or ${skipped} then
+    return new;
+  end if;
+  if ${key} = any(${sqlTextArray(custom.declared)}) then
+${raiseSql("    ", "22023", `'permdock: ' || ${key} || ' is a declared role'`, "declared-role")}
+  end if;
+  if ${qualified(ctx, CUSTOM_ROLES.shared)}(${scope}, ${key}) then
+${raiseSql("    ", "22023", `'permdock: ' || ${key} || ' is a shared role'`, "name-taken")}
+  end if;
+  return new;
+end;
+$$;
+revoke execute on function ${fn}() from public, anon, authenticated;
+drop trigger if exists "permdock_custom_role_name_guard" on ${target};
+create trigger "permdock_custom_role_name_guard"
+  before insert or update on ${target}
+  for each row execute function ${fn}();
+`;
+}
+//#endregion
 //#region src/cli/rls/custom-role-writes.ts
 function callerFunctionsSql(ctx, custom, root, levelReach, forUser) {
 	const leveled = custom.levels === true;
@@ -2063,6 +2263,7 @@ function customRoleWritesSql(ctx, levelReach) {
 	const guard = qualified(ctx, CUSTOM_ROLES.guard);
 	const shape = qualified(ctx, CUSTOM_ROLES.shape);
 	const entries = qualified(ctx, CUSTOM_ROLES.entries);
+	const problem = qualified(ctx, CUSTOM_ROLES.entryProblem);
 	const renames = Object.entries(custom.renamed ?? {}).toSorted(byKey);
 	const current = (expr) => currentKeyExpr(renames, expr);
 	const known = sqlTextArray([...custom.permissions ?? [], ...renames.map(([former]) => former)]);
@@ -2150,6 +2351,38 @@ ${callerFunctionsSql(ctx, custom, root, levelReach, true).beyond}
 
 ${callerFunctionsSql(ctx, custom, root, levelReach, true).guard}
 ` : ""}
+-- null when an allow entry is a declared permission inside the ceiling of the scope${leveled ? ", at a level the resource declares" : ""}; else unknown-permission, outside-ceiling${leveled ? " or unknown-level" : ""}
+create or replace function ${problem}(p_scope text, p_entry text)
+returns text
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  v_key text := ${current(leveled ? "split_part(p_entry, '@', 1)" : "p_entry")};
+begin
+  if p_entry is null or not (v_key = any(${known})) then
+    return 'unknown-permission';
+  end if;
+  if not exists (
+    select 1 from ${ceiling} c
+    where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
+  ) then
+    return 'outside-ceiling';
+  end if;${leveled ? `
+  if strpos(p_entry, '@') > 0 and not exists (
+    select 1 from ${ceiling} c
+    where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
+      and split_part(c.grant_key, '@', 2) = split_part(p_entry, '@', 2)
+  ) then
+    return 'unknown-level';
+  end if;` : ""}
+  return null;
+end;
+$$;
+revoke execute on function ${problem}(text, text) from public, anon, authenticated;
+
 -- the entries of a definition: declared keys and levels inside the ceiling of the scope, and declared includes
 create or replace function ${entries}(p_scope text, p_allow text[], p_deny text[], p_include text[])
 returns void
@@ -2161,23 +2394,18 @@ as $$
 declare
   v_entry text;
   v_key text;
+  v_problem text;
 begin
   foreach v_entry in array coalesce(p_allow, '{}'::text[]) loop
     v_key := ${current(leveled ? "split_part(v_entry, '@', 1)" : "v_entry")};
-    if not (v_key = any(${known})) then
+    v_problem := ${problem}(p_scope, v_entry);
+    if v_problem = 'unknown-permission' then
 ${raiseSql("      ", "22023", `'permdock: ' || v_entry || ' is not a declared permission'`, "unknown-permission")}
     end if;
-    if not exists (
-      select 1 from ${ceiling} c
-      where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
-    ) then
+    if v_problem = 'outside-ceiling' then
 ${raiseSql("      ", "22023", `'permdock: ' || v_key || ' is outside the ceiling of ' || p_scope`, "outside-ceiling")}
     end if;${leveled ? `
-    if strpos(v_entry, '@') > 0 and not exists (
-      select 1 from ${ceiling} c
-      where c.scope = p_scope and c.effect = 'allow' and ${current("c.permission")} = v_key
-        and split_part(c.grant_key, '@', 2) = split_part(v_entry, '@', 2)
-    ) then
+    if v_problem = 'unknown-level' then
 ${raiseSql("      ", "22023", `'permdock: ' || v_entry || ' names a level the resource does not declare'`, "unknown-level")}
     end if;` : ""}
   end loop;
@@ -2438,17 +2666,103 @@ ${functionBody(memberRowsBody(ctx, scope, type, "p_user", memberForSources(ctx,
 revoke execute on function ${fn}(uuid) from public, anon, authenticated;`;
 }
 //#endregion
+//#region src/cli/rls/token-scopes.ts
+const TOKEN_SCOPE_ALLOWS = "permdock_token_scope_allows";
+/** `rls.tokenScopes` as the SQL generator needs it, or `undefined` when it is off. */
+function tokenScopesPlan(setting, policy) {
+	if (setting !== true) return;
+	const permissions = listPermissions(policy.permissions).map((leaf) => ({
+		key: leaf.key,
+		scope: leaf.scope,
+		renamedFrom: formerKeys(leaf)
+	}));
+	return { scopes: delegatedScopeMap(permissions, policy.oauthScopes) };
+}
+function tokenScopeAllowsCall(ctx, grant) {
+	return `${qualified(ctx, TOKEN_SCOPE_ALLOWS)}(${grant})`;
+}
+/** The token's scopes as rows of `s(scope)`: a space-separated string or, outside `guc`, a JSON array. */
+function tokenScopeRows(ctx) {
+	if (ctx.dialect === "guc") return `regexp_split_to_table(btrim(coalesce(${subjectClaimSql(ctx, "scope")}, '')), '\\s+') s(scope)`;
+	const scope = subjectClaimJsonSql(ctx, "scope");
+	return `unnest(case jsonb_typeof(${scope})
+      when 'string' then regexp_split_to_array(btrim(${scope} #>> '{}'), '\\s+')
+      when 'array' then array(select jsonb_array_elements_text(${scope}))
+      else '{}'::text[]
+    end) s(scope)`;
+}
+/**
+* `permdock_token_scope_allows(p_grant)`: a delegated token (a `client_id`, or
+* an `act` that is not a support or impersonation session) reaches a grant key
+* only when one of its scopes maps to the key's permission. better-supabase's
+* `cap_allows` reads the same tokens the same way.
+*/
+function tokenScopeAllowsSql(ctx, plan, anonExecute) {
+	const fn = qualified(ctx, TOKEN_SCOPE_ALLOWS);
+	const act = subjectClaimJsonSql(ctx, "act");
+	const grants = anonExecute ? `revoke execute on function ${fn}(text) from public;
+grant execute on function ${fn}(text) to anon, authenticated;` : `revoke execute on function ${fn}(text) from public, anon;
+grant execute on function ${fn}(text) to authenticated;`;
+	return `-- Token scopes: a delegated token holds only the permissions its scope claim maps to; denies always apply, and a token without client_id or an agent act is not limited
+create or replace function ${fn}(p_grant text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select case
+    when coalesce(${subjectClaimSql(ctx, "client_id")}, '') = ''
+      and (${act} is null
+        or ${act} = 'null'::jsonb
+        or (jsonb_typeof(${act}) = 'object'
+          and ${act} ->> 'kind' in ('support', 'impersonation'))) then true
+    when exists (
+      select 1 from ${qualified(ctx, "role_permissions")} rp
+      where rp.grant_key = p_grant and rp.effect = 'deny'
+    ) then true
+    else exists (
+      select 1
+      from ${tokenScopeRows(ctx)}
+      where s.scope <> ''
+        and coalesce(${quoteLiteral(JSON.stringify(plan.scopes))}::jsonb -> s.scope, '[]'::jsonb)
+          ? split_part(split_part(p_grant, '#', 1), '@', 1)
+    )
+  end
+$$;
+${grants}`;
+}
+//#endregion
 //#region src/cli/rls/helpers.ts
 /**
 * The policy-side call for a grant key. Every form is uncorrelated, so
 * Postgres runs the helper once per statement (an InitPlan, or a hashed
 * SubPlan for `in`), never once per row.
 */
-function accessSql(ctx, scope, grantKey, column) {
+function accessSql(ctx, scope, grantKey, column, helper) {
 	const key = quoteLiteral(grantKey);
 	if (scope === "global") return `(select ${qualified(ctx, HELPERS.has)}(${key}))`;
 	if (column === void 0) throw configError(`PermDock CLI: ${scope}-scoped grant needs definePolicy({ scopes.${scope} })`);
-	return `${quoteIdent(column)} in (select ${qualified(ctx, permittedIdsHelper(scope))}(${key}))`;
+	return `${quoteIdent(column)} in (select ${qualified(ctx, helper ?? permittedIdsHelper(scope))}(${key}))`;
+}
+/**
+* `permitted_<parent>_ids(p_grant)` for each \`rls.tables\` \`via\`: the parent
+* rows whose scope instance the grant reaches. \`security definer\`, so the
+* caller needs no read on the parent, and called uncorrelated like
+* \`permitted_<scope>_ids\`.
+*/
+function viaHelpersSql(ctx, anonExecute) {
+	const done = /* @__PURE__ */ new Set();
+	const chunks = [];
+	for (const via of Object.values(ctx.vias ?? {})) {
+		if (done.has(via.helper)) continue;
+		done.add(via.helper);
+		chunks.push(`-- rows of ${via.table} whose ${via.column} is a ${via.scope} the grant reaches
+${helperFunction(ctx, via.helper, `setof ${via.type}`, sqlBody(`  select p.${quoteIdent(via.id)}
+  from ${quoteQualified(via.table)} p
+  where p.${quoteIdent(via.column)} in (select ${qualified(ctx, permittedIdsHelper(via.scope))}(p_grant))`), anonExecute)}`);
+	}
+	return chunks;
 }
 function userIdSql(ctx, anonExecute) {
 	const fn = userIdHelperSql(ctx);
@@ -2536,6 +2850,40 @@ ${rows.map((row) => `  (${[
 );`;
 }
 /**
+* `role_permissions` as a view over the compiled rows (`rls.seeds: 'view'`).
+* `security_invoker` makes the view read as its caller, so it adds no
+* privilege; the table's revoke applies to the view the same way.
+*/
+function seedViewSql(ctx, rows) {
+	const view = qualified(ctx, "role_permissions");
+	const columns = "role, permission, grant_key, scope, effect";
+	return `-- rls.seeds: 'view': role_permissions is a view, so the rows travel with the schema
+create or replace view ${view} (${columns}) with (security_invoker = true) as
+${rows.length === 0 ? `select null::text, null::text, null::text, null::text, null::text where false` : `select * from (values\n${rows.map((row) => `  (${[
+		row.role,
+		row.permission,
+		row.grantKey,
+		row.scope,
+		row.effect
+	].map(quoteLiteral).join(", ")})`).join(",\n")}\n) as v(${columns})`};
+revoke all on table ${view} from anon, authenticated, public;`;
+}
+/** `<schema>.seed()`: the same upsert and delete as `seedSql`, for a declarative schema that carries no rows. */
+function seedFunctionSql(ctx, rows) {
+	const fn = qualified(ctx, "seed");
+	return `-- rls.seeds: 'function': the role_permissions rows are data, so a declarative diff leaves them out; run select ${fn}(); after each deploy
+create or replace function ${fn}()
+returns void
+language sql
+volatile
+security definer
+set search_path = ''
+as $permdock$
+${seedSql(ctx, rows)}
+$permdock$;
+revoke execute on function ${fn}() from public, anon, authenticated;`;
+}
+/**
 * `role_permissions`, its seeds, and the three `security definer` helpers
 * with `search_path = ''`. `execute` goes to `authenticated` only.
 */
@@ -2545,9 +2893,13 @@ function helpersSql(ctx, rows, options) {
 	const rp = qualified(ctx, "role_permissions");
 	const chunks = [`-- permdock helpers (${ctx.authorize === "database" ? "database: reads the membership and user_roles tables" : "jwt: reads the role and memberships claims"})
 -- policies call them uncorrelated, so Postgres evaluates each once per statement`];
-	if (schema !== "public") chunks.push(`create schema if not exists ${s};\nrevoke all on schema ${s} from public;\ngrant usage on schema ${s} to ${options.anonExecute === true ? "anon, authenticated" : "authenticated"};`);
+	if (schema !== "public") {
+		const anonUsage = options.anonExecute === true || ctx.capabilities === true;
+		chunks.push(`create schema if not exists ${s};\nrevoke all on schema ${s} from public;\ngrant usage on schema ${s} to ${anonUsage ? "anon, authenticated" : "authenticated"};`);
+	}
 	if (ctx.dialect === "supabase") chunks.push(userIdSql(ctx, options.anonExecute === true));
-	chunks.push(`create table if not exists ${rp} (
+	if (ctx.seeds === "view") chunks.push(seedViewSql(ctx, rows));
+	else chunks.push(`create table if not exists ${rp} (
   role text not null,
   permission text not null,
   grant_key text not null,
@@ -2557,7 +2909,8 @@ function helpersSql(ctx, rows, options) {
 );
 alter table ${rp} enable row level security;
 revoke all on table ${rp} from anon, authenticated, public;`);
-	if (options.withoutSeeds !== true) chunks.push(seedSql(ctx, rows));
+	if (ctx.seeds === "function") chunks.push(seedFunctionSql(ctx, rows));
+	else if (options.withoutSeeds !== true && ctx.seeds !== "view") chunks.push(seedSql(ctx, rows));
 	if (ctx.authorize === "database" && options.userRoles && ctx.roles === void 0) {
 		const ur = qualified(ctx, "user_roles");
 		chunks.push(`create table if not exists ${ur} (
@@ -2573,6 +2926,7 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 	const anon = options.anonExecute === true;
 	const keys = ctx.apiKeys;
 	if (keys !== void 0) chunks.push(apiKeyAllowsSql(ctx, keys, anon));
+	if (ctx.tokenScopes !== void 0) chunks.push(tokenScopeAllowsSql(ctx, ctx.tokenScopes, anon));
 	const bodies = grantBodies(ctx);
 	chunks.push(helperFunction(ctx, HELPERS.has, "boolean", bodies.has, anon));
 	const capabilities = capabilitiesSql(ctx);
@@ -2584,6 +2938,7 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 		if (ctx.roleMemberScopes?.includes(scope.name) === true) chunks.push(memberRolesFunction(ctx, scope.name, type, anon));
 		if (hasMemberFor(ctx, scope.name)) chunks.push(memberForFunction(ctx, scope.name, type));
 	}
+	chunks.push(...viaHelpersSql(ctx, anon));
 	const forUser = forUserSql(ctx);
 	if (forUser !== "") chunks.push(forUser);
 	const writes = customRoleWritesSql(ctx, options.levelReach ?? []);
@@ -2591,6 +2946,12 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 		chunks.push(writes);
 		const cascade = customRoleCascadeSql(ctx);
 		if (cascade !== "") chunks.push(cascade);
+		const sync = ctx.customRoles?.sync;
+		if (sync !== void 0) chunks.push(sync);
+		const byId = customRoleByIdSql(ctx, options.trustedReaders);
+		if (byId !== "") chunks.push(byId);
+		const nameGuard = customRoleNameGuardSql(ctx);
+		if (nameGuard !== "") chunks.push(nameGuard);
 	}
 	const globalRoles = globalRolesSql(ctx);
 	if (globalRoles !== "") chunks.push(globalRoles);
@@ -2600,20 +2961,26 @@ revoke all on table ${ur} from anon, authenticated, public;`);
 }
 function grantBodies(ctx) {
 	const keys = ctx.apiKeys;
+	const scoped = ctx.tokenScopes !== void 0;
 	const set = ctx.grantSet === true;
-	const allows = apiKeyAllowsCall(ctx, set ? "ids.grant_key" : "p_grant");
-	const keyTenant = keyTenantSql(ctx, void 0) ?? "true";
+	const ceiling = (grant) => {
+		const calls = [...keys === void 0 ? [] : [apiKeyAllowsCall(ctx, grant)], ...scoped ? [tokenScopeAllowsCall(ctx, grant)] : []];
+		return calls.length === 0 ? void 0 : calls.join(" and ");
+	};
+	const allows = ceiling(set ? "ids.grant_key" : "p_grant");
+	const keyTenant = keys === void 0 ? "" : ` and ${keyTenantSql(ctx, void 0) ?? "true"}`;
+	const hasAllows = ceiling(set ? "g.grant_key" : "p_grant");
 	return {
-		has: sqlBody(keys === void 0 ? hasBody(ctx) : set ? `  select g.grant_key
+		has: sqlBody(hasAllows === void 0 ? hasBody(ctx) : set ? `  select g.grant_key
   from (
 ${hasBody(ctx)}
   ) g(grant_key)
-  where ${apiKeyAllowsCall(ctx, "g.grant_key")} and ${keyTenant}` : ceilingHasSql(hasBody(ctx), `${allows} and ${keyTenant}`)),
+  where ${hasAllows}${keyTenant}` : ceilingHasSql(hasBody(ctx), `${hasAllows}${keyTenant}`)),
 		ids: (scope) => {
 			const type = scopeTypeOf(ctx, scope);
 			const body = scopedBody(ctx, scope, type);
-			if (keys === void 0) return body;
-			const sql = scope === rootName(ctx) ? `${body.sql}\n  union\n${serviceKeyIdsSql(ctx, keys, scope, type)}` : body.sql;
+			if (allows === void 0) return body;
+			const sql = keys !== void 0 && scope === rootName(ctx) ? `${body.sql}\n  union\n${serviceKeyIdsSql(ctx, keys, scope, type)}` : body.sql;
 			return {
 				sql: set ? `  select ids.id, ids.grant_key
   from (
@@ -2626,7 +2993,7 @@ ${sql}
 	};
 }
 function forUserContext(ctx) {
-	const { apiKeys: _apiKeys, ...unkeyed } = ctx;
+	const { apiKeys: _apiKeys, tokenScopes: _tokenScopes, ...unkeyed } = ctx;
 	return {
 		...unkeyed,
 		subjectId: "p_user",
@@ -3649,6 +4016,42 @@ function ownershipRules(policy, scopes) {
 	};
 }
 /**
+* The roles whose `for` lists kinds that no membership source of the role's
+* scope can hold: such a role resolves to no one. A `via` read from a column
+* can hold any kind, and so does a source with no `via` (it is not
+* compared) and a scope with no table or source.
+*/
+function unsatisfiedKinds(ctx, policy) {
+	const out = [];
+	for (const [role, kinds] of Object.entries(ctx.ownership?.kinds ?? {})) {
+		const scope = roleScope(policy, ctx.scopes, role);
+		if (scope === void 0) continue;
+		const held = [];
+		const mapped = scopeTable(ctx, scope)?.table;
+		if (mapped !== void 0) {
+			const via = memberVia(mapped);
+			held.push({
+				label: mapped.table,
+				via: typeof via === "string" ? void 0 : via.value ?? void 0
+			});
+		} else for (const source of ctx.memberSources ?? ctx.sources ?? []) {
+			if (source.sql.scope !== void 0 && source.sql.scope !== scope) continue;
+			const via = source.sql.manifest.via;
+			held.push({
+				label: source.sql.table,
+				via: via === void 0 ? void 0 : "value" in via && typeof via.value === "string" ? via.value : void 0
+			});
+		}
+		if (held.length === 0 || held.some((entry) => entry.via === void 0 || kinds.includes(entry.via ?? ""))) continue;
+		out.push({
+			role,
+			for: kinds,
+			sources: held.map((entry) => `${entry.label} (via ${entry.via ?? ""})`)
+		});
+	}
+	return out;
+}
+/**
 * The ownership objects: holder-count and transfer-only triggers on each
 * scope's membership table, and `permdock_can_assign` for the application's
 * own policies on those tables. Empty when no role declares a rule.
@@ -3694,4 +4097,4 @@ function ownershipSql(ctx) {
 	return chunks.length === 0 ? "" : `${chunks.join("\n\n")}\n`;
 }
 //#endregion
-export { activeUserSql as $, collectGrants as A, hasPermittedUsers as B, byKey as C, apiKeysPlan as D, apiKeyFields as E, CLOSURE as F, memberIdsHelper as G, memberForHelper as H, graphHelper as I, permittedIdsHelper as J, memberRoleOf as K, graphSqlName as L, compileConditionSql as M, contextRefs as N, breakGlassHolder as O, sqlFunctionNames as P, activeRowSql as Q, graphSqlText as R, byCodeUnit as S, apiKeyAllowsCall as T, memberForSources as U, linkHelper as V, memberForTable as W, scopeSources as X, restrictedHelper as Y, scopeTable as Z, capabilityAccessSql as _, guardedTables as a, currentKeyExpr as b, PERMISSION_HELPERS as c, permissionKeysForHelper as d, checkSuspension as et, permittedByPermissionHelper as f, seedSql as g, helpersSql as h, assignmentSql as i, roleNames as j, breakGlassKey as k, checkName as l, accessSql as m, ownershipSql as n, ASSIGNMENTS as o, requiresSql as p, permittedForHelper as q, holderSources as r, OWNERSHIP as s, ownershipRules as t, permissionHelpersSql as u, globalRoleRows as v, API_KEY_ALLOWS as w, rolesTableScope as x, globalRoleSource as y, hasMemberFor as z };
+export { permittedForHelper as $, apiKeyFields as A, sqlFunctionNames as B, globalRoleSource as C, byKey as D, byCodeUnit as E, collectGrants as F, hasMemberFor as G, graphHelper as H, roleNames as I, memberForHelper as J, hasPermittedUsers as K, andConditions as L, assignableRoles as M, breakGlassHolder as N, API_KEY_ALLOWS as O, breakGlassKey as P, memberRoleOf as Q, compileConditionSql as R, globalRoleRows as S, rolesTableScope as T, graphSqlName as U, CLOSURE as V, graphSqlText as W, memberForTable as X, memberForSources as Y, memberIdsHelper as Z, seedSql as _, assignmentSql as a, activeUserSql as at, tokenScopesPlan as b, OWNERSHIP as c, permissionHelpersSql as d, permittedIdsHelper as et, permissionKeysForHelper as f, helpersSql as g, accessSql as h, holderSources as i, activeRowSql as it, apiKeysPlan as j, apiKeyAllowsCall as k, PERMISSION_HELPERS as l, requiresSql as m, ownershipSql as n, scopeSources as nt, guardedTables as o, checkSuspension as ot, permittedByPermissionHelper as p, linkHelper as q, unsatisfiedKinds as r, scopeTable as rt, ASSIGNMENTS as s, ownershipRules as t, restrictedHelper as tt, checkName as u, TOKEN_SCOPE_ALLOWS as v, currentKeyExpr as w, capabilityAccessSql as x, tokenScopeAllowsCall as y, contextRefs as z };