@supabase/server 0.2.0 → 1.0.0

package/docs/getting-started.md

@@ -32,14 +32,14 @@ The fastest way to get a working authenticated endpoint:
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {
+  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
     const { data } = await ctx.supabase.from('todos').select()
     return Response.json(data)
   }),
 }
 ```
 
-> The `export default { fetch }` pattern is the standard module worker interface supported by Deno (including Supabase Edge Functions), Bun, and Cloudflare Workers. For Node.js, use the [Hono adapter](hono-adapter.md) or [core primitives](core-primitives.md) with your framework of choice.
+> The `export default { fetch }` pattern is the standard module worker interface supported by Deno (including Supabase Edge Functions), Bun, and Cloudflare Workers. For Node.js, use the [Hono adapter](adapters/hono.md) or [core primitives](core-primitives.md) with your framework of choice.
 
 This single wrapper does four things for every request:
 
@@ -56,13 +56,13 @@ Your handler only runs when auth succeeds.
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: 'always' }, async (_req, _ctx) => {
+  fetch: withSupabase({ auth: 'none' }, async (_req, _ctx) => {
     return Response.json({ status: 'ok', time: new Date().toISOString() })
   }),
 }
 ```
 
-> **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request. If your function uses `allow: 'public'`, `allow: 'secret'`, or `allow: 'always'`, disable the platform-level JWT check in `supabase/config.toml`:
+> **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request. If your function uses `auth: 'publishable'`, `auth: 'secret'`, or `auth: 'none'`, disable the platform-level JWT check in `supabase/config.toml`:
 >
 > ```toml
 > [functions.my-function]
@@ -73,16 +73,16 @@ export default {
 
 Every handler receives a `SupabaseContext` with these fields:
 
-| Field           | Type                 | Description                                                                                            |
-| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
-| `supabase`      | `SupabaseClient`     | Client scoped to the caller. RLS policies apply.                                                       |
-| `supabaseAdmin` | `SupabaseClient`     | Admin client. Bypasses RLS.                                                                            |
-| `userClaims`    | `UserClaims \| null` | JWT-derived identity (`id`, `email`, `role`, `appMetadata`, `userMetadata`). `null` for non-user auth. |
-| `claims`        | `JWTClaims \| null`  | Raw JWT payload (snake_case). `null` for non-user auth.                                                |
-| `authType`      | `Allow`              | Which auth mode matched: `'user'`, `'public'`, `'secret'`, or `'always'`.                              |
-| `authKeyName`   | `string \| null`     | Which auth key name of the API key that was used.                                                      |
+| Field           | Type                  | Description                                                                                            |
+| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `supabase`      | `SupabaseClient`      | Client scoped to the caller. RLS policies apply.                                                       |
+| `supabaseAdmin` | `SupabaseClient`      | Admin client. Bypasses RLS.                                                                            |
+| `userClaims`    | `UserClaims \| null`  | JWT-derived identity (`id`, `email`, `role`, `appMetadata`, `userMetadata`). `null` for non-user auth. |
+| `jwtClaims`     | `JWTClaims \| null`   | Raw JWT payload (snake_case). `null` for non-user auth.                                                |
+| `authMode`      | `AuthMode`            | Which auth mode matched: `'user'`, `'publishable'`, `'secret'`, or `'none'`.                           |
+| `authKeyName`   | `string \| undefined` | Which auth key name of the API key that was used. Omitted for `'user'` / `'none'`.                     |
 
-The `supabase` client respects Row-Level Security. When `authType` is `'user'`, the client is scoped to that user's permissions. For other auth modes, it's initialized as anonymous.
+The `supabase` client respects Row-Level Security. When `authMode` is `'user'`, the client is scoped to that user's permissions. For other auth modes, it's initialized as anonymous.
 
 The `supabaseAdmin` client always bypasses RLS. Use it for operations that need full database access regardless of who's calling.
 
@@ -98,7 +98,7 @@ import { createSupabaseContext } from '@supabase/server'
 export default {
   fetch: async (req: Request) => {
     const { data: ctx, error } = await createSupabaseContext(req, {
-      allow: 'user',
+      auth: 'user',
     })
 
     if (error) {
@@ -124,7 +124,7 @@ CORS is enabled by default with standard supabase-js headers. You can customize
 // Custom CORS headers
 withSupabase(
   {
-    allow: 'user',
+    auth: 'user',
     cors: {
       'Access-Control-Allow-Origin': 'https://myapp.com',
       'Access-Control-Allow-Headers': 'authorization, content-type',
@@ -134,7 +134,7 @@ withSupabase(
 )
 
 // Disable CORS (e.g., when a framework handles it)
-withSupabase({ allow: 'user', cors: false }, handler)
+withSupabase({ auth: 'user', cors: false }, handler)
 ```
 
 ## Runtimes
@@ -143,7 +143,7 @@ withSupabase({ allow: 'user', cors: false }, handler)
 
 - **Supabase Edge Functions** — environment variables are automatically injected by the platform. Zero config needed.
 - **Deno / Bun** — works out of the box with the module worker pattern.
-- **Node.js** — set variables via `.env` files or your hosting platform. Use the [Hono adapter](hono-adapter.md) or [core primitives](core-primitives.md) to integrate with any framework.
+- **Node.js** — set variables via `.env` files or your hosting platform. Use the [Hono adapter](adapters/hono.md) or [core primitives](core-primitives.md) to integrate with any framework.
 - **Cloudflare Workers** — enable `nodejs_compat` or pass env overrides via the `env` config option.
 
 For full details on environment setup per runtime, see [environment-variables.md](environment-variables.md).

package/docs/security.md

@@ -12,8 +12,8 @@ The package uses a **double-HMAC technique**: both strings are HMAC'd with a ran
 
 This applies to:
 
-- **Publishable key verification** (`allow: 'public'`) — compares the `apikey` header against stored publishable keys
-- **Secret key verification** (`allow: 'secret'`) — compares the `apikey` header against stored secret keys
+- **Publishable key verification** (`auth: 'publishable'`) — compares the `apikey` header against stored publishable keys
+- **Secret key verification** (`auth: 'secret'`) — compares the `apikey` header against stored secret keys
 
 See `src/core/utils/timing-safe-equal.ts` for the implementation.
 
@@ -21,18 +21,18 @@ See `src/core/utils/timing-safe-equal.ts` for the implementation.
 
 Each auth mode provides a different level of trust:
 
-| Mode     | What it verifies                    | Who the caller is        | `supabase` client  | `supabaseAdmin` client |
-| -------- | ----------------------------------- | ------------------------ | ------------------ | ---------------------- |
-| `user`   | JWT signature against JWKS          | An authenticated user    | Row-Level Security | Full access            |
-| `public` | Publishable API key (timing-safe)   | A known client app       | Row-Level Security | Full access            |
-| `secret` | Secret API key (timing-safe)        | A trusted server/service | Full access        | Full access            |
-| `always` | Nothing — all requests are accepted | Unknown                  | Row-Level Security | Full access            |
+| Mode          | What it verifies                    | Who the caller is        | `supabase` client  | `supabaseAdmin` client |
+| ------------- | ----------------------------------- | ------------------------ | ------------------ | ---------------------- |
+| `user`        | JWT signature against JWKS          | An authenticated user    | Row-Level Security | Full access            |
+| `publishable` | Publishable API key (timing-safe)   | A known client app       | Row-Level Security | Full access            |
+| `secret`      | Secret API key (timing-safe)        | A trusted server/service | Full access        | Full access            |
+| `none`        | Nothing — all requests are accepted | Unknown                  | Row-Level Security | Full access            |
 
 Key implications:
 
 - **`user` mode** verifies the JWT using a local JWKS (JSON Web Key Set). The token must contain a `sub` claim. Verification uses the `jose` library's `jwtVerify` with a local key set — no network calls to an auth server.
-- **`public` and `secret` modes** compare the `apikey` header against known keys. The comparison is timing-safe. If you use named keys (`allow: 'secret:automations'`), only that specific key is accepted — this follows the principle of least privilege.
-- **`always` mode** performs zero authentication. The handler runs for every request. The `supabaseAdmin` client is still available, so a compromised `always` endpoint with write operations is a security risk. Only use it for truly public endpoints or when you implement your own auth (e.g., webhook signature verification).
+- **`publishable` and `secret` modes** compare the `apikey` header against known keys. The comparison is timing-safe. If you use named keys (`auth: 'secret:automations'`), only that specific key is accepted — this follows the principle of least privilege.
+- **`none` mode** performs zero authentication. The handler runs for every request. The `supabaseAdmin` client is still available, so a compromised `none` endpoint with write operations is a security risk. Only use it for truly public endpoints or when you implement your own auth (e.g., webhook signature verification).
 
 ## Named key isolation
 
@@ -40,10 +40,10 @@ Instead of accepting any valid API key, you can restrict an endpoint to a specif
 
 ```ts
 // Accepts any secret key
-withSupabase({ allow: 'secret' }, handler)
+withSupabase({ auth: 'secret' }, handler)
 
 // Only accepts the "automations" secret key
-withSupabase({ allow: 'secret:automations' }, handler)
+withSupabase({ auth: 'secret:automations' }, handler)
 ```
 
 This limits the blast radius if a key is compromised. An attacker with the `web` publishable key cannot access an endpoint that requires `secret:automations`. Named keys also make it easier to rotate or revoke access for a specific consumer without affecting others.
@@ -56,11 +56,11 @@ JWT verification in `user` mode works as follows:
 2. The token is verified against the JWKS from the `SUPABASE_JWKS` environment variable
 3. Verification uses `jose`'s `jwtVerify` with a **local** key set — there are no network calls to a JWKS endpoint
 4. The token must contain a `sub` (subject) claim to be considered valid
-5. On success, the decoded claims are available as `ctx.userClaims` and `ctx.claims`
+5. On success, the decoded claims are available as `ctx.userClaims` and `ctx.jwtClaims`
 
 If JWKS is not configured (`SUPABASE_JWKS` is missing or malformed), `user` mode is unavailable and will always reject requests.
 
-**No silent downgrade.** When `user` is combined with other modes (e.g. `allow: ['user', 'public']`), a JWT that is present but fails verification rejects the request with `InvalidCredentialsError` — it does not fall through to the next mode. This prevents a bad token paired with a valid `apikey` (or with `'always'`) from being silently downgraded to a less-privileged auth mode. Requests that simply omit the `Authorization` header still fall through as expected.
+**No silent downgrade.** When `user` is combined with other modes (e.g. `auth: ['user', 'publishable']`), a JWT that is present but fails verification rejects the request with `InvalidCredentialsError` — it does not fall through to the next mode. This prevents a bad token paired with a valid `apikey` (or with `'none'`) from being silently downgraded to a less-privileged auth mode. Requests that simply omit the `Authorization` header still fall through as expected.
 
 ## CORS handling
 
@@ -79,6 +79,6 @@ The Hono adapter does **not** handle CORS — use Hono's built-in `cors` middlew
 Credentials are extracted from two standard headers:
 
 - `Authorization: Bearer <token>` → used by `user` mode
-- `apikey: <value>` → used by `public` and `secret` modes
+- `apikey: <value>` → used by `publishable` and `secret` modes
 
 Extraction is a separate step from verification (`extractCredentials` vs `verifyCredentials`). This separation means you can inspect raw credentials in custom flows without triggering validation.

package/docs/ssr-frameworks.md

@@ -1,141 +1,77 @@
-# SSR Frameworks
+# Cookie-based environments (Next.js, SvelteKit, Remix)
 
 ## 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.
+In cookie-based frameworks like Next.js, Nuxt, SvelteKit, and Remix, the user's JWT lives in session cookies rather than the `Authorization` header. The high-level wrappers (`withSupabase`, `createSupabaseContext`) expect a standard `Request` with auth headers, so they don't work directly here.
 
-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 recommended pattern is to **compose `@supabase/server` with [`@supabase/ssr`](https://github.com/supabase/ssr)**:
 
-## The pattern
+- `@supabase/ssr` owns the cookie session lifecycle — reads cookies, writes cookies, and handles refresh-token rotation via middleware.
+- `@supabase/server` adds JWT verification (`verifyCredentials`), an RLS-scoped server client (`createContextClient`), and a service-role client (`createAdminClient`) on top.
 
-Every SSR adapter follows these steps:
+You hand `@supabase/ssr`'s fresh access token to `verifyCredentials`, then build typed clients from the result.
 
-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`**
+## How the pieces fit
 
-## Reading Supabase session cookies
+1. **`@supabase/ssr` middleware** runs on every request and refreshes the access token cookie. Without it, the cookie goes stale, `verifyCredentials` rejects expired tokens, and the user appears logged out — even with a valid refresh token. (Server Components can't write cookies, which is why the refresh has to happen in middleware.)
+2. **`@supabase/ssr` `createServerClient`** runs inside your Server Component / Route Handler, reads the (now-fresh) cookie, and exposes `auth.getSession()` / `auth.getUser()`.
+3. **`verifyCredentials`** from `@supabase/server/core` cryptographically verifies that access token against JWKS and returns the parsed claims.
+4. **`createContextClient`** builds an RLS-scoped `supabase-js` client bound to the verified token.
+5. **`createAdminClient`** builds a service-role client (no token needed).
 
-`@supabase/ssr` stores the session in cookies using a chunked, base64-encoded format:
+## Step 1 — `@supabase/ssr` middleware (refresh-token rotation)
 
-- **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:
+This middleware is required. It refreshes the access token cookie before any Server Component or Route Handler runs:
 
 ```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'
+// middleware.ts
+import { createServerClient } from '@supabase/ssr'
+import { NextResponse, type NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  let supabaseResponse = NextResponse.next({ request })
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return request.cookies.getAll()
+        },
+        setAll(cookiesToSet) {
+          cookiesToSet.forEach(({ name, value }) =>
+            request.cookies.set(name, value),
+          )
+          supabaseResponse = NextResponse.next({ request })
+          cookiesToSet.forEach(({ name, value, options }) =>
+            supabaseResponse.cookies.set(name, value, options),
+          )
+        },
+      },
+    },
+  )
 
-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
+  // Triggers refresh-token rotation and writes the new cookies via setAll.
+  await supabase.auth.getUser()
 
-  return {
-    url: url ?? undefined,
-    publishableKeys: publishableKey ? { default: publishableKey } : {},
-    secretKeys: secretKey ? { default: secretKey } : {},
-    // JWKS: either set SUPABASE_JWKS env var, or fetch it (see below)
-  }
+  return supabaseResponse
 }
-```
 
-## 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
-  }
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
 }
 ```
 
-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`.
+If you skip this middleware, the cookie's access token will eventually expire and `verifyCredentials` will reject the request.
 
-## Complete example: Next.js adapter
+## Step 2 — composed adapter
 
-A full adapter for Next.js App Router — works in Server Components, Server Actions, and Route Handlers:
+The adapter reads the (middleware-refreshed) cookie via `@supabase/ssr`, then hands the access token to `@supabase/server`'s primitives. The return shape matches the high-level `createSupabaseContext`, so callers see a familiar `{ supabase, supabaseAdmin, userClaims, jwtClaims, authMode }` bundle.
 
 ```ts
 // lib/supabase/context.ts
+import { createServerClient } from '@supabase/ssr'
 import { cookies } from 'next/headers'
 import {
   verifyCredentials,
@@ -143,55 +79,11 @@ import {
   createAdminClient,
 } from '@supabase/server/core'
 import type {
-  AllowWithKey,
+  AuthModeWithKey,
   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
@@ -219,25 +111,54 @@ async function getJwks(supabaseUrl: string): Promise<SupabaseEnv['jwks']> {
 }
 
 export async function createSupabaseContext(
-  options: { allow?: AllowWithKey | AllowWithKey[] } = { allow: 'user' },
+  options: { auth?: AuthModeWithKey | AuthModeWithKey[] } = { auth: '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') }
+  if (!nextEnv.url || !nextEnv.publishableKeys?.default) {
+    return {
+      data: null,
+      error: new Error('Missing SUPABASE_URL or SUPABASE_PUBLISHABLE_KEY'),
+    }
   }
 
+  // Read the @supabase/ssr session cookie. The middleware above has already
+  // refreshed the access token, so getSession() returns a fresh JWT.
   const cookieStore = await cookies()
-  const token = getAccessTokenFromCookies(cookieStore, nextEnv.url)
+  const ssrClient = createServerClient(
+    nextEnv.url,
+    nextEnv.publishableKeys.default,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll()
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options),
+            )
+          } catch {
+            // Server Components can't write cookies — middleware handles it.
+          }
+        },
+      },
+    },
+  )
+
+  const {
+    data: { session },
+  } = await ssrClient.auth.getSession()
+  const token = session?.access_token ?? null
 
   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 },
+    { auth: options.auth ?? 'user', env },
   )
 
   if (error) {
@@ -255,14 +176,69 @@ export async function createSupabaseContext(
       supabase,
       supabaseAdmin,
       userClaims: auth!.userClaims,
-      claims: auth!.claims,
-      authType: auth!.authType,
+      jwtClaims: auth!.jwtClaims,
+      authMode: auth!.authMode,
     },
     error: null,
   }
 }
 ```
 
+## Does this replace `@supabase/ssr`?
+
+No. `@supabase/ssr` handles cookie-based session management for frameworks like Next.js and SvelteKit. `@supabase/server` handles stateless, header-based auth for Edge Functions, Workers, and other backend runtimes. As you can see in the Next.js example above, the composable primitives already work in SSR environments but require more setup. The two packages coexist and are not replacements for each other. Deeper integration with `@supabase/ssr` is on the roadmap.
+
+## 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`.
+
 ## Usage
 
 ### In a Server Component
@@ -313,18 +289,18 @@ export async function GET() {
 
 ```ts
 // Public endpoint — no auth required
-const { data: ctx } = await createSupabaseContext({ allow: 'always' })
+const { data: ctx } = await createSupabaseContext({ auth: 'none' })
 
 // Accept either user JWT or skip auth
-const { data: ctx } = await createSupabaseContext({ allow: ['user', 'always'] })
+const { data: ctx } = await createSupabaseContext({ auth: ['user', 'none'] })
 ```
 
 ## 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:
+The adapter above is Next.js-specific only in how it wires `@supabase/ssr`'s cookie adapter. To adapt for another framework, swap the cookie adapter you pass to `createServerClient` from `@supabase/ssr` — see `@supabase/ssr`'s framework guides for the canonical patterns:
 
-- **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
+- **SvelteKit:** `event.cookies.getAll()` / `event.cookies.set(name, value, options)` in `+page.server.ts` or `+server.ts`.
+- **Remix:** parse cookies from `request.headers.get('cookie')` and emit them via `Set-Cookie` in the response.
+- **Nuxt:** use `useCookie` / `getCookie` / `setCookie` from `h3` inside server routes.
 
 Everything else — env bridging, JWKS fetching, `verifyCredentials`, client creation — stays the same.

package/docs/typescript-generics.md

@@ -21,7 +21,7 @@ import { withSupabase } from '@supabase/server'
 import type { Database } from './database.types.ts'
 
 export default {
-  fetch: withSupabase<Database>({ allow: 'user' }, async (_req, ctx) => {
+  fetch: withSupabase<Database>({ auth: 'user' }, async (_req, ctx) => {
     // ctx.supabase is SupabaseClient<Database>
     // Fully typed: column names, return type, etc.
     const { data } = await ctx.supabase
@@ -40,7 +40,7 @@ import { createSupabaseContext } from '@supabase/server'
 import type { Database } from './database.types.ts'
 
 const { data: ctx, error } = await createSupabaseContext<Database>(request, {
-  allow: 'user',
+  auth: 'user',
 })
 
 if (error) {
@@ -61,7 +61,7 @@ import {
 } from '@supabase/server/core'
 import type { Database } from './database.types.ts'
 
-const { data: auth } = await verifyAuth(request, { allow: 'user' })
+const { data: auth } = await verifyAuth(request, { auth: 'user' })
 
 const supabase = createContextClient<Database>({
   auth: { token: auth!.token },
@@ -86,7 +86,7 @@ import type { Database } from './database.types.ts'
 
 const app = new Hono()
 
-app.use('*', withSupabase({ allow: 'user' }))
+app.use('*', withSupabase({ auth: 'user' }))
 
 app.get('/todos', async (c) => {
   const { supabase } = c.var.supabaseContext as SupabaseContext<Database>
@@ -106,7 +106,7 @@ import type { Database } from './database.types.ts'
 export default {
   fetch: withSupabase<Database>(
     {
-      allow: 'user',
+      auth: 'user',
       supabaseOptions: { db: { schema: 'api' } },
     },
     async (_req, ctx) => {
@@ -128,7 +128,7 @@ export default {
 ```ts
 withSupabase<Database>(
   {
-    allow: 'user',
+    auth: 'user',
     supabaseOptions: {
       db: { schema: 'api' },
       global: {