@cerefox/memory 0.11.0 → 1.0.0-beta.1

package/docs/guides/setup-supabase.md

@@ -48,7 +48,7 @@ You need three values from Supabase: a URL, an API key, and a direct Postgres co
 See the **[Supabase API keys (2026)](#supabase-api-keys-2026)** section near the end of this guide for the full picture. The short version:
 
 - For `CEREFOX_SUPABASE_KEY` (this guide, the web UI, and the CLI): use the new **secret key** (`sb_secret_…`) from **Project Settings → API Keys → Secret key**. The legacy `service_role` JWT also still works during the transition.
-- For `CEREFOX_SUPABASE_ANON_KEY` (only if you'll use Edge Functions / MCP / GPT Actions; not needed for this guide's deployment step): you must use the **legacy anon JWT** (`eyJ…`). The new `sb_publishable_…` key fails at the Edge Function gateway. See the reference section for why.
+- To call Edge Functions / remote MCP / GPT Actions you need the **Cerefox access token** (`cfx_pat_…`), not a Supabase key. Generate it later with `cerefox token generate` (Step 7 covers the server-side setup). The legacy Supabase anon JWT is retired for Edge Function auth (iter-28E), and `CEREFOX_SUPABASE_ANON_KEY` is no longer used.
 
 Either way: keep this key secret — it bypasses Row Level Security and grants full database access.
 
@@ -78,9 +78,9 @@ cerefox init
 
 When prompted, supply the three values from Step 3 (URL, secret key, database
 URL) plus your `OPENAI_API_KEY`. If you plan to connect AI agents via the
-remote MCP / GPT Actions path, also set `CEREFOX_SUPABASE_ANON_KEY` to the
-**legacy anon JWT** (`eyJ…`, not `sb_publishable_…` — see "Supabase API keys
-(2026)" below).
+remote MCP / GPT Actions path, you'll add a **Cerefox access token** later by
+running `cerefox token generate` (it upserts `CEREFOX_ACCESS_TOKEN` into this
+same `.env` and sets the accepted set on Supabase — see Step 7).
 
 A minimal `~/.cerefox/.env` looks like:
 
@@ -89,8 +89,8 @@ CEREFOX_SUPABASE_URL=https://your-project-ref.supabase.co
 CEREFOX_SUPABASE_KEY=sb_secret_...your-secret-key...
 CEREFOX_DATABASE_URL=postgresql://postgres.yourref:yourpassword@aws-N-region.pooler.supabase.com:5432/postgres?sslmode=require
 OPENAI_API_KEY=sk-...
-# Only needed for Edge Functions / MCP / GPT Actions — must be the legacy anon JWT:
-# CEREFOX_SUPABASE_ANON_KEY=eyJ...your-legacy-anon-jwt...
+# Only needed for Edge Functions / MCP / GPT Actions — written by `cerefox token generate`:
+# CEREFOX_ACCESS_TOKEN=cfx_pat_...your-cerefox-token...
 ```
 
 > **Contributors** (repo clone): copy `cp .env.example .env` in the project root
@@ -131,6 +131,22 @@ Your project ref is in the Supabase dashboard URL:
 After it finishes, verify in the Supabase Dashboard → **Edge Functions** — all 9
 functions should appear with a green "Active" status.
 
+**Now generate the Edge Function access token.** The Edge Functions authenticate
+callers with a Cerefox access token. Generate one if you'll use **GPT Actions** or a
+**remote HTTP MCP** client, or want a fully-green `cerefox doctor`:
+
+```bash
+cerefox token generate
+```
+
+This sets the `CEREFOX_ACCESS_TOKENS` secret on Supabase and writes
+`CEREFOX_ACCESS_TOKEN` into your `.env`. It prints the token **once** — store it. You
+paste it by hand only if you connect a **Custom GPT** (Action → Authentication → API
+Key) or a **remote HTTP MCP** client. The **local MCP**, **cloud Claude** (OAuth), and
+the CLI/web reach Supabase over the Data API and don't need it, so this step is
+optional for a local-MCP-only or OAuth-only setup. Lose it → `cerefox token rotate`.
+Re-run `cerefox doctor` — the "edge functions" check goes green.
+
 > **`WARNING: Docker is not running` is expected and harmless.** The Supabase CLI checks for
 > Docker (its older local bundler ran in a container) but falls back to bundling the functions
 > server-side — it uploads the source assets (you'll see `Uploading asset (…)` lines) and
@@ -164,9 +180,10 @@ This points the client at the local stdio server (`cerefox mcp`). To edit
 configs by hand or use the remote (Edge Function) HTTP transport, see
 [`connect-agents.md`](connect-agents.md).
 
-**For cloud Claude.ai** — connect to the Supabase remote MCP (FTS keyword search only):
-1. In Supabase Dashboard → Project Settings → Integrations → MCP, get your project ref
-2. In Claude.ai Settings → Integrations, add `https://mcp.supabase.com/sse?project_ref=<ref>`
+**For cloud Claude.ai / Claude mobile** — connect over OAuth to your own
+`cerefox-mcp` Edge Function with the **full hybrid-search tool surface** (not the
+FTS-only `mcp.supabase.com` path). This needs a one-time OAuth setup — see
+[Step 7](#step-7--oauth-for-cloud-agents-claudeai--mobile-optional) below.
 
 **For cloud ChatGPT** — create a Custom GPT with GPT Actions pointing at the Edge Functions.
 
@@ -175,6 +192,129 @@ architecture explanation, and ChatGPT GPT Actions setup.
 
 ---
 
+## Step 7 — Connect cloud & mobile Claude over OAuth (optional) <a id="step-7--oauth-for-cloud-agents-claudeai--mobile-optional"></a>
+
+> **This whole section is optional.** You only need it to connect **claude.ai web and
+> the Claude mobile app** (and any other OAuth-only cloud MCP client). Everything in
+> Step 6 — the local MCP, Claude Desktop, Cursor, Claude Code, Codex, Gemini — works
+> **without** any of this. Skipping Step 7 costs you nothing except cloud/mobile Claude.
+>
+> The one extra moving part OAuth adds is a **hosted consent page** — the screen where
+> you approve the connection. A Supabase Edge Function can't serve it (Supabase rewrites
+> HTML to `text/plain` on the default `*.supabase.co` domain), so this repo ships the
+> page as a **free Cloudflare Worker** with a one-command deploy. Full design + the
+> gotchas we hit: [`docs/specs/oauth-mcp-server-design.md`](../specs/oauth-mcp-server-design.md).
+
+Cloud AI agents can only connect to a custom MCP server over **OAuth** — they cannot send
+a static token. Supabase's native **OAuth 2.1 Server** (beta; free on all plans) makes
+`cerefox-mcp` an OAuth-protected resource, so claude.ai and the mobile app get the full
+hybrid-search tool surface (not the FTS-only `mcp.supabase.com` path).
+
+**Prerequisite — asymmetric signing keys.** Token validation uses your project's public
+JWKS, so the JWT signing key must be **asymmetric (ES256 or RS256)**, not the HS256
+default. Check **Project Settings → JWT Keys**; if it says HS256, migrate to ES256 first
+(a Supabase-managed key rotation). Existing clients are unaffected (they treat the key as
+an opaque string). New projects often already default to ES256.
+
+### 7a. Enable the OAuth 2.1 Server
+
+Supabase Dashboard → **Authentication → OAuth Server** (under Configuration):
+
+- **Enable** the OAuth 2.1 Server.
+- **Authorization Path**: set to `/consent` (combines with the Site URL in 7b to form the
+  consent-page URL).
+- **Dynamic Client Registration (DCR): leave DISABLED.** The dashboard flags open DCR as a
+  security risk (any client could self-register), a single-user setup only needs one
+  client, and claude.ai's DCR against Supabase is currently unreliable. Register the one
+  client by hand in 7d instead.
+
+### 7b. Deploy the consent page (free Cloudflare Worker) and point Site URL at it
+
+The consent page is a single static file that talks only to Supabase Auth. It embeds a
+**publishable** key (`sb_publishable_…`) — **never the legacy anon JWT**. (The anon JWT is a
+full-KB credential; the publishable key is public-safe — it's rejected by the Edge Function
+gateway and, since schema 0.7.0, cannot call the Data API RPCs either. See the
+[security model](../specs/security-model.md).)
+
+Add your publishable key to `~/.cerefox/.env` as the single source
+(`deploy.sh` reads it). Grab it from the dashboard (**Project Settings → API Keys →
+Publishable**) or the CLI:
+
+```bash
+npx supabase projects api-keys --project-ref <ref>   # find the "publishable" entry
+echo 'CEREFOX_SUPABASE_PUBLISHABLE_KEY=sb_publishable_…' >> ~/.cerefox/.env
+```
+
+Then deploy to a free Cloudflare Worker (needs a free Cloudflare account — no domain, no
+card):
+
+```bash
+cd cloudflare/cerefox-consent
+./deploy.sh        # reads CEREFOX_SUPABASE_URL + CEREFOX_SUPABASE_PUBLISHABLE_KEY from ~/.cerefox/.env
+```
+
+See [`cloudflare/cerefox-consent/README.md`](../../cloudflare/cerefox-consent/README.md)
+for the manual `wrangler` commands. It prints your Worker URL, e.g.
+`https://cerefox-consent.<your-subdomain>.workers.dev`.
+
+Then Dashboard → **Authentication → URL Configuration → Site URL** = that Worker origin.
+With Authorization Path `/consent`, the consent page lands at `…workers.dev/consent`. (If
+your Site URL was the default `http://localhost:3000`, repointing is safe.)
+
+### 7c. Create the owner user + pin it
+
+1. **Owner user** — Dashboard → **Authentication → Users → Add user**: your email + a
+   strong password. This is the login you type on the consent page (unrelated to your
+   Supabase dashboard login). Copy the new user's **UUID**.
+2. **Owner pin** — the only Function secret this feature needs:
+
+   ```bash
+   supabase secrets set CEREFOX_OAUTH_OWNER_ID='<owner-user-uuid>' --project-ref <ref>
+   ```
+
+   This is the **authorization boundary**, and a server-side value only (never entered
+   into claude.ai). The OAuth path **fails closed when this is unset** — the function
+   rejects every OAuth token — because otherwise, with Supabase's default email sign-ups
+   on, anyone who self-registers could get an accepted token. For a deliberate multi-user
+   setup (with sign-ups disabled), opt out explicitly:
+   `supabase secrets set CEREFOX_OAUTH_ALLOW_ANY_USER=true`.
+
+### 7d. Register the Claude client — **use `client_secret_post`**
+
+Dashboard → **Authentication → OAuth Apps → New OAuth App**:
+
+- **Client type**: Confidential.
+- **Redirect URI** (exact match, no wildcards): `https://claude.ai/api/mcp/auth_callback`
+- **Token endpoint auth method: `request body` (`client_secret_post`)** — **not** HTTP
+  Basic. Claude sends its client secret in the request body; the Basic default silently
+  fails the token exchange with an opaque `ofid_…` error and no usable token. **This is
+  the single most common setup mistake — get it right here.**
+- Save, then copy the **Client ID** and **Client Secret** (the secret is shown once). You
+  paste both into the claude.ai connector — see
+  [`connect-agents.md` → Cloud Claude](connect-agents.md#cloud-claude-claudeai-web--mobile-oauth).
+
+### 7e. Deploy the function
+
+```bash
+cerefox server deploy --functions-only
+```
+
+Deploys `cerefox-mcp` with `--no-verify-jwt` (in-function auth). Then wire the claude.ai
+connector per
+[`connect-agents.md` → Cloud Claude](connect-agents.md#cloud-claude-claudeai-web--mobile-oauth).
+
+> **Note — the Cerefox access token (iter-28E).** All nine data Edge Functions (the 8
+> primitives + `cerefox-mcp`) now deploy `--no-verify-jwt` and authenticate the **Cerefox
+> access token** in-function; the legacy anon JWT is retired for Edge Function auth. Before
+> your first token-gated deploy, run `cerefox token generate` — it sets the accepted set
+> (`CEREFOX_ACCESS_TOKENS`, a Supabase Function secret) and writes `CEREFOX_ACCESS_TOKEN` to
+> your local `.env`. Deploying token-gated functions with no token set locks every caller
+> out, so generate the token first. `cerefox-mcp` also accepts an owner-pinned OAuth token
+> (the arm this Step 7 configures); the OAuth path fails closed until `CEREFOX_OAUTH_OWNER_ID`
+> is set (7c).
+
+---
+
 ## Troubleshooting
 
 ### "could not connect to server"
@@ -203,18 +343,19 @@ In 2026 Supabase rolled out a new API key system. The dashboard now shows two ke
 | Family | What you'll see in the dashboard | Use it for |
 |---|---|---|
 | **New (recommended)** | "Publishable key" (`sb_publishable_…`) and "Secret key" (`sb_secret_…`) | `CEREFOX_SUPABASE_KEY` — works end-to-end through the Data API. |
-| **Legacy** | "anon" and "service_role" JWTs (`eyJ…`), filed under a "Legacy" section | `CEREFOX_SUPABASE_ANON_KEY` — **still required** for any Edge Function call (MCP, GPT Actions, e2e tests, direct curl). |
+| **Legacy** | "anon" and "service_role" JWTs (`eyJ…`), filed under a "Legacy" section | `service_role` still works for `CEREFOX_SUPABASE_KEY` (Data API). The **anon** JWT is **no longer used** for Edge Function auth (retired in iter-28E — see below). |
 
 ### What goes where in `.env`
 
 | Variable | Recommended value | Why |
 |---|---|---|
 | `CEREFOX_SUPABASE_KEY` | New **secret key** (`sb_secret_…`). Legacy `service_role` JWT also works. | Used by `db/client.py` to reach the Data API (PostgREST). Both formats are accepted by the gateway. |
-| `CEREFOX_SUPABASE_ANON_KEY` | **Legacy anon JWT** (`eyJ…`). | Used as the `Authorization: Bearer …` header for Edge Function calls. The Supabase Edge Function gateway still validates this token as a JWT — it parses `header.payload.signature` and rejects non-JWT keys with `UNAUTHORIZED_INVALID_JWT_FORMAT`. The new `sb_publishable_…` key is not a JWT and fails. |
+| `CEREFOX_ACCESS_TOKEN` | **Cerefox access token** (`cfx_pat_…`) from `cerefox token generate`. | The `Authorization: Bearer …` credential for Edge Function calls (remote MCP, GPT Actions, e2e tests, direct curl). Validated in-function; rotatable via `cerefox token rotate`. |
+| `CEREFOX_SUPABASE_ANON_KEY` | *(deprecated / unused)* | Formerly the Edge Function Bearer credential. Retired in iter-28E; retained only so an old `.env` still parses. |
 
-### Why we cannot just use the new keys everywhere
+### Why Edge Functions use a Cerefox token, not a Supabase key
 
-The Data API gateway was migrated in 2026 to accept both the new and legacy key formats. The Edge Function gateway was not. A Supabase team member [confirmed this](https://github.com/orgs/supabase/discussions/41834): the only way to call Edge Functions with the new keys today is to deploy each function with `verify_jwt = false` and validate the key inside the function. Cerefox is not yet doing that (a future migration; see Decision Log 2026 Q2 for context and triggers).
+The Data API gateway was migrated in 2026 to accept both the new and legacy key formats. The Edge Function gateway was not — it rejects the new `sb_publishable_…`/`sb_secret_…` keys as non-JWTs. Rather than pin Edge Function auth to the unrotatable legacy anon JWT (revoke-only on ES256-migrated projects), iter-28E deploys every data Edge Function with `verify_jwt = false` and validates a **Cerefox-managed access token** in-function — a secret, rotatable credential independent of Supabase's key lifecycle. See `docs/specs/ef-auth-migration-design.md`.
 
 ### Is the legacy key going away?
 

package/docs/guides/upgrading.md

@@ -84,7 +84,8 @@ if you need it.
 
 **ChatGPT Custom GPT (GPT Actions):** after an upgrade, check the OpenAPI schema
 version in [`connect-agents.md`](connect-agents.md); if it changed, paste the new
-schema into the Custom GPT editor and **re-enter your Supabase legacy anon JWT**
-as the Bearer token. (The editor clears the key on every schema save, and the
-new `sb_publishable_…` key doesn't work for GPT Actions — see
+schema into the Custom GPT editor and **re-enter your Cerefox access token**
+(`cfx_pat_…`, from `cerefox token generate`) as the Bearer token. (The editor
+clears the key on every schema save. The legacy Supabase anon JWT is retired for
+Edge Function auth as of iter-28E — see
 [`setup-supabase.md`](setup-supabase.md#supabase-api-keys-2026).)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.11.0",
+  "version": "1.0.0-beta.1",
   "description": "Cerefox — user-owned shared memory for AI agents. The local TypeScript runtime: stdio MCP server in v0.4; CLI binary added in v0.5; in-process web server in v0.6; ingestion pipeline in v0.7.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",