@exposify/supabase 0.3.7 → 0.3.9

package/README.md

@@ -26,10 +26,7 @@ From your Supabase project's root (the directory containing `supabase/`):
 npx exposify-supabase init
 ```
 
-This is safe to re-run — it never overwrites an existing function file, and
-never scaffolds a second copy of the migration if one's already there
-(checked by filename, not content: migrations are meant to be immutable
-once written, so a re-run skips rather than rewrites). It writes:
+This is safe to re-run; see "Re-running `init`" below. It writes:
 
 - `supabase/migrations/<timestamp>_exposify_meta.sql` — a SQL migration that
   adds `exposify_meta()`, a `SECURITY DEFINER` function returning, per table,
@@ -37,8 +34,10 @@ once written, so a re-run skips rather than rewrites). It writes:
   you've written. It only ever returns catalog metadata (table/column names,
   flags, comments) — never row data — which is what makes it safe to grant
   to `anon`/`authenticated` and call with a low-privilege key.
-- `supabase/functions/mcp/index.ts` — the edge function itself, a few lines
-  around `aiReady()`.
+- `supabase/functions/mcp/index.ts` — the edge function itself. `init` owns
+  the part between `// exposify:begin` and `// exposify:end` (imports and a
+  `generated` options object). Everything after that is yours, starting with
+  `Deno.serve(aiReady({ ...generated, /* your options */ }))`.
 - `supabase/functions/mcp/docs/` — an empty directory for optional bundled
   docs (see "Knowledge base" below).
 
@@ -101,36 +100,84 @@ you to hand-edit `writes`/`rpc`/comments yourself:
    worth doing even for tables you're not granting writes on, since it's
    the only thing that makes read tools self-explanatory to an agent.
 
-If `supabase/functions/mcp/index.ts` already exists, none of this touches
-it — your selections are printed as a config snippet to merge in by hand
-instead, and the documentation migration still gets written either way.
-Connects using `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` (env vars or
-`--url`/`--key` flags — **the service role key, not the anon key**; see the
-note on introspection below) — without those, `init` can't reach anything to
-introspect and falls back to the fixed scaffold-and-ask-to-deploy flow above,
-same as before this wizard existed.
+On a re-run, each question starts from what's already configured; see
+"Re-running `init`" below.
+
+To reach the project, `init` needs its URL and **service role key (not the
+anon key)**; see the note on introspection below. It looks in this order:
+
+1. `--url`/`--key` flags.
+2. `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` env vars. A flag beats its env
+   var, so a value left in your shell can't override what you typed.
+3. The Supabase CLI, if it's on your `PATH`:
+   - a running local stack: `supabase status` (`API_URL` +
+     `SERVICE_ROLE_KEY`, or the newer `SECRET_KEY`);
+   - the linked project: the ref in `supabase/.temp/project-ref`, keys from
+     `supabase projects api-keys --reveal`. This needs `supabase login`.
+
+   If both exist, `init` asks which one to use. `--local`/`--linked`
+   skips the question. Without a terminal to ask in, it uses the linked
+   project, because that's where `functions deploy` sends the function.
+
+It prints which source it used. The key stays in memory and is never written
+to a file. If nothing works, `init` can't introspect anything and falls back
+to the fixed scaffold-and-ask-to-deploy flow above.
+
+### Re-running `init`
+
+`init` works out every file change first and only then writes. That makes
+re-runs safe:
+
+- **Answers default to what's configured.** The broker and anonymous sign-in
+  questions default to what the function already has. Per-table writes show
+  the current grants (`orders [i,u]:`). Enter keeps them, `-` clears them,
+  and a typo keeps them too, with a note. Declining "Configure write
+  access?" keeps all grants as they are. RPCs work the same way.
+  Non-interactive runs keep everything except what flags override, so CI
+  can't reset your config.
+- **Only the managed block of `index.ts` is ever rewritten, and only when
+  its config actually changed.** Order doesn't count, so the same grants in
+  a different order aren't a change. Code outside the markers is never
+  touched. If you edited *inside* the block in a way `init` can't read back,
+  or the file has no markers, `init` leaves the file alone and prints the
+  block for you to merge. It also leaves `verify_jwt` on until the broker
+  wiring is really in the file, because turning it off first would let
+  tokenless requests run as anon.
+- **Descriptions are never asked for twice.** Columns covered by a local
+  `_exposify_comments.sql` count as documented even before `db push`, so a
+  re-run doesn't write a second migration for them.
+- **A run that changes no file checks the project instead.** It checks that
+  `exposify_meta()` is applied, that local descriptions are pushed, and that
+  the deployed function is current. "Current" means its write/RPC tools match
+  the config, and it rejects tokenless requests when the config uses the
+  broker. If all of that holds, `init` prints "Already up to date" and stops.
+  Otherwise it names what's behind and offers only the step that fixes it
+  (`db push` and/or `functions deploy`).
+- **`init --check`** asks no questions and writes nothing. It exits 1 if a
+  run would change a file (CI drift check). It looks at local files only;
+  `doctor` checks the live project.
 
 ### Using the hosted broker
 
-If you use the Exposify hosted broker (the dashboard's "Hosted broker" card),
 `init` asks first:
 
 ```
-Use the Exposify hosted broker for auth (MCP clients get a long-lived extb_... token instead of a Supabase JWT)? [y/N]
+Let agents log in as your users through the Exposify hosted broker (they get a long-lived connection instead of an hourly Supabase JWT)? [y/N]
 ```
 
-Or skip the question with `--broker-url <url> --broker-project <id>`
-(or `EXPOSIFY_BROKER_URL`/`EXPOSIFY_PROJECT_ID`), which also works
-non-interactively. Saying yes does three things:
-
-1. **Wires the resolver into the function.** Adds
-   `auth: createHostedAuthResolver({ brokerUrl, projectId, licenseKey })` and
-   `authRequired: true` to `aiReady()`. The license key is read from the
-   `EXPOSIFY_LICENSE_KEY` secret and is never written into the file. If
-   `index.ts` already exists, `init` prints the snippet for you to merge in
-   yourself.
-2. **Sets `verify_jwt = false` for `mcp` in `supabase/config.toml`.** An
-   `extb_...` token isn't a JWT, so with the gateway's check on, every request
+Or skip the question with `--broker` (`--broker-url <url>`, or
+`EXPOSIFY_BROKER_URL`, also points it at a different broker, for local
+development), which also works non-interactively. Saying yes does three
+things:
+
+1. **Wires the broker into the function.** Adds `auth: hostedBroker()` and
+   `authRequired: true` to `aiReady()`. `hostedBroker()` reads the
+   `EXPOSIFY_KEY` secret, which is never written into the file. This goes in
+   the managed block, so an existing `index.ts` gets it too, unless its block
+   was hand-edited. In that case `init` prints the block for you to merge,
+   and leaves `verify_jwt` alone until you have.
+2. **Sets `verify_jwt = false` for `mcp` in `supabase/config.toml`.** A
+   broker token isn't a Supabase JWT, so with the gateway's check on, every request
    fails with `{"code":"UNAUTHORIZED_ASYMMETRIC_JWT","message":"Invalid JWT"}`
    before the function runs. The setting goes in config.toml and not just
    on the deploy command line, because a later plain
@@ -139,13 +186,14 @@ non-interactively. Saying yes does three things:
    that have no valid broker token. Otherwise those requests would run as
    `anon`.
 3. **Deploys with `--no-verify-jwt`**, and adds
-   `supabase secrets set EXPOSIFY_LICENSE_KEY=...` to the printed steps.
-   `init` never sees the license key, so you set that secret yourself.
+   `supabase secrets set EXPOSIFY_KEY=...` to the printed steps.
+   `init` never sees the key, so you set that secret yourself.
    Until you do, every request gets a 401.
 
-MCP clients then send `Authorization: Bearer extb_...`. Don't give the client
-the JWT that `POST /resolve` returns. It's the short-lived Supabase token the
-function swaps in on each request, and it stops working when it expires.
+MCP clients then click Connect and sign in through the broker (or send a
+pasted `Authorization: Bearer extb_...`). Don't give the client the JWT that
+`POST /resolve` returns. It's the short-lived Supabase token the function
+swaps in on each request, and it stops working when it expires.
 
 ## 2. Decide what's exposed
 
@@ -157,19 +205,24 @@ invisible, full stop, with no override. For each exposed table you get a
 column list, `order`, and a `limit` capped server-side (100 rows by default,
 regardless of what the caller asks for).
 
-Writes and Postgres functions are **opt-in**, edited in
-`supabase/functions/mcp/index.ts`:
+Writes and Postgres functions are **opt-in**. Re-run `init` to change them,
+or edit the managed block in `supabase/functions/mcp/index.ts` by hand,
+keeping its format. Anything else goes below the block:
 
 ```ts
+// exposify:begin -- generated by `npx exposify-supabase init`, ...
 import { aiReady } from "npm:@exposify/supabase";
 
-Deno.serve(aiReady({
+const generated = {
   // "<table>.insert" | "<table>.update" | "<table>.delete" | "<table>.*"
   writes: ["orders.insert", "orders.update"],
-
   // Postgres functions exposed as rpc_<fn> tools
   rpc: ["place_order"],
+};
+// exposify:end
 
+Deno.serve(aiReady({
+  ...generated,
   // Sibling edge functions, invoked via fetch with the caller's forwarded JWT
   functions: {
     refund: {
@@ -201,7 +254,7 @@ Other options you can pass to `aiReady()`:
 | Option | Default | What it does |
 |---|---|---|
 | `docs` | `["docs/**/*.md"]` | Glob(s), relative to the function directory, bundled into the knowledge base |
-| `docsAuth` | `"public"` | `"required"` hides `search_docs` until the caller sends *any* `Authorization` header (presence-only, not validated) |
+| `docsAuth` | `"public"` (`"required"` with the hosted broker) | `"required"` hides `search_docs` until the caller sends *any* `Authorization` header (presence-only, not validated) |
 | `maxRows` | `100` | Hard cap applied to every `query_<table>` call |
 | `rateLimit` / `rateWindowMs` | `60` / `60000` | In-memory, per-instance, best-effort rate limit — **not** distributed across edge instances; real limits belong to Supabase's own gateway |
 | `supabaseUrl` / `anonKey` / `serviceRoleKey` | read from `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` env vars | Override for local dev/testing; in a deployed function all three env vars are automatic. `serviceRoleKey` is used only for schema introspection — see below. |
@@ -253,7 +306,9 @@ unless you're editing `sql/exposify_meta.sql` directly).
 ## 4. Connect an MCP client
 
 Point any MCP client at the function's URL with a real user's JWT as the
-bearer token — for example, with the Claude Code CLI:
+bearer token (or set up OAuth or the hosted broker, below, so the client logs
+in by itself) — for
+example, with the Claude Code CLI:
 
 ```bash
 claude mcp add --transport http my-app https://<project-ref>.supabase.co/functions/v1/mcp \
@@ -264,29 +319,174 @@ Ask the agent to query or mutate data. **It should succeed for that user's
 own rows and be refused everyone else's** — that's the definition of done:
 RLS enforcement, not anything in this SDK, is what makes that true.
 
-## Long-lived tokens for clients that can't refresh (token broker)
+## 5. Check it: `doctor`
+
+```bash
+npx exposify-supabase doctor            # finds the project the same way init does
+npx exposify-supabase doctor --token <user-jwt | extb_...>
+```
+
+A read-only health check of everything `init` sets up. It never writes a file
+and never runs a mutating Supabase CLI command. Each check prints ✓ (pass),
+! (warning) or ✗ (failure), and warnings and failures come with the fix. It
+exits 1 if anything failed, so you can run it in CI.
+
+- **Project:** `supabase/config.toml`, the Supabase CLI, the linked project.
+- **Local files:** the `exposify_meta()` migration and `functions/mcp/index.ts`,
+  and which auth that file uses. With the hosted broker or OAuth, it checks
+  that `verify_jwt = false` for `mcp`.
+- **Database:** `exposify_meta()` is applied and the PostgREST schema is
+  readable. It lists which tables became tools, and warns about tables that
+  never will: RLS off, or RLS on but no API grants. It also warns about
+  tables whose missing comments leave tools with thin descriptions.
+- **Deployed function:** speaks MCP to `<project>/functions/v1/mcp`
+  (`initialize`, then `tools/list`) and reports the tool count. If the
+  function registered `exposify://diagnostics`, which it only does when
+  degraded, doctor prints that too. With the broker, it also checks that the
+  `EXPOSIFY_KEY` secret exists (`supabase secrets list`).
+
+**How the function check authenticates:** it uses `--token` if you pass one.
+Otherwise it sends no token. If the gateway rejects that (`verify_jwt` on),
+it retries once with the legacy anon key, when one was discovered or set in
+`SUPABASE_ANON_KEY`. Tools come from service-role introspection, so the anon
+role is enough to list them. A function with `authRequired` answers 401 to
+both, and doctor reports that as a warning asking for `--token`.
+
+## "Click Connect and log in" with Supabase Auth (OAuth)
+
+Instead of pasting a JWT, MCP clients can log users in through Supabase
+Auth's OAuth 2.1 server:
+
+```ts
+// supabase/functions/mcp/index.ts
+import { aiReady, supabaseAuth } from "npm:@exposify/supabase";
+
+Deno.serve(aiReady({ oauth: supabaseAuth(), writes: ["todos.*"] }));
+```
+
+`init --oauth` (or answering yes to its "sign in with Supabase Auth?"
+question) writes this for you and handles `verify_jwt`. The user adds just
+the function URL to Claude, Cursor, etc. The first request gets a `401`
+whose `WWW-Authenticate` points at Protected Resource Metadata served under
+the function's own URL (`…/functions/v1/mcp/.well-known/oauth-protected-resource`).
+The client then discovers Supabase Auth, registers, opens your consent page,
+and refreshes tokens later on its own. The validated token is an ordinary
+project JWT, forwarded to PostgREST unchanged, so **RLS runs as the
+signed-in user** exactly as with a pasted JWT.
+
+Project setup (dashboard, **Authentication > OAuth Server**, beta):
+
+- Enable the OAuth 2.1 server and **dynamic client registration**.
+- Set the **authorization path** to a consent page your app hosts, built
+  with `supabase.auth.oauth.getAuthorizationDetails()` /
+  `approveAuthorization()`. Supabase doesn't host one for you.
+- Use **asymmetric JWT signing keys**. `supabaseAuth()` verifies tokens
+  against `/auth/v1/.well-known/jwks.json`, and legacy HS256 projects have no
+  keys there.
+- **Turn off the gateway's JWT check** (`verify_jwt = false`). Otherwise the
+  gateway answers the first tokenless request with its own `401`, which has no
+  `resource_metadata`, and discovery never starts. The `oauth` gate checks
+  every token itself.
+
+Notes:
+
+- Supabase Auth always issues `aud: "authenticated"` and can't bind a
+  token to the function's URL, so `supabaseAuth()` accepts that audience (a
+  startup warning says so). In practice any valid user JWT of the project
+  is accepted, which is exactly what RLS already trusts.
+- `resource` defaults to `${SUPABASE_URL}/functions/v1/<function directory>`.
+  Pass `supabaseAuth({ resource })` if you serve the function under a
+  custom domain.
+- Any other spec-compliant AS works with plain options:
+  `oauth: { issuer, resource, scopes?, audience?, jwksUri?, verify? }`
+  (see the `@exposify/express` README).
+- By default PRM is only reachable through the `401` header (an edge
+  function can't serve the project domain's root `/.well-known/`, and
+  Supabase's custom-domain add-on doesn't change that; the root still
+  belongs to Supabase). MCP clients are required to prefer that header, so
+  this only fails with clients that probe well-known URIs and ignore it. If
+  you hit one, or want a branded URL anyway, see "Serving it from your own
+  domain" below.
+- `oauth` can't be combined with `auth`/`authRequired` (the broker) or
+  `docsAuth: "public"`; both throw at startup.
+- Not yet verified against a live Supabase project with a real MCP client;
+  see HANDOVER.
+
+### Serving it from your own domain (optional)
+
+To give clients the standard root-level well-known URI, put a proxy you
+control in front of the function, e.g. a Cloudflare Worker on
+`mcp.acme.com`:
+
+```js
+const FN = "https://<project-ref>.supabase.co/functions/v1/mcp";
+
+export default {
+  async fetch(req) {
+    const { pathname, search } = new URL(req.url);
+    let target;
+    if (pathname === "/.well-known/oauth-protected-resource/mcp") {
+      target = `${FN}/.well-known/oauth-protected-resource`;
+    } else if (pathname === "/mcp" || pathname.startsWith("/mcp/")) {
+      target = FN + pathname.slice("/mcp".length) + search;
+    } else {
+      return new Response("not found", { status: 404 });
+    }
+    return fetch(new Request(target, req));
+  },
+};
+```
+
+and tell the function its public address:
+
+```ts
+oauth: supabaseAuth({
+  resource: "https://mcp.acme.com/mcp",  // what clients connect to = token audience
+  metadataUrl: "https://mcp.acme.com/.well-known/oauth-protected-resource/mcp",
+}),
+```
+
+The PRM now reports the proxy URL, the `401` points at the root-level URI,
+and the function answers the forwarded request (it serves PRM on any path
+ending in `/.well-known/oauth-protected-resource`). Caveat: the built-in
+per-IP rate limiter keys on `x-forwarded-for`, which Supabase's gateway
+will likely set to the proxy's address, so every client could share one
+60-requests/minute bucket. Rate-limit at the proxy and raise `rateLimit` on
+the function. This setup is untested against a real deployment.
+
+## Long-lived tokens for clients that can't refresh (the hosted broker)
 
 Supabase user JWTs expire (default 1h) and their refresh tokens rotate; a plain
-MCP client can hold a bearer token but can't refresh it. Pass an `auth`
-resolver (any `(incoming: Headers) => Headers | Promise<Headers>`, such as
-`broker.resolver` from [`@exposify/token-broker`](../token-broker/README.md))
-and the client sends a long-lived broker token instead:
+MCP client can hold a bearer token but can't refresh it. Exposify's hosted
+broker holds each user's session, refreshes it, and swaps the agent's
+long-lived connection token (`extb_...`) for a live Supabase JWT on every
+call ([`docs/hosted-broker.md`](../../docs/hosted-broker.md)). `init` sets it
+up (see "Using the hosted broker" above); by hand:
+
+```sh
+supabase secrets set EXPOSIFY_KEY=exk_...   # the project's secret key from the dashboard
+```
 
 ```ts
 // supabase/functions/mcp/index.ts
-import { aiReady } from "npm:@exposify/supabase";
-import { broker } from "./broker.ts"; // createTokenBroker(...) over a shared store
+import { aiReady, hostedBroker } from "npm:@exposify/supabase";
 
-Deno.serve(aiReady({ auth: broker.resolver, authRequired: true, writes: ["todos.*"] }));
+Deno.serve(aiReady({ auth: hostedBroker(), authRequired: true, writes: ["todos.*"] }));
 ```
 
-- The resolver receives the request's original headers (the `extb_...` token)
-  and its result **replaces** them for PostgREST and `functions` calls, so RLS
-  applies as that user and the broker token is never forwarded. `apikey` and a
+With the `EXPOSIFY_KEY` secret set, `aiReady()` uses the broker even without
+`auth`, and `authRequired` defaults to on; `hostedBroker()` just says so in
+the code, and never throws (a missing secret refuses every call with one
+warning).
+
+- `auth` takes any resolver (`(incoming: Headers) => Headers | Promise<Headers>`).
+  It receives the request's original headers (the `extb_...` token) and its
+  result **replaces** them for PostgREST and `functions` calls, so RLS applies
+  as that user and the connection token is never forwarded. `apikey` and a
   missing `authorization` still fall back to the anon key.
-- `docsAuth: "required"` checks the raw incoming headers, so a broker token
-  counts as authenticated.
-- A broker resolver returns empty headers for an unknown/revoked token or a
+- `docsAuth: "required"` checks the raw incoming headers, so a connection
+  token counts as authenticated.
+- The resolver returns empty headers for an unknown or revoked token or a
   failed refresh. By default the request then runs as the `anon` role (RLS
   decides). Set `authRequired: true` to answer `401` instead. Recommended.
 - A resolver that throws yields a 503.
@@ -294,24 +494,7 @@ Deno.serve(aiReady({ auth: broker.resolver, authRequired: true, writes: ["todos.
   (`[functions.mcp] verify_jwt = false` in `supabase/config.toml`, or
   `supabase functions deploy mcp --no-verify-jwt`). Otherwise Supabase
   rejects the `extb_...` token as `Invalid JWT` before your code runs. With
-  the check off, `authRequired: true` stops being optional.
-- For the platform-hosted broker, use `createHostedAuthResolver` in place of
-  `broker.resolver`. `init` can set this up for you; see "Using the hosted
-  broker" above.
-
-**Deployment constraints** (not verified end to end, see HANDOVER):
-
-- The broker's OAuth server (`listenTokenBroker`) is a Node HTTP server and
-  can't run in an Edge Function; run it as a separate service.
-- The edge function builds its own `createTokenBroker(...)` over the **same
-  persistent `TokenStore`** (Redis/Postgres, see the token-broker README's
-  `ioredis` example) and the same `TOKEN_BROKER_ENCRYPTION_KEY`. The in-memory
-  store is per-process and won't work.
-- The broker service does proactive refresh; short-lived edge instances rely on
-  the resolver's lazy refresh when `expiresAt` has passed.
-- `@exposify/token-broker` imports `node:crypto` (`scryptSync`, AES-256-GCM,
-  RS256). Whether that works under Supabase's Deno runtime has **not** been
-  tested; try `supabase functions serve` before depending on it.
+  the check off, `authRequired: true` stops being optional. `init` does both.
 
 ## Knowledge base
 
@@ -356,7 +539,10 @@ PostgREST's OpenAPI document at all, so `generate` needs the same
 privileged key runtime introspection does. Nothing from the service role
 key ends up in the generated manifest — it's just table/column metadata.
 
-This writes `supabase/functions/mcp/exposify.manifest.json`. Load it in
+This writes `supabase/functions/mcp/exposify.manifest.json`. A re-run only
+rewrites it when the schema in it changed (a new `generatedAt` alone doesn't
+count), so committing the manifest doesn't produce churn.
+`generate --check` exits 1 if the manifest is missing or out of date. Load it in
 `aiReady({ manifest: ... })` — since the function runs on Deno, import it
 with a JSON import:
 
@@ -366,8 +552,33 @@ import manifest from "./exposify.manifest.json" with { type: "json" };
 Deno.serve(aiReady({ manifest, /* ...writes/rpc/functions... */ }));
 ```
 
+## What the function logs
+
+Once per edge instance (cold start), after the first schema introspection,
+the function prints whether MCP is up. It shows in `supabase functions serve`
+locally and in the function's logs in production:
+
+```
+[exposify-supabase] MCP ready at https://<ref>.supabase.co/functions/v1/mcp: 9 tools (5 query, 2 write, 1 rpc, search_docs), 3 docs indexed, auth: passthrough (caller's JWT)
+```
+
+- **Manifest fallback:** the same line, marked "from the bundled manifest",
+  plus a warning with the fix.
+- **Functions-only fallback:** `MCP failed to start: couldn't read the
+  database schema ...` with a fix line, since no database tools exist.
+- **Missing `SUPABASE_URL`:** reported once at cold start.
+- **With `oauth`:** the issuer's keys are fetched at cold start, and a
+  failure becomes a warning.
+
+Failures and warnings always print. The ready line and the issuer check are
+on by default and off under `NODE_ENV=test`; `startupLog: true | false`
+overrides that.
+
 ## Troubleshooting
 
+Start with `npx exposify-supabase doctor`. It checks most of what's below
+and names the fix.
+
 **"exposify_meta() is not reachable" / "PGRST202" errors in function logs.**
 The migration hasn't been applied to this database. Run `supabase db push`
 (or apply `sql/exposify_meta.sql` from this package directly), then