@cerefox/memory 1.10.1 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/dist/bin/cerefox.js +998 -220
  2. package/dist/frontend/assets/{index-i67RH1VY.js → index-P1F2Ldl9.js} +25 -25
  3. package/dist/frontend/assets/{index-i67RH1VY.js.map → index-P1F2Ldl9.js.map} +1 -1
  4. package/dist/frontend/index.html +1 -1
  5. package/dist/server-assets/_shared/ef-meta/index.ts +3 -3
  6. package/dist/server-assets/_shared/mcp-tools/access-paths.ts +51 -0
  7. package/dist/server-assets/_shared/mcp-tools/types.ts +13 -14
  8. package/docs/guides/access-paths.md +1 -0
  9. package/docs/guides/configuration.md +29 -3
  10. package/package.json +1 -1
package/dist/frontend/index.html CHANGED
@@ -15,7 +15,7 @@
15
15
  href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
16
16
  />
17
17
  <title>Cerefox</title>
18
- <script type="module" crossorigin src="/app/assets/index-i67RH1VY.js"></script>
18
+ <script type="module" crossorigin src="/app/assets/index-P1F2Ldl9.js"></script>
19
19
  <link rel="stylesheet" crossorigin href="/app/assets/index-Dm_zCch4.css">
20
20
  </head>
21
21
  <body>
package/dist/server-assets/_shared/ef-meta/index.ts CHANGED
@@ -18,7 +18,7 @@
18
18
  * doesn't touch `supabase/functions/` leaves it alone).
19
19
  */
20
20
 
21
- export const EF_VERSION = "1.10.1";
21
+ export const EF_VERSION = "1.12.0";
22
22
 
23
23
  /**
24
24
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.10.1";
36
36
  * is imported by the Deno Edge Functions, which cannot reach into the npm
37
37
  * package.
38
38
  */
39
- export const CEREFOX_VERSION = "1.10.1";
39
+ export const CEREFOX_VERSION = "1.12.0";
40
40
 
41
41
  /**
42
42
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.10.1";
46
46
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
47
47
  * uses it to stay silent on label-only drift.
48
48
  */
49
- export const EF_LAST_CHANGED = "1.10.1";
49
+ export const EF_LAST_CHANGED = "1.11.0";
50
50
 
51
51
  /**
52
52
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp
package/dist/server-assets/_shared/mcp-tools/access-paths.ts ADDED
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The `access_path` vocabulary — a dependency-free leaf module so the frontend
3
+ * can import it through the `@cerefox/access-paths` vite alias (same pattern
4
+ * as `@cerefox/audit-ops` and `@cerefox/schemas`) without dragging server-side
5
+ * helpers into the bundle. `_shared/mcp-tools/types.ts` re-exports the type
6
+ * for Node/Deno consumers; there is exactly ONE definition.
7
+ *
8
+ * **Why this is a shared const and not three literals** (iter-40, #226): the
9
+ * domain was previously written out by hand in three places — the `AccessPath`
10
+ * union here, `deriveAccessPathStats()` in the frontend, and the Analytics
11
+ * page's filter dropdown. A hand-maintained list that must match another
12
+ * hand-maintained list drifts; on this project that exact shape produced the
13
+ * missing RLS table, the unguarded test suites, and the Edge Function bundle
14
+ * allow-list. Adding `"api"` would have been the fourth instance.
15
+ *
16
+ * Now the union is derived from this array, and the frontend's label map is a
17
+ * `Record<AccessPath, string>`, so a value added here that is not given a
18
+ * label fails the frontend typecheck rather than quietly vanishing from a
19
+ * dropdown. `deriveAccessPathStats()` still resolves by name on purpose (an
20
+ * unknown path must not silently inflate the agent total) and is covered by
21
+ * its own tests.
22
+ *
23
+ * There is deliberately NO database CHECK on `cerefox_usage_log.access_path`
24
+ * (verified: the column is free text). This type is the guard.
25
+ */
26
+
27
+ /**
28
+ * Logical channels through which a Cerefox operation can reach the backend.
29
+ *
30
+ * - `remote-mcp` — `cerefox-mcp` Edge Function (HTTP MCP transport).
31
+ * - `local-mcp` — `@cerefox/memory`'s stdio MCP bin.
32
+ * - `cli` — the `cerefox` CLI bin.
33
+ * - `webapp` — `/api/v1` called by the bundled web UI, i.e. a caller
34
+ * that supplied no identity of its own.
35
+ * - `edge-function` — a primitive Cerefox Edge Function (GPT Actions,
36
+ * direct HTTP).
37
+ * - `api` — `/api/v1` called by something that named itself
38
+ * (#226). Derived from the presence of caller identity,
39
+ * never accepted from the request; see
40
+ * `packages/memory/src/web/identity.ts`.
41
+ */
42
+ export const ACCESS_PATHS = [
43
+ "remote-mcp",
44
+ "local-mcp",
45
+ "cli",
46
+ "webapp",
47
+ "edge-function",
48
+ "api",
49
+ ] as const;
50
+
51
+ export type AccessPath = (typeof ACCESS_PATHS)[number];
package/dist/server-assets/_shared/mcp-tools/types.ts CHANGED
@@ -16,6 +16,8 @@
16
16
  * each consumer; the handlers themselves are runtime-agnostic.
17
17
  */
18
18
 
19
+ import type { AccessPath } from "./access-paths.ts";
20
+
19
21
  /** Structural type for the Supabase client surface the handlers actually
20
22
  * use (`.rpc()` + `.from()`). We deliberately don't `import { SupabaseClient }
21
23
  * from "@supabase/supabase-js"` here because Bun workspaces install a
@@ -42,23 +44,20 @@ export type JsonSchema = Record<string, unknown>;
42
44
 
43
45
  /**
44
46
  * Logical channel through which a Cerefox operation reached the backend.
45
- * Recorded in `cerefox_usage_log.access_path` so the analytics dashboard
46
- * can attribute load to each surface.
47
+ * Recorded in `cerefox_usage_log.access_path` so the analytics dashboard can
48
+ * attribute load to each surface.
47
49
  *
48
- * Values:
49
- * - `remote-mcp` — `cerefox-mcp` Edge Function (HTTP MCP transport).
50
- * - `local-mcp` — `@cerefox/memory`'s `cerefox-mcp` stdio bin.
51
- * - `cli` — the `cerefox` CLI bin (v0.5+). Mirrors the
52
- * Python CLI's `access_path = "cli"`.
50
+ * **Defined once** in the dependency-free leaf `./access-paths.ts`, and
51
+ * re-exported here so server-side callers keep importing it from `types.ts`.
52
+ * The values, and why the definition moved, are documented there.
53
53
  *
54
- * Adding a new channel here also requires updating
55
- * `cerefox_usage_log.access_path`'s documented domain (no DB CHECK exists —
56
- * verified in review; the column is free text and this type is the guard).
54
+ * Adding a channel means adding it to `ACCESS_PATHS` and then to
55
+ * `deriveAccessPathStats()` in the frontend, which resolves paths by exact
56
+ * name and deliberately ignores unknown ones. A value added to the vocabulary
57
+ * but not to the deriver is stored, charted, and invisible on the dashboard.
57
58
  */
58
- // The documented access_path domain (CLAUDE.md → usage tracking) — the type
59
- // had lagged at the three MCP-era values while webapp/edge-function callers
60
- // logged through wider-typed wrappers.
61
- export type AccessPath = "remote-mcp" | "local-mcp" | "cli" | "webapp" | "edge-function";
59
+ export type { AccessPath };
60
+ export { ACCESS_PATHS } from "./access-paths.ts";
62
61
 
63
62
  export interface ToolContext {
64
63
  /** OpenAI/Fireworks API key for tools that need to embed (search, ingest).
package/docs/guides/access-paths.md CHANGED
@@ -216,6 +216,7 @@ single container with an internally-held token.
216
216
  | ChatGPT Custom GPT | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | AI assistant via GPT Actions |
217
217
  | curl / HTTP scripts | HTTPS → primitive Edge Functions | Cerefox access token (`cfx_pat_…`) | Ad-hoc queries, automation |
218
218
  | Web UI (`cerefox web`) | Supabase REST API | Secret key (or legacy service_role) | Web UI backend (TS Hono) |
219
+ | **HTTP client → `/api/v1`** | Plain HTTP to `cerefox web` / Cerefox Local | **None from loopback; API key otherwise** (v1.12.0) — `cerefox api-key generate` / `cerefox-local api-key` | A local program or bot harness that wants HTTP rather than MCP. Names itself with `X-Cerefox-Author` / `X-Cerefox-Requestor` (v1.11.0): a declared label for attribution, not a verified identity. See [`api.md`](api.md) |
219
220
  | `cerefox` CLI (human) | Supabase REST API | Secret key (or legacy service_role) | Ingestion, search, reindex, backup |
220
221
  | 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 |
221
222
  | `cerefox server deploy` / deployment scripts | Direct TCP | DB password | Schema deploy, data restore |
package/docs/guides/configuration.md CHANGED
@@ -43,6 +43,8 @@ Full rule documented in [`docs/specs/polish-and-distribution-design.md` §7](../
43
43
  | `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`. |
44
44
  | `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. |
45
45
  | `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). |
46
+ | `CEREFOX_API_KEY` | `""` | Local web server (#229) | **Local API key** (`cfx_lak_…`) for `/api/v1` and `/rest/v1` on the machine running `cerefox web`. Callers on **loopback need no credential**; callers arriving on any other interface must send `Authorization: Bearer <key>`. Unset means the gate is off and the server behaves exactly as it did before v1.12.0 — so upgrading never breaks a working install. Minted by `cerefox api-key generate`; Cerefox Local mints its own at first boot (`cerefox-local api-key`). **Never sent to Supabase**; distinct from `CEREFOX_ACCESS_TOKEN`, which is the *cloud* credential for the Edge Functions. |
47
+ | `CEREFOX_API_REQUIRE_KEY` | `""` | Local web server (#229) | Set to `1` to demand the API key from **every** caller, loopback included. The one topology that needs it: a same-host reverse proxy, which reconnects from `127.0.0.1`, so every proxied request would otherwise look local and be exempt. `X-Forwarded-For` is deliberately never consulted to recover the original address — it is caller-supplied, so trusting it would let anyone claim to be local. Has no effect when `CEREFOX_API_KEY` is unset (demanding a key that does not exist would lock you out of your own server). |
46
48
  | `SUPABASE_ACCESS_TOKEN` | *(unset)* | For EF deploys (optional) | Supabase **personal access token** (`sbp_…`, from [supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens)), read by the **Supabase CLI** that `cerefox server deploy` shells out to for Edge Function deploys. Optional — without it the CLI falls back to its `supabase login` credential, which on **macOS lives in the Keychain and triggers a password dialog per function deploy** (9 per full deploy; a denied dialog fails that function with `LegacyPlatformAuthRequiredError`). Setting it in `~/.cerefox/.env` avoids the dialogs entirely: Cerefox exports every key from its `.env` to the environment, so the child CLI inherits it. Not a `CEREFOX_` variable — the name is the Supabase CLI's own. **Keep secret** (it grants management access to your Supabase account). |
47
49
 
48
50
  **When each is needed:**
@@ -441,7 +443,7 @@ Each usage log entry records:
441
443
  | Field | Description |
442
444
  |-------|-------------|
443
445
  | `operation` | What was called: `search`, `metadata_search`, `get_document`, `list_versions`, `get_audit_log`, `list_metadata_keys`, `list_projects` |
444
- | `access_path` | Where the call came from: `remote-mcp`, `local-mcp`, `edge-function`, `webapp`, `cli` |
446
+ | `access_path` | Where the call came from: `remote-mcp`, `local-mcp`, `edge-function`, `webapp`, `cli`, `api` |
445
447
  | `requestor` | Who made the call: agent name (e.g., "Claude Code", "mcp-agent") or "user" for webapp/CLI |
446
448
  | `document_id` | Optional: which document was accessed (for get_document, list_versions) |
447
449
  | `project_id` | Optional: which project was filtered on |
@@ -452,7 +454,7 @@ Each usage log entry records:
452
454
  The `access_path` is set by the caller layer (not the end user):
453
455
  - Edge Functions set `"edge-function"` (GPT Actions, direct HTTP callers)
454
456
  - `cerefox-mcp` tool handlers set `"remote-mcp"` (Claude Code, Cursor, Claude Desktop)
455
- - The web UI's JSON API routes set `"webapp"`
457
+ - The web UI's JSON API routes set `"webapp"` when the caller sends no identity, and `"api"` when it names itself with `X-Cerefox-Author` / `X-Cerefox-Requestor` (v1.11.0; see [`api.md`](api.md)). The path is derived, never accepted from the caller.
456
458
  - Local MCP server sets `"local-mcp"`
457
459
  - CLI sets `"cli"` for read/search commands
458
460
 
@@ -477,10 +479,34 @@ optional. When omitted, it defaults to `"mcp-agent"`. This means the usage log s
477
479
  `"mcp-agent"` for all calls that don't explicitly identify themselves, making analytics
478
480
  less useful in multi-agent setups.
479
481
 
480
- You can optionally enforce caller identification so that all MCP tool calls must include
482
+ You can optionally enforce caller identification so that MCP tool calls must include
481
483
  a requestor/author identity. Calls without identity receive a JSON-RPC `-32602` error
482
484
  with a helpful message telling the agent what to provide.
483
485
 
486
+ ### What it actually covers
487
+
488
+ **These two settings are enforced by the Edge Functions only.** Each of the nine
489
+ Edge Functions carries the check, including `cerefox-mcp`, which is the **remote**
490
+ MCP transport. Nothing else does:
491
+
492
+ | Surface | Enforced? |
493
+ |---|---|
494
+ | Edge Functions (GPT Actions, direct HTTP) | Yes |
495
+ | Remote MCP (`cerefox-mcp` Edge Function) | Yes |
496
+ | **Local MCP** (`cerefox mcp`, stdio) | **No** |
497
+ | **`/api/v1`** (`cerefox web`, Cerefox Local) | **No** |
498
+ | CLI | **No** |
499
+
500
+ This is stated plainly because the setting's name promises more than it
501
+ delivers: enabling it does not make identity required everywhere, and an
502
+ operator who assumes otherwise has a gap exactly where their local agents are.
503
+ The reason it is scoped this way is that the Edge Functions are the
504
+ internet-facing surface, while the local surfaces are already reachable only by
505
+ whoever is on the machine.
506
+
507
+ If you need it everywhere, that is a shared helper every transport calls, not a
508
+ tenth copy of the same block. Raise an issue rather than assuming it is there.
509
+
484
510
  ### Enabling enforcement
485
511
 
486
512
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cerefox/memory",
3
- "version": "1.10.1",
3
+ "version": "1.12.0",
4
4
  "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://github.com/fstamatelopoulos/cerefox",