@supabase/server 0.1.4 → 0.2.0-rc.45

package/README.md

@@ -4,32 +4,38 @@
 [![Package](https://img.shields.io/npm/v/@supabase/server)](https://www.npmjs.com/package/@supabase/server)
 [![pkg.pr.new](https://pkg.pr.new/badge/supabase/server)](https://pkg.pr.new/~/supabase/server)
 
-Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.
+> **Beta:** This package is under active development. APIs and documentation may change. If you find a bug or have a feature request, please [open an issue](https://github.com/supabase/server/issues) or [submit a PR](https://github.com/supabase/server/blob/main/CONTRIBUTING.md).
+
+`@supabase/server` gives you batteries included access to the
+[supabase-js SDK](https://github.com/supabase/supabase-js), including client
+creation and authentication automatically scoped to the inbound requests to your
+Edge Functions and APIs.
 
 ```ts
 import { withSupabase } from '@supabase/server'
 
 export default {
   fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {
-    const { data } = await ctx.supabase.from('todos').select()
-    return Response.json(data)
+    // RLS-scoped — this user only sees their own favorites
+    const { data: myGames } = await ctx.supabase.from('favorite_games').select()
+    return Response.json(myGames)
   }),
 }
 ```
 
-One import. One line of config. Auth is validated, clients are scoped, CORS is handled. Your handler only runs on successful auth.
+One import. One line of config. Auth is validated, clients are ready, CORS is handled. Your handler only runs on successful auth.
 
 ## Installation
 
 ```bash
+# Deno / Supabase Edge Functions (no install — import directly)
+import { withSupabase } from "npm:@supabase/server";
+
 # npm
 npm install @supabase/server
 
 # pnpm
 pnpm add @supabase/server
-
-# Deno / Supabase Edge Functions (no install — import directly)
-import { withSupabase } from "npm:@supabase/server";
 ```
 
 ### AI coding skills
@@ -42,19 +48,24 @@ npx skills add supabase/server
 
 ## Quick Start
 
+Imagine you're building an app where users track their favorite games. They sign in and manage their own list. An admin dashboard curates featured titles. A cron job refreshes the "popular this week" rankings. Here's how each piece looks:
+
 ### Authenticated endpoint
 
 ```ts
+// A signed-in user fetches their favorite games.
 export default {
   fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {
-    // ctx.supabase — RLS-scoped to the authenticated user
-    // ctx.supabaseAdmin — bypasses RLS (service role)
-    // ctx.userClaims — user identity from JWT (id, email, role)
-    // ctx.claims — JWT claims
-    // ctx.authType — which auth mode matched
-
-    const { data } = await ctx.supabase.from('todos').select()
-    return Response.json(data)
+    const { supabase, supabaseAdmin, userClaims, claims, authType } = ctx
+    // supabase       — RLS-scoped to the authenticated user
+    // supabaseAdmin  — bypasses RLS (service role)
+    // userClaims     — user identity from JWT (id, email, role)
+    // claims         — full JWT claims
+    // authType       — which auth mode matched
+
+    // RLS-scoped — this user only sees their own favorites
+    const { data: myGames } = await supabase.from('favorite_games').select()
+    return Response.json(myGames)
   }),
 }
 ```
@@ -62,6 +73,8 @@ export default {
 ### Public endpoint (no auth)
 
 ```ts
+// The frontend hits this before showing the login screen.
+// allow: 'always' means no credentials required.
 export default {
   fetch: withSupabase({ allow: 'always' }, async (_req, _ctx) => {
     return Response.json({ status: 'ok' })
@@ -72,10 +85,14 @@ export default {
 ### API key protected
 
 ```ts
+// An admin dashboard fetches the list of featured games to curate.
+// Secret key auth (not a user JWT) — supabaseAdmin bypasses RLS.
 export default {
   fetch: withSupabase({ allow: 'secret' }, async (_req, ctx) => {
-    const { data } = await ctx.supabaseAdmin.from('config').select()
-    return Response.json(data)
+    const { data: featuredGames } = await ctx.supabaseAdmin
+      .from('featured_games')
+      .select()
+    return Response.json(featuredGames)
   }),
 }
 ```
@@ -83,14 +100,25 @@ export default {
 ### Dual auth (user or service)
 
 ```ts
+// Users view their own play stats from the app (JWT).
+// A backend service pulls stats for any user (secret key + user_id in body).
 export default {
   fetch: withSupabase({ allow: ['user', 'secret'] }, async (req, ctx) => {
-    const userId = ctx.userClaims?.id ?? (await req.json()).user_id
-    const { data } = await ctx.supabaseAdmin
-      .from('reports')
+    const callerIsUser = ctx.authType === 'user'
+
+    if (callerIsUser) {
+      // RLS-scoped — the database enforces "own stats only"
+      const { data: myStats } = await ctx.supabase.from('play_stats').select()
+      return Response.json(myStats)
+    }
+
+    // Service path — bypass RLS to pull stats for any user
+    const { user_id } = await req.json()
+    const { data: playStats } = await ctx.supabaseAdmin
+      .from('play_stats')
       .select()
-      .eq('user_id', userId)
-    return Response.json(data)
+      .eq('user_id', user_id)
+    return Response.json(playStats)
   }),
 }
 ```
@@ -98,28 +126,35 @@ export default {
 ### Server-to-server
 
 ```ts
-// Only accept the "automations" named secret key
+// A cron job refreshes the "popular this week" list every hour.
+// Named key ("cron") so it can be rotated without touching other services.
 export default {
-  fetch: withSupabase({ allow: 'secret:automations' }, async (req, ctx) => {
-    const body = await req.json()
-    const { data } = await ctx.supabaseAdmin
-      .from('scheduled_tasks')
-      .insert({ name: body.taskName })
-    return Response.json({ success: true, data })
+  fetch: withSupabase({ allow: 'secret:cron' }, async (_req, ctx) => {
+    const oneWeekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
+    const { data: popularThisWeek } = await ctx.supabaseAdmin.rpc(
+      'get_most_favorited_since',
+      { since: oneWeekAgo.toISOString(), limit_count: 10 },
+    )
+    await ctx.supabaseAdmin
+      .from('featured_games')
+      .upsert(
+        popularThisWeek.map((g) => ({ game_id: g.id, reason: 'popular' })),
+      )
+    return Response.json({ popularThisWeek })
   }),
 }
 ```
 
-The caller sends the secret key in the `apikey` header:
+The cron job sends the named secret key in the `apikey` header:
 
 ```ts
-await fetch('https://<project>.supabase.co/functions/v1/my-function', {
+const refreshEndpoint =
+  'https://<project>.supabase.co/functions/v1/refresh-popular'
+const cronKey = 'sb_secret_...' // the "cron" named secret key
+
+await fetch(refreshEndpoint, {
   method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    apikey: 'sb_secret_...', // the "automations" secret key
-  },
-  body: JSON.stringify({ taskName: 'cleanup' }),
+  headers: { apikey: cronKey },
 })
 ```
 
@@ -132,7 +167,7 @@ await fetch('https://<project>.supabase.co/functions/v1/my-function', {
 | `"secret"`         | Valid secret key      | Server-to-server, internal calls                    |
 | `"always"`         | None                  | Open endpoints, wrappers that handle their own auth |
 
-Array syntax (`allow: ["user", "secret"]`) accepts multiple auth methods — first match wins.
+Array syntax (`allow: ["user", "secret"]`) accepts multiple auth methods — first match wins. An absent credential falls through to the next mode; a present-but-invalid JWT rejects the request (no silent downgrade). See [`docs/auth-modes.md`](docs/auth-modes.md).
 
 Named key validation: `allow: "public:web_app"` or `allow: "secret:automations"` validates against a specific named key in `SUPABASE_PUBLISHABLE_KEYS` or `SUPABASE_SECRET_KEYS`.
 
@@ -154,6 +189,7 @@ interface SupabaseContext {
   userClaims: UserClaims | null // JWT-derived identity (for full User, call supabase.auth.getUser())
   claims: JWTClaims | null // Present when auth is JWT
   authType: Allow // Which auth mode matched
+  authKeyName?: string | null // Auth key name of the API key that was used for this request
 }
 ```
 
@@ -201,12 +237,14 @@ import { withSupabase } from '@supabase/server/adapters/hono'
 
 const app = new Hono()
 
-app.get('/todos', withSupabase({ allow: 'user' }), async (c) => {
-  const { supabase: sb } = c.var.supabaseContext
-  const { data } = await sb.from('todos').select()
-  return c.json(data)
+// Protected — withSupabase middleware validates the JWT before the handler runs
+app.get('/games', withSupabase({ allow: 'user' }), async (c) => {
+  const { supabase } = c.var.supabaseContext
+  const { data: myGames } = await supabase.from('favorite_games').select()
+  return c.json(myGames)
 })
 
+// Public — no middleware means no auth
 app.get('/health', (c) => c.json({ status: 'ok' }))
 
 export default { fetch: app.fetch }
@@ -214,6 +252,56 @@ export default { fetch: app.fetch }
 
 The adapter does not handle CORS — use `hono/cors` for that. Per-route auth works naturally by applying the middleware to specific routes.
 
+### H3 / Nuxt
+
+```ts
+import { H3 } from 'h3'
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+const app = new H3()
+
+// Protected — withSupabase validates the JWT before the handler runs
+app.use(withSupabase({ allow: 'user' }))
+
+app.get('/games', async (event) => {
+  const { supabase } = event.context.supabaseContext
+  const { data: myGames } = await supabase.from('favorite_games').select()
+  return myGames
+})
+
+// Public — no middleware means no auth
+app.get('/health', () => ({ status: 'ok' }))
+
+export default { fetch: app.fetch }
+```
+
+For **Nuxt**, use `defineHandler` for file routes:
+
+```ts
+// server/api/games.get.ts
+import { defineHandler } from 'h3'
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+export default defineHandler({
+  middleware: [withSupabase({ allow: 'user' })],
+  handler: async (event) => {
+    const { supabase } = event.context.supabaseContext
+    return supabase.from('favorite_games').select()
+  },
+})
+```
+
+For app-wide auth, register it as a server middleware:
+
+```ts
+// server/middleware/supabase.ts
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+export default withSupabase({ allow: 'user' })
+```
+
+The adapter does not handle CORS — use H3's CORS utilities for that.
+
 ## Primitives
 
 For when you need more control than `withSupabase` provides — multiple routes with different auth, custom response headers, or building your own wrapper.
@@ -253,9 +341,9 @@ const { data: auth, error } = await verifyCredentials(credentials, {
 ### createContextClient / createAdminClient
 
 ```ts
-const supabase = createContextClient(auth.token) // user-scoped, RLS applies
-const supabase = createContextClient() // anonymous, RLS as anon
-const supabaseAdmin = createAdminClient() // bypasses RLS
+const userScopedClient = createContextClient(auth.token) // RLS applies as this user
+const anonClient = createContextClient() // RLS applies as anon role
+const adminClient = createAdminClient() // bypasses RLS entirely
 ```
 
 ### createSupabaseContext
@@ -278,6 +366,8 @@ const { data: env, error } = resolveEnv({
 
 ### Example: custom multi-route handler
 
+The same games API and health check from the Hono example, built from primitives instead of a framework:
+
 ```ts
 import { verifyAuth, createContextClient } from '@supabase/server/core'
 
@@ -285,11 +375,13 @@ export default {
   fetch: async (req) => {
     const url = new URL(req.url)
 
+    // Public — no auth needed
     if (url.pathname === '/health') {
       return Response.json({ status: 'ok' })
     }
 
-    if (url.pathname === '/todos') {
+    // Protected — verify the JWT, then create a user-scoped client
+    if (url.pathname === '/games') {
       const { data: auth, error } = await verifyAuth(req, { allow: 'user' })
       if (error)
         return Response.json(
@@ -297,9 +389,11 @@ export default {
           { status: error.status },
         )
 
-      const supabase = createContextClient(auth.token)
-      const { data } = await supabase.from('todos').select()
-      return Response.json(data)
+      const userScopedClient = createContextClient(auth.token)
+      const { data: myGames } = await userScopedClient
+        .from('favorite_games')
+        .select()
+      return Response.json(myGames)
     }
 
     return new Response('Not found', { status: 404 })
@@ -333,9 +427,10 @@ For other environments, pass overrides via the `env` config option or `resolveEn
 
 - **Supabase Edge Functions** — environment variables are auto-injected. Zero config.
 - **Deno / Bun** — works out of the box with the `export default { fetch }` pattern.
-- **Node.js** — use the [Hono adapter](#hono) or [core primitives](#primitives) with your framework of choice.
+- **Node.js** — use the [Hono adapter](#hono), [H3 adapter](#h3--nuxt), or [core primitives](#primitives) with your framework of choice.
 - **Cloudflare Workers** — enable `nodejs_compat` in `wrangler.toml` or pass env overrides via the `env` config option.
-- **Next.js / Nuxt / SvelteKit / Remix** — use core primitives to build a cookie-based auth adapter. See [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md).
+- **Nuxt** — use the [H3 adapter](#h3--nuxt) directly as a server middleware.
+- **Next.js / SvelteKit / Remix** — use core primitives to build a cookie-based auth adapter. See [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md).
 
 ## Exports
 
@@ -344,6 +439,7 @@ For other environments, pass overrides via the `env` config option or `resolveEn
 | `@supabase/server`               | `withSupabase`, `createSupabaseContext`                                                                           |
 | `@supabase/server/core`          | `verifyAuth`, `verifyCredentials`, `extractCredentials`, `createContextClient`, `createAdminClient`, `resolveEnv` |
 | `@supabase/server/adapters/hono` | `withSupabase` (Hono middleware)                                                                                  |
+| `@supabase/server/adapters/h3`   | `withSupabase` (H3 / Nuxt middleware)                                                                             |
 
 ## Documentation
 

package/dist/adapters/h3/index.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_create_supabase_context = require('../../create-supabase-context-C_8SbO5w.cjs');
+let h3 = require("h3");
+
+//#region src/adapters/h3/middleware.ts
+/**
+* H3 middleware that creates a {@link SupabaseContext} and stores it in `event.context.supabaseContext`.
+*
+* Skips if a previous middleware already set the context, enabling chained middleware via `app.use()`.
+* Throws an `HTTPError` on auth failure.
+*
+* @param config - Auth modes and optional environment overrides. CORS is excluded — use H3's CORS utilities.
+* @returns An H3 middleware.
+*
+* @example App-wide auth via `app.use()`
+* ```ts
+* import { H3 } from 'h3'
+* import { withSupabase } from '@supabase/server/adapters/h3'
+*
+* const app = new H3()
+* app.use(withSupabase({ allow: 'user' }))
+*
+* app.get('/games', async (event) => {
+*   const { supabase } = event.context.supabaseContext
+*   return supabase.from('favorite_games').select()
+* })
+*
+* export default { fetch: app.fetch }
+* ```
+*
+* @example Per-route auth via `defineHandler`
+* ```ts
+* import { defineHandler } from 'h3'
+* import { withSupabase } from '@supabase/server/adapters/h3'
+*
+* export default defineHandler({
+*   middleware: [withSupabase({ allow: 'user' })],
+*   handler: async (event) => {
+*     const { supabase } = event.context.supabaseContext
+*     return supabase.from('favorite_games').select()
+*   },
+* })
+* ```
+*/
+function withSupabase(config) {
+	return (0, h3.defineMiddleware)(async (event, next) => {
+		if (event.context.supabaseContext) return next();
+		const { data: ctx, error } = await require_create_supabase_context.createSupabaseContext(event.req, config);
+		if (error) throw new h3.HTTPError(error.message, {
+			status: error.status,
+			cause: error
+		});
+		event.context.supabaseContext = ctx;
+		return next();
+	});
+}
+
+//#endregion
+exports.withSupabase = withSupabase;

package/dist/adapters/h3/index.d.cts

@@ -0,0 +1,51 @@
+import { f as WithSupabaseConfig, l as SupabaseContext } from "../../types-DqhOaSlC.cjs";
+import { Middleware } from "h3";
+
+//#region src/adapters/h3/middleware.d.ts
+/**
+ * H3 middleware that creates a {@link SupabaseContext} and stores it in `event.context.supabaseContext`.
+ *
+ * Skips if a previous middleware already set the context, enabling chained middleware via `app.use()`.
+ * Throws an `HTTPError` on auth failure.
+ *
+ * @param config - Auth modes and optional environment overrides. CORS is excluded — use H3's CORS utilities.
+ * @returns An H3 middleware.
+ *
+ * @example App-wide auth via `app.use()`
+ * ```ts
+ * import { H3 } from 'h3'
+ * import { withSupabase } from '@supabase/server/adapters/h3'
+ *
+ * const app = new H3()
+ * app.use(withSupabase({ allow: 'user' }))
+ *
+ * app.get('/games', async (event) => {
+ *   const { supabase } = event.context.supabaseContext
+ *   return supabase.from('favorite_games').select()
+ * })
+ *
+ * export default { fetch: app.fetch }
+ * ```
+ *
+ * @example Per-route auth via `defineHandler`
+ * ```ts
+ * import { defineHandler } from 'h3'
+ * import { withSupabase } from '@supabase/server/adapters/h3'
+ *
+ * export default defineHandler({
+ *   middleware: [withSupabase({ allow: 'user' })],
+ *   handler: async (event) => {
+ *     const { supabase } = event.context.supabaseContext
+ *     return supabase.from('favorite_games').select()
+ *   },
+ * })
+ * ```
+ */
+declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): Middleware;
+declare module 'h3' {
+  interface H3EventContext {
+    supabaseContext: SupabaseContext;
+  }
+}
+//#endregion
+export { withSupabase };

package/dist/adapters/h3/index.d.mts

@@ -0,0 +1,51 @@
+import { f as WithSupabaseConfig, l as SupabaseContext } from "../../types-DKe8uOwI.mjs";
+import { Middleware } from "h3";
+
+//#region src/adapters/h3/middleware.d.ts
+/**
+ * H3 middleware that creates a {@link SupabaseContext} and stores it in `event.context.supabaseContext`.
+ *
+ * Skips if a previous middleware already set the context, enabling chained middleware via `app.use()`.
+ * Throws an `HTTPError` on auth failure.
+ *
+ * @param config - Auth modes and optional environment overrides. CORS is excluded — use H3's CORS utilities.
+ * @returns An H3 middleware.
+ *
+ * @example App-wide auth via `app.use()`
+ * ```ts
+ * import { H3 } from 'h3'
+ * import { withSupabase } from '@supabase/server/adapters/h3'
+ *
+ * const app = new H3()
+ * app.use(withSupabase({ allow: 'user' }))
+ *
+ * app.get('/games', async (event) => {
+ *   const { supabase } = event.context.supabaseContext
+ *   return supabase.from('favorite_games').select()
+ * })
+ *
+ * export default { fetch: app.fetch }
+ * ```
+ *
+ * @example Per-route auth via `defineHandler`
+ * ```ts
+ * import { defineHandler } from 'h3'
+ * import { withSupabase } from '@supabase/server/adapters/h3'
+ *
+ * export default defineHandler({
+ *   middleware: [withSupabase({ allow: 'user' })],
+ *   handler: async (event) => {
+ *     const { supabase } = event.context.supabaseContext
+ *     return supabase.from('favorite_games').select()
+ *   },
+ * })
+ * ```
+ */
+declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): Middleware;
+declare module 'h3' {
+  interface H3EventContext {
+    supabaseContext: SupabaseContext;
+  }
+}
+//#endregion
+export { withSupabase };

package/dist/adapters/h3/index.mjs

@@ -0,0 +1,58 @@
+import { t as createSupabaseContext } from "../../create-supabase-context-DXD5rxi1.mjs";
+import { HTTPError, defineMiddleware } from "h3";
+
+//#region src/adapters/h3/middleware.ts
+/**
+* H3 middleware that creates a {@link SupabaseContext} and stores it in `event.context.supabaseContext`.
+*
+* Skips if a previous middleware already set the context, enabling chained middleware via `app.use()`.
+* Throws an `HTTPError` on auth failure.
+*
+* @param config - Auth modes and optional environment overrides. CORS is excluded — use H3's CORS utilities.
+* @returns An H3 middleware.
+*
+* @example App-wide auth via `app.use()`
+* ```ts
+* import { H3 } from 'h3'
+* import { withSupabase } from '@supabase/server/adapters/h3'
+*
+* const app = new H3()
+* app.use(withSupabase({ allow: 'user' }))
+*
+* app.get('/games', async (event) => {
+*   const { supabase } = event.context.supabaseContext
+*   return supabase.from('favorite_games').select()
+* })
+*
+* export default { fetch: app.fetch }
+* ```
+*
+* @example Per-route auth via `defineHandler`
+* ```ts
+* import { defineHandler } from 'h3'
+* import { withSupabase } from '@supabase/server/adapters/h3'
+*
+* export default defineHandler({
+*   middleware: [withSupabase({ allow: 'user' })],
+*   handler: async (event) => {
+*     const { supabase } = event.context.supabaseContext
+*     return supabase.from('favorite_games').select()
+*   },
+* })
+* ```
+*/
+function withSupabase(config) {
+	return defineMiddleware(async (event, next) => {
+		if (event.context.supabaseContext) return next();
+		const { data: ctx, error } = await createSupabaseContext(event.req, config);
+		if (error) throw new HTTPError(error.message, {
+			status: error.status,
+			cause: error
+		});
+		event.context.supabaseContext = ctx;
+		return next();
+	});
+}
+
+//#endregion
+export { withSupabase };

package/dist/adapters/hono/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_create_supabase_context = require('../../create-supabase-context--VqMJpDu.cjs');
+const require_create_supabase_context = require('../../create-supabase-context-C_8SbO5w.cjs');
 let hono_http_exception = require("hono/http-exception");
 let hono_factory = require("hono/factory");
 

package/dist/adapters/hono/index.d.cts

@@ -1,5 +1,5 @@
-import { f as WithSupabaseConfig, l as SupabaseContext } from "../../types-DxTr0Qum.cjs";
-import * as hono_types0 from "hono/types";
+import { f as WithSupabaseConfig, l as SupabaseContext } from "../../types-DqhOaSlC.cjs";
+import { MiddlewareHandler } from "hono";
 
 //#region src/adapters/hono/middleware.d.ts
 /**
@@ -28,10 +28,10 @@ import * as hono_types0 from "hono/types";
  * export default { fetch: app.fetch }
  * ```
  */
-declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): hono_types0.MiddlewareHandler<{
+declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): MiddlewareHandler<{
   Variables: {
     supabaseContext: SupabaseContext;
   };
-}, string, {}, Response>;
+}>;
 //#endregion
 export { withSupabase };

package/dist/adapters/hono/index.d.mts

@@ -1,5 +1,5 @@
-import { f as WithSupabaseConfig, l as SupabaseContext } from "../../types-CbC-wBUe.mjs";
-import * as hono_types0 from "hono/types";
+import { f as WithSupabaseConfig, l as SupabaseContext } from "../../types-DKe8uOwI.mjs";
+import { MiddlewareHandler } from "hono";
 
 //#region src/adapters/hono/middleware.d.ts
 /**
@@ -28,10 +28,10 @@ import * as hono_types0 from "hono/types";
  * export default { fetch: app.fetch }
  * ```
  */
-declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): hono_types0.MiddlewareHandler<{
+declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): MiddlewareHandler<{
   Variables: {
     supabaseContext: SupabaseContext;
   };
-}, string, {}, Response>;
+}>;
 //#endregion
 export { withSupabase };

package/dist/adapters/hono/index.mjs

@@ -1,4 +1,4 @@
-import { t as createSupabaseContext } from "../../create-supabase-context-B3Uzt_3I.mjs";
+import { t as createSupabaseContext } from "../../create-supabase-context-DXD5rxi1.mjs";
 import { HTTPException } from "hono/http-exception";
 import { createMiddleware } from "hono/factory";
 

package/dist/core/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_verify_auth = require('../verify-auth-DrgvEuKo.cjs');
+const require_verify_auth = require('../verify-auth-C4zqDlfj.cjs');
 
 exports.createAdminClient = require_verify_auth.createAdminClient;
 exports.createContextClient = require_verify_auth.createContextClient;

package/dist/core/index.d.cts

@@ -1,5 +1,5 @@
-import { a as CreateAdminClientOptions, i as ClientAuth, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, u as SupabaseEnv } from "../types-DxTr0Qum.cjs";
-import { i as EnvError, t as AuthError } from "../errors-O2ugIMec.cjs";
+import { a as CreateAdminClientOptions, i as ClientAuth, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, u as SupabaseEnv } from "../types-DqhOaSlC.cjs";
+import { i as EnvError, t as AuthError } from "../errors-Dyj5Cjt6.cjs";
 import { SupabaseClient } from "@supabase/supabase-js";
 
 //#region src/core/resolve-env.d.ts
@@ -72,8 +72,11 @@ interface VerifyCredentialsOptions {
 /**
  * Verifies pre-extracted credentials against one or more allowed auth modes.
  *
- * Tries each mode in order — first match wins. Use {@link verifyAuth} to extract
- * and verify in a single call.
+ * Tries each mode in order — first match wins. A mode is only tried when its
+ * credential is present; a JWT that is present but fails verification
+ * short-circuits the chain with `InvalidCredentialsError` instead of falling
+ * through to the next mode. Use {@link verifyAuth} to extract and verify in a
+ * single call.
  *
  * @param credentials - The credentials to verify (from {@link extractCredentials}).
  * @param options - Allowed auth modes and optional env overrides.

package/dist/core/index.d.mts

@@ -1,5 +1,5 @@
-import { a as CreateAdminClientOptions, i as ClientAuth, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, u as SupabaseEnv } from "../types-CbC-wBUe.mjs";
-import { i as EnvError, t as AuthError } from "../errors-CAH-RRA3.mjs";
+import { a as CreateAdminClientOptions, i as ClientAuth, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, u as SupabaseEnv } from "../types-DKe8uOwI.mjs";
+import { i as EnvError, t as AuthError } from "../errors-m42mkqhD.mjs";
 import { SupabaseClient } from "@supabase/supabase-js";
 
 //#region src/core/resolve-env.d.ts
@@ -72,8 +72,11 @@ interface VerifyCredentialsOptions {
 /**
  * Verifies pre-extracted credentials against one or more allowed auth modes.
  *
- * Tries each mode in order — first match wins. Use {@link verifyAuth} to extract
- * and verify in a single call.
+ * Tries each mode in order — first match wins. A mode is only tried when its
+ * credential is present; a JWT that is present but fails verification
+ * short-circuits the chain with `InvalidCredentialsError` instead of falling
+ * through to the next mode. Use {@link verifyAuth} to extract and verify in a
+ * single call.
  *
  * @param credentials - The credentials to verify (from {@link extractCredentials}).
  * @param options - Allowed auth modes and optional env overrides.

package/dist/core/index.mjs

@@ -1,3 +1,3 @@
-import { a as createAdminClient, i as createContextClient, n as verifyCredentials, o as resolveEnv, r as extractCredentials, t as verifyAuth } from "../verify-auth-Bt2uGltH.mjs";
+import { a as createAdminClient, i as createContextClient, n as verifyCredentials, o as resolveEnv, r as extractCredentials, t as verifyAuth } from "../verify-auth-CxFZy9rl.mjs";
 
 export { createAdminClient, createContextClient, extractCredentials, resolveEnv, verifyAuth, verifyCredentials };

package/dist/{create-supabase-context--VqMJpDu.cjs → create-supabase-context-C_8SbO5w.cjs}

@@ -1,4 +1,4 @@
-const require_verify_auth = require('./verify-auth-DrgvEuKo.cjs');
+const require_verify_auth = require('./verify-auth-C4zqDlfj.cjs');
 
 //#region src/create-supabase-context.ts
 /**

package/dist/{create-supabase-context-B3Uzt_3I.mjs → create-supabase-context-DXD5rxi1.mjs}

@@ -1,4 +1,4 @@
-import { a as createAdminClient, f as Errors, i as createContextClient, l as CreateSupabaseClientError, s as AuthError, t as verifyAuth, u as EnvError } from "./verify-auth-Bt2uGltH.mjs";
+import { a as createAdminClient, f as Errors, i as createContextClient, l as CreateSupabaseClientError, s as AuthError, t as verifyAuth, u as EnvError } from "./verify-auth-CxFZy9rl.mjs";
 
 //#region src/create-supabase-context.ts
 /**

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_verify_auth = require('./verify-auth-DrgvEuKo.cjs');
-const require_create_supabase_context = require('./create-supabase-context--VqMJpDu.cjs');
+const require_verify_auth = require('./verify-auth-C4zqDlfj.cjs');
+const require_create_supabase_context = require('./create-supabase-context-C_8SbO5w.cjs');
 let _supabase_supabase_js_cors = require("@supabase/supabase-js/cors");
 
 //#region src/cors.ts

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as CreateAdminClientOptions, c as JWTClaims, d as UserClaims, f as WithSupabaseConfig, i as ClientAuth, l as SupabaseContext, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, t as Allow, u as SupabaseEnv } from "./types-DxTr0Qum.cjs";
-import { a as EnvGenericError, c as MissingDefaultPublishableKeyError, d as MissingSecretKeyError, f as MissingSupabaseURLError, i as EnvError, l as MissingDefaultSecretKeyError, n as AuthGenericError, o as Errors, r as CreateSupabaseClientError, s as InvalidCredentialsError, t as AuthError, u as MissingPublishableKeyError } from "./errors-O2ugIMec.cjs";
+import { a as CreateAdminClientOptions, c as JWTClaims, d as UserClaims, f as WithSupabaseConfig, i as ClientAuth, l as SupabaseContext, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, t as Allow, u as SupabaseEnv } from "./types-DqhOaSlC.cjs";
+import { a as EnvGenericError, c as MissingDefaultPublishableKeyError, d as MissingSecretKeyError, f as MissingSupabaseURLError, i as EnvError, l as MissingDefaultSecretKeyError, n as AuthGenericError, o as Errors, r as CreateSupabaseClientError, s as InvalidCredentialsError, t as AuthError, u as MissingPublishableKeyError } from "./errors-Dyj5Cjt6.cjs";
 
 //#region src/with-supabase.d.ts
 /**

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as CreateAdminClientOptions, c as JWTClaims, d as UserClaims, f as WithSupabaseConfig, i as ClientAuth, l as SupabaseContext, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, t as Allow, u as SupabaseEnv } from "./types-CbC-wBUe.mjs";
-import { a as EnvGenericError, c as MissingDefaultPublishableKeyError, d as MissingSecretKeyError, f as MissingSupabaseURLError, i as EnvError, l as MissingDefaultSecretKeyError, n as AuthGenericError, o as Errors, r as CreateSupabaseClientError, s as InvalidCredentialsError, t as AuthError, u as MissingPublishableKeyError } from "./errors-CAH-RRA3.mjs";
+import { a as CreateAdminClientOptions, c as JWTClaims, d as UserClaims, f as WithSupabaseConfig, i as ClientAuth, l as SupabaseContext, n as AllowWithKey, o as CreateContextClientOptions, r as AuthResult, s as Credentials, t as Allow, u as SupabaseEnv } from "./types-DKe8uOwI.mjs";
+import { a as EnvGenericError, c as MissingDefaultPublishableKeyError, d as MissingSecretKeyError, f as MissingSupabaseURLError, i as EnvError, l as MissingDefaultSecretKeyError, n as AuthGenericError, o as Errors, r as CreateSupabaseClientError, s as InvalidCredentialsError, t as AuthError, u as MissingPublishableKeyError } from "./errors-m42mkqhD.mjs";
 
 //#region src/with-supabase.d.ts
 /**

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { _ as MissingSecretKeyError, c as AuthGenericError, d as EnvGenericError, f as Errors, g as MissingPublishableKeyError, h as MissingDefaultSecretKeyError, l as CreateSupabaseClientError, m as MissingDefaultPublishableKeyError, p as InvalidCredentialsError, s as AuthError, u as EnvError, v as MissingSupabaseURLError } from "./verify-auth-Bt2uGltH.mjs";
-import { t as createSupabaseContext } from "./create-supabase-context-B3Uzt_3I.mjs";
+import { _ as MissingSecretKeyError, c as AuthGenericError, d as EnvGenericError, f as Errors, g as MissingPublishableKeyError, h as MissingDefaultSecretKeyError, l as CreateSupabaseClientError, m as MissingDefaultPublishableKeyError, p as InvalidCredentialsError, s as AuthError, u as EnvError, v as MissingSupabaseURLError } from "./verify-auth-CxFZy9rl.mjs";
+import { t as createSupabaseContext } from "./create-supabase-context-DXD5rxi1.mjs";
 import { corsHeaders } from "@supabase/supabase-js/cors";
 
 //#region src/cors.ts

package/dist/{types-CbC-wBUe.d.mts → types-DKe8uOwI.d.mts}

@@ -14,7 +14,10 @@ import { SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
  * // Single mode
  * withSupabase({ allow: 'user' }, handler)
  *
- * // Multiple modes — the first match wins
+ * // Multiple modes — the first match wins.
+ * // A mode is tried only when its credential is present; a JWT that is
+ * // present but fails verification rejects immediately rather than falling
+ * // through to the next mode.
  * withSupabase({ allow: ['user', 'public'] }, handler)
  * ```
  */
@@ -182,6 +185,8 @@ interface UserClaims {
 interface WithSupabaseConfig {
   /**
    * Auth mode(s) to accept. Modes are tried in order — the first match wins.
+   * A mode falls through only when its credential is absent; a present-but-invalid
+   * JWT short-circuits the chain with `InvalidCredentialsError`.
    *
    * @defaultValue `"user"`
    */

package/dist/{types-DxTr0Qum.d.cts → types-DqhOaSlC.d.cts}

@@ -14,7 +14,10 @@ import { SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
  * // Single mode
  * withSupabase({ allow: 'user' }, handler)
  *
- * // Multiple modes — the first match wins
+ * // Multiple modes — the first match wins.
+ * // A mode is tried only when its credential is present; a JWT that is
+ * // present but fails verification rejects immediately rather than falling
+ * // through to the next mode.
  * withSupabase({ allow: ['user', 'public'] }, handler)
  * ```
  */
@@ -182,6 +185,8 @@ interface UserClaims {
 interface WithSupabaseConfig {
   /**
    * Auth mode(s) to accept. Modes are tried in order — the first match wins.
+   * A mode falls through only when its credential is absent; a present-but-invalid
+   * JWT short-circuits the chain with `InvalidCredentialsError`.
    *
    * @defaultValue `"user"`
    */

package/dist/{verify-auth-DrgvEuKo.cjs → verify-auth-C4zqDlfj.cjs}

@@ -388,9 +388,15 @@ function claimsToUserClaims(claims) {
 		userMetadata: claims.user_metadata
 	};
 }
+const INVALID = Symbol("invalid");
 /**
 * Attempts to authenticate credentials against a single auth mode.
-* Returns the {@link AuthResult} on success, or `null` if the mode doesn't match.
+*
+* Returns:
+* - `AuthResult` on success.
+* - `null` if the mode doesn't apply (no relevant credential present — safe to try the next mode).
+* - `INVALID` if a credential was present but failed verification (must reject immediately).
+*
 * @internal
 */
 async function tryMode(mode, credentials, env) {
@@ -457,7 +463,7 @@ async function tryMode(mode, credentials, env) {
 			try {
 				const jwkSet = (0, jose.createLocalJWKSet)(env.jwks);
 				const { payload } = await (0, jose.jwtVerify)(credentials.token, jwkSet);
-				if (typeof payload.sub !== "string") return null;
+				if (typeof payload.sub !== "string") return INVALID;
 				const claims = payload;
 				return {
 					authType: "user",
@@ -467,7 +473,7 @@ async function tryMode(mode, credentials, env) {
 					keyName: null
 				};
 			} catch {
-				return null;
+				return INVALID;
 			}
 		default: return null;
 	}
@@ -475,8 +481,11 @@ async function tryMode(mode, credentials, env) {
 /**
 * Verifies pre-extracted credentials against one or more allowed auth modes.
 *
-* Tries each mode in order — first match wins. Use {@link verifyAuth} to extract
-* and verify in a single call.
+* Tries each mode in order — first match wins. A mode is only tried when its
+* credential is present; a JWT that is present but fails verification
+* short-circuits the chain with `InvalidCredentialsError` instead of falling
+* through to the next mode. Use {@link verifyAuth} to extract and verify in a
+* single call.
 *
 * @param credentials - The credentials to verify (from {@link extractCredentials}).
 * @param options - Allowed auth modes and optional env overrides.
@@ -502,6 +511,10 @@ async function verifyCredentials(credentials, options) {
 	const modes = Array.isArray(options.allow) ? options.allow : [options.allow];
 	for (const mode of modes) {
 		const result = await tryMode(mode, credentials, env);
+		if (result === INVALID) return {
+			data: null,
+			error: Errors[InvalidCredentialsError]()
+		};
 		if (result) return {
 			data: result,
 			error: null

package/dist/{verify-auth-Bt2uGltH.mjs → verify-auth-CxFZy9rl.mjs}

@@ -388,9 +388,15 @@ function claimsToUserClaims(claims) {
 		userMetadata: claims.user_metadata
 	};
 }
+const INVALID = Symbol("invalid");
 /**
 * Attempts to authenticate credentials against a single auth mode.
-* Returns the {@link AuthResult} on success, or `null` if the mode doesn't match.
+*
+* Returns:
+* - `AuthResult` on success.
+* - `null` if the mode doesn't apply (no relevant credential present — safe to try the next mode).
+* - `INVALID` if a credential was present but failed verification (must reject immediately).
+*
 * @internal
 */
 async function tryMode(mode, credentials, env) {
@@ -457,7 +463,7 @@ async function tryMode(mode, credentials, env) {
 			try {
 				const jwkSet = createLocalJWKSet(env.jwks);
 				const { payload } = await jwtVerify(credentials.token, jwkSet);
-				if (typeof payload.sub !== "string") return null;
+				if (typeof payload.sub !== "string") return INVALID;
 				const claims = payload;
 				return {
 					authType: "user",
@@ -467,7 +473,7 @@ async function tryMode(mode, credentials, env) {
 					keyName: null
 				};
 			} catch {
-				return null;
+				return INVALID;
 			}
 		default: return null;
 	}
@@ -475,8 +481,11 @@ async function tryMode(mode, credentials, env) {
 /**
 * Verifies pre-extracted credentials against one or more allowed auth modes.
 *
-* Tries each mode in order — first match wins. Use {@link verifyAuth} to extract
-* and verify in a single call.
+* Tries each mode in order — first match wins. A mode is only tried when its
+* credential is present; a JWT that is present but fails verification
+* short-circuits the chain with `InvalidCredentialsError` instead of falling
+* through to the next mode. Use {@link verifyAuth} to extract and verify in a
+* single call.
 *
 * @param credentials - The credentials to verify (from {@link extractCredentials}).
 * @param options - Allowed auth modes and optional env overrides.
@@ -502,6 +511,10 @@ async function verifyCredentials(credentials, options) {
 	const modes = Array.isArray(options.allow) ? options.allow : [options.allow];
 	for (const mode of modes) {
 		const result = await tryMode(mode, credentials, env);
+		if (result === INVALID) return {
+			data: null,
+			error: Errors[InvalidCredentialsError]()
+		};
 		if (result) return {
 			data: result,
 			error: null

package/docs/api-reference.md

@@ -291,17 +291,17 @@ class AuthError extends Error {
 
 ## Error Code Constants
 
-| Constant                            | Value                               | Class       | Meaning                           |
-| ----------------------------------- | ----------------------------------- | ----------- | --------------------------------- |
-| `EnvGenericError`                   | `'ENV_ERROR'`                       | `EnvError`  | Generic environment error         |
-| `MissingSupabaseURLError`           | `'MISSING_SUPABASE_URL'`            | `EnvError`  | `SUPABASE_URL` not set            |
-| `MissingPublishableKeyError`        | `'MISSING_PUBLISHABLE_KEY'`         | `EnvError`  | Named publishable key not found   |
-| `MissingDefaultPublishableKeyError` | `'MISSING_DEFAULT_PUBLISHABLE_KEY'` | `EnvError`  | No default publishable key        |
-| `MissingSecretKeyError`             | `'MISSING_SECRET_KEY'`              | `EnvError`  | Named secret key not found        |
-| `MissingDefaultSecretKeyError`      | `'MISSING_DEFAULT_SECRET_KEY'`      | `EnvError`  | No default secret key             |
-| `AuthGenericError`                  | `'AUTH_ERROR'`                      | `AuthError` | Generic auth error                |
-| `InvalidCredentialsError`           | `'INVALID_CREDENTIALS'`             | `AuthError` | No credential matched             |
-| `CreateSupabaseClientError`         | `'CREATE_SUPABASE_CLIENT_ERROR'`    | `AuthError` | Client creation failed after auth |
+| Constant                            | Value                               | Class       | Meaning                                           |
+| ----------------------------------- | ----------------------------------- | ----------- | ------------------------------------------------- |
+| `EnvGenericError`                   | `'ENV_ERROR'`                       | `EnvError`  | Generic environment error                         |
+| `MissingSupabaseURLError`           | `'MISSING_SUPABASE_URL'`            | `EnvError`  | `SUPABASE_URL` not set                            |
+| `MissingPublishableKeyError`        | `'MISSING_PUBLISHABLE_KEY'`         | `EnvError`  | Named publishable key not found                   |
+| `MissingDefaultPublishableKeyError` | `'MISSING_DEFAULT_PUBLISHABLE_KEY'` | `EnvError`  | No default publishable key                        |
+| `MissingSecretKeyError`             | `'MISSING_SECRET_KEY'`              | `EnvError`  | Named secret key not found                        |
+| `MissingDefaultSecretKeyError`      | `'MISSING_DEFAULT_SECRET_KEY'`      | `EnvError`  | No default secret key                             |
+| `AuthGenericError`                  | `'AUTH_ERROR'`                      | `AuthError` | Generic auth error                                |
+| `InvalidCredentialsError`           | `'INVALID_CREDENTIALS'`             | `AuthError` | No credential matched, or JWT failed verification |
+| `CreateSupabaseClientError`         | `'CREATE_SUPABASE_CLIENT_ERROR'`    | `AuthError` | Client creation failed after auth                 |
 
 ---
 

package/docs/auth-modes.md

@@ -147,6 +147,8 @@ 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.
+
 ## Named key syntax
 
 When your project has multiple API keys (e.g., separate keys for web, mobile, and internal services), use the colon syntax to validate against a specific named key.
@@ -198,6 +200,6 @@ withSupabase({ allow: ['user', 'public:web'] }, async (_req, ctx) => {
 
 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`
+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`.
 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/error-handling.md

@@ -21,11 +21,11 @@ Thrown when a required environment variable is missing or malformed. Always `sta
 
 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                |
+| Code                           | Status | Meaning                                                                                   |
+| ------------------------------ | ------ | ----------------------------------------------------------------------------------------- |
+| `INVALID_CREDENTIALS`          | 401    | No credential matched any allowed auth mode, or a JWT was present but failed verification |
+| `CREATE_SUPABASE_CLIENT_ERROR` | 500    | Auth succeeded but client creation failed                                                 |
+| `AUTH_ERROR`                   | 401    | Generic authentication error                                                              |
 
 ## How errors surface in each layer
 

package/docs/security.md

@@ -56,10 +56,12 @@ 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.user` and `ctx.claims`
+5. On success, the decoded claims are available as `ctx.userClaims` and `ctx.claims`
 
 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.
+
 ## CORS handling
 
 `withSupabase` handles CORS automatically:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/server",
-  "version": "0.1.4",
+  "version": "0.2.0-rc.45",
   "description": "Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.",
   "keywords": [
     "edge",
@@ -34,6 +34,11 @@
       "import": "./dist/adapters/hono/index.mjs",
       "require": "./dist/adapters/hono/index.cjs"
     },
+    "./adapters/h3": {
+      "types": "./dist/adapters/h3/index.d.mts",
+      "import": "./dist/adapters/h3/index.mjs",
+      "require": "./dist/adapters/h3/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
@@ -69,9 +74,13 @@
   },
   "peerDependencies": {
     "@supabase/supabase-js": "^2.0.0",
-    "hono": "^4.0.0"
+    "hono": "^4.0.0",
+    "h3": "^2.0.0"
   },
   "peerDependenciesMeta": {
+    "h3": {
+      "optional": true
+    },
     "hono": {
       "optional": true
     }
@@ -81,6 +90,7 @@
     "@commitlint/config-conventional": "^20.4.2",
     "@supabase/supabase-js": "^2.98.0",
     "eslint": "^10.0.2",
+    "h3": "2.0.1-rc.20",
     "hono": "^4.12.5",
     "prettier": "3.8.1",
     "pretty-quick": "^4.2.2",

package/skills/supabase-server/SKILL.md

@@ -5,6 +5,8 @@ description: Use when writing server-side code with Supabase — Edge Functions,
 
 # @supabase/server
 
+> **Beta:** This package is under active development. APIs and documentation may change. If you find a bug or have a feature request, please [open an issue](https://github.com/supabase/server/issues) or [submit a PR](https://github.com/supabase/server/blob/main/CONTRIBUTING.md).
+
 > **This is a brand new package.** There is no information available online yet — no blog posts, no Stack Overflow answers, no tutorials. Do not search the web for usage examples. Rely exclusively on the documentation files listed below and the source code in this repository.
 
 > **Do not use legacy Supabase keys.** The `anon` key and `service_role` key (env vars `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`) are legacy and will be deprecated. Do not use them unless the user explicitly asks. Always use the new API keys:
@@ -22,6 +24,7 @@ Server-side utilities for Supabase. Handles auth, client creation, and context i
 
 - Wraps fetch handlers with credential verification, CORS, and pre-configured Supabase clients
 - Supports 4 auth modes: `user` (JWT), `public` (publishable key), `secret` (secret key), `always` (none)
+- Array syntax (`allow: ['user', 'secret']`) is first-match-wins. A present-but-invalid JWT rejects with `InvalidCredentialsError` — it does not silently downgrade to the next mode.
 - Provides composable core primitives for custom auth flows and framework integration
 - Includes a Hono adapter for per-route auth
 
@@ -197,6 +200,8 @@ Use `allow: 'secret'` to accept any secret key, or `allow: 'secret:name'` to req
 
 **Never use `allow: 'always'` for endpoints that read or write user data without verifying who the caller is.**
 
+**On `allow: ['user', 'always']`.** A stale or malformed JWT on such an endpoint is rejected with `InvalidCredentialsError` — it is not silently downgraded to anonymous. Callers that might hold a cached/expired token should either omit the `Authorization` header entirely or refresh before calling. If the goal is "anonymous unless a valid user is signed in," this is the correct behavior; if the goal is truly "accept anything," use `allow: 'always'` on its own.
+
 ## Edge Function recipes
 
 ### Function-to-function calls