* fix: apply Injectable programmatically so NestJS adapter loads in raw Node
The @Injectable() decorator on the guard in withSupabase() shipped
untranspiled (tsdown/oxc does not lower legacy decorators), crashing
`require`/`import` of the adapter with SyntaxError under plain Node.
Apply it as Injectable()(SupabaseAuthGuard) instead, and add a raw-Node
load smoke test (pnpm smoke) in CI to catch this class of regression.
Fixes#87
* fix: fail smoke test when no entrypoints are found in exports
adds generic Database type override to hono adapter
added test to ensure chained declarations preserve context type
updated docs to include alternative hono declaration
* docs: clarify bare auth mode matches only the default key
Bare `auth: 'publishable'` / `auth: 'secret'` match only the `default`
key in SUPABASE_PUBLISHABLE_KEYS / SUPABASE_SECRET_KEYS. This was
documented inconsistently — two spots wrongly claimed bare `secret`
accepts any key, and most tables/TSDoc omitted the detail entirely.
- Fix incorrect "accepts any secret key" statements in security.md and
the supabase-server skill (bare = default; `secret:*` = any)
- Name the `default` key directly in every auth-mode table (README,
auth-modes.md, security.md, src/index.ts TSDoc)
- Add the default-key sentence to the Secret mode section to match
Publishable, and clarify AuthMode / AuthModeWithKey TSDoc in types.ts
* docs: document default-key resolution for wildcard and client factories
Follow-up to the auth-mode default-key pass, closing two remaining gaps:
- Publishable mode section now mentions the `publishable:*` wildcard, so it
mirrors the Secret mode sentence exactly.
- Document which key createAdminClient / createContextClient use: the named
key when `auth.keyName` is set, otherwise `default` with a fallback to the
first key in the set. This was untouched by docs anywhere despite being
tested behavior, and it deliberately differs from the `secret` /
`publishable` auth modes, which match `default` only and never fall back.
* feat: explicit cors config shape ('default' | 'none' | { headers })
Keeps boolean/Record forms accepted but deprecated.
* refactor: rename cors 'none' to 'disabled'
Reads more clearly as an on/off switch and matches the SDK-1149 proposal.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: add @category tags to public API and add nestjs to TypeDoc entry points
* docs: add @category tags, fix TypeDoc cross-module links, export options types
* docs: some small missing things
* docs: add @module for jsr score
The allow→auth / 'always'→'none' / 'public'→'publishable' /
authType→authMode rename was already applied across the prose docs,
but a few JSDoc reference comments (which feed the typedoc API
reference) still used the old names:
- AuthResult doc: "public" → "publishable"
- keyName doc: "always" → "none"
- Elysia plugin @example blocks: allow: 'user' → auth: 'user'
* chore(types): export common set of types for supabase server
* fix: moving peer dep type re-export to its own module path
* docs: docummenting peer deps types
* fix: creating export entry
* fix: not renaming 'AuthError'
* docs(types): improving 'supabase-js' peer description
* fix: regression, exporting 'AuthError'
---------
Co-authored-by: Kalleby Santos <kalleby_santos@hotmail.com>
* feat: add NestJS adapter
Ships `@supabase/server/adapters/nestjs`:
- `withSupabase(opts)` — class guard for `@UseGuards()` and
`useGlobalGuards()`, supporting Express and Fastify
- `@SupabaseCtx(key?, ...pipes)` — param decorator returning the full
SupabaseContext or a single field, with NestJS pipes applied to the
extracted value
- 401s thrown as `HttpException` with `{ message, code }`; the
underlying `AuthError` is exposed on `cause`
Adds `@nestjs/common` as an optional peer dep (`^10 || ^11`), wires the
new export in package.json / jsr.json / tsdown.config.ts, and enables
`experimentalDecorators` + `emitDecoratorMetadata` in tsconfig. Test
setup uses unplugin-swc via vitest.config.ts so integration tests can
boot a real Nest app on both Express and Fastify.
Docs: README quickstart + docs/adapters/nestjs.md.
* refactor(nestjs): address PR review feedback
- Scope `experimentalDecorators` + `emitDecoratorMetadata` to
`src/adapters/nestjs/tsconfig.json` (extends root) and exclude the
adapter from the root project so the options aren't enforced
repo-wide. `typecheck` now runs both projects.
- Convert `vitest.config.ts` to the `projects` syntax so the
`unplugin-swc` transform applies only to the nestjs project; the unit
project runs unchanged with esbuild.
- Throw `HttpException` (500, `unsupported_context`) instead of
returning true on non-HTTP execution contexts so misuse fails loudly
on the first request rather than silently no-op'ing on every
RPC/WebSocket message.
- Remove the "skip if context already set" branch so handler-level
guards can tighten what a global guard set. Previously the outer
(global) guard always won under Nest's global → controller → handler
order, so a stricter handler-level guard could be silently bypassed.
Tests updated; `@SupabaseCtx` decorator unchanged.
- Drop unused `CanActivate` import from integration.test.ts.
* docs(nestjs): update guard behavior section to match new semantics
The guard no longer skips when a prior context exists — it always
re-evaluates. Rewrite the doc section to match the JSDoc wording and
the inner-rejects/inner-overwrites tests.
* feat(env): add support for JWKS discovery endpoints
* feat(env): fix vars to be seperate
* fix(env): updated to non-exposed
* test(env): cover malformed JWKS URL and resolver cache replacement
* feat(env): allow http SUPABASE_JWKS_URL for loopback hosts
---------
Co-authored-by: Tomas Pozo <tomaspozogarzon@gmail.com>
* feat: rename `allow` config option to `auth`
Aligns the SDK with Supabase CLI terminology — `auth: 'user'` reads
more naturally than `allow: 'user'`. The legacy `allow` key still
works (with a one-time `console.warn` per process) and will be
removed in a future major release; when both `auth` and `allow` are
provided, `auth` wins. Also exports new `AuthMode` / `AuthModeWithKey`
types alongside deprecated `Allow` / `AllowWithKey` aliases.
* feat!: rename auth mode values `'always'` → `'none'` and `'public'` → `'publishable'`
Aligns auth-mode values with Supabase CLI terminology. `'none'` reads more
directly than `'always'` for "no authentication required", and
`'publishable'` matches the `SUPABASE_PUBLISHABLE_KEY(S)` env var names.
`'secret'` and `'user'` are unchanged.
BREAKING CHANGE: the `'always'` and `'public'` mode values no longer work.
Replace `auth: 'always'` with `auth: 'none'`, `auth: 'public'` with
`auth: 'publishable'`, and `auth: 'public:<name>'` with
`auth: 'publishable:<name>'`. Runtime checks like
`ctx.authType === 'public'` must be updated to
`ctx.authType === 'publishable'`.
* feat!: rename `authType` field to `authMode` on `AuthResult` and `SupabaseContext`
Lines the field name up with its type — `authMode: AuthMode`. Reads more
naturally for both humans and AI agents working with the API.
BREAKING CHANGE: the `authType` field was renamed to `authMode` on
`AuthResult` (returned by `verifyAuth` / `verifyCredentials`) and on
`SupabaseContext` (passed to handlers). Find-and-replace
`ctx.authType` → `ctx.authMode` and `auth.authType` → `auth.authMode`
across your codebase.
* feat!: rename `claims` field to `jwtClaims` on `AuthResult` and `SupabaseContext`
Pairs naturally with `userClaims` and makes the snake_case JWT payload
distinct from the normalized identity view at a glance.
* refactor!: narrow `SupabaseContext.authKeyName` to `string | undefined`
The field used to be `string | null | undefined` (optional + explicitly
nullable), forcing consumers to handle two absence values. Collapse to a
single representation by dropping `null`: the property is simply omitted
for `'user'` and `'none'` modes, which don't match a named key.
`AuthResult.keyName` keeps its `string | null` shape — it's the
low-level type where the field is always present and `null` actively
signals "no named key for this mode."
* docs: add publishable-key example to README quick start
The auth-modes table documented the publishable mode but the quick start
only showed user, none, secret, dual, and server-to-server examples,
leaving readers without a concrete shape for publishable. Slot it
between the "no auth" and "secret" examples so the progression reads
no key → publishable (anon, key-gated) → secret (admin, key-gated).
The example clarifies the resulting client behavior — `supabase` is
anonymous, RLS still applies, and the publishable key is a client gate
rather than a user identity — which is the most common point of
confusion vs. `auth: 'secret'`.
* docs: update skill description
* docs: update ssr references accross docs and skill
* docs(adapters): add ecosystem index + community contribution guide
Adds src/adapters/README.md (index, maintenance model, contribution
checklist) and docs/adapters/h3.md. Moves docs/hono-adapter.md into
docs/adapters/. Slims the top-level README Framework Adapters section
to a canonical adapter table + brief examples. Updates CONTRIBUTING.md,
docs/getting-started.md, and the supabase-server skill to reference the
new paths.
* docs: sweep adapter and SSR docs to use renamed API
The cherry-picked docs commits were authored before the API renames in
this branch, so the new content arrived using `allow:`, `'always'`,
`'public'`, `claims`, `authType`, and `AllowWithKey`. Update the
newly-arrived files in line with the renamed API:
- docs/adapters/h3.md — `allow:` → `auth:`, `claims, authType` →
`jwtClaims, authMode` throughout
- docs/ssr-frameworks.md — composed Next.js adapter example now uses
`auth:` / `AuthModeWithKey` / `jwtClaims` / `authMode`
- src/adapters/README.md — adapter-test checklist mentions the four
current modes (`'user'`, `'publishable'`, `'secret'`, `'none'`)
- CONTRIBUTING.md — same wording fix in the adapter-PR section
- skills/supabase-server/SKILL.md — top-level skill description points
at `auth:` and the new mode values; legacy patterns folded into the
existing migration trigger
- src/adapters/hono/middleware.ts — inline comment example uses `auth:`
in both halves rather than mixing legacy and current option names
- README.md — collapsed Hono and H3 quick-start snippets use `auth:`
Migration prose (`README.md` callout, `docs/auth-modes.md` callout,
`docs/api-reference.md` deprecated-aliases section, `SKILL.md`
migration callouts) intentionally still references the old names; they
document the migration itself.
* docs: reframe Beta disclaimer for v1 launch + extract MIGRATION.md
The Beta callout ("APIs and documentation may change") directly
contradicts the SemVer commitment that v1 makes. For launch material
that pins to v1, the contradiction undermines the stability message
the version number is meant to carry.
Replace it with a v1.0 callout that leads with stability under SemVer
and follows with honest "active development continues" framing — new
adapters and ergonomic improvements in minor releases, breaking
changes only ever in a major bump.
Move the v0 → v1 rename map out of the README and into a dedicated
MIGRATION.md. The README quick start was buried under 20+ lines of
migration tables that only matter to upgraders, not first-time
readers — exactly the wrong tradeoff at launch. New short callout
points upgraders at MIGRATION.md.
SKILL.md gets the same Beta → v1.0 swap. The agent-operational
migration rules (lines 12-14: "always emit `auth:` in new code", "the
new mode values are `'none'` / `'publishable'`") are kept inline —
they're rules the agent applies every time it writes code, not
user-facing migration steps, so they don't belong in MIGRATION.md.
* docs: reframe v1.0 callout as "Public Beta" to match Supabase house style
The previous "Stable under SemVer; active development continues" framing
mixed two distinct axes — code stability (SemVer) and product
lifecycle stage (Public Beta / GA) — into the SemVer line. Several
Supabase docs run those independently: a release can be v1+ in SemVer
terms and still labeled Public Beta in lifecycle terms.
Lead with both signals in the headline: "v1.0 — Public Beta." Keep the
SemVer commitment ("breaking changes only ship as a major bump") so
launch copy can pin to v1, and pair it with the Public Beta lifecycle
stage so readers know the product line is still early. Same swap in
the SKILL.md mirror.
* fix: reject invalid JWTs immediately instead of falling through to next auth mode
Introduce an INVALID sentinel so tryMode can distinguish "credential
present but failed" from "credential absent." The main loop now short-
circuits on INVALID instead of silently trying the next allowed mode.
Also covers the case where a JWT verifies cryptographically but has no
sub claim (or sub isn't a string) -- previously returned null (fallthrough),
now returns INVALID (reject).
BREAKING CHANGE: when multiple auth modes are allowed, a present-but-invalid
JWT is now rejected with InvalidCredentialsError instead of falling through
to the next mode. Clients that previously relied on silent fallthrough
(e.g., stale token + valid apikey) must now either omit the Authorization
header or refresh the token.
* docs: clarify invalid-JWT no-fallthrough semantics
Align documentation with the behavior introduced in the fix!: commit on
this branch. Make clear across user-facing docs, TSDoc, and SKILL that:
- A mode is "tried" only when its credential is actually present, so a
request with no Authorization header still falls through.
- A JWT that is present but fails verification (malformed, expired, wrong
signature, missing sub) rejects with InvalidCredentialsError — it does
not silently fall through to another allowed mode.
Touches README, docs/auth-modes, docs/security, docs/error-handling,
docs/api-reference, skills/supabase-server/SKILL, and TSDoc on the Allow
type, WithSupabaseConfig.allow, and verifyCredentials.
---------
Co-authored-by: Tomas Pozo <tomaspozogarzon@gmail.com>
* fix: correctly passing down the keyName based on authType
- Only passing keyName for during 'createContextClient' if the authType
is public
* feat: exposing 'keyName' to SupabaseContext
* docs: adding 'authKeyName' reference
Webhook signature verification varies too much across providers
to justify a generic helper. Each case should be handled with
the provider's own SDK (e.g., Stripe, GitHub).
* docs: add initial documentation and skills.md
* docs: apply formatting
* docs: update SKILL.md to resolve docs from package location and ship docs with npm
SKILL.md now instructs agents to find documentation in the installed
@supabase/server package (node_modules or repo root) instead of using
relative paths. Added docs/ and SKILL.md to package.json files array
so they ship with npm installs.
* docs: add missing HTTPException import in error-handling example
* docs: fix strictNullChecks issues, duplicate variables, and missing context in examples
- Add non-null assertions (!) after error guards where TS can't narrow
destructured result tuples
- Split duplicate variable declarations into separate code blocks
- Add missing imports and show where variables like `auth` come from
- Keep { data, error } destructuring pattern consistent with SDK convention
* docs: reframe as runtime-agnostic and add env auto-injection details
- getting-started: replace Edge Function framing with runtime-neutral
language, explain module worker pattern works across Deno/Bun/Workers,
add Runtimes section covering all supported environments
- webhooks: replace Deno.env with process.env for portable examples
- environment-variables: add "Auto-injected in" column distinguishing
Platform vs Local CLI, reframe section headers
- auth-modes: clean up example key values
- core-primitives: clarify "Integration with frameworks" wording
- types: simplify TSDoc for publishable/secret key descriptions
* docs: add SSR frameworks guide and update references
Add docs/ssr-frameworks.md covering the pattern for using core
primitives in Next.js, SvelteKit, Nuxt, and Remix — cookie extraction,
env bridging, JWKS caching, and a complete Next.js adapter example.
Replace the basic SSR example in core-primitives.md with a pointer
to the new dedicated doc. Add SSR row to SKILL.md routing table.
* docs: add disclaimer of new package
* docs: extend explanation on keys env vars
* docs: add platform-specific quick starts to SKILL.md
Split the single generic example into per-platform sections
(Edge Functions, Cloudflare Workers, Hono, SSR Frameworks) so
AI agents pick the correct import specifier for each runtime.
Adds npm: prefix to all Deno examples and a Deno column to the
entry points table. Also adds createSupabaseContext examples.
* docs: add server-to-server quick starts and allow:always guardrails
Add secret key auth and webhook signature verification quick starts
to SKILL.md. Add explicit decision tree for allow:'always' so AI
agents confirm with the user before leaving endpoints unprotected.
* docs: add legacy keys warning, skills install, remove webhook docs
- Add legacy keys warning to SKILL.md (avoid anon/service_role keys)
- Add AI coding skills install section to README
- Add server-to-server quick start with caller code to README
- Add runtimes, documentation table, and named secret keys to README
- Remove verifyWebhookSignature references from all docs
- Delete docs/webhooks.md (code removal in separate PR)
* docs: add verify_jwt = false note for non-user auth modes
Edge Functions require verify_jwt = false in config.toml when
using allow: public, secret, or always — otherwise the platform
rejects requests before the handler runs.
* docs: add edge function recipes and refactor env vars doc
Add recipes for function-to-function calls, pg_net from database,
Stripe webhooks, and generic webhook signature verification.
Document the @supabase/server/wrappers entry point.
Refactor environment-variables.md into Supabase vs non-Supabase sections.
* docs: add security doc covering timing-safe comparison, auth model, CORS
* docs: link auth-modes timing-safe mentions to security.md
* docs: adding 'local cli' to secrets table
This envs will be injected from cli too
* docs: setting Deno as first installation choice
* docs: adding 'verify_jwt=false' disclaimer for non-user auth
* docs: split Deno/Supabase runtime section, merge Deno/Node/Bun
* docs(skills): adding legacy code migration example
* docs(skills): explaining why legacy code should be migrated
* docs: rewrite migration section, improve skill description triggers
---------
Co-authored-by: Kalleby Santos <kalleby_santos@hotmail.com>
* feat: add `supabaseOptions` to `WithSupabaseConfig` for client customization
Allow users to pass `SupabaseClientOptions` through to the internal
`createClient` calls, enabling custom schemas, fetch, and realtime config
while security-critical auth settings remain force-overwritten.
* fix: sanitize Authorization and apikey headers from supabaseOptions
User-provided supabaseOptions.global.headers could include Authorization
or apikey, bypassing verified credentials. Strip both before spreading
user headers into the client options.
* docs: add comprehensive TSDoc comments with embedded examples across all source files
Add JSDoc/TSDoc documentation to every exported function, type, interface,
and error class. Includes @param, @returns, @throws, @example with
copy-pasteable code, @see cross-references, and @packageDocumentation
module overviews. Examples use the runtime-agnostic `export default { fetch }`
pattern instead of Deno-specific APIs.
* docs: align annotations with @supabase/server naming and runtime-agnostic framing
- Replace all @supabase/edge-functions imports with @supabase/server across 13 source files
- Frame withSupabase as built for the Web API Request/Response standard
- Explain adapter purpose: frameworks wrap the runtime's native standards, adapters bridge the gap
- Fix CONTRIBUTING.md repo URL from edge-functions to server
* docs: trim inline comments to practical scope — one summary, one example
Move architecture explanations, auth mode tables, multi-example variations,
and cryptographic theory out of inline TSDoc. Keep each doc comment focused
on what the function does and one copy-pasteable example.
* docs: fix @packageDocumentation tag placement and Cloudflare Workers caveat
- Move @packageDocumentation to its own line in barrel files (TSDoc spec requirement)
- Clarify that Cloudflare Workers need node-compat or overrides for env resolution
* fix: use matched key name for client creation instead of always defaulting
verifyCredentials now returns the matched keyName in AuthResult.
createContextClient and createAdminClient accept an optional keyName
parameter, falling back to 'default' when not provided.
* test: add keyName resolution tests and fix fallback to first available key
Client creation now falls back to first available key when no 'default'
exists and keyName is null. Tests cover named keys, wildcard matching
non-first keys, and the full fallback chain.
* docs: update README samples to export default format and clean up imports
* fix: use null check for keyName fallback and tailor error messages
Use keyName == null instead of truthiness check so empty strings
don't incorrectly trigger fallback. Error messages now only suggest
SUPABASE_*_KEY for the default key, not for named keys.
* fix: only pass keyName to admin client for secret auth, make keyName optional
Admin client now only receives keyName when authType is 'secret',
preventing mismatched key lookups when auth is public. AuthResult.keyName
is now optional to avoid breaking consumers who construct the type.
* fix: support bare array format for SUPABASE_JWKS env var
The platform provides JWKS as a JSON array [...] but parseJwks
expected { keys: [...] }. Now wraps bare arrays automatically.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add platform env var integration test for resolveEnv
Verifies parsing of real platform env var shapes: multiple
named keys and bare JWKS array with two EC key entries.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: validate parseJwks input before casting to JsonWebKeySet
Reject valid JSON that isn't a valid JWKS (e.g. primitives, empty
objects, objects with non-array `keys`) instead of blindly casting.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Katerina Skroumpelou