@supabase/server 0.1.1 → 0.1.2

package/docs/getting-started.md

@@ -0,0 +1,149 @@
+# Getting Started
+
+## Installation
+
+```bash
+# Deno (import directly)
+import { withSupabase } from 'npm:@supabase/server'
+
+# npm
+npm install @supabase/server
+
+# pnpm
+pnpm add @supabase/server
+
+```
+
+`@supabase/server` requires `@supabase/supabase-js` as a peer dependency:
+
+```bash
+# npm
+npm install @supabase/supabase-js
+
+# pnpm
+pnpm add @supabase/supabase-js
+```
+
+## Your first authenticated endpoint
+
+The fastest way to get a working authenticated endpoint:
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: 'user' }, async (_req, ctx) => {
+    const { data } = await ctx.supabase.from('todos').select()
+    return Response.json(data)
+  }),
+}
+```
+
+> The `export default { fetch }` pattern is the standard module worker interface supported by Deno (including Supabase Edge Functions), Bun, and Cloudflare Workers. For Node.js, use the [Hono adapter](hono-adapter.md) or [core primitives](core-primitives.md) with your framework of choice.
+
+This single wrapper does four things for every request:
+
+1. **CORS** — handles `OPTIONS` preflight and adds CORS headers to all responses
+2. **Auth** — extracts and verifies credentials from request headers
+3. **Clients** — creates two Supabase clients: one scoped to the caller, one admin
+4. **Errors** — returns a JSON error response (`{ message, code }`) if auth fails
+
+Your handler only runs when auth succeeds.
+
+## A public endpoint (no auth)
+
+```ts
+import { withSupabase } from '@supabase/server'
+
+export default {
+  fetch: withSupabase({ allow: 'always' }, async (_req, _ctx) => {
+    return Response.json({ status: 'ok', time: new Date().toISOString() })
+  }),
+}
+```
+
+> **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request. If your function uses `allow: 'public'`, `allow: 'secret'`, or `allow: 'always'`, disable the platform-level JWT check in `supabase/config.toml`:
+>
+> ```toml
+> [functions.my-function]
+> verify_jwt = false
+> ```
+
+## What's in the context
+
+Every handler receives a `SupabaseContext` with these fields:
+
+| Field           | Type                 | Description                                                                                            |
+| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `supabase`      | `SupabaseClient`     | Client scoped to the caller. RLS policies apply.                                                       |
+| `supabaseAdmin` | `SupabaseClient`     | Admin client. Bypasses RLS.                                                                            |
+| `userClaims`    | `UserClaims \| null` | JWT-derived identity (`id`, `email`, `role`, `appMetadata`, `userMetadata`). `null` for non-user auth. |
+| `claims`        | `JWTClaims \| null`  | Raw JWT payload (snake_case). `null` for non-user auth.                                                |
+| `authType`      | `Allow`              | Which auth mode matched: `'user'`, `'public'`, `'secret'`, or `'always'`.                              |
+| `authKeyName`   | `string \| null`     | Which auth key name of the API key that was used.                                                      |
+
+The `supabase` client respects Row-Level Security. When `authType` is `'user'`, the client is scoped to that user's permissions. For other auth modes, it's initialized as anonymous.
+
+The `supabaseAdmin` client always bypasses RLS. Use it for operations that need full database access regardless of who's calling.
+
+`userClaims` gives you a lightweight view of the user's identity from the JWT. For the full Supabase `User` object (email confirmation, providers, etc.), call `ctx.supabase.auth.getUser()`.
+
+## Using createSupabaseContext directly
+
+When you need the context without the full wrapper — inside a framework route handler, custom middleware, or any situation where you want to control the response yourself:
+
+```ts
+import { createSupabaseContext } from '@supabase/server'
+
+export default {
+  fetch: async (req: Request) => {
+    const { data: ctx, error } = await createSupabaseContext(req, {
+      allow: 'user',
+    })
+
+    if (error) {
+      return Response.json(
+        { message: error.message, code: error.code },
+        { status: error.status },
+      )
+    }
+
+    const { data } = await ctx!.supabase.from('todos').select()
+    return Response.json(data)
+  },
+}
+```
+
+`createSupabaseContext` returns a result tuple `{ data, error }` instead of producing a Response. This gives you full control over error formatting and response headers.
+
+## CORS configuration
+
+CORS is enabled by default with standard supabase-js headers. You can customize or disable it:
+
+```ts
+// Custom CORS headers
+withSupabase(
+  {
+    allow: 'user',
+    cors: {
+      'Access-Control-Allow-Origin': 'https://myapp.com',
+      'Access-Control-Allow-Headers': 'authorization, content-type',
+    },
+  },
+  handler,
+)
+
+// Disable CORS (e.g., when a framework handles it)
+withSupabase({ allow: 'user', cors: false }, handler)
+```
+
+## Runtimes
+
+`withSupabase` and `createSupabaseContext` work with any runtime that supports the Web API `Request`/`Response` standard. The [core primitives](core-primitives.md) go further — they work in any environment where you can extract headers, regardless of the request/response model (Express, Fastify, etc.).
+
+- **Supabase Edge Functions** — environment variables are automatically injected by the platform. Zero config needed.
+- **Deno / Bun** — works out of the box with the module worker pattern.
+- **Node.js** — set variables via `.env` files or your hosting platform. Use the [Hono adapter](hono-adapter.md) or [core primitives](core-primitives.md) to integrate with any framework.
+- **Cloudflare Workers** — enable `nodejs_compat` or pass env overrides via the `env` config option.
+
+For full details on environment setup per runtime, see [environment-variables.md](environment-variables.md).

package/docs/hono-adapter.md

@@ -0,0 +1,185 @@
+# Hono Adapter
+
+## Setup
+
+Install Hono as a peer dependency:
+
+```bash
+pnpm add hono
+```
+
+The adapter exports its own `withSupabase` that returns Hono middleware instead of a fetch handler.
+
+## Basic app with auth
+
+```ts
+import { Hono } from 'hono'
+import { withSupabase } from '@supabase/server/adapters/hono'
+
+const app = new Hono()
+
+// Apply auth to all routes
+app.use('*', withSupabase({ allow: 'user' }))
+
+app.get('/todos', async (c) => {
+  const { supabase } = c.var.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return c.json(data)
+})
+
+app.get('/profile', async (c) => {
+  const { supabase, userClaims } = c.var.supabaseContext
+  const { data } = await supabase
+    .from('profiles')
+    .select()
+    .eq('id', userClaims!.id)
+  return c.json(data)
+})
+
+export default { fetch: app.fetch }
+```
+
+The context is stored in `c.var.supabaseContext` and contains the same `SupabaseContext` fields as the main `withSupabase` wrapper: `supabase`, `supabaseAdmin`, `userClaims`, `claims`, and `authType`.
+
+## Per-route auth
+
+Apply different auth modes to different routes by using the middleware inline:
+
+```ts
+import { Hono } from 'hono'
+import { withSupabase } from '@supabase/server/adapters/hono'
+
+const app = new Hono()
+
+// Public route — no auth
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+// User-authenticated route
+app.get('/todos', withSupabase({ allow: 'user' }), async (c) => {
+  const { supabase } = c.var.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return c.json(data)
+})
+
+// Secret-key-protected admin route
+app.post('/admin/sync', withSupabase({ allow: 'secret' }), async (c) => {
+  const { supabaseAdmin } = c.var.supabaseContext
+  const { data } = await supabaseAdmin
+    .from('audit_log')
+    .insert({ action: 'sync' })
+  return c.json(data)
+})
+
+// Dual auth — users or services
+app.get('/reports', withSupabase({ allow: ['user', 'secret'] }), async (c) => {
+  const { supabase, authType } = c.var.supabaseContext
+  return c.json({ authType })
+})
+
+export default { fetch: app.fetch }
+```
+
+## Skip behavior
+
+If a previous middleware already set `c.var.supabaseContext`, subsequent `withSupabase` calls skip auth. This enables a pattern where route-level middleware overrides the app-wide default:
+
+```ts
+const app = new Hono()
+
+// App-wide: require user auth
+app.use('*', withSupabase({ allow: '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({ allow: 'secret' }), async (c) => {
+  const { supabaseAdmin } = c.var.supabaseContext
+  // ...
+})
+```
+
+## CORS
+
+The Hono adapter does not handle CORS — the `cors` option is excluded from its config type. Use Hono's built-in CORS middleware:
+
+```ts
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { withSupabase } from '@supabase/server/adapters/hono'
+
+const app = new Hono()
+
+app.use('*', cors())
+app.use('*', withSupabase({ allow: 'user' }))
+
+app.get('/todos', async (c) => {
+  const { supabase } = c.var.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return c.json(data)
+})
+
+export default { fetch: app.fetch }
+```
+
+## Error handling
+
+When auth fails, the adapter throws a Hono `HTTPException`. The original `AuthError` is available via `cause`:
+
+```ts
+import { Hono } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { withSupabase } from '@supabase/server/adapters/hono'
+import { AuthError } from '@supabase/server'
+
+const app = new Hono()
+
+app.use('*', withSupabase({ allow: 'user' }))
+
+// Custom error handler
+app.onError((err, c) => {
+  if (err instanceof HTTPException && err.cause instanceof AuthError) {
+    const authError = err.cause
+    return c.json(
+      { error: authError.message, code: authError.code },
+      authError.status as 401 | 500,
+    )
+  }
+  return c.json({ error: 'Internal server error' }, 500)
+})
+
+app.get('/todos', async (c) => {
+  const { supabase } = c.var.supabaseContext
+  const { data } = await supabase.from('todos').select()
+  return c.json(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({
+    allow: 'user',
+    env: { url: 'http://localhost:54321' },
+  }),
+)
+```
+
+## Supabase client options
+
+Forward options to the underlying `createClient()` calls:
+
+```ts
+app.use(
+  '*',
+  withSupabase({
+    allow: 'user',
+    supabaseOptions: { db: { schema: 'api' } },
+  }),
+)
+```

package/docs/security.md

@@ -0,0 +1,82 @@
+# Security
+
+This document explains the security decisions behind `@supabase/server`. It's informational — you don't need to read this to use the package, but it helps if you want to understand why things work the way they do.
+
+## Timing-safe credential comparison
+
+API keys are compared using constant-time comparison to prevent [timing attacks](https://en.wikipedia.org/wiki/Timing_attack).
+
+A naive string comparison (`===`) short-circuits on the first mismatched character. An attacker can measure response times to guess the key one character at a time. With enough requests, this leaks the full key.
+
+The package uses a **double-HMAC technique**: both strings are HMAC'd with a random ephemeral key, then the resulting digests are compared byte-by-byte with a constant-time XOR loop. This ensures that comparison time is independent of where (or whether) the strings differ.
+
+This applies to:
+
+- **Publishable key verification** (`allow: 'public'`) — compares the `apikey` header against stored publishable keys
+- **Secret key verification** (`allow: 'secret'`) — compares the `apikey` header against stored secret keys
+
+See `src/core/utils/timing-safe-equal.ts` for the implementation.
+
+## Auth mode security model
+
+Each auth mode provides a different level of trust:
+
+| Mode     | What it verifies                    | Who the caller is        | `supabase` client  | `supabaseAdmin` client |
+| -------- | ----------------------------------- | ------------------------ | ------------------ | ---------------------- |
+| `user`   | JWT signature against JWKS          | An authenticated user    | Row-Level Security | Full access            |
+| `public` | Publishable API key (timing-safe)   | A known client app       | Row-Level Security | Full access            |
+| `secret` | Secret API key (timing-safe)        | A trusted server/service | Full access        | Full access            |
+| `always` | Nothing — all requests are accepted | Unknown                  | Row-Level Security | Full access            |
+
+Key implications:
+
+- **`user` mode** verifies the JWT using a local JWKS (JSON Web Key Set). The token must contain a `sub` claim. Verification uses the `jose` library's `jwtVerify` with a local key set — no network calls to an auth server.
+- **`public` and `secret` modes** compare the `apikey` header against known keys. The comparison is timing-safe. If you use named keys (`allow: 'secret:automations'`), only that specific key is accepted — this follows the principle of least privilege.
+- **`always` mode** performs zero authentication. The handler runs for every request. The `supabaseAdmin` client is still available, so a compromised `always` endpoint with write operations is a security risk. Only use it for truly public endpoints or when you implement your own auth (e.g., webhook signature verification).
+
+## Named key isolation
+
+Instead of accepting any valid API key, you can restrict an endpoint to a specific named key:
+
+```ts
+// Accepts any secret key
+withSupabase({ allow: 'secret' }, handler)
+
+// Only accepts the "automations" secret key
+withSupabase({ allow: 'secret:automations' }, handler)
+```
+
+This limits the blast radius if a key is compromised. An attacker with the `web` publishable key cannot access an endpoint that requires `secret:automations`. Named keys also make it easier to rotate or revoke access for a specific consumer without affecting others.
+
+## JWT verification
+
+JWT verification in `user` mode works as follows:
+
+1. The `Authorization: Bearer <token>` header is extracted from the request
+2. The token is verified against the JWKS from the `SUPABASE_JWKS` environment variable
+3. Verification uses `jose`'s `jwtVerify` with a **local** key set — there are no network calls to a JWKS endpoint
+4. The token must contain a `sub` (subject) claim to be considered valid
+5. On success, the decoded claims are available as `ctx.user` and `ctx.claims`
+
+If JWKS is not configured (`SUPABASE_JWKS` is missing or malformed), `user` mode is unavailable and will always reject requests.
+
+## CORS handling
+
+`withSupabase` handles CORS automatically:
+
+- **Preflight requests** (`OPTIONS`) return `204` with CORS headers and skip the handler entirely — no auth check runs
+- **All other requests** get CORS headers appended to the response
+- **Error responses** (auth failures) also include CORS headers, so the browser can read the error
+
+CORS defaults come from `@supabase/supabase-js/cors`. You can pass custom headers or disable CORS entirely with `cors: false`.
+
+The Hono adapter does **not** handle CORS — use Hono's built-in `cors` middleware instead.
+
+## Credential extraction
+
+Credentials are extracted from two standard headers:
+
+- `Authorization: Bearer <token>` → used by `user` mode
+- `apikey: <value>` → used by `public` and `secret` modes
+
+Extraction is a separate step from verification (`extractCredentials` vs `verifyCredentials`). This separation means you can inspect raw credentials in custom flows without triggering validation.