@exposify/supabase 0.3.7 → 0.3.8

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,14 +100,62 @@ 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
 
@@ -126,9 +173,10 @@ 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.
+   `EXPOSIFY_LICENSE_KEY` secret and 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`.** An
    `extb_...` token isn't a JWT, so with the gateway's check on, every request
    fails with `{"code":"UNAUTHORIZED_ASYMMETRIC_JWT","message":"Invalid JWT"}`
@@ -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: {
@@ -253,7 +306,8 @@ 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, 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,6 +318,141 @@ 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.
 
+## 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_LICENSE_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 (token broker)
 
 Supabase user JWTs expire (default 1h) and their refresh tokens rotate; a plain
@@ -356,7 +545,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 +558,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