@supabase/server 0.2.0 → 1.0.0-rc.53

package/docs/{hono-adapter.md → adapters/hono.md}

@@ -19,7 +19,7 @@ import { withSupabase } from '@supabase/server/adapters/hono'
 const app = new Hono()
 
 // Apply auth to all routes
-app.use('*', withSupabase({ allow: 'user' }))
+app.use('*', withSupabase({ auth: 'user' }))
 
 app.get('/todos', async (c) => {
   const { supabase } = c.var.supabaseContext
@@ -39,7 +39,7 @@ app.get('/profile', async (c) => {
 export default { fetch: app.fetch }
 ```
 
-The context is stored in `c.var.supabaseContext` and contains the same `SupabaseContext` fields as the main `withSupabase` wrapper: `supabase`, `supabaseAdmin`, `userClaims`, `claims`, and `authType`.
+The context is stored in `c.var.supabaseContext` and contains the same `SupabaseContext` fields as the main `withSupabase` wrapper: `supabase`, `supabaseAdmin`, `userClaims`, `jwtClaims`, and `authMode`.
 
 ## Per-route auth
 
@@ -55,14 +55,14 @@ const app = new Hono()
 app.get('/health', (c) => c.json({ status: 'ok' }))
 
 // User-authenticated route
-app.get('/todos', withSupabase({ allow: 'user' }), async (c) => {
+app.get('/todos', withSupabase({ auth: 'user' }), async (c) => {
   const { supabase } = c.var.supabaseContext
   const { data } = await supabase.from('todos').select()
   return c.json(data)
 })
 
 // Secret-key-protected admin route
-app.post('/admin/sync', withSupabase({ allow: 'secret' }), async (c) => {
+app.post('/admin/sync', withSupabase({ auth: 'secret' }), async (c) => {
   const { supabaseAdmin } = c.var.supabaseContext
   const { data } = await supabaseAdmin
     .from('audit_log')
@@ -71,9 +71,9 @@ app.post('/admin/sync', withSupabase({ allow: 'secret' }), async (c) => {
 })
 
 // Dual auth — users or services
-app.get('/reports', withSupabase({ allow: ['user', 'secret'] }), async (c) => {
-  const { supabase, authType } = c.var.supabaseContext
-  return c.json({ authType })
+app.get('/reports', withSupabase({ auth: ['user', 'secret'] }), async (c) => {
+  const { supabase, authMode } = c.var.supabaseContext
+  return c.json({ authMode })
 })
 
 export default { fetch: app.fetch }
@@ -81,22 +81,11 @@ export default { fetch: app.fetch }
 
 ## Skip behavior
 
-If a previous middleware already set `c.var.supabaseContext`, subsequent `withSupabase` calls skip auth. This enables a pattern where route-level middleware overrides the app-wide default:
+If a previous middleware already set `c.var.supabaseContext`, subsequent `withSupabase` calls skip auth. This matters when multiple `app.use` middlewares overlap on the same path — the first one to set the context wins.
 
-```ts
-const app = new Hono()
-
-// App-wide: require user auth
-app.use('*', withSupabase({ allow: 'user' }))
+**Important:** Hono runs middleware in registration order (`app.use` before route-level middleware). An `app.use('*', ...)` middleware will always run before inline route middleware, so the skip-if-set pattern cannot be used to make a route stricter than the app-wide default.
 
-// This route needs secret auth instead.
-// The route-level middleware runs first, sets the context,
-// and the app-wide middleware skips.
-app.post('/webhook', withSupabase({ allow: 'secret' }), async (c) => {
-  const { supabaseAdmin } = c.var.supabaseContext
-  // ...
-})
-```
+For routes that need different auth than the rest of the app, use per-route middleware without an app-wide middleware (see the "Per-route auth" section above).
 
 ## CORS
 
@@ -110,7 +99,7 @@ import { withSupabase } from '@supabase/server/adapters/hono'
 const app = new Hono()
 
 app.use('*', cors())
-app.use('*', withSupabase({ allow: 'user' }))
+app.use('*', withSupabase({ auth: 'user' }))
 
 app.get('/todos', async (c) => {
   const { supabase } = c.var.supabaseContext
@@ -133,7 +122,7 @@ import { AuthError } from '@supabase/server'
 
 const app = new Hono()
 
-app.use('*', withSupabase({ allow: 'user' }))
+app.use('*', withSupabase({ auth: 'user' }))
 
 // Custom error handler
 app.onError((err, c) => {
@@ -164,7 +153,7 @@ Pass `env` to override auto-detected environment variables, same as the main wra
 app.use(
   '*',
   withSupabase({
-    allow: 'user',
+    auth: 'user',
     env: { url: 'http://localhost:54321' },
   }),
 )
@@ -178,7 +167,7 @@ Forward options to the underlying `createClient()` calls:
 app.use(
   '*',
   withSupabase({
-    allow: 'user',
+    auth: 'user',
     supabaseOptions: { db: { schema: 'api' } },
   }),
 )

package/docs/api-reference.md

@@ -18,7 +18,7 @@ function withSupabase<Database = unknown>(
 Wraps a fetch handler with auth, CORS, and client creation. Returns a `(req: Request) => Promise<Response>` function suitable for `export default { fetch }`.
 
 - Handles `OPTIONS` preflight when CORS is enabled
-- Verifies credentials per `config.allow`
+- Verifies credentials per `config.auth`
 - Returns JSON error response on auth failure
 - Adds CORS headers to all responses
 
@@ -36,7 +36,7 @@ function createSupabaseContext<Database = unknown>(
 
 Creates a `SupabaseContext` from a request. Returns a result tuple. The `cors` option is ignored.
 
-Defaults to `allow: 'user'` when `options` is omitted.
+Defaults to `auth: 'user'` when `options` is omitted.
 
 ---
 
@@ -47,7 +47,10 @@ Defaults to `allow: 'user'` when `options` is omitted.
 ```ts
 function verifyAuth(
   request: Request,
-  options: { allow: AllowWithKey | AllowWithKey[]; env?: Partial<SupabaseEnv> },
+  options: {
+    auth?: AuthModeWithKey | AuthModeWithKey[]
+    env?: Partial<SupabaseEnv>
+  },
 ): Promise<{ data: AuthResult; error: null } | { data: null; error: AuthError }>
 ```
 
@@ -58,7 +61,10 @@ Extracts credentials from a request and verifies them. Convenience wrapper over
 ```ts
 function verifyCredentials(
   credentials: Credentials,
-  options: { allow: AllowWithKey | AllowWithKey[]; env?: Partial<SupabaseEnv> },
+  options: {
+    auth?: AuthModeWithKey | AuthModeWithKey[]
+    env?: Partial<SupabaseEnv>
+  },
 ): Promise<{ data: AuthResult; error: null } | { data: null; error: AuthError }>
 ```
 
@@ -124,25 +130,29 @@ Hono middleware. Sets `c.var.supabaseContext` on the Hono context. Throws `HTTPE
 
 Skips if `c.var.supabaseContext` is already set (enables route-level overrides).
 
-Defaults to `allow: 'user'` when config is omitted.
+Defaults to `auth: 'user'` when config is omitted.
 
 ---
 
 ## Types
 
-### Allow
+### AuthMode
 
 ```ts
-type Allow = 'always' | 'public' | 'secret' | 'user'
+type AuthMode = 'none' | 'publishable' | 'secret' | 'user'
 ```
 
-### AllowWithKey
+### AuthModeWithKey
 
 ```ts
-type AllowWithKey = Allow | `public:${string}` | `secret:${string}`
+type AuthModeWithKey = AuthMode | `publishable:${string}` | `secret:${string}`
 ```
 
-Extended auth mode with named key support. Examples: `'public:web'`, `'secret:*'`, `'secret:internal'`.
+Extended auth mode with named key support. Examples: `'publishable:web'`, `'secret:*'`, `'secret:internal'`.
+
+### Allow / AllowWithKey (deprecated aliases)
+
+`Allow` and `AllowWithKey` are kept as deprecated aliases for `AuthMode` and `AuthModeWithKey`. Prefer the `Auth*` names — the legacy ones will be removed in a future major release.
 
 ### SupabaseContext\<Database\>
 
@@ -151,8 +161,9 @@ interface SupabaseContext<Database = unknown> {
   supabase: SupabaseClient<Database>
   supabaseAdmin: SupabaseClient<Database>
   userClaims: UserClaims | null
-  claims: JWTClaims | null
-  authType: Allow
+  jwtClaims: JWTClaims | null
+  authMode: AuthMode
+  authKeyName?: string
 }
 ```
 
@@ -160,7 +171,9 @@ interface SupabaseContext<Database = unknown> {
 
 ```ts
 interface WithSupabaseConfig {
-  allow?: AllowWithKey | AllowWithKey[] // default: 'user'
+  auth?: AuthModeWithKey | AuthModeWithKey[] // default: 'user'
+  /** @deprecated use `auth` instead — will be removed in a future major release */
+  allow?: AuthModeWithKey | AuthModeWithKey[]
   env?: Partial<SupabaseEnv>
   cors?: boolean | Record<string, string> // default: true
   supabaseOptions?: SupabaseClientOptions<string>
@@ -191,10 +204,10 @@ interface Credentials {
 
 ```ts
 interface AuthResult {
-  authType: Allow
+  authMode: AuthMode
   token: string | null
   userClaims: UserClaims | null
-  claims: JWTClaims | null
+  jwtClaims: JWTClaims | null
   keyName?: string | null
 }
 ```

package/docs/auth-modes.md

@@ -2,17 +2,21 @@
 
 ## Overview
 
-Every request is validated against one or more auth modes before your handler runs. The `allow` config determines which modes are accepted.
+Every request is validated against one or more auth modes before your handler runs. The `auth` config determines which modes are accepted.
 
-| Mode       | Credential required                          | Typical use case                       |
-| ---------- | -------------------------------------------- | -------------------------------------- |
-| `'user'`   | Valid JWT in `Authorization: Bearer <token>` | Authenticated user endpoints           |
-| `'public'` | Valid publishable key in `apikey` header     | Client-facing, key-validated endpoints |
-| `'secret'` | Valid secret key in `apikey` header          | Server-to-server, internal calls       |
-| `'always'` | None                                         | Open endpoints, custom auth wrappers   |
+> **`allow` is deprecated.** The `auth` option replaces the legacy `allow` option. `allow` still works (with a one-time `console.warn`) but will be removed in a future major release. Migration is a find-and-replace: `allow:` → `auth:`.
+
+> **Breaking — auth API renamed.** `'always'` is now `'none'` and `'public'` is now `'publishable'` (including the colon variants `'public:<name>'` → `'publishable:<name>'`). The field on `AuthResult` and `SupabaseContext` was also renamed from `authType` to `authMode` so it matches the `AuthMode` type. The old names no longer work — update the option values you pass in **and** any runtime checks on `ctx.authType` (now `ctx.authMode`).
+
+| Mode            | Credential required                          | Typical use case                       |
+| --------------- | -------------------------------------------- | -------------------------------------- |
+| `'user'`        | Valid JWT in `Authorization: Bearer <token>` | Authenticated user endpoints           |
+| `'publishable'` | Valid publishable key in `apikey` header     | Client-facing, key-validated endpoints |
+| `'secret'`      | Valid secret key in `apikey` header          | Server-to-server, internal calls       |
+| `'none'`        | None                                         | Open endpoints, custom auth wrappers   |
 
 > **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request same as `'user'`.
-> If your function uses `'public'`, `'secret'` or `'always'`, disable the platform-level JWT check in `supabase/config.toml`:
+> If your function uses `'publishable'`, `'secret'` or `'none'`, disable the platform-level JWT check in `supabase/config.toml`:
 >
 > ```toml
 > [functions.my-function]
@@ -27,15 +31,15 @@ The default. Verifies the JWT using your project's JWKS (JSON Web Key Set).
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {
+  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
     // ctx.userClaims has the caller's identity
     console.log(ctx.userClaims!.id) // "d0f1a2b3-..."
     console.log(ctx.userClaims!.email) // "user@example.com"
     console.log(ctx.userClaims!.role) // "authenticated"
 
-    // ctx.claims has the raw JWT payload
-    console.log(ctx.claims!.sub) // same as userClaims.id
-    console.log(ctx.claims!.exp) // token expiration (epoch seconds)
+    // ctx.jwtClaims has the raw JWT payload
+    console.log(ctx.jwtClaims!.sub) // same as userClaims.id
+    console.log(ctx.jwtClaims!.exp) // token expiration (epoch seconds)
 
     // ctx.supabase is scoped to this user — RLS applies
     const { data } = await ctx.supabase.from('todos').select()
@@ -52,7 +56,7 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
 
 **`userClaims` vs `supabase.auth.getUser()`:** `userClaims` is extracted from the JWT and is available instantly — no network call. It includes `id`, `email`, `role`, `appMetadata`, and `userMetadata`. For the full Supabase `User` object (email confirmation status, providers, linked identities), call `ctx.supabase.auth.getUser()`, which makes a request to the auth server.
 
-## Public mode
+## Publishable mode
 
 Validates that the `apikey` header contains a recognized publishable key. Uses timing-safe comparison to prevent timing attacks. See [`security.md`](security.md) for details.
 
@@ -60,7 +64,7 @@ Validates that the `apikey` header contains a recognized publishable key. Uses t
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: 'public' }, async (_req, ctx) => {
+  fetch: withSupabase({ auth: 'publishable' }, async (_req, ctx) => {
     // ctx.userClaims is null — no JWT involved
     // ctx.supabase is initialized as anonymous (RLS anon role)
     const { data } = await ctx.supabase.from('products').select()
@@ -75,17 +79,17 @@ The caller must send:
 apikey: sb_publishable_abc123...
 ```
 
-By default, `public` mode validates against the `"default"` key in `SUPABASE_PUBLISHABLE_KEYS`. Use named key syntax to target a specific key (see below).
+By default, `publishable` mode validates against the `"default"` key in `SUPABASE_PUBLISHABLE_KEYS`. Use named key syntax to target a specific key (see below).
 
 ## Secret mode
 
-Validates that the `apikey` header contains a recognized secret key. Same timing-safe comparison as public mode. See [`security.md`](security.md) for details.
+Validates that the `apikey` header contains a recognized secret key. Same timing-safe comparison as publishable mode. See [`security.md`](security.md) for details.
 
 ```ts
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: 'secret' }, async (_req, ctx) => {
+  fetch: withSupabase({ auth: 'secret' }, async (_req, ctx) => {
     // ctx.supabaseAdmin bypasses RLS — use for privileged operations
     const { data } = await ctx.supabaseAdmin.from('config').select()
     return Response.json(data)
@@ -99,7 +103,7 @@ The caller must send:
 apikey: sb_secret_xyz789...
 ```
 
-## Always mode
+## None mode
 
 No credentials required. Every request is accepted.
 
@@ -107,8 +111,8 @@ No credentials required. Every request is accepted.
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: 'always' }, async (_req, ctx) => {
-    // ctx.authType is 'always'
+  fetch: withSupabase({ auth: 'none' }, async (_req, ctx) => {
+    // ctx.authMode is 'none'
     // ctx.userClaims is null
     // ctx.supabase is anonymous (RLS anon role)
     return Response.json({ status: 'healthy' })
@@ -116,7 +120,7 @@ export default {
 }
 ```
 
-Use `always` for health checks, public APIs, or when you handle auth yourself inside the handler.
+Use `none` for health checks, public APIs, or when you handle auth yourself inside the handler.
 
 ## Array syntax (multiple modes)
 
@@ -126,9 +130,9 @@ Accept multiple auth methods. Modes are tried in order — the first match wins.
 import { withSupabase } from '@supabase/server'
 
 export default {
-  fetch: withSupabase({ allow: ['user', 'secret'] }, async (req, ctx) => {
-    // ctx.authType tells you which mode matched
-    if (ctx.authType === 'user') {
+  fetch: withSupabase({ auth: ['user', 'secret'] }, async (req, ctx) => {
+    // ctx.authMode tells you which mode matched
+    if (ctx.authMode === 'user') {
       // Called by an authenticated user
       const { data } = await ctx.supabase.from('reports').select()
       return Response.json(data)
@@ -147,7 +151,7 @@ export default {
 
 A request with a valid JWT matches `'user'`. A request with a valid secret key matches `'secret'`. A request with neither is rejected.
 
-**Fallthrough vs rejection.** A mode is only "tried" when its credential is actually present. A request with no `Authorization` header moves on to the next mode. But if a JWT _is_ present and fails verification (malformed, expired, wrong signature, or missing a `sub` claim), the request is rejected immediately with `InvalidCredentialsError` — it will not silently fall through to `'public'`, `'secret'`, or `'always'`. The same rule applies on the API-key side: `'public'` and `'secret'` fall through only when no `apikey` header is sent. This prevents a bad credential from being downgraded to a less-privileged auth mode.
+**Fallthrough vs rejection.** A mode is only "tried" when its credential is actually present. A request with no `Authorization` header moves on to the next mode. But if a JWT _is_ present and fails verification (malformed, expired, wrong signature, or missing a `sub` claim), the request is rejected immediately with `InvalidCredentialsError` — it will not silently fall through to `'publishable'`, `'secret'`, or `'none'`. The same rule applies on the API-key side: `'publishable'` and `'secret'` fall through only when no `apikey` header is sent. This prevents a bad credential from being downgraded to a less-privileged auth mode.
 
 ## Named key syntax
 
@@ -167,39 +171,39 @@ Keys are stored as a JSON object in `SUPABASE_PUBLISHABLE_KEYS` or `SUPABASE_SEC
 
 ```ts
 // Only accept the "web" publishable key
-withSupabase({ allow: 'public:web' }, handler)
+withSupabase({ auth: 'publishable:web' }, handler)
 
 // Only accept the "internal" secret key
-withSupabase({ allow: 'secret:internal' }, handler)
+withSupabase({ auth: 'secret:internal' }, handler)
 ```
 
 ### Wildcard — accept any key in the set
 
 ```ts
 // Accept any publishable key
-withSupabase({ allow: 'public:*' }, handler)
+withSupabase({ auth: 'publishable:*' }, handler)
 
 // Accept any secret key
-withSupabase({ allow: 'secret:*' }, handler)
+withSupabase({ auth: 'secret:*' }, handler)
 ```
 
 ### Which key matched?
 
-When using named keys, `ctx.authType` tells you the mode and `keyName` on the `AuthResult` (from core primitives) tells you which key matched. In the high-level `withSupabase` wrapper, the matched key is used internally for client creation.
+When using named keys, `ctx.authMode` tells you the mode and `keyName` on the `AuthResult` (from core primitives) tells you which key matched. In the high-level `withSupabase` wrapper, the matched key is used internally for client creation.
 
 ### Combining named keys with other modes
 
 ```ts
-withSupabase({ allow: ['user', 'public:web'] }, async (_req, ctx) => {
+withSupabase({ auth: ['user', 'publishable:web'] }, async (_req, ctx) => {
   // Accepts either a valid JWT or the "web" publishable key
-  return Response.json({ authType: ctx.authType })
+  return Response.json({ authMode: ctx.authMode })
 })
 ```
 
 ## How auth flows through the system
 
 1. `extractCredentials(request)` reads `Authorization: Bearer <token>` and `apikey` from headers
-2. Each mode in `allow` is tried in order against the extracted credentials
-3. First match wins — returns an `AuthResult` with `authType`, `token`, `userClaims`, `claims`, and `keyName`. A mode falls through to the next only when its credential is absent; a credential that is present but invalid terminates the chain with `InvalidCredentialsError`.
+2. Each mode in `auth` is tried in order against the extracted credentials
+3. First match wins — returns an `AuthResult` with `authMode`, `token`, `userClaims`, `jwtClaims`, and `keyName`. A mode falls through to the next only when its credential is absent; a credential that is present but invalid terminates the chain with `InvalidCredentialsError`.
 4. The auth result is used to create scoped clients (`supabase` with the user's token, `supabaseAdmin` with the secret key)
 5. Everything is bundled into a `SupabaseContext` and passed to your handler

package/docs/core-primitives.md

@@ -19,7 +19,7 @@ The primitives compose into a pipeline. Each step is independent — use only wh
 ```
 resolveEnv()                          → SupabaseEnv
 extractCredentials(request)           → Credentials { token, apikey }
-verifyCredentials(credentials, opts)  → AuthResult { authType, token, userClaims, claims, keyName }
+verifyCredentials(credentials, opts)  → AuthResult { authMode, token, userClaims, jwtClaims, keyName }
 createContextClient(options)          → SupabaseClient (RLS-scoped)
 createAdminClient(options)            → SupabaseClient (bypasses RLS)
 ```
@@ -77,14 +77,14 @@ import { verifyCredentials } from '@supabase/server/core'
 
 const credentials = { token: cookieToken, apikey: null }
 const { data: auth, error } = await verifyCredentials(credentials, {
-  allow: 'user',
+  auth: 'user',
 })
 
 if (error) {
   return Response.json({ message: error.message }, { status: error.status })
 }
 
-console.log(auth!.authType) // 'user'
+console.log(auth!.authMode) // 'user'
 console.log(auth!.userClaims) // { id: '...', email: '...', role: 'authenticated' }
 ```
 
@@ -93,17 +93,17 @@ Supports all auth mode syntax — single mode, arrays, and named keys:
 ```ts
 // Multiple modes
 const { data: auth } = await verifyCredentials(creds, {
-  allow: ['user', 'public'],
+  auth: ['user', 'publishable'],
 })
 
 // Named key
 const { data: auth } = await verifyCredentials(creds, {
-  allow: 'public:web',
+  auth: 'publishable:web',
 })
 
 // Wildcard
 const { data: auth } = await verifyCredentials(creds, {
-  allow: 'secret:*',
+  auth: 'secret:*',
 })
 ```
 
@@ -115,7 +115,7 @@ Convenience function that combines `extractCredentials` and `verifyCredentials`
 import { verifyAuth } from '@supabase/server/core'
 
 const { data: auth, error } = await verifyAuth(request, {
-  allow: 'user',
+  auth: 'user',
 })
 
 if (error) {
@@ -134,7 +134,7 @@ Creates a Supabase client scoped to the caller's identity. RLS policies apply.
 import { verifyAuth, createContextClient } from '@supabase/server/core'
 
 // With a user's token (from verifyAuth)
-const { data: auth } = await verifyAuth(request, { allow: 'user' })
+const { data: auth } = await verifyAuth(request, { auth: 'user' })
 const supabase = createContextClient({
   auth: { token: auth!.token, keyName: auth!.keyName },
 })
@@ -194,7 +194,7 @@ export default {
 
     // User-authenticated route
     if (url.pathname === '/todos') {
-      const { data: auth, error } = await verifyAuth(req, { allow: 'user' })
+      const { data: auth, error } = await verifyAuth(req, { auth: 'user' })
       if (error) {
         return Response.json(
           { message: error.message },
@@ -212,7 +212,7 @@ export default {
     // Admin route — secret key only
     if (url.pathname === '/admin/users') {
       const { data: auth, error } = await verifyAuth(req, {
-        allow: 'secret',
+        auth: 'secret',
       })
       if (error) {
         return Response.json(
@@ -233,8 +233,8 @@ export default {
 }
 ```
 
-## SSR frameworks (Next.js, Nuxt, SvelteKit, Remix)
+## Cookie-based environments (with `@supabase/ssr`)
 
-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.
+In Next.js, SvelteKit, Remix, and other cookie-based frameworks, the JWT lives in session cookies rather than the `Authorization` header. The recommended pattern is to **compose with [`@supabase/ssr`](https://github.com/supabase/ssr)**: let `@supabase/ssr` own the cookie session lifecycle and refresh-token rotation (via middleware), then hand its fresh access token to `verifyCredentials` and build typed clients with `createContextClient` + `createAdminClient`.
 
-For a complete guide with cookie parsing, JWKS caching, env bridging, and full framework adapters, see [ssr-frameworks.md](ssr-frameworks.md).
+For the full pattern — middleware setup, the composed adapter, JWKS caching, and other-framework adapting tips — see [ssr-frameworks.md](ssr-frameworks.md).

package/docs/environment-variables.md

@@ -5,22 +5,22 @@ On Supabase Platform and Local Development (CLI), all variables are auto-provisi
 | 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                       |
+| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_..."}` | Named publishable keys as JSON object | All                               |
+| `SUPABASE_SECRET_KEYS`      | `{"default":"sb_secret_..."}`      | Named secret keys as JSON object      | All                               |
+| `SUPABASE_JWKS`             | `{"keys":[...]}` or `[...]`        | JSON Web Key Set for JWT verification | All                               |
+| `SUPABASE_PUBLISHABLE_KEY`  | `sb_publishable_...`               | Single publishable key (fallback)     | Self-hosted, if manually exported |
+| `SUPABASE_SECRET_KEY`       | `sb_secret_...`                    | Single secret key (fallback)          | Self-hosted, if manually exported |
 
 ## 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)         |
+| Variable                   | Required when                             |
+| -------------------------- | ----------------------------------------- |
+| `SUPABASE_URL`             | Always                                    |
+| `SUPABASE_SECRET_KEY`      | `auth: 'secret'` or using `supabaseAdmin` |
+| `SUPABASE_PUBLISHABLE_KEY` | `auth: 'publishable'`                     |
+| `SUPABASE_JWKS`            | `auth: 'user'` (JWT verification)         |
 
 ### Minimal `.env` example
 
@@ -48,10 +48,10 @@ You can then validate against specific keys with named key syntax:
 
 ```ts
 // Only accept the "web" publishable key
-withSupabase({ allow: 'public:web' }, handler)
+withSupabase({ auth: 'publishable:web' }, handler)
 
 // Accept any secret key
-withSupabase({ allow: 'secret:*' }, handler)
+withSupabase({ auth: 'secret:*' }, handler)
 ```
 
 ### Singular form — equivalent to a single "default" key
@@ -69,7 +69,7 @@ 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.
+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 `auth: 'publishable'` (which looks for the `"default"` key) works with both forms.
 
 ### Priority
 
@@ -87,7 +87,7 @@ SUPABASE_JWKS={"keys":[{"kty":"RSA","n":"...","e":"AQAB"}]}
 SUPABASE_JWKS=[{"kty":"RSA","n":"...","e":"AQAB"}]
 ```
 
-When `SUPABASE_JWKS` is not set, JWT verification (`allow: 'user'`) is unavailable.
+When `SUPABASE_JWKS` is not set, JWT verification (`auth: 'user'`) is unavailable.
 
 ## Runtime-specific behavior
 
@@ -119,7 +119,7 @@ Cloudflare Workers don't expose `Deno.env` or `process.env` by default. Two opti
    ```ts
    withSupabase(
      {
-       allow: 'user',
+       auth: 'user',
        env: {
          url: env.SUPABASE_URL,
          publishableKeys: { default: env.SUPABASE_PUBLISHABLE_KEY },
@@ -140,7 +140,7 @@ import { withSupabase } from '@supabase/server'
 export default {
   fetch: withSupabase(
     {
-      allow: 'user',
+      auth: 'user',
       env: {
         url: 'http://localhost:54321', // override just the URL
       },

package/docs/error-handling.md

@@ -62,7 +62,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) {
@@ -93,7 +93,7 @@ import { withSupabase } from '@supabase/server/adapters/hono'
 
 const app = new Hono()
 
-app.use('*', withSupabase({ allow: 'user' }))
+app.use('*', withSupabase({ auth: 'user' }))
 
 app.onError((err, c) => {
   if (err instanceof HTTPException && err.cause) {
@@ -115,7 +115,7 @@ Result-tuple functions:
 import { verifyAuth, resolveEnv } from '@supabase/server/core'
 
 // verifyAuth returns { data, error }
-const { data: auth, error } = await verifyAuth(request, { allow: 'user' })
+const { data: auth, error } = await verifyAuth(request, { auth: 'user' })
 if (error) {
   return Response.json({ message: error.message }, { status: error.status })
 }
@@ -137,7 +137,7 @@ import {
 } from '@supabase/server/core'
 import { EnvError } from '@supabase/server'
 
-const { data: auth, error } = await verifyAuth(request, { allow: 'user' })
+const { data: auth, error } = await verifyAuth(request, { auth: 'user' })
 // ... handle error ...
 
 try {