@supabase/lite 0.8.0 → 0.8.1-next.2

package/LIMITATIONS.md

@@ -10,7 +10,7 @@ Anchors below point to the corresponding STATUS.md section. If a limitation here
 - Subquery `WITH CHECK` on `INSERT` (`user_id IN (SELECT …)`, `EXISTS (…)`) → throws. Denormalise the owning column. See [RLS known limitations](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
 - Scalar functions outside the allow-list in `DEFAULT` or `CHECK` (`trim`, `btrim`, `length`, `lower`, `upper`, …) → `Function call "<name>" not supported`. Use literals or move the check to the app layer. See [Column Defaults](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#column-defaults) and [CHECK constraint functions](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#check-constraint-functions).
 - `nextval` / `currval`, `clock_timestamp`, `txid_current`, user-defined functions → not supported. See [Column Defaults](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#column-defaults).
-- `FORCE ROW LEVEL SECURITY` → not differentiated from `ENABLE ROW LEVEL SECURITY`. See [RLS known limitations](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
+- `FORCE ROW LEVEL SECURITY` / `NO FORCE` → accepted and ignored (no table-owner exemption to toggle). See [RLS known limitations](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
 - PL/pgSQL `DECLARE`, `IF`, `LOOP`, `RAISE`, variables → not supported in trigger bodies. See [PL/pgSQL Trigger Functions](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#plpgsql-trigger-functions).
 
 ## supabase-js (SQLite path)
@@ -26,15 +26,25 @@ Anchors below point to the corresponding STATUS.md section. If a limitation here
 ## Auth (shipped with caveats)
 
 - `double_confirm_changes = true` (secure email change) is spec-compatible but **not** GoTrue's full two-mailbox flow: it finalizes from the current-email confirmation only, so it does not require the new mailbox to also confirm. It still prevents a session thief from changing the email using only a mailbox they control. See [Auth email delivery & templates](https://github.com/supabase-community/lite/blob/HEAD/docs/src/content/docs/auth/email.mdx).
+- OAuth / social sign-in (`signInWithOAuth`, `exchangeCodeForSession`) only implements `github` and `google`. Enabling any other configured provider (including `apple`) returns "provider ... is not yet implemented". Automatic account linking on a verified-email match works; manual `linkIdentity()`/`unlinkIdentity()` do not. On the D1 backend, multi-statement Auth transaction spans (OAuth callback/token writes, email-change and other OTP verification) run best-effort without a wrapping transaction (D1 has no callback transaction API; single-statement guards still prevent code/state reuse) — all other backends are fully transactional. See [Auth API: Implemented](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#auth-api-gotrue-compatible).
+- Legacy JWT-as-apikey (`ANON_KEY`/`SERVICE_ROLE_KEY` HS256) → not supported. Use the opaque `sb_publishable_*`/`sb_secret_*` keys instead. See [API Keys](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#api-keys).
+- API key enforcement is opt-in: with no `auth.publishable_key`/`auth.secret_key` configured, `/rest/v1` and `/auth/v1` accept any/no `apikey` (unchanged old behavior). See [API Keys](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#api-keys).
+- A key passed only via `Authorization` (no `apikey` header/query param) → 401. Use `apikey` header or `?apikey=` query param. See [API Keys](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#api-keys).
+- No local mailbox UI: `[auth.email.smtp] enabled = true` sends real mail via `SmtpEmailDriver` (Nodemailer; e.g. to Mailpit/Inbucket at `localhost:1025`), but there is no built-in mailbox web UI to browse those messages — use the SMTP server's own UI. `[inbucket]` config is still parsed but not acted on: no local Inbucket-compatible service is started. The default `ConsoleEmailDriver` prints emails (To/Subject/text) to the console instead. `SmtpEmailDriver` requires Node or Bun; it is not supported on Cloudflare Workers or in the browser. See [Auth email delivery & templates](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#auth-api-gotrue-compatible).
 
 ## Auth (planned, not yet shipped)
 
-- OAuth, anonymous sign-in, identity linking, admin API, MFA → planned. See [Auth API: Planned](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#-planned).
+- Other OAuth providers (Apple and the rest of the 18-provider config surface), anonymous sign-in, manual identity linking, admin API, MFA → planned. See [Auth API: Planned](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#-planned).
 
 ## Runtime / dev
 
-- `vite preview` does **not** mount the API. Plugin runs in `vite` / `vite dev` only. See [Vite plugin scope](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#vite-plugin-scope).
+- `vite preview` mounts the API and runs boot migrations, but does **not** watch schemas and never enables admin mode (it simulates production). `vite build` and standalone production servers do not mount the API at all. See [Vite plugin scope](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#vite-plugin-scope).
 - Do not run `lite dev` (or `lite start`) alongside the Vite plugin — both bind the API and collide. See [When to use what](https://github.com/supabase-community/lite/blob/HEAD/README.md#when-to-use-what).
+- `lite start` runs the imperative (migrations) workflow. Develop a declarative project (`supabase/schemas/*.sql`) with `lite dev` or the Vite plugin, and ship it by generating a migration: `lite db diff -f <name>` then `lite db reset`. `lite start` works on a declarative project while the cache written by the last `lite dev` run is valid; without a valid cache it is always refused, with no exceptions — it never re-derives RLS from schema files it did not apply, and never substitutes migration-only metadata for them. `lite db diff -f <name>` followed by `lite db reset` is the transition that makes the migration history authoritative, and after it `lite start` boots again. `lite migration up` is not that transition: it is non-destructive, so the generated migration re-creates objects the declarative apply already created and fails against the live development database. `lite db reset` is the related gotcha: it is destructive and replays migrations only, so anything `schemas/*.sql` describes that you never captured with `lite db diff -f` — tables and RLS policies alike — is simply not in the reset database. See [RLS](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
+- `supabase/.temp/.deparse-cache.json` is safe to delete: it is regenerated on the next apply/translate, and a boot that cannot rebuild it fails closed (refuses to serve), never open. Only `sqlite-postgres` uses it. See [RLS](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
+- **Admin mode is on by default locally.** `lite dev`, `lite start`, and the Vite dev server serve *keyless* `/rest/v1` (+ `/storage/v1` on the CLI) requests as `service_role`, so those requests bypass RLS. Credentialed requests are unaffected. Disable with `--no-admin` / `supalite({ admin: false })`. See [API Keys](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#api-keys).
+- Admin mode never elevates `/auth/v1`, cross-origin requests, requests from a non-loopback socket, or requests for a non-loopback hostname (DNS rebinding) — so it is not a way to reach a dev server from another machine or from a hostile page. Embedders get the hostname check only, so set `options.server.admin` on a loopback-bound server or not at all.
+- The Vite plugin mounts `/rest/v1` but not `/storage/v1`, so admin mode covers storage on the CLI only unless you add the prefix. See [Vite plugin scope](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#vite-plugin-scope).
 
 ## Postgres backends (pglite, postgres)
 
@@ -52,5 +62,8 @@ Common ways code goes wrong against supalite. The fix for each is the correspond
 - Don't call `rpc()` on the SQLite path. Run a regular HTTP endpoint, or switch the driver to `pglite` / `postgres` in `config.toml`.
 - Don't use embedded dotted-path filters (`.eq('rel.col', v)`) on SQLite. Filter the FK column on the parent, or fetch matching ids first.
 - Don't run `lite dev` or `lite start` next to the Vite plugin — port collision.
-- Don't assume `vite preview` mounts the API. It doesn't. Use `lite start` or a real backend for non-dev environments.
+- Don't `lite db reset` then `lite start` on a declarative project and expect your schema to be there. Reset is destructive and replays migrations only, adopting that state (RLS included) as the authoritative one — run `lite db diff -f <name>` first so the declarative schema exists as a migration.
+- Don't test RLS with a keyless request while admin mode is on — it runs as `service_role` and sees everything. Send `apikey: $PUBLISHABLE_KEY` (for `anon`), plus `Authorization: Bearer $USER_JWT` for `authenticated`, or start with `--no-admin`.
+- Don't send only `Authorization: Bearer $USER_JWT` and expect `authenticated` RLS. With keys configured that's a 401 — the `apikey` is required as well.
+- Don't rely on `vite preview` for a production-like surface beyond the API mount: it skips schema watching and admin mode, but it is still a dev tool. Use `lite start` or a real backend for non-dev environments.
 - Don't reach for `trim` / `length` / `lower` inside `CHECK` constraints on SQLite — use literal/operator comparisons.

package/PATTERNS.md

@@ -36,6 +36,27 @@ await supabase.from("<thing>").insert({
 });
 ```
 
+## Verifying RLS policies locally
+
+Local admin mode is on by default (`lite dev`, `lite start`, Vite dev server), and a request with **no** credential runs as `service_role` — so a bare `curl` sees every row and proves nothing about your policies. Always test with a credential; those requests are never elevated and behave exactly as they will in production.
+
+```bash
+# anon: what a logged-out visitor sees
+curl -H "apikey: $SUPABASE_PUBLISHABLE_KEY" \
+  "http://localhost:54321/rest/v1/<thing>?select=*"
+
+# authenticated: the apikey is required IN ADDITION to the user JWT
+JWT=$(curl -s -H "apikey: $SUPABASE_PUBLISHABLE_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"a@b.co","password":"secret123"}' \
+  "http://localhost:54321/auth/v1/token?grant_type=password" | jq -r .access_token)
+
+curl -H "apikey: $SUPABASE_PUBLISHABLE_KEY" -H "Authorization: Bearer $JWT" \
+  "http://localhost:54321/rest/v1/<thing>?select=*"
+```
+
+`Authorization` alone is a 401 — opaque keys are only read from `apikey`, matching upstream. supabase-js sends both automatically, so app code needs no special handling. To take admin mode out of the picture entirely, start with `--no-admin` (or `supalite({ admin: false })`) and every request will require a key.
+
 ## Filtering an embedded resource (SQLite path)
 
 Dotted-path filters (`.eq('rel.col', v)`) are not supported on SQLite. Two options:
@@ -78,7 +99,7 @@ The canonical Vite recipe:
 5. `src/lib/supabase.ts`:
    ```ts
    import { createClient } from "@supabase/supabase-js";
-   export const supabase = createClient(window.location.origin, "any-string-works-for-now");
+   export const supabase = createClient(window.location.origin, "<sb_publishable_...>");
    ```
 6. `bun run dev`.
 

package/README.md

@@ -14,7 +14,7 @@ Supalite targets AI builders who want quick, cheap prototypes today with a clear
 
 **Scope:** Both declarative schema (`supabase/schemas/*.sql`) and imperative Postgres migrations (`supabase/migrations/*.sql`, Supabase-CLI compatible) are supported. See [Migrations](#migrations). Advanced Postgres-specific column types (ranges, arrays of composites, and similar) are not available.
 
-Validated against the upstream PostgREST and GoTrue spec suites: 1,918 cases passing on SQLite (1,677 Data API + 241 Auth), zero failing. See [Testing](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#testing) for per-backend pass rates.
+Correctness is checked against an internal spec suite derived from the upstream PostgREST and GoTrue test suites: ~2,400 Data API and ~500 Auth cases, replayed against every backend with zero failures. Together with the repo's own suite that's ~32k assertions. See [Testing](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#testing) for current pass rates and skips.
 
 ---
 
@@ -49,7 +49,7 @@ For a per-capability parity view with effort estimates and feasibility notes for
 |-------------------------|--------|--------------------------------------------------------------------|
 | [Databases](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#database-support)               | ✅     | `bun:sqlite`, `node:sqlite`, sqlite-wasm, Cloudflare D1 + DO, PGlite, PostgreSQL |
 | [Data API (PostgREST)](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#database-api-postgrest-compatible)    | ✅     | 53/74 supabase-js methods on SQLite: `from`, `select`, `insert`, `update`, `delete`, `upsert`, `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `is`, `isDistinct`, `like`, `ilike`, `likeAllOf`, `likeAnyOf`, `ilikeAllOf`, `ilikeAnyOf`, `match`, `or`, `not`, `filter`, `order`, `limit`, `range`, `single`, `maybeSingle`, `csv`, `abortSignal`, `setHeader`, `throwOnError`, `maxAffected`, `returns`, `overrideTypes`, plus full resource embedding (FK joins, `!inner`, spreads, nested, aggregates). Partial: `contains`, `containedBy`, `overlaps`, `textSearch` (LIKE-based lexeme approximation), `regexMatch`/`regexIMatch` (simple anchored patterns). `rpc` not supported on SQLite. 72/74 on Postgres. |
-| [Auth API (GoTrue)](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#auth-api-gotrue-compatible)       | ✅     | 21/63 supabase-js methods (11 backend + 10 client-side helpers): `signUp`, `signInWithPassword`, `signInWithOtp`, `verifyOtp`, `refreshSession`, `signOut`, `getUser`, `updateUser`, `resetPasswordForEmail`, `resend`, `reauthenticate`. OAuth, anonymous, identity linking, admin API, and MFA planned. |
+| [Auth API (GoTrue)](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#auth-api-gotrue-compatible)       | ✅     | 23/63 supabase-js methods (13 backend + 10 client-side helpers): `signUp`, `signInWithPassword`, `signInWithOtp`, `verifyOtp`, `refreshSession`, `signOut`, `getUser`, `updateUser`, `resetPasswordForEmail`, `resend`, `reauthenticate`, `signInWithOAuth`, `exchangeCodeForSession`. OAuth covers `github`/`google` only (PKCE + implicit, automatic account linking); other providers (incl. Apple), anonymous sign-in, manual identity linking, admin API, and MFA planned. |
 | [Storage API](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#storage-api-compatible)             | 🧪     | 20/20 supabase-js methods: `upload`, `download`, `list`, `remove`, `move`, `copy`, `info`, `exists`, `update`, `getPublicUrl`, `createSignedUrl`, `createSignedUrls`, `createSignedUploadUrl`, `uploadToSignedUrl`, `listBuckets`, `getBucket`, `createBucket`, `updateBucket`, `deleteBucket`, `emptyBucket`. Role-based access + RLS pending. <br />⚠️ Gated behind `EXPERIMENTAL_STORAGE`. |
 | Realtime                | 🔄     | Coming soon                                                        |
 | Edge Functions          | 🔄     | Coming soon                                                        |
@@ -75,14 +75,16 @@ lite dev       # start server with schema hot-reload
 
 The API is now running at `http://localhost:54321`. Point `@supabase/supabase-js` at it:
 
+`lite init` also generates any missing publishable/secret API key(s) into root `.env` (per-variable, never overwrites an existing one) and prints them:
+
 ```typescript
 import { createClient } from "@supabase/supabase-js";
 
-const supabase = createClient("http://localhost:54321", "any-string-works-for-now");
+const supabase = createClient("http://localhost:54321", "<sb_publishable_...>");
 const { data } = await supabase.from("todos").select("*");
 ```
 
-> No anon key is required yet. Pass any non-empty string as the second argument.
+> Use the printed `sb_publishable_*` key as the anon key. If no keys are configured, any/no `apikey` is accepted (old behavior) — see [API keys](#api-keys).
 
 Edit `supabase/schemas/schema.sql` and the dev server re-applies the schema automatically.
 
@@ -116,7 +118,8 @@ to show details like the config file and database location on stderr.
 
 | Command          | Description                                                   |
 |------------------|---------------------------------------------------------------|
-| `init`           | Scaffold `supabase/` (config, schema, seed, data dir)         |
+| `init`           | Scaffold `supabase/` (config, schema, seed, data dir); generates any missing API key(s) into `.env` |
+| `generate-keys`  | (Re)generate the publishable/secret API key pair, upsert `.env`        |
 | `dev`            | Start server + watch `schemas/*.sql`, auto-apply on change    |
 | `start`          | Start server (no watch, no auto-migrate)                      |
 | `db schema`      | Print current DB schema; `--diff` compares vs `schemas/*.sql` |
@@ -148,6 +151,7 @@ lite db translate "alter table public.todos add column done boolean" | lite db q
 echo "select * from todos" | lite db query                   # pipe a one-off statement in
 lite upgrade --dry-run          # rehearsal plus SQLite shim audit
 lite upgrade --dry-run --json   # machine-readable shim audit output
+lite generate-keys              # (re)generate the API key pair, upsert .env
 ```
 
 Upgrade targets:
@@ -251,6 +255,8 @@ enabled = true
 jwt_secret = "dev-secret-change-me"
 jwt_expiry = 3600
 enable_signup = true
+publishable_key = "env(SUPABASE_PUBLISHABLE_KEY)"
+secret_key = "env(SUPABASE_SECRET_KEY)"
 
 [auth.email]
 enable_confirmations = false
@@ -258,6 +264,44 @@ enable_confirmations = false
 
 > **`auth.jwt_secret`**: if omitted, auth falls back to the insecure placeholder `"unsafe-secret-change-me"` so local dev doesn't break. Always set your own for anything beyond throwaway local use.
 
+### API keys
+
+`lite init` generates a `sb_publishable_*`/`sb_secret_*` key pair into root `.env` (`SUPABASE_PUBLISHABLE_KEY`/`SUPABASE_SECRET_KEY`) and wires `auth.publishable_key`/`auth.secret_key` to reference them via `env(VAR)`, same field names as the upstream `supabase` CLI. It's per-variable: only whichever key is actually missing gets (re)generated — an existing `SUPABASE_PUBLISHABLE_KEY` or `SUPABASE_SECRET_KEY` is never overwritten. `lite start`/`lite dev` print the resolved keys under the server URL.
+
+Enforcement kicks in once at least one key is configured: `sb_publishable_*` authenticates as `anon`, `sb_secret_*` as `service_role` (bypasses RLS, including on SQLite). An unconfigured key simply never matches. With no keys configured at all, `/rest/v1` and `/auth/v1` keep the old behavior (any/no `apikey` accepted). Keys must be sent via the `apikey` header or `?apikey=` query param — supabase-js does this automatically — a key sent only via `Authorization` is rejected. A real user session JWT in `Authorization` always outranks the API key. `/storage/v1` is transform-only (like upstream self-hosted Kong): it never 401s on a missing/invalid key, so public/signed/S3-presigned URLs stay keyless, but a secret key still satisfies storage's own authed routes as `service_role`. Legacy JWT-as-apikey (`ANON_KEY`/`SERVICE_ROLE_KEY` HS256) is not supported.
+
+Lost or rotating keys: `lite generate-keys` mints a fresh pair and upserts `.env`.
+
+### Admin mode (local only)
+
+`lite dev`, `lite start`, and the Vite dev server run with admin mode **on**. A request carrying no credential at all — no `apikey`, no `Authorization` — on `/rest/v1` (and `/storage/v1` on the CLI) is served as `service_role`. That's what lets the built-in studio read and edit any table without a secret key shipping to the browser, mirroring self-hosted Supabase Studio where the server holds the key.
+
+Elevation additionally requires the request to be same-origin (or carry no `Origin`), to arrive on a loopback socket, and to name a loopback host. Both locality checks are needed: the socket peer stops a machine on your network from spoofing `Host: localhost`, and the hostname stops DNS rebinding, where a hostile page re-resolves its own domain to `127.0.0.1` so the socket is genuinely loopback. `/auth/v1` is never elevated, and the Vite plugin only mounts `/rest/v1`.
+
+```bash
+lite start --no-admin              # off: keyless requests are no longer elevated
+```
+```ts
+supalite({ admin: false })         # off for the Vite dev server
+```
+
+Precedence is explicit flag > `options.server.admin` in `config.toml` > launcher default, so a config file can opt a project out but can never re-enable admin after `--no-admin`. Off by default when embedding `App` yourself and in `vite preview`.
+
+Because keyless requests skip RLS, test policies with a credential: `apikey: $PUBLISHABLE_KEY` for `anon`, and that **plus** `Authorization: Bearer $USER_JWT` for `authenticated`. A bearer token alone is a 401.
+
+Embedding the `App` class directly: `app.getClient()` defaults to the configured publishable key (override via `{ apikey }`). Disable enforcement entirely with `options.server.apiKeys: false`, or supply your own key→role mapping via `options.server.apiKeys.resolver`:
+
+```ts
+new App({
+  connection,
+  options: {
+    server: {
+      apiKeys: { resolver: async (key) => key === myKey ? { type: "secret", claims: { role: "service_role" } } : null },
+    },
+  },
+});
+```
+
 ---
 
 ## Writing schemas
@@ -318,7 +362,7 @@ const client = app.getClient();
 const { data } = await client.from("todos").select("*");
 ```
 
-Queries route through `app.fetch` internally. Same API, no HTTP round trip.
+Queries route through `app.fetch` internally. Same API, no HTTP round trip. `getClient()` defaults to the configured `auth.publishable_key` (override with `getClient({ apikey })`).
 
 ---
 

package/STATUS.md

@@ -239,11 +239,13 @@ Each supported behavior is regression-covered against both backends in [`app/tes
 |-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Subquery `WITH CHECK` on `INSERT`       | `WITH CHECK` expressions containing subqueries (e.g. `user_id IN (SELECT ...)`, `EXISTS (...)`) cannot be evaluated in-memory. Currently throws an error. **Workaround:** denormalise the authorising column (e.g. `user_id` onto the child table) and use `auth.uid() = user_id`. See [WITH CHECK subqueries](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/limitations/rls-with-check-subqueries.md). |
 | `UPSERT` applies `INSERT` policies only | Postgres applies `UPDATE` policies on conflict; supalite applies `INSERT WITH CHECK` to all upsert rows since conflict resolution is unknown pre-execution. |
-| `FORCE ROW LEVEL SECURITY`              | Not differentiated from `ENABLE ROW LEVEL SECURITY`; table owner is not exempt.                                                                            |
+| `FORCE ROW LEVEL SECURITY`              | Accepted and ignored (`FORCE` / `NO FORCE`): there is no table-owner exemption to toggle. As on Postgres, `FORCE` alone does not enable RLS.                 |
 | `RETURNING` + `SELECT` policy           | Postgres errors if `RETURNING` references rows not visible to `SELECT` policy. Not checked.                                                                 |
 
 📖 See [`internal/docs/postgres/rls.md`](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/postgres/rls.md) for the full RLS reference and behavior matrix.
 
+**SQLite metadata persistence (`sqlite-postgres`):** Policies live in translation metadata, not in the database file, so a command that never migrates would otherwise boot with RLS off. Every declarative schema translation, every `lite db reset`, and every migration apply in a migrations-only project writes the full deparse info to `supabase/.temp/.deparse-cache.json`. `lite start` restores that cache, verified against the migration-history fingerprint, the schema hash, member-level payload validation, and a cross-check that its RLS table list still covers everything the applied migration history enabled RLS on. When the cache is missing or stale, a migrations-only project recalculates from the applied migration history (never from unapplied migration files). A declarative project (`supabase/schemas/*.sql`) is instead refused outright, with no exceptions: `lite start` serves the migrations workflow and never applies schema files, so without a valid cache it exits with non-interactive recovery instructions rather than guessing. `lite db diff -f <name>` then `lite db reset` is the transition that establishes migration authority — the generated migration carries the schema's `ENABLE ROW LEVEL SECURITY` / `CREATE POLICY` statements, and `db reset` is destructive, so afterwards the migration-derived metadata describes the fresh database exactly and is always persisted. That is what makes the recovery loop terminate. A non-destructive `lite migration up` never persists over a declarative project's snapshot, because it cannot know what the live database still carries from a declarative apply. RLS metadata also follows the table lifecycle: an `ALTER TABLE ... RENAME TO` carries enforcement and its policies to the new name, and a `DROP TABLE` (even followed by a `CREATE TABLE` of the same name) drops them, matching Postgres. Embedded/programmatic use falls back to a per-table deny backstop. The cache file is safe to delete — it is regenerated by the next apply, and a boot that cannot rebuild it fails closed, never open. `pglite` / `postgres` (native RLS) and the bare `sqlite` driver are unaffected. See [LIMITATIONS.md](https://github.com/supabase-community/lite/blob/HEAD/LIMITATIONS.md) for the declarative-project workflow.
+
 **PGlite / PostgreSQL auto-setup:** When any table has `ENABLE ROW LEVEL SECURITY`, supalite creates `anon`, `authenticated`, and `service_role` roles (if missing; `service_role` uses `BYPASSRLS`) and grants default privileges on all tables and sequences in the relevant schemas. No manual `CREATE ROLE` or `GRANT` statements needed for these built-in roles.
 
 ### PL/pgSQL Trigger Functions
@@ -488,6 +490,8 @@ Run `bun run test:spec:analyze` (or `:sqlite-postgres`, `:pglite`, `:postgres`)
 
 Backend implementation in `app/src/auth/`. GoTrue-compatible HTTP endpoints at `/auth/v1/*`.
 
+Auth behaves identically across database backends, with one caveat: on Cloudflare D1, multi-statement Auth transaction spans (OAuth callback/token writes, email-change and other OTP verification) run best-effort without a wrapping transaction — D1 has no callback transaction API, so errors propagate but prior writes persist. Single-statement atomic guards (conditional `UPDATE`/`DELETE` with rowcount checks) still prevent auth-code/state/token reuse on D1. All other backends, including Durable Objects, are fully transactional.
+
 ### ✅ Implemented
 
 | Method                 | Endpoint                               | Notes                                                                 |
@@ -503,6 +507,8 @@ Backend implementation in `app/src/auth/`. GoTrue-compatible HTTP endpoints at `
 | `recover()`            | `POST /recover`                        | Password reset email                                                  |
 | `resend()`             | `POST /resend`                         | Resend confirmation / email change                                    |
 | `reauthenticate()`     | `GET /reauthenticate`                  | Request reauthentication nonce                                        |
+| `signInWithOAuth()`    | `GET /authorize`                       | `github` and `google` providers; authorization-code (PKCE) and implicit flows |
+| `exchangeCodeForSession()` | `GET`/`POST /callback`, `POST /token?grant_type=pkce` | PKCE code exchange; automatic account linking on verified-email match; other configured providers (incl. `apple`) return "provider ... is not yet implemented" |
 
 Supporting infrastructure:
 
@@ -513,16 +519,35 @@ Supporting infrastructure:
 - Configurable email signup, confirmations, and secure/insecure email change. Note: `double_confirm_changes=true` is spec-compatible (finalizes from the current-email confirmation, delivered to the current address) but does not implement GoTrue's full two-mailbox confirmation. See [LIMITATIONS.md](https://github.com/supabase-community/lite/blob/HEAD/LIMITATIONS.md#auth-shipped-with-caveats).
 - Mailer integration (confirmation, recovery, magic link, email change, reauthentication)
 - Default Supabase-styled email templates with `site_url`-based verify links; per-type overrides via `auth.email.template.<type>.{subject,content_path}` (GoTrue `{{ .ConfirmationURL }}` etc. variables)
-- Email drivers `Resend` / `AWS SES` / `Sendmail` (injected via `options.drivers.email`; default `NoopEmailDriver` logs only)
+- Email drivers `Resend` / `AWS SES` / `Sendmail` / `SMTP` (injected via `options.drivers.email`, or auto-selected for SMTP when `[auth.email.smtp] enabled = true`); `SMTP` sends via Nodemailer and requires Node or Bun (not Workers/browser); default `ConsoleEmailDriver` is a console mail catcher — prints To/Subject + the text body (including OTP codes and verification links) to the console instead of delivering
+
+### API Keys
+
+Opaque `sb_publishable_*` / `sb_secret_*` keys, matching Supabase's current key format. Generated per project (never hardcoded); configured via `auth.publishable_key` / `auth.secret_key` in `config.toml` (same field names as upstream `supabase` CLI), values sourced from root `.env` (`SUPABASE_PUBLISHABLE_KEY` / `SUPABASE_SECRET_KEY`) via `env(VAR)`.
+
+| Behavior | Status | Notes |
+|----------|--------|-------|
+| `sb_publishable_*` → `anon`, `sb_secret_*` → `service_role` | ✅ | Enforced on `/rest/v1` and `/auth/v1` only when keys are configured; unconfigured projects keep the old behavior (any/no `apikey` accepted) |
+| Auth exemptions (`/verify`, `callback`, `authorize`, `oauth`, `sso/saml`, `.well-known`, `scim`) | ✅ | Mirrors upstream's gateway exemption list |
+| Key source: `apikey` header or `?apikey=` query param | ✅ | A key in `Authorization` alone is rejected (401), matching upstream self-hosted conformance |
+| Real user session JWT in `Authorization` | ✅ | Always outranks the API key |
+| `/storage/v1` | ⚠️ | Transform-only, like upstream self-hosted Kong: keys map to roles when present, but a missing/invalid key never 401s at the gateway (public objects, signed URLs, S3 presigned flows stay keyless). Storage's own route auth still applies; a secret key satisfies storage's authed routes as `service_role` (including bypassing RLS-equivalent checks on SQLite) |
+| Secret key + browser `User-Agent` (`Mozilla/5.0`) | ✅ | Rejected (401), mirrors the hosted gateway's browser guard |
+| OpenAPI root (`GET /rest/v1/`) | ✅ | Requires the secret key: publishable → 403, secret → 200, mirroring upstream's admin-only ACL on that route (LITE-35) |
+| Local admin mode (`options.server.admin`) | ✅ | Local-dev only. A request with **no** credential (no `apikey` header/query, no `Authorization`) on `/rest/v1` or `/storage/v1` is served as `service_role`, so a browser studio can do admin work without a secret key reaching the browser. Also requires same-origin (or no `Origin`), a loopback **socket peer**, and a loopback **hostname** — both halves: the peer check stops a LAN client spoofing `Host: localhost`, the hostname check stops DNS rebinding (where the socket really is loopback but `Host`/`Origin` are the attacker's domain). `/auth/v1` is never elevated. On by default for `lite dev`, `lite start` (`--no-admin` to disable) and the Vite dev server (`/rest/v1` only there — the plugin doesn't mount `/storage/v1`); off for `vite preview` and for embedders. Precedence: explicit flag > `options.server.admin` in config > launcher default. Credentialed requests are unaffected, so `anon`/`authenticated` RLS stays testable (LITE-309) |
+| Secrets redacted from `/_system/config` / `/_system/info` | ✅ | `auth.secret_key` and `auth.jwt_secret` are masked in both responses |
+| Legacy JWT-as-apikey (`ANON_KEY`/`SERVICE_ROLE_KEY` HS256) | ❌ | Not supported |
+| `options.server.apiKeys: false` | ✅ | Disables enforcement entirely (embedders) |
+| `options.server.apiKeys.resolver` | ✅ | Custom resolver override (embedders) |
+
+CLI: `lite init` generates whichever key(s) are missing into root `.env` (per-variable — an existing key is never overwritten) and prints them; `lite generate-keys` (re)generates the whole pair and upserts `.env`; `lite start`/`lite dev` print the resolved keys under the server URL, or a hint that none are configured. `app.getClient()` defaults to the configured publishable key (override via `{ apikey }`).
 
 ### 🔄 Planned
 
 | Method                      | Notes                                                         |
 |-----------------------------|---------------------------------------------------------------|
-| `signInWithOAuth()`         | Config schema exists, major providers (Google, GitHub, Apple) |
-| `exchangeCodeForSession()`  | PKCE flow for OAuth                                           |
 | `signInAnonymously()`       | Create anonymous session                                      |
-| `linkIdentity()`            | Link OAuth identity to existing user                          |
+| `linkIdentity()`            | Manual link of an OAuth identity to an existing user (automatic linking on OAuth sign-in already works) |
 | `unlinkIdentity()`          | Remove linked identity                                        |
 | `admin.createUser()`        | Direct user creation (skip confirmation)                      |
 | `admin.listUsers()`         | Paginated user list                                           |
@@ -583,21 +608,20 @@ These methods exist in `@supabase/supabase-js` but are client-side concerns, not
 
 | Status            | Count |
 |-------------------|-------|
-| ✅ Implemented     | 11    |
-| 🔄 Planned        | 15    |
+| ✅ Implemented     | 13    |
+| 🔄 Planned        | 13    |
 | ⚫ Not Planned     | 27    |
 | ⚫ Client-side N/A | 10    |
 
 ### Auth spec: SQLite skip breakdown
 
-The 247 cases skipped against the supabase-spec Auth corpus break down by deferred feature. Generated by `cd app && bun run test:spec:auth:analyze:sqlite` (writes `.context/auth-analysis-sqlite.json`).
+The 223 cases skipped against the supabase-spec Auth corpus break down by deferred feature. Generated by `cd app && bun run test:spec:auth:analyze:sqlite` (writes `.context/auth-analysis-sqlite.json`). The 24 `oauth_redirect.json` cases now pass, closing the `oauth` category; they cover github/google authorize redirects, provider config validation, PKCE parameter persistence/validation, and callback error handling. The corpus has no successful provider callback and no `/token?grant_type=pkce` exchange, so that coverage lives in the focused mock-provider tests in `app/test/auth/oauth-*.test.ts` (implicit and PKCE round-trips, account linking, concurrency).
 
 | Category                        | Skipped | Why                                                                |
 |---------------------------------|--------:|--------------------------------------------------------------------|
 | `admin_api`                     | 69      | `/admin/*` endpoints (createUser, listUsers, generateLink, etc.)   |
 | `mfa`                           | 44      | TOTP/WebAuthn enroll/challenge/verify                              |
 | `non_runnable_spec_placeholder` | 29      | Upstream rows with `expected.status: null`; see `app/test/supabase-spec/auth/NON_RUNNABLE_PLACEHOLDERS.md` |
-| `oauth`                         | 24      | OAuth2/PKCE provider flows                                         |
 | `phone_sms`                     | 23      | Phone signup / SMS OTP                                             |
 | `saml_sso`                      | 18      | SAML / SSO                                                         |
 | `session_admin`                 | 12      | Admin session management                                           |
@@ -657,7 +681,7 @@ Backend implementation in `app/src/storage/`. HTTP endpoints at `/storage/v1/*`.
 | Feature                        | Notes                                                      |
 |--------------------------------|------------------------------------------------------------|
 | `/status` health endpoint      | Oracle returns 200 with no auth                            |
-| Role-based access control      | service_role-only for admin ops, anon/authenticated gating |
+| Role-based access control      | API keys now resolve `service_role`/`anon`/`authenticated` for storage's route-level auth (see [API Keys](#api-keys)); no per-object RLS policies yet |
 | RLS policies on storage tables | Per-user object access via row-level security              |
 | Bucket list query params       | `?search=`, `?limit=`, `?offset=` on `GET /bucket`         |
 | S3-compatible protocol         | `PUT/GET/DELETE` via S3 API paths (`/s3/`)                 |
@@ -708,8 +732,9 @@ Default command output is pipe-friendly: no global banner, and config/database-l
 
 | Command   | Status | Notes                                                              |
 |-----------|--------|--------------------------------------------------------------------|
-| `init`    | ✅      | Scaffolds API, migration/seed paths, and auth defaults; flags differ upstream |
-| `start`   | ✅      | In-process; no Docker stack flags (`-x`, `--ignore-health-check`)  |
+| `init`    | ✅      | Scaffolds API, migration/seed paths, and auth defaults; generates any missing publishable/secret API key(s) into root `.env` (per-variable, never overwrites an existing one); flags differ upstream |
+| `start`   | ✅      | In-process; prints resolved API keys under the server URL; no Docker stack flags (`-x`, `--ignore-health-check`). Never migrates; the entry point for the migrations workflow. On `sqlite-postgres` it restores/recalculates RLS metadata first and refuses to boot if it cannot (see [RLS](#row-level-security-rls)) |
+| `generate-keys` | ✅ | `[lite]`: (re)generates the publishable/secret API key pair and upserts root `.env` |
 | `status`  | 🧪      | `[experimental]` `[lite]`: shows linked project metadata          |
 | `login`   | 🧪      | `[experimental]` Email/password against supalite cloud             |
 | `logout`  | 🧪      | `[experimental]` Parity                                            |
@@ -736,7 +761,7 @@ Default command output is pipe-friendly: no global banner, and config/database-l
 | `db query`    | ✅      | Renamed from top-level `exec`; supports `--remote`, `--config`, and stdin |
 | `db schema`   | ✅      | `[lite]`: moved from top-level; `--diff` and `--sql` modes          |
 | `db push`     | 🔄     | Not registered; use `lite cloud deploy`                             |
-| `db reset`    | ✅      | Replays migrations + seed; does not apply declarative schema_paths   |
+| `db reset`    | ✅      | Replays migrations + seed; does not apply declarative schema_paths; clears `supabase/.temp` caches and always rewrites the deparse cache from the replayed migrations — the reset is destructive, so migration state (RLS included) becomes the authoritative state, and declarative schemas are only in the database if you generated a migration from them first (`lite db diff -f <name>`) |
 | `db pull`, `db dump`, `db lint`, `db advisors` | 🔄 | Not registered                       |
 | `db start`    | 🚫     | Not applicable; in-process, no separate DB start                    |
 
@@ -796,7 +821,7 @@ Mirrors upstream behavior documented in [`internal/docs/cli/environment.md`](htt
 
 | Status                      | Count |
 |-----------------------------|-------|
-| ✅ Implemented               | 25    |
+| ✅ Implemented               | 26    |
 | 🔄 Planned (not registered) | 14    |
 | 🚫 Not Applicable           | 7     |
 
@@ -817,7 +842,8 @@ Mirrors upstream behavior documented in [`internal/docs/cli/environment.md`](htt
 ### Vite plugin scope
 
 - **Active during `vite` / `vite dev` and `vite preview`.** `vite dev` watches `schemas/*.sql` for hot-reload; `vite preview` mounts the API and runs boot migrations but does **not** watch schemas (it simulates production). `vite build` and any standalone production server do **not** mount the API — use a real backend (`lite start`, hosted Supabase, or equivalent) there.
-- **Same-process by design.** The plugin mounts `/auth/v1`, `/rest/v1`, and `/_system` on the Vite dev server. Do not run `lite dev` or `lite start` alongside — both bind the API and will collide on port.
+- **Same-process by design.** The plugin mounts `/auth/v1`, `/rest/v1`, and `/_system` on the Vite dev server. `/storage/v1` is not mounted by default — add it to `prefixes` if you need it. Do not run `lite dev` or `lite start` alongside — both bind the API and will collide on port.
+- **Admin mode on in dev, never in preview.** `vite`/`vite dev` default to `admin: true` (keyless same-origin loopback `/rest/v1` requests run as `service_role`); `configurePreviewServer` forces it off. Override with `supalite({ admin: false })`. See [API Keys](#api-keys).
 - **Env-var injection.** The plugin's `config()` hook injects `VITE_SUPABASE_URL` (the current origin) and a dev `VITE_SUPABASE_ANON_KEY`, so `createClient(import.meta.env.VITE_SUPABASE_URL, import.meta.env.VITE_SUPABASE_ANON_KEY)` works with no `.env`. A user-provided `.env` overrides either value.
 
 ---
@@ -840,9 +866,9 @@ See [UPGRADE.md](https://github.com/supabase-community/lite/blob/HEAD/UPGRADE.md
 
 | Test Suite | Passing           | Skipped     | Failed          | Assertions        | Files          |
 |------------|-------------------|-------------|-----------------|-------------------|----------------|
-| App        | **2,376 passing** | 486 skipped | 0 failed        | 17,538 assertions | 168 test files |
-| App (vitest: node + browser + D1 + DO + KV) | **47 passing** | 0 skipped | 0 failed | — | 5 test files |
-| Repo       | **3,404 passing** | 540 skipped | 0 failed | 31,320 assertions | 173 test files |
+| App        | **2,939 passing** | 486 skipped | 0 failed        | 19,345 assertions | 204 test files |
+| App (vitest: node + browser + D1 + DO + KV) | **65 passing** | 0 skipped | 0 failed | — | 5 test files |
+| Repo       | **3,967 passing** | 540 skipped | 0 failed | 33,127 assertions | 209 test files |
 
 Latest `cd app && bun test`, `cd app && bun run vitest`, and root `bun test --recursive` completed with zero failures.
 
@@ -859,10 +885,10 @@ Auth supabase-spec status (`cd app && bun run test:spec:auth`):
 
 | Backend | Total | Passing | Pass % | Skipped | Skip % | Failed |
 |---------|------:|--------:|-------:|--------:|-------:|-------:|
-| Postgres | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
-| PGlite | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
-| SQLite | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
-| SQLite-Postgres | 488 | **241** | 49.4% | 247 | 50.6% | 0 |
+| Postgres | 488 | **265** | 54.3% | 223 | 45.7% | 0 |
+| PGlite | 488 | **265** | 54.3% | 223 | 45.7% | 0 |
+| SQLite | 488 | **265** | 54.3% | 223 | 45.7% | 0 |
+| SQLite-Postgres | 488 | **265** | 54.3% | 223 | 45.7% | 0 |
 
 ### Methodology
 
@@ -870,7 +896,7 @@ Feature status tables above are validated by ported test suites run against both
 
 **PostgREST (Database API):** 501 test cases extracted from the upstream [PostgREST Haskell test suite](https://github.com/PostgREST/postgrest) into JSON specs (`packages/postgrest-test-suite/`). Verified by running against real PostgREST and PostgreSQL via Docker. All 501 pass against vendor. The same suite runs against lite's implementation on four backends (`postgres`, `pglite`, `sqlite`, `sqlite-postgres`), with skips documented per dialect for known incompatibilities (JSON operators, range types, full-text search locale differences). Run `bun run test:spec:status` in `app/` to regenerate the baseline table. `sqlite-postgres` exercises the deparser path end users hit with `driver: "sqlite-postgres"`.
 
-**Auth (GoTrue):** 51 test cases across 12 spec files (`packages/gotrue-test-suite/`) covering all 11 implemented endpoints. Verified by running against the vendor GoTrue Docker image (v2.186.0) with PostgreSQL + Inbucket (email trap). The same suite runs against lite's auth implementation on both SQLite and PostgreSQL. The upstream `supabase-spec` Auth JSON cases also run against lite's SQLite auth implementation under `app/test/supabase-spec/auth/`; the baseline now unskips passing email/password/refresh/user, error-shape, health/settings/JWKS, response-shape, email side-effect, logout/reauthenticate DB-change, magic-link, email OTP/verify token, refresh rotation, session lifecycle, short JWT-expiry, non-phone config-variant, recovery password-change, and duplicate-signup/form-token response-shape cases. Remaining Auth skips are hard-scoped product areas or non-runnable upstream placeholder rows documented in `app/test/supabase-spec/auth/NON_RUNNABLE_PLACEHOLDERS.md`; there are no current addressable Auth skips. Run `bun run test:spec:auth:analyze` in `app/` to execute all Auth JSON cases and group current mismatch signatures.
+**Auth (GoTrue):** 51 test cases across 12 spec files (`packages/gotrue-test-suite/`) covering the 11 pre-OAuth implemented endpoints; the OAuth `/authorize` and `/callback` endpoints are covered by the supabase-spec cases below, and the PKCE token exchange (`/token?grant_type=pkce`) is covered solely by the focused integration tests in `app/test/auth/oauth-*.test.ts`. Verified by running against the vendor GoTrue Docker image (v2.186.0) with PostgreSQL + Inbucket (email trap). The same suite runs against lite's auth implementation on both SQLite and PostgreSQL. The upstream `supabase-spec` Auth JSON cases also run against lite's SQLite auth implementation under `app/test/supabase-spec/auth/`; the baseline now unskips passing email/password/refresh/user, error-shape, health/settings/JWKS, response-shape, email side-effect, logout/reauthenticate DB-change, magic-link, email OTP/verify token, refresh rotation, session lifecycle, short JWT-expiry, non-phone config-variant, recovery password-change, duplicate-signup/form-token response-shape, and OAuth redirect (github/google authorize, callback error handling, PKCE challenge persistence/validation) cases. The upstream corpus contains no `/token?grant_type=pkce` case, so PKCE code redemption is covered only by `app/test/auth/oauth-flow.test.ts` (authorize -> callback -> token round-trips, verifier mismatch, replay) and `app/test/auth/oauth-concurrency.test.ts` (concurrent redemption races). Remaining Auth skips are hard-scoped product areas (admin API, MFA, phone/SMS, SAML/SSO, anonymous, manual identity linking) or non-runnable upstream placeholder rows documented in `app/test/supabase-spec/auth/NON_RUNNABLE_PLACEHOLDERS.md`; there are no current addressable Auth skips. Run `bun run test:spec:auth:analyze` in `app/` to execute all Auth JSON cases and group current mismatch signatures.
 
 Both test suites are reusable packages exposing `definePostgrestTests()` and `defineAuthTests()`. They accept either a URL (for vendor) or a fetch handler (for direct in-process testing).
 

package/dist/{Connection-D9UUTsjg.d.ts → Connection-ZWTDByQ5.d.ts}

@@ -528,6 +528,18 @@ interface PlanStep {
     sql: string;
     description?: string;
     type?: PlanStepType;
+    /**
+     * Commit the current transaction and begin a new one before running this
+     * step. Set where the planner requires a commit boundary — a statement whose
+     * effect is unusable until its transaction commits, e.g. `ALTER TYPE … ADD
+     * VALUE` followed by anything that uses the new value.
+     *
+     * Execution metadata lives on the step (rather than alongside the plan) so it
+     * survives cloning and JSON round-trips of a `PlanResult`.
+     */
+    newTransaction?: boolean;
+    /** Run this step outside a transaction entirely (e.g. `CREATE INDEX CONCURRENTLY`). */
+    nonTransactional?: boolean;
 }
 interface DataLossWarning {
     table: string;
@@ -640,6 +652,21 @@ declare abstract class Connection<Driver = unknown, DB = any, Config extends ICo
         useCache?: boolean;
     }): Promise<IntrospectResult>;
     transaction(_statements: string[], _opts?: TransactionOptions): Promise<void>;
+    /**
+     * Callback-based transaction API for application code (e.g. AuthRepository)
+     * that needs atomicity across several kysely operations without hand-rolling
+     * BEGIN/COMMIT/ROLLBACK. `fn` is handed a kysely instance bound to the
+     * transaction — use it (not `this.kysely`) for every operation that must
+     * participate.
+     *
+     * Default implementation issues a real BEGIN/COMMIT/ROLLBACK via kysely's
+     * `transaction().execute()`, appropriate for backends where `sql\`BEGIN\``
+     * is meaningful (base sqlite drivers, Postgres). Durable Objects storage
+     * has no such thing — `DoSqliteConnection` overrides this to use
+     * `storage.transaction()` instead, running `fn` against the *same* kysely
+     * instance (see that class for why).
+     */
+    runInTransaction<T>(fn: (trx: Kysely<DB>) => Promise<T>): Promise<T>;
     abstract close(): Promise<void>;
     createMigrator(_desiredSchema: string): ConnectionMigrator;
     onPostgrestAST(ast: AnyAST, _vars?: VarsContext): Promise<AnyAST>;