@supabase/server 0.1.1-rc.26 → 0.1.1-rc.28

package/dist/{types-ClmJ8pi8.d.mts → types-BmWSIuH7.d.mts}

@@ -1,4 +1,4 @@
-import { SupabaseClient } from "@supabase/supabase-js";
+import { SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
 
 //#region src/types.d.ts
 /**
@@ -204,6 +204,50 @@ interface WithSupabaseConfig {
    * @defaultValue `true`
    */
   cors?: boolean | Record<string, string>;
+  /**
+   * Options forwarded to both internal `createClient()` calls.
+   *
+   * `accessToken` is stripped, and auth settings (`persistSession`, `autoRefreshToken`,
+   * `detectSessionInUrl`) are force-overwritten to server-safe values.
+   *
+   * @example
+   * ```ts
+   * withSupabase({
+   *   allow: 'user',
+   *   supabaseOptions: { db: { schema: 'api' } },
+   * }, handler)
+   * ```
+   */
+  supabaseOptions?: SupabaseClientOptions<string>;
+}
+/**
+ * Auth identity for client creation functions.
+ *
+ * @see {@link verifyAuth}, {@link verifyCredentials}
+ */
+interface ClientAuth {
+  /** The caller's JWT, or `null` for anonymous access. */
+  token?: string | null;
+  /** Name of the API key to use. Falls back to `"default"`, then first available. */
+  keyName?: string | null;
+}
+/** Options for {@link createContextClient}. */
+interface CreateContextClientOptions {
+  /** Auth identity — token and key name from the verified request. */
+  auth?: ClientAuth;
+  /** Override auto-detected environment variables. */
+  env?: Partial<SupabaseEnv>;
+  /** Options forwarded to `createClient()`. `accessToken` is stripped; auth settings are force-overwritten. */
+  supabaseOptions?: SupabaseClientOptions<string>;
+}
+/** Options for {@link createAdminClient}. */
+interface CreateAdminClientOptions {
+  /** Auth identity — key name from the verified request. */
+  auth?: Pick<ClientAuth, 'keyName'>;
+  /** Override auto-detected environment variables. */
+  env?: Partial<SupabaseEnv>;
+  /** Options forwarded to `createClient()`. `accessToken` is stripped; auth settings are force-overwritten. */
+  supabaseOptions?: SupabaseClientOptions<string>;
 }
 /**
  * The Supabase context created for each authenticated request.
@@ -224,4 +268,4 @@ interface SupabaseContext<Database = unknown> {
   authType: Allow;
 }
 //#endregion
-export { JWTClaims as a, UserClaims as c, Credentials as i, WithSupabaseConfig as l, AllowWithKey as n, SupabaseContext as o, AuthResult as r, SupabaseEnv as s, Allow as t };
+export { CreateAdminClientOptions as a, JWTClaims as c, UserClaims as d, WithSupabaseConfig as f, ClientAuth as i, SupabaseContext as l, AllowWithKey as n, CreateContextClientOptions as o, AuthResult as r, Credentials as s, Allow as t, SupabaseEnv as u };

package/dist/{types-CnKoFCMX.d.cts → types-X7xYi2LN.d.cts}

@@ -1,4 +1,4 @@
-import { SupabaseClient } from "@supabase/supabase-js";
+import { SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
 
 //#region src/types.d.ts
 /**
@@ -204,6 +204,50 @@ interface WithSupabaseConfig {
    * @defaultValue `true`
    */
   cors?: boolean | Record<string, string>;
+  /**
+   * Options forwarded to both internal `createClient()` calls.
+   *
+   * `accessToken` is stripped, and auth settings (`persistSession`, `autoRefreshToken`,
+   * `detectSessionInUrl`) are force-overwritten to server-safe values.
+   *
+   * @example
+   * ```ts
+   * withSupabase({
+   *   allow: 'user',
+   *   supabaseOptions: { db: { schema: 'api' } },
+   * }, handler)
+   * ```
+   */
+  supabaseOptions?: SupabaseClientOptions<string>;
+}
+/**
+ * Auth identity for client creation functions.
+ *
+ * @see {@link verifyAuth}, {@link verifyCredentials}
+ */
+interface ClientAuth {
+  /** The caller's JWT, or `null` for anonymous access. */
+  token?: string | null;
+  /** Name of the API key to use. Falls back to `"default"`, then first available. */
+  keyName?: string | null;
+}
+/** Options for {@link createContextClient}. */
+interface CreateContextClientOptions {
+  /** Auth identity — token and key name from the verified request. */
+  auth?: ClientAuth;
+  /** Override auto-detected environment variables. */
+  env?: Partial<SupabaseEnv>;
+  /** Options forwarded to `createClient()`. `accessToken` is stripped; auth settings are force-overwritten. */
+  supabaseOptions?: SupabaseClientOptions<string>;
+}
+/** Options for {@link createAdminClient}. */
+interface CreateAdminClientOptions {
+  /** Auth identity — key name from the verified request. */
+  auth?: Pick<ClientAuth, 'keyName'>;
+  /** Override auto-detected environment variables. */
+  env?: Partial<SupabaseEnv>;
+  /** Options forwarded to `createClient()`. `accessToken` is stripped; auth settings are force-overwritten. */
+  supabaseOptions?: SupabaseClientOptions<string>;
 }
 /**
  * The Supabase context created for each authenticated request.
@@ -224,4 +268,4 @@ interface SupabaseContext<Database = unknown> {
   authType: Allow;
 }
 //#endregion
-export { JWTClaims as a, UserClaims as c, Credentials as i, WithSupabaseConfig as l, AllowWithKey as n, SupabaseContext as o, AuthResult as r, SupabaseEnv as s, Allow as t };
+export { CreateAdminClientOptions as a, JWTClaims as c, UserClaims as d, WithSupabaseConfig as f, ClientAuth as i, SupabaseContext as l, AllowWithKey as n, CreateContextClientOptions as o, AuthResult as r, Credentials as s, Allow as t, SupabaseEnv as u };

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

@@ -5,8 +5,7 @@ import { createLocalJWKSet, jwtVerify } from "jose";
 /**
 * Thrown when a required environment variable is missing or malformed.
 *
-* Has a fixed `status` of `500` since environment errors are server-side
-* configuration issues, not client errors.
+* Always has `status: 500` — environment errors are server-side configuration issues.
 *
 * @example
 * ```ts
@@ -23,13 +22,32 @@ import { createLocalJWKSet, jwtVerify } from "jose";
 * ```
 */
 var EnvError = class extends Error {
-	constructor(message, code = "ENV_ERROR") {
+	constructor(message, code = EnvGenericError) {
 		super(message);
 		this.status = 500;
 		this.name = "EnvError";
 		this.code = code;
 	}
 };
+/** Generic environment error code. */
+const EnvGenericError = "ENV_ERROR";
+/** `SUPABASE_URL` is not set. */
+const MissingSupabaseURLError = "MISSING_SUPABASE_URL";
+/** Named publishable key not found in `SUPABASE_PUBLISHABLE_KEYS`. */
+const MissingPublishableKeyError = "MISSING_PUBLISHABLE_KEY";
+/** No default publishable key found. */
+const MissingDefaultPublishableKeyError = "MISSING_DEFAULT_PUBLISHABLE_KEY";
+/** Named secret key not found in `SUPABASE_SECRET_KEYS`. */
+const MissingSecretKeyError = "MISSING_SECRET_KEY";
+/** No default secret key found. */
+const MissingDefaultSecretKeyError = "MISSING_DEFAULT_SECRET_KEY";
+const EnvErrorMap = {
+	[MissingSupabaseURLError]: () => new EnvError("SUPABASE_URL is required but not set", MissingSupabaseURLError),
+	[MissingSecretKeyError]: (name) => new EnvError(`No "${name}" secret key found. Include a "${name}" entry in SUPABASE_SECRET_KEYS.`, MissingSecretKeyError),
+	[MissingDefaultSecretKeyError]: () => new EnvError("No default secret key found. Set SUPABASE_SECRET_KEY or include a \"default\" entry in SUPABASE_SECRET_KEYS.", MissingDefaultSecretKeyError),
+	[MissingPublishableKeyError]: (name) => new EnvError(`No "${name}" publishable key found. Include a "${name}" entry in SUPABASE_PUBLISHABLE_KEYS.`, MissingPublishableKeyError),
+	[MissingDefaultPublishableKeyError]: () => new EnvError("No default publishable key found. Set SUPABASE_PUBLISHABLE_KEY or include a \"default\" entry in SUPABASE_PUBLISHABLE_KEYS.", MissingDefaultPublishableKeyError)
+};
 /**
 * Thrown when authentication or authorization fails.
 *
@@ -44,20 +62,44 @@ var EnvError = class extends Error {
 * if (error) {
 *   // error is an AuthError
 *   return Response.json(
-*     { error: error.message, code: error.code },
+*     { message: error.message, code: error.code },
 *     { status: error.status },
 *   )
 * }
 * ```
 */
 var AuthError = class extends Error {
-	constructor(message, code = "AUTH_ERROR", status = 401) {
+	constructor(message, code = AuthGenericError, status = 401) {
 		super(message);
 		this.name = "AuthError";
 		this.code = code;
 		this.status = status;
 	}
 };
+/** Generic authentication error code. */
+const AuthGenericError = "AUTH_ERROR";
+/** No credential matched any allowed auth mode. */
+const InvalidCredentialsError = "INVALID_CREDENTIALS";
+/** Failed to create a Supabase client after auth succeeded. */
+const CreateSupabaseClientError = "CREATE_SUPABASE_CLIENT_ERROR";
+const AuthErrorMap = {
+	[InvalidCredentialsError]: () => new AuthError("Invalid credentials", InvalidCredentialsError, 401),
+	[CreateSupabaseClientError]: () => new AuthError("Failed to create Supabase client", CreateSupabaseClientError, 500)
+};
+/**
+* Factory map for all error types. Keyed by error code constant, each entry
+* returns a pre-configured {@link EnvError} or {@link AuthError}.
+*
+* @example
+* ```ts
+* throw Errors[MissingSupabaseURLError]()
+* throw Errors[MissingPublishableKeyError]('mobile')
+* ```
+*/
+const Errors = {
+	...EnvErrorMap,
+	...AuthErrorMap
+};
 
 //#endregion
 //#region src/core/resolve-env.ts
@@ -138,7 +180,7 @@ function resolveEnv(overrides) {
 	const url = overrides?.url ?? getEnvVar("SUPABASE_URL");
 	if (!url) return {
 		data: null,
-		error: new EnvError("SUPABASE_URL is required but not set", "MISSING_SUPABASE_URL")
+		error: Errors[MissingSupabaseURLError]()
 	};
 	return {
 		data: {
@@ -157,11 +199,8 @@ function resolveEnv(overrides) {
 * Creates an admin Supabase client that bypasses Row-Level Security.
 *
 * Uses a secret key for authentication, giving full access to all data.
-* Session persistence is disabled (stateless, one client per request).
+* Stateless — one client per request.
 *
-* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
-* @param keyName - Name of the secret key to use. Falls back to `"default"`, then first available.
-* @returns A configured {@link SupabaseClient} with admin (service-role) privileges.
 * @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
 *
 * @example
@@ -170,18 +209,32 @@ function resolveEnv(overrides) {
 * const { data } = await supabaseAdmin.from('audit_log').insert({ action: 'user_login' })
 * ```
 */
-function createAdminClient(env, keyName) {
-	const { data: resolved, error } = resolveEnv(env);
+function createAdminClient(options) {
+	const { data: resolved, error } = resolveEnv(options?.env);
 	if (error) throw error;
+	const keyName = options?.auth?.keyName;
+	const supabaseOptions = options?.supabaseOptions;
 	const name = keyName ?? "default";
 	const keys = resolved.secretKeys;
 	const secretKey = keys[name] ?? (keyName == null ? Object.values(keys)[0] : void 0);
-	if (!secretKey) throw new EnvError(name === "default" ? "No default secret key found. Set SUPABASE_SECRET_KEY or include a \"default\" entry in SUPABASE_SECRET_KEYS." : `No "${name}" secret key found. Include a "${name}" entry in SUPABASE_SECRET_KEYS.`, "MISSING_SECRET_KEY");
-	return createClient(resolved.url, secretKey, { auth: {
-		persistSession: false,
-		autoRefreshToken: false,
-		detectSessionInUrl: false
-	} });
+	if (!secretKey) throw name === "default" ? Errors[MissingDefaultSecretKeyError]() : Errors[MissingSecretKeyError](name);
+	const safeHeaders = { ...supabaseOptions?.global?.headers };
+	delete safeHeaders.Authorization;
+	delete safeHeaders.apikey;
+	return createClient(resolved.url, secretKey, {
+		...supabaseOptions,
+		accessToken: void 0,
+		global: {
+			...supabaseOptions?.global,
+			headers: safeHeaders
+		},
+		auth: {
+			...supabaseOptions?.auth,
+			persistSession: false,
+			autoRefreshToken: false,
+			detectSessionInUrl: false
+		}
+	});
 }
 
 //#endregion
@@ -190,32 +243,44 @@ function createAdminClient(env, keyName) {
 * Creates a Supabase client scoped to the caller's context.
 *
 * Configured with a publishable key and (optionally) the caller's JWT,
-* so Row-Level Security policies apply. Session persistence is disabled
-* (stateless, one client per request).
+* so Row-Level Security policies apply. Stateless — one client per request.
 *
-* @param token - The caller's JWT, or `null` for anonymous access.
-* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
-* @param keyName - Name of the publishable key to use. Falls back to `"default"`, then first available.
-* @returns A configured {@link SupabaseClient} with RLS enforced.
 * @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
 *
 * @example
 * ```ts
 * const { data: auth } = await verifyAuth(request, { allow: 'user' })
-* const supabase = createContextClient(auth.token)
+* const supabase = createContextClient({
+*   auth: { token: auth.token, keyName: auth.keyName },
+* })
 * const { data } = await supabase.rpc('get_my_items')
 * ```
 */
-function createContextClient(token, env, keyName) {
-	const { data: resolved, error } = resolveEnv(env);
+function createContextClient(options) {
+	const { data: resolved, error } = resolveEnv(options?.env);
 	if (error) throw error;
+	const token = options?.auth?.token;
+	const keyName = options?.auth?.keyName;
+	const supabaseOptions = options?.supabaseOptions;
 	const name = keyName ?? "default";
 	const keys = resolved.publishableKeys;
 	const anonKey = keys[name] ?? (keyName == null ? Object.values(keys)[0] : void 0);
-	if (!anonKey) throw new EnvError(name === "default" ? "No default publishable key found. Set SUPABASE_PUBLISHABLE_KEY or include a \"default\" entry in SUPABASE_PUBLISHABLE_KEYS." : `No "${name}" publishable key found. Include a "${name}" entry in SUPABASE_PUBLISHABLE_KEYS.`, "MISSING_PUBLISHABLE_KEY");
+	if (!anonKey) throw name === "default" ? Errors[MissingDefaultPublishableKeyError]() : Errors[MissingPublishableKeyError](name);
+	const safeHeaders = { ...supabaseOptions?.global?.headers };
+	delete safeHeaders.Authorization;
+	delete safeHeaders.apikey;
 	return createClient(resolved.url, anonKey, {
-		global: { headers: token ? { Authorization: `Bearer ${token}` } : {} },
+		...supabaseOptions,
+		accessToken: void 0,
+		global: {
+			...supabaseOptions?.global,
+			headers: {
+				...safeHeaders,
+				...token ? { Authorization: `Bearer ${token}` } : {}
+			}
+		},
 		auth: {
+			...supabaseOptions?.auth,
 			persistSession: false,
 			autoRefreshToken: false,
 			detectSessionInUrl: false
@@ -424,7 +489,7 @@ async function tryMode(mode, credentials, env) {
 *   allow: ['user', 'public'],
 * })
 * if (error) {
-*   return Response.json({ error: error.message }, { status: error.status })
+*   return Response.json({ message: error.message }, { status: error.status })
 * }
 * ```
 */
@@ -444,7 +509,7 @@ async function verifyCredentials(credentials, options) {
 	}
 	return {
 		data: null,
-		error: new AuthError("Invalid credentials", "INVALID_CREDENTIALS", 401)
+		error: Errors[InvalidCredentialsError]()
 	};
 }
 
@@ -473,7 +538,7 @@ async function verifyCredentials(credentials, options) {
 * })
 *
 * if (error) {
-*   return Response.json({ error: error.message }, { status: error.status })
+*   return Response.json({ message: error.message }, { status: error.status })
 * }
 *
 * console.log(auth.userClaims!.id) // "d0f1a2b3-..."
@@ -484,4 +549,4 @@ async function verifyAuth(request, options) {
 }
 
 //#endregion
-export { createAdminClient as a, EnvError as c, createContextClient as i, verifyCredentials as n, resolveEnv as o, extractCredentials as r, AuthError as s, verifyAuth as t };
+export { MissingSecretKeyError as _, createAdminClient as a, AuthGenericError as c, EnvGenericError as d, Errors as f, MissingPublishableKeyError as g, MissingDefaultSecretKeyError as h, createContextClient as i, CreateSupabaseClientError as l, MissingDefaultPublishableKeyError as m, verifyCredentials as n, resolveEnv as o, InvalidCredentialsError as p, extractCredentials as r, AuthError as s, verifyAuth as t, EnvError as u, MissingSupabaseURLError as v };

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

@@ -5,8 +5,7 @@ let jose = require("jose");
 /**
 * Thrown when a required environment variable is missing or malformed.
 *
-* Has a fixed `status` of `500` since environment errors are server-side
-* configuration issues, not client errors.
+* Always has `status: 500` — environment errors are server-side configuration issues.
 *
 * @example
 * ```ts
@@ -23,13 +22,32 @@ let jose = require("jose");
 * ```
 */
 var EnvError = class extends Error {
-	constructor(message, code = "ENV_ERROR") {
+	constructor(message, code = EnvGenericError) {
 		super(message);
 		this.status = 500;
 		this.name = "EnvError";
 		this.code = code;
 	}
 };
+/** Generic environment error code. */
+const EnvGenericError = "ENV_ERROR";
+/** `SUPABASE_URL` is not set. */
+const MissingSupabaseURLError = "MISSING_SUPABASE_URL";
+/** Named publishable key not found in `SUPABASE_PUBLISHABLE_KEYS`. */
+const MissingPublishableKeyError = "MISSING_PUBLISHABLE_KEY";
+/** No default publishable key found. */
+const MissingDefaultPublishableKeyError = "MISSING_DEFAULT_PUBLISHABLE_KEY";
+/** Named secret key not found in `SUPABASE_SECRET_KEYS`. */
+const MissingSecretKeyError = "MISSING_SECRET_KEY";
+/** No default secret key found. */
+const MissingDefaultSecretKeyError = "MISSING_DEFAULT_SECRET_KEY";
+const EnvErrorMap = {
+	[MissingSupabaseURLError]: () => new EnvError("SUPABASE_URL is required but not set", MissingSupabaseURLError),
+	[MissingSecretKeyError]: (name) => new EnvError(`No "${name}" secret key found. Include a "${name}" entry in SUPABASE_SECRET_KEYS.`, MissingSecretKeyError),
+	[MissingDefaultSecretKeyError]: () => new EnvError("No default secret key found. Set SUPABASE_SECRET_KEY or include a \"default\" entry in SUPABASE_SECRET_KEYS.", MissingDefaultSecretKeyError),
+	[MissingPublishableKeyError]: (name) => new EnvError(`No "${name}" publishable key found. Include a "${name}" entry in SUPABASE_PUBLISHABLE_KEYS.`, MissingPublishableKeyError),
+	[MissingDefaultPublishableKeyError]: () => new EnvError("No default publishable key found. Set SUPABASE_PUBLISHABLE_KEY or include a \"default\" entry in SUPABASE_PUBLISHABLE_KEYS.", MissingDefaultPublishableKeyError)
+};
 /**
 * Thrown when authentication or authorization fails.
 *
@@ -44,20 +62,44 @@ var EnvError = class extends Error {
 * if (error) {
 *   // error is an AuthError
 *   return Response.json(
-*     { error: error.message, code: error.code },
+*     { message: error.message, code: error.code },
 *     { status: error.status },
 *   )
 * }
 * ```
 */
 var AuthError = class extends Error {
-	constructor(message, code = "AUTH_ERROR", status = 401) {
+	constructor(message, code = AuthGenericError, status = 401) {
 		super(message);
 		this.name = "AuthError";
 		this.code = code;
 		this.status = status;
 	}
 };
+/** Generic authentication error code. */
+const AuthGenericError = "AUTH_ERROR";
+/** No credential matched any allowed auth mode. */
+const InvalidCredentialsError = "INVALID_CREDENTIALS";
+/** Failed to create a Supabase client after auth succeeded. */
+const CreateSupabaseClientError = "CREATE_SUPABASE_CLIENT_ERROR";
+const AuthErrorMap = {
+	[InvalidCredentialsError]: () => new AuthError("Invalid credentials", InvalidCredentialsError, 401),
+	[CreateSupabaseClientError]: () => new AuthError("Failed to create Supabase client", CreateSupabaseClientError, 500)
+};
+/**
+* Factory map for all error types. Keyed by error code constant, each entry
+* returns a pre-configured {@link EnvError} or {@link AuthError}.
+*
+* @example
+* ```ts
+* throw Errors[MissingSupabaseURLError]()
+* throw Errors[MissingPublishableKeyError]('mobile')
+* ```
+*/
+const Errors = {
+	...EnvErrorMap,
+	...AuthErrorMap
+};
 
 //#endregion
 //#region src/core/resolve-env.ts
@@ -138,7 +180,7 @@ function resolveEnv(overrides) {
 	const url = overrides?.url ?? getEnvVar("SUPABASE_URL");
 	if (!url) return {
 		data: null,
-		error: new EnvError("SUPABASE_URL is required but not set", "MISSING_SUPABASE_URL")
+		error: Errors[MissingSupabaseURLError]()
 	};
 	return {
 		data: {
@@ -157,11 +199,8 @@ function resolveEnv(overrides) {
 * Creates an admin Supabase client that bypasses Row-Level Security.
 *
 * Uses a secret key for authentication, giving full access to all data.
-* Session persistence is disabled (stateless, one client per request).
+* Stateless — one client per request.
 *
-* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
-* @param keyName - Name of the secret key to use. Falls back to `"default"`, then first available.
-* @returns A configured {@link SupabaseClient} with admin (service-role) privileges.
 * @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
 *
 * @example
@@ -170,18 +209,32 @@ function resolveEnv(overrides) {
 * const { data } = await supabaseAdmin.from('audit_log').insert({ action: 'user_login' })
 * ```
 */
-function createAdminClient(env, keyName) {
-	const { data: resolved, error } = resolveEnv(env);
+function createAdminClient(options) {
+	const { data: resolved, error } = resolveEnv(options?.env);
 	if (error) throw error;
+	const keyName = options?.auth?.keyName;
+	const supabaseOptions = options?.supabaseOptions;
 	const name = keyName ?? "default";
 	const keys = resolved.secretKeys;
 	const secretKey = keys[name] ?? (keyName == null ? Object.values(keys)[0] : void 0);
-	if (!secretKey) throw new EnvError(name === "default" ? "No default secret key found. Set SUPABASE_SECRET_KEY or include a \"default\" entry in SUPABASE_SECRET_KEYS." : `No "${name}" secret key found. Include a "${name}" entry in SUPABASE_SECRET_KEYS.`, "MISSING_SECRET_KEY");
-	return (0, _supabase_supabase_js.createClient)(resolved.url, secretKey, { auth: {
-		persistSession: false,
-		autoRefreshToken: false,
-		detectSessionInUrl: false
-	} });
+	if (!secretKey) throw name === "default" ? Errors[MissingDefaultSecretKeyError]() : Errors[MissingSecretKeyError](name);
+	const safeHeaders = { ...supabaseOptions?.global?.headers };
+	delete safeHeaders.Authorization;
+	delete safeHeaders.apikey;
+	return (0, _supabase_supabase_js.createClient)(resolved.url, secretKey, {
+		...supabaseOptions,
+		accessToken: void 0,
+		global: {
+			...supabaseOptions?.global,
+			headers: safeHeaders
+		},
+		auth: {
+			...supabaseOptions?.auth,
+			persistSession: false,
+			autoRefreshToken: false,
+			detectSessionInUrl: false
+		}
+	});
 }
 
 //#endregion
@@ -190,32 +243,44 @@ function createAdminClient(env, keyName) {
 * Creates a Supabase client scoped to the caller's context.
 *
 * Configured with a publishable key and (optionally) the caller's JWT,
-* so Row-Level Security policies apply. Session persistence is disabled
-* (stateless, one client per request).
+* so Row-Level Security policies apply. Stateless — one client per request.
 *
-* @param token - The caller's JWT, or `null` for anonymous access.
-* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
-* @param keyName - Name of the publishable key to use. Falls back to `"default"`, then first available.
-* @returns A configured {@link SupabaseClient} with RLS enforced.
 * @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
 *
 * @example
 * ```ts
 * const { data: auth } = await verifyAuth(request, { allow: 'user' })
-* const supabase = createContextClient(auth.token)
+* const supabase = createContextClient({
+*   auth: { token: auth.token, keyName: auth.keyName },
+* })
 * const { data } = await supabase.rpc('get_my_items')
 * ```
 */
-function createContextClient(token, env, keyName) {
-	const { data: resolved, error } = resolveEnv(env);
+function createContextClient(options) {
+	const { data: resolved, error } = resolveEnv(options?.env);
 	if (error) throw error;
+	const token = options?.auth?.token;
+	const keyName = options?.auth?.keyName;
+	const supabaseOptions = options?.supabaseOptions;
 	const name = keyName ?? "default";
 	const keys = resolved.publishableKeys;
 	const anonKey = keys[name] ?? (keyName == null ? Object.values(keys)[0] : void 0);
-	if (!anonKey) throw new EnvError(name === "default" ? "No default publishable key found. Set SUPABASE_PUBLISHABLE_KEY or include a \"default\" entry in SUPABASE_PUBLISHABLE_KEYS." : `No "${name}" publishable key found. Include a "${name}" entry in SUPABASE_PUBLISHABLE_KEYS.`, "MISSING_PUBLISHABLE_KEY");
+	if (!anonKey) throw name === "default" ? Errors[MissingDefaultPublishableKeyError]() : Errors[MissingPublishableKeyError](name);
+	const safeHeaders = { ...supabaseOptions?.global?.headers };
+	delete safeHeaders.Authorization;
+	delete safeHeaders.apikey;
 	return (0, _supabase_supabase_js.createClient)(resolved.url, anonKey, {
-		global: { headers: token ? { Authorization: `Bearer ${token}` } : {} },
+		...supabaseOptions,
+		accessToken: void 0,
+		global: {
+			...supabaseOptions?.global,
+			headers: {
+				...safeHeaders,
+				...token ? { Authorization: `Bearer ${token}` } : {}
+			}
+		},
 		auth: {
+			...supabaseOptions?.auth,
 			persistSession: false,
 			autoRefreshToken: false,
 			detectSessionInUrl: false
@@ -424,7 +489,7 @@ async function tryMode(mode, credentials, env) {
 *   allow: ['user', 'public'],
 * })
 * if (error) {
-*   return Response.json({ error: error.message }, { status: error.status })
+*   return Response.json({ message: error.message }, { status: error.status })
 * }
 * ```
 */
@@ -444,7 +509,7 @@ async function verifyCredentials(credentials, options) {
 	}
 	return {
 		data: null,
-		error: new AuthError("Invalid credentials", "INVALID_CREDENTIALS", 401)
+		error: Errors[InvalidCredentialsError]()
 	};
 }
 
@@ -473,7 +538,7 @@ async function verifyCredentials(credentials, options) {
 * })
 *
 * if (error) {
-*   return Response.json({ error: error.message }, { status: error.status })
+*   return Response.json({ message: error.message }, { status: error.status })
 * }
 *
 * console.log(auth.userClaims!.id) // "d0f1a2b3-..."
@@ -490,12 +555,72 @@ Object.defineProperty(exports, 'AuthError', {
     return AuthError;
   }
 });
+Object.defineProperty(exports, 'AuthGenericError', {
+  enumerable: true,
+  get: function () {
+    return AuthGenericError;
+  }
+});
+Object.defineProperty(exports, 'CreateSupabaseClientError', {
+  enumerable: true,
+  get: function () {
+    return CreateSupabaseClientError;
+  }
+});
 Object.defineProperty(exports, 'EnvError', {
   enumerable: true,
   get: function () {
     return EnvError;
   }
 });
+Object.defineProperty(exports, 'EnvGenericError', {
+  enumerable: true,
+  get: function () {
+    return EnvGenericError;
+  }
+});
+Object.defineProperty(exports, 'Errors', {
+  enumerable: true,
+  get: function () {
+    return Errors;
+  }
+});
+Object.defineProperty(exports, 'InvalidCredentialsError', {
+  enumerable: true,
+  get: function () {
+    return InvalidCredentialsError;
+  }
+});
+Object.defineProperty(exports, 'MissingDefaultPublishableKeyError', {
+  enumerable: true,
+  get: function () {
+    return MissingDefaultPublishableKeyError;
+  }
+});
+Object.defineProperty(exports, 'MissingDefaultSecretKeyError', {
+  enumerable: true,
+  get: function () {
+    return MissingDefaultSecretKeyError;
+  }
+});
+Object.defineProperty(exports, 'MissingPublishableKeyError', {
+  enumerable: true,
+  get: function () {
+    return MissingPublishableKeyError;
+  }
+});
+Object.defineProperty(exports, 'MissingSecretKeyError', {
+  enumerable: true,
+  get: function () {
+    return MissingSecretKeyError;
+  }
+});
+Object.defineProperty(exports, 'MissingSupabaseURLError', {
+  enumerable: true,
+  get: function () {
+    return MissingSupabaseURLError;
+  }
+});
 Object.defineProperty(exports, 'createAdminClient', {
   enumerable: true,
   get: function () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/server",
-  "version": "0.1.1-rc.26",
+  "version": "0.1.1-rc.28",
   "description": "Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.",
   "keywords": [
     "edge",