feat: add plugins option to withSupabase

Author: mandarini

package.json

@@ -134,6 +134,7 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
+    "@supabase/web-middleware": "link:../web-middleware",
     "jose": "^6.2.0"
   }
 }

pnpm-lock.yaml

@@ -7,6 +7,7 @@ minimumReleaseAgeExclude:
   - '@esbuild/*'
 blockExoticSubdeps: true
 allowBuilds:
+  '@supabase/web-middleware': true
   '@nestjs/core': false
   '@swc/core': false
   esbuild: false

pnpm-workspace.yaml

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineMiddleware } from '@supabase/web-middleware'
 
 import { _resetAllowDeprecationWarned } from './core/utils/deprecation.js'
 import { withSupabase } from './with-supabase.js'
@@ -98,6 +99,127 @@ describe('withSupabase', () => {
     expect(res.headers.get('Access-Control-Allow-Origin')).toBeNull()
   })
 
+  describe('plugins', () => {
+    it('composes plugins after the Supabase context is established', async () => {
+      const withFlag = defineMiddleware<
+        'flag',
+        void,
+        Record<never, never>,
+        boolean
+      >({
+        key: 'flag',
+        run: () => async () => ({ flag: true }),
+      })
+
+      const handler = withSupabase(
+        { auth: 'none', env: baseEnv, plugins: [withFlag()] },
+        async (_req, ctx) =>
+          Response.json({ authMode: ctx.authMode, flag: ctx.flag }),
+      )
+
+      const res = await handler(new Request('http://localhost'))
+      const body = await res.json()
+      expect(body.authMode).toBe('none')
+      expect(body.flag).toBe(true)
+    })
+
+    it('plugin receives the Supabase context at runtime', async () => {
+      let capturedHasSupabase = false
+
+      const withCapture = defineMiddleware<
+        'captured',
+        void,
+        Record<never, never>,
+        true
+      >({
+        key: 'captured',
+        run: () => async (_req, ctx) => {
+          capturedHasSupabase = !!(ctx as { supabase?: unknown }).supabase
+          return { captured: true as const }
+        },
+      })
+
+      const handler = withSupabase(
+        { auth: 'none', env: baseEnv, plugins: [withCapture()] },
+        async () => Response.json({ ok: true }),
+      )
+
+      await handler(new Request('http://localhost'))
+      expect(capturedHasSupabase).toBe(true)
+    })
+
+    it('plugin can short-circuit before the handler', async () => {
+      const withBlock = defineMiddleware<
+        'blocked',
+        void,
+        Record<never, never>,
+        true
+      >({
+        key: 'blocked',
+        run: () => async () => new Response('blocked', { status: 403 }),
+      })
+
+      const innerHandler = vi.fn(async () => Response.json({ ok: true }))
+
+      const handler = withSupabase(
+        { auth: 'none', env: baseEnv, plugins: [withBlock()] },
+        innerHandler,
+      )
+
+      const res = await handler(new Request('http://localhost'))
+      expect(res.status).toBe(403)
+      expect(innerHandler).not.toHaveBeenCalled()
+    })
+
+    it('plugins run in array order (first = outermost, runs first on request)', async () => {
+      const order: string[] = []
+
+      const withA = defineMiddleware<'a', void, Record<never, never>, true>({
+        key: 'a',
+        run: () => async () => {
+          order.push('a')
+          return { a: true as const }
+        },
+      })
+      const withB = defineMiddleware<'b', void, Record<never, never>, true>({
+        key: 'b',
+        run: () => async () => {
+          order.push('b')
+          return { b: true as const }
+        },
+      })
+
+      const handler = withSupabase(
+        { auth: 'none', env: baseEnv, plugins: [withA(), withB()] },
+        async (_req, ctx) => Response.json({ a: ctx.a, b: ctx.b }),
+      )
+
+      const res = await handler(new Request('http://localhost'))
+      expect(order).toEqual(['a', 'b'])
+      expect(await res.json()).toEqual({ a: true, b: true })
+    })
+
+    it('CORS headers still apply when plugins are present', async () => {
+      const withNoop = defineMiddleware<
+        'noop',
+        void,
+        Record<never, never>,
+        true
+      >({
+        key: 'noop',
+        run: () => async () => ({ noop: true as const }),
+      })
+
+      const handler = withSupabase(
+        { auth: 'none', env: baseEnv, plugins: [withNoop()] },
+        async () => Response.json({ ok: true }),
+      )
+
+      const res = await handler(new Request('http://localhost'))
+      expect(res.headers.get('Access-Control-Allow-Origin')).toBe('*')
+    })
+  })
+
   describe('allow → auth deprecation', () => {
     beforeEach(() => {
       _resetAllowDeprecationWarned()

src/with-supabase.test.ts

@@ -1,6 +1,26 @@
 import { buildCorsHeaders, addCorsHeaders } from './cors.js'
 import { createSupabaseContext } from './create-supabase-context.js'
 import type { SupabaseContext, WithSupabaseConfig } from './types.js'
+import type { Entry } from '@supabase/web-middleware'
+
+type AnyEntry = Entry<string, object, unknown>
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyHandler = (req: Request, ctx: any) => Promise<Response>
+
+/**
+ * Accumulate the ctx contributions of a plugin tuple — same logic as
+ * `pipeline`'s internal `Accumulate`, seeded from `object` (no `BaseContext`
+ * or `_runtime` in the visible ctx type; see implementation note below).
+ */
+type PluginsCtx<Plugins extends readonly AnyEntry[]> =
+  Plugins extends readonly [
+    Entry<infer Key extends string, object, infer Contribution>,
+    ...infer Rest,
+  ]
+    ? Rest extends readonly AnyEntry[]
+      ? { [P in Key]: Contribution } & PluginsCtx<Rest>
+      : { [P in Key]: Contribution }
+    : object
 
 /**
  * Wraps a request handler with Supabase auth, client creation, and CORS handling.
@@ -17,6 +37,7 @@ import type { SupabaseContext, WithSupabaseConfig } from './types.js'
  * ```ts
  * import { withSupabase } from '@supabase/server'
  *
+ * // Without plugins — existing API, unchanged.
  * export default {
  *   fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
  *     const { data } = await ctx.supabase.rpc('get_my_profile')
@@ -28,6 +49,55 @@ import type { SupabaseContext, WithSupabaseConfig } from './types.js'
 export function withSupabase<Database = unknown>(
   config: WithSupabaseConfig,
   handler: (req: Request, ctx: SupabaseContext<Database>) => Promise<Response>,
+): (req: Request) => Promise<Response>
+
+/**
+ * Variant that accepts a `plugins` array — each `withFoo(config)` call returns
+ * an `Entry` from `@supabase/web-middleware`. Plugins run **after** the Supabase
+ * context is established; they receive `ctx.supabase`, `ctx.userClaims`, etc.
+ * already present and contribute their own typed keys on top.
+ *
+ * @example
+ * ```ts
+ * import { withSupabase } from '@supabase/server'
+ * import { withGuestbook } from '@supabase/plugin-guestbook/server'
+ * import { withRateLimit } from '@supabase/plugin-rate-limit/server'
+ *
+ * export default {
+ *   fetch: withSupabase(
+ *     { auth: 'user', plugins: [withRateLimit({ rpm: 100 }), withGuestbook()] },
+ *     async (req, ctx) => {
+ *       ctx.supabase      // from @supabase/server
+ *       ctx.rateLimit     // from withRateLimit
+ *       ctx.guestbook     // from withGuestbook
+ *       return Response.json(await ctx.guestbook.list())
+ *     },
+ *   ),
+ * }
+ * ```
+ *
+ * **Type note.** `PluginsCtx<Plugins>` accumulates the key contributions of the
+ * plugins array. Plugins that declare `In` prerequisites on Supabase-provided
+ * keys (`supabase`, `userClaims`, …) satisfy those at runtime (the Supabase
+ * context is merged before plugins run) but not at the type level — a full
+ * implementation would widen the prerequisite-validation seed to include
+ * `SupabaseContext`. Ordering and collision checks within the plugins array work
+ * normally via `web-middleware`'s runtime chain.
+ */
+export function withSupabase<
+  Database = unknown,
+  const Plugins extends readonly AnyEntry[] = readonly AnyEntry[],
+>(
+  config: WithSupabaseConfig & { plugins: Plugins },
+  handler: (
+    req: Request,
+    ctx: SupabaseContext<Database> & PluginsCtx<Plugins>,
+  ) => Promise<Response>,
+): (req: Request) => Promise<Response>
+
+export function withSupabase<Database = unknown>(
+  config: WithSupabaseConfig & { plugins?: readonly AnyEntry[] },
+  handler: AnyHandler,
 ): (req: Request) => Promise<Response> {
   return async (req: Request) => {
     if (config.cors !== false && req.method === 'OPTIONS') {
@@ -51,7 +121,29 @@ export function withSupabase<Database = unknown>(
       )
     }
 
-    const response = await handler(req, ctx)
+    let response: Response
+    if (config.plugins?.length) {
+      // Compose plugins around the handler — same fold as pipeline's reduceRight,
+      // but without calling pipeline() so we supply the seeded ctx ourselves.
+      const composed = (
+        config.plugins as readonly AnyEntry[]
+      ).reduceRight<AnyHandler>((h, entry) => entry(h), handler)
+      // Seed _runtime so web-middleware entries recognise this as an upstream
+      // context (isContext() checks for _runtime.getEnv). Falls through to
+      // process.env; a full implementation would bridge to SupabaseEnv.
+      const g = globalThis as {
+        process?: { env?: Record<string, string | undefined> }
+      }
+      response = await composed(req, {
+        ...ctx,
+        _runtime: {
+          name: 'unknown' as const,
+          getEnv: (key: string): string | undefined => g.process?.env?.[key],
+        },
+      })
+    } else {
+      response = await handler(req, ctx as object)
+    }
 
     if (config.cors !== false) {
       return addCorsHeaders(response, config.cors)