@cerefox/memory 1.10.1 → 1.11.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 (11) hide show
  1. package/dist/bin/cerefox.js +208 -48
  2. package/dist/frontend/assets/{index-i67RH1VY.js → index-sef54G6W.js} +26 -26
  3. package/dist/frontend/assets/index-sef54G6W.js.map +1 -0
  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 +27 -3
  10. package/package.json +1 -1
  11. package/dist/frontend/assets/index-i67RH1VY.js.map +0 -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-sef54G6W.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.11.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.11.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** — loopback-bound by default | 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
@@ -441,7 +441,7 @@ Each usage log entry records:
441
441
  | Field | Description |
442
442
  |-------|-------------|
443
443
  | `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` |
444
+ | `access_path` | Where the call came from: `remote-mcp`, `local-mcp`, `edge-function`, `webapp`, `cli`, `api` |
445
445
  | `requestor` | Who made the call: agent name (e.g., "Claude Code", "mcp-agent") or "user" for webapp/CLI |
446
446
  | `document_id` | Optional: which document was accessed (for get_document, list_versions) |
447
447
  | `project_id` | Optional: which project was filtered on |
@@ -452,7 +452,7 @@ Each usage log entry records:
452
452
  The `access_path` is set by the caller layer (not the end user):
453
453
  - Edge Functions set `"edge-function"` (GPT Actions, direct HTTP callers)
454
454
  - `cerefox-mcp` tool handlers set `"remote-mcp"` (Claude Code, Cursor, Claude Desktop)
455
- - The web UI's JSON API routes set `"webapp"`
455
+ - 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
456
  - Local MCP server sets `"local-mcp"`
457
457
  - CLI sets `"cli"` for read/search commands
458
458
 
@@ -477,10 +477,34 @@ optional. When omitted, it defaults to `"mcp-agent"`. This means the usage log s
477
477
  `"mcp-agent"` for all calls that don't explicitly identify themselves, making analytics
478
478
  less useful in multi-agent setups.
479
479
 
480
- You can optionally enforce caller identification so that all MCP tool calls must include
480
+ You can optionally enforce caller identification so that MCP tool calls must include
481
481
  a requestor/author identity. Calls without identity receive a JSON-RPC `-32602` error
482
482
  with a helpful message telling the agent what to provide.
483
483
 
484
+ ### What it actually covers
485
+
486
+ **These two settings are enforced by the Edge Functions only.** Each of the nine
487
+ Edge Functions carries the check, including `cerefox-mcp`, which is the **remote**
488
+ MCP transport. Nothing else does:
489
+
490
+ | Surface | Enforced? |
491
+ |---|---|
492
+ | Edge Functions (GPT Actions, direct HTTP) | Yes |
493
+ | Remote MCP (`cerefox-mcp` Edge Function) | Yes |
494
+ | **Local MCP** (`cerefox mcp`, stdio) | **No** |
495
+ | **`/api/v1`** (`cerefox web`, Cerefox Local) | **No** |
496
+ | CLI | **No** |
497
+
498
+ This is stated plainly because the setting's name promises more than it
499
+ delivers: enabling it does not make identity required everywhere, and an
500
+ operator who assumes otherwise has a gap exactly where their local agents are.
501
+ The reason it is scoped this way is that the Edge Functions are the
502
+ internet-facing surface, while the local surfaces are already reachable only by
503
+ whoever is on the machine.
504
+
505
+ If you need it everywhere, that is a shared helper every transport calls, not a
506
+ tenth copy of the same block. Raise an issue rather than assuming it is there.
507
+
484
508
  ### Enabling enforcement
485
509
 
486
510
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cerefox/memory",
3
- "version": "1.10.1",
3
+ "version": "1.11.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",