@supabase/server 1.1.0-rc.66 → 1.2.0-rc.69

package/README.md

@@ -266,11 +266,12 @@ Adapters wrap `withSupabase` for a specific framework's middleware contract. The
 
 > **Adapters are a community-driven initiative.** They're developed, maintained, and evolved by contributors — including responding to upstream framework changes. See [`src/adapters/README.md`](src/adapters/README.md) for the contribution requirements (tests, types, docs, build wiring) if you'd like to add or help maintain one.
 
-| Framework | Import                             | Framework version | Docs                                               |
-| --------- | ---------------------------------- | ----------------- | -------------------------------------------------- |
-| Hono      | `@supabase/server/adapters/hono`   | `^4.0.0`          | [docs/adapters/hono.md](docs/adapters/hono.md)     |
-| H3 / Nuxt | `@supabase/server/adapters/h3`     | `^2.0.0`          | [docs/adapters/h3.md](docs/adapters/h3.md)         |
-| Elysia    | `@supabase/server/adapters/elysia` | `^1.4.0`          | [docs/adapters/elysia.md](docs/adapters/elysia.md) |
+| Framework | Import                             | Framework version      | Docs                                               |
+| --------- | ---------------------------------- | ---------------------- | -------------------------------------------------- |
+| Hono      | `@supabase/server/adapters/hono`   | `^4.0.0`               | [docs/adapters/hono.md](docs/adapters/hono.md)     |
+| H3 / Nuxt | `@supabase/server/adapters/h3`     | `^2.0.0`               | [docs/adapters/h3.md](docs/adapters/h3.md)         |
+| Elysia    | `@supabase/server/adapters/elysia` | `^1.4.0`               | [docs/adapters/elysia.md](docs/adapters/elysia.md) |
+| NestJS    | `@supabase/server/adapters/nestjs` | `^10.0.0 \|\| ^11.0.0` | [docs/adapters/nestjs.md](docs/adapters/nestjs.md) |
 
 See the per-adapter docs above for setup, per-route auth, CORS, error handling, and other patterns.
 
@@ -316,6 +317,25 @@ app.listen(3000)
 
 The adapter does not handle CORS — use `@elysiajs/cors` for that.
 
+### NestJS
+
+```ts
+import { Controller, Get, UseGuards } from '@nestjs/common'
+import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+import type { SupabaseContext } from '@supabase/server'
+
+@Controller('games')
+@UseGuards(withSupabase({ auth: 'user' }))
+export class GamesController {
+  @Get()
+  list(@SupabaseCtx() ctx: SupabaseContext) {
+    return ctx.supabase.from('favorite_games').select()
+  }
+}
+```
+
+See [docs/adapters/nestjs.md](docs/adapters/nestjs.md) for per-route auth, exception filters, CORS, and more.
+
 ## Primitives
 
 For when you need more control than `withSupabase` provides — multiple routes with different auth, custom response headers, or building your own wrapper.
@@ -465,6 +485,7 @@ No. `@supabase/ssr` handles cookie-based session management for frameworks like
 | `@supabase/server/adapters/hono`   | `withSupabase` (Hono middleware)                                                                                  |
 | `@supabase/server/adapters/h3`     | `withSupabase` (H3 / Nuxt middleware)                                                                             |
 | `@supabase/server/adapters/elysia` | `withSupabase` (Elysia plugin)                                                                                    |
+| `@supabase/server/adapters/nestjs` | `withSupabase` (NestJS guard), `SupabaseCtx` (param decorator)                                                    |
 
 ## Documentation
 
@@ -476,6 +497,7 @@ No. `@supabase/ssr` handles cookie-based session management for frameworks like
 | How do I use this with Hono?                                        | [`docs/adapters/hono.md`](docs/adapters/hono.md)                 |
 | How do I use this with H3 / Nuxt?                                   | [`docs/adapters/h3.md`](docs/adapters/h3.md)                     |
 | How do I use this with Elysia?                                      | [`docs/adapters/elysia.md`](docs/adapters/elysia.md)             |
+| How do I use this with NestJS?                                      | [`docs/adapters/nestjs.md`](docs/adapters/nestjs.md)             |
 | How do I use low-level primitives for custom flows?                 | [`docs/core-primitives.md`](docs/core-primitives.md)             |
 | How do environment variables work across runtimes?                  | [`docs/environment-variables.md`](docs/environment-variables.md) |
 | How do I handle errors? What codes exist?                           | [`docs/error-handling.md`](docs/error-handling.md)               |

package/dist/adapters/nestjs/index.cjs

@@ -0,0 +1,118 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_create_supabase_context = require('../../create-supabase-context-CKv-4AIg.cjs');
+let _nestjs_common = require("@nestjs/common");
+
+//#region src/adapters/nestjs/middleware.ts
+function toWebRequest(req) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(req.headers ?? {})) {
+		if (name.startsWith(":")) continue;
+		if (Array.isArray(value)) headers.set(name, value.join(", "));
+		else if (value != null) headers.set(name, String(value));
+	}
+	return new Request(`http://nestjs.local${req.url ?? "/"}`, { headers });
+}
+/**
+* NestJS guard that creates a {@link SupabaseContext} and stores it on the
+* underlying request as `request.supabaseContext`.
+*
+* **HTTP-only.** The guard reads HTTP headers via `switchToHttp()` and throws
+* if applied to an RPC or WebSocket handler — those transports must
+* authenticate via context-specific mechanisms.
+*
+* Always runs, even if a previous guard already set the context. This matches
+* Nest's guard order (global → controller → handler), so handler-level guards
+* can tighten what a global guard set rather than being skipped.
+*
+* Throws `HttpException` on auth failure — the original `AuthError` is
+* available via `cause`.
+*
+* @param config - Auth modes and optional environment overrides. CORS is excluded —
+*   use NestJS's built-in CORS (`app.enableCors()`).
+* @returns A guard class that can be passed to `@UseGuards(...)`.
+*
+* @example App-wide auth via `app.useGlobalGuards()`
+* ```ts
+* import { NestFactory } from '@nestjs/core'
+* import { withSupabase } from '@supabase/server/adapters/nestjs'
+*
+* const app = await NestFactory.create(AppModule)
+* app.useGlobalGuards(new (withSupabase({ auth: 'user' }))())
+* await app.listen(3000)
+* ```
+*
+* @example Per-route auth via `@UseGuards(...)`
+* ```ts
+* import { Controller, Get, UseGuards } from '@nestjs/common'
+* import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+* import type { SupabaseContext } from '@supabase/server'
+*
+* @Controller('games')
+* export class GamesController {
+*   @Get()
+*   @UseGuards(withSupabase({ auth: 'user' }))
+*   async list(@SupabaseCtx() ctx: SupabaseContext) {
+*     const { data } = await ctx.supabase.from('favorite_games').select()
+*     return data
+*   }
+* }
+* ```
+*/
+function withSupabase(config) {
+	@((0, _nestjs_common.Injectable)()) class SupabaseAuthGuard {
+		async canActivate(executionContext) {
+			const contextType = executionContext.getType();
+			if (contextType !== "http") throw new _nestjs_common.HttpException({
+				message: `withSupabase guard only supports HTTP contexts (got '${contextType}'). Authenticate non-HTTP transports separately.`,
+				code: "unsupported_context"
+			}, 500);
+			const req = executionContext.switchToHttp().getRequest();
+			const { data: ctx, error } = await require_create_supabase_context.createSupabaseContext(toWebRequest(req), config);
+			if (error) throw new _nestjs_common.HttpException({
+				message: error.message,
+				code: error.code
+			}, error.status, { cause: error });
+			req.supabaseContext = ctx;
+			return true;
+		}
+	}
+	return SupabaseAuthGuard;
+}
+
+//#endregion
+//#region src/adapters/nestjs/decorator.ts
+/**
+* NestJS param decorator that returns the {@link SupabaseContext} attached
+* by `withSupabase()`. Pass a key (e.g. `'supabase'`, `'userClaims'`) to pull
+* a single field, or no argument to receive the whole context.
+*
+* @example
+* ```ts
+* import { Controller, Get, UseGuards } from '@nestjs/common'
+* import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+* import type { SupabaseContext } from '@supabase/server'
+*
+* @Controller('games')
+* @UseGuards(withSupabase({ auth: 'user' }))
+* export class GamesController {
+*   @Get()
+*   list(@SupabaseCtx() ctx: SupabaseContext) {
+*     return ctx.supabase.from('favorite_games').select()
+*   }
+*
+*   @Get('me')
+*   me(@SupabaseCtx('userClaims') user: SupabaseContext['userClaims']) {
+*     return user
+*   }
+* }
+* ```
+*/
+const SupabaseCtx = (0, _nestjs_common.createParamDecorator)((data, ctx) => {
+	const supabaseContext = ctx.switchToHttp().getRequest().supabaseContext;
+	if (data) return supabaseContext?.[data];
+	return supabaseContext;
+});
+
+//#endregion
+exports.SupabaseCtx = SupabaseCtx;
+exports.withSupabase = withSupabase;

package/dist/adapters/nestjs/index.d.cts

@@ -0,0 +1,82 @@
+import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-CwKZOVIv.cjs";
+import { CanActivate, PipeTransform, Type } from "@nestjs/common";
+
+//#region src/adapters/nestjs/middleware.d.ts
+/**
+ * NestJS guard that creates a {@link SupabaseContext} and stores it on the
+ * underlying request as `request.supabaseContext`.
+ *
+ * **HTTP-only.** The guard reads HTTP headers via `switchToHttp()` and throws
+ * if applied to an RPC or WebSocket handler — those transports must
+ * authenticate via context-specific mechanisms.
+ *
+ * Always runs, even if a previous guard already set the context. This matches
+ * Nest's guard order (global → controller → handler), so handler-level guards
+ * can tighten what a global guard set rather than being skipped.
+ *
+ * Throws `HttpException` on auth failure — the original `AuthError` is
+ * available via `cause`.
+ *
+ * @param config - Auth modes and optional environment overrides. CORS is excluded —
+ *   use NestJS's built-in CORS (`app.enableCors()`).
+ * @returns A guard class that can be passed to `@UseGuards(...)`.
+ *
+ * @example App-wide auth via `app.useGlobalGuards()`
+ * ```ts
+ * import { NestFactory } from '@nestjs/core'
+ * import { withSupabase } from '@supabase/server/adapters/nestjs'
+ *
+ * const app = await NestFactory.create(AppModule)
+ * app.useGlobalGuards(new (withSupabase({ auth: 'user' }))())
+ * await app.listen(3000)
+ * ```
+ *
+ * @example Per-route auth via `@UseGuards(...)`
+ * ```ts
+ * import { Controller, Get, UseGuards } from '@nestjs/common'
+ * import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+ * import type { SupabaseContext } from '@supabase/server'
+ *
+ * @Controller('games')
+ * export class GamesController {
+ *   @Get()
+ *   @UseGuards(withSupabase({ auth: 'user' }))
+ *   async list(@SupabaseCtx() ctx: SupabaseContext) {
+ *     const { data } = await ctx.supabase.from('favorite_games').select()
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): Type<CanActivate>;
+//#endregion
+//#region src/adapters/nestjs/decorator.d.ts
+/**
+ * NestJS param decorator that returns the {@link SupabaseContext} attached
+ * by `withSupabase()`. Pass a key (e.g. `'supabase'`, `'userClaims'`) to pull
+ * a single field, or no argument to receive the whole context.
+ *
+ * @example
+ * ```ts
+ * import { Controller, Get, UseGuards } from '@nestjs/common'
+ * import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+ * import type { SupabaseContext } from '@supabase/server'
+ *
+ * @Controller('games')
+ * @UseGuards(withSupabase({ auth: 'user' }))
+ * export class GamesController {
+ *   @Get()
+ *   list(@SupabaseCtx() ctx: SupabaseContext) {
+ *     return ctx.supabase.from('favorite_games').select()
+ *   }
+ *
+ *   @Get('me')
+ *   me(@SupabaseCtx('userClaims') user: SupabaseContext['userClaims']) {
+ *     return user
+ *   }
+ * }
+ * ```
+ */
+declare const SupabaseCtx: (data?: keyof SupabaseContext, ...pipes: (Type<PipeTransform> | PipeTransform)[]) => ParameterDecorator;
+//#endregion
+export { SupabaseCtx, withSupabase };

package/dist/adapters/nestjs/index.d.mts

@@ -0,0 +1,82 @@
+import { d as SupabaseContext, m as WithSupabaseConfig } from "../../types-DbvLfq25.mjs";
+import { CanActivate, PipeTransform, Type } from "@nestjs/common";
+
+//#region src/adapters/nestjs/middleware.d.ts
+/**
+ * NestJS guard that creates a {@link SupabaseContext} and stores it on the
+ * underlying request as `request.supabaseContext`.
+ *
+ * **HTTP-only.** The guard reads HTTP headers via `switchToHttp()` and throws
+ * if applied to an RPC or WebSocket handler — those transports must
+ * authenticate via context-specific mechanisms.
+ *
+ * Always runs, even if a previous guard already set the context. This matches
+ * Nest's guard order (global → controller → handler), so handler-level guards
+ * can tighten what a global guard set rather than being skipped.
+ *
+ * Throws `HttpException` on auth failure — the original `AuthError` is
+ * available via `cause`.
+ *
+ * @param config - Auth modes and optional environment overrides. CORS is excluded —
+ *   use NestJS's built-in CORS (`app.enableCors()`).
+ * @returns A guard class that can be passed to `@UseGuards(...)`.
+ *
+ * @example App-wide auth via `app.useGlobalGuards()`
+ * ```ts
+ * import { NestFactory } from '@nestjs/core'
+ * import { withSupabase } from '@supabase/server/adapters/nestjs'
+ *
+ * const app = await NestFactory.create(AppModule)
+ * app.useGlobalGuards(new (withSupabase({ auth: 'user' }))())
+ * await app.listen(3000)
+ * ```
+ *
+ * @example Per-route auth via `@UseGuards(...)`
+ * ```ts
+ * import { Controller, Get, UseGuards } from '@nestjs/common'
+ * import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+ * import type { SupabaseContext } from '@supabase/server'
+ *
+ * @Controller('games')
+ * export class GamesController {
+ *   @Get()
+ *   @UseGuards(withSupabase({ auth: 'user' }))
+ *   async list(@SupabaseCtx() ctx: SupabaseContext) {
+ *     const { data } = await ctx.supabase.from('favorite_games').select()
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+declare function withSupabase(config?: Omit<WithSupabaseConfig, 'cors'>): Type<CanActivate>;
+//#endregion
+//#region src/adapters/nestjs/decorator.d.ts
+/**
+ * NestJS param decorator that returns the {@link SupabaseContext} attached
+ * by `withSupabase()`. Pass a key (e.g. `'supabase'`, `'userClaims'`) to pull
+ * a single field, or no argument to receive the whole context.
+ *
+ * @example
+ * ```ts
+ * import { Controller, Get, UseGuards } from '@nestjs/common'
+ * import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+ * import type { SupabaseContext } from '@supabase/server'
+ *
+ * @Controller('games')
+ * @UseGuards(withSupabase({ auth: 'user' }))
+ * export class GamesController {
+ *   @Get()
+ *   list(@SupabaseCtx() ctx: SupabaseContext) {
+ *     return ctx.supabase.from('favorite_games').select()
+ *   }
+ *
+ *   @Get('me')
+ *   me(@SupabaseCtx('userClaims') user: SupabaseContext['userClaims']) {
+ *     return user
+ *   }
+ * }
+ * ```
+ */
+declare const SupabaseCtx: (data?: keyof SupabaseContext, ...pipes: (Type<PipeTransform> | PipeTransform)[]) => ParameterDecorator;
+//#endregion
+export { SupabaseCtx, withSupabase };

package/dist/adapters/nestjs/index.mjs

@@ -0,0 +1,116 @@
+import { t as createSupabaseContext } from "../../create-supabase-context-BxSEJN8a.mjs";
+import { HttpException, Injectable, createParamDecorator } from "@nestjs/common";
+
+//#region src/adapters/nestjs/middleware.ts
+function toWebRequest(req) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(req.headers ?? {})) {
+		if (name.startsWith(":")) continue;
+		if (Array.isArray(value)) headers.set(name, value.join(", "));
+		else if (value != null) headers.set(name, String(value));
+	}
+	return new Request(`http://nestjs.local${req.url ?? "/"}`, { headers });
+}
+/**
+* NestJS guard that creates a {@link SupabaseContext} and stores it on the
+* underlying request as `request.supabaseContext`.
+*
+* **HTTP-only.** The guard reads HTTP headers via `switchToHttp()` and throws
+* if applied to an RPC or WebSocket handler — those transports must
+* authenticate via context-specific mechanisms.
+*
+* Always runs, even if a previous guard already set the context. This matches
+* Nest's guard order (global → controller → handler), so handler-level guards
+* can tighten what a global guard set rather than being skipped.
+*
+* Throws `HttpException` on auth failure — the original `AuthError` is
+* available via `cause`.
+*
+* @param config - Auth modes and optional environment overrides. CORS is excluded —
+*   use NestJS's built-in CORS (`app.enableCors()`).
+* @returns A guard class that can be passed to `@UseGuards(...)`.
+*
+* @example App-wide auth via `app.useGlobalGuards()`
+* ```ts
+* import { NestFactory } from '@nestjs/core'
+* import { withSupabase } from '@supabase/server/adapters/nestjs'
+*
+* const app = await NestFactory.create(AppModule)
+* app.useGlobalGuards(new (withSupabase({ auth: 'user' }))())
+* await app.listen(3000)
+* ```
+*
+* @example Per-route auth via `@UseGuards(...)`
+* ```ts
+* import { Controller, Get, UseGuards } from '@nestjs/common'
+* import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+* import type { SupabaseContext } from '@supabase/server'
+*
+* @Controller('games')
+* export class GamesController {
+*   @Get()
+*   @UseGuards(withSupabase({ auth: 'user' }))
+*   async list(@SupabaseCtx() ctx: SupabaseContext) {
+*     const { data } = await ctx.supabase.from('favorite_games').select()
+*     return data
+*   }
+* }
+* ```
+*/
+function withSupabase(config) {
+	@Injectable() class SupabaseAuthGuard {
+		async canActivate(executionContext) {
+			const contextType = executionContext.getType();
+			if (contextType !== "http") throw new HttpException({
+				message: `withSupabase guard only supports HTTP contexts (got '${contextType}'). Authenticate non-HTTP transports separately.`,
+				code: "unsupported_context"
+			}, 500);
+			const req = executionContext.switchToHttp().getRequest();
+			const { data: ctx, error } = await createSupabaseContext(toWebRequest(req), config);
+			if (error) throw new HttpException({
+				message: error.message,
+				code: error.code
+			}, error.status, { cause: error });
+			req.supabaseContext = ctx;
+			return true;
+		}
+	}
+	return SupabaseAuthGuard;
+}
+
+//#endregion
+//#region src/adapters/nestjs/decorator.ts
+/**
+* NestJS param decorator that returns the {@link SupabaseContext} attached
+* by `withSupabase()`. Pass a key (e.g. `'supabase'`, `'userClaims'`) to pull
+* a single field, or no argument to receive the whole context.
+*
+* @example
+* ```ts
+* import { Controller, Get, UseGuards } from '@nestjs/common'
+* import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+* import type { SupabaseContext } from '@supabase/server'
+*
+* @Controller('games')
+* @UseGuards(withSupabase({ auth: 'user' }))
+* export class GamesController {
+*   @Get()
+*   list(@SupabaseCtx() ctx: SupabaseContext) {
+*     return ctx.supabase.from('favorite_games').select()
+*   }
+*
+*   @Get('me')
+*   me(@SupabaseCtx('userClaims') user: SupabaseContext['userClaims']) {
+*     return user
+*   }
+* }
+* ```
+*/
+const SupabaseCtx = createParamDecorator((data, ctx) => {
+	const supabaseContext = ctx.switchToHttp().getRequest().supabaseContext;
+	if (data) return supabaseContext?.[data];
+	return supabaseContext;
+});
+
+//#endregion
+export { SupabaseCtx, withSupabase };

package/docs/adapters/nestjs.md

@@ -0,0 +1,204 @@
+# NestJS Adapter
+
+## Setup
+
+Install NestJS as a peer dependency:
+
+```bash
+pnpm add @nestjs/common @nestjs/core
+```
+
+The adapter exports `withSupabase` (a guard factory) and `SupabaseCtx` (a param decorator). Together they replace the `c.var.supabaseContext` / `event.context.supabaseContext` patterns from the Hono and H3 adapters.
+
+`withSupabase(config)` returns a `CanActivate` guard class. The guard reads the underlying request (Express or Fastify), verifies credentials with `@supabase/server/core`, and attaches the resulting `SupabaseContext` to `request.supabaseContext`. From any handler you can pull it out with `@SupabaseCtx()`.
+
+## Basic controller with auth
+
+```ts
+// games.controller.ts
+import { Controller, Get, UseGuards } from '@nestjs/common'
+import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+import type { SupabaseContext } from '@supabase/server'
+
+@Controller('games')
+@UseGuards(withSupabase({ auth: 'user' }))
+export class GamesController {
+  @Get()
+  async list(@SupabaseCtx() ctx: SupabaseContext) {
+    const { data } = await ctx.supabase.from('favorite_games').select()
+    return data
+  }
+
+  @Get('me')
+  me(@SupabaseCtx('userClaims') user: SupabaseContext['userClaims']) {
+    return user
+  }
+}
+```
+
+`@SupabaseCtx()` returns the entire `SupabaseContext` (`supabase`, `supabaseAdmin`, `userClaims`, `jwtClaims`, `authMode`, `authKeyName`). Pass a key (`@SupabaseCtx('supabase')`) to extract a single field.
+
+### Typing your database
+
+The guard does not thread a `Database` generic, so `@SupabaseCtx()` resolves to `SupabaseContext<unknown>` by default. To get typed table access, annotate the parameter at the handler:
+
+```ts
+import type { SupabaseContext } from '@supabase/server'
+import type { Database } from './database.types'
+
+@Get()
+async list(@SupabaseCtx() ctx: SupabaseContext<Database>) {
+  const { data } = await ctx.supabase.from('favorite_games').select()
+  return data
+}
+```
+
+## Per-route auth
+
+Apply different auth modes per controller or per handler — the closest `@UseGuards()` wins:
+
+```ts
+import { Controller, Get, Post, UseGuards } from '@nestjs/common'
+import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
+import type { SupabaseContext } from '@supabase/server'
+
+@Controller()
+export class AppController {
+  // Public — no guard
+  @Get('health')
+  health() {
+    return { status: 'ok' }
+  }
+
+  // User-authenticated route
+  @Get('todos')
+  @UseGuards(withSupabase({ auth: 'user' }))
+  async todos(@SupabaseCtx() ctx: SupabaseContext) {
+    const { data } = await ctx.supabase.from('todos').select()
+    return data
+  }
+
+  // Secret-key-protected admin route
+  @Post('admin/sync')
+  @UseGuards(withSupabase({ auth: 'secret' }))
+  async sync(@SupabaseCtx() ctx: SupabaseContext) {
+    const { data } = await ctx.supabaseAdmin
+      .from('audit_log')
+      .insert({ action: 'sync' })
+    return data
+  }
+
+  // Dual auth — users or services
+  @Get('reports')
+  @UseGuards(withSupabase({ auth: ['user', 'secret'] }))
+  reports(@SupabaseCtx('authMode') authMode: SupabaseContext['authMode']) {
+    return { authMode }
+  }
+}
+```
+
+## App-wide guard
+
+Apply the guard globally with `app.useGlobalGuards()`:
+
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core'
+import { withSupabase } from '@supabase/server/adapters/nestjs'
+import { AppModule } from './app.module'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  app.useGlobalGuards(new (withSupabase({ auth: 'user' }))())
+  await app.listen(3000)
+}
+bootstrap()
+```
+
+## Multiple guards
+
+`withSupabase` always runs, even if a previous guard already set `request.supabaseContext`. NestJS executes guards in order (global → controller → handler), so a handler-level guard naturally tightens what a global guard set: the later guard re-authenticates with its own config and either rejects the request or overwrites the context. The innermost guard wins.
+
+If you need different auth per route, prefer per-route `@UseGuards(...)` without a global guard.
+
+## CORS
+
+The NestJS adapter does not handle CORS. Use NestJS's built-in CORS:
+
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  app.enableCors({ origin: 'https://myapp.com' })
+  await app.listen(3000)
+}
+bootstrap()
+```
+
+The `cors` option is excluded from `WithSupabaseConfig` for this adapter.
+
+## Error handling
+
+When auth fails, the adapter throws a NestJS `HttpException`. The original `AuthError` is available via `cause`. Add an exception filter to format the response:
+
+```ts
+// supabase-auth.filter.ts
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+} from '@nestjs/common'
+import { AuthError } from '@supabase/server'
+import type { Response } from 'express'
+
+@Catch(HttpException)
+export class SupabaseAuthFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const cause = exception.cause
+    if (!(cause instanceof AuthError)) throw exception
+
+    const res = host.switchToHttp().getResponse<Response>()
+    res.status(cause.status).json({
+      error: cause.message,
+      code: cause.code,
+    })
+  }
+}
+```
+
+Register it globally:
+
+```ts
+// main.ts
+app.useGlobalFilters(new SupabaseAuthFilter())
+```
+
+## Environment overrides
+
+Pass `env` to override auto-detected environment variables:
+
+```ts
+@UseGuards(
+  withSupabase({
+    auth: 'user',
+    env: { url: 'http://localhost:54321' },
+  }),
+)
+```
+
+## Supabase client options
+
+Forward options to the underlying `createClient()` calls:
+
+```ts
+@UseGuards(
+  withSupabase({
+    auth: 'user',
+    supabaseOptions: { db: { schema: 'api' } },
+  }),
+)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/server",
-  "version": "1.1.0-rc.66",
+  "version": "1.2.0-rc.69",
   "description": "Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.",
   "keywords": [
     "edge",
@@ -44,6 +44,11 @@
       "import": "./dist/adapters/elysia/index.mjs",
       "require": "./dist/adapters/elysia/index.cjs"
     },
+    "./adapters/nestjs": {
+      "types": "./dist/adapters/nestjs/index.d.mts",
+      "import": "./dist/adapters/nestjs/index.mjs",
+      "require": "./dist/adapters/nestjs/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
@@ -68,19 +73,23 @@
     "prepare": "simple-git-hooks",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p src/adapters/nestjs"
   },
   "simple-git-hooks": {
     "pre-commit": "pnpm pretty-quick --staged",
     "commit-msg": "pnpm commitlint --edit \"$1\""
   },
   "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@supabase/supabase-js": "^2.0.0",
     "h3": "^2.0.0",
     "hono": "^4.0.0",
     "elysia": "^1.4.0"
   },
   "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
     "h3": {
       "optional": true
     },
@@ -94,18 +103,29 @@
   "devDependencies": {
     "@commitlint/cli": "^20.4.2",
     "@commitlint/config-conventional": "^20.4.2",
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "@nestjs/platform-express": "^11.1.19",
+    "@nestjs/platform-fastify": "^11.1.19",
+    "@nestjs/testing": "^11.1.19",
     "@supabase/supabase-js": "^2.105.4",
+    "@swc/core": "^1.15.33",
+    "@types/supertest": "^7.2.0",
     "eslint": "^10.0.2",
     "elysia": "^1.4.0",
     "h3": "2.0.1-rc.20",
     "hono": "^4.12.5",
     "prettier": "3.8.1",
     "pretty-quick": "^4.2.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
     "simple-git-hooks": "^2.13.1",
+    "supertest": "^7.2.2",
     "tsdown": "^0.20.3",
     "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
+    "unplugin-swc": "^1.5.9",
     "vitest": "^4.0.18"
   },
   "dependencies": {