@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-webhooks-events/references/event-handler-pattern.md

@@ -0,0 +1,106 @@
+# Event Handler Pattern
+
+## Typed Event Dispatcher
+
+A registry-based pattern for routing Supabase webhook events to typed handlers. This eliminates switch statements and makes adding new event handlers declarative.
+
+```typescript
+// types.ts
+type EventType = "INSERT" | "UPDATE" | "DELETE";
+
+interface WebhookPayload<T = Record<string, unknown>> {
+  type: EventType;
+  table: string;
+  schema: string;
+  record: T;
+  old_record: T | null;
+}
+
+type EventHandler<T = Record<string, unknown>> = (
+  payload: WebhookPayload<T>
+) => Promise<void>;
+
+interface HandlerRegistration {
+  table: string;
+  event: EventType | "*";
+  handler: EventHandler;
+}
+```
+
+## Dispatcher Implementation
+
+```typescript
+// event-dispatcher.ts
+class EventDispatcher {
+  private handlers: HandlerRegistration[] = [];
+
+  on(table: string, event: EventType | "*", handler: EventHandler): void {
+    this.handlers.push({ table, event, handler });
+  }
+
+  async dispatch(payload: WebhookPayload): Promise<void> {
+    const matched = this.handlers.filter(
+      (h) =>
+        h.table === payload.table &&
+        (h.event === "*" || h.event === payload.type)
+    );
+
+    if (matched.length === 0) {
+      console.warn(
+        `No handler for ${payload.type} on ${payload.table}`
+      );
+      return;
+    }
+
+    // Run all matched handlers concurrently
+    const results = await Promise.allSettled(
+      matched.map((h) => h.handler(payload))
+    );
+
+    for (const result of results) {
+      if (result.status === "rejected") {
+        console.error("Handler failed:", result.reason);
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+```typescript
+// Register handlers
+const dispatcher = new EventDispatcher();
+
+dispatcher.on("orders", "INSERT", async (payload) => {
+  await sendOrderConfirmationEmail(payload.record.email);
+  await updateInventoryCount(payload.record.product_id, -1);
+});
+
+dispatcher.on("orders", "UPDATE", async (payload) => {
+  if (payload.old_record?.status !== payload.record.status) {
+    await notifyStatusChange(payload.record);
+  }
+});
+
+dispatcher.on("profiles", "*", async (payload) => {
+  await syncToExternalCRM(payload.record);
+});
+
+// In your Edge Function serve() handler:
+serve(async (req) => {
+  const payload: WebhookPayload = await req.json();
+  await dispatcher.dispatch(payload);
+  return new Response(JSON.stringify({ ok: true }));
+});
+```
+
+## Benefits
+
+- **Type safety**: each handler receives typed payloads
+- **Separation of concerns**: one handler per side effect
+- **Testable**: handlers are pure async functions, easy to unit test
+- **Extensible**: add new handlers without modifying dispatch logic
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-webhooks-events/references/examples.md

@@ -0,0 +1,133 @@
+# Examples
+
+## Testing Webhooks Locally
+
+### 1. Start Supabase Locally
+
+```bash
+supabase start
+# Note the API URL and service_role key from output
+```
+
+### 2. Expose Local Edge Function with ngrok
+
+```bash
+# Serve the Edge Function locally
+supabase functions serve on-order-created --env-file .env.local
+
+# In another terminal, expose it
+ngrok http 54321
+# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
+```
+
+### 3. Create the Trigger Pointing to ngrok
+
+```sql
+-- In local psql or Supabase SQL editor
+CREATE OR REPLACE FUNCTION public.test_webhook()
+RETURNS trigger AS $$
+BEGIN
+  PERFORM net.http_post(
+    url     := 'https://abc123.ngrok.io/functions/v1/on-order-created',
+    headers := '{"Content-Type": "application/json"}'::jsonb,
+    body    := jsonb_build_object('type', TG_OP, 'record', row_to_json(NEW)::jsonb)
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER test_webhook_trigger
+  AFTER INSERT ON public.orders
+  FOR EACH ROW EXECUTE FUNCTION public.test_webhook();
+```
+
+### 4. Trigger the Event
+
+```bash
+# Insert a row to fire the webhook
+curl -X POST 'http://localhost:54321/rest/v1/orders' \
+  -H "apikey: <anon-key>" \
+  -H "Authorization: Bearer <anon-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"product_id": 1, "quantity": 2, "status": "pending"}'
+```
+
+### 5. Verify in ngrok Dashboard
+
+Open `http://localhost:4040` to see the webhook request in ngrok's inspector.
+
+## Manual Webhook Testing with curl
+
+```bash
+# Simulate an INSERT webhook payload
+curl -X POST http://localhost:54321/functions/v1/on-order-created \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <service-role-key>" \
+  -d '{
+    "type": "INSERT",
+    "table": "orders",
+    "schema": "public",
+    "record": {"id": 42, "product_id": 1, "quantity": 2, "status": "pending"},
+    "old_record": null
+  }'
+
+# Simulate an UPDATE webhook payload
+curl -X POST http://localhost:54321/functions/v1/on-order-created \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <service-role-key>" \
+  -d '{
+    "type": "UPDATE",
+    "table": "orders",
+    "schema": "public",
+    "record": {"id": 42, "product_id": 1, "quantity": 2, "status": "shipped"},
+    "old_record": {"id": 42, "product_id": 1, "quantity": 2, "status": "pending"}
+  }'
+```
+
+## Realtime Subscription Test (Browser Console)
+
+```javascript
+// Paste in browser console with Supabase JS loaded
+const { createClient } = supabase;
+const client = createClient(
+  "http://localhost:54321",
+  "<anon-key>"
+);
+
+client
+  .channel("test")
+  .on("postgres_changes", { event: "*", schema: "public", table: "orders" },
+    (payload) => console.log("Realtime event:", payload)
+  )
+  .subscribe((status) => console.log("Status:", status));
+
+// Now insert a row via curl or the dashboard — you should see the event logged
+```
+
+## Auth Hook Test (Custom JWT Claims)
+
+```sql
+-- Create a user role mapping
+INSERT INTO public.user_roles (user_id, role) VALUES
+  ('<user-uuid>', 'admin');
+
+-- Create the custom claims hook
+CREATE OR REPLACE FUNCTION public.custom_access_token_hook(event jsonb)
+RETURNS jsonb AS $$
+DECLARE
+  user_role text;
+BEGIN
+  SELECT role INTO user_role
+  FROM public.user_roles
+  WHERE user_id = (event->>'user_id')::uuid;
+
+  event := jsonb_set(event, '{claims,user_role}', to_jsonb(COALESCE(user_role, 'user')));
+  RETURN event;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- Enable in Dashboard > Auth > Hooks > Custom Access Token
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-webhooks-events/references/signature-verification.md

@@ -0,0 +1,165 @@
+# Signature Verification
+
+## Why Verify Webhook Signatures
+
+Any public Edge Function URL can receive HTTP requests from anyone. Without signature verification, an attacker could send fake webhook payloads to trigger unintended side effects (creating orders, modifying data, sending emails). Always verify the HMAC signature before processing.
+
+## Deno (Edge Functions)
+
+```typescript
+// Deno-native using Web Crypto API (no npm dependencies)
+async function verifyWebhookSignature(
+  rawBody: string,
+  signature: string,
+  secret: string
+): Promise<boolean> {
+  const encoder = new TextEncoder();
+
+  // Import the secret as an HMAC key
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+
+  // Sign the raw body
+  const signed = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(rawBody)
+  );
+
+  // Convert to hex string
+  const expected = Array.from(new Uint8Array(signed))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+
+  // Constant-time comparison to prevent timing attacks
+  if (signature.length !== expected.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < signature.length; i++) {
+    mismatch |= signature.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+
+// Usage in Edge Function
+serve(async (req) => {
+  const secret = Deno.env.get("WEBHOOK_SECRET")!;
+  const body = await req.text();
+  const sig = req.headers.get("x-webhook-signature") ?? "";
+
+  if (!(await verifyWebhookSignature(body, sig, secret))) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  const payload = JSON.parse(body);
+  // ... process verified payload
+});
+```
+
+## Node.js (External Webhook Receivers)
+
+```typescript
+import crypto from "node:crypto";
+
+function verifySupabaseSignature(
+  rawBody: Buffer | string,
+  signature: string,
+  timestamp: string,
+  secret: string
+): boolean {
+  // Reject old timestamps (replay attack protection — 5 min window)
+  const age = Date.now() - parseInt(timestamp, 10) * 1000;
+  if (age > 300_000) {
+    console.error("Webhook timestamp too old:", age, "ms");
+    return false;
+  }
+
+  // Compute expected HMAC using timestamp.body format
+  const signedPayload = `${timestamp}.${rawBody.toString()}`;
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(signedPayload)
+    .digest("hex");
+
+  // Timing-safe comparison
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+
+// Usage in Express
+app.post("/webhook/supabase", (req, res) => {
+  const signature = req.headers["x-webhook-signature"] as string;
+  const timestamp = req.headers["x-webhook-timestamp"] as string;
+
+  if (!verifySupabaseSignature(req.body, signature, timestamp, WEBHOOK_SECRET)) {
+    return res.status(401).json({ error: "Invalid signature" });
+  }
+
+  const payload = JSON.parse(req.body.toString());
+  // ... process verified payload
+  res.json({ ok: true });
+});
+```
+
+## Generating the Webhook Secret
+
+```bash
+# Generate a secure random secret
+openssl rand -hex 32
+# Example: a1b2c3d4e5f6...
+
+# Set as Edge Function secret
+supabase secrets set WEBHOOK_SECRET=a1b2c3d4e5f6...
+
+# Set in the trigger function (use Supabase Vault for production)
+-- Dashboard > SQL Editor
+SELECT vault.create_secret('a1b2c3d4e5f6...', 'webhook_secret');
+```
+
+## Signing Outgoing Webhooks from Triggers
+
+If you need the trigger to sign the payload so the receiver can verify:
+
+```sql
+CREATE OR REPLACE FUNCTION public.signed_webhook()
+RETURNS trigger AS $$
+DECLARE
+  payload jsonb;
+  secret text;
+  signature text;
+BEGIN
+  payload := jsonb_build_object('type', TG_OP, 'record', row_to_json(NEW)::jsonb);
+
+  -- Retrieve secret from Vault
+  SELECT decrypted_secret INTO secret
+  FROM vault.decrypted_secrets
+  WHERE name = 'webhook_secret';
+
+  -- Compute HMAC-SHA256 signature
+  signature := encode(
+    hmac(payload::text, secret, 'sha256'),
+    'hex'
+  );
+
+  PERFORM net.http_post(
+    url     := 'https://your-receiver.com/webhook',
+    headers := jsonb_build_object(
+      'Content-Type', 'application/json',
+      'x-webhook-signature', signature
+    ),
+    body    := payload
+  );
+
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*