@sunboyoo/supabase-rbac 1.0.3 → 1.1.0

package/README.md

@@ -86,12 +86,10 @@ npx rbac-init --dest ./supabase/migrations
 npx rbac-init --dry-run
 npx rbac-init --force
 npx rbac-init --verbose
-npx rbac-init --with-examples
 ```
 
 > ✅ **推荐**：默认不覆盖已有文件（避免误伤本地改动）。
 > 如需覆盖，请显式 `--force`。
-> 说明：默认不复制示例迁移（包含 app1 orders 例子）。如需示例，请加 `--with-examples`。
 
 ---
 
@@ -155,6 +153,62 @@ await supabase.auth.refreshSession();
 
 否则用户 token 仍是旧 claims。
 
+### 4) 业务表 RLS 配置示例
+
+在业务表上配置 RLS 策略调用 `rbac.has_perm()`：
+
+```sql
+-- 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'))
+);
+```
+
+**要点：**
+
+* 用 `(select rbac.has_perm(...))` 包裹：诱导 PostgreSQL 优化器做 InitPlan（一次计算）
+* 即使未完全 InitPlan，`has_perm` 内部也有事务级缓存，避免 N+1 查询
+* 客户端正常 CRUD；无权限时：SELECT 返回 0 行，INSERT/UPDATE/DELETE 返回 403
+
 ---
 
 ## 前端集成（React）

package/bin/rbac-init.js

@@ -1,80 +1,99 @@
 #!/usr/bin/env node
 /* ================================================================================================
-EN: rbac-init CLI
-- Safely copy bundled SQL migrations into target supabase/migrations folder.
-中文：rbac-init 命令
-- 将包内 migrations 安全复制到项目的 supabase/migrations
+EN: rbac-init CLI - Copy bundled SQL migrations into target supabase/migrations folder.
+中文：rbac-init 命令 - 将包内 migrations 复制到项目的 supabase/migrations
 ================================================================================================ */
 
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
-import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+const PREFIX = "[rbac-init]";
+
 function parseArgs(argv) {
-  const out = { dest: null, force: false, dryRun: false, verbose: false, withExamples: false };
+  const out = { dest: null, force: false, dryRun: false, verbose: false };
   for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--dest") out.dest = argv[++i] ?? null;
-    else if (a === "--force" || a === "-f") out.force = true;
-    else if (a === "--dry-run") out.dryRun = true;
-    else if (a === "--verbose" || a === "-v") out.verbose = true;
-    else if (a === "--with-examples") out.withExamples = true;
-    else if (a === "--help" || a === "-h") {
-      console.log(`rbac-init
+    const arg = argv[i];
+    switch (arg) {
+      case "--dest":
+        out.dest = argv[++i] ?? null;
+        break;
+      case "--force":
+      case "-f":
+        out.force = true;
+        break;
+      case "--dry-run":
+        out.dryRun = true;
+        break;
+      case "--verbose":
+      case "-v":
+        out.verbose = true;
+        break;
+      case "--help":
+      case "-h":
+        console.log(`rbac-init
 
 Usage:
-  rbac-init [--dest <path>] [--force] [--dry-run] [--verbose] [--with-examples]
+  rbac-init [--dest <path>] [--force] [--dry-run] [--verbose]
 
 Defaults:
   --dest ./supabase/migrations
 
 Options:
-  --force    overwrite if exists and content differs
-  --dry-run  print actions without writing
-  --verbose  print detailed logs
-  --with-examples  include example migrations (off by default)
+  -f, --force    Overwrite existing files if content differs
+  --dry-run      Print actions without writing
+  -v, --verbose  Print detailed logs
 `);
-      process.exit(0);
+        process.exit(0);
     }
   }
   return out;
 }
 
-async function exists(p) {
-  try { await fsp.access(p, fs.constants.F_OK); return true; } catch { return false; }
-}
+const exists = async (p) => {
+  try {
+    await fsp.access(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
 
-async function readText(p) {
-  try { return await fsp.readFile(p, "utf8"); } catch { return null; }
-}
+const readText = async (p) => {
+  try {
+    return await fsp.readFile(p, "utf8");
+  } catch {
+    return null;
+  }
+};
 
 async function main() {
   const args = parseArgs(process.argv);
-  const cwd = process.cwd();
-  const destDir = path.resolve(cwd, args.dest ?? path.join("supabase", "migrations"));
+  const destDir = path.resolve(process.cwd(), args.dest ?? path.join("supabase", "migrations"));
 
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = path.dirname(__filename);
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
   const srcDir = path.resolve(__dirname, "..", "migrations");
 
   if (!(await exists(srcDir))) {
-    console.error(`[rbac-init] migrations folder not found in package: ${srcDir}`);
+    console.error(`${PREFIX} migrations folder not found: ${srcDir}`);
     process.exit(1);
   }
 
   if (!(await exists(destDir))) {
-    if (args.dryRun) console.log(`[dry-run] mkdir -p ${destDir}`);
-    else await fsp.mkdir(destDir, { recursive: true });
+    if (args.dryRun) {
+      console.log(`[dry-run] mkdir -p ${destDir}`);
+    } else {
+      await fsp.mkdir(destDir, { recursive: true });
+    }
   }
 
   const files = (await fsp.readdir(srcDir))
     .filter((f) => f.endsWith(".sql"))
-    .filter((f) => args.withExamples || !/example/i.test(f))
     .sort();
+
   if (files.length === 0) {
-    console.log("[rbac-init] no .sql files found.");
+    console.log(`${PREFIX} no .sql files found.`);
     return;
   }
 
@@ -88,17 +107,17 @@ async function main() {
     const srcText = await readText(src);
     const dstText = dstExists ? await readText(dst) : null;
 
-    const same = dstExists && srcText != null && dstText != null && srcText === dstText;
-
-    if (same) {
+    // Skip if content is identical
+    if (dstExists && srcText === dstText) {
       skipped++;
-      if (args.verbose) console.log(`[rbac-init] skip same: ${file}`);
+      if (args.verbose) console.log(`${PREFIX} skip (same): ${file}`);
       continue;
     }
 
+    // Skip if exists and not forced
     if (dstExists && !args.force) {
       skipped++;
-      console.log(`[rbac-init] skip exists (use --force): ${file}`);
+      console.log(`${PREFIX} skip (use --force): ${file}`);
       continue;
     }
 
@@ -108,15 +127,19 @@ async function main() {
     }
 
     await fsp.copyFile(src, dst);
-    if (dstExists) overwritten++; else copied++;
-    console.log(`[rbac-init] ${dstExists ? "overwrote" : "copied"}: ${file}`);
+    if (dstExists) {
+      overwritten++;
+    } else {
+      copied++;
+    }
+    console.log(`${PREFIX} ${dstExists ? "overwrote" : "copied"}: ${file}`);
   }
 
-  console.log(`[rbac-init] done. copied=${copied}, overwritten=${overwritten}, skipped=${skipped}`);
-  console.log(`[rbac-init] next: run "supabase db push"`);
+  console.log(`${PREFIX} done. copied=${copied}, overwritten=${overwritten}, skipped=${skipped}`);
+  console.log(`${PREFIX} next: run "supabase db push"`);
 }
 
 main().catch((e) => {
-  console.error("[rbac-init] error:", e);
+  console.error(`${PREFIX} error:`, e);
   process.exit(1);
 });

package/migrations/20251229000003_create_rbac_functions_and_hook.sql

@@ -126,11 +126,11 @@ 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,''));
+  _res_key     text := 'rbac.res.h' || md5(coalesce(target_app_id,'') || '|' || coalesce(required_perm_name,''));
+  _t_roles_key text := 'rbac.rids.h' || md5('t|' || coalesce(target_app_id,''));
+  _g_roles_key text := 'rbac.rids.h' || md5('g|global');
+  _t_pid_key   text := 'rbac.pid.h'  || md5('t|' || coalesce(target_app_id,'') || '|' || coalesce(required_perm_name,''));
+  _g_pid_key   text := 'rbac.pid.h'  || md5('g|global|' || coalesce(required_perm_name,''));
 
   _target_role_ids uuid[];
   _global_role_ids uuid[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sunboyoo/supabase-rbac",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "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,
@@ -106,4 +106,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
-}
+}

package/migrations/20251229000005_setup_example_app1_orders_rls.sql

@@ -1,102 +0,0 @@
-/* =================================================================================================
-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'))
-);