@sunboyoo/supabase-rbac 1.0.2

package/migrations/20251229000003_create_rbac_functions_and_hook.sql

@@ -0,0 +1,246 @@
+/* =================================================================================================
+ENGLISH COMMENT BLOCK (Architecture + Ops + Frontend Guidance)
+====================================================================================================
+
+FILE PURPOSE
+- Creates two critical functions:
+  1) hooks.custom_access_token_hook(event jsonb)
+     - Runs during login / token refresh.
+     - Injects per-app role_ids (UUID arrays) into JWT claims at:
+       claims.app_metadata.role_ids
+     - This keeps JWT small and stable (UUID-based; role renames safe).
+
+  2) rbac.has_perm(target_app_id text, required_perm_name text)
+     - RLS-friendly authorization primitive.
+     - Implements Global-Mirror semantics:
+       Path A: target app roles ↔ target app permission_id
+       Path B: global roles     ↔ global permission_id (same name mirror)
+     - Uses transaction-local GUC cache (set_config/current_setting) to mitigate N+1.
+
+WHY THIS IS PRODUCTION-READY
+- JWT stores role_ids UUID (not names): rename-safe and join-free checks.
+- Deterministic and safe GUC keys via md5 (no illegal characters).
+- Sentinel UUID caches "permission not found" to avoid repeated lookups.
+- Defensive parsing: never 500 due to malformed claims; fail-closed to deny access.
+
+FRONTEND / OPS GUIDANCE (Must-read)
+- Role assignment changes require JWT refresh:
+  supabase.auth.refreshSession()
+- Hook must be wired in Dashboard:
+  Auth → Hooks → Custom access token hook → hooks.custom_access_token_hook
+- Do not call has_perm directly from clients. Use RLS on business tables and handle 401/403.
+- Permission naming: use stable lowercase dotted strings (order.read, payroll.export).
+
+==================================================================================================== */
+
+
+/* =================================================================================================
+中文注释区块（架构 + 运维 + 前端指引）
+====================================================================================================
+
+文件目的
+- 创建两个关键函数：
+  1) hooks.custom_access_token_hook(event jsonb)
+     - 在登录/刷新 token 时执行
+     - 向 JWT 注入各 App 的 role_ids（UUID 数组），路径：
+       claims.app_metadata.role_ids
+     - JWT 只携带 role_ids，体积小、重命名不失效。
+
+  2) rbac.has_perm(target_app_id, required_perm_name)
+     - 给 RLS Policy 调用的核心鉴权原语
+     - 实现 Global-Mirror：
+       路径A：target_app 角色 ↔ target_app 权限
+       路径B：global 角色     ↔ global 同名镜像权限
+     - 事务级 GUC 缓存避免 RLS 扫描多行时的 N+1 查询。
+
+为何可生产
+- JWT 存 UUID（不存 name）：重命名安全、判定无 join、性能极强
+- md5 生成 GUC key：保证变量名合法，防特殊字符引发错误
+- 哨兵 UUID 缓存“不存在权限”：避免重复查 permissions 表
+- 防御性解析：token claims 异常也不会 500，默认拒绝（fail-closed）
+
+前端/运维必读
+- 用户角色变更后必须刷新 JWT：
+  supabase.auth.refreshSession()
+- 必须在 Dashboard 绑定 Hook：
+  Auth → Hooks → Custom access token hook → hooks.custom_access_token_hook
+- 不建议前端直接调用 has_perm；让 RLS 拦截并处理 401/403
+- 权限名建议：全小写 + 点号分层（order.read, payroll.export）
+
+==================================================================================================== */
+
+
+-- Functions:
+-- 1) hooks.custom_access_token_hook: inject role_ids into JWT claims (per app_id)
+-- 2) rbac.has_perm: RLS-friendly permission check using:
+--    - Role IDs from JWT (UUID)
+--    - Permission ID pre-resolution (with sentinel caching)
+--    - Transaction-local caching using set_config/current_setting
+
+create or replace function hooks.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+set search_path = ''
+as $$
+declare
+  uid uuid;
+  role_id_map jsonb;
+begin
+  -- Defensive: malformed user_id should not break auth flow
+  begin
+    uid := (event ->> 'user_id')::uuid;
+  exception when others then
+    return event;
+  end;
+
+  -- Inject per-app role UUID arrays:
+  -- { "app1": ["uuid..."], "global": ["uuid..."] }
+  select jsonb_object_agg(app_id, role_ids)
+    into role_id_map
+  from (
+    select
+      r.app_id,
+      jsonb_agg(distinct r.id order by r.id) as role_ids
+    from rbac.roles r
+    join rbac.user_roles ur on ur.role_id = r.id
+    where ur.user_id = uid
+    group by r.app_id
+  ) t;
+
+  return jsonb_set(
+    event,
+    '{claims,app_metadata,role_ids}',
+    coalesce(role_id_map, '{}'::jsonb),
+    true
+  );
+end;
+$$;
+
+
+create or replace function rbac.has_perm(target_app_id text, required_perm_name text)
+returns boolean
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  _res_key     text := 'rbac.res.' || md5(coalesce(target_app_id,'') || '|' || coalesce(required_perm_name,''));
+  _t_roles_key text := 'rbac.rids.' || md5('t|' || coalesce(target_app_id,''));
+  _g_roles_key text := 'rbac.rids.' || md5('g|global');
+  _t_pid_key   text := 'rbac.pid.'  || md5('t|' || coalesce(target_app_id,'') || '|' || coalesce(required_perm_name,''));
+  _g_pid_key   text := 'rbac.pid.'  || md5('g|global|' || coalesce(required_perm_name,''));
+
+  _target_role_ids uuid[];
+  _global_role_ids uuid[];
+
+  _target_pid uuid;
+  _global_pid uuid;
+
+  _sentinel constant uuid := '00000000-0000-0000-0000-000000000000'::uuid;
+  _granted  boolean := false;
+
+  _jwt jsonb;
+begin
+  -- Level 1: final decision cache
+  if current_setting(_res_key, true) is not null then
+    return current_setting(_res_key) = 'true';
+  end if;
+
+  _jwt := auth.jwt();
+
+  -- Level 2: cache role_ids(uuid[]) for target app (never 500; fail-closed)
+  if current_setting(_t_roles_key, true) is null then
+    begin
+      select coalesce(array_agg((x.value)::uuid), '{}'::uuid[])
+        into _target_role_ids
+      from jsonb_array_elements_text(
+        coalesce(_jwt #> array['app_metadata','role_ids', target_app_id], '[]'::jsonb)
+      ) as x(value);
+    exception when others then
+      _target_role_ids := '{}'::uuid[];
+    end;
+    perform set_config(_t_roles_key, _target_role_ids::text, true);
+  else
+    begin
+      _target_role_ids := current_setting(_t_roles_key)::uuid[];
+    exception when others then
+      _target_role_ids := '{}'::uuid[];
+    end;
+  end if;
+
+  -- Level 2b: cache role_ids(uuid[]) for global
+  if current_setting(_g_roles_key, true) is null then
+    begin
+      select coalesce(array_agg((x.value)::uuid), '{}'::uuid[])
+        into _global_role_ids
+      from jsonb_array_elements_text(
+        coalesce(_jwt #> array['app_metadata','role_ids','global'], '[]'::jsonb)
+      ) as x(value);
+    exception when others then
+      _global_role_ids := '{}'::uuid[];
+    end;
+    perform set_config(_g_roles_key, _global_role_ids::text, true);
+  else
+    begin
+      _global_role_ids := current_setting(_g_roles_key)::uuid[];
+    exception when others then
+      _global_role_ids := '{}'::uuid[];
+    end;
+  end if;
+
+  -- Level 3: permission_id cache for target app (sentinel if not found)
+  if current_setting(_t_pid_key, true) is null then
+    select p.id
+      into _target_pid
+    from rbac.permissions p
+    where p.app_id = target_app_id
+      and p.name   = required_perm_name;
+
+    _target_pid := coalesce(_target_pid, _sentinel);
+    perform set_config(_t_pid_key, _target_pid::text, true);
+  else
+    _target_pid := current_setting(_t_pid_key)::uuid;
+  end if;
+
+  -- Level 3b: permission_id cache for global mirror (sentinel if not found)
+  if current_setting(_g_pid_key, true) is null then
+    select p.id
+      into _global_pid
+    from rbac.permissions p
+    where p.app_id = 'global'
+      and p.name   = required_perm_name;
+
+    _global_pid := coalesce(_global_pid, _sentinel);
+    perform set_config(_g_pid_key, _global_pid::text, true);
+  else
+    _global_pid := current_setting(_g_pid_key)::uuid;
+  end if;
+
+  -- Path A: target roles ↔ target permission
+  if _target_pid <> _sentinel and cardinality(_target_role_ids) > 0 then
+    select exists (
+      select 1
+      from rbac.role_permissions rp
+      where rp.app_id        = target_app_id
+        and rp.permission_id = _target_pid
+        and rp.role_id       = any(_target_role_ids)
+    ) into _granted;
+  end if;
+
+  -- Path B: global roles ↔ global mirrored permission
+  if not _granted and _global_pid <> _sentinel and cardinality(_global_role_ids) > 0 then
+    select exists (
+      select 1
+      from rbac.role_permissions rp
+      where rp.app_id        = 'global'
+        and rp.permission_id = _global_pid
+        and rp.role_id       = any(_global_role_ids)
+    ) into _granted;
+  end if;
+
+  perform set_config(_res_key, _granted::text, true);
+  return _granted;
+end;
+$$;

package/migrations/20251229000004_setup_rbac_grants_and_hardening.sql

@@ -0,0 +1,97 @@
+/* =================================================================================================
+ENGLISH COMMENT BLOCK (Architecture + Ops + Frontend Guidance)
+====================================================================================================
+
+FILE PURPOSE
+- Applies security hardening (GRANT/REVOKE) to minimize PostgREST exposure:
+  - RBAC tables/views/functions are not readable by public/anon/authenticated.
+  - service_role gets RBAC management privileges (admin backend).
+  - supabase_auth_admin gets minimum read + hook execution rights.
+  - authenticated/anon get schema USAGE + has_perm EXECUTE to allow RLS evaluation.
+
+WHY THIS MATTERS
+- Schema isolation + REVOKE/GRANT is the most reliable long-term defense against:
+  - permission dictionary enumeration
+  - accidental API exposure
+  - policy drift / FORCE RLS operational hazards on RBAC base tables
+
+IMPORTANT: Schema USAGE for RLS
+- Even if has_perm is SECURITY DEFINER, some environments require caller USAGE on schema rbac
+  during RLS evaluation. We grant USAGE on schema rbac to authenticated/anon.
+- This does NOT expose tables because SELECT remains revoked.
+
+DEPLOYMENT CHECKLIST
+- Also remove rbac/hooks from Supabase Dashboard → API → Exposed Schemas.
+- Wire the Auth hook in Dashboard:
+  Auth → Hooks → Custom access token hook → hooks.custom_access_token_hook
+
+==================================================================================================== */
+
+
+/* =================================================================================================
+中文注释区块（架构 + 运维 + 前端指引）
+====================================================================================================
+
+文件目的
+- 统一执行安全硬化（GRANT/REVOKE），最小化 PostgREST 暴露面：
+  - public/anon/authenticated 不能读 RBAC 表/视图/函数
+  - service_role 具备 RBAC 管理权限（后台管理端）
+  - supabase_auth_admin 具备最小读取权限（roles/user_roles）+ Hook 执行权限
+  - authenticated/anon 具备 schema USAGE + has_perm EXECUTE，保证 RLS 可正常评估
+
+为何关键
+- Schema 隔离 + 授权收紧是长期最稳的防线：
+  - 防止权限字典被枚举
+  - 防止 API 误暴露
+  - 避免在 RBAC 表上启用/漂移 RLS 带来的运维灾难
+
+重要：RLS 执行需要 schema USAGE
+- 即使 has_perm 是 SECURITY DEFINER，有些环境下 RLS 评估仍要求调用者对 rbac schema 有 USAGE。
+- 因此授予 authenticated/anon 对 rbac 的 USAGE。
+- 这不会暴露 RBAC 表，因为 SELECT 仍然被 revoke。
+
+部署清单
+- Supabase Dashboard → API → Exposed Schemas 中移除 rbac/hooks
+- Dashboard → Auth → Hooks 绑定 custom access token hook
+
+==================================================================================================== */
+
+
+-- Security hardening:
+-- - lock down RBAC tables from PostgREST (public/anon/authenticated)
+-- - allow auth hook runner to read minimal RBAC tables
+-- - allow authenticated/anon to evaluate RLS via schema USAGE + function EXECUTE
+
+-- rbac schema/table lockdown
+revoke all on all tables    in schema rbac from public;
+revoke all on all sequences in schema rbac from public;
+revoke all on all functions in schema rbac from public;
+
+revoke all on all tables    in schema rbac from anon, authenticated;
+revoke all on all sequences in schema rbac from anon, authenticated;
+revoke all on all functions in schema rbac from anon, authenticated;
+
+-- service_role: RBAC management (admin backend)
+grant usage on schema rbac to service_role;
+grant select, insert, update, delete on all tables in schema rbac to service_role;
+
+-- auth hook runner: minimal reads
+grant usage on schema rbac to supabase_auth_admin;
+grant select on rbac.roles, rbac.user_roles to supabase_auth_admin;
+
+-- IMPORTANT: schema USAGE for RLS evaluation (does NOT expose tables)
+grant usage on schema rbac to authenticated, anon;
+
+-- hooks schema hardening + hook execute only for auth service
+revoke all on schema hooks from public;
+revoke all on schema hooks from anon, authenticated;
+
+revoke all on function hooks.custom_access_token_hook(jsonb) from public;
+revoke all on function hooks.custom_access_token_hook(jsonb) from anon, authenticated;
+
+grant usage on schema hooks to supabase_auth_admin;
+grant execute on function hooks.custom_access_token_hook(jsonb) to supabase_auth_admin;
+
+-- Allow RLS to call has_perm (function execute only; RBAC tables still hidden)
+grant execute on function rbac.has_perm(text, text) to authenticated;
+grant execute on function rbac.has_perm(text, text) to anon;

package/migrations/20251229000005_setup_example_app1_orders_rls.sql

@@ -0,0 +1,102 @@
+/* =================================================================================================
+ENGLISH COMMENT BLOCK (Architecture + Ops + Frontend Guidance)
+====================================================================================================
+
+FILE PURPOSE
+- Example business table (app1-private) + RLS policies demonstrating how to use rbac.has_perm().
+- This file represents how each app/module should apply RLS on its own private tables.
+
+HOW TO USE THIS PATTERN (Recommended)
+- For each app module:
+  - Create its private tables (no need to add app_id column if the table is truly app-private).
+  - Enable RLS.
+  - Write policies that call:
+    (select rbac.has_perm('<app_id>', '<permission_name>'))
+
+WHY WRAP WITH (SELECT ...)
+- Encourages PostgreSQL optimizer to evaluate the function once per statement (InitPlan best-effort).
+- Even if the optimizer does not fully InitPlan it, has_perm has transaction-local caching to prevent
+  N+1 RBAC lookups.
+
+FRONTEND BEHAVIOR
+- Client does normal CRUD calls. If permission is missing:
+  - SELECT returns 0 rows or 403 depending on query/path.
+  - INSERT/UPDATE/DELETE returns 403.
+- After admin changes roles/permissions:
+  - user must refresh JWT: supabase.auth.refreshSession()
+
+==================================================================================================== */
+
+
+/* =================================================================================================
+中文注释区块（架构 + 运维 + 前端指引）
+====================================================================================================
+
+文件目的
+- 示例业务表（app1 私有）及 RLS 策略，演示如何调用 rbac.has_perm()。
+- 真实项目中建议每个 App/模块的业务表和策略独立迁移文件维护。
+
+推荐用法
+- 每个 App：
+  - 建立自己的私有业务表（如果确实是 app-private 表，不需要 app_id 字段）。
+  - 开启 RLS。
+  - 策略中调用：
+    (select rbac.has_perm('<app_id>', '<permission_name>'))
+
+为什么用 (SELECT ...) 包裹
+- 诱导优化器把函数当作 InitPlan（尽力做到一次计算）。
+- 即使没有完全 InitPlan，has_perm 内部也有事务级缓存，能避免 N+1 权限查询。
+
+前端表现
+- 前端正常 CRUD。无权限时：
+  - SELECT 可能返回 0 行或 403（取决于接口路径/查询方式）
+  - INSERT/UPDATE/DELETE 返回 403
+- 管理端改完角色/权限后：
+  - 用户需刷新 JWT：supabase.auth.refreshSession()
+
+==================================================================================================== */
+
+
+-- Example business table (app1-private) and RLS policies.
+-- In real projects, you usually create one migration per module/table group.
+
+create table if not exists public.orders (
+  id           uuid primary key default gen_random_uuid(),
+  created_at   timestamptz not null default now(),
+  customer     text,
+  amount_cents int not null default 0
+);
+
+alter table public.orders enable row level security;
+
+drop policy if exists app1_order_select on public.orders;
+create policy app1_order_select
+on public.orders
+for select
+using (
+  (select rbac.has_perm('app1', 'order.read'))
+);
+
+drop policy if exists app1_order_insert on public.orders;
+create policy app1_order_insert
+on public.orders
+for insert
+with check (
+  (select rbac.has_perm('app1', 'order.create'))
+);
+
+drop policy if exists app1_order_update on public.orders;
+create policy app1_order_update
+on public.orders
+for update
+using (
+  (select rbac.has_perm('app1', 'order.update'))
+);
+
+drop policy if exists app1_order_delete on public.orders;
+create policy app1_order_delete
+on public.orders
+for delete
+using (
+  (select rbac.has_perm('app1', 'order.delete'))
+);

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@sunboyoo/supabase-rbac",
+  "version": "1.0.2",
+  "description": "Industrial-grade RBAC helper for Supabase multi-app projects (JWT role_ids + optional permission RPC + React hooks + pg manager + CLI).",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sunboyoo/supabase-rbac.git"
+  },
+  "homepage": "https://github.com/sunboyoo/supabase-rbac#readme",
+  "bugs": {
+    "url": "https://github.com/sunboyoo/supabase-rbac/issues"
+  },
+  "keywords": [
+    "supabase",
+    "rbac",
+    "postgres",
+    "rls",
+    "auth",
+    "permissions",
+    "roles",
+    "react"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "import": "./dist/shared.js",
+      "require": "./dist/shared.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "require": "./dist/client.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "bin",
+    "migrations",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "rbac-init": "./bin/rbac-init.js"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts src/shared.ts src/client.tsx src/server.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint .",
+    "prepublishOnly": "pnpm test:run && pnpm build"
+  },
+  "dependencies": {
+    "jose": "^5.0.0",
+    "pg": "^8.11.0"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": "^2.0.0",
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@testing-library/react": "^14.3.1",
+    "@types/pg": "^8.11.0",
+    "@types/react": "^18.0.0",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "jsdom": "^24.1.3",
+    "tsup": "^8.1.0",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.51.0",
+    "vitest": "^2.1.9"
+  },
+  "packageManager": "pnpm@10.27.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}