@cerefox/memory 0.11.1 → 1.0.0-beta.1

package/dist/server-assets/supabase/functions/cerefox-mcp/oauth.ts

@@ -0,0 +1,121 @@
+/**
+ * OAuth 2.1 protected-resource glue for cerefox-mcp (design §3–6).
+ *
+ * Pure auth logic lives in `_shared/mcp-auth/`; this file is the HTTP/Deno layer:
+ * it builds the authenticator from Function secrets, serves the RFC 9728 metadata
+ * document, and formats the 401 challenge. It is imported only by the EF.
+ */
+
+import { CORS_HEADERS } from "./shared.ts";
+import {
+  type AuthResult,
+  createMcpAuthenticator,
+  type McpAuthenticator,
+} from "../../../_shared/mcp-auth/index.ts";
+
+/** Stable public path of this function (used to build absolute metadata URLs). */
+export const FUNCTION_PATH = "/functions/v1/cerefox-mcp";
+
+/** The protected-resource metadata route, matched as a suffix of the request path. */
+const PRS_SUFFIX = "/.well-known/oauth-protected-resource";
+
+/**
+ * Origin of the deployed project, e.g. `https://<ref>.supabase.co`, from the
+ * platform-injected `SUPABASE_URL` — NOT from request headers.
+ *
+ * SECURITY (design §6): the token issuer and JWKS URL are derived from this origin.
+ * Deriving it from client-influenced headers (`x-forwarded-host`/`-proto`) would let
+ * a caller point token validation at an attacker-controlled JWKS and forge a token
+ * that passes (JWKS-poisoning auth bypass). `SUPABASE_URL` is set by the platform for
+ * every Edge Function and is not client-controllable (every other Cerefox EF already
+ * depends on it). It is also the exact public https origin Anthropic requires for the
+ * RFC 9728 `resource` identifier — so this both hardens auth and removes the earlier
+ * `http://` (internal-proxy) scheme workaround.
+ */
+function projectOrigin(): string {
+  return (Deno.env.get("SUPABASE_URL") ?? "").replace(/\/+$/, "");
+}
+
+/** Absolute URL of this MCP server (the `resource` identifier — must match exactly). */
+export function resourceUrl(): string {
+  return `${projectOrigin()}${FUNCTION_PATH}`;
+}
+
+/** The Supabase auth server issuer for this project. */
+export function issuerUrl(): string {
+  return `${projectOrigin()}/auth/v1`;
+}
+
+/** True when the request targets the (public) protected-resource metadata route. */
+export function isProtectedResourceMetadata(req: Request): boolean {
+  const path = new URL(req.url).pathname;
+  // Accept both the plain suffix and the RFC 9728 path-insertion form
+  // (…/oauth-protected-resource/functions/v1/cerefox-mcp).
+  return path.includes(PRS_SUFFIX);
+}
+
+/** RFC 9728 Protected Resource Metadata document. */
+export function protectedResourceMetadata(): Response {
+  const body = {
+    resource: resourceUrl(),
+    // Anthropic reads authorization_servers[0]; Supabase serves valid AS metadata here.
+    authorization_servers: [issuerUrl()],
+    bearer_methods_supported: ["header"],
+    scopes_supported: ["openid", "email"],
+    resource_name: "Cerefox",
+  };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { ...CORS_HEADERS, "Content-Type": "application/json" },
+  });
+}
+
+/**
+ * 401 with an explicit `resource_metadata` pointer (RFC 9728 §5.1), so clients
+ * discover our metadata route rather than probing the domain root.
+ */
+export function unauthorizedChallenge(result: AuthResult): Response {
+  const metadataUrl = `${resourceUrl()}${PRS_SUFFIX}`;
+  const invalid = result.ok === false && result.reason !== "no_token";
+  const params = [`resource_metadata="${metadataUrl}"`];
+  if (invalid) params.push(`error="invalid_token"`);
+  return new Response(JSON.stringify({ error: "unauthorized" }), {
+    status: 401,
+    headers: {
+      ...CORS_HEADERS,
+      "Content-Type": "application/json",
+      "WWW-Authenticate": `Bearer ${params.join(", ")}`,
+    },
+  });
+}
+
+/**
+ * Build the authenticator from Function secrets + the injected SUPABASE_URL.
+ *
+ * Secrets (set via `supabase secrets set`):
+ *   CEREFOX_OAUTH_OWNER_ID       — pinned owner user id. The OAuth path fails CLOSED
+ *                                  when this is unset (design §6 / Finding 3), unless
+ *                                  CEREFOX_OAUTH_ALLOW_ANY_USER="true" is set.
+ *   CEREFOX_OAUTH_ALLOW_ANY_USER — explicit opt-out of the owner pin (multi-user /
+ *                                  sign-ups-disabled setups). Default off.
+ *
+ * The non-OAuth static path is the **Cerefox access token** (`CEREFOX_ACCESS_TOKENS`,
+ * iter-28E) — the same credential the primitive EFs accept — checked in the handler
+ * via `_shared/ef-auth` (see index.ts), NOT here. The legacy `CEREFOX_MCP_STATIC_BEARER`
+ * (anon JWT) is retired: `staticBearer` is left unset so this authenticator handles
+ * OAuth only.
+ */
+export function buildAuthenticator(): McpAuthenticator {
+  const issuer = issuerUrl();
+  const ownerUserId = Deno.env.get("CEREFOX_OAUTH_OWNER_ID") ?? null;
+  const allowAnyUser = Deno.env.get("CEREFOX_OAUTH_ALLOW_ANY_USER") === "true";
+  return createMcpAuthenticator({
+    issuer,
+    jwksUri: `${issuer}/.well-known/jwks.json`,
+    expectedAudience: "authenticated",
+    ownerUserId,
+    allowAnyUser,
+    staticBearer: null,
+    allowedAlgs: ["ES256", "RS256"],
+  });
+}

package/dist/server-assets/supabase/functions/cerefox-metadata/index.ts

@@ -1,6 +1,7 @@
 import "jsr:@supabase/functions-js/edge-runtime.d.ts";
 import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
+import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 
 /**
  * cerefox-metadata — Supabase Edge Function
@@ -29,6 +30,13 @@ Deno.serve(async (req: Request): Promise<Response> => {
     return new Response(null, { status: 200, headers: CORS_HEADERS });
   }
 
+  const authFail = efAuthGate(
+    req.headers.get("Authorization"),
+    Deno.env.get("CEREFOX_ACCESS_TOKENS"),
+    { ...CORS_HEADERS, "Content-Type": "application/json" },
+  );
+  if (authFail) return authFail;
+
   if (isVersionRequest(req)) {
     return versionResponse("cerefox-metadata", { ...CORS_HEADERS, "Content-Type": "application/json" });
   }

package/dist/server-assets/supabase/functions/cerefox-metadata-search/index.ts

@@ -1,6 +1,7 @@
 import "jsr:@supabase/functions-js/edge-runtime.d.ts";
 import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
+import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 
 /**
  * cerefox-metadata-search -- Supabase Edge Function
@@ -43,6 +44,13 @@ Deno.serve(async (req: Request): Promise<Response> => {
     return new Response(null, { status: 200, headers: CORS_HEADERS });
   }
 
+  const authFail = efAuthGate(
+    req.headers.get("Authorization"),
+    Deno.env.get("CEREFOX_ACCESS_TOKENS"),
+    { ...CORS_HEADERS, "Content-Type": "application/json" },
+  );
+  if (authFail) return authFail;
+
   if (isVersionRequest(req)) {
     return versionResponse("cerefox-metadata-search", { ...CORS_HEADERS, "Content-Type": "application/json" });
   }

package/dist/server-assets/supabase/functions/cerefox-search/index.ts

@@ -1,6 +1,8 @@
 import "jsr:@supabase/functions-js/edge-runtime.d.ts";
 import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
+import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
+import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
 
 /**
  * cerefox-search — Supabase Edge Function
@@ -68,6 +70,7 @@ const EMBEDDING_INITIAL_BACKOFF_MS = 500; // 500ms, 1s, 2s exponential backoff
 
 async function getEmbedding(text: string, apiKey: string): Promise<number[]> {
   let lastError: Error | null = null;
+  const input = capEmbeddingInput(text); // iter-28D Phase 0: cap (queries are short; safety)
 
   for (let attempt = 0; attempt < EMBEDDING_MAX_RETRIES; attempt++) {
     try {
@@ -79,7 +82,7 @@ async function getEmbedding(text: string, apiKey: string): Promise<number[]> {
         },
         body: JSON.stringify({
           model: OPENAI_MODEL,
-          input: text,
+          input,
           dimensions: EMBEDDING_DIMENSIONS,
         }),
       });
@@ -182,6 +185,13 @@ Deno.serve(async (req: Request) => {
     });
   }
 
+  const authFail = efAuthGate(
+    req.headers.get("Authorization"),
+    Deno.env.get("CEREFOX_ACCESS_TOKENS"),
+    headers,
+  );
+  if (authFail) return authFail;
+
   if (isVersionRequest(req)) {
     return versionResponse("cerefox-search", headers);
   }

package/docs/guides/access-paths.md

@@ -3,27 +3,31 @@
 Cerefox is built in three distinct layers. Understanding them tells you which credentials to
 configure, what can reach the database, and which path is right for your integration.
 
-> **A note on Supabase keys (2026):** Cerefox needs two API keys for two different transport
-> layers. Layer 1 (Edge Functions) uses the **legacy anon JWT** as a Bearer token — the new
-> `sb_publishable_…` key is rejected by the Edge Function gateway. Layer 2 (web + CLI REST)
-> uses the new **secret key** (`sb_secret_…`) or the legacy `service_role` JWT — either
-> works. See [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026)
-> for the full picture and why this asymmetry exists.
+> **A note on credentials (2026):** Cerefox uses two different credentials for two transport
+> layers. Layer 1 (Edge Functions) uses the **Cerefox access token** (`cfx_pat_…`) as a Bearer
+> token — a random, Cerefox-managed secret validated in-function (the legacy Supabase anon JWT
+> is retired for all Edge Function paths as of iter-28E). Layer 2 (web + CLI REST) uses the new
+> **secret key** (`sb_secret_…`) or the legacy `service_role` JWT — either works. See
+> [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026)
+> for the full picture.
 
 ---
 
 ## Layer 1 — AI Agents via Edge Functions (HTTPS)
 
 This is the primary integration layer for AI clients. Nine Supabase Edge Functions are
-deployed on the Supabase platform and are reachable over HTTPS with nothing more than the
-**legacy anon JWT** (a public-facing JWT, `eyJ…`). The Supabase gateway validates the key
-before any request reaches a function; individual functions then use the service-role key
-internally to call Postgres RPCs. Your anon key is never elevated to database-level access.
-
-> ⚠️ Use the **legacy anon JWT** here, not the new `sb_publishable_…` key. The Edge
-> Function gateway rejects non-JWT keys with `UNAUTHORIZED_INVALID_JWT_FORMAT`. See
-> [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026)
-> for why.
+deployed on the Supabase platform and are reachable over HTTPS with the **Cerefox access
+token** (`cfx_pat_…`) as a Bearer token. Each function is deployed `--no-verify-jwt` and
+**authenticates the token in-function** (constant-time compare against the accepted set); it
+then uses the service-role key internally to call Postgres RPCs. The token grants Edge
+Function access only — it is never elevated to database-level access, and the service-role key
+never leaves the server.
+
+> ⚠️ The credential here is the **Cerefox access token**, not a Supabase key. Generate it with
+> `cerefox token generate` (it sets the `CEREFOX_ACCESS_TOKENS` Function secret and writes
+> `CEREFOX_ACCESS_TOKEN` to your local `.env`). The legacy Supabase anon JWT is retired for
+> Edge Function auth as of iter-28E. See
+> [`setup-supabase.md` → Step 7](setup-supabase.md#step-7--oauth-for-cloud-agents-claudeai--mobile-optional).
 
 ### The nine Edge Functions
 
@@ -37,7 +41,7 @@ internally to call Postgres RPCs. Your anon key is never elevated to database-le
 | `cerefox-get-audit-log` | Query audit log entries with filters |
 | `cerefox-metadata-search` | Query documents by metadata key-value criteria without text search |
 | `cerefox-list-projects` | List all projects with names, IDs, and descriptions |
-| `cerefox-mcp` | Streamable HTTP MCP adapter — calls Postgres RPCs directly |
+| `cerefox-mcp` | Streamable HTTP MCP adapter — calls Postgres RPCs directly. **Also** an OAuth 2.1 protected resource for cloud/mobile Claude (optional — see "the OAuth variant" below) |
 
 ### How clients connect
 
@@ -46,10 +50,10 @@ the MCP Streamable HTTP protocol and calls the Postgres RPCs directly (no intern
 to the primitive Edge Functions). The client only ever talks to one URL.
 
 ```
-MCP client (anon key)
+MCP client (Cerefox token)
     │
     ▼
-cerefox-mcp
+cerefox-mcp   (in-function token check)
     │
     ▼ (service-role key, internal)
 Postgres RPCs
@@ -60,15 +64,46 @@ using an OpenAPI schema. `cerefox-mcp` is not involved (ChatGPT does not support
 Streamable HTTP MCP protocol).
 
 **curl / scripts / custom HTTP clients** can also call the primitives directly using the
-same anon key as a Bearer token.
+same Cerefox token as a Bearer token.
 
 ### Credentials needed
 
 - `CEREFOX_SUPABASE_URL` — your Supabase project URL
-- **Legacy anon JWT** — found in your Supabase dashboard under **Project Settings → API Keys → Legacy → anon**. (Do not use the new `sb_publishable_…` key — gateway constraint.)
+- **Cerefox access token** (`cfx_pat_…`) — generate it with `cerefox token generate`. It is a
+  random, Cerefox-managed secret (not a Supabase key), validated in-function on every Edge
+  Function call.
 
 See `docs/guides/connect-agents.md` for step-by-step setup per client.
 
+### The OAuth variant of `cerefox-mcp` — cloud & mobile Claude (optional)
+
+claude.ai web and the Claude mobile app **cannot** send a static Bearer token — a custom
+connector there requires **OAuth**. As an optional feature (iter-28A), `cerefox-mcp` is
+therefore *also* an OAuth 2.1 protected resource, so those clients get the same full
+tool surface. Nothing else in Layer 1 changes, and you can ignore this entirely if you
+don't use cloud/mobile Claude.
+
+How it differs from the static-token path:
+
+- **Two accepted credentials.** `cerefox-mcp` authenticates each request itself
+  (`_shared/mcp-auth/`), accepting **either** a valid OAuth 2.1 access token (verified
+  against the project **JWKS**, with the token's `sub` pinned to `CEREFOX_OAUTH_OWNER_ID`)
+  **or** the static **Cerefox access token** (constant-time compare, the same token the
+  static-Bearer clients use). All nine data Edge Functions are deployed `--no-verify-jwt` and
+  do their token check in-function; `cerefox-mcp` additionally supports the OAuth arm.
+- **Supabase is the authorization server.** The OAuth flow uses Supabase's native OAuth 2.1
+  Server. The one piece that must serve HTML — the **consent page** — is a free **Cloudflare
+  Worker** (`cloudflare/cerefox-consent/`), because a Supabase Edge Function can't serve
+  `text/html` on the default `*.supabase.co` domain.
+- **The owner pin is the authorization boundary.** `CEREFOX_OAUTH_OWNER_ID` (the owner
+  user's UUID) is a server-side value — never entered into any client — and only tokens
+  whose `sub` matches it are accepted.
+
+Config: `CEREFOX_OAUTH_OWNER_ID` (owner pin), a pre-registered OAuth App using
+**`client_secret_post`**, and the Cloudflare Worker (public project URL + publishable key
+baked in). Setup: [`setup-supabase.md` → Step 7](setup-supabase.md#step-7--oauth-for-cloud-agents-claudeai--mobile-optional).
+Design: [`docs/specs/oauth-mcp-server-design.md`](../specs/oauth-mcp-server-design.md).
+
 ---
 
 ## Layer 2 — Web UI and CLI via Supabase REST
@@ -177,10 +212,11 @@ single container with an internally-held token.
 
 | Caller | Transport | Auth credential | Typical use |
 |---|---|---|---|
-| Claude Code / Cursor | HTTPS → `cerefox-mcp` | Legacy anon JWT | Daily AI assistant access |
-| Claude Desktop | HTTPS → `cerefox-mcp` (via `supergateway`) | Legacy anon JWT | Daily AI assistant access |
-| ChatGPT Custom GPT | HTTPS → primitive Edge Functions | Legacy anon JWT | AI assistant via GPT Actions |
-| curl / HTTP scripts | HTTPS → primitive Edge Functions | Legacy anon JWT | Ad-hoc queries, automation |
+| Claude Code / Cursor | HTTPS → `cerefox-mcp` | Cerefox access token (`cfx_pat_…`) | Advanced/fallback; prefer local MCP for daily use |
+| Claude Desktop | HTTPS → `cerefox-mcp` (via `supergateway`) | Cerefox access token (`cfx_pat_…`) | Advanced/fallback; prefer local MCP for daily use |
+| **Cloud Claude (claude.ai web + mobile)** | HTTPS → `cerefox-mcp` over **OAuth 2.1** | Owner-pinned OAuth access token (JWKS-verified) | Optional; memory in the browser + on the phone |
+| ChatGPT Custom GPT | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | AI assistant via GPT Actions |
+| curl / HTTP scripts | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | Ad-hoc queries, automation |
 | Web UI (`cerefox web`) | Supabase REST API | Secret key (or legacy service_role) | Web UI backend (TS Hono) |
 | `cerefox` CLI (human) | Supabase REST API | Secret key (or legacy service_role) | Ingestion, search, reindex, backup |
 | Local coding agent via `cerefox` CLI | Supabase REST API | Secret key (or legacy service_role) | User-authorised agent (Claude Code, Codex CLI, opencode, OpenClaw, Hermes, …) acting on user's behalf via Bash tool |
@@ -188,11 +224,26 @@ single container with an internally-held token.
 
 ### Key security principle
 
-The (legacy) anon JWT is safe to share with AI agents and client applications — it can
-only call the operations exposed by the Edge Functions, and the Supabase gateway
-rate-limits and validates it. The secret key / `service_role` JWT and the database
-password must never be embedded in client-facing configuration or committed to the
-repository.
+The **Cerefox access token** (`cfx_pat_…`) is the **Edge Function credential**. It authenticates
+to the Edge Functions (which run business logic with the service-role key internally); each
+function validates it in-function and Supabase rate-limits the request. **It is not RLS-scoped**
+— any holder can call the full EF tool surface (read *and* write). So treat it as a shared
+secret for *trusted* agents/clients — keep it in local configs, but do **not** publish it on a
+public web page. Unlike the retired legacy anon JWT (which was revoke-only on ES256-migrated
+projects), the Cerefox token is **rotatable** with zero downtime via `cerefox token rotate`.
+
+> **Schema 0.7.0 hardening:** the `cerefox_*` RPCs are `SECURITY DEFINER` and previously
+> had broader-than-intended `EXECUTE` grants. They now grant `EXECUTE` only to
+> `service_role` (which every legitimate caller uses) — revoked from `anon`/`authenticated`/
+> `PUBLIC`. A security hardening; run `cerefox server deploy` to apply. See
+> [`docs/specs/security-model.md`](../specs/security-model.md).
+
+The **publishable** key (`sb_publishable_…`) is genuinely public-safe: the EF gateway
+rejects it and (post-0.7.0) it cannot call the RPCs either, so it grants no KB access — it
+only reaches Supabase Auth. That's why the OAuth consent page embeds it, not the anon JWT.
+
+The secret key / `service_role` JWT and the database password must never be embedded in
+client-facing configuration or committed to the repository.
 
 ---
 
@@ -233,7 +284,7 @@ So the access model is:
    is therefore always possible until the human explicitly chooses purge.
 
 A `cerefox purge-doc` CLI command, a `cerefox_purge_document` MCP tool, or a
-`/documents/{id}/purge` HTTP endpoint accessible via the anon JWT would each break this
+`/documents/{id}/purge` HTTP endpoint accessible via the Cerefox token would each break this
 property. **Do not add them without a governance design that replaces the human-in-the-
 loop step with an equivalent guard** (e.g. a "purge approval queue" the web UI must
 clear before the operation actually runs).

package/docs/guides/cli.md

@@ -539,6 +539,34 @@ Detects fresh vs. existing databases: a fresh DB gets schema + RPCs + migration
 
 ---
 
+### `cerefox token generate` / `cerefox token rotate` / `cerefox token list`
+
+**Purpose**: manage the **Cerefox access token** (`cfx_pat_…`) — the Bearer credential that
+callers present to the Edge Functions (remote MCP, GPT Actions, direct HTTP). It replaces the
+retired legacy anon JWT (iter-28E). The token is validated in-function; the accepted set lives
+in the `CEREFOX_ACCESS_TOKENS` Supabase Function secret, and the value this machine presents is
+`CEREFOX_ACCESS_TOKEN` in local `.env`.
+
+**Synopsis**:
+```
+cerefox token generate           # mint a token, set it on Supabase, write it to local .env
+cerefox token rotate             # add a new token (accepted set becomes [new, old]) — zero downtime
+cerefox token rotate --finalize  # drop the old token once every client is on the new one
+cerefox token list               # show masked fingerprints of the accepted set (never the value)
+```
+
+- `generate` prints the token **once** (it's a secret — reprints are impossible; lose it → `rotate`),
+  sets the `CEREFOX_ACCESS_TOKENS` Function secret, and upserts `CEREFOX_ACCESS_TOKEN` into your
+  local `.env` (backs the file up; warns if `.env` isn't gitignored; `--no-env` skips the write).
+- `rotate` widens the accepted set to `[new, old]` so clients cut over with no downtime;
+  `rotate --finalize` removes the old token afterward.
+- Paste the token into each client per [`connect-agents.md`](connect-agents.md): the Custom GPT's
+  Actions → Authentication (Bearer), or the remote-MCP client header.
+- Run `token generate` **before** a token-gated `cerefox server deploy` — deploying token-gated
+  Edge Functions with no token set locks every caller out.
+
+---
+
 ### `cerefox config list` / `cerefox config get` / `cerefox config set`
 
 **Purpose**: read/write runtime config in `cerefox_config` (e.g. `usage_tracking_enabled`, `require_requestor_identity`).
@@ -607,6 +635,7 @@ These flat commands handle install, configuration, and health. Run any with `--h
 | `cerefox doctor` | Diagnose the install (credentials, DB reachability, schema version). |
 | `cerefox status` | Show connection + schema status. |
 | `cerefox configure-agent --tool <client>` | Write MCP client config (`claude-code`, `claude-desktop`, `cursor`, `codex`, `gemini`). |
+| `cerefox token generate` / `rotate` / `list` | Manage the Cerefox access token (`cfx_pat_…`) — the Edge Function Bearer credential (remote MCP, GPT Actions, curl). See the [`cerefox token`](#cerefox-token-generate--cerefox-token-rotate--cerefox-token-list) section above. |
 | `cerefox self-update` | Update the installed `@cerefox/memory` package. |
 | `cerefox completion` | Emit a shell completion script. |
 | `cerefox backup create` / `cerefox backup restore` | File-system backup / restore of the knowledge base (see [`ops-scripts.md`](ops-scripts.md)). |

package/docs/guides/configuration.md

@@ -39,11 +39,14 @@ Full rule documented in [`docs/specs/polish-and-distribution-design.md` §7](../
 |----------|---------|----------|-------------|
 | `CEREFOX_SUPABASE_URL` | `""` | For app | Supabase project URL. Found in: Project Settings → API → Project URL |
 | `CEREFOX_SUPABASE_KEY` | `""` | For app | New **secret key** (`sb_secret_…`) from Project Settings → API Keys → Secret key. Legacy `service_role` JWT also works. **Keep secret.** See [`setup-supabase.md` → Supabase API keys (2026)](setup-supabase.md#supabase-api-keys-2026). |
-| `CEREFOX_SUPABASE_ANON_KEY` | `""` | For Edge Functions / e2e | **Legacy anon JWT** (`eyJ…`), under "Legacy" in Project Settings → API Keys. Used as Bearer token for Edge Function / MCP / GPT Action calls. The new `sb_publishable_…` key fails at the Edge Function gateway and cannot replace this. See [`setup-supabase.md`](setup-supabase.md#supabase-api-keys-2026). |
+| `CEREFOX_ACCESS_TOKEN` | `""` | For Edge Functions / e2e | **Cerefox access token** (`cfx_pat_…`), the single token this machine presents. Written to local `.env` by `cerefox token generate`. Used as the `Authorization: Bearer …` credential for remote MCP / GPT Actions / direct Edge Function calls, and read by `cerefox doctor` + the live e2e tests. Rotatable via `cerefox token rotate`. |
+| `CEREFOX_ACCESS_TOKENS` | `""` | Server-side (Function secret) | The **server-side accepted set** — a comma-separated list of Cerefox tokens, set as a Supabase **Function secret** (not local `.env`). A request is accepted if its Bearer matches any token in the set, enabling zero-downtime rotation. Managed by `cerefox token generate` / `rotate`. |
+| `CEREFOX_SUPABASE_ANON_KEY` | `""` | *(deprecated / unused)* | Formerly the legacy anon JWT Bearer for Edge Function calls. **Retired in iter-28E** — Edge Functions now authenticate the Cerefox access token in-function. Retained only so an old `.env` still parses; no longer read. |
 | `CEREFOX_DATABASE_URL` | `""` | For scripts | Direct Postgres URL for deployment scripts. **Use the Session Pooler** (port `5432`) — Transaction Pooler (`6543`) does not support DDL. Username must include the project-ref suffix (`postgres.<project-ref>`). Append `?sslmode=require`. See [`setup-supabase.md` → Connection pooling (2026)](setup-supabase.md#connection-pooling-2026). |
 
 **When each is needed:**
 - `CEREFOX_SUPABASE_URL` + `CEREFOX_SUPABASE_KEY` — used by the CLI, web UI, and local MCP server (ingestion, search) via the Supabase Data API
+- `CEREFOX_ACCESS_TOKEN` — used to call the Edge Functions (remote MCP, GPT Actions, direct HTTP) and by `cerefox doctor` / the live e2e tests; `CEREFOX_ACCESS_TOKENS` is its server-side counterpart (the accepted set). Generate both with `cerefox token generate`.
 - `CEREFOX_DATABASE_URL` — used only for schema deploys (`cerefox server deploy`, or the contributor scripts `bun scripts/db_*.ts`) via a direct Postgres connection
 
 ---