@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-policy-guardrails/SKILL.md

@@ -1,257 +1,284 @@
 ---
 name: supabase-policy-guardrails
-description: |
-  Implement Supabase lint rules, policy enforcement, and automated guardrails.
-  Use when setting up code quality rules for Supabase integrations, implementing
-  pre-commit hooks, or configuring CI policy checks for Supabase best practices.
-  Trigger with phrases like "supabase policy", "supabase lint",
-  "supabase guardrails", "supabase best practices check", "supabase eslint".
-allowed-tools: Read, Write, Edit, Bash(npx:*)
-version: 1.0.0
-license: MIT
-author: Jeremy Longshore <jeremy@intentsolutions.io>
----
-
-# Supabase Policy & Guardrails
-
-## Overview
-Automated policy enforcement and guardrails for Supabase integrations.
-
-## Prerequisites
-- ESLint configured in project
-- Pre-commit hooks infrastructure
-- CI/CD pipeline with policy checks
-- TypeScript for type enforcement
-
-## ESLint Rules
-
-### Custom Supabase Plugin
-```javascript
-// eslint-plugin-supabase/rules/no-hardcoded-keys.js
-module.exports = {
-  meta: {
-    type: 'problem',
-    docs: {
-      description: 'Disallow hardcoded Supabase API keys',
-    },
-    fixable: 'code',
-  },
-  create(context) {
-    return {
-      Literal(node) {
-        if (typeof node.value === 'string') {
-          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
-            context.report({
-              node,
-              message: 'Hardcoded Supabase API key detected',
-            });
-          }
-        }
-      },
-    };
-  },
-};
-```
-
-### ESLint Configuration
-```javascript
-// .eslintrc.js
-module.exports = {
-  plugins: ['supabase'],
-  rules: {
-    'supabase/no-hardcoded-keys': 'error',
-    'supabase/require-error-handling': 'warn',
-    'supabase/use-typed-client': 'warn',
-  },
-};
-```
-
-## Pre-Commit Hooks
-
-```yaml
-# .pre-commit-config.yaml
-repos:
-  - repo: local
-    hooks:
-      - id: supabase-secrets-check
-        name: Check for Supabase secrets
-        entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0'
-        language: system
-        pass_filenames: false
-
-      - id: supabase-config-validate
-        name: Validate Supabase configuration
-        entry: node scripts/validate-supabase-config.js
-        language: node
-        files: '\.supabase\.json$'
-```
-
-## TypeScript Strict Patterns
-
-```typescript
-// Enforce typed configuration
-interface SupabaseStrictConfig {
-  apiKey: string;  // Required
-  environment: 'development' | 'staging' | 'production';  // Enum
-  timeout: number;  // Required number, not optional
-  retries: number;
-}
-
-// Disallow any in Supabase code
-// @ts-expect-error - Using any is forbidden
-const client = new Client({ apiKey: any });
-
-// Prefer this
-const client = new SupabaseClient(config satisfies SupabaseStrictConfig);
-```
-
-## Architecture Decision Records
+description: 'Enforce organizational governance for Supabase projects: shared RLS
+  policy
 
-### ADR Template
-```markdown
-# ADR-001: Supabase Client Initialization
+  library with reusable templates, table and column naming conventions,
 
-## Status
-Accepted
+  migration review process with CI checks, cost alert thresholds,
 
-## Context
-We need to decide how to initialize the Supabase client across our application.
+  and security audit scripts scanning for common misconfigurations.
 
-## Decision
-We will use the singleton pattern with lazy initialization.
+  Use when establishing Supabase standards across teams, creating RLS
 
-## Consequences
-- Pro: Single client instance, connection reuse
-- Pro: Easy to mock in tests
-- Con: Global state requires careful lifecycle management
+  policy templates, setting up migration review workflows, or auditing
 
-## Enforcement
-- ESLint rule: supabase/use-singleton-client
-- CI check: grep for "new SupabaseClient(" outside allowed files
-```
+  existing projects for security and cost issues.
 
-## Policy-as-Code (OPA)
-
-```rego
-# supabase-policy.rego
-package supabase
-
-# Deny production API keys in non-production environments
-deny[msg] {
-  input.environment != "production"
-  startswith(input.apiKey, "sk_live_")
-  msg := "Production API keys not allowed in non-production environment"
-}
-
-# Require minimum timeout
-deny[msg] {
-  input.timeout < 10000
-  msg := sprintf("Timeout too low: %d < 10000ms minimum", [input.timeout])
-}
-
-# Require retry configuration
-deny[msg] {
-  not input.retries
-  msg := "Retry configuration is required"
-}
-```
+  Trigger with phrases like "supabase governance", "supabase policy library",
 
-## CI Policy Checks
+  "supabase naming convention", "supabase migration review",
 
-```yaml
-# .github/workflows/supabase-policy.yml
-name: Supabase Policy Check
+  "supabase cost alert", "supabase security audit", "supabase RLS template".
 
-on: [push, pull_request]
+  '
+allowed-tools: Read, Write, Edit, Bash(supabase:*), Bash(psql:*), Bash(npx:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- governance
+- security
+- rls
+- naming-conventions
+- cost-management
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
+---
+# Supabase Policy Guardrails
 
-jobs:
-  policy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
+## Overview
 
-      - name: Check for hardcoded secrets
-        run: |
-          if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
-            echo "ERROR: Hardcoded Supabase keys found"
-            exit 1
-          fi
+Organizational governance for Supabase at scale: a **shared RLS policy library** (reusable templates for common access patterns), **naming conventions** (tables, columns, functions, policies), **migration review process** (CI checks ensuring RLS, preventing destructive operations, enforcing naming), **cost alert configuration** (billing thresholds and usage monitoring), and **security audit scripts** (scanning for exposed keys, missing RLS, overly permissive policies). All patterns use real `createClient` from `@supabase/supabase-js` and Supabase CLI commands.
 
-      - name: Validate configuration schema
-        run: |
-          npx ajv validate -s supabase-config.schema.json -d config/supabase/*.json
+## Prerequisites
 
-      - name: Run ESLint Supabase rules
-        run: npx eslint --plugin supabase --rule 'supabase/no-hardcoded-keys: error' src/
+- Supabase project with `supabase` CLI installed and linked
+- `@supabase/supabase-js` v2+ installed
+- CI/CD pipeline (GitHub Actions recommended)
+- Database access via `psql` or Supabase SQL Editor
+- Pro plan recommended for cost alerts and usage API
+
+## Step 1 — Shared RLS Policy Library and Naming Conventions
+
+### RLS Policy Templates
+
+Create reusable RLS policy templates that teams apply to new tables. This prevents each developer from writing ad-hoc policies and ensures consistent access control.
+
+```sql
+-- supabase/migrations/00000000000000_rls_policy_library.sql
+-- Shared RLS policy library — apply these templates to new tables
+
+-- ============================================================
+-- Template 1: Owner-only access (user owns the row)
+-- Usage: tables with a user_id column (todos, profiles, settings)
+-- ============================================================
+CREATE OR REPLACE FUNCTION public.rls_owner_only(table_name text, user_column text DEFAULT 'user_id')
+RETURNS void AS $$
+BEGIN
+  EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', table_name);
+
+  EXECUTE format(
+    'CREATE POLICY "owner_select" ON public.%I FOR SELECT USING (%I = auth.uid())',
+    table_name, user_column
+  );
+  EXECUTE format(
+    'CREATE POLICY "owner_insert" ON public.%I FOR INSERT WITH CHECK (%I = auth.uid())',
+    table_name, user_column
+  );
+  EXECUTE format(
+    'CREATE POLICY "owner_update" ON public.%I FOR UPDATE USING (%I = auth.uid())',
+    table_name, user_column
+  );
+  EXECUTE format(
+    'CREATE POLICY "owner_delete" ON public.%I FOR DELETE USING (%I = auth.uid())',
+    table_name, user_column
+  );
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================
+-- Template 2: Organization-scoped access (user is member of org)
+-- Usage: tables with org_id referencing org_members
+-- ============================================================
+CREATE OR REPLACE FUNCTION public.rls_org_scoped(
+  table_name text,
+  org_column text DEFAULT 'org_id',
+  allow_delete boolean DEFAULT false
+)
+RETURNS void AS $$
+BEGIN
+  EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', table_name);
+
+  EXECUTE format(
+    'CREATE POLICY "org_select" ON public.%I FOR SELECT USING (
+      %I IN (SELECT org_id FROM public.org_members WHERE user_id = auth.uid())
+    )', table_name, org_column
+  );
+  EXECUTE format(
+    'CREATE POLICY "org_insert" ON public.%I FOR INSERT WITH CHECK (
+      %I IN (SELECT org_id FROM public.org_members WHERE user_id = auth.uid())
+    )', table_name, org_column
+  );
+  EXECUTE format(
+    'CREATE POLICY "org_update" ON public.%I FOR UPDATE USING (
+      %I IN (SELECT org_id FROM public.org_members WHERE user_id = auth.uid() AND role IN (''admin'', ''editor''))
+    )', table_name, org_column
+  );
+
+  IF allow_delete THEN
+    EXECUTE format(
+      'CREATE POLICY "org_delete" ON public.%I FOR DELETE USING (
+        %I IN (SELECT org_id FROM public.org_members WHERE user_id = auth.uid() AND role = ''admin'')
+      )', table_name, org_column
+    );
+  END IF;
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================
+-- Template 3: Public read, authenticated write
+-- Usage: blog posts, product listings, public content
+-- ============================================================
+CREATE OR REPLACE FUNCTION public.rls_public_read_auth_write(
+  table_name text,
+  owner_column text DEFAULT 'created_by'
+)
+RETURNS void AS $$
+BEGIN
+  EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', table_name);
+
+  EXECUTE format(
+    'CREATE POLICY "public_select" ON public.%I FOR SELECT USING (true)',
+    table_name
+  );
+  EXECUTE format(
+    'CREATE POLICY "auth_insert" ON public.%I FOR INSERT WITH CHECK (auth.uid() IS NOT NULL)',
+    table_name
+  );
+  EXECUTE format(
+    'CREATE POLICY "owner_update" ON public.%I FOR UPDATE USING (%I = auth.uid())',
+    table_name, owner_column
+  );
+  EXECUTE format(
+    'CREATE POLICY "owner_delete" ON public.%I FOR DELETE USING (%I = auth.uid())',
+    table_name, owner_column
+  );
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply templates to tables:
+-- SELECT public.rls_owner_only('todos');
+-- SELECT public.rls_org_scoped('projects', 'org_id', true);
+-- SELECT public.rls_public_read_auth_write('blog_posts', 'author_id');
 ```
 
-## Runtime Guardrails
-
-```typescript
-// Prevent dangerous operations in production
-const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];
-
-function guardSupabaseOperation(operation: string): void {
-  const isProd = process.env.NODE_ENV === 'production';
-
-  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
-    throw new Error(`Operation '${operation}' blocked in production`);
-  }
-}
-
-// Rate limit protection
-function guardRateLimits(requestsInWindow: number): void {
-  const limit = parseInt(process.env.SUPABASE_RATE_LIMIT || '100');
-
-  if (requestsInWindow > limit * 0.9) {
-    console.warn('Approaching Supabase rate limit');
-  }
-
-  if (requestsInWindow >= limit) {
-    throw new Error('Supabase rate limit exceeded - request blocked');
-  }
-}
+### Naming Conventions
+
+```sql
+-- supabase/migrations/00000000000001_naming_convention_check.sql
+-- Validation function that checks naming conventions at migration time
+
+CREATE OR REPLACE FUNCTION public.validate_naming_conventions()
+RETURNS TABLE(issue text, object_name text, suggestion text) AS $$
+BEGIN
+  -- Tables must be snake_case, plural
+  RETURN QUERY
+  SELECT
+    'Table name should be plural snake_case'::text,
+    t.tablename::text,
+    regexp_replace(t.tablename, '([A-Z])', '_\1', 'g')::text
+  FROM pg_tables t
+  WHERE t.schemaname = 'public'
+  AND (
+    t.tablename ~ '[A-Z]'           -- contains uppercase
+    OR t.tablename ~ '-'             -- contains hyphens
+    OR t.tablename !~ 's$'           -- not plural (heuristic)
+  )
+  AND t.tablename NOT LIKE '\_%';   -- skip internal tables
+
+  -- Columns must be snake_case
+  RETURN QUERY
+  SELECT
+    'Column name should be snake_case'::text,
+    (c.table_name || '.' || c.column_name)::text,
+    regexp_replace(c.column_name, '([A-Z])', '_\1', 'g')::text
+  FROM information_schema.columns c
+  WHERE c.table_schema = 'public'
+  AND (c.column_name ~ '[A-Z]' OR c.column_name ~ '-');
+
+  -- Foreign key columns should end with _id
+  RETURN QUERY
+  SELECT
+    'Foreign key column should end with _id'::text,
+    (tc.table_name || '.' || kcu.column_name)::text,
+    (kcu.column_name || '_id')::text
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name
+  WHERE tc.constraint_type = 'FOREIGN KEY'
+  AND tc.table_schema = 'public'
+  AND kcu.column_name NOT LIKE '%_id';
+
+  -- Boolean columns should start with is_ or has_
+  RETURN QUERY
+  SELECT
+    'Boolean column should start with is_ or has_'::text,
+    (c.table_name || '.' || c.column_name)::text,
+    ('is_' || c.column_name)::text
+  FROM information_schema.columns c
+  WHERE c.table_schema = 'public'
+  AND c.data_type = 'boolean'
+  AND c.column_name NOT LIKE 'is_%'
+  AND c.column_name NOT LIKE 'has_%';
+END;
+$$ LANGUAGE plpgsql;
+
+-- Run: SELECT * FROM public.validate_naming_conventions();
 ```
 
-## Instructions
-
-### Step 1: Create ESLint Rules
-Implement custom lint rules for Supabase patterns.
+### Naming Convention Reference
 
-### Step 2: Configure Pre-Commit Hooks
-Set up hooks to catch issues before commit.
+| Object | Convention | Example |
+|--------|-----------|---------|
+| Tables | Plural snake_case | `user_profiles`, `order_items` |
+| Columns | snake_case | `created_at`, `full_name` |
+| Foreign keys | `{referenced_table_singular}_id` | `user_id`, `order_id` |
+| Booleans | `is_` or `has_` prefix | `is_active`, `has_verified_email` |
+| Timestamps | `_at` suffix | `created_at`, `updated_at`, `deleted_at` |
+| RLS policies | `{scope}_{operation}` | `owner_select`, `org_insert` |
+| Functions | `verb_noun` | `create_user`, `get_dashboard_metrics` |
+| Indexes | `idx_{table}_{columns}` | `idx_orders_user_id_created_at` |
+| Migrations | `{timestamp}_{verb}_{description}` | `20250322000000_create_orders_table.sql` |
 
-### Step 3: Add CI Policy Checks
-Implement policy-as-code in CI pipeline.
+## Step 2 — Migration Review Process with CI Checks
 
-### Step 4: Enable Runtime Guardrails
-Add production safeguards for dangerous operations.
+See [CI checks, cost alerts, and security audits](references/ci-cost-security.md) for GitHub Actions migration guardrails (RLS enforcement, naming checks, destructive operation blocks), pre-commit hooks, cost monitoring with Slack alerts, security audit scripts, and scheduled Edge Function audits.
 
 ## Output
-- ESLint plugin with Supabase rules
-- Pre-commit hooks blocking secrets
-- CI policy checks passing
-- Runtime guardrails active
+
+- Shared RLS policy library with owner-only, org-scoped, and public-read templates
+- Naming convention validation function checking tables, columns, FKs, and booleans
+- CI pipeline enforcing RLS, naming, and destructive operation controls
+- Pre-commit hook blocking hardcoded secrets and tables without RLS
+- Cost monitoring script with configurable thresholds and Slack alerting
+- Security audit script detecting missing RLS, permissive policies, and missing indexes
+- Scheduled Edge Function for continuous security monitoring
 
 ## Error Handling
+
 | Issue | Cause | Solution |
 |-------|-------|----------|
-| ESLint rule not firing | Wrong config | Check plugin registration |
-| Pre-commit skipped | --no-verify | Enforce in CI |
-| Policy false positive | Regex too broad | Narrow pattern match |
-| Guardrail triggered | Actual issue | Fix or whitelist |
+| CI RLS check fails on new table | Migration missing `ENABLE ROW LEVEL SECURITY` | Add `ALTER TABLE` after `CREATE TABLE` in same migration |
+| Naming convention false positive | Table is intentionally singular (e.g., `config`) | Add to exclusion list in validation function |
+| Cost alert not firing | Missing `SUPABASE_ACCESS_TOKEN` | Generate token at supabase.com/dashboard/account/tokens |
+| Security audit times out | Too many tables to scan | Run audit on specific schemas or paginate results |
+| Pre-commit blocks legitimate JWT in test | Test fixture contains JWT-like string | Add test file path to exclusion pattern |
+| RLS template function not found | Migration not applied | Run `supabase db reset` or apply migration manually |
 
 ## Examples
 
-### Quick ESLint Check
-```bash
-npx eslint --plugin supabase --rule 'supabase/no-hardcoded-keys: error' src/
-```
+See [CI, cost, and security reference](references/ci-cost-security.md) for full examples including applying RLS templates, running security audits, and checking naming conventions.
 
 ## Resources
-- [ESLint Plugin Development](https://eslint.org/docs/latest/extend/plugins)
-- [Pre-commit Framework](https://pre-commit.com/)
-- [Open Policy Agent](https://www.openpolicyagent.org/)
+
+- [Supabase Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)
+- [Supabase CLI Migrations](https://supabase.com/docs/guides/cli/managing-environments)
+- [Supabase Management API](https://supabase.com/docs/reference/api/introduction)
+- [Supabase Pricing](https://supabase.com/pricing)
+- [PostgreSQL Naming Conventions](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)
 
 ## Next Steps
-For architecture blueprints, see `supabase-architecture-variants`.
+
+For architecture patterns across different app types, see `supabase-architecture-variants`.