feat: withSupabase on the @supabase/middleware engine

[mandarini]

Summary

withSupabase now runs on the @supabase/middleware engine, and the pieces it is built from ship as public middleware. Adds a middleware option so @supabase/middleware entries can compose around the handler after the Supabase context is established — plus four first-party middleware: withSupabaseClient, withSupabaseAdminClient, withClaims, and withPostgres.

Naming: the array holds middleware (per-request behavior), so that's its name.

import { withSupabase } from '@supabase/server'
import { withPostgres } from '@supabase/server/middleware/postgres'

export default {
  fetch: withSupabase(
    { auth: 'user', middleware: [withPostgres()] },
    async (req, ctx) => {
      ctx.supabase      // from @supabase/server — already present when the middleware runs
      ctx.postgres      // from withPostgres — RLS-scoped SQL as the caller
      const posts = await ctx.postgres.query('select id, title from posts limit 10')
      return Response.json({ posts })
    },
  ),
}

The middleware receive ctx.supabase, ctx.jwtClaims, etc. already populated — they run after the Supabase context is created, not before.

Architecture

End user
  → withSupabase({ middleware: [withPostgres(), withRateLimit(cfg)] }, handler)
  → never sees pipeline()

withSupabase internals (this PR)
  → runs on the engine for EVERY request: folds
    [withSupabaseClient, withSupabaseAdminClient, ...config.middleware]
    around the handler — the same public middleware anyone can compose
  → verifyAuth stays outside the chain (ordered multi-mode resolution +
    historical error shapes), its verified identity is seeded via seedContext()
  → forwards the host's 2nd fetch arg (Workers env) so bindings reach getEnv

Middleware author (e.g. withPostgres)
  → defineMiddleware({ key, run })
  → env access via the importable getEnv() — no reserved ctx keys
  → never calls pipeline()

Why verifyAuth isn't itself a chain entry: an engine middleware contributes exactly one ctx key; verifyAuth's single pass produces four (userClaims, jwtClaims, authMode, authKeyName) via ordered multi-mode resolution. Instead, withClaims shares the same verification core (verifyUserJwt) as verifyAuth's user mode — same code, two surfaces.

What changed

• src/with-supabase.ts — rewritten on the engine: the two client middleware compose around the user's middleware array and handler on every request. Public API, ctx keys, and error shapes are unchanged (the pre-existing test suite passes unmodified as the parity proof). Two named overloads (no-middleware / with-middleware) so TypeScript infers the handler's ctx concretely; MiddlewareCtx<Entries> accumulates the entries' key contributions. Client-construction failures keep their historical JSON responses — phase-guarded so user middleware / handler throws propagate exactly as before
• src/middleware/client (@supabase/server/middleware/client) — withSupabaseClient<Database>(): contributes ctx.supabase (RLS-scoped). Under withSupabase it mirrors verified credentials (token only for user mode, matched publishable key by name); standalone it attaches the raw bearer — PostgREST verifies on every query
• src/middleware/admin-client (@supabase/server/middleware/admin-client) — withSupabaseAdminClient<Database>(): contributes ctx.supabaseAdmin, secret key selected from the upstream authKeyName when the request authenticated as secret
• src/middleware/claims (@supabase/server/middleware/claims) — withClaims: now JWKS-verified only (shared verifyUserJwt core: JWKS resolver caching, HS256 shared-secret path, sb_* passthrough). No token → contributes null; invalid token → 401; missing JWKS → 500. The demo-grade decoder is gone
• src/middleware/postgres (@supabase/server/middleware/postgres) — withPostgres: contributes ctx.postgres, an RLS-scoped pg client. Every query runs in its own transaction that injects the caller's claims (request.jwt.claims) and drops to their role, PostgREST-style; the role is clamped to authenticated/anon. Table-grants hint on 42501
• src/core/verify-user-jwt.ts — the extracted shared verification core used by both verifyCredentials and withClaims
• package.json — @supabase/middleware@^0.3.0 from npm (preview build retired) + four middleware subpath exports (also in jsr.json / tsdown)
• Tests — middleware composition/order/short-circuit/CORS, platform-env forwarding, JWKS verification (RS256 + HS256 + foreign-key rejection), client key selection from upstream auth, client-construction error mapping vs handler-throw propagation, claim injection/role clamp/rollback/42501 for withPostgres

Compatibility

• No breaking changes for released consumers: every existing export is unchanged; the six SupabaseContext keys keep exact semantics; error JSON shapes are identical. New subpaths are additive; release is a minor
• The returned fetch handler gained an optional second parameter (the host platform arg) — assignable in both directions
• Type-level floor is TS ≥ 5.4 (the engine's .d.ts uses NoInfer); consumers with skipLibCheck are unaffected
• @supabase/middleware@0.3.0 is published on both npm and JSR; the JSR dry-run packaging check passes in CI

Try it

npm i https://pkg.pr.new/@supabase/server@88

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@88

commit: bf90330

[mandarini]

You can also test this out on 1.5.0-beta.0