@supabase/lite 0.9.0 → 0.9.1-next.1

package/dist/vite/index.d.ts

@@ -2168,7 +2168,18 @@ declare function createServer(app: App, options?: ServerOptions): hono_hono_base
             status: hono_utils_http_status.StatusCode;
         };
     };
-}, "/rest/v1"> | hono_types.MergeSchemaPath<hono_types.BlankSchema | hono_types.MergeSchemaPath<{
+}, "/rest/v1"> | hono_types.MergeSchemaPath<(hono_types.BlankSchema | hono_types.MergeSchemaPath<{
+    "/status": {
+        $get: {
+            input: {};
+            output: {
+                status: string;
+            };
+            outputFormat: "json";
+            status: 200;
+        };
+    };
+} & {
     "/object/public/:bucketId/*": {
         $get: {
             input: {
@@ -2626,7 +2637,20 @@ declare function createServer(app: App, options?: ServerOptions): hono_hono_base
             status: 404;
         };
     };
-}, "/">, "/storage/v1"> | hono_types.MergeSchemaPath<{
+}, "/">) & {
+    "*": {
+        $all: {
+            input: {};
+            output: {
+                message: string;
+                error: string;
+                statusCode: number;
+            };
+            outputFormat: "json";
+            status: 404;
+        };
+    };
+}, "/storage/v1"> | hono_types.MergeSchemaPath<{
     "/ping": {
         $get: {
             input: {};

package/docs/auth/email.mdx

@@ -0,0 +1,214 @@
+---
+title: "Email delivery & templates"
+description: "Configure the email driver, verification links, and customizable transactional email templates for Supabase Lite Auth."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Supabase Lite sends the same transactional emails as Supabase (signup confirmation, magic link, password recovery, email change, reauthentication). Out of the box it ships Supabase-styled HTML templates and builds verification links from your `site_url`, so email auth works with zero configuration. Everything is overridable. By default, emails are printed to the server console and nothing is actually delivered until you configure a real driver.
+
+## Local development: the console mail catcher
+
+The default driver, `ConsoleEmailDriver`, requires no configuration: it logs every outgoing email to the server console instead of sending it, so you can develop and test email flows without a mail provider. Each email is printed as `To`, `Subject`, and the rendered plain-text body (the default templates put the OTP code and the confirmation link in that body). HTML is never printed.
+
+```
+[@supabase/lite] email captured (not delivered)
+To: user@example.test
+Subject: Confirm Your Signup
+
+Confirm your signup with this code: 123456
+
+Or follow this link: http://localhost:3000/auth/v1/verify?token=...&type=signup&redirect_to=http%3A%2F%2Flocalhost%3A3000
+```
+
+Grep the server output for `email captured` to find these entries among your other logs.
+
+This is Supabase Lite's equivalent of the Supabase CLI's Mailpit: the CLI runs a local SMTP server and web UI at `localhost:54324` (config section `[inbucket]`) that catches every email your project sends. Lite has no built-in SMTP server or mailbox UI; it prints to the console by default. Point `[auth.email.smtp]` at a real SMTP server (including a local one like Mailpit) to send for real — see [SMTP](#smtp) below. `[inbucket]` is still parsed for compatibility but not acted on: lite never starts a local mailbox service.
+
+Note that `enable_confirmations` under `[auth.email]` defaults to `false`, matching upstream, so signups autoconfirm and no email is sent at all until you turn it on.
+
+To silence the console output, pass `{ silent: true }`; to send it somewhere else (a file, a test spy, structured logging), pass a custom `logger`:
+
+```ts
+import { App, ConsoleEmailDriver } from "@supabase/lite";
+
+const app = new App({
+  connection,
+  auth: { jwt_secret, site_url: "https://app.example.com" },
+  options: {
+    drivers: {
+      email: new ConsoleEmailDriver({ silent: true }),
+      // or: new ConsoleEmailDriver({ logger: { info: (message) => myLogger.info(message) } }),
+    },
+  },
+});
+```
+
+## Verification links
+
+Emailed links point at the auth server's verify endpoint:
+
+```
+{site_url}/auth/v1/verify?token=<hash>&type=<type>&redirect_to=<redirect_to>
+```
+
+`GET /auth/v1/verify` verifies the token server-side and issues a `303` redirect to `redirect_to` (falling back to `site_url` if the target is not allow-listed), with the session in the URL fragment on success or `error`/`error_code` on failure — matching GoTrue. Set `site_url` (and any `additional_redirect_urls`) under `[auth]`:
+
+```toml
+[auth]
+site_url = "https://app.example.com"
+additional_redirect_urls = ["https://app.example.com/welcome"]
+```
+
+The 6-digit numeric code is delivered in the same email and verified against the database, so both `verifyOtp({ token_hash })` and `verifyOtp({ email, token })` work with any driver and across isolates.
+
+## SMTP
+
+Unlike the other drivers, SMTP can be configured directly in `config.toml` — matching `supabase start`, which wires `GOTRUE_SMTP_*` from the same section. Set `enabled = true` and lite auto-selects `SmtpEmailDriver`, no `options.drivers.email` needed:
+
+```toml
+[auth.email.smtp]
+enabled = true
+host = "localhost"
+port = 1025
+user = "apikey"
+pass = "env(SMTP_PASSWORD)"
+admin_email = "admin@example.com"
+sender_name = "My App"
+```
+
+`host`, `port`, `user`, `pass`, and `admin_email` are all required when `enabled = true` — matching the upstream `supabase` CLI's own validation. The app throws a clear config error at startup otherwise: `Missing required field in config: auth.email.smtp.<field>`. That example points at [Mailpit](https://mailpit.axllent.org/) running locally (`docker run -p 1025:1025 -p 8025:8025 axllent/mailpit`); open `http://localhost:8025` for the mailbox UI (Mailpit accepts any user/pass).
+
+`SmtpEmailDriver` is also available for programmatic construction, same as the other bundled drivers:
+
+```ts
+import { App, SmtpEmailDriver } from "@supabase/lite";
+
+const app = new App({
+  connection,
+  auth: { jwt_secret, site_url: "https://app.example.com" },
+  options: {
+    drivers: {
+      email: new SmtpEmailDriver({
+        host: "smtp.sendgrid.net",
+        port: 587,
+        user: "apikey",
+        pass: process.env.SENDGRID_API_KEY!,
+        from: "auth@example.com",
+      }),
+    },
+  },
+});
+```
+
+`SmtpEmailDriver` sends via [Nodemailer](https://nodemailer.com/). TLS behavior follows Nodemailer's own options: implicit TLS on port `465` (`secure` defaults to `port === 465`), opportunistic `STARTTLS` otherwise. When credentials (`user`/`pass`) are configured and the connection isn't already implicit-TLS, `requireTls` defaults to `true` — the driver fails instead of sending credentials over a plaintext connection when `STARTTLS` isn't offered. Pass `requireTls: false` to opt back into best-effort `STARTTLS`, or `rejectUnauthorized: false` to accept a self-signed certificate. Config-driven SMTP (`[auth.email.smtp]`) always has credentials (they're required), so it always requires TLS by default.
+
+`from` (and the programmatic driver's `from` option) accepts either a plain address string or a structured `{ name, address }` object; Nodemailer encodes the display name safely, so names containing quotes or non-ASCII characters round-trip correctly in the generated MIME. `sender_name` in `config.toml` is passed through this way automatically.
+
+`SmtpEmailDriver` requires Node or Bun (Nodemailer needs `node:net`/`node:tls`). It is not supported on Cloudflare Workers or in the browser — `send()` throws `SMTP email is not supported in this runtime (SmtpEmailDriver requires Node or Bun)` there.
+
+<Aside type="caution">
+Explicit `options.drivers.email` always wins over `[auth.email.smtp]`, even when `enabled = true`. `enabled` is a plain boolean and defaults to its zero value, `false`: an `[auth.email.smtp]` section present in `config.toml` without `enabled = true` (or with it explicitly `false`) behaves exactly like no section at all — `ConsoleEmailDriver` is used.
+</Aside>
+
+## Choosing an email driver
+
+The default driver is `ConsoleEmailDriver` (see [Local development](#local-development-the-console-mail-catcher) above), which only logs emails to the console. Real drivers (`Resend`, `AWS SES`, `Sendmail`, `SMTP`) ship with the library and are injected programmatically when you construct the app:
+
+```ts
+import { App, ResendEmailDriver } from "@supabase/lite";
+
+const app = new App({
+  connection,
+  auth: {
+    jwt_secret,
+    site_url: "https://app.example.com",
+    email: { enable_confirmations: true },
+  },
+  options: {
+    drivers: {
+      email: new ResendEmailDriver({
+        apiKey: process.env.RESEND_API_KEY!,
+        from: "auth@example.com",
+      }),
+    },
+  },
+});
+```
+
+`AwsSesEmailDriver`, `SendmailEmailDriver`, and `SmtpEmailDriver` (see [SMTP](#smtp) above) are available from the same entry point. Any object implementing `send({ to, subject, text, html })` works as a custom driver.
+
+## Bring your own provider
+
+If none of the bundled drivers fit, implement `EmailDriver` yourself. It needs one method, `send({ to, subject, text, html })`:
+
+```ts
+import type { EmailDriver } from "@supabase/lite";
+
+class MyApiEmailDriver implements EmailDriver {
+  async send({ to, subject, text, html }: {
+    to: string; subject: string; text?: string; html?: string;
+  }) {
+    await fetch("https://api.my-email-provider.test/v1/send", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${process.env.MY_EMAIL_API_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ to, subject, text, html }),
+    });
+  }
+}
+```
+
+Custom drivers are always injected via `options.drivers.email` when constructing the `App`, the same as the bundled drivers above. SMTP is the one exception: it also auto-selects from `[auth.email.smtp]` in `config.toml` (see [SMTP](#smtp)), though an explicit `options.drivers.email` still wins over it.
+
+## OTP length and expiry
+
+```toml
+[auth.email]
+otp_length = 6      # digits in the emailed code
+otp_expiry = 3600   # seconds before the code / link expires (default 1 hour)
+```
+
+Expiry is enforced in `verifyOtp` against the token's `*_sent_at` timestamp; an expired code returns `otp_expired`.
+
+## Secure email change
+
+When a user changes their email, `double_confirm_changes` (default `true`) controls how the change is confirmed:
+
+- **`true` (secure):** the confirmation that finalizes the change is delivered to the **current** address and hashed with it. Confirming it changes the account email. A token delivered to the pending new address cannot finalize the change on its own.
+- **`false` (insecure):** the confirmation is sent to the new address and confirming it finalizes the change immediately.
+
+<Aside type="caution">
+Supabase Lite's secure email change is **partial**: it confirms from the current mailbox before finalizing (so a stolen session cannot move the account email to an attacker's mailbox using only that mailbox), but it does **not** implement GoTrue's full two-mailbox flow that requires *both* the old and new addresses to confirm before the change takes effect. The current-email confirmation alone finalizes. See [LIMITATIONS.md](https://github.com/supabase-community/lite/blob/main/LIMITATIONS.md).
+</Aside>
+
+## Customizing templates
+
+Override the subject and HTML per email type under `[auth.email.template.<type>]`, where `<type>` is one of `invite`, `confirmation`, `recovery`, `magic_link`, `email_change`:
+
+```toml
+[auth.email.template.confirmation]
+subject = "Confirm your account"
+content_path = "./emails/confirmation.html"
+```
+
+Templates use the same Go-template variables as upstream GoTrue, so existing Supabase templates work unchanged:
+
+| Variable | Description |
+|---|---|
+| `{{ .ConfirmationURL }}` | Full verification link (see above) |
+| `{{ .Token }}` | The numeric OTP code |
+| `{{ .TokenHash }}` | The hashed token used in the link |
+| `{{ .SiteURL }}` | Configured `site_url` |
+| `{{ .Email }}` | Recipient email |
+| `{{ .NewEmail }}` | New address (email change) |
+| `{{ .RedirectTo }}` | Post-verification redirect target |
+| `{{ .Data }}` | User metadata |
+
+<Aside type="caution">
+`content_path` is read from the filesystem, so it is available on Node and the CLI but not in browser or Cloudflare Workers bundles. On those runtimes the built-in default templates are used (or inline your HTML another way). Zero-config defaults work everywhere.
+</Aside>
+
+When no `content_path` is set, the built-in Supabase-styled default template for that type is used.

package/docs/auth/not-supported.mdx

@@ -0,0 +1,57 @@
+---
+title: "Auth: not supported"
+description: "Anonymous sign-in, manual identity linking, the admin API, MFA, and OAuth providers beyond github/google are not implemented yet. What's planned vs. not planned, and the hosted-Supabase workaround."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+These gaps are backend-independent: they're missing regardless of whether you run SQLite, PGlite, or Postgres. Auth doesn't have the SQLite-vs-Postgres split the Data API has. Nothing here is a SQLite platform limitation; it's just not built yet.
+
+<Aside type="caution">
+If your app needs any of the flows below today, run it against hosted Supabase instead of Supabase Lite, or gate the feature until it lands.
+</Aside>
+
+<Aside type="note">
+`signInWithOAuth()` / `exchangeCodeForSession()` are implemented for the `github` and `google` providers (PKCE + implicit flows, automatic account linking on a verified-email match). See [Supported flows](/auth/supported-flows). Enabling any other configured provider, including `apple`, returns "provider ... is not yet implemented" — that gap is tracked below.
+</Aside>
+
+## Planned
+
+Config schema or partial groundwork exists; these are the next Auth surfaces on the roadmap.
+
+| Method | Upstream doc | Notes |
+|---|---|---|
+| `signInWithOAuth()` / `exchangeCodeForSession()` for other providers | [Social login](https://supabase.com/docs/guides/auth/social-login) | Config schema exists for the remaining 16 providers (incl. Apple); `github`/`google` already work |
+| `signInAnonymously()` | [Anonymous sign-ins](https://supabase.com/docs/guides/auth/auth-anonymous) | Create an anonymous session |
+| `linkIdentity()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Manually link an OAuth identity to an existing user; automatic linking on OAuth sign-in already works |
+| `unlinkIdentity()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Remove a linked identity |
+| `admin.createUser()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Direct user creation, skips confirmation |
+| `admin.listUsers()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Paginated user list |
+| `admin.getUserById()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Fetch user by ID |
+| `admin.updateUserById()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Direct user update |
+| `admin.deleteUser()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | User deletion |
+| `admin.inviteUserByEmail()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Send an invite |
+| `admin.generateLink()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Generate verification/reset links |
+| `admin.signOut()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) | Admin-initiated logout |
+| `admin.mfa.listFactors()` | [Auth MFA](https://supabase.com/docs/guides/auth/auth-mfa) | List a user's MFA factors |
+| `admin.mfa.deleteFactor()` | [Auth MFA](https://supabase.com/docs/guides/auth/auth-mfa) | Remove an MFA factor |
+
+## Not currently planned
+
+No implementation work scheduled. Reach for hosted Supabase if you need these.
+
+| Area | Methods | Upstream doc |
+|---|---|---|
+| MFA / TOTP | `mfa.enroll()`, `mfa.challenge()`, `mfa.verify()`, `mfa.challengeAndVerify()`, `mfa.unenroll()`, `mfa.listFactors()`, `mfa.getAuthenticatorAssuranceLevel()` | [Auth MFA](https://supabase.com/docs/guides/auth/auth-mfa) |
+| WebAuthn | `mfa.webauthn.*` (5 methods) | [Auth MFA](https://supabase.com/docs/guides/auth/auth-mfa) |
+| SSO/SAML | `signInWithSSO()` | [Auth guide](https://supabase.com/docs/guides/auth) |
+| Web3 | `signInWithWeb3()` | [Auth guide](https://supabase.com/docs/guides/auth) |
+| OIDC | `signInWithIdToken()` | [Auth guide](https://supabase.com/docs/guides/auth) |
+| OAuth server | `oauth.getAuthorizationDetails()`, `oauth.approveAuthorization()`, `oauth.denyAuthorization()`, `oauth.listGrants()`, `oauth.revokeGrant()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) |
+| OAuth admin | `oauth.listClients()`, `oauth.createClient()`, `oauth.getClient()`, `oauth.updateClient()`, `oauth.deleteClient()`, `oauth.regenerateClientSecret()` | [Auth admin API](https://supabase.com/docs/reference/javascript/auth-admin-api) |
+
+## Related schema gaps
+
+Because the OAuth 2.1 authorization server/admin surface and MFA aren't implemented, the underlying `auth.*` tables for those features (`auth.mfa_factors`, `auth.sso_providers`, `auth.oauth_clients`, and similar) also aren't reconciled against upstream. `auth.flow_state`, used by the implemented social-login PKCE flow, is reconciled.
+
+For what does work today, see [Supported flows](/auth/supported-flows). For the general Auth model these gaps sit on top of, see the [Supabase Auth docs](https://supabase.com/docs/guides/auth).

package/docs/auth/overview.mdx

@@ -0,0 +1,52 @@
+---
+title: "Auth overview"
+description: "GoTrue-compatible Auth API for @supabase/lite: what's implemented, what's planned, and how it fits into supabase-js."
+---
+
+import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
+
+Supabase Lite ships a GoTrue-compatible Auth API at `/auth/v1/*`. For the methods it implements, `@supabase/supabase-js`'s `auth` client works unchanged: same request shapes, same JWT format, same session/refresh-token behavior.
+
+<Aside type="note">
+Auth support is capability-independent of the database backend. The same 13 endpoints work identically on SQLite, PGlite, and Postgres, since Auth is not a Postgres-vs-SQLite translation problem the way the Data API is. One exception: on the Cloudflare 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 auth-code/state reuse. All other backends, including Durable Objects, are fully transactional.
+</Aside>
+
+## Coverage
+
+13 of 63 `supabase-js` auth methods are implemented as real backend endpoints, including OAuth sign-in for `github` and `google` (PKCE + implicit flows, automatic account linking). Of the remaining 50: 13 are planned (other OAuth providers incl. Apple, anonymous sign-in, manual identity linking, the admin API), 27 are not currently planned (MFA, SSO, Web3, OAuth-server), and 10 are client-side-only helpers that need no backend (`getSession`, `onAuthStateChange`, and similar) and already work as-is since they don't hit the network.
+
+<CardGrid>
+  <Card title="Supported flows">
+    Email/password, OTP, sessions, password recovery, OAuth sign-in (github/google): the 13 implemented endpoints with examples. [Read more →](/auth/supported-flows/)
+  </Card>
+  <Card title="Not supported">
+    Other OAuth providers, anonymous sign-in, admin API, MFA: what's missing and the hosted-Supabase workaround. [Read more →](/auth/not-supported/)
+  </Card>
+  <Card title="Email delivery & templates">
+    The console mail catcher, choosing a real email driver, verification links, and customizable templates. [Read more →](/auth/email/)
+  </Card>
+</CardGrid>
+
+## API keys
+
+Supabase Lite issues opaque `sb_publishable_*` / `sb_secret_*` keys, matching Supabase's current key format — generated per project, never hardcoded. `lite init` generates any missing key(s) into root `.env` (`SUPABASE_PUBLISHABLE_KEY` / `SUPABASE_SECRET_KEY`, per-variable — an existing one is never overwritten) and wires `config.toml`'s `auth.publishable_key` / `auth.secret_key` to reference them via `env(VAR)` (same field names as the upstream `supabase` CLI). `lite generate-keys` (re)generates the whole pair; `lite start`/`lite dev` print the resolved keys.
+
+`sb_publishable_*` authenticates as `anon`, `sb_secret_*` as `service_role` (bypasses RLS, including on SQLite). Enforcement on `/rest/v1` and `/auth/v1` is opt-in: it activates once at least one key is configured — an unconfigured key simply never matches, and an unconfigured project keeps the old behavior (any/no `apikey` accepted). Keys must arrive via the `apikey` header or `?apikey=` query param (what `supabase-js` sends automatically); a key sent only via `Authorization` is rejected, matching upstream self-hosted conformance. A real user session JWT in `Authorization` always outranks the API key. A secret key rejected from a browser `User-Agent` mirrors the hosted gateway's browser guard. Legacy JWT-as-apikey (the old `ANON_KEY`/`SERVICE_ROLE_KEY` HS256 tokens) is not supported.
+
+`/storage/v1` is transform-only, like upstream self-hosted Kong: it never 401s on a missing/invalid key (public objects, signed URLs, and S3 presigned flows stay keyless), but a secret key still satisfies storage's own authed routes as `service_role`.
+
+The OpenAPI root (`GET /rest/v1/`) requires the secret key, mirroring upstream's admin-only ACL on that route: a publishable key gets 403, the secret key gets 200.
+
+There is one exception to enforcement, and it only exists locally: [admin mode](/running#admin-mode). `lite dev` and `lite start` serve keyless `/rest/v1` and `/storage/v1` requests as `service_role`, so the browser studio can do admin work without a secret key shipping to the browser (which the browser guard would reject anyway). The Vite dev server does the same for `/rest/v1`; it does not mount `/storage/v1` unless you add it to the plugin's `prefixes`. Only same-origin requests on a loopback socket **and** a loopback hostname are elevated — that pairing is what blocks both LAN peers spoofing `Host` and DNS rebinding — and any request carrying a key or an `Authorization` header keeps its normal role. Turn it off with `--no-admin`; it is off by default for embedders and in `vite preview`.
+
+Embedders using the `App` class directly can disable enforcement (`options.server.apiKeys: false`) or supply a custom resolver (`options.server.apiKeys.resolver`); `app.getClient()` defaults to the configured publishable key. See `STATUS.md` (`#api-keys`) in the installed package for the full behavior matrix.
+
+## What's shared with the Data API
+
+Auth issues the JWTs that Row Level Security reads. `auth.uid()`, `auth.role()`, and `auth.jwt()` in your RLS policies resolve from the same token this Auth API signs, on every backend. See [Database: RLS](/database/rls) for how policies consume these claims, and [Database backends](/database/backends) for switching between SQLite, PGlite, and Postgres.
+
+<Aside type="note">
+This page tracks capability-level rollups. The package installed in your project ships an exact method-by-method matrix in `STATUS.md` that updates every `npm install`. Treat that file as the source of truth for exact counts. See also [Compatibility](/compatibility).
+</Aside>
+
+For the Auth concepts that behave identically to upstream (JWT structure, session lifecycle, GoTrue's general model), see the [Supabase Auth docs](https://supabase.com/docs/guides/auth).

package/docs/auth/supported-flows.mdx

@@ -0,0 +1,120 @@
+---
+title: "Supported auth flows"
+description: "The 13 GoTrue-compatible Auth endpoints Supabase Lite implements, with supabase-js examples."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Each method below hits a real backend endpoint at `/auth/v1/*` and behaves like upstream GoTrue for the cases it covers. Session issuance, refresh-token rotation (with reuse detection and revocation), and password hashing are all implemented, not stubbed.
+
+| `supabase-js` method | Endpoint | Notes |
+|---|---|---|
+| [`signUp()`](https://supabase.com/docs/reference/javascript/auth-signup) | `POST /signup` | Email/password, optional metadata, email confirmation |
+| [`signInWithPassword()`](https://supabase.com/docs/guides/auth/passwords) | `POST /token?grant_type=password` | Returns JWT + refresh token |
+| [`signInWithOtp()`](https://supabase.com/docs/guides/auth/auth-email-otp) | `POST /otp` | Magic link / OTP via email |
+| [`verifyOtp()`](https://supabase.com/docs/reference/javascript/auth-verifyotp) | `POST /verify` | signup, magiclink, recovery, email_change, reauthentication. Both the numeric code (`{ email, token }`) and the link's `token_hash` verify against the DB |
+| [`refreshSession()`](https://supabase.com/docs/reference/javascript/auth-refreshsession) | `POST /token?grant_type=refresh_token` | Token rotation, immediate-reuse compatibility, session expiry checks |
+| [`signOut()`](https://supabase.com/docs/reference/javascript/auth-signout) | `POST /logout` | Scopes: `local`, `global`, `others` |
+| [`getUser()`](https://supabase.com/docs/reference/javascript/auth-getuser) | `GET /user` | JWT-authenticated |
+| [`updateUser()`](https://supabase.com/docs/reference/javascript/auth-updateuser) | `PUT /user` | Metadata, password, email change |
+| [`resetPasswordForEmail()`](https://supabase.com/docs/reference/javascript/auth-resetpasswordforemail) | `POST /recover` | Password reset email (client method wraps the `recover` endpoint) |
+| [`resend()`](https://supabase.com/docs/reference/javascript/auth-resend) | `POST /resend` | Resend confirmation / email change |
+| [`reauthenticate()`](https://supabase.com/docs/reference/javascript/auth-reauthenticate) | `GET /reauthenticate` | Request a reauthentication nonce |
+| [`signInWithOAuth()`](https://supabase.com/docs/guides/auth/social-login) | `GET /authorize` | `github` and `google` only; redirects into the provider's consent screen (PKCE or implicit flow) |
+| [`exchangeCodeForSession()`](https://supabase.com/docs/reference/javascript/auth-exchangecodeforsession) | `GET`/`POST /callback`, `POST /token?grant_type=pkce` | Completes the OAuth handshake; automatic account linking when the provider email matches an existing verified user |
+
+## Email/password
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+
+const supabase = createClient("http://localhost:54321", "<anon-key>");
+
+await supabase.auth.signUp({
+  email: "user@example.com",
+  password: "correct-horse-battery-staple",
+});
+
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: "user@example.com",
+  password: "correct-horse-battery-staple",
+});
+// data.session.access_token is a JWT; RLS policies read auth.uid() from it.
+```
+
+## Email OTP / magic link
+
+```ts
+await supabase.auth.signInWithOtp({ email: "user@example.com" });
+
+// after the user receives the code/link:
+const { data, error } = await supabase.auth.verifyOtp({
+  email: "user@example.com",
+  token: "123456",
+  type: "email",
+});
+```
+
+The 6-digit code is emailed and verified against the database, so it works with any email driver and across isolates (e.g. Cloudflare Workers) — no in-memory state. Emailed links point at `GET /auth/v1/verify`, which verifies the token and redirects to your `redirect_to`. See [Email delivery & templates](/auth/email) to configure the sender, subjects, and HTML.
+
+<Aside>
+Set `[auth.email] enable_confirmations = false` in `config.toml` for local dev so `signUp()` returns an active session immediately instead of waiting on a confirmation email.
+</Aside>
+
+## OAuth / social sign-in
+
+Both the authorization-code (PKCE) and implicit flows are supported. Which one you get depends on the client's `flowType`, which `supabase-js` defaults to `"implicit"` — set `flowType: "pkce"` explicitly to opt into PKCE.
+
+### Implicit (the `supabase-js` default)
+
+```ts
+const supabase = createClient("http://localhost:54321", "<anon-key>");
+// flowType defaults to "implicit"
+
+await supabase.auth.signInWithOAuth({ provider: "github" });
+// or provider: "google"
+
+// the redirect back to your `redirect_to` URL carries the session in the
+// fragment (`#access_token=...`); supabase-js reads it automatically via
+// `detectSessionInUrl` (also on by default) — do not call
+// `exchangeCodeForSession()` here.
+```
+
+### PKCE, handled automatically
+
+With `flowType: "pkce"` and the default `detectSessionInUrl: true`, the browser client redeems the `?code=...` param itself as soon as the callback page loads. This is the path to use in a browser app — no exchange call of your own:
+
+```ts
+const supabase = createClient("http://localhost:54321", "<anon-key>", {
+  auth: { flowType: "pkce" },
+});
+
+await supabase.auth.signInWithOAuth({ provider: "github" });
+
+// on the redirect back, supabase-js exchanges the `?code=...` param and stores
+// the session; just wait for it:
+const { data } = await supabase.auth.getSession();
+```
+
+### PKCE, exchanged manually
+
+Only call `exchangeCodeForSession()` yourself when you own the callback handling — a server-side route, or a custom client flow. Turn detection off on that client, otherwise it races your call and one of the two attempts fails against the single-use code:
+
+```ts
+const supabase = createClient("http://localhost:54321", "<anon-key>", {
+  auth: { flowType: "pkce", detectSessionInUrl: false },
+});
+
+await supabase.auth.signInWithOAuth({ provider: "github" });
+
+// the redirect back to your `redirect_to` URL carries a `?code=...` query param:
+const { data, error } = await supabase.auth.exchangeCodeForSession(code);
+```
+
+<Aside>
+Auth codes are single-use. Never combine `detectSessionInUrl: true` with your own `exchangeCodeForSession()` call — the second redemption fails. And calling `exchangeCodeForSession(code)` against an implicit-flow redirect fails outright: there's no `?code` param, only fragment tokens. Match the exchange call to the client's configured `flowType`.
+</Aside>
+
+Only `github` and `google` are implemented; enabling any other configured provider (including `apple`) returns "provider ... is not yet implemented". If a provider's email matches an existing verified user, the identity is linked to that account automatically — there's no separate `linkIdentity()` step for this case. See [Not supported](/auth/not-supported) for the providers and manual linking gaps.
+
+For everything these flows behave identically to upstream on (JWT claims shape, GoTrue error codes, cookie/session storage on the client), see the [Supabase Auth guide](https://supabase.com/docs/guides/auth), [password auth](https://supabase.com/docs/guides/auth/passwords), [email OTP](https://supabase.com/docs/guides/auth/auth-email-otp), and [social login](https://supabase.com/docs/guides/auth/social-login) docs. For what's missing, see [Not supported](/auth/not-supported).

package/docs/cli/overview.mdx

@@ -0,0 +1,112 @@
+---
+title: "CLI overview"
+description: "The lite CLI versus the supabase CLI: parity, gaps, and what's still experimental."
+---
+
+import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The `lite` CLI is a small, in-process CLI for local Supabase Lite projects. It mirrors the shape of the upstream [Supabase CLI](https://supabase.com/docs/reference/cli/introduction) (command names, `supabase/` layout, `config.toml` format) but implements only what Supabase Lite needs: there is no Docker stack, no shadow database, and no diff-engine orchestration behind it.
+
+<Aside type="note">
+Command names are aligned to `supabase` CLI v2.98.2. Lite-only commands (`dev`, `repl`, `debug`, `upgrade`) have no upstream equivalent.
+</Aside>
+
+## Install
+
+Install globally to expose the `lite` binary system-wide:
+
+<Tabs sync="pkg-manager">
+<TabItem label="bun">
+```bash
+bun add -g @supabase/lite
+```
+</TabItem>
+<TabItem label="npm">
+```bash
+npm install -g @supabase/lite
+```
+</TabItem>
+<TabItem label="pnpm">
+```bash
+pnpm add -g @supabase/lite
+```
+</TabItem>
+</Tabs>
+
+Or install per-project and run it through your package manager's runner (`bunx lite <cmd>`, `npx lite <cmd>`, `pnpm exec lite <cmd>`).
+
+## Parity table
+
+| Command | lite | supabase | Notes |
+|---|---|---|---|
+| `init` | Yes | Yes | Scaffolds `supabase/` (config, schema, seed, data dir); generates any missing API key(s) into `.env`. Flags differ from upstream. |
+| `generate-keys` | Yes (lite-only) | No | (Re)generates the publishable/secret API key pair and upserts `.env`. |
+| `dev` | Yes (lite-only) | No | Starts the server and watches `schemas/*.sql`, auto-applying on change. Scaffolds the project first if `supabase/` is absent, so it works in an empty directory. |
+| `start` | Yes | Yes | In-process, no watch, no auto-migrate. Requires `lite init` first: upstream runs without a `config.toml`, but lite is code-first and has no Studio to build a schema in an empty database. No Docker stack flags (`-x`, `--ignore-health-check`). |
+| `stop` | No | Yes | Not registered. There's no long-running Docker stack to stop. |
+| `repl` | Yes (lite-only) | No | Interactive REPL with `app`, `client`, `conn`, `db` in scope. |
+| `debug` | Yes (lite-only) | No | Dumps runtime/config info. |
+| `upgrade` | Yes (lite-only) | No | Migrates a Supabase Lite project to hosted or local Supabase. See [Upgrade](/upgrade). |
+| `bootstrap` | No | Yes | Not planned; starter-template scaffolding stays with the upstream CLI. |
+| `db schema` | Yes (lite-only) | No | Prints current DB schema; `--diff` compares against `schemas/*.sql`. |
+| `db diff` | Yes | Yes | Emits a pg-DDL migration from the declarative schema diff. `--local` semantics only, single engine (no migra/pg-delta/pgAdmin choice, no shadow DB). |
+| `db query` | Yes | Yes (as `db query`, previously top-level `exec`) | Runs a SQL statement, from an argument or stdin, against the local DB; splits multi-statement input. Suppresses CLI chrome by default so it's pipeable (`--verbose` prints chrome to stderr). Supports `--remote` and `--config`. |
+| `db translate` | Yes (lite-only) | No | Translate Postgres SQL to the backend dialect (arg or stdin). Composes with `db query` via a pipe. |
+| `db reset` | Yes | Yes | Drops everything, replays migrations, runs seed. Does not apply declarative `schema_paths`. |
+| `db push` | No | Yes | Not registered; use `lite cloud deploy` (experimental) instead. |
+| `db pull` | No | Yes | Not registered. |
+| `db dump` | No | Yes | Not registered. |
+| `db lint` | No | Yes | Not registered. |
+| `db advisors` | No | Yes | Not registered. |
+| `db start` | No | Yes | Not applicable; there's no separate DB process to start. |
+| `migration new` | Yes | Yes | Creates an empty migration file in `supabase/migrations/`. |
+| `migration up` | Yes | Yes (as `migration up`, no direct upstream verb of the same name for local apply) | Applies pending migrations; `--dry-run` previews without applying. |
+| `migration list` | Yes | Yes | Shows applied vs. pending migrations. |
+| `migration down` | No | Yes | Not registered. |
+| `migration repair` | No | Yes | Not registered. |
+| `migration squash` | No | Yes | Not registered. |
+| `migration fetch` | No | Yes | Not registered. |
+| `login` / `logout` | Experimental | Yes | Email/password against Supabase Lite cloud, not the Supabase Management API. |
+| `link` / `unlink` | Experimental | Yes | Parity at the verb level; `link` has no `--password`/`--skip-pooler`. |
+| `status` | Experimental | Yes | Shows linked project metadata, not Docker container status. |
+| `signup` / `whoami` | Experimental (lite-only) | No | Register/inspect a Supabase Lite cloud account. |
+| `cloud deploy` | Experimental (lite-only) | No | Pushes schema/config/seed to a linked Supabase Lite cloud project (renamed from `push`). |
+| `cloud diff` | Experimental (lite-only) | No | Diffs local against the linked remote. |
+| `projects list` / `create` | Experimental | Yes | Flags differ (no `--org-id`/`--region`). |
+| `projects api-keys` / `delete` | No | Yes | Not registered. |
+| `functions *` | No | Yes | Edge Functions are not implemented yet. |
+| `gen types` / `gen signing-key` | No | Yes | Not implemented yet. |
+| `seed buckets` | No | Yes | Depends on Storage RLS/role support landing first. |
+| `test db` / `test new` | No | Yes | Not applicable on SQLite (no pgTAP). |
+| `services` | No | Yes | Not applicable; there's no Docker stack to list. |
+| Management API groups (`orgs`, `secrets`, `branches`, `domains`, `sso`, `backups`, `snippets`, `postgres-config`, `network-*`, `encryption`, `inspect`, `storage`, `telemetry`) | No | Yes | Deferred; none registered, to keep `--help` output clean. Re-evaluated as Supabase Lite cloud grows a matching surface. |
+
+## What's missing, in one place
+
+If you're coming from the `supabase` CLI, these upstream capabilities have no lite equivalent today:
+
+- **Docker-backed commands**: `stop`, `db start`, `services`. There's no container stack.
+- **`db` toolbox**: `push`, `pull`, `dump`, `lint`, `advisors` are not registered.
+- **`migration` toolbox**: `down`, `repair`, `squash`, `fetch` are not registered.
+- **`functions`**: Edge Functions aren't implemented.
+- **`gen`**: no type generation yet.
+- **`seed buckets`, `bootstrap`, `test db`/`test new`**: not planned or blocked on other features.
+- Every Management API group (`orgs`, `secrets`, `branches`, `sso`, `backups`, `snippets`, `postgres-config`, `network-*`, `encryption`, `inspect`, `storage`, `telemetry`): deferred pending Supabase Lite cloud.
+
+## Experimental commands
+
+`login`, `logout`, `status`, `link`, `unlink`, `signup`, `whoami`, the `cloud` group, and `projects list`/`create` are gated behind Supabase Lite's own experimental flag and talk to **Supabase Lite cloud**, not the Supabase Management API. They print an experimental warning when run. Treat them as unstable: names and flags may change before 1.0.
+
+## Common flags
+
+```bash
+lite init --pglite                      # scaffold with PGlite instead of SQLite
+lite db reset --hard                    # delete the DB file, replay migrations + seed
+lite db schema --diff                   # diff current DB vs schemas/*.sql
+lite db schema --sql                    # print raw CREATE statements
+lite db diff -f tweak                   # emit a migration from the schema diff
+cat supabase/seed.sql | lite db translate | lite db query   # translate + apply ad-hoc SQL
+lite db query "select count(*) from todos"
+```
+
+See [Migrations](/database/migrations) for the migration workflow and [Database backends](/database/backends) for `--pglite`/driver selection. For the full upstream command reference, see the [Supabase CLI reference](https://supabase.com/docs/reference/cli/introduction).

package/docs/cli/telemetry.mdx

@@ -0,0 +1,34 @@
+---
+title: "Telemetry"
+description: "The lite CLI sends anonymous usage telemetry by default. How to disable it."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The `lite` CLI sends anonymous usage telemetry by default, to help prioritize fixes and features.
+
+<Aside type="note">
+No personally identifiable information is collected: no file paths, project names, DB URLs, env values, hostnames, IPs, or stack traces.
+</Aside>
+
+What's collected: the command name, which CLI flags were present (boolean presence only, never values), runtime (`node`/`bun`/`deno`), Node version, platform/arch, CI/agent/container detection, DB driver (`sqlite`/`sqlite-postgres`/`pglite`/`postgres`), DB location (`file`/`memory`/`local`/`remote`), and a DB size bucket.
+
+## Opt out
+
+Any of these disables telemetry:
+
+```bash
+lite --no-telemetry <cmd>
+```
+
+```bash
+LITE_TELEMETRY=0 lite <cmd>
+```
+
+```bash
+DO_NOT_TRACK=1 lite <cmd>
+```
+
+`DO_NOT_TRACK` follows the [consoledonottrack.com](https://consoledonottrack.com) convention, so it also applies if you already set it globally to opt out of telemetry across other CLIs.
+
+This is a Supabase Lite-specific concern with no direct upstream page; see the [Supabase CLI reference](https://supabase.com/docs/reference/cli/introduction) for the CLI it mirrors.