@supabase/server 0.2.0 → 1.0.0

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

@@ -58,7 +58,7 @@ const EnvErrorMap = {
 * ```ts
 * import { AuthError, createSupabaseContext } from '@supabase/server'
 *
-* const { data: ctx, error } = await createSupabaseContext(request, { allow: 'user' })
+* const { data: ctx, error } = await createSupabaseContext(request, { auth: 'user' })
 * if (error) {
 *   // error is an AuthError
 *   return Response.json(
@@ -249,7 +249,7 @@ function createAdminClient(options) {
 *
 * @example
 * ```ts
-* 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 },
 * })
@@ -320,6 +320,37 @@ function extractCredentials(request) {
 	};
 }
 
+//#endregion
+//#region src/core/utils/deprecation.ts
+let allowDeprecationWarned = false;
+/**
+* Emits a one-time deprecation warning when the legacy `allow` option is used
+* instead of `auth`. The warning fires at most once per process to avoid
+* spamming logs in long-running servers.
+*
+* @internal
+*/
+function warnAllowDeprecated() {
+	if (allowDeprecationWarned) return;
+	allowDeprecationWarned = true;
+	console.warn("[@supabase/server] The `allow` option is deprecated and will be removed in a future major release. Use `auth` instead — e.g. `{ auth: \"user\" }` instead of `{ allow: \"user\" }`.");
+}
+/**
+* Resolves the auth mode from `auth` (preferred) or `allow` (deprecated),
+* falling back to `"user"` when neither is provided. Emits a one-time
+* deprecation warning when `allow` is used without `auth`.
+*
+* @internal
+*/
+function resolveAuthOption(options) {
+	if (options.auth !== void 0) return options.auth;
+	if (options.allow !== void 0) {
+		warnAllowDeprecated();
+		return options.allow;
+	}
+	return "user";
+}
+
 //#endregion
 //#region src/core/utils/timing-safe-equal.ts
 const encoder = new TextEncoder();
@@ -347,19 +378,19 @@ async function timingSafeEqual(a, b) {
 //#endregion
 //#region src/core/verify-credentials.ts
 /**
-* Parses an {@link AllowWithKey} string into its base mode and optional key name.
+* Parses an {@link AuthModeWithKey} string into its base mode and optional key name.
 *
 * @example
 * ```
-* parseAllowMode('user')         → { base: 'user',   keyName: null }
-* parseAllowMode('public:web')   → { base: 'public', keyName: 'web' }
-* parseAllowMode('secret:*')     → { base: 'secret', keyName: '*' }
+* parseAuthMode('user')              → { base: 'user',        keyName: null }
+* parseAuthMode('publishable:web')   → { base: 'publishable', keyName: 'web' }
+* parseAuthMode('secret:*')          → { base: 'secret',      keyName: '*' }
 * ```
 *
 * @internal
 */
-function parseAllowMode(mode) {
-	if (mode === "always" || mode === "public" || mode === "secret" || mode === "user") return {
+function parseAuthMode(mode) {
+	if (mode === "none" || mode === "publishable" || mode === "secret" || mode === "user") return {
 		base: mode,
 		keyName: null
 	};
@@ -379,13 +410,13 @@ function parseAllowMode(mode) {
 * Converts raw {@link JWTClaims} (snake_case) to a normalized {@link UserClaims} (camelCase).
 * @internal
 */
-function claimsToUserClaims(claims) {
+function jwtClaimsToUserClaims(jwtClaims) {
 	return {
-		id: claims.sub,
-		role: claims.role,
-		email: claims.email,
-		appMetadata: claims.app_metadata,
-		userMetadata: claims.user_metadata
+		id: jwtClaims.sub,
+		role: jwtClaims.role,
+		email: jwtClaims.email,
+		appMetadata: jwtClaims.app_metadata,
+		userMetadata: jwtClaims.user_metadata
 	};
 }
 const INVALID = Symbol("invalid");
@@ -400,34 +431,34 @@ const INVALID = Symbol("invalid");
 * @internal
 */
 async function tryMode(mode, credentials, env) {
-	const { base, keyName } = parseAllowMode(mode);
+	const { base, keyName } = parseAuthMode(mode);
 	switch (base) {
-		case "always": return {
-			authType: "always",
+		case "none": return {
+			authMode: "none",
 			token: null,
 			userClaims: null,
-			claims: null,
+			jwtClaims: null,
 			keyName: null
 		};
-		case "public": {
+		case "publishable": {
 			if (!credentials.apikey) return null;
 			const keys = env.publishableKeys;
 			if (keyName === "*") {
 				for (const [name, value] of Object.entries(keys)) if (await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "public",
+					authMode: "publishable",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			} else {
 				const name = keyName ?? "default";
 				const value = keys[name];
 				if (value && await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "public",
+					authMode: "publishable",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			}
@@ -438,20 +469,20 @@ async function tryMode(mode, credentials, env) {
 			const keys = env.secretKeys;
 			if (keyName === "*") {
 				for (const [name, value] of Object.entries(keys)) if (await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "secret",
+					authMode: "secret",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			} else {
 				const name = keyName ?? "default";
 				const value = keys[name];
 				if (value && await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "secret",
+					authMode: "secret",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			}
@@ -464,12 +495,12 @@ async function tryMode(mode, credentials, env) {
 				const jwkSet = (0, jose.createLocalJWKSet)(env.jwks);
 				const { payload } = await (0, jose.jwtVerify)(credentials.token, jwkSet);
 				if (typeof payload.sub !== "string") return INVALID;
-				const claims = payload;
+				const jwtClaims = payload;
 				return {
-					authType: "user",
+					authMode: "user",
 					token: credentials.token,
-					userClaims: claimsToUserClaims(claims),
-					claims,
+					userClaims: jwtClaimsToUserClaims(jwtClaims),
+					jwtClaims,
 					keyName: null
 				};
 			} catch {
@@ -495,7 +526,7 @@ async function tryMode(mode, credentials, env) {
 * ```ts
 * const credentials = extractCredentials(request)
 * const { data: auth, error } = await verifyCredentials(credentials, {
-*   allow: ['user', 'public'],
+*   auth: ['user', 'publishable'],
 * })
 * if (error) {
 *   return Response.json({ message: error.message }, { status: error.status })
@@ -508,7 +539,8 @@ async function verifyCredentials(credentials, options) {
 		data: null,
 		error: new AuthError(envError.message, envError.code, 500)
 	};
-	const modes = Array.isArray(options.allow) ? options.allow : [options.allow];
+	const resolved = resolveAuthOption(options);
+	const modes = Array.isArray(resolved) ? resolved : [resolved];
 	for (const mode of modes) {
 		const result = await tryMode(mode, credentials, env);
 		if (result === INVALID) return {
@@ -547,7 +579,7 @@ async function verifyCredentials(credentials, options) {
 * import { verifyAuth } from '@supabase/server/core'
 *
 * const { data: auth, error } = await verifyAuth(request, {
-*   allow: 'user',
+*   auth: 'user',
 * })
 *
 * if (error) {

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

@@ -58,7 +58,7 @@ const EnvErrorMap = {
 * ```ts
 * import { AuthError, createSupabaseContext } from '@supabase/server'
 *
-* const { data: ctx, error } = await createSupabaseContext(request, { allow: 'user' })
+* const { data: ctx, error } = await createSupabaseContext(request, { auth: 'user' })
 * if (error) {
 *   // error is an AuthError
 *   return Response.json(
@@ -249,7 +249,7 @@ function createAdminClient(options) {
 *
 * @example
 * ```ts
-* 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 },
 * })
@@ -320,6 +320,37 @@ function extractCredentials(request) {
 	};
 }
 
+//#endregion
+//#region src/core/utils/deprecation.ts
+let allowDeprecationWarned = false;
+/**
+* Emits a one-time deprecation warning when the legacy `allow` option is used
+* instead of `auth`. The warning fires at most once per process to avoid
+* spamming logs in long-running servers.
+*
+* @internal
+*/
+function warnAllowDeprecated() {
+	if (allowDeprecationWarned) return;
+	allowDeprecationWarned = true;
+	console.warn("[@supabase/server] The `allow` option is deprecated and will be removed in a future major release. Use `auth` instead — e.g. `{ auth: \"user\" }` instead of `{ allow: \"user\" }`.");
+}
+/**
+* Resolves the auth mode from `auth` (preferred) or `allow` (deprecated),
+* falling back to `"user"` when neither is provided. Emits a one-time
+* deprecation warning when `allow` is used without `auth`.
+*
+* @internal
+*/
+function resolveAuthOption(options) {
+	if (options.auth !== void 0) return options.auth;
+	if (options.allow !== void 0) {
+		warnAllowDeprecated();
+		return options.allow;
+	}
+	return "user";
+}
+
 //#endregion
 //#region src/core/utils/timing-safe-equal.ts
 const encoder = new TextEncoder();
@@ -347,19 +378,19 @@ async function timingSafeEqual(a, b) {
 //#endregion
 //#region src/core/verify-credentials.ts
 /**
-* Parses an {@link AllowWithKey} string into its base mode and optional key name.
+* Parses an {@link AuthModeWithKey} string into its base mode and optional key name.
 *
 * @example
 * ```
-* parseAllowMode('user')         → { base: 'user',   keyName: null }
-* parseAllowMode('public:web')   → { base: 'public', keyName: 'web' }
-* parseAllowMode('secret:*')     → { base: 'secret', keyName: '*' }
+* parseAuthMode('user')              → { base: 'user',        keyName: null }
+* parseAuthMode('publishable:web')   → { base: 'publishable', keyName: 'web' }
+* parseAuthMode('secret:*')          → { base: 'secret',      keyName: '*' }
 * ```
 *
 * @internal
 */
-function parseAllowMode(mode) {
-	if (mode === "always" || mode === "public" || mode === "secret" || mode === "user") return {
+function parseAuthMode(mode) {
+	if (mode === "none" || mode === "publishable" || mode === "secret" || mode === "user") return {
 		base: mode,
 		keyName: null
 	};
@@ -379,13 +410,13 @@ function parseAllowMode(mode) {
 * Converts raw {@link JWTClaims} (snake_case) to a normalized {@link UserClaims} (camelCase).
 * @internal
 */
-function claimsToUserClaims(claims) {
+function jwtClaimsToUserClaims(jwtClaims) {
 	return {
-		id: claims.sub,
-		role: claims.role,
-		email: claims.email,
-		appMetadata: claims.app_metadata,
-		userMetadata: claims.user_metadata
+		id: jwtClaims.sub,
+		role: jwtClaims.role,
+		email: jwtClaims.email,
+		appMetadata: jwtClaims.app_metadata,
+		userMetadata: jwtClaims.user_metadata
 	};
 }
 const INVALID = Symbol("invalid");
@@ -400,34 +431,34 @@ const INVALID = Symbol("invalid");
 * @internal
 */
 async function tryMode(mode, credentials, env) {
-	const { base, keyName } = parseAllowMode(mode);
+	const { base, keyName } = parseAuthMode(mode);
 	switch (base) {
-		case "always": return {
-			authType: "always",
+		case "none": return {
+			authMode: "none",
 			token: null,
 			userClaims: null,
-			claims: null,
+			jwtClaims: null,
 			keyName: null
 		};
-		case "public": {
+		case "publishable": {
 			if (!credentials.apikey) return null;
 			const keys = env.publishableKeys;
 			if (keyName === "*") {
 				for (const [name, value] of Object.entries(keys)) if (await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "public",
+					authMode: "publishable",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			} else {
 				const name = keyName ?? "default";
 				const value = keys[name];
 				if (value && await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "public",
+					authMode: "publishable",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			}
@@ -438,20 +469,20 @@ async function tryMode(mode, credentials, env) {
 			const keys = env.secretKeys;
 			if (keyName === "*") {
 				for (const [name, value] of Object.entries(keys)) if (await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "secret",
+					authMode: "secret",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			} else {
 				const name = keyName ?? "default";
 				const value = keys[name];
 				if (value && await timingSafeEqual(credentials.apikey, value)) return {
-					authType: "secret",
+					authMode: "secret",
 					token: null,
 					userClaims: null,
-					claims: null,
+					jwtClaims: null,
 					keyName: name
 				};
 			}
@@ -464,12 +495,12 @@ async function tryMode(mode, credentials, env) {
 				const jwkSet = createLocalJWKSet(env.jwks);
 				const { payload } = await jwtVerify(credentials.token, jwkSet);
 				if (typeof payload.sub !== "string") return INVALID;
-				const claims = payload;
+				const jwtClaims = payload;
 				return {
-					authType: "user",
+					authMode: "user",
 					token: credentials.token,
-					userClaims: claimsToUserClaims(claims),
-					claims,
+					userClaims: jwtClaimsToUserClaims(jwtClaims),
+					jwtClaims,
 					keyName: null
 				};
 			} catch {
@@ -495,7 +526,7 @@ async function tryMode(mode, credentials, env) {
 * ```ts
 * const credentials = extractCredentials(request)
 * const { data: auth, error } = await verifyCredentials(credentials, {
-*   allow: ['user', 'public'],
+*   auth: ['user', 'publishable'],
 * })
 * if (error) {
 *   return Response.json({ message: error.message }, { status: error.status })
@@ -508,7 +539,8 @@ async function verifyCredentials(credentials, options) {
 		data: null,
 		error: new AuthError(envError.message, envError.code, 500)
 	};
-	const modes = Array.isArray(options.allow) ? options.allow : [options.allow];
+	const resolved = resolveAuthOption(options);
+	const modes = Array.isArray(resolved) ? resolved : [resolved];
 	for (const mode of modes) {
 		const result = await tryMode(mode, credentials, env);
 		if (result === INVALID) return {
@@ -547,7 +579,7 @@ async function verifyCredentials(credentials, options) {
 * import { verifyAuth } from '@supabase/server/core'
 *
 * const { data: auth, error } = await verifyAuth(request, {
-*   allow: 'user',
+*   auth: 'user',
 * })
 *
 * if (error) {

package/docs/adapters/h3.md

@@ -0,0 +1,180 @@
+# H3 / Nuxt Adapter
+
+## Setup
+
+Install H3 as a peer dependency:
+
+```bash
+pnpm add h3
+```
+
+The adapter exports its own `withSupabase` that returns H3 middleware instead of a fetch handler. Works with standalone H3 servers and Nuxt server routes (which run on H3 under the hood).
+
+## Basic app with auth
+
+```ts
+import { H3 } from 'h3'
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+const app = new H3()
+
+// Apply auth to all routes
+app.use(withSupabase({ auth: 'user' }))
+
+app.get('/todos', async (event) => {
+  const { supabase } = event.context.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return data
+})
+
+app.get('/profile', async (event) => {
+  const { supabase, userClaims } = event.context.supabaseContext
+  const { data } = await supabase
+    .from('profiles')
+    .select()
+    .eq('id', userClaims!.id)
+  return data
+})
+
+export default { fetch: app.fetch }
+```
+
+The context is stored in `event.context.supabaseContext` and contains the same `SupabaseContext` fields as the main `withSupabase` wrapper: `supabase`, `supabaseAdmin`, `userClaims`, `jwtClaims`, and `authMode`.
+
+## Per-route auth
+
+Apply different auth modes to different routes by attaching the middleware to specific handlers:
+
+```ts
+import { H3 } from 'h3'
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+const app = new H3()
+
+// Public route — no auth
+app.get('/health', () => ({ status: 'ok' }))
+
+// User-authenticated route
+app.get('/todos', withSupabase({ auth: 'user' }), async (event) => {
+  const { supabase } = event.context.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return data
+})
+
+// Secret-key-protected admin route
+app.post('/admin/sync', withSupabase({ auth: 'secret' }), async (event) => {
+  const { supabaseAdmin } = event.context.supabaseContext
+  const { data } = await supabaseAdmin
+    .from('audit_log')
+    .insert({ action: 'sync' })
+  return data
+})
+
+// Dual auth — users or services
+app.get(
+  '/reports',
+  withSupabase({ auth: ['user', 'secret'] }),
+  async (event) => {
+    const { authMode } = event.context.supabaseContext
+    return { authMode }
+  },
+)
+
+export default { fetch: app.fetch }
+```
+
+## Nuxt: file-based routes
+
+Use `defineHandler` to attach auth to a single Nuxt server route:
+
+```ts
+// server/api/games.get.ts
+import { defineHandler } from 'h3'
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+export default defineHandler({
+  middleware: [withSupabase({ auth: 'user' })],
+  handler: async (event) => {
+    const { supabase } = event.context.supabaseContext
+    return supabase.from('favorite_games').select()
+  },
+})
+```
+
+## Nuxt: app-wide auth
+
+Register as a server middleware to apply auth to every route:
+
+```ts
+// server/middleware/supabase.ts
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+export default withSupabase({ auth: 'user' })
+```
+
+## Skip behavior
+
+If a previous middleware already set `event.context.supabaseContext`, subsequent `withSupabase` calls skip auth. This enables a pattern where route-level middleware overrides the app-wide default:
+
+```ts
+const app = new H3()
+
+// App-wide: require user auth
+app.use(withSupabase({ auth: 'user' }))
+
+// 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({ auth: 'secret' }), async (event) => {
+  const { supabaseAdmin } = event.context.supabaseContext
+  // ...
+})
+```
+
+## CORS
+
+The H3 adapter does not handle CORS — the `cors` option is excluded from its config type. Use H3's built-in CORS utilities:
+
+```ts
+import { H3, handleCors } from 'h3'
+import { withSupabase } from '@supabase/server/adapters/h3'
+
+const app = new H3()
+
+app.use((event) => handleCors(event, { origin: '*' }))
+app.use(withSupabase({ auth: 'user' }))
+
+app.get('/todos', async (event) => {
+  const { supabase } = event.context.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return data
+})
+
+export default { fetch: app.fetch }
+```
+
+## Environment overrides
+
+Pass `env` to override auto-detected environment variables, same as the main wrapper:
+
+```ts
+app.use(
+  withSupabase({
+    auth: 'user',
+    env: { url: 'http://localhost:54321' },
+  }),
+)
+```
+
+## Supabase client options
+
+Forward options to the underlying `createClient()` calls:
+
+```ts
+app.use(
+  withSupabase({
+    auth: 'user',
+    supabaseOptions: { db: { schema: 'api' } },
+  }),
+)
+```