@sunboyoo/supabase-rbac 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sunboyoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,404 @@
+# @sunboyoo/supabase-rbac 集成指南（README）
+
+> 工业级、多 App、多模块 RBAC（Supabase + PostgreSQL + TypeScript/React）
+> **数据库 RLS 才是最终权威**；前端仅用于 UI 显隐（可选），避免“前端鉴权等于安全”的误区。
+
+---
+
+## 目录
+
+* [功能概览](#功能概览)
+* [核心设计原则](#核心设计原则)
+* [安装与初始化](#安装与初始化)
+* [Supabase Dashboard 必做配置](#supabase-dashboard-必做配置)
+* [数据库部署与验证](#数据库部署与验证)
+* [前端集成（React）](#前端集成react)
+* [服务端/管理端集成（Node）](#服务端管理端集成node)
+* [可选增强：permission-name 语义化判定](#可选增强permission-name-语义化判定)
+* [最佳实践：权限命名与角色管理](#最佳实践权限命名与角色管理)
+* [常见问题（FAQ）](#常见问题faq)
+* [安全边界与威胁模型](#安全边界与威胁模型)
+* [版本与兼容性](#版本与兼容性)
+
+---
+
+## 功能概览
+
+* ✅ **多应用支持（app_id）**：同一 Supabase 项目支持多个业务 App/模块。
+* ✅ **自动合并 global 角色**：`app1` + `global` 角色集合合并用于判定。
+* ✅ **数据库强制鉴权（RLS）**：策略调用 `rbac.has_perm(app_id, perm_name)`。
+* ✅ **JWT 注入 role_ids（UUID）**：通过 Supabase Auth Custom Access Token Hook 注入。
+* ✅ **React 集成**：`RBACProvider` + `useRBAC()`。
+* ✅ **Server 管理端**：`RBACManager`（pg 直连，不依赖 PostgREST 暴露 rbac schema）。
+* ✅ **CLI 初始化**：`rbac-init` 将 migrations 复制到项目 `supabase/migrations`。
+* 🧩（可选）**permission-name 前端语义化判定**：通过受控 RPC 拉取“我的权限名列表”。
+
+---
+
+## 核心设计原则
+
+### 1) DB 是权威：安全必须由 RLS 强制执行
+
+* 前端的 `hasRole()` / `hasPermission()` **只能用于 UI 显隐或交互优化**。
+* **真正的安全**来自业务表的 RLS：没有权限时数据库返回 403/0 rows。
+
+### 2) RBAC schema 默认不暴露
+
+* 强烈建议：Supabase Dashboard → **API → Exposed Schemas** 中移除 `rbac` / `hooks`。
+* 这样可最大化降低：
+
+  * 权限字典枚举
+  * 意外暴露 RBAC 表
+  * 运维期间策略漂移导致的风险
+
+### 3) role_ids 放 JWT，稳定且 rename-safe
+
+* JWT 中存的是 role UUID，而不是 role name：
+
+  * 角色重命名不会影响鉴权
+  * 不依赖 role name join
+  * token 体积小
+
+---
+
+## 安装与初始化
+
+### 1) 安装
+
+```bash
+pnpm add @sunboyoo/supabase-rbac
+```
+
+### 2) 初始化 migrations（复制 SQL）
+
+在你的项目根目录执行：
+
+```bash
+npx rbac-init
+# 或
+pnpm exec rbac-init
+```
+
+常用参数：
+
+```bash
+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`。
+
+---
+
+## Supabase Dashboard 必做配置
+
+### 1) 移除 Exposed Schemas
+
+路径：**Supabase Dashboard → API → Exposed Schemas**
+
+* ✅ **保留**：`public`（以及你业务需要的 schema）
+* ❌ **移除**：`rbac`、`hooks`
+
+> 这是安全关键点：避免 PostgREST 暴露 RBAC 表/视图。
+
+### 2) 绑定 Custom Access Token Hook
+
+路径：**Dashboard → Auth → Hooks → Custom access token hook**
+
+选择：
+
+* Function：`hooks.custom_access_token_hook`
+
+此 Hook 会在登录/refresh token 时执行，把每个 app 的 role_ids 注入到 JWT claims。
+
+---
+
+## 数据库部署与验证
+
+### 1) 推送迁移
+
+```bash
+supabase db push
+```
+
+### 2) 验证 Hook 注入是否成功
+
+用户登录后，在前端拿到 session 的 `access_token` 并 decode（仅用于验证）：
+
+你应能看到类似结构（示意）：
+
+```json
+{
+  "app_metadata": {
+    "role_ids": {
+      "app1": ["uuid-..."],
+      "global": ["uuid-..."]
+    }
+  }
+}
+```
+
+> 若看不到 `role_ids`：通常是 **Hook 没绑定** 或用户还未刷新 session。
+
+### 3) 角色变更后必须 refresh token
+
+当你在管理端更新用户角色后：
+
+```ts
+await supabase.auth.refreshSession();
+```
+
+否则用户 token 仍是旧 claims。
+
+---
+
+## 前端集成（React）
+
+### 1) 包裹 Provider
+
+```tsx
+import { RBACProvider } from "@sunboyoo/supabase-rbac/client";
+import { supabase } from "./supabaseClient";
+
+export function Root() {
+  return (
+    <RBACProvider client={supabase} appId="app1">
+      <App />
+    </RBACProvider>
+  );
+}
+```
+
+### 2) useRBAC 基础用法
+
+```tsx
+import { useRBAC } from "@sunboyoo/supabase-rbac/client";
+
+export function Toolbar() {
+  const {
+    isAuthenticated,
+    isRBACReady,
+    roleIds,
+    hasRole,
+    refresh
+  } = useRBAC();
+
+  if (!isRBACReady) return null;
+
+  const ADMIN_ROLE_ID = "00000000-0000-0000-0000-000000000001"; // 示例：建议来自你的常量映射
+
+  return (
+    <div>
+      {isAuthenticated && <span>Signed in</span>}
+
+      {hasRole([ADMIN_ROLE_ID]) && (
+        <button>Admin Only</button>
+      )}
+
+      <button onClick={() => refresh(true)}>Force Refresh Token</button>
+    </div>
+  );
+}
+```
+
+### 3) 推荐：role UUID 不要硬编码
+
+你有 3 种推荐方式：
+
+1. **Seed 输出常量文件**（推荐）
+2. 管理端查询后写入配置/环境变量
+3. 业务端后端 API 下发（适用于动态系统）
+
+---
+
+## 服务端/管理端集成（Node）
+
+> RBACManager 采用 **pg 直连数据库**，不依赖 PostgREST 暴露 `rbac` schema，符合安全最佳实践。
+
+### 1) 初始化
+
+```ts
+import { RBACManager } from "@sunboyoo/supabase-rbac/server";
+
+const rbac = new RBACManager({
+  connectionString: process.env.SUPABASE_DB_URL!, // 推荐使用 Supabase 提供的数据库连接串
+  rbacSchema: "rbac" // 可省略
+});
+```
+
+### 2) 创建权限/角色/绑定
+
+```ts
+const appId = "app1";
+
+// 0) 确保 app 已存在（外键约束）
+await rbac.createApp({ id: appId, name: "App 1" });
+
+// 1) 创建权限字典
+const permId = await rbac.createPermission({
+  appId,
+  name: "order.delete",
+  description: "Delete orders"
+});
+
+// 2) 创建角色
+const roleId = await rbac.createRole({
+  appId,
+  name: "Admin"
+});
+
+// 3) 绑定角色-权限
+await rbac.grantPermissionToRole({ appId, roleId, permissionId: permId });
+
+// 4) 给用户分配角色
+await rbac.assignRole({ userId: targetUserId, roleId });
+```
+
+### 3) 关闭连接
+
+```ts
+await rbac.close();
+```
+
+---
+
+## 可选增强：permission-name 语义化判定
+
+### 为什么是“可选”？
+
+* 优点：业务代码更可维护：`hasPermission('order.delete')`
+* 代价：增加一个 RPC 查询（你需要接受额外 DB 负载 + 一定暴露面）
+
+### 如何启用
+
+1. 确保数据库已部署 permission-name RPC（例如 `get_my_permissions`）
+2. Provider 开启 permissions 选项：
+
+```tsx
+<RBACProvider
+  client={supabase}
+  appId="app1"
+  permissions={{
+    enabled: true,
+    rpcName: "get_my_permissions",
+    ttlMs: 60000,
+    nonBlocking: true
+  }}
+>
+  <App />
+</RBACProvider>
+```
+
+### RPC 参考实现（可选）
+
+将 RPC 放在你 **已暴露的 schema**（例如 `public`），RBAC 表仍保持隐藏：
+
+```sql
+create or replace function public.get_my_permissions(target_app_id text)
+returns table(permission_name text)
+language sql
+security definer
+set search_path = ''
+as $$
+  select distinct p.name as permission_name
+  from rbac.user_roles ur
+  join rbac.roles r on r.id = ur.role_id
+  join rbac.role_permissions rp on rp.role_id = r.id and rp.app_id = r.app_id
+  join rbac.permissions p on p.id = rp.permission_id and p.app_id = r.app_id
+  where ur.user_id = auth.uid()
+    and r.app_id in (target_app_id, 'global');
+$$;
+
+grant execute on function public.get_my_permissions(text) to authenticated;
+```
+
+> 注意：如需自定义 `global` key，请同步调整 RPC 与前端 `globalAppId`。
+
+使用：
+
+```tsx
+const { hasPermission, isPermissionReady } = useRBAC();
+if (!isPermissionReady) return null;
+
+return hasPermission("order.delete") ? <DeleteBtn /> : null;
+```
+
+### 强提醒：permission-name 仍然不是安全边界
+
+即使前端显示了按钮，最终能否 DELETE 仍由 RLS 决定。
+
+---
+
+## 最佳实践：权限命名与角色管理
+
+### 权限命名规范
+
+* 全小写
+* 点号分层
+* 稳定、不频繁改动
+
+示例：
+
+* `order.read`
+* `order.create`
+* `order.update`
+* `order.delete`
+* `payroll.export`
+
+### global-mirror 语义
+
+* `global` 是真实 app_id（不是 NULL）
+* 如果 global 角色要跨 App 赋权：
+
+  * 必须在 `rbac.permissions(app_id='global')` 中创建“同名镜像权限”
+
+---
+
+## 常见问题（FAQ）
+
+### Q1：为什么前端看不到 role_ids？
+
+* Hook 未绑定或用户未 refresh session。
+* 解决：
+
+  1. Dashboard 绑定 hook
+  2. 用户端执行 `supabase.auth.refreshSession()`
+
+### Q2：为什么 server.ts 用 pg 而不是 supabase-js？
+
+因为你最佳实践要求 **rbac schema 不暴露**，而 supabase-js（PostgREST）访问不了隐藏 schema。pg 直连是最可靠路径。
+
+### Q3：我开启了 hasPermission，但 RPC 报错怎么办？
+
+* 库会优雅降级：permissionNames 置空，仍可用 hasRole。
+* 你应检查：
+
+  * permission-name RPC 是否已部署
+  * rpcName 是否匹配
+  * GRANT EXECUTE 是否给 authenticated
+
+---
+
+## 安全边界与威胁模型
+
+* ✅ DB/RLS：安全权威
+* ⚠️ Client gating：只做体验
+* ✅ RBAC schema 不暴露：降低枚举风险
+* ⚠️ 可选 RPC：增加暴露面，但控制在“仅返回自己权限”范围内
+* ⚠️ 不要给不受信任用户直连 SQL 或“SQL 执行器”类 RPC；`has_perm` 使用事务级缓存（`set_config`/`current_setting`），需在受控 SQL 环境使用
+
+---
+
+## 版本与兼容性
+
+* Node：建议 18+
+* React：>=16.8
+* supabase-js：^2.x
+* PostgreSQL：Supabase 托管 PG（带 pgcrypto）
+
+---

package/bin/rbac-init.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/* ================================================================================================
+EN: rbac-init CLI
+- Safely 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";
+
+function parseArgs(argv) {
+  const out = { dest: null, force: false, dryRun: false, verbose: false, withExamples: 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
+
+Usage:
+  rbac-init [--dest <path>] [--force] [--dry-run] [--verbose] [--with-examples]
+
+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)
+`);
+      process.exit(0);
+    }
+  }
+  return out;
+}
+
+async function exists(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; }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const cwd = process.cwd();
+  const destDir = path.resolve(cwd, args.dest ?? path.join("supabase", "migrations"));
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const srcDir = path.resolve(__dirname, "..", "migrations");
+
+  if (!(await exists(srcDir))) {
+    console.error(`[rbac-init] migrations folder not found in package: ${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 });
+  }
+
+  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.");
+    return;
+  }
+
+  let copied = 0, overwritten = 0, skipped = 0;
+
+  for (const file of files) {
+    const src = path.join(srcDir, file);
+    const dst = path.join(destDir, file);
+
+    const dstExists = await exists(dst);
+    const srcText = await readText(src);
+    const dstText = dstExists ? await readText(dst) : null;
+
+    const same = dstExists && srcText != null && dstText != null && srcText === dstText;
+
+    if (same) {
+      skipped++;
+      if (args.verbose) console.log(`[rbac-init] skip same: ${file}`);
+      continue;
+    }
+
+    if (dstExists && !args.force) {
+      skipped++;
+      console.log(`[rbac-init] skip exists (use --force): ${file}`);
+      continue;
+    }
+
+    if (args.dryRun) {
+      console.log(`[dry-run] ${dstExists ? "overwrite" : "copy"} ${file}`);
+      continue;
+    }
+
+    await fsp.copyFile(src, dst);
+    if (dstExists) overwritten++; else copied++;
+    console.log(`[rbac-init] ${dstExists ? "overwrote" : "copied"}: ${file}`);
+  }
+
+  console.log(`[rbac-init] done. copied=${copied}, overwritten=${overwritten}, skipped=${skipped}`);
+  console.log(`[rbac-init] next: run "supabase db push"`);
+}
+
+main().catch((e) => {
+  console.error("[rbac-init] error:", e);
+  process.exit(1);
+});

package/dist/chunk-23MRNBGM.js

@@ -0,0 +1,116 @@
+// src/server.ts
+import pg from "pg";
+var { Pool } = pg;
+function qIdent(ident) {
+  return `"${String(ident).replace(/"/g, '""')}"`;
+}
+var RBACManager = class {
+  pool;
+  schema;
+  constructor(opts) {
+    this.pool = new Pool({ connectionString: opts.connectionString });
+    this.schema = opts.rbacSchema ?? "rbac";
+  }
+  async close() {
+    await this.pool.end();
+  }
+  /** EN: Run a transaction.
+   *  中文：事务封装
+   */
+  async tx(fn) {
+    const client = await this.pool.connect();
+    try {
+      await client.query("begin");
+      const res = await fn(client);
+      await client.query("commit");
+      return res;
+    } catch (e) {
+      await client.query("rollback");
+      throw e;
+    } finally {
+      client.release();
+    }
+  }
+  async createApp(params) {
+    const s = qIdent(this.schema);
+    await this.pool.query(
+      `insert into ${s}.apps (id, name) values ($1, $2)
+       on conflict (id) do update set name = excluded.name`,
+      [params.id, params.name]
+    );
+  }
+  async createPermission(params) {
+    const s = qIdent(this.schema);
+    const res = await this.pool.query(
+      `insert into ${s}.permissions (app_id, name, description)
+       values ($1, $2, $3)
+       on conflict (app_id, name) do update set description = excluded.description
+       returning id`,
+      [params.appId, params.name, params.description ?? null]
+    );
+    return res.rows[0].id;
+  }
+  async createRole(params) {
+    const s = qIdent(this.schema);
+    const res = await this.pool.query(
+      `insert into ${s}.roles (app_id, name, description)
+       values ($1, $2, $3)
+       on conflict (app_id, name) do update set description = excluded.description
+       returning id`,
+      [params.appId, params.name, params.description ?? null]
+    );
+    return res.rows[0].id;
+  }
+  async grantPermissionToRole(params) {
+    const s = qIdent(this.schema);
+    await this.pool.query(
+      `insert into ${s}.role_permissions (app_id, role_id, permission_id)
+       values ($1, $2, $3)
+       on conflict do nothing`,
+      [params.appId, params.roleId, params.permissionId]
+    );
+  }
+  async revokePermissionFromRole(params) {
+    const s = qIdent(this.schema);
+    await this.pool.query(
+      `delete from ${s}.role_permissions
+       where app_id = $1 and role_id = $2 and permission_id = $3`,
+      [params.appId, params.roleId, params.permissionId]
+    );
+  }
+  async assignRole(params) {
+    const s = qIdent(this.schema);
+    await this.pool.query(
+      `insert into ${s}.user_roles (user_id, role_id)
+       values ($1, $2)
+       on conflict do nothing`,
+      [params.userId, params.roleId]
+    );
+  }
+  async removeRole(params) {
+    const s = qIdent(this.schema);
+    await this.pool.query(
+      `delete from ${s}.user_roles where user_id = $1 and role_id = $2`,
+      [params.userId, params.roleId]
+    );
+  }
+  async getUserRoleIds(params) {
+    const s = qIdent(this.schema);
+    const includeGlobal = params.includeGlobal ?? true;
+    const globalAppId = params.globalAppId ?? "global";
+    const appIds = includeGlobal ? [params.appId, globalAppId] : [params.appId];
+    const res = await this.pool.query(
+      `select r.id as role_id
+       from ${s}.user_roles ur
+       join ${s}.roles r on r.id = ur.role_id
+       where ur.user_id = $1 and r.app_id = any($2::text[])
+       order by r.app_id, r.id`,
+      [params.userId, appIds]
+    );
+    return res.rows.map((x) => x.role_id);
+  }
+};
+
+export {
+  RBACManager
+};

package/dist/chunk-ZFY3OHWO.js

@@ -0,0 +1,54 @@
+// src/shared.ts
+import { decodeJwt } from "jose";
+var IS_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isUuid(v) {
+  return typeof v === "string" && IS_UUID.test(v);
+}
+function uniqueStable(arr) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const x of arr) {
+    if (seen.has(x)) continue;
+    seen.add(x);
+    out.push(x);
+  }
+  return out;
+}
+function decodeClaims(token) {
+  if (!token) return null;
+  try {
+    return decodeJwt(token);
+  } catch {
+    return null;
+  }
+}
+function getMergedRoleIds(params) {
+  const { token, appId, includeGlobal = true, globalAppId = "global" } = params;
+  const claims = decodeClaims(token);
+  const roleMap = claims?.app_metadata?.role_ids ?? {};
+  const appRoles = Array.isArray(roleMap[appId]) ? roleMap[appId] : [];
+  const gRoles = includeGlobal && Array.isArray(roleMap[globalAppId]) ? roleMap[globalAppId] : [];
+  const merged = uniqueStable([...appRoles, ...gRoles]).filter(isUuid);
+  const userId = isUuid(claims?.sub) ? claims.sub : null;
+  const exp = typeof claims?.exp === "number" ? claims.exp : null;
+  return { roleIds: merged, claims, userId, exp };
+}
+function hasRole(userRoleIds, required, mode = "any") {
+  if (!required || required.length === 0) return true;
+  if (!userRoleIds || userRoleIds.length === 0) return false;
+  const set = new Set(userRoleIds);
+  if (mode === "all") {
+    for (const r of required) if (!set.has(r)) return false;
+    return true;
+  }
+  for (const r of required) if (set.has(r)) return true;
+  return false;
+}
+
+export {
+  isUuid,
+  uniqueStable,
+  decodeClaims,
+  getMergedRoleIds,
+  hasRole
+};