@sunboyoo/supabase-rbac 1.0.2

package/dist/types-BayIl-Ha.d.cts

@@ -0,0 +1,116 @@
+type UUID = string;
+type RoleCheckMode = "any" | "all";
+type RoleIdsByApp = Record<string, UUID[]>;
+interface RBACClaims {
+    app_metadata?: {
+        role_ids?: RoleIdsByApp;
+        [k: string]: unknown;
+    };
+    sub?: string;
+    exp?: number;
+    [k: string]: unknown;
+}
+interface Logger {
+    debug?: (msg: string, meta?: unknown) => void;
+    info?: (msg: string, meta?: unknown) => void;
+    warn?: (msg: string, meta?: unknown) => void;
+    error?: (msg: string, meta?: unknown) => void;
+}
+/** EN: Client permission-name support is optional and should be feature-flagged.
+ *  中文：permission-name 能力是可选增强，建议 feature-flag 控制，默认关闭以最小暴露面。
+ */
+interface PermissionNameOptions {
+    /** EN: Enable permission-name list loading via RPC. Default: false
+     *  中文：是否启用通过 RPC 加载 permission-name 列表。默认 false
+     */
+    enabled?: boolean;
+    /** EN: RPC function name. Default: 'rbac.get_my_permissions' or 'get_my_permissions' depending on your PostgREST exposure.
+     *      Best practice: expose via RPC name 'get_my_permissions' (no schema prefix) if you keep rbac schema not exposed.
+     *  中文：RPC 函数名。默认 'get_my_permissions'（推荐：不带 schema 前缀，更利于隐藏 schema）
+     */
+    rpcName?: string;
+    /** EN: TTL for permission list cache in ms. Default: 60_000
+     *  中文：permission 列表缓存 TTL（毫秒）。默认 60秒
+     */
+    ttlMs?: number;
+    /** EN: Non-blocking: roleIds update first, permissions load in background. Default: true
+     *  中文：非阻塞：先更新 roleIds，permissions 后台加载。默认 true
+     */
+    nonBlocking?: boolean;
+}
+interface RBACProviderProps {
+    /** EN: Supabase client instance
+     *  中文：Supabase client 实例
+     */
+    client: any;
+    /** EN: current app_id
+     *  中文：当前 app_id
+     */
+    appId: string;
+    /** EN: include global roles automatically (default true)
+     *  中文：自动合并 global 角色（默认 true）
+     */
+    includeGlobal?: boolean;
+    /** EN: global app id key (default 'global')
+     *  中文：global app_id key（默认 'global'）
+     */
+    globalAppId?: string;
+    /** EN: Permission-name support options (optional)
+     *  中文：permission-name 可选增强配置
+     */
+    permissions?: PermissionNameOptions;
+    /** EN: Optional logger hook (no console spam by default)
+     *  中文：可选 logger（默认不输出 console）
+     */
+    logger?: Logger;
+    children: any;
+}
+interface RBACState {
+    appId: string;
+    /** EN: Auth state
+     *  中文：认证态（是否登录）
+     */
+    isAuthenticated: boolean;
+    /** EN: Parsed user id (best-effort)
+     *  中文：user id（尽力获取）
+     */
+    userId: UUID | null;
+    /** EN: Merged role ids for (appId + optional global)
+     *  中文：合并后的 roleIds（appId + 可选 global）
+     */
+    roleIds: UUID[];
+    /** EN: Optional permission-name list (only when enabled)
+     *  中文：可选的 permission-name 列表（仅启用时）
+     */
+    permissionNames: string[];
+    /** EN: Loading state for RBAC info (roles always; permissions optional)
+     *  中文：RBAC 加载状态（roles 必有；permissions 可选）
+     */
+    isRBACLoading: boolean;
+    /** EN: Permission-name loading state (only meaningful when enabled)
+     *  中文：permission-name 加载状态（启用时才有意义）
+     */
+    isPermissionLoading: boolean;
+    /** EN: Whether RBAC base (roles) is ready
+     *  中文：RBAC 基础（roles）是否就绪
+     */
+    isRBACReady: boolean;
+    /** EN: Whether permission list is ready (when enabled)
+     *  中文：permission 列表是否就绪（启用时）
+     */
+    isPermissionReady: boolean;
+    /** EN: Refresh RBAC state. forceSessionUpdate triggers supabase.auth.refreshSession()
+     *  中文：刷新 RBAC 状态。forceSessionUpdate 会触发 refreshSession 以重新注入 claims
+     */
+    refresh: (forceSessionUpdate?: boolean) => Promise<void>;
+    /** EN: Role gating (fast path)
+     *  中文：基于 roleIds 的 UI 判定（快路径）
+     */
+    hasRole: (requiredRoleIds: UUID[], mode?: RoleCheckMode) => boolean;
+    /** EN: Permission gating (slow path; optional)
+     *  中文：基于 permission-name 的 UI 判定（慢路径；可选）
+     */
+    hasPermission: (permissionName: string) => boolean;
+}
+
+export type { Logger as L, PermissionNameOptions as P, RoleCheckMode as R, UUID as U, RoleIdsByApp as a, RBACClaims as b, RBACProviderProps as c, RBACState as d };

package/dist/types-BayIl-Ha.d.ts

@@ -0,0 +1,116 @@
+type UUID = string;
+type RoleCheckMode = "any" | "all";
+type RoleIdsByApp = Record<string, UUID[]>;
+interface RBACClaims {
+    app_metadata?: {
+        role_ids?: RoleIdsByApp;
+        [k: string]: unknown;
+    };
+    sub?: string;
+    exp?: number;
+    [k: string]: unknown;
+}
+interface Logger {
+    debug?: (msg: string, meta?: unknown) => void;
+    info?: (msg: string, meta?: unknown) => void;
+    warn?: (msg: string, meta?: unknown) => void;
+    error?: (msg: string, meta?: unknown) => void;
+}
+/** EN: Client permission-name support is optional and should be feature-flagged.
+ *  中文：permission-name 能力是可选增强，建议 feature-flag 控制，默认关闭以最小暴露面。
+ */
+interface PermissionNameOptions {
+    /** EN: Enable permission-name list loading via RPC. Default: false
+     *  中文：是否启用通过 RPC 加载 permission-name 列表。默认 false
+     */
+    enabled?: boolean;
+    /** EN: RPC function name. Default: 'rbac.get_my_permissions' or 'get_my_permissions' depending on your PostgREST exposure.
+     *      Best practice: expose via RPC name 'get_my_permissions' (no schema prefix) if you keep rbac schema not exposed.
+     *  中文：RPC 函数名。默认 'get_my_permissions'（推荐：不带 schema 前缀，更利于隐藏 schema）
+     */
+    rpcName?: string;
+    /** EN: TTL for permission list cache in ms. Default: 60_000
+     *  中文：permission 列表缓存 TTL（毫秒）。默认 60秒
+     */
+    ttlMs?: number;
+    /** EN: Non-blocking: roleIds update first, permissions load in background. Default: true
+     *  中文：非阻塞：先更新 roleIds，permissions 后台加载。默认 true
+     */
+    nonBlocking?: boolean;
+}
+interface RBACProviderProps {
+    /** EN: Supabase client instance
+     *  中文：Supabase client 实例
+     */
+    client: any;
+    /** EN: current app_id
+     *  中文：当前 app_id
+     */
+    appId: string;
+    /** EN: include global roles automatically (default true)
+     *  中文：自动合并 global 角色（默认 true）
+     */
+    includeGlobal?: boolean;
+    /** EN: global app id key (default 'global')
+     *  中文：global app_id key（默认 'global'）
+     */
+    globalAppId?: string;
+    /** EN: Permission-name support options (optional)
+     *  中文：permission-name 可选增强配置
+     */
+    permissions?: PermissionNameOptions;
+    /** EN: Optional logger hook (no console spam by default)
+     *  中文：可选 logger（默认不输出 console）
+     */
+    logger?: Logger;
+    children: any;
+}
+interface RBACState {
+    appId: string;
+    /** EN: Auth state
+     *  中文：认证态（是否登录）
+     */
+    isAuthenticated: boolean;
+    /** EN: Parsed user id (best-effort)
+     *  中文：user id（尽力获取）
+     */
+    userId: UUID | null;
+    /** EN: Merged role ids for (appId + optional global)
+     *  中文：合并后的 roleIds（appId + 可选 global）
+     */
+    roleIds: UUID[];
+    /** EN: Optional permission-name list (only when enabled)
+     *  中文：可选的 permission-name 列表（仅启用时）
+     */
+    permissionNames: string[];
+    /** EN: Loading state for RBAC info (roles always; permissions optional)
+     *  中文：RBAC 加载状态（roles 必有；permissions 可选）
+     */
+    isRBACLoading: boolean;
+    /** EN: Permission-name loading state (only meaningful when enabled)
+     *  中文：permission-name 加载状态（启用时才有意义）
+     */
+    isPermissionLoading: boolean;
+    /** EN: Whether RBAC base (roles) is ready
+     *  中文：RBAC 基础（roles）是否就绪
+     */
+    isRBACReady: boolean;
+    /** EN: Whether permission list is ready (when enabled)
+     *  中文：permission 列表是否就绪（启用时）
+     */
+    isPermissionReady: boolean;
+    /** EN: Refresh RBAC state. forceSessionUpdate triggers supabase.auth.refreshSession()
+     *  中文：刷新 RBAC 状态。forceSessionUpdate 会触发 refreshSession 以重新注入 claims
+     */
+    refresh: (forceSessionUpdate?: boolean) => Promise<void>;
+    /** EN: Role gating (fast path)
+     *  中文：基于 roleIds 的 UI 判定（快路径）
+     */
+    hasRole: (requiredRoleIds: UUID[], mode?: RoleCheckMode) => boolean;
+    /** EN: Permission gating (slow path; optional)
+     *  中文：基于 permission-name 的 UI 判定（慢路径；可选）
+     */
+    hasPermission: (permissionName: string) => boolean;
+}
+
+export type { Logger as L, PermissionNameOptions as P, RoleCheckMode as R, UUID as U, RoleIdsByApp as a, RBACClaims as b, RBACProviderProps as c, RBACState as d };

package/migrations/20251229000000_create_rbac_schemas_and_extensions.sql

@@ -0,0 +1,70 @@
+/* =================================================================================================
+ENGLISH COMMENT BLOCK (Architecture + Ops + Frontend Guidance)
+====================================================================================================
+
+FILE PURPOSE
+- This migration creates required extensions and the two dedicated schemas:
+  - rbac  : all RBAC tables / views / core permission-check function
+  - hooks : Supabase Auth hook function used to inject claims into JWT
+
+ARCHITECTURE OVERVIEW (High-level)
+- Multi-App / Multi-Module RBAC in one Supabase project (SSO).
+- RBAC is shared across apps; business tables remain app-private.
+- Authorization is enforced in DB via RLS policies calling rbac.has_perm(app_id, perm_name).
+- JWT stores role_ids (UUID) per app_id, injected by a custom access token hook.
+
+IMPORTANT NOTES
+- This file ONLY creates schemas and baseline schema revokes.
+- Do NOT expose schemas rbac / hooks via Supabase Dashboard → API → Exposed Schemas.
+- Stronger REVOKE/GRANT hardening happens in later migrations (do not duplicate here).
+
+FRONTEND / EXTERNAL USAGE (Reference)
+- Frontend typically does NOT call rbac.has_perm directly. RLS enforces permissions.
+- After admin changes user roles, users must refresh token:
+  supabase.auth.refreshSession()
+
+==================================================================================================== */
+
+
+/* =================================================================================================
+中文注释区块（架构 + 运维 + 前端指引）
+====================================================================================================
+
+文件目的
+- 本迁移只负责创建必要扩展与两个 schema：
+  - rbac  ：RBAC 权限表/视图/核心判定函数
+  - hooks ：Supabase Auth Hook（向 JWT 注入 claims）
+
+架构总览（高层）
+- 同一 Supabase 项目下多 App/多模块（SSO）。
+- RBAC 表全生态共用；业务表按 App 私有。
+- 权限在数据库层用 RLS 强制执行，策略调用 rbac.has_perm(app_id, perm_name)。
+- JWT 存 role_ids（UUID），通过 Auth access token hook 注入。
+
+重要说明
+- 本文件只做 schema + 基础 revoke，不做完整授权收紧。
+- Supabase Dashboard → API → Exposed Schemas 必须移除 rbac / hooks（强防枚举）。
+- 更完整的 GRANT/REVOKE 会在后续迁移中集中处理，避免重复与漂移。
+
+前端/外部使用提示
+- 前端通常不直接调用 rbac.has_perm，依赖 RLS 拦截并处理 401/403。
+- 管理端更改用户角色后，用户需 refresh token：
+  supabase.auth.refreshSession()
+
+==================================================================================================== */
+
+
+-- Create required extension(s) and schemas for RBAC / Hooks.
+-- Note: Removing schemas from Supabase "Exposed Schemas" is a Dashboard setting, not SQL.
+
+create extension if not exists pgcrypto;
+
+create schema if not exists rbac;
+create schema if not exists hooks;
+
+-- Baseline schema lockdown (tables are locked down later via grants/revokes).
+revoke all on schema rbac  from public;
+revoke all on schema hooks from public;
+
+revoke all on schema rbac  from anon, authenticated;
+revoke all on schema hooks from anon, authenticated;

package/migrations/20251229000001_create_rbac_tables.sql

@@ -0,0 +1,134 @@
+/* =================================================================================================
+ENGLISH COMMENT BLOCK (Architecture + Ops + Frontend Guidance)
+====================================================================================================
+
+FILE PURPOSE
+- Creates RBAC core tables shared across all apps/modules:
+  - rbac.apps
+  - rbac.permissions
+  - rbac.roles
+  - rbac.role_permissions (with composite FK integrity)
+  - rbac.user_roles
+- Creates required indexes for the authorization hot path.
+- Disables RLS on RBAC tables (RBAC is protected via GRANT/REVOKE + schema isolation).
+
+ARCHITECTURE KEYWORDS
+- App-scoped Roles & Permissions (app_id)
+- Global-Mirror Permissions (app_id='global', not NULL)
+- Composite Foreign Key Consistency (prevents cross-app binding of roles/permissions)
+- Shared RBAC, App-Private Data
+
+GLOBAL-MIRROR SEMANTICS (Critical)
+- 'global' is a real app_id row (never NULL).
+- Global roles grant permissions ONLY via global permissions dictionary.
+- If a global role should grant an app permission, you must create a mirrored permission:
+  rbac.permissions(app_id='global', name='<same permission name>').
+
+OPERATIONS NOTES
+- RBAC tables do NOT enable RLS to avoid FORCE RLS / policy drift operational risks.
+- Security hardening and exposure control (revoke/grant) is applied in later migrations.
+
+==================================================================================================== */
+
+
+/* =================================================================================================
+中文注释区块（架构 + 运维 + 前端指引）
+====================================================================================================
+
+文件目的
+- 创建全生态共享的 RBAC 核心表：
+  - rbac.apps
+  - rbac.permissions
+  - rbac.roles
+  - rbac.role_permissions（复合外键强一致性）
+  - rbac.user_roles
+- 创建鉴权热路径所需索引。
+- RBAC 表不开 RLS（通过 GRANT/REVOKE + schema 隔离来保护）。
+
+架构关键字
+- 按 app_id 作用域的角色/权限（App-scoped）
+- Global-Mirror（global 是实体 app_id，不用 NULL）
+- 复合外键强一致性（杜绝跨 App 脏绑定）
+- RBAC 共享，业务表 App 私有
+
+Global-Mirror 语义（重点）
+- 'global' 必须存在且不可为 NULL。
+- global 角色要跨 App 授权，必须在 global 权限字典中创建“同名镜像权限”。
+
+运维说明
+- RBAC 表不开 RLS，避免 FORCE RLS 等运维坑与策略漂移。
+- 具体 REVOKE/GRANT 收紧在后续迁移执行（请勿在此文件重复）。
+
+==================================================================================================== */
+
+
+-- RBAC core tables (shared across all apps/modules)
+-- Design:
+-- - app-scoped roles & permissions (app_id)
+-- - global is a first-class app_id (NOT NULL)
+-- - role_permissions uses composite FK to prevent cross-app binding (physical integrity)
+
+create table if not exists rbac.apps (
+  id   text primary key,   -- 'app1', 'app2', 'global'
+  name text not null
+);
+
+insert into rbac.apps (id, name)
+values ('global', 'Global System')
+on conflict (id) do nothing;
+
+create table if not exists rbac.permissions (
+  id     uuid primary key default gen_random_uuid(),
+  app_id text not null references rbac.apps(id) on delete cascade,
+  name   text not null, -- 'order.read'
+  description text,
+  constraint permissions_unique_name unique (app_id, name),
+  constraint permissions_unique_id_app unique (id, app_id),
+  constraint permissions_id_not_sentinel check (id <> '00000000-0000-0000-0000-000000000000'::uuid)
+);
+
+create index if not exists idx_permissions_app_name
+  on rbac.permissions(app_id, name);
+
+create table if not exists rbac.roles (
+  id     uuid primary key default gen_random_uuid(),
+  app_id text not null references rbac.apps(id) on delete cascade,
+  name   text not null, -- can be renamed safely; auth uses role_id
+  description text,
+  constraint roles_unique_name unique (app_id, name),
+  constraint roles_unique_id_app unique (id, app_id),
+  constraint roles_id_not_sentinel check (id <> '00000000-0000-0000-0000-000000000000'::uuid)
+);
+
+create table if not exists rbac.role_permissions (
+  app_id        text not null references rbac.apps(id) on delete cascade,
+  role_id       uuid not null,
+  permission_id uuid not null,
+  primary key (app_id, role_id, permission_id),
+
+  -- Physical consistency: role_id and permission_id must belong to the SAME app_id
+  constraint fk_role_consistency
+    foreign key (role_id, app_id) references rbac.roles(id, app_id) on delete cascade,
+  constraint fk_perm_consistency
+    foreign key (permission_id, app_id) references rbac.permissions(id, app_id) on delete cascade
+);
+
+-- Hot-path index for authorization check
+create index if not exists idx_rp_lookup
+  on rbac.role_permissions(app_id, permission_id, role_id);
+
+create table if not exists rbac.user_roles (
+  user_id uuid not null references auth.users(id) on delete cascade,
+  role_id uuid not null references rbac.roles(id) on delete cascade,
+  primary key (user_id, role_id)
+);
+
+create index if not exists idx_user_roles_uid  on rbac.user_roles(user_id);
+create index if not exists idx_user_roles_role on rbac.user_roles(role_id);
+
+-- RBAC tables are protected via GRANT/REVOKE (not RLS) for operational safety.
+alter table rbac.apps             disable row level security;
+alter table rbac.permissions      disable row level security;
+alter table rbac.roles            disable row level security;
+alter table rbac.role_permissions disable row level security;
+alter table rbac.user_roles       disable row level security;

package/migrations/20251229000002_create_rbac_views.sql

@@ -0,0 +1,70 @@
+/* =================================================================================================
+ENGLISH COMMENT BLOCK (Architecture + Ops + Frontend Guidance)
+====================================================================================================
+
+FILE PURPOSE
+- Creates optional RBAC views for debugging/admin tooling:
+  - rbac.v_user_app_role_ids
+  - rbac.v_role_permissions
+
+IMPORTANT NOTES
+- Views do not automatically expose data to clients.
+- Exposure is controlled by:
+  - Supabase Dashboard "Exposed Schemas"
+  - GRANT/REVOKE (applied in later migration)
+- These views are primarily for:
+  - admin dashboards (service_role)
+  - internal troubleshooting / audits
+  - verifying role-permission bindings
+
+FRONTEND GUIDANCE
+- Do NOT rely on these views from client apps unless you intentionally expose them and design an admin API.
+- Normal apps should rely on RLS + business-table queries.
+
+==================================================================================================== */
+
+
+/* =================================================================================================
+中文注释区块（架构 + 运维 + 前端指引）
+====================================================================================================
+
+文件目的
+- 创建 RBAC 辅助视图（用于调试/管理）：
+  - rbac.v_user_app_role_ids（用户在各 App 下的角色）
+  - rbac.v_role_permissions（角色-权限展开）
+
+重要说明
+- 视图不会自动暴露给客户端，是否可访问取决于：
+  - Supabase Exposed Schemas 配置
+  - 后续迁移中的 GRANT/REVOKE
+- 这些视图建议只用于 service_role 的管理端或排障。
+
+前端提示
+- 普通前端 App 不应直接访问这些视图。
+- 正常业务只依赖 RLS + 业务表查询。
+
+==================================================================================================== */
+
+
+-- Optional views for debugging/admin tooling.
+-- Note: These views do not imply exposure; exposure is controlled by grants and exposed schemas.
+
+create or replace view rbac.v_user_app_role_ids as
+select
+  ur.user_id,
+  r.app_id,
+  r.id   as role_id,
+  r.name as role_name
+from rbac.user_roles ur
+join rbac.roles r on r.id = ur.role_id;
+
+create or replace view rbac.v_role_permissions as
+select
+  rp.app_id,
+  rp.role_id,
+  ro.name as role_name,
+  rp.permission_id,
+  p.name as permission_name
+from rbac.role_permissions rp
+join rbac.roles ro on ro.id = rp.role_id
+join rbac.permissions p on p.id = rp.permission_id;