@supabase/server 1.0.1-rc.57 → 1.1.0-rc.58

package/README.md

@@ -400,19 +400,20 @@ export default {
 
 Automatically available in Supabase Edge Functions:
 
-| Variable                    | Format                                                        | Description                           |
-| --------------------------- | ------------------------------------------------------------- | ------------------------------------- |
-| `SUPABASE_URL`              | `https://<ref>.supabase.co`                                   | Your project URL                      |
-| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_...","web":"sb_publishable_..."}` | Publishable API keys (named)          |
-| `SUPABASE_SECRET_KEYS`      | `{"default":"sb_secret_...","web":"sb_secret_..."}`           | Secret API keys (named)               |
-| `SUPABASE_JWKS`             | `{"keys":[...]}` or `[...]`                                   | JSON Web Key Set for JWT verification |
+| Variable                    | Format                                                        | Description                                  |
+| --------------------------- | ------------------------------------------------------------- | -------------------------------------------- |
+| `SUPABASE_URL`              | `https://<ref>.supabase.co`                                   | Your project URL                             |
+| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_...","web":"sb_publishable_..."}` | Publishable API keys (named)                 |
+| `SUPABASE_SECRET_KEYS`      | `{"default":"sb_secret_...","web":"sb_secret_..."}`           | Secret API keys (named)                      |
+| `SUPABASE_JWKS`             | `{"keys":[...]}` or `[...]`                                   | Inline JSON Web Key Set for JWT verification |
 
 Also supported (for local dev, self-hosted, or other runtimes):
 
-| Variable                   | Format               | Description            |
-| -------------------------- | -------------------- | ---------------------- |
-| `SUPABASE_PUBLISHABLE_KEY` | `sb_publishable_...` | Single publishable key |
-| `SUPABASE_SECRET_KEY`      | `sb_secret_...`      | Single secret key      |
+| Variable                   | Format               | Description                                               |
+| -------------------------- | -------------------- | --------------------------------------------------------- |
+| `SUPABASE_PUBLISHABLE_KEY` | `sb_publishable_...` | Single publishable key                                    |
+| `SUPABASE_SECRET_KEY`      | `sb_secret_...`      | Single secret key                                         |
+| `SUPABASE_JWKS_URL`        | `https://...`        | Remote JWKS endpoint (used when `SUPABASE_JWKS` is unset) |
 
 When both singular and plural forms are set, plural takes priority.
 

package/dist/adapters/h3/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_create_supabase_context = require('../../create-supabase-context-B-2NDJhL.cjs');
+const require_create_supabase_context = require('../../create-supabase-context-Bmuv6M-5.cjs');
 let h3 = require("h3");
 
 //#region src/adapters/h3/middleware.ts

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

@@ -1,4 +1,4 @@
-import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-u7fYLtzC.cjs";
+import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-Bjy1j07i.cjs";
 import { Middleware } from "h3";
 
 //#region src/adapters/h3/middleware.d.ts

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

@@ -1,4 +1,4 @@
-import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-B2yXZjmG.mjs";
+import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-DP9l5Cvf.mjs";
 import { Middleware } from "h3";
 
 //#region src/adapters/h3/middleware.d.ts

package/dist/adapters/h3/index.mjs

@@ -1,4 +1,4 @@
-import { t as createSupabaseContext } from "../../create-supabase-context-BBZtr3D2.mjs";
+import { t as createSupabaseContext } from "../../create-supabase-context-BeZJlUBy.mjs";
 import { HTTPError, defineMiddleware } from "h3";
 
 //#region src/adapters/h3/middleware.ts

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-B-2NDJhL.cjs');
+const require_create_supabase_context = require('../../create-supabase-context-Bmuv6M-5.cjs');
 let hono_http_exception = require("hono/http-exception");
 let hono_factory = require("hono/factory");
 

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

@@ -1,4 +1,4 @@
-import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-u7fYLtzC.cjs";
+import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-Bjy1j07i.cjs";
 import { MiddlewareHandler } from "hono";
 
 //#region src/adapters/hono/middleware.d.ts

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

@@ -1,4 +1,4 @@
-import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-B2yXZjmG.mjs";
+import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-DP9l5Cvf.mjs";
 import { MiddlewareHandler } from "hono";
 
 //#region src/adapters/hono/middleware.d.ts

package/dist/adapters/hono/index.mjs

@@ -1,4 +1,4 @@
-import { t as createSupabaseContext } from "../../create-supabase-context-BBZtr3D2.mjs";
+import { t as createSupabaseContext } from "../../create-supabase-context-BeZJlUBy.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-BKZK83Y8.cjs');
+const require_verify_auth = require('../verify-auth-z-iM98dR.cjs');
 
 exports.createAdminClient = require_verify_auth.createAdminClient;
 exports.createContextClient = require_verify_auth.createContextClient;

package/dist/core/index.d.cts

@@ -1,4 +1,4 @@
-import { a as AuthResult, c as CreateContextClientOptions, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, o as ClientAuth, s as CreateAdminClientOptions } from "../types-u7fYLtzC.cjs";
+import { a as AuthResult, c as CreateContextClientOptions, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, o as ClientAuth, s as CreateAdminClientOptions } from "../types-Bjy1j07i.cjs";
 import { i as EnvError, t as AuthError } from "../errors-CZFEYnV_.cjs";
 import { SupabaseClient } from "@supabase/supabase-js";
 
@@ -7,8 +7,9 @@ import { SupabaseClient } from "@supabase/supabase-js";
  * Resolves Supabase environment configuration from runtime environment variables.
  *
  * Reads `SUPABASE_URL`, keys (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`),
- * and `SUPABASE_JWKS`. Works across Deno, Node.js, and Bun. For Cloudflare Workers,
- * use `overrides` or enable node-compat.
+ * and the JWKS source (`SUPABASE_JWKS` for inline keys, or `SUPABASE_JWKS_URL`
+ * for a remote endpoint). Works across Deno, Node.js, and Bun. For Cloudflare
+ * Workers, use `overrides` or enable node-compat.
  *
  * @param overrides - Partial values that take precedence over env vars.
  * @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.

package/dist/core/index.d.mts

@@ -1,4 +1,4 @@
-import { a as AuthResult, c as CreateContextClientOptions, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, o as ClientAuth, s as CreateAdminClientOptions } from "../types-B2yXZjmG.mjs";
+import { a as AuthResult, c as CreateContextClientOptions, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, o as ClientAuth, s as CreateAdminClientOptions } from "../types-DP9l5Cvf.mjs";
 import { i as EnvError, t as AuthError } from "../errors-0dbzn5gA.mjs";
 import { SupabaseClient } from "@supabase/supabase-js";
 
@@ -7,8 +7,9 @@ import { SupabaseClient } from "@supabase/supabase-js";
  * Resolves Supabase environment configuration from runtime environment variables.
  *
  * Reads `SUPABASE_URL`, keys (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`),
- * and `SUPABASE_JWKS`. Works across Deno, Node.js, and Bun. For Cloudflare Workers,
- * use `overrides` or enable node-compat.
+ * and the JWKS source (`SUPABASE_JWKS` for inline keys, or `SUPABASE_JWKS_URL`
+ * for a remote endpoint). Works across Deno, Node.js, and Bun. For Cloudflare
+ * Workers, use `overrides` or enable node-compat.
  *
  * @param overrides - Partial values that take precedence over env vars.
  * @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.

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-CZQd36s0.mjs";
+import { a as createAdminClient, i as createContextClient, n as verifyCredentials, o as resolveEnv, r as extractCredentials, t as verifyAuth } from "../verify-auth-CZ3mB47e.mjs";
 
 export { createAdminClient, createContextClient, extractCredentials, resolveEnv, verifyAuth, verifyCredentials };

package/dist/{create-supabase-context-BBZtr3D2.mjs → create-supabase-context-BeZJlUBy.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-CZQd36s0.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-CZ3mB47e.mjs";
 
 //#region src/create-supabase-context.ts
 /**

package/dist/{create-supabase-context-B-2NDJhL.cjs → create-supabase-context-Bmuv6M-5.cjs}

@@ -1,4 +1,4 @@
-const require_verify_auth = require('./verify-auth-BKZK83Y8.cjs');
+const require_verify_auth = require('./verify-auth-z-iM98dR.cjs');
 
 //#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-BKZK83Y8.cjs');
-const require_create_supabase_context = require('./create-supabase-context-B-2NDJhL.cjs');
+const require_verify_auth = require('./verify-auth-z-iM98dR.cjs');
+const require_create_supabase_context = require('./create-supabase-context-Bmuv6M-5.cjs');
 let _supabase_supabase_js_cors = require("@supabase/supabase-js/cors");
 
 //#region src/cors.ts

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as AuthResult, c as CreateContextClientOptions, d as SupabaseContext, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, m as WithSupabaseConfig, n as AllowWithKey, o as ClientAuth, p as UserClaims, r as AuthMode, s as CreateAdminClientOptions, t as Allow, u as JWTClaims } from "./types-u7fYLtzC.cjs";
+import { a as AuthResult, c as CreateContextClientOptions, d as SupabaseContext, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, m as WithSupabaseConfig, n as AllowWithKey, o as ClientAuth, p as UserClaims, r as AuthMode, s as CreateAdminClientOptions, t as Allow, u as JWTClaims } from "./types-Bjy1j07i.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-CZFEYnV_.cjs";
 
 //#region src/with-supabase.d.ts

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as AuthResult, c as CreateContextClientOptions, d as SupabaseContext, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, m as WithSupabaseConfig, n as AllowWithKey, o as ClientAuth, p as UserClaims, r as AuthMode, s as CreateAdminClientOptions, t as Allow, u as JWTClaims } from "./types-B2yXZjmG.mjs";
+import { a as AuthResult, c as CreateContextClientOptions, d as SupabaseContext, f as SupabaseEnv, i as AuthModeWithKey, l as Credentials, m as WithSupabaseConfig, n as AllowWithKey, o as ClientAuth, p as UserClaims, r as AuthMode, s as CreateAdminClientOptions, t as Allow, u as JWTClaims } from "./types-DP9l5Cvf.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-0dbzn5gA.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-CZQd36s0.mjs";
-import { t as createSupabaseContext } from "./create-supabase-context-BBZtr3D2.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-CZ3mB47e.mjs";
+import { t as createSupabaseContext } from "./create-supabase-context-BeZJlUBy.mjs";
 import { corsHeaders } from "@supabase/supabase-js/cors";
 
 //#region src/cors.ts

package/dist/{types-B2yXZjmG.d.mts → types-Bjy1j07i.d.cts}

@@ -73,11 +73,22 @@ interface SupabaseEnv {
    */
   secretKeys: Record<string, string>;
   /**
-   * JSON Web Key Set used for JWT verification. Sourced from `SUPABASE_JWKS`.
-   * Accepts both `{ keys: [...] }` and bare `[...]` array formats.
+   * JWKS source used for JWT verification.
+   *
+   * Sourced from one of (in priority order):
+   * - `SUPABASE_JWKS` — inline JSON. Resolves to a {@link JsonWebKeySet}.
+   * - `SUPABASE_JWKS_URL` — remote endpoint. Resolves to a {@link URL}; keys
+   *   are fetched lazily and cached in memory (cooldown / max-age handled by
+   *   `jose`). `https://` is always accepted; plain `http://` is accepted
+   *   only for loopback hosts (`localhost`, `127.0.0.0/8`, `::1`) to support
+   *   the Supabase CLI. Any other `http://` URL is rejected to prevent MITM
+   *   swap-in of a forged signing key.
+   *
    * `null` when no JWKS is configured (JWT verification will be unavailable).
+   * Each env var is authoritative when set: a malformed value resolves to
+   * `null` rather than falling through to the other variable.
    */
-  jwks: JsonWebKeySet | null;
+  jwks: JsonWebKeySet | URL | null;
 }
 /**
  * A JSON Web Key Set as defined by RFC 7517.

package/dist/{types-u7fYLtzC.d.cts → types-DP9l5Cvf.d.mts}

@@ -73,11 +73,22 @@ interface SupabaseEnv {
    */
   secretKeys: Record<string, string>;
   /**
-   * JSON Web Key Set used for JWT verification. Sourced from `SUPABASE_JWKS`.
-   * Accepts both `{ keys: [...] }` and bare `[...]` array formats.
+   * JWKS source used for JWT verification.
+   *
+   * Sourced from one of (in priority order):
+   * - `SUPABASE_JWKS` — inline JSON. Resolves to a {@link JsonWebKeySet}.
+   * - `SUPABASE_JWKS_URL` — remote endpoint. Resolves to a {@link URL}; keys
+   *   are fetched lazily and cached in memory (cooldown / max-age handled by
+   *   `jose`). `https://` is always accepted; plain `http://` is accepted
+   *   only for loopback hosts (`localhost`, `127.0.0.0/8`, `::1`) to support
+   *   the Supabase CLI. Any other `http://` URL is rejected to prevent MITM
+   *   swap-in of a forged signing key.
+   *
    * `null` when no JWKS is configured (JWT verification will be unavailable).
+   * Each env var is authoritative when set: a malformed value resolves to
+   * `null` rather than falling through to the other variable.
    */
-  jwks: JsonWebKeySet | null;
+  jwks: JsonWebKeySet | URL | null;
 }
 /**
  * A JSON Web Key Set as defined by RFC 7517.

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

@@ -1,5 +1,5 @@
 import { createClient } from "@supabase/supabase-js";
-import { createLocalJWKSet, jwtVerify } from "jose";
+import { createLocalJWKSet, createRemoteJWKSet, jwtVerify } from "jose";
 
 //#region src/errors.ts
 /**
@@ -141,9 +141,10 @@ function resolveKeys(singularVar, pluralVar) {
 	return {};
 }
 /**
-* Parses a JWKS JSON string into a {@link JsonWebKeySet}.
-* Accepts both `{ keys: [...] }` and bare `[...]` array formats.
-* Returns `null` if the input is missing or malformed.
+* Parses an inline JWKS JSON string. Accepts `{ keys: [...] }` or a bare
+* array `[...]` (wrapped as `{ keys: [...] }`). Returns `null` for missing
+* or malformed input.
+*
 * @internal
 */
 function parseJwks(raw) {
@@ -158,11 +159,63 @@ function parseJwks(raw) {
 	}
 }
 /**
+* Returns true if the hostname is a loopback address — `localhost`,
+* `*.localhost`, `127.0.0.0/8`, or `::1`. Browsers treat these as secure
+* contexts because traffic never leaves the machine.
+*
+* @internal
+*/
+function isLoopbackHost(hostname) {
+	if (hostname === "localhost" || hostname.endsWith(".localhost")) return true;
+	if (hostname === "[::1]") return true;
+	if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) return true;
+	return false;
+}
+/**
+* Parses a JWKS endpoint URL. `https://` is always accepted. Plain `http://`
+* is accepted only for loopback hosts (`localhost`, `127.0.0.0/8`, `::1`) so
+* the Supabase CLI flow works against `http://localhost:54321`. For any
+* other host, http is rejected: a MITM on the JWKS fetch could swap in an
+* attacker-controlled key and forge JWTs that pass verification. Returns
+* `null` for missing or malformed input.
+*
+* @internal
+*/
+function parseJwksUrl(raw) {
+	if (!raw) return null;
+	const trimmed = raw.trim();
+	try {
+		const url = new URL(trimmed);
+		if (url.protocol === "https:") return url;
+		if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Resolves the JWKS source from `SUPABASE_JWKS` (inline JSON) or
+* `SUPABASE_JWKS_URL` (https endpoint). `SUPABASE_JWKS` wins when set;
+* `SUPABASE_JWKS_URL` is only consulted if `SUPABASE_JWKS` is absent. Each
+* variable is treated as authoritative — if set but malformed, the result is
+* `null` and the other variable is *not* consulted as a fallback.
+*
+* @internal
+*/
+function resolveJwks() {
+	const rawJwks = getEnvVar("SUPABASE_JWKS");
+	if (rawJwks && rawJwks.trim()) return parseJwks(rawJwks);
+	const rawJwksUrl = getEnvVar("SUPABASE_JWKS_URL");
+	if (rawJwksUrl && rawJwksUrl.trim()) return parseJwksUrl(rawJwksUrl);
+	return null;
+}
+/**
 * Resolves Supabase environment configuration from runtime environment variables.
 *
 * Reads `SUPABASE_URL`, keys (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`),
-* and `SUPABASE_JWKS`. Works across Deno, Node.js, and Bun. For Cloudflare Workers,
-* use `overrides` or enable node-compat.
+* and the JWKS source (`SUPABASE_JWKS` for inline keys, or `SUPABASE_JWKS_URL`
+* for a remote endpoint). Works across Deno, Node.js, and Bun. For Cloudflare
+* Workers, use `overrides` or enable node-compat.
 *
 * @param overrides - Partial values that take precedence over env vars.
 * @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.
@@ -187,7 +240,7 @@ function resolveEnv(overrides) {
 			url,
 			publishableKeys: overrides?.publishableKeys ?? resolveKeys("SUPABASE_PUBLISHABLE_KEY", "SUPABASE_PUBLISHABLE_KEYS"),
 			secretKeys: overrides?.secretKeys ?? resolveKeys("SUPABASE_SECRET_KEY", "SUPABASE_SECRET_KEYS"),
-			jwks: overrides?.jwks ?? parseJwks(getEnvVar("SUPABASE_JWKS"))
+			jwks: overrides?.jwks ?? resolveJwks()
 		},
 		error: null
 	};
@@ -420,6 +473,28 @@ function jwtClaimsToUserClaims(jwtClaims) {
 	};
 }
 const INVALID = Symbol("invalid");
+let remoteJwksResolver = void 0;
+/**
+* Returns a key resolver for the given JWKS source.
+*
+* For a {@link URL}, the underlying `createRemoteJWKSet` resolver is cached
+* across requests so `jose`'s built-in cooldown / max-age caching is
+* preserved. Local JWKS objects are wrapped on every call — they're trivially
+* cheap and the object identity may change across requests.
+*
+* @internal
+*/
+function getJwksResolver(jwks) {
+	if (jwks instanceof URL) {
+		const url = jwks.toString();
+		if (remoteJwksResolver?.url !== url) remoteJwksResolver = {
+			url,
+			resolver: createRemoteJWKSet(jwks)
+		};
+		return remoteJwksResolver.resolver;
+	}
+	return createLocalJWKSet(jwks);
+}
 /**
 * Attempts to authenticate credentials against a single auth mode.
 *
@@ -492,7 +567,7 @@ async function tryMode(mode, credentials, env) {
 			if (!credentials.token) return null;
 			if (!env.jwks) return null;
 			try {
-				const jwkSet = createLocalJWKSet(env.jwks);
+				const jwkSet = getJwksResolver(env.jwks);
 				const { payload } = await jwtVerify(credentials.token, jwkSet);
 				if (typeof payload.sub !== "string") return INVALID;
 				const jwtClaims = payload;

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

@@ -141,9 +141,10 @@ function resolveKeys(singularVar, pluralVar) {
 	return {};
 }
 /**
-* Parses a JWKS JSON string into a {@link JsonWebKeySet}.
-* Accepts both `{ keys: [...] }` and bare `[...]` array formats.
-* Returns `null` if the input is missing or malformed.
+* Parses an inline JWKS JSON string. Accepts `{ keys: [...] }` or a bare
+* array `[...]` (wrapped as `{ keys: [...] }`). Returns `null` for missing
+* or malformed input.
+*
 * @internal
 */
 function parseJwks(raw) {
@@ -158,11 +159,63 @@ function parseJwks(raw) {
 	}
 }
 /**
+* Returns true if the hostname is a loopback address — `localhost`,
+* `*.localhost`, `127.0.0.0/8`, or `::1`. Browsers treat these as secure
+* contexts because traffic never leaves the machine.
+*
+* @internal
+*/
+function isLoopbackHost(hostname) {
+	if (hostname === "localhost" || hostname.endsWith(".localhost")) return true;
+	if (hostname === "[::1]") return true;
+	if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname)) return true;
+	return false;
+}
+/**
+* Parses a JWKS endpoint URL. `https://` is always accepted. Plain `http://`
+* is accepted only for loopback hosts (`localhost`, `127.0.0.0/8`, `::1`) so
+* the Supabase CLI flow works against `http://localhost:54321`. For any
+* other host, http is rejected: a MITM on the JWKS fetch could swap in an
+* attacker-controlled key and forge JWTs that pass verification. Returns
+* `null` for missing or malformed input.
+*
+* @internal
+*/
+function parseJwksUrl(raw) {
+	if (!raw) return null;
+	const trimmed = raw.trim();
+	try {
+		const url = new URL(trimmed);
+		if (url.protocol === "https:") return url;
+		if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Resolves the JWKS source from `SUPABASE_JWKS` (inline JSON) or
+* `SUPABASE_JWKS_URL` (https endpoint). `SUPABASE_JWKS` wins when set;
+* `SUPABASE_JWKS_URL` is only consulted if `SUPABASE_JWKS` is absent. Each
+* variable is treated as authoritative — if set but malformed, the result is
+* `null` and the other variable is *not* consulted as a fallback.
+*
+* @internal
+*/
+function resolveJwks() {
+	const rawJwks = getEnvVar("SUPABASE_JWKS");
+	if (rawJwks && rawJwks.trim()) return parseJwks(rawJwks);
+	const rawJwksUrl = getEnvVar("SUPABASE_JWKS_URL");
+	if (rawJwksUrl && rawJwksUrl.trim()) return parseJwksUrl(rawJwksUrl);
+	return null;
+}
+/**
 * Resolves Supabase environment configuration from runtime environment variables.
 *
 * Reads `SUPABASE_URL`, keys (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`),
-* and `SUPABASE_JWKS`. Works across Deno, Node.js, and Bun. For Cloudflare Workers,
-* use `overrides` or enable node-compat.
+* and the JWKS source (`SUPABASE_JWKS` for inline keys, or `SUPABASE_JWKS_URL`
+* for a remote endpoint). Works across Deno, Node.js, and Bun. For Cloudflare
+* Workers, use `overrides` or enable node-compat.
 *
 * @param overrides - Partial values that take precedence over env vars.
 * @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.
@@ -187,7 +240,7 @@ function resolveEnv(overrides) {
 			url,
 			publishableKeys: overrides?.publishableKeys ?? resolveKeys("SUPABASE_PUBLISHABLE_KEY", "SUPABASE_PUBLISHABLE_KEYS"),
 			secretKeys: overrides?.secretKeys ?? resolveKeys("SUPABASE_SECRET_KEY", "SUPABASE_SECRET_KEYS"),
-			jwks: overrides?.jwks ?? parseJwks(getEnvVar("SUPABASE_JWKS"))
+			jwks: overrides?.jwks ?? resolveJwks()
 		},
 		error: null
 	};
@@ -420,6 +473,28 @@ function jwtClaimsToUserClaims(jwtClaims) {
 	};
 }
 const INVALID = Symbol("invalid");
+let remoteJwksResolver = void 0;
+/**
+* Returns a key resolver for the given JWKS source.
+*
+* For a {@link URL}, the underlying `createRemoteJWKSet` resolver is cached
+* across requests so `jose`'s built-in cooldown / max-age caching is
+* preserved. Local JWKS objects are wrapped on every call — they're trivially
+* cheap and the object identity may change across requests.
+*
+* @internal
+*/
+function getJwksResolver(jwks) {
+	if (jwks instanceof URL) {
+		const url = jwks.toString();
+		if (remoteJwksResolver?.url !== url) remoteJwksResolver = {
+			url,
+			resolver: (0, jose.createRemoteJWKSet)(jwks)
+		};
+		return remoteJwksResolver.resolver;
+	}
+	return (0, jose.createLocalJWKSet)(jwks);
+}
 /**
 * Attempts to authenticate credentials against a single auth mode.
 *
@@ -492,7 +567,7 @@ async function tryMode(mode, credentials, env) {
 			if (!credentials.token) return null;
 			if (!env.jwks) return null;
 			try {
-				const jwkSet = (0, jose.createLocalJWKSet)(env.jwks);
+				const jwkSet = getJwksResolver(env.jwks);
 				const { payload } = await (0, jose.jwtVerify)(credentials.token, jwkSet);
 				if (typeof payload.sub !== "string") return INVALID;
 				const jwtClaims = payload;

package/docs/environment-variables.md

@@ -2,25 +2,25 @@
 
 On Supabase Platform and Local Development (CLI), all variables are auto-provisioned — no configuration needed
 
-| Variable                    | Format                             | Description                           | Available in                      |
-| --------------------------- | ---------------------------------- | ------------------------------------- | --------------------------------- |
-| `SUPABASE_URL`              | `https://<ref>.supabase.co`        | Your Supabase project URL             | All                               |
-| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_..."}` | Named publishable keys as JSON object | All                               |
-| `SUPABASE_SECRET_KEYS`      | `{"default":"sb_secret_..."}`      | Named secret keys as JSON object      | All                               |
-| `SUPABASE_JWKS`             | `{"keys":[...]}` or `[...]`        | JSON Web Key Set for JWT verification | All                               |
-| `SUPABASE_PUBLISHABLE_KEY`  | `sb_publishable_...`               | Single publishable key (fallback)     | Self-hosted, if manually exported |
-| `SUPABASE_SECRET_KEY`       | `sb_secret_...`                    | Single secret key (fallback)          | Self-hosted, if manually exported |
+| Variable                    | Format                             | Description                                  | Available in                      |
+| --------------------------- | ---------------------------------- | -------------------------------------------- | --------------------------------- |
+| `SUPABASE_URL`              | `https://<ref>.supabase.co`        | Your Supabase project URL                    | All                               |
+| `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_..."}` | Named publishable keys as JSON object        | All                               |
+| `SUPABASE_SECRET_KEYS`      | `{"default":"sb_secret_..."}`      | Named secret keys as JSON object             | All                               |
+| `SUPABASE_JWKS`             | `{"keys":[...]}` or `[...]`        | Inline JSON Web Key Set for JWT verification | All                               |
+| `SUPABASE_PUBLISHABLE_KEY`  | `sb_publishable_...`               | Single publishable key (fallback)            | Self-hosted, if manually exported |
+| `SUPABASE_SECRET_KEY`       | `sb_secret_...`                    | Single secret key (fallback)                 | Self-hosted, if manually exported |
 
 ## Non-Supabase environments (Node.js, Bun, Cloudflare, self-hosted)
 
 Set these based on which auth modes your app uses:
 
-| Variable                   | Required when                             |
-| -------------------------- | ----------------------------------------- |
-| `SUPABASE_URL`             | Always                                    |
-| `SUPABASE_SECRET_KEY`      | `auth: 'secret'` or using `supabaseAdmin` |
-| `SUPABASE_PUBLISHABLE_KEY` | `auth: 'publishable'`                     |
-| `SUPABASE_JWKS`            | `auth: 'user'` (JWT verification)         |
+| Variable                               | Required when                             |
+| -------------------------------------- | ----------------------------------------- |
+| `SUPABASE_URL`                         | Always                                    |
+| `SUPABASE_SECRET_KEY`                  | `auth: 'secret'` or using `supabaseAdmin` |
+| `SUPABASE_PUBLISHABLE_KEY`             | `auth: 'publishable'`                     |
+| `SUPABASE_JWKS` or `SUPABASE_JWKS_URL` | `auth: 'user'` (JWT verification)         |
 
 ### Minimal `.env` example
 
@@ -75,19 +75,34 @@ The singular form is a convenience for the common case where you only have one k
 
 When both singular and plural forms are set, the plural form takes priority.
 
-## JWKS format
+## JWKS source
 
-`SUPABASE_JWKS` accepts two formats:
+JWT verification (`auth: 'user'`) needs a JWKS. There are two ways to provide one:
 
 ```
-# Standard JWKS format
+# Inline JSON — standard JWKS format
 SUPABASE_JWKS={"keys":[{"kty":"RSA","n":"...","e":"AQAB"}]}
 
-# Bare array (convenience)
+# Inline JSON — bare array (convenience, wrapped as { keys: [...] })
 SUPABASE_JWKS=[{"kty":"RSA","n":"...","e":"AQAB"}]
+
+# Remote JWKS endpoint — keys are fetched on demand and cached in memory.
+# HTTPS is required for any non-loopback host; plain http:// is rejected
+# (a MITM on the JWKS fetch could swap in an attacker-controlled key and
+# forge JWTs that verify). http:// is allowed for loopback hosts only —
+# `localhost`, `127.0.0.0/8`, `::1` — to support the local Supabase CLI.
+SUPABASE_JWKS_URL=https://<ref>.supabase.co/auth/v1/.well-known/jwks.json
+
+# Local development against `supabase start`:
+SUPABASE_JWKS_URL=http://localhost:54321/auth/v1/.well-known/jwks.json
 ```
 
-When `SUPABASE_JWKS` is not set, JWT verification (`auth: 'user'`) is unavailable.
+### Resolution order
+
+1. `SUPABASE_JWKS` — when set, treated as authoritative inline JSON.
+2. `SUPABASE_JWKS_URL` — only checked when `SUPABASE_JWKS` is unset or empty.
+   Must be `https://`, except loopback hosts may use `http://`.
+3. Otherwise — `null`. JWT verification (`auth: 'user'`) is unavailable.
 
 ## Runtime-specific behavior
 
@@ -176,7 +191,8 @@ interface SupabaseEnv {
   url: string
   publishableKeys: Record<string, string>
   secretKeys: Record<string, string>
-  jwks: JsonWebKeySet | null
+  // `URL` when SUPABASE_JWKS is a remote endpoint, `JsonWebKeySet` for inline keys
+  jwks: JsonWebKeySet | URL | null
 }
 ```
 

package/package.json

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