feat(middleware): add postgres and claims middleware entrypoints

Graduate withPostgres and withClaims out of plugin-examples into
@supabase/server/middleware/*, so the PRFAQ's built-in middleware ship
from the package instead of example-local code (SDK-1163 item 5).

- withPostgres reads claims from ctx.jwtClaims (already populated by
  withSupabase), so `middleware: [withPostgres()]` works with no separate
  withClaims. Keeps the RLS role-clamp and tx-local request.jwt.claims
  injection. pg is an optional peer dep (Node/Deno only, not Workers).
- withClaims ships for the standalone agnostic pipeline() case
  (demo-only: no signature verification).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mandarini

jsr.json

@@ -8,7 +8,9 @@
     "./adapters/hono": "./src/adapters/hono/index.ts",
     "./adapters/h3": "./src/adapters/h3/index.ts",
     "./adapters/elysia": "./src/adapters/elysia/index.ts",
-    "./adapters/nestjs": "./src/adapters/nestjs/index.ts"
+    "./adapters/nestjs": "./src/adapters/nestjs/index.ts",
+    "./middleware/postgres": "./src/middleware/postgres/index.ts",
+    "./middleware/claims": "./src/middleware/claims/index.ts"
   },
   "publish": {
     "include": ["src/**/*.ts", "README.md", "LICENSE"],

package.json

@@ -89,6 +89,26 @@
         "default": "./dist/adapters/nestjs/index.cjs"
       }
     },
+    "./middleware/postgres": {
+      "import": {
+        "types": "./dist/middleware/postgres/index.d.mts",
+        "default": "./dist/middleware/postgres/index.mjs"
+      },
+      "require": {
+        "types": "./dist/middleware/postgres/index.d.cts",
+        "default": "./dist/middleware/postgres/index.cjs"
+      }
+    },
+    "./middleware/claims": {
+      "import": {
+        "types": "./dist/middleware/claims/index.d.mts",
+        "default": "./dist/middleware/claims/index.mjs"
+      },
+      "require": {
+        "types": "./dist/middleware/claims/index.d.cts",
+        "default": "./dist/middleware/claims/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
@@ -128,7 +148,8 @@
     "@supabase/supabase-js": "^2.0.0",
     "elysia": "^1.4.0",
     "h3": "^2.0.0",
-    "hono": "^4.0.0"
+    "hono": "^4.0.0",
+    "pg": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@nestjs/common": {
@@ -142,6 +163,9 @@
     },
     "elysia": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -156,6 +180,7 @@
     "@supabase/supabase-js": "^2.105.4",
     "@swc/core": "^1.15.33",
     "@types/node": "^26.0.1",
+    "@types/pg": "^8.11.0",
     "@types/supertest": "^7.2.0",
     "elysia": "^1.4.0",
     "eslint": "^10.0.2",

pnpm-lock.yaml

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+
+import { withClaims } from './index.js'
+
+function base64url(obj: unknown): string {
+  return Buffer.from(JSON.stringify(obj))
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+function tokenFor(claims: Record<string, unknown>): string {
+  return `header.${base64url(claims)}.sig`
+}
+
+const runtime = { name: 'node' as const, getEnv: () => undefined }
+
+describe('withClaims', () => {
+  it('decodes the Bearer token payload into ctx.jwtClaims', async () => {
+    let seen: unknown
+    const handler = withClaims(async (_req, ctx) => {
+      seen = ctx.jwtClaims
+      return Response.json({ ok: true })
+    })
+
+    await handler(
+      new Request('http://localhost', {
+        headers: {
+          Authorization: `Bearer ${tokenFor({ sub: 'u1', role: 'authenticated' })}`,
+        },
+      }),
+      { _runtime: runtime },
+    )
+
+    expect(seen).toEqual({ sub: 'u1', role: 'authenticated' })
+  })
+
+  it('contributes null when no Authorization header is present', async () => {
+    let seen: unknown = 'unset'
+    const handler = withClaims(async (_req, ctx) => {
+      seen = ctx.jwtClaims
+      return Response.json({ ok: true })
+    })
+
+    await handler(new Request('http://localhost'), { _runtime: runtime })
+
+    expect(seen).toBeNull()
+  })
+
+  it('contributes null for a malformed token', async () => {
+    let seen: unknown = 'unset'
+    const handler = withClaims(async (_req, ctx) => {
+      seen = ctx.jwtClaims
+      return Response.json({ ok: true })
+    })
+
+    await handler(
+      new Request('http://localhost', {
+        headers: { Authorization: 'Bearer not-a-jwt' },
+      }),
+      { _runtime: runtime },
+    )
+
+    expect(seen).toBeNull()
+  })
+})

src/middleware/claims/index.test.ts

@@ -0,0 +1,57 @@
+import { defineMiddleware } from '@supabase/web-middleware'
+
+/**
+ * Loosely-typed JWT claims contributed by {@link withClaims}.
+ *
+ * @category Middleware
+ */
+export interface JwtClaims {
+  sub?: string
+  role?: string
+  [k: string]: unknown
+}
+
+/** base64url-decode a JWT payload segment (no signature verification). */
+function decodeJwtPayload(token: string): JwtClaims | null {
+  const part = token.split('.')[1]
+  if (!part) return null
+  const b64 = part
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+    .padEnd(Math.ceil(part.length / 4) * 4, '=')
+  try {
+    return JSON.parse(atob(b64)) as JwtClaims
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Contributes `ctx.jwtClaims` by decoding the caller's Bearer token.
+ *
+ * Use this only when composing a standalone `pipeline([...], handler)` that is
+ * **not** wrapped by `withSupabase` — for example a Supabase-agnostic Edge
+ * Function that still wants the caller's claims available to a downstream
+ * middleware such as {@link withPostgres}. Inside `withSupabase`, the context
+ * already carries `jwtClaims` (JWKS-verified), so `withClaims` is unnecessary.
+ *
+ * > **DEMO ONLY — does NOT verify the signature.** It base64url-decodes the
+ * > payload so the Postgres example is self-contained. `withSupabase` verifies
+ * > the JWT against the project JWKS before trusting the claims; never trust an
+ * > unverified token in production.
+ *
+ * @category Middleware
+ */
+export const withClaims = defineMiddleware<
+  'jwtClaims',
+  void,
+  Record<never, never>,
+  JwtClaims | null
+>({
+  key: 'jwtClaims',
+  run: () => async (req) => {
+    const auth = req.headers.get('Authorization')
+    const token = auth?.replace(/^Bearer\s+/i, '')
+    return { jwtClaims: token ? decodeJwtPayload(token) : null }
+  },
+})