@supabase/server 0.1.1 → 0.1.2

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

@@ -52,12 +52,12 @@ interface SupabaseEnv {
   /** Supabase project URL (e.g. `"https://<ref>.supabase.co"`). Sourced from `SUPABASE_URL`. */
   url: string;
   /**
-   * Named publishable (anon) keys. Sourced from `SUPABASE_PUBLISHABLE_KEYS` (JSON object)
+   * Named publishable keys. Sourced from `SUPABASE_PUBLISHABLE_KEYS` (JSON object)
    * or `SUPABASE_PUBLISHABLE_KEY` (single key, stored as `{ default: "<value>" }`).
    */
   publishableKeys: Record<string, string>;
   /**
-   * Named secret (service-role) keys. Sourced from `SUPABASE_SECRET_KEYS` (JSON object)
+   * Named secret keys. Sourced from `SUPABASE_SECRET_KEYS` (JSON object)
    * or `SUPABASE_SECRET_KEY` (single key, stored as `{ default: "<value>" }`).
    */
   secretKeys: Record<string, string>;
@@ -266,6 +266,8 @@ interface SupabaseContext<Database = unknown> {
   claims: JWTClaims | null;
   /** The auth mode that was used for this request. */
   authType: Allow;
+  /** The auth key name of the API key that was used for this request. */
+  authKeyName?: string | null;
 }
 //#endregion
 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-X7xYi2LN.d.cts → types-DxTr0Qum.d.cts}

@@ -52,12 +52,12 @@ interface SupabaseEnv {
   /** Supabase project URL (e.g. `"https://<ref>.supabase.co"`). Sourced from `SUPABASE_URL`. */
   url: string;
   /**
-   * Named publishable (anon) keys. Sourced from `SUPABASE_PUBLISHABLE_KEYS` (JSON object)
+   * Named publishable keys. Sourced from `SUPABASE_PUBLISHABLE_KEYS` (JSON object)
    * or `SUPABASE_PUBLISHABLE_KEY` (single key, stored as `{ default: "<value>" }`).
    */
   publishableKeys: Record<string, string>;
   /**
-   * Named secret (service-role) keys. Sourced from `SUPABASE_SECRET_KEYS` (JSON object)
+   * Named secret keys. Sourced from `SUPABASE_SECRET_KEYS` (JSON object)
    * or `SUPABASE_SECRET_KEY` (single key, stored as `{ default: "<value>" }`).
    */
   secretKeys: Record<string, string>;
@@ -266,6 +266,8 @@ interface SupabaseContext<Database = unknown> {
   claims: JWTClaims | null;
   /** The auth mode that was used for this request. */
   authType: Allow;
+  /** The auth key name of the API key that was used for this request. */
+  authKeyName?: string | null;
 }
 //#endregion
 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/docs/api-reference.md

@@ -0,0 +1,322 @@
+# API Reference
+
+Complete reference for every export, organized by entry point.
+
+---
+
+## @supabase/server
+
+### withSupabase
+
+```ts
+function withSupabase<Database = unknown>(
+  config: WithSupabaseConfig,
+  handler: (req: Request, ctx: SupabaseContext<Database>) => Promise<Response>,
+): (req: Request) => Promise<Response>
+```
+
+Wraps a fetch handler with auth, CORS, and client creation. Returns a `(req: Request) => Promise<Response>` function suitable for `export default { fetch }`.
+
+- Handles `OPTIONS` preflight when CORS is enabled
+- Verifies credentials per `config.allow`
+- Returns JSON error response on auth failure
+- Adds CORS headers to all responses
+
+### createSupabaseContext
+
+```ts
+function createSupabaseContext<Database = unknown>(
+  request: Request,
+  options?: WithSupabaseConfig,
+): Promise<
+  | { data: SupabaseContext<Database>; error: null }
+  | { data: null; error: AuthError }
+>
+```
+
+Creates a `SupabaseContext` from a request. Returns a result tuple. The `cors` option is ignored.
+
+Defaults to `allow: 'user'` when `options` is omitted.
+
+---
+
+## @supabase/server/core
+
+### verifyAuth
+
+```ts
+function verifyAuth(
+  request: Request,
+  options: { allow: AllowWithKey | AllowWithKey[]; env?: Partial<SupabaseEnv> },
+): Promise<{ data: AuthResult; error: null } | { data: null; error: AuthError }>
+```
+
+Extracts credentials from a request and verifies them. Convenience wrapper over `extractCredentials` + `verifyCredentials`.
+
+### verifyCredentials
+
+```ts
+function verifyCredentials(
+  credentials: Credentials,
+  options: { allow: AllowWithKey | AllowWithKey[]; env?: Partial<SupabaseEnv> },
+): Promise<{ data: AuthResult; error: null } | { data: null; error: AuthError }>
+```
+
+Verifies pre-extracted credentials against allowed auth modes. Tries each mode in order — first match wins.
+
+### extractCredentials
+
+```ts
+function extractCredentials(request: Request): Credentials
+```
+
+Reads `Authorization: Bearer <token>` and `apikey` headers from a request. Pure extraction, no validation. Synchronous.
+
+### resolveEnv
+
+```ts
+function resolveEnv(
+  overrides?: Partial<SupabaseEnv>,
+): { data: SupabaseEnv; error: null } | { data: null; error: EnvError }
+```
+
+Resolves Supabase environment configuration from runtime variables. `SUPABASE_URL` is the only hard requirement.
+
+### createContextClient
+
+```ts
+function createContextClient<Database = unknown>(
+  options?: CreateContextClientOptions,
+): SupabaseClient<Database>
+```
+
+Creates a user-scoped Supabase client. RLS applies. **Throws `EnvError`** if URL or publishable key is missing.
+
+Configured with:
+
+- Publishable key (named or default) as `apikey` header
+- User's JWT as `Authorization: Bearer` header (when `auth.token` is provided)
+- `persistSession: false`, `autoRefreshToken: false`, `detectSessionInUrl: false`
+
+### createAdminClient
+
+```ts
+function createAdminClient<Database = unknown>(
+  options?: CreateAdminClientOptions,
+): SupabaseClient<Database>
+```
+
+Creates an admin Supabase client that bypasses RLS. **Throws `EnvError`** if URL or secret key is missing.
+
+---
+
+## @supabase/server/adapters/hono
+
+### withSupabase (Hono)
+
+```ts
+function withSupabase(
+  config?: Omit<WithSupabaseConfig, 'cors'>,
+): MiddlewareHandler
+```
+
+Hono middleware. Sets `c.var.supabaseContext` on the Hono context. Throws `HTTPException` on auth failure with `cause: AuthError`.
+
+Skips if `c.var.supabaseContext` is already set (enables route-level overrides).
+
+Defaults to `allow: 'user'` when config is omitted.
+
+---
+
+## Types
+
+### Allow
+
+```ts
+type Allow = 'always' | 'public' | 'secret' | 'user'
+```
+
+### AllowWithKey
+
+```ts
+type AllowWithKey = Allow | `public:${string}` | `secret:${string}`
+```
+
+Extended auth mode with named key support. Examples: `'public:web'`, `'secret:*'`, `'secret:internal'`.
+
+### SupabaseContext\<Database\>
+
+```ts
+interface SupabaseContext<Database = unknown> {
+  supabase: SupabaseClient<Database>
+  supabaseAdmin: SupabaseClient<Database>
+  userClaims: UserClaims | null
+  claims: JWTClaims | null
+  authType: Allow
+}
+```
+
+### WithSupabaseConfig
+
+```ts
+interface WithSupabaseConfig {
+  allow?: AllowWithKey | AllowWithKey[] // default: 'user'
+  env?: Partial<SupabaseEnv>
+  cors?: boolean | Record<string, string> // default: true
+  supabaseOptions?: SupabaseClientOptions<string>
+}
+```
+
+### SupabaseEnv
+
+```ts
+interface SupabaseEnv {
+  url: string
+  publishableKeys: Record<string, string>
+  secretKeys: Record<string, string>
+  jwks: JsonWebKeySet | null
+}
+```
+
+### Credentials
+
+```ts
+interface Credentials {
+  token: string | null
+  apikey: string | null
+}
+```
+
+### AuthResult
+
+```ts
+interface AuthResult {
+  authType: Allow
+  token: string | null
+  userClaims: UserClaims | null
+  claims: JWTClaims | null
+  keyName?: string | null
+}
+```
+
+### JWTClaims
+
+```ts
+interface JWTClaims {
+  sub: string
+  iss?: string
+  aud?: string | string[]
+  exp?: number
+  iat?: number
+  role?: string
+  email?: string
+  app_metadata?: Record<string, unknown>
+  user_metadata?: Record<string, unknown>
+  [key: string]: unknown
+}
+```
+
+### UserClaims
+
+```ts
+interface UserClaims {
+  id: string
+  role?: string
+  email?: string
+  appMetadata?: Record<string, unknown>
+  userMetadata?: Record<string, unknown>
+}
+```
+
+### ClientAuth
+
+```ts
+interface ClientAuth {
+  token?: string | null
+  keyName?: string | null
+}
+```
+
+### CreateContextClientOptions
+
+```ts
+interface CreateContextClientOptions {
+  auth?: ClientAuth
+  env?: Partial<SupabaseEnv>
+  supabaseOptions?: SupabaseClientOptions<string>
+}
+```
+
+### CreateAdminClientOptions
+
+```ts
+interface CreateAdminClientOptions {
+  auth?: Pick<ClientAuth, 'keyName'>
+  env?: Partial<SupabaseEnv>
+  supabaseOptions?: SupabaseClientOptions<string>
+}
+```
+
+### JsonWebKeySet
+
+```ts
+interface JsonWebKeySet {
+  keys: JsonWebKey[]
+}
+```
+
+---
+
+## Error Classes
+
+### EnvError
+
+```ts
+class EnvError extends Error {
+  readonly status: 500
+  readonly code: string
+}
+```
+
+### AuthError
+
+```ts
+class AuthError extends Error {
+  readonly status: number // 401 or 500
+  readonly code: string
+}
+```
+
+---
+
+## 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 |
+
+---
+
+## Errors Factory Map
+
+```ts
+const Errors: {
+  [MissingSupabaseURLError]: () => EnvError
+  [MissingPublishableKeyError]: (name: string) => EnvError
+  [MissingDefaultPublishableKeyError]: () => EnvError
+  [MissingSecretKeyError]: (name: string) => EnvError
+  [MissingDefaultSecretKeyError]: () => EnvError
+  [InvalidCredentialsError]: () => AuthError
+  [CreateSupabaseClientError]: () => AuthError
+}
+```
+
+Keyed by error code constant. Each entry returns a pre-configured error instance.

package/docs/auth-modes.md

@@ -0,0 +1,203 @@
+# Auth Modes
+
+## Overview
+
+Every request is validated against one or more auth modes before your handler runs. The `allow` config determines which modes are accepted.
+
+| Mode       | Credential required                          | Typical use case                       |
+| ---------- | -------------------------------------------- | -------------------------------------- |
+| `'user'`   | Valid JWT in `Authorization: Bearer <token>` | Authenticated user endpoints           |
+| `'public'` | Valid publishable key in `apikey` header     | Client-facing, key-validated endpoints |
+| `'secret'` | Valid secret key in `apikey` header          | Server-to-server, internal calls       |
+| `'always'` | None                                         | Open endpoints, custom auth wrappers   |
+
+> **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request same as `'user'`.
+> If your function uses `'public'`, `'secret'` or `'always'`, disable the platform-level JWT check in `supabase/config.toml`:
+>
+> ```toml
+> [functions.my-function]
+> verify_jwt = false
+> ```
+
+## User mode
+
+The default. Verifies the JWT using your project's JWKS (JSON Web Key Set).
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {
+    // ctx.userClaims has the caller's identity
+    console.log(ctx.userClaims!.id) // "d0f1a2b3-..."
+    console.log(ctx.userClaims!.email) // "user@example.com"
+    console.log(ctx.userClaims!.role) // "authenticated"
+
+    // ctx.claims has the raw JWT payload
+    console.log(ctx.claims!.sub) // same as userClaims.id
+    console.log(ctx.claims!.exp) // token expiration (epoch seconds)
+
+    // ctx.supabase is scoped to this user — RLS applies
+    const { data } = await ctx.supabase.from('todos').select()
+    return Response.json(data)
+  }),
+}
+```
+
+The caller must send:
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+**`userClaims` vs `supabase.auth.getUser()`:** `userClaims` is extracted from the JWT and is available instantly — no network call. It includes `id`, `email`, `role`, `appMetadata`, and `userMetadata`. For the full Supabase `User` object (email confirmation status, providers, linked identities), call `ctx.supabase.auth.getUser()`, which makes a request to the auth server.
+
+## Public mode
+
+Validates that the `apikey` header contains a recognized publishable key. Uses timing-safe comparison to prevent timing attacks. See [`security.md`](security.md) for details.
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: 'public' }, async (_req, ctx) => {
+    // ctx.userClaims is null — no JWT involved
+    // ctx.supabase is initialized as anonymous (RLS anon role)
+    const { data } = await ctx.supabase.from('products').select()
+    return Response.json(data)
+  }),
+}
+```
+
+The caller must send:
+
+```
+apikey: sb_publishable_abc123...
+```
+
+By default, `public` mode validates against the `"default"` key in `SUPABASE_PUBLISHABLE_KEYS`. Use named key syntax to target a specific key (see below).
+
+## Secret mode
+
+Validates that the `apikey` header contains a recognized secret key. Same timing-safe comparison as public mode. See [`security.md`](security.md) for details.
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: 'secret' }, async (_req, ctx) => {
+    // ctx.supabaseAdmin bypasses RLS — use for privileged operations
+    const { data } = await ctx.supabaseAdmin.from('config').select()
+    return Response.json(data)
+  }),
+}
+```
+
+The caller must send:
+
+```
+apikey: sb_secret_xyz789...
+```
+
+## Always mode
+
+No credentials required. Every request is accepted.
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: 'always' }, async (_req, ctx) => {
+    // ctx.authType is 'always'
+    // ctx.userClaims is null
+    // ctx.supabase is anonymous (RLS anon role)
+    return Response.json({ status: 'healthy' })
+  }),
+}
+```
+
+Use `always` for health checks, public APIs, or when you handle auth yourself inside the handler.
+
+## Array syntax (multiple modes)
+
+Accept multiple auth methods. Modes are tried in order — the first match wins.
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: ['user', 'secret'] }, async (req, ctx) => {
+    // ctx.authType tells you which mode matched
+    if (ctx.authType === 'user') {
+      // Called by an authenticated user
+      const { data } = await ctx.supabase.from('reports').select()
+      return Response.json(data)
+    }
+
+    // Called by another service with a secret key
+    const { user_id } = await req.json()
+    const { data } = await ctx.supabaseAdmin
+      .from('reports')
+      .select()
+      .eq('user_id', user_id)
+    return Response.json(data)
+  }),
+}
+```
+
+A request with a valid JWT matches `'user'`. A request with a valid secret key matches `'secret'`. A request with neither is rejected.
+
+## 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.
+
+Keys are stored as a JSON object in `SUPABASE_PUBLISHABLE_KEYS` or `SUPABASE_SECRET_KEYS`:
+
+```json
+{
+  "default": "sb_publishable_123...",
+  "web": "sb_publishable_abc...",
+  "mobile": "sb_publishable_a1b2..."
+}
+```
+
+### Target a specific key
+
+```ts
+// Only accept the "web" publishable key
+withSupabase({ allow: 'public:web' }, handler)
+
+// Only accept the "internal" secret key
+withSupabase({ allow: 'secret:internal' }, handler)
+```
+
+### Wildcard — accept any key in the set
+
+```ts
+// Accept any publishable key
+withSupabase({ allow: 'public:*' }, handler)
+
+// Accept any secret key
+withSupabase({ allow: 'secret:*' }, handler)
+```
+
+### Which key matched?
+
+When using named keys, `ctx.authType` tells you the mode and `keyName` on the `AuthResult` (from core primitives) tells you which key matched. In the high-level `withSupabase` wrapper, the matched key is used internally for client creation.
+
+### Combining named keys with other modes
+
+```ts
+withSupabase({ allow: ['user', 'public:web'] }, async (_req, ctx) => {
+  // Accepts either a valid JWT or the "web" publishable key
+  return Response.json({ authType: ctx.authType })
+})
+```
+
+## How auth flows through the system
+
+1. `extractCredentials(request)` reads `Authorization: Bearer <token>` and `apikey` from headers
+2. Each mode in `allow` is tried in order against the extracted credentials
+3. First match wins — returns an `AuthResult` with `authType`, `token`, `userClaims`, `claims`, and `keyName`
+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