@supabase/server 0.1.1 → 0.1.2

package/docs/ssr-frameworks.md

@@ -0,0 +1,330 @@
+# SSR Frameworks
+
+## When you need this
+
+In SSR frameworks like Next.js, Nuxt, SvelteKit, and Remix, the user's JWT doesn't arrive in an `Authorization` header — it's stored in session cookies managed by `@supabase/ssr`. The high-level wrappers (`withSupabase`, `createSupabaseContext`) expect a standard `Request` with auth headers, so they don't work directly in SSR contexts.
+
+Instead, use the [core primitives](core-primitives.md) to build a lightweight adapter for your framework. The pattern is the same everywhere — only the cookie-reading part changes.
+
+## The pattern
+
+Every SSR adapter follows these steps:
+
+1. **Extract the access token from cookies** (framework-specific)
+2. **Bridge environment variables** to the `SupabaseEnv` shape
+3. **Resolve JWKS** for JWT verification
+4. **Call `verifyCredentials`** with the extracted token
+5. **Create clients** with `createContextClient` + `createAdminClient`
+6. **Return a `SupabaseContext`**
+
+## Reading Supabase session cookies
+
+`@supabase/ssr` stores the session in cookies using a chunked, base64-encoded format:
+
+- **Cookie name:** `sb-<project-ref>-auth-token` (the project ref is extracted from your Supabase URL)
+- **Chunking:** if the session is too large for a single cookie, it's split into `sb-<ref>-auth-token.0`, `.1`, `.2`, etc.
+- **Base64 encoding:** the cookie value may be prefixed with `base64-`, indicating base64url encoding
+
+To extract the access token:
+
+```ts
+const BASE64_PREFIX = 'base64-'
+
+function getAccessTokenFromCookies(
+  getCookie: (name: string) => string | undefined,
+  supabaseUrl: string,
+): string | null {
+  // Extract project ref from URL: "https://abc123.supabase.co" → "abc123"
+  const ref = new URL(supabaseUrl).hostname.split('.')[0]
+  const storageKey = `sb-${ref}-auth-token`
+
+  // Try single cookie first, then chunked
+  let raw = getCookie(storageKey) ?? null
+
+  if (!raw) {
+    const chunks: string[] = []
+    for (let i = 0; ; i++) {
+      const chunk = getCookie(`${storageKey}.${i}`)
+      if (!chunk) break
+      chunks.push(chunk)
+    }
+    if (chunks.length > 0) raw = chunks.join('')
+  }
+
+  if (!raw) return null
+
+  // Decode base64url if needed
+  let decoded = raw
+  if (decoded.startsWith(BASE64_PREFIX)) {
+    try {
+      const base64 = decoded
+        .substring(BASE64_PREFIX.length)
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+      decoded = atob(base64)
+    } catch {
+      return null
+    }
+  }
+
+  // Parse the session JSON and extract access_token
+  try {
+    const session = JSON.parse(decoded)
+    return session.access_token ?? null
+  } catch {
+    return null
+  }
+}
+```
+
+The `getCookie` parameter is a function that reads a cookie by name — its implementation depends on your framework (e.g., `cookies().get(name)?.value` in Next.js, `event.cookies.get(name)` in SvelteKit).
+
+## Environment variable bridging
+
+SSR frameworks often use their own naming conventions for environment variables. Map them to a `Partial<SupabaseEnv>` that the core primitives expect:
+
+```ts
+import type { SupabaseEnv } from '@supabase/server'
+
+function resolveEnvFromFramework(): Partial<SupabaseEnv> {
+  // Example: Next.js uses NEXT_PUBLIC_* for client-exposed vars
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL
+  const publishableKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
+  const secretKey = process.env.SUPABASE_SECRET_KEY
+
+  return {
+    url: url ?? undefined,
+    publishableKeys: publishableKey ? { default: publishableKey } : {},
+    secretKeys: secretKey ? { default: secretKey } : {},
+    // JWKS: either set SUPABASE_JWKS env var, or fetch it (see below)
+  }
+}
+```
+
+## JWKS resolution
+
+JWT verification requires a JWKS (JSON Web Key Set). Two options:
+
+**Option 1: Set the `SUPABASE_JWKS` environment variable.** This is auto-available on the Supabase platform and in local CLI. If set, the core primitives pick it up automatically — no extra code needed.
+
+**Option 2: Fetch from the well-known endpoint and cache.** Useful when deploying to environments where `SUPABASE_JWKS` isn't set:
+
+```ts
+import type { SupabaseEnv } from '@supabase/server'
+
+let cachedJwks: SupabaseEnv['jwks'] = null
+
+async function getJwks(supabaseUrl: string): Promise<SupabaseEnv['jwks']> {
+  if (cachedJwks) return cachedJwks
+
+  try {
+    const res = await fetch(`${supabaseUrl}/auth/v1/.well-known/jwks.json`)
+    if (!res.ok) return null
+    cachedJwks = await res.json()
+    return cachedJwks
+  } catch {
+    return null
+  }
+}
+```
+
+The cache lives in module scope, so it persists across requests for the lifetime of the server process. For serverless environments (e.g., Vercel), the cache is per-invocation — consider using an external cache or always setting `SUPABASE_JWKS`.
+
+## Complete example: Next.js adapter
+
+A full adapter for Next.js App Router — works in Server Components, Server Actions, and Route Handlers:
+
+```ts
+// lib/supabase/context.ts
+import { cookies } from 'next/headers'
+import {
+  verifyCredentials,
+  createContextClient,
+  createAdminClient,
+} from '@supabase/server/core'
+import type {
+  AllowWithKey,
+  SupabaseContext,
+  SupabaseEnv,
+} from '@supabase/server'
+
+const BASE64_PREFIX = 'base64-'
+
+function getAccessTokenFromCookies(
+  cookieStore: Awaited<ReturnType<typeof cookies>>,
+  url: string,
+): string | null {
+  const ref = new URL(url).hostname.split('.')[0]
+  const storageKey = `sb-${ref}-auth-token`
+
+  let raw = cookieStore.get(storageKey)?.value ?? null
+
+  if (!raw) {
+    const chunks: string[] = []
+    for (let i = 0; ; i++) {
+      const chunk = cookieStore.get(`${storageKey}.${i}`)?.value
+      if (!chunk) break
+      chunks.push(chunk)
+    }
+    if (chunks.length > 0) raw = chunks.join('')
+  }
+
+  if (!raw) return null
+
+  let decoded = raw
+  if (decoded.startsWith(BASE64_PREFIX)) {
+    try {
+      const base64 = decoded
+        .substring(BASE64_PREFIX.length)
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+      decoded = atob(base64)
+    } catch {
+      return null
+    }
+  }
+
+  try {
+    const session = JSON.parse(decoded)
+    return session.access_token ?? null
+  } catch {
+    return null
+  }
+}
+
+function resolveNextEnv(): Partial<SupabaseEnv> {
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL
+  const publishableKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
+  const secretKey = process.env.SUPABASE_SECRET_KEY
+
+  return {
+    url: url ?? undefined,
+    publishableKeys: publishableKey ? { default: publishableKey } : {},
+    secretKeys: secretKey ? { default: secretKey } : {},
+  }
+}
+
+let cachedJwks: SupabaseEnv['jwks'] = null
+
+async function getJwks(supabaseUrl: string): Promise<SupabaseEnv['jwks']> {
+  if (cachedJwks) return cachedJwks
+  try {
+    const res = await fetch(`${supabaseUrl}/auth/v1/.well-known/jwks.json`)
+    if (!res.ok) return null
+    cachedJwks = await res.json()
+    return cachedJwks
+  } catch {
+    return null
+  }
+}
+
+export async function createSupabaseContext(
+  options: { allow?: AllowWithKey | AllowWithKey[] } = { allow: 'user' },
+): Promise<
+  { data: SupabaseContext; error: null } | { data: null; error: Error }
+> {
+  const nextEnv = resolveNextEnv()
+
+  if (!nextEnv.url) {
+    return { data: null, error: new Error('Missing SUPABASE_URL') }
+  }
+
+  const cookieStore = await cookies()
+  const token = getAccessTokenFromCookies(cookieStore, nextEnv.url)
+
+  const jwks = await getJwks(nextEnv.url)
+  const env: Partial<SupabaseEnv> = { ...nextEnv, jwks }
+
+  const { data: auth, error } = await verifyCredentials(
+    { token, apikey: null },
+    { allow: options.allow ?? 'user', env },
+  )
+
+  if (error) {
+    return { data: null, error }
+  }
+
+  const supabase = createContextClient({
+    auth: { token: auth!.token },
+    env,
+  })
+  const supabaseAdmin = createAdminClient({ env })
+
+  return {
+    data: {
+      supabase,
+      supabaseAdmin,
+      userClaims: auth!.userClaims,
+      claims: auth!.claims,
+      authType: auth!.authType,
+    },
+    error: null,
+  }
+}
+```
+
+## Usage
+
+### In a Server Component
+
+```tsx
+// app/page.tsx
+import { createSupabaseContext } from '@/lib/supabase/context'
+import { redirect } from 'next/navigation'
+
+export default async function Home() {
+  const { data: ctx, error } = await createSupabaseContext()
+
+  if (error) {
+    redirect('/auth/login')
+  }
+
+  const { data: todos } = await ctx!.supabase.from('todos').select()
+
+  return (
+    <ul>
+      {todos?.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### In a Route Handler
+
+```ts
+// app/api/todos/route.ts
+import { createSupabaseContext } from '@/lib/supabase/context'
+
+export async function GET() {
+  const { data: ctx, error } = await createSupabaseContext()
+
+  if (error) {
+    return Response.json({ message: error.message }, { status: 401 })
+  }
+
+  const { data } = await ctx!.supabase.from('todos').select()
+  return Response.json(data)
+}
+```
+
+### With different auth modes
+
+```ts
+// Public endpoint — no auth required
+const { data: ctx } = await createSupabaseContext({ allow: 'always' })
+
+// Accept either user JWT or skip auth
+const { data: ctx } = await createSupabaseContext({ allow: ['user', 'always'] })
+```
+
+## Adapting for other frameworks
+
+The adapter above is Next.js-specific only in how it reads cookies (`await cookies()` from `next/headers`). To adapt for another framework, replace the cookie-reading logic:
+
+- **SvelteKit:** `event.cookies.get(name)` in `+page.server.ts` or `+server.ts`
+- **Nuxt:** `useCookie(name)` in server routes, or `getCookie(event, name)` from `h3`
+- **Remix:** `request.headers.get('cookie')` then parse with a cookie library
+
+Everything else — env bridging, JWKS fetching, `verifyCredentials`, client creation — stays the same.

package/docs/typescript-generics.md

@@ -0,0 +1,143 @@
+# TypeScript Generics
+
+## Overview
+
+All client-creating functions accept a `Database` generic parameter. When you pass your generated database types, every `.from('table').select()` call is fully typed — column names, return types, insert shapes, and RPC signatures.
+
+## Generating types
+
+Use the Supabase CLI to generate TypeScript types from your database schema:
+
+```bash
+npx supabase gen types typescript --project-id your-project-ref > src/database.types.ts
+```
+
+This produces a `Database` type that describes your schema.
+
+## Using with withSupabase
+
+```ts
+import { withSupabase } from '@supabase/server'
+import type { Database } from './database.types.ts'
+
+export default {
+  fetch: withSupabase<Database>({ allow: 'user' }, async (_req, ctx) => {
+    // ctx.supabase is SupabaseClient<Database>
+    // Fully typed: column names, return type, etc.
+    const { data } = await ctx.supabase
+      .from('todos')
+      .select('id, title, completed')
+    // data is { id: number; title: string; completed: boolean }[] | null
+    return Response.json(data)
+  }),
+}
+```
+
+## Using with createSupabaseContext
+
+```ts
+import { createSupabaseContext } from '@supabase/server'
+import type { Database } from './database.types.ts'
+
+const { data: ctx, error } = await createSupabaseContext<Database>(request, {
+  allow: 'user',
+})
+
+if (error) {
+  throw error
+}
+
+// ctx.supabase and ctx.supabaseAdmin are both SupabaseClient<Database>
+const { data } = await ctx!.supabase.from('profiles').select('id, email')
+```
+
+## Using with core primitives
+
+```ts
+import {
+  verifyAuth,
+  createContextClient,
+  createAdminClient,
+} from '@supabase/server/core'
+import type { Database } from './database.types.ts'
+
+const { data: auth } = await verifyAuth(request, { allow: 'user' })
+
+const supabase = createContextClient<Database>({
+  auth: { token: auth!.token },
+})
+
+const supabaseAdmin = createAdminClient<Database>()
+
+// Both clients are fully typed
+const { data: todos } = await supabase.from('todos').select()
+const { data: users } = await supabaseAdmin.from('profiles').select()
+```
+
+## Using with the Hono adapter
+
+The Hono context variable is typed as `SupabaseContext` (without the generic). To get typed clients, assert the type when destructuring:
+
+```ts
+import { Hono } from 'hono'
+import { withSupabase } from '@supabase/server/adapters/hono'
+import type { SupabaseContext } from '@supabase/server'
+import type { Database } from './database.types.ts'
+
+const app = new Hono()
+
+app.use('*', withSupabase({ allow: 'user' }))
+
+app.get('/todos', async (c) => {
+  const { supabase } = c.var.supabaseContext as SupabaseContext<Database>
+  const { data } = await supabase.from('todos').select('id, title')
+  return c.json(data)
+})
+```
+
+## Custom schema
+
+If your tables are in a schema other than `public`, pass it via `supabaseOptions`:
+
+```ts
+import { withSupabase } from '@supabase/server'
+import type { Database } from './database.types.ts'
+
+export default {
+  fetch: withSupabase<Database>(
+    {
+      allow: 'user',
+      supabaseOptions: { db: { schema: 'api' } },
+    },
+    async (_req, ctx) => {
+      // Queries target the 'api' schema
+      const { data } = await ctx.supabase.from('todos').select()
+      return Response.json(data)
+    },
+  ),
+}
+```
+
+## Forwarding other Supabase client options
+
+`supabaseOptions` accepts the same options as `createClient()` from `@supabase/supabase-js`, with two exceptions:
+
+- `accessToken` is stripped — token injection is managed by the SDK from verified credentials
+- Auth settings (`persistSession`, `autoRefreshToken`, `detectSessionInUrl`) are force-set to server-safe values
+
+```ts
+withSupabase<Database>(
+  {
+    allow: 'user',
+    supabaseOptions: {
+      db: { schema: 'api' },
+      global: {
+        headers: { 'x-custom-header': 'value' },
+      },
+    },
+  },
+  handler,
+)
+```
+
+Note: `Authorization` and `apikey` headers in `supabaseOptions.global.headers` are sanitized (removed) to prevent overriding the verified credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.",
   "keywords": [
     "edge",
@@ -29,11 +29,6 @@
       "import": "./dist/core/index.mjs",
       "require": "./dist/core/index.cjs"
     },
-    "./wrappers": {
-      "types": "./dist/wrappers/index.d.mts",
-      "import": "./dist/wrappers/index.mjs",
-      "require": "./dist/wrappers/index.cjs"
-    },
     "./adapters/hono": {
       "types": "./dist/adapters/hono/index.d.mts",
       "import": "./dist/adapters/hono/index.mjs",
@@ -45,7 +40,9 @@
   "types": "./dist/index.d.cts",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "SKILL.md"
   ],
   "engines": {
     "node": ">=20"

package/dist/wrappers/index.cjs

@@ -1,45 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-
-//#region src/wrappers/webhook.ts
-const encoder = new TextEncoder();
-/**
-* Verifies a webhook signature using HMAC-SHA256 with timing-safe comparison.
-*
-* @param payload - The raw request body as a string.
-* @param signature - The hex-encoded signature from the webhook header.
-* @param secret - The shared secret used to sign webhooks.
-* @returns `true` if the signature is valid, `false` otherwise.
-*
-* @example
-* ```ts
-* const payload = await req.text()
-* const signature = req.headers.get('x-webhook-signature') ?? ''
-*
-* const isValid = await verifyWebhookSignature(payload, signature, secret)
-* if (!isValid) {
-*   return Response.json({ error: 'Invalid signature' }, { status: 401 })
-* }
-* ```
-*/
-async function verifyWebhookSignature(payload, signature, secret) {
-	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	const expected = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
-	const expectedHex = Array.from(new Uint8Array(expected)).map((b) => b.toString(16).padStart(2, "0")).join("");
-	const compareKey = await crypto.subtle.importKey("raw", crypto.getRandomValues(new Uint8Array(32)), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	const [sigA, sigB] = await Promise.all([crypto.subtle.sign("HMAC", compareKey, encoder.encode(expectedHex)), crypto.subtle.sign("HMAC", compareKey, encoder.encode(signature))]);
-	const viewA = new Uint8Array(sigA);
-	const viewB = new Uint8Array(sigB);
-	if (viewA.length !== viewB.length) return false;
-	let result = 0;
-	for (let i = 0; i < viewA.length; i++) result |= viewA[i] ^ viewB[i];
-	return result === 0;
-}
-
-//#endregion
-exports.verifyWebhookSignature = verifyWebhookSignature;

package/dist/wrappers/index.d.cts

@@ -1,23 +0,0 @@
-//#region src/wrappers/webhook.d.ts
-/**
- * Verifies a webhook signature using HMAC-SHA256 with timing-safe comparison.
- *
- * @param payload - The raw request body as a string.
- * @param signature - The hex-encoded signature from the webhook header.
- * @param secret - The shared secret used to sign webhooks.
- * @returns `true` if the signature is valid, `false` otherwise.
- *
- * @example
- * ```ts
- * const payload = await req.text()
- * const signature = req.headers.get('x-webhook-signature') ?? ''
- *
- * const isValid = await verifyWebhookSignature(payload, signature, secret)
- * if (!isValid) {
- *   return Response.json({ error: 'Invalid signature' }, { status: 401 })
- * }
- * ```
- */
-declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
-//#endregion
-export { verifyWebhookSignature };

package/dist/wrappers/index.d.mts

@@ -1,23 +0,0 @@
-//#region src/wrappers/webhook.d.ts
-/**
- * Verifies a webhook signature using HMAC-SHA256 with timing-safe comparison.
- *
- * @param payload - The raw request body as a string.
- * @param signature - The hex-encoded signature from the webhook header.
- * @param secret - The shared secret used to sign webhooks.
- * @returns `true` if the signature is valid, `false` otherwise.
- *
- * @example
- * ```ts
- * const payload = await req.text()
- * const signature = req.headers.get('x-webhook-signature') ?? ''
- *
- * const isValid = await verifyWebhookSignature(payload, signature, secret)
- * if (!isValid) {
- *   return Response.json({ error: 'Invalid signature' }, { status: 401 })
- * }
- * ```
- */
-declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
-//#endregion
-export { verifyWebhookSignature };

package/dist/wrappers/index.mjs

@@ -1,43 +0,0 @@
-//#region src/wrappers/webhook.ts
-const encoder = new TextEncoder();
-/**
-* Verifies a webhook signature using HMAC-SHA256 with timing-safe comparison.
-*
-* @param payload - The raw request body as a string.
-* @param signature - The hex-encoded signature from the webhook header.
-* @param secret - The shared secret used to sign webhooks.
-* @returns `true` if the signature is valid, `false` otherwise.
-*
-* @example
-* ```ts
-* const payload = await req.text()
-* const signature = req.headers.get('x-webhook-signature') ?? ''
-*
-* const isValid = await verifyWebhookSignature(payload, signature, secret)
-* if (!isValid) {
-*   return Response.json({ error: 'Invalid signature' }, { status: 401 })
-* }
-* ```
-*/
-async function verifyWebhookSignature(payload, signature, secret) {
-	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	const expected = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
-	const expectedHex = Array.from(new Uint8Array(expected)).map((b) => b.toString(16).padStart(2, "0")).join("");
-	const compareKey = await crypto.subtle.importKey("raw", crypto.getRandomValues(new Uint8Array(32)), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	const [sigA, sigB] = await Promise.all([crypto.subtle.sign("HMAC", compareKey, encoder.encode(expectedHex)), crypto.subtle.sign("HMAC", compareKey, encoder.encode(signature))]);
-	const viewA = new Uint8Array(sigA);
-	const viewB = new Uint8Array(sigB);
-	if (viewA.length !== viewB.length) return false;
-	let result = 0;
-	for (let i = 0; i < viewA.length; i++) result |= viewA[i] ^ viewB[i];
-	return result === 0;
-}
-
-//#endregion
-export { verifyWebhookSignature };