@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-enterprise-rbac/SKILL.md

@@ -1,222 +1,389 @@
 ---
 name: supabase-enterprise-rbac
-description: |
-  Configure Supabase enterprise SSO, role-based access control, and organization management.
-  Use when implementing SSO integration, configuring role-based permissions,
-  or setting up organization-level controls for Supabase.
-  Trigger with phrases like "supabase SSO", "supabase RBAC",
-  "supabase enterprise", "supabase roles", "supabase permissions", "supabase SAML".
-allowed-tools: Read, Write, Edit
+description: 'Implement custom role-based access control via JWT claims in Supabase:
+  app_metadata.role,
+
+  RLS policies with auth.jwt() role extraction, organization-scoped access, and API
+  key scoping.
+
+  Use when implementing role-based permissions, configuring organization-level access,
+
+  building admin/member/viewer hierarchies, or scoping API keys per role.
+
+  Trigger: "supabase RBAC", "supabase roles", "supabase permissions", "supabase JWT
+  claims",
+
+  "supabase organization access", "supabase custom roles", "supabase app_metadata".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(npx supabase:*), Bash(supabase:*), Bash(psql:*),
+  Grep, Glob
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- rbac
+- security
+- enterprise
+- roles
+- permissions
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Supabase Enterprise RBAC
 
 ## Overview
-Configure enterprise-grade access control for Supabase integrations.
 
-## Prerequisites
-- Supabase Enterprise tier subscription
-- Identity Provider (IdP) with SAML/OIDC support
-- Understanding of role-based access patterns
-- Audit logging infrastructure
+Supabase supports custom role-based access control (RBAC) by storing role information in `app_metadata` on the user's JWT, then reading those claims in RLS policies via `auth.jwt() ->> 'role'`. This skill implements a complete RBAC system: defining roles in `app_metadata`, writing RLS policies that enforce role hierarchies, scoping access by organization, managing roles through the Admin API, and protecting API endpoints with role checks — all using real `createClient` from `@supabase/supabase-js`.
 
-## Role Definitions
+**When to use:** Building multi-role applications (admin/editor/viewer), implementing organization-scoped access, creating custom permission systems beyond Supabase's built-in `anon`/`authenticated` roles, or scoping API operations by user role.
 
-| Role | Permissions | Use Case |
-|------|-------------|----------|
-| Admin | Full access | Platform administrators |
-| Developer | Read/write, no delete | Active development |
-| Viewer | Read-only | Stakeholders, auditors |
-| Service | API access only | Automated systems |
+## Prerequisites
 
-## Role Implementation
+- `@supabase/supabase-js` v2+ with service role key for admin operations
+- Understanding of JWT claims and Supabase's `auth.jwt()` SQL function
+- Database access via SQL Editor or `psql` for RLS policy creation
+- Supabase project with authentication configured
 
-```typescript
-enum SupabaseRole {
-  Admin = 'admin',
-  Developer = 'developer',
-  Viewer = 'viewer',
-  Service = 'service',
-}
+## Instructions
 
-interface SupabasePermissions {
-  read: boolean;
-  write: boolean;
-  delete: boolean;
-  admin: boolean;
-}
+### Step 1: Define Roles via app_metadata and JWT Claims
 
-const ROLE_PERMISSIONS: Record<SupabaseRole, SupabasePermissions> = {
-  admin: { read: true, write: true, delete: true, admin: true },
-  developer: { read: true, write: true, delete: false, admin: false },
-  viewer: { read: true, write: false, delete: false, admin: false },
-  service: { read: true, write: true, delete: false, admin: false },
-};
-
-function checkPermission(
-  role: SupabaseRole,
-  action: keyof SupabasePermissions
-): boolean {
-  return ROLE_PERMISSIONS[role][action];
-}
-```
+Store custom roles in the user's `app_metadata` using the Admin API. These claims appear in every JWT the user receives and are available in RLS policies.
 
-## SSO Integration
-
-### SAML Configuration
+**Set user roles with the Admin API:**
 
 ```typescript
-// Supabase SAML setup
-const samlConfig = {
-  entryPoint: 'https://idp.company.com/saml/sso',
-  issuer: 'https://supabase.com/saml/metadata',
-  cert: process.env.SAML_CERT,
-  callbackUrl: 'https://app.yourcompany.com/auth/supabase/callback',
-};
-
-// Map IdP groups to Supabase roles
-const groupRoleMapping: Record<string, SupabaseRole> = {
-  'Engineering': SupabaseRole.Developer,
-  'Platform-Admins': SupabaseRole.Admin,
-  'Data-Team': SupabaseRole.Viewer,
-};
-```
+import { createClient } from '@supabase/supabase-js';
 
-### OAuth2/OIDC Integration
-
-```typescript
-import { OAuth2Client } from '@supabase/supabase-js';
-
-const oauthClient = new OAuth2Client({
-  clientId: process.env.SUPABASE_OAUTH_CLIENT_ID!,
-  clientSecret: process.env.SUPABASE_OAUTH_CLIENT_SECRET!,
-  redirectUri: 'https://app.yourcompany.com/auth/supabase/callback',
-  scopes: read, write, realtime,
-});
-```
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
 
-## Organization Management
+// Define the role hierarchy
+type AppRole = 'admin' | 'editor' | 'viewer' | 'member';
 
-```typescript
-interface SupabaseOrganization {
-  id: string;
-  name: string;
-  ssoEnabled: boolean;
-  enforceSso: boolean;
-  allowedDomains: string[];
-  defaultRole: SupabaseRole;
+interface AppMetadata {
+  role: AppRole;
+  org_id: string;
+  permissions?: string[];
 }
 
-async function createOrganization(
-  config: SupabaseOrganization
-): Promise<void> {
-  await supabaseClient.organizations.create({
-    ...config,
-    settings: {
-      sso: {
-        enabled: config.ssoEnabled,
-        enforced: config.enforceSso,
-        domains: config.allowedDomains,
-      },
+// Assign a role to a user (admin operation)
+async function setUserRole(userId: string, role: AppRole, orgId: string) {
+  const { data, error } = await supabase.auth.admin.updateUserById(userId, {
+    app_metadata: {
+      role,
+      org_id: orgId,
     },
   });
-}
-```
 
-## Access Control Middleware
+  if (error) throw new Error(`Failed to set role: ${error.message}`);
 
-```typescript
-function requireSupabasePermission(
-  requiredPermission: keyof SupabasePermissions
-) {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const user = req.user as { supabaseRole: SupabaseRole };
+  console.log(`User ${userId} assigned role "${role}" in org "${orgId}"`);
+  return data.user;
+}
 
-    if (!checkPermission(user.supabaseRole, requiredPermission)) {
-      return res.status(403).json({
-        error: 'Forbidden',
-        message: `Missing permission: ${requiredPermission}`,
-      });
-    }
+// Assign granular permissions (optional, for fine-grained control)
+async function setUserPermissions(
+  userId: string,
+  permissions: string[]
+) {
+  const { data, error } = await supabase.auth.admin.updateUserById(userId, {
+    app_metadata: { permissions },
+  });
 
-    next();
-  };
+  if (error) throw new Error(`Failed to set permissions: ${error.message}`);
+  return data.user;
 }
 
-// Usage
-app.delete('/supabase/resource/:id',
-  requireSupabasePermission('delete'),
-  deleteResourceHandler
-);
+// Bulk role assignment (e.g., onboarding a team)
+async function assignTeamRoles(
+  orgId: string,
+  assignments: { userId: string; role: AppRole }[]
+) {
+  const results = await Promise.allSettled(
+    assignments.map(({ userId, role }) => setUserRole(userId, role, orgId))
+  );
+
+  const succeeded = results.filter((r) => r.status === 'fulfilled').length;
+  const failed = results.filter((r) => r.status === 'rejected').length;
+  console.log(`Assigned ${succeeded} roles, ${failed} failures`);
+}
 ```
 
-## Audit Trail
+**Read roles from the JWT in application code:**
 
 ```typescript
-interface SupabaseAuditEntry {
-  timestamp: Date;
-  userId: string;
-  role: SupabaseRole;
-  action: string;
-  resource: string;
-  success: boolean;
-  ipAddress: string;
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+// Get the current user's role from their JWT
+async function getCurrentUserRole(): Promise<AppRole | null> {
+  const { data: { user }, error } = await supabase.auth.getUser();
+  if (error || !user) return null;
+
+  return (user.app_metadata?.role as AppRole) ?? null;
+}
+
+// Get the current user's organization
+async function getCurrentOrg(): Promise<string | null> {
+  const { data: { user } } = await supabase.auth.getUser();
+  return user?.app_metadata?.org_id ?? null;
 }
 
-async function logSupabaseAccess(entry: SupabaseAuditEntry): Promise<void> {
-  await auditDb.insert(entry);
+// Check if current user has a specific role or higher
+function hasRole(userRole: AppRole, requiredRole: AppRole): boolean {
+  const hierarchy: Record<AppRole, number> = {
+    admin: 4,
+    editor: 3,
+    member: 2,
+    viewer: 1,
+  };
+  return hierarchy[userRole] >= hierarchy[requiredRole];
+}
 
-  // Alert on suspicious activity
-  if (entry.action === 'delete' && !entry.success) {
-    await alertOnSuspiciousActivity(entry);
+// Middleware-style role check for API routes
+async function requireRole(requiredRole: AppRole) {
+  const role = await getCurrentUserRole();
+  if (!role || !hasRole(role, requiredRole)) {
+    throw new Error(
+      `Access denied: requires "${requiredRole}" role, user has "${role ?? 'none'}"`
+    );
   }
 }
 ```
 
-## Instructions
+### Step 2: RLS Policies with JWT Role Claims
+
+Write Row Level Security policies that read `auth.jwt() ->> 'role'` and `auth.jwt() -> 'app_metadata' ->> 'org_id'` to enforce role-based and organization-scoped access.
+
+**Role-based RLS policies:**
+
+```sql
+-- Create a helper function to extract role from JWT
+CREATE OR REPLACE FUNCTION public.get_user_role()
+RETURNS text AS $$
+  SELECT coalesce(
+    auth.jwt() -> 'app_metadata' ->> 'role',
+    'viewer'  -- default role if not set
+  );
+$$ LANGUAGE sql STABLE SECURITY DEFINER;
+
+-- Create a helper function to extract org_id from JWT
+CREATE OR REPLACE FUNCTION public.get_user_org_id()
+RETURNS text AS $$
+  SELECT auth.jwt() -> 'app_metadata' ->> 'org_id';
+$$ LANGUAGE sql STABLE SECURITY DEFINER;
+
+-- Enable RLS on all tables
+ALTER TABLE public.projects ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.team_members ENABLE ROW LEVEL SECURITY;
+
+-- Projects: org members can read, editors+ can create/update, admins can delete
+CREATE POLICY "org_members_read_projects" ON public.projects
+  FOR SELECT USING (
+    org_id = get_user_org_id()
+  );
+
+CREATE POLICY "editors_create_projects" ON public.projects
+  FOR INSERT WITH CHECK (
+    org_id = get_user_org_id()
+    AND get_user_role() IN ('admin', 'editor')
+  );
+
+CREATE POLICY "editors_update_projects" ON public.projects
+  FOR UPDATE USING (
+    org_id = get_user_org_id()
+    AND get_user_role() IN ('admin', 'editor')
+  );
+
+CREATE POLICY "admins_delete_projects" ON public.projects
+  FOR DELETE USING (
+    org_id = get_user_org_id()
+    AND get_user_role() = 'admin'
+  );
+
+-- Documents: org-scoped with role-based write access
+CREATE POLICY "org_read_documents" ON public.documents
+  FOR SELECT USING (
+    org_id = get_user_org_id()
+  );
+
+CREATE POLICY "editors_write_documents" ON public.documents
+  FOR INSERT WITH CHECK (
+    org_id = get_user_org_id()
+    AND get_user_role() IN ('admin', 'editor')
+  );
+
+CREATE POLICY "owner_or_admin_update_documents" ON public.documents
+  FOR UPDATE USING (
+    org_id = get_user_org_id()
+    AND (
+      created_by = auth.uid()
+      OR get_user_role() = 'admin'
+    )
+  );
+
+-- Team members: admins manage team, members can read
+CREATE POLICY "org_read_team" ON public.team_members
+  FOR SELECT USING (
+    org_id = get_user_org_id()
+  );
+
+CREATE POLICY "admins_manage_team" ON public.team_members
+  FOR ALL USING (
+    org_id = get_user_org_id()
+    AND get_user_role() = 'admin'
+  );
+```
+
+**Organization-scoped access table schema:**
+
+```sql
+-- Organizations table
+CREATE TABLE public.organizations (
+  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+  name text NOT NULL,
+  slug text UNIQUE NOT NULL,
+  created_at timestamptz DEFAULT now()
+);
 
-### Step 1: Define Roles
-Map organizational roles to Supabase permissions.
+-- Team members junction table
+CREATE TABLE public.team_members (
+  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+  org_id uuid REFERENCES public.organizations(id) ON DELETE CASCADE,
+  user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE,
+  role text NOT NULL DEFAULT 'member' CHECK (role IN ('admin', 'editor', 'member', 'viewer')),
+  invited_by uuid REFERENCES auth.users(id),
+  created_at timestamptz DEFAULT now(),
+  UNIQUE(org_id, user_id)
+);
 
-### Step 2: Configure SSO
-Set up SAML or OIDC integration with your IdP.
+-- Projects scoped to organizations
+CREATE TABLE public.projects (
+  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+  org_id uuid REFERENCES public.organizations(id) ON DELETE CASCADE,
+  name text NOT NULL,
+  created_by uuid REFERENCES auth.users(id),
+  created_at timestamptz DEFAULT now()
+);
+
+-- Index for fast org-scoped queries
+CREATE INDEX idx_team_members_org ON public.team_members(org_id);
+CREATE INDEX idx_team_members_user ON public.team_members(user_id);
+CREATE INDEX idx_projects_org ON public.projects(org_id);
+```
 
-### Step 3: Implement Middleware
-Add permission checks to API endpoints.
+### Step 3: API Key Scoping and Role Enforcement in Application Code
 
-### Step 4: Enable Audit Logging
-Track all access for compliance.
+See [API key scoping and role enforcement](references/api-scoping-and-enforcement.md) for server-side `withRole()` middleware, per-request client creation, admin panel operations (list members, invite users, change roles), and organization management patterns.
 
 ## Output
-- Role definitions implemented
-- SSO integration configured
-- Permission middleware active
-- Audit trail enabled
+
+After completing this skill, you will have:
+
+- **Role assignment via app_metadata** — `admin.updateUserById()` sets role claims on user JWTs
+- **JWT claim extraction** — `get_user_role()` and `get_user_org_id()` SQL helper functions
+- **Role-based RLS policies** — SELECT/INSERT/UPDATE/DELETE scoped by role hierarchy (admin > editor > member > viewer)
+- **Organization-scoped access** — multi-tenant isolation via `org_id` in JWT claims and RLS policies
+- **Application-layer enforcement** — `withRole()` middleware for API routes with proper 401/403 responses
+- **Admin panel operations** — list members, invite users, change roles with both database and JWT updates
+- **Role hierarchy checking** — `hasRole()` function supporting role escalation comparison
 
 ## Error Handling
-| Issue | Cause | Solution |
+
+| Error | Cause | Solution |
 |-------|-------|----------|
-| SSO login fails | Wrong callback URL | Verify IdP config |
-| Permission denied | Missing role mapping | Update group mappings |
-| Token expired | Short TTL | Refresh token logic |
-| Audit gaps | Async logging failed | Check log pipeline |
+| `app_metadata.role` is null in JWT | Role not set or user needs to re-login | Call `admin.updateUserById()` to set role; user must refresh their session |
+| RLS policy returns empty results | JWT claims don't match policy conditions | Check `auth.jwt()` output in SQL Editor; verify `app_metadata` was set correctly |
+| `permission denied for function` | Helper function not created or wrong schema | Create `get_user_role()` in the `public` schema with `SECURITY DEFINER` |
+| User role changes not reflected | JWT cached with old claims | User must sign out and sign in again, or call `supabase.auth.refreshSession()` |
+| `duplicate key value violates unique constraint` | User already in organization | Check `team_members` table for existing entry before inserting |
+| `foreign key violation` on team_members | User or org doesn't exist | Verify both `user_id` and `org_id` exist before inserting membership |
+| Role hierarchy bypass | Direct database access with service role | Service role bypasses RLS by design — restrict its use to server-side admin operations only |
 
 ## Examples
 
-### Quick Permission Check
+**Example 1 — Quick role check in a component:**
+
 ```typescript
-if (!checkPermission(user.role, 'write')) {
-  throw new ForbiddenError('Write permission required');
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(url, anonKey);
+
+async function canEditProject(): Promise<boolean> {
+  const { data: { user } } = await supabase.auth.getUser();
+  const role = user?.app_metadata?.role;
+  return role === 'admin' || role === 'editor';
+}
+```
+
+**Example 2 — Verify RLS policies work correctly:**
+
+```sql
+-- Test as an editor in org-123
+SET request.jwt.claims = '{"sub": "user-uuid", "role": "authenticated", "app_metadata": {"role": "editor", "org_id": "org-123"}}';
+
+-- Should return only org-123 projects
+SELECT * FROM projects;
+
+-- Should succeed (editors can create)
+INSERT INTO projects (org_id, name, created_by) VALUES ('org-123', 'Test', 'user-uuid');
+
+-- Should fail (editors cannot delete)
+DELETE FROM projects WHERE id = 'some-project-id';
+
+RESET request.jwt.claims;
+```
+
+**Example 3 — Onboard a new organization:**
+
+```typescript
+async function onboardOrganization(orgName: string, adminEmail: string) {
+  // 1. Create the organization
+  const { data: org } = await adminClient
+    .from('organizations')
+    .insert({ name: orgName, slug: orgName.toLowerCase().replace(/\s+/g, '-') })
+    .select('id')
+    .single();
+
+  // 2. Assign the creator as admin
+  const { data: { users } } = await adminClient.auth.admin.listUsers();
+  const adminUser = users.find((u) => u.email === adminEmail);
+
+  if (adminUser && org) {
+    await setUserRole(adminUser.id, 'admin', org.id);
+    await adminClient.from('team_members').insert({
+      org_id: org.id,
+      user_id: adminUser.id,
+      role: 'admin',
+    });
+  }
+
+  return org;
 }
 ```
 
 ## Resources
-- [Supabase Enterprise Guide](https://supabase.com/docs/enterprise)
-- [SAML 2.0 Specification](https://wiki.oasis-open.org/security/FrontPage)
-- [OpenID Connect Spec](https://openid.net/specs/openid-connect-core-1_0.html)
+
+- [Custom Claims and RBAC — Supabase Docs](https://supabase.com/docs/guides/database/postgres/custom-claims-and-role-based-access-control-rbac)
+- [Auth Admin updateUserById — Supabase Docs](https://supabase.com/docs/reference/javascript/auth-admin-updateuserbyid)
+- [Row Level Security — Supabase Docs](https://supabase.com/docs/guides/database/postgres/row-level-security)
+- [auth.jwt() Function — Supabase Docs](https://supabase.com/docs/guides/database/postgres/row-level-security#helper-functions)
+- [Multi-tenancy Patterns — Supabase Docs](https://supabase.com/docs/guides/getting-started/architecture#multi-tenancy)
+- [inviteUserByEmail — Supabase Docs](https://supabase.com/docs/reference/javascript/auth-admin-inviteuserbyemail)
 
 ## Next Steps
-For major migrations, see `supabase-migration-deep-dive`.
+
+- For database migration patterns, see `supabase-migration-deep-dive`
+- For security hardening and API key scoping, see `supabase-security-basics`
+- For data handling and GDPR compliance, see `supabase-data-handling`