supabase · mandarini · May 6, 2026 · May 5, 2026 · May 6, 2026 · May 6, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,48 +2,43 @@
 
 ## [0.2.0](https://github.com/supabase/server/compare/server-v0.1.4...server-v0.2.0) (2026-04-24)
 
-
 ### ⚠ BREAKING CHANGES
 
-* 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.
+- 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.
 
 ### Features
 
-* add H3 adapter ([#36](https://github.com/supabase/server/issues/36)) ([4310142](https://github.com/supabase/server/commit/43101427e64c01b986376ca5d94c5e008d0adcdf))
-
+- add H3 adapter ([#36](https://github.com/supabase/server/issues/36)) ([4310142](https://github.com/supabase/server/commit/43101427e64c01b986376ca5d94c5e008d0adcdf))
 
 ### Bug Fixes
 
-* reject invalid JWTs immediately instead of falling through to next  auth mode ([#35](https://github.com/supabase/server/issues/35)) ([0251690](https://github.com/supabase/server/commit/0251690a7f57eb3e2d72074348d8a96f5fb55231))
+- reject invalid JWTs immediately instead of falling through to next auth mode ([#35](https://github.com/supabase/server/issues/35)) ([0251690](https://github.com/supabase/server/commit/0251690a7f57eb3e2d72074348d8a96f5fb55231))
 
 ## [0.1.4](https://github.com/supabase/server/compare/server-v0.1.3...server-v0.1.4) (2026-04-01)
 
-
 ### Features
 
-* add `supabaseOptions` and refactor client creation to options objects ([#19](https://github.com/supabase/server/issues/19)) ([5a10099](https://github.com/supabase/server/commit/5a100995a1b6254f92768c82c74b1c754c29b3b2))
-* exposing `keyName` to `SupabaseContext` ([#22](https://github.com/supabase/server/issues/22)) ([7f1b1a7](https://github.com/supabase/server/commit/7f1b1a75cc98d08a63275131481e5df825c10afb))
-* implement server-side DX primitives, wrappers, and adapters ([#6](https://github.com/supabase/server/issues/6)) ([d206e5c](https://github.com/supabase/server/commit/d206e5cdb102bf96e0c501b72e7f161cbf9fba0c))
-* passing down Database generic type to `createClient` ([#16](https://github.com/supabase/server/issues/16)) ([4053f6d](https://github.com/supabase/server/commit/4053f6d8db89201a239190a025b08cf19083acb4))
-* set initial release version ([8352bda](https://github.com/supabase/server/commit/8352bda35c5967a6692f0a21744d30793e10709a))
-* standardize error response ([#18](https://github.com/supabase/server/issues/18)) ([a7ddb74](https://github.com/supabase/server/commit/a7ddb74bfbbe4565d461be7df7f01e64854f6c06))
-
+- add `supabaseOptions` and refactor client creation to options objects ([#19](https://github.com/supabase/server/issues/19)) ([5a10099](https://github.com/supabase/server/commit/5a100995a1b6254f92768c82c74b1c754c29b3b2))
+- exposing `keyName` to `SupabaseContext` ([#22](https://github.com/supabase/server/issues/22)) ([7f1b1a7](https://github.com/supabase/server/commit/7f1b1a75cc98d08a63275131481e5df825c10afb))
+- implement server-side DX primitives, wrappers, and adapters ([#6](https://github.com/supabase/server/issues/6)) ([d206e5c](https://github.com/supabase/server/commit/d206e5cdb102bf96e0c501b72e7f161cbf9fba0c))
+- passing down Database generic type to `createClient` ([#16](https://github.com/supabase/server/issues/16)) ([4053f6d](https://github.com/supabase/server/commit/4053f6d8db89201a239190a025b08cf19083acb4))
+- set initial release version ([8352bda](https://github.com/supabase/server/commit/8352bda35c5967a6692f0a21744d30793e10709a))
+- standardize error response ([#18](https://github.com/supabase/server/issues/18)) ([a7ddb74](https://github.com/supabase/server/commit/a7ddb74bfbbe4565d461be7df7f01e64854f6c06))
 
 ### Bug Fixes
 
-* key name resolution for client creation ([#9](https://github.com/supabase/server/issues/9)) ([e17bd4e](https://github.com/supabase/server/commit/e17bd4ecb1c46d0dc1468f363c884090d78ae86a))
-* move SKILL.md into skills/ subdirectory to align with agentskills spec ([#24](https://github.com/supabase/server/issues/24)) ([10c8780](https://github.com/supabase/server/commit/10c8780cc21de3bb860d2ec8bf5589f69d4ea447))
-* release action ([#29](https://github.com/supabase/server/issues/29)) ([91580d1](https://github.com/supabase/server/commit/91580d11fd1217a22da1150757114ee980d6157b))
-* remove provenance until repo is public ([2ebbc71](https://github.com/supabase/server/commit/2ebbc71e214c4bbae62c6af203a039801b5e3d4d))
-* removing `core` lib exports from root index ([#17](https://github.com/supabase/server/issues/17)) ([5e53e3c](https://github.com/supabase/server/commit/5e53e3c14fcc7c198f1c0bbec9089b4aedd91473))
-* support bare array format for SUPABASE_JWKS ([#8](https://github.com/supabase/server/issues/8)) ([6bd2e4d](https://github.com/supabase/server/commit/6bd2e4dfc1b60ce4cc8a1b59435b87797e1cb017))
+- key name resolution for client creation ([#9](https://github.com/supabase/server/issues/9)) ([e17bd4e](https://github.com/supabase/server/commit/e17bd4ecb1c46d0dc1468f363c884090d78ae86a))
+- move SKILL.md into skills/ subdirectory to align with agentskills spec ([#24](https://github.com/supabase/server/issues/24)) ([10c8780](https://github.com/supabase/server/commit/10c8780cc21de3bb860d2ec8bf5589f69d4ea447))
+- release action ([#29](https://github.com/supabase/server/issues/29)) ([91580d1](https://github.com/supabase/server/commit/91580d11fd1217a22da1150757114ee980d6157b))
+- remove provenance until repo is public ([2ebbc71](https://github.com/supabase/server/commit/2ebbc71e214c4bbae62c6af203a039801b5e3d4d))
+- removing `core` lib exports from root index ([#17](https://github.com/supabase/server/issues/17)) ([5e53e3c](https://github.com/supabase/server/commit/5e53e3c14fcc7c198f1c0bbec9089b4aedd91473))
+- support bare array format for SUPABASE_JWKS ([#8](https://github.com/supabase/server/issues/8)) ([6bd2e4d](https://github.com/supabase/server/commit/6bd2e4dfc1b60ce4cc8a1b59435b87797e1cb017))
 
 ## [0.1.3](https://github.com/supabase/server/compare/server-v0.1.2...server-v0.1.3) (2026-04-01)
 
-
 ### Bug Fixes
 
-* move SKILL.md into skills/ subdirectory to align with agentskills spec ([#24](https://github.com/supabase/server/issues/24)) ([10c8780](https://github.com/supabase/server/commit/10c8780cc21de3bb860d2ec8bf5589f69d4ea447))
+- move SKILL.md into skills/ subdirectory to align with agentskills spec ([#24](https://github.com/supabase/server/issues/24)) ([10c8780](https://github.com/supabase/server/commit/10c8780cc21de3bb860d2ec8bf5589f69d4ea447))
 
 ## [0.1.2](https://github.com/supabase/server/compare/server-v0.1.1...server-v0.1.2) (2026-04-01)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,6 +11,7 @@ Thank you for your interest in contributing to `@supabase/server`! This document
 - [Testing](#testing)
 - [Code Style](#code-style)
 - [Submitting Changes](#submitting-changes)
+- [Contributing a framework adapter](#contributing-a-framework-adapter)
 - [Release Process](#release-process)
 
 ## Getting Started
@@ -150,6 +151,12 @@ BREAKING CHANGE: auth configuration now uses a discriminated union
 - Rebase on `main` if needed to resolve conflicts
 - Be responsive to review feedback
 
+## Contributing a framework adapter
+
+Framework adapters (Hono, H3, …) are community-maintained and live in this repo under `src/adapters/`. They have **additional requirements** on top of the general PR guidelines above — tests covering every auth mode, no new runtime deps beyond a peer-dep, matching the existing adapter shape, and updating both adapter tables (in `README.md` and `src/adapters/README.md`).
+
+See [`src/adapters/README.md`](src/adapters/README.md) for the full checklist before opening an adapter PR.
+
 ## Release Process
 
 This project uses [release-please](https://github.com/googleapis/release-please) for automated releases. You don't need to manually manage versions or changelogs.

diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,47 @@
+# Migration
+
+## v0.x → v1.0
+
+v1.0 ships a coordinated set of API renames adopted as part of v1 prep. They make the public surface read more naturally and align with Supabase CLI and env-var terminology. Once v2 lands, the deprecated names below will be removed.
+
+### Renames
+
+| Before                                         | After                                          | Notes                                                                                                                                                                                                                           |
+| ---------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `withSupabase({ allow: ... })`                 | `withSupabase({ auth: ... })`                  | **Soft-deprecated.** `allow` still works in v1 and emits a one-time `console.warn` per process; `auth` wins when both are present. Removed in v2.                                                                               |
+| `auth: 'always'`                               | `auth: 'none'`                                 | Reads more directly as "no authentication required".                                                                                                                                                                            |
+| `auth: 'public'` / `'public:<name>'`           | `auth: 'publishable'` / `'publishable:<name>'` | Matches `SUPABASE_PUBLISHABLE_KEY(S)` and the `sb_publishable_...` key prefix.                                                                                                                                                  |
+| `ctx.authType` / `auth.authType`               | `ctx.authMode` / `auth.authMode`               | Lines the field up with its `AuthMode` type.                                                                                                                                                                                    |
+| `ctx.claims` / `auth.claims`                   | `ctx.jwtClaims` / `auth.jwtClaims`             | Pairs naturally with `userClaims`; distinguishes the snake_case JWT payload from the normalized identity view.                                                                                                                  |
+| `SupabaseContext.authKeyName?: string \| null` | `SupabaseContext.authKeyName?: string`         | Single absence representation. The property is omitted for `'user'` / `'none'` modes that don't match a named key. `AuthResult.keyName` deliberately keeps `string \| null` (low-level type where the field is always present). |
+| `Allow` / `AllowWithKey` (types)               | `AuthMode` / `AuthModeWithKey`                 | **Soft-deprecated.** Old aliases still resolve to the new types; removed in v2 alongside the `allow` option.                                                                                                                    |
+
+### Migration cheat sheet
+
+Most of the migration is a find-and-replace at the call site:
+
+| Pattern                                                       | Replace with                                                        |
+| ------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `allow:`                                                      | `auth:` (or leave it for now and silence the warning later)         |
+| `auth: 'always'`                                              | `auth: 'none'`                                                      |
+| `auth: 'public'` / `'public:<name>'`                          | `auth: 'publishable'` / `'publishable:<name>'`                      |
+| `ctx.authType` / `auth.authType`                              | `ctx.authMode` / `auth.authMode`                                    |
+| `ctx.claims` / `auth.claims`                                  | `ctx.jwtClaims` / `auth.jwtClaims`                                  |
+| `ctx.authKeyName === null`                                    | `ctx.authKeyName === undefined` (or just `!ctx.authKeyName`)        |
+| `import type { Allow, AllowWithKey } from '@supabase/server'` | `import type { AuthMode, AuthModeWithKey } from '@supabase/server'` |
+
+### Why these names?
+
+- **`auth` over `allow`** — matches Supabase CLI terminology; `auth: 'user'` reads more naturally as "this endpoint authenticates a user."
+- **`'none'` over `'always'`** — `'none'` reads more directly as "no authentication required" than `'always'` did as "always allow."
+- **`'publishable'` over `'public'`** — matches the env var names `SUPABASE_PUBLISHABLE_KEY(S)` and the `sb_publishable_...` key prefix used everywhere else in Supabase.
+- **`authMode` over `authType`** — lines up the field name with its TypeScript type (`authMode: AuthMode`).
+- **`jwtClaims` over `claims`** — reading `userClaims` and `jwtClaims` next to each other makes it obvious which is the normalized identity view vs. the raw JWT payload.
+- **`authKeyName?: string` over `string | null`** — single absence representation; consumers don't have to handle both `null` and `undefined`.
+
+### Compatibility timeline
+
+- **v1.x** — deprecated `allow:` option and `Allow` / `AllowWithKey` aliases continue to work; one-time `console.warn` on first use of `allow:`.
+- **v2.0** — deprecated names will be removed.
+
+The renamed mode values (`'always'` / `'public'` → `'none'` / `'publishable'`) and the renamed fields (`authType` → `authMode`, `claims` → `jwtClaims`) are **already removed** in v1.0 — their old forms no longer work at runtime or in TypeScript.