@supabase/server 0.1.1 → 0.1.2-rc.32

package/docs/core-primitives.md

@@ -0,0 +1,240 @@
+# Core Primitives
+
+## When to use primitives
+
+Use `withSupabase` or `createSupabaseContext` for standard use cases. Drop down to core primitives when you need:
+
+- Multiple routes with different auth in a single handler
+- Custom response headers or error formats
+- Integration with frameworks other than the ones provided
+- Pre-extracted credentials (e.g., from cookies, custom headers)
+- Just auth verification without client creation
+
+All primitives are available from `@supabase/server/core`.
+
+## The composition pipeline
+
+The primitives compose into a pipeline. Each step is independent — use only what you need:
+
+```
+resolveEnv()                          → SupabaseEnv
+extractCredentials(request)           → Credentials { token, apikey }
+verifyCredentials(credentials, opts)  → AuthResult { authType, token, userClaims, claims, keyName }
+createContextClient(options)          → SupabaseClient (RLS-scoped)
+createAdminClient(options)            → SupabaseClient (bypasses RLS)
+```
+
+Or use the convenience function that combines extraction and verification:
+
+```
+verifyAuth(request, opts)  → AuthResult (extractCredentials + verifyCredentials in one call)
+```
+
+## resolveEnv
+
+Resolves Supabase environment configuration from runtime variables. The only hard requirement is `SUPABASE_URL`.
+
+```ts
+import { resolveEnv } from '@supabase/server/core'
+
+const { data: env, error } = resolveEnv()
+if (error) {
+  // error is an EnvError — e.g., SUPABASE_URL not set
+  console.error(error.message)
+}
+```
+
+With partial overrides:
+
+```ts
+const { data: envOverridden } = resolveEnv({
+  url: 'http://localhost:54321',
+})
+```
+
+Returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.
+
+## extractCredentials
+
+Pure extraction — reads headers, performs no validation.
+
+```ts
+import { extractCredentials } from '@supabase/server/core'
+
+const creds = extractCredentials(request)
+// creds.token  → string | null  (from Authorization: Bearer <token>)
+// creds.apikey → string | null  (from apikey header)
+```
+
+This is synchronous and never fails. Fields are `null` when the corresponding header is absent.
+
+## verifyCredentials
+
+Verifies pre-extracted credentials against allowed auth modes. Use this when credentials come from a non-standard source (cookies, custom headers, etc.).
+
+```ts
+import { verifyCredentials } from '@supabase/server/core'
+
+const credentials = { token: cookieToken, apikey: null }
+const { data: auth, error } = await verifyCredentials(credentials, {
+  allow: 'user',
+})
+
+if (error) {
+  return Response.json({ message: error.message }, { status: error.status })
+}
+
+console.log(auth!.authType) // 'user'
+console.log(auth!.userClaims) // { id: '...', email: '...', role: 'authenticated' }
+```
+
+Supports all auth mode syntax — single mode, arrays, and named keys:
+
+```ts
+// Multiple modes
+const { data: auth } = await verifyCredentials(creds, {
+  allow: ['user', 'public'],
+})
+
+// Named key
+const { data: auth } = await verifyCredentials(creds, {
+  allow: 'public:web',
+})
+
+// Wildcard
+const { data: auth } = await verifyCredentials(creds, {
+  allow: 'secret:*',
+})
+```
+
+## verifyAuth
+
+Convenience function that combines `extractCredentials` and `verifyCredentials` in a single call. Use this when working with a standard `Request`:
+
+```ts
+import { verifyAuth } from '@supabase/server/core'
+
+const { data: auth, error } = await verifyAuth(request, {
+  allow: 'user',
+})
+
+if (error) {
+  return Response.json({ message: error.message }, { status: error.status })
+}
+
+console.log(auth.userClaims!.id) // "d0f1a2b3-..."
+console.log(auth.token) // the verified JWT string
+```
+
+## createContextClient
+
+Creates a Supabase client scoped to the caller's identity. RLS policies apply.
+
+```ts
+import { verifyAuth, createContextClient } from '@supabase/server/core'
+
+// With a user's token (from verifyAuth)
+const { data: auth } = await verifyAuth(request, { allow: 'user' })
+const supabase = createContextClient({
+  auth: { token: auth!.token, keyName: auth!.keyName },
+})
+```
+
+```ts
+// Anonymous (no token) — RLS as anon role
+const anonClient = createContextClient()
+```
+
+The client is configured with:
+
+- The publishable key as the `apikey` header
+- The user's JWT as the `Authorization: Bearer` header (if token is provided)
+- Server-safe auth settings: `persistSession: false`, `autoRefreshToken: false`, `detectSessionInUrl: false`
+
+This function throws `EnvError` if `SUPABASE_URL` or the required publishable key is missing. Wrap in try/catch when using directly.
+
+## createAdminClient
+
+Creates a Supabase client that bypasses Row-Level Security using a secret key.
+
+```ts
+import { createAdminClient } from '@supabase/server/core'
+
+const supabaseAdmin = createAdminClient()
+```
+
+```ts
+// With a specific named key
+const supabaseAdminInternal = createAdminClient({
+  auth: { keyName: 'internal' },
+})
+```
+
+Same server-safe settings as `createContextClient`. Throws `EnvError` if the secret key is missing.
+
+## Full example: custom multi-route handler
+
+Using primitives to build a handler with different auth per route, without a framework:
+
+```ts
+import {
+  verifyAuth,
+  createContextClient,
+  createAdminClient,
+} from '@supabase/server/core'
+
+export default {
+  fetch: async (req: Request) => {
+    const url = new URL(req.url)
+
+    // Public route — no auth needed
+    if (url.pathname === '/health') {
+      return Response.json({ status: 'ok' })
+    }
+
+    // User-authenticated route
+    if (url.pathname === '/todos') {
+      const { data: auth, error } = await verifyAuth(req, { allow: 'user' })
+      if (error) {
+        return Response.json(
+          { message: error.message },
+          { status: error.status },
+        )
+      }
+
+      const supabase = createContextClient({
+        auth: { token: auth!.token, keyName: auth!.keyName },
+      })
+      const { data } = await supabase.from('todos').select()
+      return Response.json(data)
+    }
+
+    // Admin route — secret key only
+    if (url.pathname === '/admin/users') {
+      const { data: auth, error } = await verifyAuth(req, {
+        allow: 'secret',
+      })
+      if (error) {
+        return Response.json(
+          { message: error.message },
+          { status: error.status },
+        )
+      }
+
+      const supabaseAdmin = createAdminClient({
+        auth: { keyName: auth!.keyName },
+      })
+      const { data } = await supabaseAdmin.from('profiles').select()
+      return Response.json(data)
+    }
+
+    return new Response('Not found', { status: 404 })
+  },
+}
+```
+
+## SSR frameworks (Next.js, Nuxt, SvelteKit, Remix)
+
+In SSR frameworks, the JWT lives in session cookies rather than the `Authorization` header. Use `verifyCredentials` with a token extracted from cookies, then create clients as usual. This is the key primitive that enables SSR integration — it accepts pre-extracted credentials from any source.
+
+For a complete guide with cookie parsing, JWKS caching, env bridging, and full framework adapters, see [ssr-frameworks.md](ssr-frameworks.md).

package/docs/environment-variables.md

@@ -0,0 +1,189 @@
+## Supabase environments (zero config)
+
+On Supabase Platform and Local Development (CLI), all variables are auto-provisioned — no configuration needed
+
+| Variable                    | Format                             | Description                           | Available in                      |
+| --------------------------- | ---------------------------------- | ------------------------------------- | --------------------------------- |
+| `SUPABASE_URL`              | `https://<ref>.supabase.co`        | Your Supabase project URL             | All                               |
+| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_..."}` | Named publishable keys as JSON object | Platform, Local Development (CLI) |
+| `SUPABASE_SECRET_KEYS`      | `{"default":"sb_secret_..."}`      | Named secret keys as JSON object      | Platform, Local Development (CLI) |
+| `SUPABASE_JWKS`             | `{"keys":[...]}` or `[...]`        | JSON Web Key Set for JWT verification | Platform, Local Development (CLI) |
+| `SUPABASE_PUBLISHABLE_KEY`  | `sb_publishable_...`               | Single publishable key (fallback)     | Self-hosted                       |
+| `SUPABASE_SECRET_KEY`       | `sb_secret_...`                    | Single secret key (fallback)          | Self-hosted                       |
+
+## Non-Supabase environments (Node.js, Bun, Cloudflare, self-hosted)
+
+Set these based on which auth modes your app uses:
+
+| Variable                   | Required when                              |
+| -------------------------- | ------------------------------------------ |
+| `SUPABASE_URL`             | Always                                     |
+| `SUPABASE_SECRET_KEY`      | `allow: 'secret'` or using `supabaseAdmin` |
+| `SUPABASE_PUBLISHABLE_KEY` | `allow: 'public'`                          |
+| `SUPABASE_JWKS`            | `allow: 'user'` (JWT verification)         |
+
+### Minimal `.env` example
+
+```env
+SUPABASE_URL=https://<ref>.supabase.co
+SUPABASE_SECRET_KEY=sb_secret_...
+SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
+SUPABASE_JWKS={"keys":[...]}
+```
+
+## Plural vs singular keys
+
+The SDK checks the plural form first (`SUPABASE_PUBLISHABLE_KEYS`), then falls back to the singular form (`SUPABASE_PUBLISHABLE_KEY`). The same applies to secret keys.
+
+### Plural form — named keys as a JSON object
+
+Use this when you have multiple keys for different clients (web, mobile, internal):
+
+```
+SUPABASE_PUBLISHABLE_KEYS={"default":"sb_publishable_default_abc","web":"sb_publishable_web_xyz","mobile":"sb_publishable_mobile_123"}
+SUPABASE_SECRET_KEYS={"default":"sb_secret_default_abc","internal":"sb_secret_internal_xyz"}
+```
+
+You can then validate against specific keys with named key syntax:
+
+```ts
+// Only accept the "web" publishable key
+withSupabase({ allow: 'public:web' }, handler)
+
+// Accept any secret key
+withSupabase({ allow: 'secret:*' }, handler)
+```
+
+### Singular form — equivalent to a single "default" key
+
+```
+SUPABASE_PUBLISHABLE_KEY=sb_publishable_default_abc
+SUPABASE_SECRET_KEY=sb_secret_default_abc
+```
+
+This is equivalent to setting the plural form with a single `"default"` entry:
+
+```
+# These two are the same:
+SUPABASE_PUBLISHABLE_KEY=sb_publishable_default_abc
+SUPABASE_PUBLISHABLE_KEYS={"default":"sb_publishable_default_abc"}
+```
+
+The singular form is a convenience for the common case where you only have one key. The SDK stores it internally as `{ default: "<value>" }`, so `allow: 'public'` (which looks for the `"default"` key) works with both forms.
+
+### Priority
+
+When both singular and plural forms are set, the plural form takes priority.
+
+## JWKS format
+
+`SUPABASE_JWKS` accepts two formats:
+
+```
+# Standard JWKS format
+SUPABASE_JWKS={"keys":[{"kty":"RSA","n":"...","e":"AQAB"}]}
+
+# Bare array (convenience)
+SUPABASE_JWKS=[{"kty":"RSA","n":"...","e":"AQAB"}]
+```
+
+When `SUPABASE_JWKS` is not set, JWT verification (`allow: 'user'`) is unavailable.
+
+## Runtime-specific behavior
+
+The SDK reads environment variables using this priority:
+
+1. `Deno.env.get(name)` — Deno (including Supabase Edge Functions)
+2. `process.env[name]` — Node.js, Bun, Cloudflare Workers (with node-compat)
+
+### Supabase Edge Functions
+
+Environment variables are auto-provisioned by the platform. Nothing to configure.
+
+### Deno / Node.js / Bun
+
+Set variables via `.env` files (with a loader like `dotenv` for Node.js) or your deployment platform's environment configuration.
+
+### Cloudflare Workers
+
+Cloudflare Workers don't expose `Deno.env` or `process.env` by default. Two options:
+
+1. **Enable node-compat** in `wrangler.toml`:
+
+   ```toml
+   compatibility_flags = ["nodejs_compat"]
+   ```
+
+2. **Pass overrides** via the `env` config option:
+
+   ```ts
+   withSupabase(
+     {
+       allow: 'user',
+       env: {
+         url: env.SUPABASE_URL,
+         publishableKeys: { default: env.SUPABASE_PUBLISHABLE_KEY },
+         secretKeys: { default: env.SUPABASE_SECRET_KEY },
+       },
+     },
+     handler,
+   )
+   ```
+
+## Using env overrides
+
+The `env` option on `withSupabase`, `createSupabaseContext`, and core primitives lets you override auto-detected values. Partial overrides are merged with what's resolved from environment variables:
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase(
+    {
+      allow: 'user',
+      env: {
+        url: 'http://localhost:54321', // override just the URL
+      },
+    },
+    handler,
+  ),
+}
+```
+
+## Using resolveEnv directly
+
+For manual environment resolution — useful in tests, custom setups, or debugging:
+
+```ts
+import { resolveEnv } from '@supabase/server/core'
+
+const { data: env, error } = resolveEnv()
+if (error) {
+  console.error(`Missing config: ${error.message}`)
+}
+
+// With overrides
+const { data: envOverridden } = resolveEnv({
+  url: 'http://localhost:54321',
+  publishableKeys: { default: 'test-key' },
+})
+```
+
+`resolveEnv` returns a `SupabaseEnv` object:
+
+```ts
+interface SupabaseEnv {
+  url: string
+  publishableKeys: Record<string, string>
+  secretKeys: Record<string, string>
+  jwks: JsonWebKeySet | null
+}
+```
+
+## Graceful parsing
+
+Malformed JSON in environment variables doesn't throw — the SDK falls back to empty values:
+
+- Malformed `SUPABASE_PUBLISHABLE_KEYS` or `SUPABASE_SECRET_KEYS` → empty `{}`
+- Malformed `SUPABASE_JWKS` → `null` (JWT verification unavailable)
+- Missing `SUPABASE_URL` → `EnvError` (this is the only hard requirement)

package/docs/error-handling.md

@@ -0,0 +1,191 @@
+# Error Handling
+
+## Error classes
+
+The SDK has two error classes, both with `status` (HTTP code) and `code` (machine-readable string) properties.
+
+### EnvError
+
+Thrown when a required environment variable is missing or malformed. Always `status: 500` — these are server configuration issues, not client errors.
+
+| Code                              | Meaning                                                        |
+| --------------------------------- | -------------------------------------------------------------- |
+| `MISSING_SUPABASE_URL`            | `SUPABASE_URL` is not set                                      |
+| `MISSING_PUBLISHABLE_KEY`         | Named publishable key not found in `SUPABASE_PUBLISHABLE_KEYS` |
+| `MISSING_DEFAULT_PUBLISHABLE_KEY` | No default publishable key found                               |
+| `MISSING_SECRET_KEY`              | Named secret key not found in `SUPABASE_SECRET_KEYS`           |
+| `MISSING_DEFAULT_SECRET_KEY`      | No default secret key found                                    |
+| `ENV_ERROR`                       | Generic environment error                                      |
+
+### AuthError
+
+Thrown when authentication or authorization fails. Status is `401` for invalid credentials, `500` for server-side auth failures.
+
+| Code                           | Status | Meaning                                     |
+| ------------------------------ | ------ | ------------------------------------------- |
+| `INVALID_CREDENTIALS`          | 401    | No credential matched any allowed auth mode |
+| `CREATE_SUPABASE_CLIENT_ERROR` | 500    | Auth succeeded but client creation failed   |
+| `AUTH_ERROR`                   | 401    | Generic authentication error                |
+
+## How errors surface in each layer
+
+Different layers of the SDK handle errors differently. Understanding which pattern each function uses prevents surprises.
+
+| Function                  | Pattern       | What happens on error                                                    |
+| ------------------------- | ------------- | ------------------------------------------------------------------------ |
+| `withSupabase()`          | Auto-response | Returns `Response.json({ message, code }, { status })` with CORS headers |
+| `createSupabaseContext()` | Result tuple  | Returns `{ data: null, error: AuthError }`                               |
+| `verifyAuth()`            | Result tuple  | Returns `{ data: null, error: AuthError }`                               |
+| `verifyCredentials()`     | Result tuple  | Returns `{ data: null, error: AuthError }`                               |
+| `resolveEnv()`            | Result tuple  | Returns `{ data: null, error: EnvError }`                                |
+| `createContextClient()`   | **Throws**    | Throws `EnvError`                                                        |
+| `createAdminClient()`     | **Throws**    | Throws `EnvError`                                                        |
+| Hono `withSupabase()`     | HTTPException | Throws `HTTPException` with `cause: AuthError`                           |
+
+The two client factory functions (`createContextClient`, `createAdminClient`) are the only ones that throw. Everything else returns a result tuple `{ data, error }`.
+
+## Handling errors in withSupabase
+
+`withSupabase` handles errors automatically. If auth fails, the caller receives a JSON response:
+
+```json
+{ "message": "Invalid credentials", "code": "INVALID_CREDENTIALS" }
+```
+
+with the appropriate HTTP status code and CORS headers. Your handler never runs.
+
+If you need custom error formatting, use `createSupabaseContext` instead:
+
+```ts
+import { createSupabaseContext } from '@supabase/server'
+
+export default {
+  fetch: async (req: Request) => {
+    const { data: ctx, error } = await createSupabaseContext(req, {
+      allow: 'user',
+    })
+
+    if (error) {
+      // Custom error format
+      return Response.json(
+        {
+          success: false,
+          error: { message: error.message, code: error.code },
+        },
+        { status: error.status },
+      )
+    }
+
+    const { data } = await ctx!.supabase.from('todos').select()
+    return Response.json({ success: true, data })
+  },
+}
+```
+
+## Handling errors in Hono
+
+The Hono adapter throws an `HTTPException` when auth fails. Access the original `AuthError` via `.cause`:
+
+```ts
+import { Hono } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { withSupabase } from '@supabase/server/adapters/hono'
+
+const app = new Hono()
+
+app.use('*', withSupabase({ allow: 'user' }))
+
+app.onError((err, c) => {
+  if (err instanceof HTTPException && err.cause) {
+    const authError = err.cause
+    return c.json(
+      { message: authError.message, code: authError.code },
+      err.status,
+    )
+  }
+  return c.json({ message: 'Internal error' }, 500)
+})
+```
+
+## Handling errors in core primitives
+
+Result-tuple functions:
+
+```ts
+import { verifyAuth, resolveEnv } from '@supabase/server/core'
+
+// verifyAuth returns { data, error }
+const { data: auth, error } = await verifyAuth(request, { allow: 'user' })
+if (error) {
+  return Response.json({ message: error.message }, { status: error.status })
+}
+
+// resolveEnv returns { data, error }
+const { data: env, error: envError } = resolveEnv()
+if (envError) {
+  console.error(`Config issue [${envError.code}]: ${envError.message}`)
+}
+```
+
+Client factories throw — wrap them in try/catch:
+
+```ts
+import {
+  verifyAuth,
+  createContextClient,
+  createAdminClient,
+} from '@supabase/server/core'
+import { EnvError } from '@supabase/server'
+
+const { data: auth, error } = await verifyAuth(request, { allow: 'user' })
+// ... handle error ...
+
+try {
+  const supabase = createContextClient({ auth: { token: auth!.token } })
+  const supabaseAdmin = createAdminClient()
+} catch (e) {
+  if (e instanceof EnvError) {
+    console.error(`Config issue [${e.code}]: ${e.message}`)
+    return Response.json({ message: e.message }, { status: 500 })
+  }
+  throw e
+}
+```
+
+## Using the Errors factory map
+
+The `Errors` object provides factory functions for creating error instances by code. Useful when building custom error handling or testing:
+
+```ts
+import {
+  Errors,
+  MissingSupabaseURLError,
+  InvalidCredentialsError,
+} from '@supabase/server'
+
+// Create specific errors
+const envError = Errors[MissingSupabaseURLError]()
+// → EnvError { message: "SUPABASE_URL is required but not set", code: "MISSING_SUPABASE_URL", status: 500 }
+
+const authError = Errors[InvalidCredentialsError]()
+// → AuthError { message: "Invalid credentials", code: "INVALID_CREDENTIALS", status: 401 }
+```
+
+## Checking error types
+
+```ts
+import { AuthError, EnvError } from '@supabase/server'
+
+try {
+  // ... some operation
+} catch (e) {
+  if (e instanceof AuthError) {
+    // e.status is 401 or 500
+    // e.code is 'INVALID_CREDENTIALS', 'CREATE_SUPABASE_CLIENT_ERROR', or 'AUTH_ERROR'
+  }
+  if (e instanceof EnvError) {
+    // e.status is always 500
+    // e.code is one of the MISSING_* constants or 'ENV_ERROR'
+  }
+}
+```