@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-enterprise-rbac/references/api-scoping-and-enforcement.md

@@ -0,0 +1,255 @@
+# API Key Scoping and Role Enforcement
+
+Enforce roles at the application layer to complement RLS, and scope API operations by role.
+
+**Server-side role enforcement middleware:**
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+import type { NextRequest } from 'next/server';
+
+// Create a per-request client with the user's JWT
+function createRequestClient(request: NextRequest) {
+  const token = request.headers.get('Authorization')?.replace('Bearer ', '');
+
+  return createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      global: {
+        headers: { Authorization: `Bearer ${token}` },
+      },
+    }
+  );
+}
+
+// Role enforcement for API routes
+async function withRole(
+  request: NextRequest,
+  requiredRole: AppRole,
+  handler: (supabase: ReturnType<typeof createClient>, user: any) => Promise<Response>
+) {
+  const supabase = createRequestClient(request);
+
+  const { data: { user }, error } = await supabase.auth.getUser();
+  if (error || !user) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const userRole = user.app_metadata?.role as AppRole;
+  if (!userRole || !hasRole(userRole, requiredRole)) {
+    return Response.json(
+      { error: `Forbidden: requires "${requiredRole}" role` },
+      { status: 403 }
+    );
+  }
+
+  return handler(supabase, user);
+}
+
+// Usage in Next.js App Router
+export async function DELETE(request: NextRequest) {
+  return withRole(request, 'admin', async (supabase, user) => {
+    const projectId = request.nextUrl.searchParams.get('id');
+
+    const { error } = await supabase
+      .from('projects')
+      .delete()
+      .eq('id', projectId);
+
+    if (error) return Response.json({ error: error.message }, { status: 400 });
+    return Response.json({ deleted: true });
+  });
+}
+```
+
+**Admin panel — manage user roles:**
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const adminClient = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+
+// List all users in an organization with their roles
+async function listOrgMembers(orgId: string) {
+  const { data, error } = await adminClient
+    .from('team_members')
+    .select(`
+      user_id,
+      role,
+      created_at,
+      profiles!inner(email, full_name)
+    `)
+    .eq('org_id', orgId)
+    .order('created_at', { ascending: false });
+
+  if (error) throw error;
+  return data;
+}
+
+// Invite a user to an organization
+async function inviteToOrg(
+  email: string,
+  orgId: string,
+  role: AppRole,
+  invitedBy: string
+) {
+  // Create or get the user
+  const { data: existingUsers } = await adminClient
+    .from('profiles')
+    .select('id')
+    .eq('email', email)
+    .single();
+
+  const userId = existingUsers?.id;
+  if (!userId) {
+    // Send invite email via Supabase Auth
+    const { error } = await adminClient.auth.admin.inviteUserByEmail(email, {
+      data: { org_id: orgId, role },
+    });
+    if (error) throw error;
+    return { status: 'invited' };
+  }
+
+  // Add existing user to org
+  const { error } = await adminClient.from('team_members').insert({
+    org_id: orgId,
+    user_id: userId,
+    role,
+    invited_by: invitedBy,
+  });
+
+  if (error) throw error;
+
+  // Update user's app_metadata with org and role
+  await setUserRole(userId, role, orgId);
+
+  return { status: 'added', userId };
+}
+
+// Change a user's role (admin only)
+async function changeUserRole(
+  orgId: string,
+  targetUserId: string,
+  newRole: AppRole
+) {
+  // Update team_members table
+  const { error: dbError } = await adminClient
+    .from('team_members')
+    .update({ role: newRole })
+    .eq('org_id', orgId)
+    .eq('user_id', targetUserId);
+
+  if (dbError) throw dbError;
+
+  // Update JWT claims
+  await setUserRole(targetUserId, newRole, orgId);
+
+  console.log(`User ${targetUserId} role changed to "${newRole}" in org ${orgId}`);
+}
+```
+
+## Output
+
+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
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `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
+
+**Example 1 — Quick role check in a component:**
+
+```typescript
+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
+
+- [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 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`

package/skills/supabase-enterprise-rbac/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | 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 |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-enterprise-rbac/references/examples.md

@@ -0,0 +1,12 @@
+## Examples
+
+### Quick Permission Check
+
+```typescript
+if (!checkPermission(user.role, 'write')) {
+  throw new ForbiddenError('Write permission required');
+}
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-enterprise-rbac/references/role-implementation.md

@@ -0,0 +1,33 @@
+# Role Implementation
+
+## Role Implementation
+
+```typescript
+enum SupabaseRole {
+  Admin = 'admin',
+  Developer = 'developer',
+  Viewer = 'viewer',
+  Service = 'service',
+}
+
+interface SupabasePermissions {
+  read: boolean;
+  write: boolean;
+  delete: boolean;
+  admin: boolean;
+}
+
+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];
+}
+```

package/skills/supabase-enterprise-rbac/references/sso-integration.md

@@ -0,0 +1,35 @@
+# Sso Integration
+
+## SSO Integration
+
+### SAML Configuration
+
+```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,
+};
+```
+
+### 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,
+});
+```

package/skills/supabase-hello-world/SKILL.md

@@ -1,96 +1,202 @@
 ---
 name: supabase-hello-world
-description: |
-  Create a minimal working Supabase example.
-  Use when starting a new Supabase integration, testing your setup,
-  or learning basic Supabase API patterns.
-  Trigger with phrases like "supabase hello world", "supabase example",
-  "supabase quick start", "simple supabase code".
-allowed-tools: Read, Write, Edit
+description: "Run your first Supabase query \u2014 insert a row and read it back.\n\
+  Use when starting a new Supabase project, verifying your connection works,\nor learning\
+  \ the basic insert-then-select pattern with @supabase/supabase-js.\nTrigger with\
+  \ phrases like \"supabase hello world\", \"first supabase query\",\n\"supabase quick\
+  \ start\", \"test supabase connection\", \"supabase insert and select\".\n"
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(supabase:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- database
+- getting-started
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
-# Supabase Hello World
+# Supabase Hello World — First Query
 
 ## Overview
-Minimal working example demonstrating core Supabase functionality.
+
+Execute your first real Supabase query: create a `todos` table in the dashboard, insert a row with the JS client, and read it back. This validates that your project URL, anon key, and Row Level Security are configured correctly before you build anything else.
 
 ## Prerequisites
-- Completed `supabase-install-auth` setup
-- Valid API credentials configured
-- Development environment ready
+
+- Completed `supabase-install-auth` setup (project URL + anon key in `.env`)
+- `@supabase/supabase-js` v2+ installed (`npm install @supabase/supabase-js`)
+- A Supabase project at [supabase.com/dashboard](https://supabase.com/dashboard)
 
 ## Instructions
 
-### Step 1: Create Entry File
-Create a new file for your hello world example.
+### Step 1: Create the `todos` Table
+
+Open your Supabase dashboard SQL Editor and run:
+
+```sql
+-- Create a simple todos table
+create table public.todos (
+  id bigint generated always as identity primary key,
+  task text not null,
+  is_complete boolean default false,
+  inserted_at timestamptz default now()
+);
+
+-- Enable Row Level Security (required for anon key access)
+alter table public.todos enable row level security;
+
+-- Allow anyone with the anon key to read and insert
+-- (permissive for hello-world; lock down before production)
+create policy "Allow public read" on public.todos
+  for select using (true);
+
+create policy "Allow public insert" on public.todos
+  for insert with check (true);
+```
+
+Verify the table appears under **Table Editor** in the dashboard before continuing.
+
+### Step 2: Insert a Row
 
-### Step 2: Import and Initialize Client
 ```typescript
-import { SupabaseClient } from '@supabase/supabase-js';
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+)
+
+// Insert a row and return it with .select()
+const { data, error } = await supabase
+  .from('todos')
+  .insert({ task: 'Hello from Supabase!' })
+  .select()
+
+if (error) {
+  console.error('Insert failed:', error.message)
+  // e.g. "new row violates row-level security policy"
+  process.exit(1)
+}
 
-const client = new SupabaseClient({
-  apiKey: process.env.SUPABASE_API_KEY,
-});
+console.log('Inserted:', data)
+// [{ id: 1, task: "Hello from Supabase!", is_complete: false, inserted_at: "2026-03-22T..." }]
 ```
 
-### Step 3: Make Your First API Call
+Key detail: `.insert()` alone returns `{ data: null }`. You must chain `.select()` to get the inserted row back.
+
+### Step 3: Read It Back
+
 ```typescript
-async function main() {
-  const result = await supabase.from('todos').insert({ task: 'Hello!' }).select(); console.log(result.data);
+// Select all rows from todos
+const { data: todos, error: selectError } = await supabase
+  .from('todos')
+  .select('*')
+
+if (selectError) {
+  console.error('Select failed:', selectError.message)
+  process.exit(1)
 }
 
-main().catch(console.error);
+console.log('Todos:', todos)
+// [{ id: 1, task: "Hello from Supabase!", is_complete: false, inserted_at: "2026-03-22T..." }]
+
+// Verify the round-trip
+if (todos && todos.length > 0) {
+  console.log('Round-trip verified — row exists in database')
+} else {
+  console.error('No rows returned. Check RLS policies.')
+}
 ```
 
+Open the **Table Editor** in the Supabase dashboard to visually confirm the row is there.
+
 ## Output
-- Working code file with Supabase client initialization
-- Successful API response confirming connection
-- Console output showing:
-```
-Success! Your Supabase connection is working.
-```
+
+- `todos` table created with RLS enabled
+- One row inserted via the JS client
+- Same row read back with `.select('*')`
+- Dashboard confirms the data round-trip
 
 ## Error Handling
+
 | Error | Cause | Solution |
 |-------|-------|----------|
-| Import Error | SDK not installed | Verify with `npm list` or `pip show` |
-| Auth Error | Invalid credentials | Check environment variable is set |
-| Timeout | Network issues | Increase timeout or check connectivity |
-| Rate Limit | Too many requests | Wait and retry with exponential backoff |
+| `relation "public.todos" does not exist` | Table not created | Run the Step 1 SQL in the dashboard SQL Editor |
+| `new row violates row-level security policy` | RLS blocks the insert | Add the permissive insert policy from Step 1 |
+| `Invalid API key` | Wrong anon key in `.env` | Copy from Settings > API in the dashboard |
+| `FetchError: request to https://... failed` | Wrong project URL | Verify `SUPABASE_URL` matches dashboard URL |
+| `data` is `null` after insert | Missing `.select()` chain | Add `.select()` after `.insert()` |
+| Empty array returned from select | RLS blocks reads | Add the select policy from Step 1 |
 
 ## Examples
 
-### TypeScript Example
-```typescript
-import { SupabaseClient } from '@supabase/supabase-js';
-
-const client = new SupabaseClient({
-  apiKey: process.env.SUPABASE_API_KEY,
-});
+### TypeScript (Complete Script)
 
-async function main() {
-  const result = await supabase.from('todos').insert({ task: 'Hello!' }).select(); console.log(result.data);
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+)
+
+async function helloSupabase() {
+  // Insert
+  const { data: inserted, error: insertErr } = await supabase
+    .from('todos')
+    .insert({ task: 'Hello from TypeScript!' })
+    .select()
+    .single()
+
+  if (insertErr) throw new Error(`Insert: ${insertErr.message}`)
+  console.log('Inserted:', inserted)
+
+  // Read back
+  const { data: rows, error: selectErr } = await supabase
+    .from('todos')
+    .select('*')
+    .order('inserted_at', { ascending: false })
+    .limit(5)
+
+  if (selectErr) throw new Error(`Select: ${selectErr.message}`)
+  console.log('Recent todos:', rows)
 }
 
-main().catch(console.error);
+helloSupabase().catch(console.error)
 ```
 
-### Python Example
-```python
-from supabase import SupabaseClient
-
-client = SupabaseClient()
+### Python
 
-response = supabase.table('todos').insert({'task': 'Hello!'}).execute(); print(response.data)
+```python
+from supabase import create_client
+import os
+
+supabase = create_client(
+    os.environ["SUPABASE_URL"],
+    os.environ["SUPABASE_ANON_KEY"]
+)
+
+# Insert a row
+result = supabase.table("todos").insert({"task": "Hello from Python!"}).execute()
+print("Inserted:", result.data)
+# [{"id": 2, "task": "Hello from Python!", "is_complete": False, ...}]
+
+# Read it back
+result = supabase.table("todos").select("*").execute()
+print("All todos:", result.data)
 ```
 
+Install the Python client with: `pip install supabase`
+
 ## Resources
-- [Supabase Getting Started](https://supabase.com/docs/getting-started)
-- [Supabase API Reference](https://supabase.com/docs/api)
-- [Supabase Examples](https://supabase.com/docs/examples)
+
+- [Supabase Getting Started](https://supabase.com/docs/guides/getting-started)
+- [JS Client — Insert](https://supabase.com/docs/reference/javascript/insert)
+- [JS Client — Select](https://supabase.com/docs/reference/javascript/select)
+- [Python Client](https://supabase.com/docs/reference/python/introduction)
+- [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)
 
 ## Next Steps
-Proceed to `supabase-local-dev-loop` for development workflow setup.
+
+Proceed to `supabase-local-dev-loop` for local development workflow with the Supabase CLI.