@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/supabase/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: supabase
+
+should_trigger:
+  - prompt: "My Supabase RLS policy returns no rows even though the data is there."
+    why: Core empty-result debugging — RLS, role scope, or data-API exposure; the central confusion this skill exists to resolve.
+  - prompt: "Set up cookie-based auth with Supabase in my Next.js app router."
+    why: SSR auth wiring with @supabase/ssr — browser/server clients plus mandatory middleware token refresh.
+  - prompt: "configura Supabase con Next.js y protege las rutas del servidor"
+    why: Spanish phrasing of the SSR auth + route-protection task; must still route to supabase.
+  - prompt: "Should I use Realtime Broadcast or Postgres Changes for a presence feature?"
+    why: Non-obvious architecture choice — the right answer (default to Broadcast, Postgres Changes doesn't fan out) is Supabase-specific knowledge.
+  - prompt: "Write an Edge Function that inserts a row using the service role key."
+    why: Edge Functions plus the key trust boundary — when bypassing RLS with service_role is and isn't appropriate.
+  - prompt: "Is it safe to put the Supabase anon key in my client bundle?"
+    why: Non-obvious trust-boundary question — yes, but only because RLS gates rows; tests the core mental model.
+  - prompt: "Should I verify the Supabase JWT locally with getClaims or hit the Auth server with getUser to protect my server routes?"
+    why: Non-obvious 2026 decision — getClaims() is the documented default (local JWK verify, asymmetric keys); getUser() is the higher-cost fallback for live ban/delete detection.
+
+should_not_trigger:
+  - prompt: "Add a composite index and tune this slow Postgres query with EXPLAIN."
+    route_to: postgresdb
+    why: Engine-level query tuning with no Supabase layer.
+  - prompt: "Define my schema in TypeScript with Drizzle and run typed queries."
+    route_to: drizzle-orm
+    why: ORM-first data access; Drizzle can sit on top of Supabase Postgres but the question is about the ORM.
+  - prompt: "Write Firestore security rules for my Firebase app."
+    route_to: firebase
+    why: Different BaaS (Google) — Firestore rules, not Postgres RLS.
+  - prompt: "Why is my Next.js page not revalidating with the App Router cache?"
+    route_to: nextjs
+    why: Framework caching mechanics, not Supabase client/auth wiring.
+
+capability:
+  - scenario: "Design the data layer for a multi-tenant SaaS on Supabase: orgs, members, per-org rows, file uploads, and a Next.js frontend."
+    must_include:
+      - anon/publishable (browser, RLS-gated) vs service_role/secret (server-only, bypasses RLS) boundary
+      - "enable row level security on tables, policies scoped to authenticated"
+      - "wrapping auth.uid() as (select auth.uid()) and indexing policy columns"
+      - membership/team_id authorization via a security-definer helper or join (not a per-row correlated subquery)
+      - "@supabase/ssr browser + server clients, middleware token refresh, getClaims() not getSession() for server-side gating (getUser() only when live ban/delete detection is needed)"
+      - storage bucket RLS on storage.objects (private bucket + signed URLs)
+      - note that a table must be exposed to the data API or PostgREST returns empty results

package/skills/shared/supabase/references/auth-ssr.md

@@ -0,0 +1,173 @@
+# Cookie-based Auth with @supabase/ssr (Next.js App Router)
+
+Full wiring for server-side auth. The package is `@supabase/ssr` (it replaced `@supabase/auth-helpers`).
+Three clients plus middleware; the rule everywhere is **`getClaims()` for authorization, never
+`getSession()`**. `getClaims()` verifies the JWT signature locally against your project's published
+public keys — the documented default since new projects sign with asymmetric keys (2025-10-01 onward).
+Keep `getUser()` as the strict, higher-cost fallback for when you need to catch a banned or deleted
+user mid-session (it round-trips to the Auth server on every call). On a legacy project still using a
+symmetric JWT secret, `getClaims()` transparently falls back to that same round-trip.
+
+## lib/supabase/client.ts (browser)
+
+```ts
+import { createBrowserClient } from "@supabase/ssr";
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  );
+}
+```
+
+## lib/supabase/server.ts (Server Components / Route Handlers / Server Actions)
+
+```ts
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+export async function createClient() {
+  const cookieStore = await cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => cookieStore.getAll(),
+        setAll: (toSet) => {
+          try {
+            toSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options),
+            );
+          } catch {
+            // Called from a Server Component — cookies are read-only here.
+            // Safe to ignore: middleware refreshes the session.
+          }
+        },
+      },
+    },
+  );
+}
+```
+
+## middleware.ts (mandatory — refreshes expired tokens)
+
+Server Components can't write cookies, so the *only* place an expired access token gets refreshed is
+middleware. Without this, sessions silently expire mid-session.
+
+```ts
+import { createServerClient } from "@supabase/ssr";
+import { NextResponse, type NextRequest } from "next/server";
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request });
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => request.cookies.getAll(),
+        setAll: (toSet) => {
+          toSet.forEach(({ name, value }) => request.cookies.set(name, value));
+          response = NextResponse.next({ request });
+          toSet.forEach(({ name, value, options }) =>
+            response.cookies.set(name, value, options),
+          );
+        },
+      },
+    },
+  );
+
+  // IMPORTANT: getClaims() verifies the JWT signature locally (asymmetric keys,
+  // default for new projects) — the lower-latency default. Swap to getUser() only
+  // if you need strict per-request revalidation against the Auth server (live
+  // ban/delete detection). Do not put logic between createServerClient and this call.
+  const { data } = await supabase.auth.getClaims();
+  const user = data?.claims;
+
+  if (!user && !request.nextUrl.pathname.startsWith("/login")) {
+    const url = request.nextUrl.clone();
+    url.pathname = "/login";
+    return NextResponse.redirect(url);
+  }
+  return response;
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+## Server-action sign-in / sign-out
+
+```ts
+"use server";
+import { createClient } from "@/lib/supabase/server";
+import { redirect } from "next/navigation";
+
+export async function signIn(formData: FormData) {
+  const supabase = await createClient();
+  const { error } = await supabase.auth.signInWithPassword({
+    email: String(formData.get("email")),
+    password: String(formData.get("password")),
+  });
+  if (error) return { error: error.message };
+  redirect("/dashboard");
+}
+
+export async function signOut() {
+  const supabase = await createClient();
+  await supabase.auth.signOut();
+  redirect("/login");
+}
+```
+
+## OAuth + PKCE callback route
+
+OAuth (and magic-link) flows use PKCE: the provider redirects back with a `code` you exchange for a
+session. Add a route handler at `/auth/callback`.
+
+```ts
+import { createClient } from "@/lib/supabase/server";
+import { NextResponse } from "next/server";
+
+export async function GET(request: Request) {
+  const { searchParams, origin } = new URL(request.url);
+  const code = searchParams.get("code");
+  const next = searchParams.get("next") ?? "/";
+
+  if (code) {
+    const supabase = await createClient();
+    const { error } = await supabase.auth.exchangeCodeForSession(code);
+    if (!error) return NextResponse.redirect(`${origin}${next}`);
+  }
+  return NextResponse.redirect(`${origin}/auth/auth-code-error`);
+}
+```
+
+## Protecting a Server Component
+
+```ts
+const supabase = await createClient();
+const { data } = await supabase.auth.getClaims(); // local JWK verify; never getSession() here
+if (!data?.claims) redirect("/login");
+// Need to catch a just-banned/deleted user this request? Use getUser() instead (Auth round-trip).
+```
+
+## auth-helpers → @supabase/ssr migration checklist
+
+- Remove `@supabase/auth-helpers-nextjs`; install `@supabase/ssr`.
+- Replace `createClientComponentClient` → `createBrowserClient` (lib/supabase/client.ts).
+- Replace `createServerComponentClient` / `createRouteHandlerClient` → `createServerClient` with the
+  `getAll`/`setAll` cookie adapter (lib/supabase/server.ts).
+- Add `middleware.ts` for token refresh — this was implicit before and is now explicit.
+- Audit every server-side `getSession()` and switch authorization checks to `getClaims()` (keep
+  `getUser()` only where live ban/delete detection is required).
+
+## SvelteKit / Remix
+
+Same `@supabase/ssr` package and the same `getClaims()` rule. SvelteKit: create the server client in
+`hooks.server.ts`, refresh in the handle hook, expose via `event.locals`. Remix: create the client per
+request in the loader/action with the `getAll`/`setAll` adapter backed by Remix's cookie session.

package/skills/shared/supabase/references/rls-cookbook.md

@@ -0,0 +1,122 @@
+# RLS cookbook
+
+Concrete Row Level Security patterns. Every policy assumes RLS is enabled on the table
+(`alter table X enable row level security;`) and is scoped `to authenticated` unless a public-read case
+explicitly needs `anon`. Always pair owner/tenant predicates with an index on the filtered column.
+
+## Owner-only (per-user rows)
+
+```sql
+alter table documents enable row level security;
+
+create policy "owner full access" on documents
+  for all to authenticated
+  using ( user_id = (select auth.uid()) )
+  with check ( user_id = (select auth.uid()) );
+
+create index on documents (user_id);
+```
+
+`using` gates which rows are *visible* (select/update/delete); `with check` gates what *new/updated*
+rows are allowed (insert/update). Set both or an update can move a row out of your reach.
+
+## Multi-tenant (team_id via membership table)
+
+Don't inline a correlated subquery against the membership table in every policy — it re-runs per row.
+Use a `security definer` helper that runs once and is safe to index against.
+
+```sql
+create table memberships (
+  user_id uuid not null references auth.users (id),
+  team_id uuid not null references teams (id),
+  primary key (user_id, team_id)
+);
+
+-- security definer: runs with the function owner's rights, bypassing RLS on memberships,
+-- so the helper itself doesn't recurse. Lock down its search_path.
+create or replace function is_team_member(target_team uuid)
+returns boolean
+language sql
+security definer
+set search_path = ''
+stable
+as $$
+  select exists (
+    select 1 from public.memberships m
+    where m.team_id = target_team
+      and m.user_id = (select auth.uid())
+  );
+$$;
+
+create policy "team members read" on projects
+  for select to authenticated
+  using ( is_team_member(team_id) );
+
+create index on projects (team_id);
+create index on memberships (user_id, team_id);
+```
+
+## Public-read, private-write
+
+```sql
+-- anyone (even anon) may read published rows
+create policy "public reads published" on posts
+  for select to anon, authenticated
+  using ( status = 'published' );
+
+-- only the author may write
+create policy "author writes" on posts
+  for all to authenticated
+  using ( author_id = (select auth.uid()) )
+  with check ( author_id = (select auth.uid()) );
+```
+
+## Storage object policies
+
+`storage.objects` is a normal table; policy it the same way. Convention: prefix paths with the owner id
+so the policy can parse it.
+
+```sql
+create policy "users manage own avatar folder" on storage.objects
+  for all to authenticated
+  using (
+    bucket_id = 'avatars'
+    and (storage.foldername(name))[1] = (select auth.uid())::text
+  )
+  with check (
+    bucket_id = 'avatars'
+    and (storage.foldername(name))[1] = (select auth.uid())::text
+  );
+```
+
+## Realtime private channel (realtime.messages)
+
+Private Broadcast/Presence channels are authorized by RLS on `realtime.messages`. The channel name is
+available as `realtime.topic()`.
+
+```sql
+create policy "members read room broadcasts" on realtime.messages
+  for select to authenticated
+  using ( is_team_member( (realtime.topic())::uuid ) );
+
+create policy "members write room broadcasts" on realtime.messages
+  for insert to authenticated
+  with check ( is_team_member( (realtime.topic())::uuid ) );
+```
+
+## Testing a policy locally
+
+Simulate an authenticated request inside `psql` / a migration test by switching role and faking the JWT
+claims that `auth.uid()` reads.
+
+```sql
+begin;
+  set local role authenticated;
+  set local request.jwt.claims = '{"sub":"00000000-0000-0000-0000-000000000001"}';
+
+  -- auth.uid() now returns that sub; run the query you expect a user to make
+  select * from documents;        -- should return only that user's rows
+rollback;
+```
+
+Reset with `reset role;`. Run the same query as `anon` to confirm it returns nothing where it should.

package/skills/shared/supabase/scripts/verify.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# verify.sh — Supabase repo footgun gate.
+#
+# Usage:
+#   bash scripts/verify.sh [TARGET_DIR]    # defaults to the current directory
+#
+# Read-only: it only greps the working tree, writes nothing, makes no network
+# calls, runs no installs. Safe to re-run and safe in CI / pre-commit.
+#
+# Exit codes:
+#   0  clean, OR only warnings found, OR target has no relevant files (no false failure)
+#   1  HARD violation: a service_role / sb_secret_ key string in a client-reachable file
+#
+# Checks:
+#   HARD  service_role / sb_secret_ in a file that is client-reachable
+#         (contains "use client", or lives under app/ pages/ components/ src/components/)
+#   WARN  getSession() used in server/middleware code for gating
+#   WARN  create policy referencing bare auth.uid()/auth.jwt() without (select ...)
+#   WARN  create table in a migration with no nearby `enable row level security`
+#
+# Targets stock macOS bash 3.2: no mapfile, no associative arrays, arrays
+# initialised before use, set -e intentionally off (each check owns its status).
+
+set -u
+
+TARGET="${1:-.}"
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+hard=0
+warns=0
+
+hardfail() { printf '%s\n' "${RED}LEAK: $1${RESET}"; hard=$((hard + 1)); }
+warn()     { printf '%s\n' "${YELLOW}WARN: $1${RESET}"; warns=$((warns + 1)); }
+ok()       { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+if [ ! -d "$TARGET" ]; then
+  printf '%s\n' "${YELLOW}SKIP: target '$TARGET' is not a directory; nothing to check.${RESET}"
+  exit 0
+fi
+
+# Collect candidate source files (exclude vendor/build/VCS dirs). Newline-delimited.
+# `|| true` so an empty match never trips set -e-like behaviour.
+files="$(find "$TARGET" \
+  \( -name node_modules -o -name .git -o -name .next -o -name dist -o -name build -o -name .vercel \) -prune -o \
+  -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.sql' -o -name '*.env*' \) -print \
+  2>/dev/null || true)"
+
+if [ -z "$files" ]; then
+  ok "no JS/TS/SQL/env files under '$TARGET' — nothing to verify."
+  exit 0
+fi
+
+# --- HARD: service_role / sb_secret_ in client-reachable files ----------------
+# A file is client-reachable if it declares "use client" OR sits in a client path.
+printf '%s\n' "$files" | while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  grep -Eqi 'service_?role|sb_secret_' "$f" 2>/dev/null || continue
+  client=0
+  grep -q '"use client"' "$f" 2>/dev/null && client=1
+  case "$f" in
+    */components/*|*/src/components/*|*/pages/*) client=1 ;;
+  esac
+  # app/ is client-reachable except server-only files (route handlers / actions are
+  # ambiguous; flag and let the human confirm) — be conservative: only flag app/ when
+  # the file also imports the browser client or declares use client.
+  case "$f" in
+    */app/*) grep -Eq '"use client"|createBrowserClient' "$f" 2>/dev/null && client=1 ;;
+  esac
+  if [ "$client" -eq 1 ]; then
+    printf 'HARDHIT\t%s\n' "$f"
+  fi
+done > /tmp/supabase_verify_hard.$$ 2>/dev/null || true
+
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  f="${line#HARDHIT	}"
+  hardfail "service_role/sb_secret_ in client-reachable file: $f"
+done < /tmp/supabase_verify_hard.$$
+rm -f /tmp/supabase_verify_hard.$$ 2>/dev/null || true
+
+# --- WARN: getSession() in server/middleware code -----------------------------
+printf '%s\n' "$files" | while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  case "$f" in
+    *middleware.*|*/server.ts|*/server.tsx|*/app/*|*/lib/*) ;;
+    *) continue ;;
+  esac
+  grep -q 'getSession(' "$f" 2>/dev/null && printf 'WARNHIT\t%s\n' "$f"
+done > /tmp/supabase_verify_w1.$$ 2>/dev/null || true
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  f="${line#WARNHIT	}"
+  warn "getSession() in server/middleware file (use getClaims() for authorization; getUser() only for live ban/delete detection): $f"
+done < /tmp/supabase_verify_w1.$$
+rm -f /tmp/supabase_verify_w1.$$ 2>/dev/null || true
+
+# --- WARN: create policy with bare auth.uid()/auth.jwt() ----------------------
+# Heuristic: a .sql file that has create policy AND a bare auth.uid()/auth.jwt()
+# not preceded by `select `. Per-file granularity (line context is unreliable in bash 3.2).
+printf '%s\n' "$files" | while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  case "$f" in *.sql) ;; *) continue ;; esac
+  grep -qi 'create policy' "$f" 2>/dev/null || continue
+  # bare call = auth.uid()/auth.jwt() that is NOT immediately preceded by "select "
+  if grep -Eiq '(^|[^t][^ ]?)(auth\.(uid|jwt)\(\))' "$f" 2>/dev/null \
+     && grep -Eiq '[^(] *auth\.(uid|jwt)\(\)' "$f" 2>/dev/null \
+     && ! grep -Eiq 'select +auth\.(uid|jwt)\(\)' "$f" 2>/dev/null; then
+    printf 'WARNHIT\t%s\n' "$f"
+  fi
+done > /tmp/supabase_verify_w2.$$ 2>/dev/null || true
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  f="${line#WARNHIT	}"
+  warn "policy uses bare auth.uid()/auth.jwt() — wrap as (select auth.uid()) for per-statement caching: $f"
+done < /tmp/supabase_verify_w2.$$
+rm -f /tmp/supabase_verify_w2.$$ 2>/dev/null || true
+
+# --- WARN: create table with no enable row level security in same file --------
+printf '%s\n' "$files" | while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  case "$f" in *.sql) ;; *) continue ;; esac
+  grep -qi 'create table' "$f" 2>/dev/null || continue
+  grep -qi 'enable row level security' "$f" 2>/dev/null && continue
+  printf 'WARNHIT\t%s\n' "$f"
+done > /tmp/supabase_verify_w3.$$ 2>/dev/null || true
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  f="${line#WARNHIT	}"
+  warn "migration creates a table but has no 'enable row level security' — exposed tables default to no protection: $f"
+done < /tmp/supabase_verify_w3.$$
+rm -f /tmp/supabase_verify_w3.$$ 2>/dev/null || true
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$hard" -gt 0 ]; then
+  printf '%s\n' "${RED}FAIL: $hard hard violation(s), $warns warning(s).${RESET}"
+  exit 1
+fi
+if [ "$warns" -gt 0 ]; then
+  printf '%s\n' "${YELLOW}PASS with $warns warning(s) to review.${RESET}"
+  exit 0
+fi
+ok "no Supabase footguns detected."
+exit 0