@remnic/core 9.4.2 → 9.5.0

package/src/access-token-capabilities.ts

@@ -0,0 +1,391 @@
+/**
+ * Per-token capabilities (issue #1837).
+ *
+ * A token entry MAY carry an explicit, versioned capabilities record. The
+ * record's PRESENCE is mechanically detectable, which is load-bearing for
+ * security:
+ *
+ *   - ABSENT `capabilities` field ⇒ a PRE-FEATURE legacy entry (minted
+ *     before this feature). It is UNRESTRICTED — full access — purely for
+ *     backward compatibility. This is the ONLY path by which "full access"
+ *     is granted by omission.
+ *
+ *   - PRESENT `capabilities` record (always carries a `version` marker) ⇒ a
+ *     token minted by the capability-aware path. Even a new token minted
+ *     without `--ops`/`--namespaces` records an EXPLICIT unrestricted record
+ *     (`{ version: 1 }`) — a deliberate, auditable choice, never an
+ *     accidentally-omitted field. Within the record, the two axes follow
+ *     absent-vs-present semantics:
+ *       * axis ABSENT (e.g. no `ops` key)        ⇒ unrestricted on that axis.
+ *       * axis PRESENT and empty (`ops: []`)     ⇒ deny all (fail-closed).
+ *       * axis PRESENT and non-empty             ⇒ allow only the listed values.
+ *
+ * Malformed capability input at mint time (bad version, non-array axes,
+ * non-string elements, unknown op names against the catalog, malformed
+ * namespace values) is REJECTED — a token is never created from invalid
+ * input (rule: invalid input rejected, not defaulted).
+ *
+ * This module owns the pure capability logic (shape validation, allow-list
+ * checks) and the per-request AsyncLocalStorage carrying the presenting
+ * token's resolved capabilities down to the access boundary. It imports
+ * nothing else in the package except the forbidden-error class, so it can be
+ * reused by the token store, the boundary, and the HTTP/MCP surfaces without
+ * cycles.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { EngramAccessForbiddenError } from "./access-errors.js";
+
+/** Current capability-record schema version. */
+export const TOKEN_CAPABILITIES_VERSION = 1 as const;
+
+/**
+ * Versioned capabilities record stored on a token entry. Presence of this
+ * record (vs. an absent field) is what distinguishes a capability-aware
+ * token from a pre-feature legacy entry.
+ */
+export interface TokenCapabilities {
+  readonly version: typeof TOKEN_CAPABILITIES_VERSION;
+  /**
+   * Operations allow-list. `undefined` (key absent) ⇒ unrestricted on this
+   * axis. `[]` ⇒ deny all ops (fail-closed). Non-empty ⇒ allow only listed.
+   */
+  ops?: string[];
+  /**
+   * Namespaces allow-list. `undefined` ⇒ unrestricted. `[]` ⇒ deny all.
+   * Non-empty ⇒ allow only listed.
+   */
+  namespaces?: string[];
+}
+
+/**
+ * Namespace value validation. Namespace identifiers are flexible (default,
+ * team, self, principal-prefixed, project-prefixed) but must never contain
+ * whitespace, path separators, traversal segments, or control characters —
+ * such values are malformed at mint time and rejected, never silently
+ * coerced.
+ */
+const NAMESPACE_VALUE_MAX_LENGTH = 128;
+// Non-empty, no whitespace, no path separators, no control chars. `.` and
+// `..` are rejected separately so legitimate dotted names (e.g. a domain)
+// remain allowed while traversal is not.
+const NAMESPACE_VALUE_PATTERN = /^[^\s\/\\\x00-\x1F]+$/;
+
+/** True when `value` is an acceptable namespace allow-list entry. */
+export function isValidNamespaceValue(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0 || value.length > NAMESPACE_VALUE_MAX_LENGTH) {
+    return false;
+  }
+  if (!NAMESPACE_VALUE_PATTERN.test(value)) return false;
+  if (value === "." || value === "..") return false;
+  return true;
+}
+
+function isStringArray(value: unknown): value is unknown[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+function dedupeSort(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+/**
+ * Parse one axis (ops or namespaces) for PERSISTENCE/LOAD. Returns the
+ * cleaned array (deduped, sorted; possibly empty to preserve "present ⇒
+ * fail-closed") or `undefined` when the key is absent. Throws on a malformed
+ * shape (non-array, non-string elements, malformed namespace values). Op
+ * validation against the catalog happens only at mint time.
+ */
+function parseAxis(
+  obj: Record<string, unknown>,
+  key: "ops" | "namespaces",
+  validateValue: (v: unknown) => boolean,
+  valueLabel: string,
+): string[] | undefined {
+  if (!Object.prototype.hasOwnProperty.call(obj, key)) return undefined;
+  const value = obj[key];
+  if (value === undefined || value === null) return undefined;
+  if (!isStringArray(value)) {
+    throw new Error(`capabilities ${key} must be an array of non-empty strings`);
+  }
+  const cleaned: string[] = [];
+  for (const v of value) {
+    if (typeof v !== "string" || v.length === 0) {
+      throw new Error(`capabilities ${key} must be an array of non-empty strings`);
+    }
+    if (!validateValue(v)) {
+      throw new Error(`capabilities ${key} contains a malformed ${valueLabel}: ${JSON.stringify(v)}`);
+    }
+    cleaned.push(v);
+  }
+  // Preserve presence: an explicitly empty array stays [] (fail-closed),
+  // NOT coerced to undefined (which would mean unrestricted).
+  return dedupeSort(cleaned);
+}
+
+/**
+ * Normalize a capabilities record for PERSISTENCE/LOAD. Returns `undefined`
+ * ONLY when the record is entirely absent (a pre-feature legacy entry ⇒
+ * unrestricted). When present, an absent/`undefined` `version` is COERCED to
+ * the current default (1) — mirroring {@link validateCapabilitiesForMint} — so
+ * a record that mint-validated also load-normalizes without a schema throw.
+ * An explicitly-present WRONG version (not 1) is still rejected. Throws on a
+ * malformed record (non-object, explicitly-wrong version, malformed axes).
+ */
+export function normalizeCapabilities(raw: unknown): TokenCapabilities | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("capabilities must be an object with a version marker");
+  }
+  const obj = raw as Record<string, unknown>;
+  // Coerce absent/undefined version → 1, mirroring validateCapabilitiesForMint
+  // (version 1 is the only schema version; coercing keeps mint-validated
+  // records reloadable). Only an explicitly-present WRONG version throws.
+  if (obj.version !== undefined && obj.version !== TOKEN_CAPABILITIES_VERSION) {
+    throw new Error(`capabilities.version must be ${TOKEN_CAPABILITIES_VERSION}`);
+  }
+  const ops = parseAxis(obj, "ops", () => true, "operation");
+  const namespaces = parseAxis(obj, "namespaces", isValidNamespaceValue, "namespace");
+  const result: TokenCapabilities = { version: TOKEN_CAPABILITIES_VERSION };
+  if (ops !== undefined) result.ops = ops;
+  if (namespaces !== undefined) result.namespaces = namespaces;
+  return result;
+}
+
+/**
+ * Validate a capabilities record at MINT time. ALWAYS returns a versioned
+ * record (never `undefined`) so every newly-minted token carries an explicit
+ * capability decision — a new token can never gain full access by OMITTING
+ * the field. When `raw` is absent/null, the result is an explicit
+ * unrestricted record (`{ version: 1 }`), a deliberate/auditable choice. A
+ * present-but-`undefined` (or absent) `version` is coerced to the current
+ * default (1); an explicitly-wrong version is rejected. This version rule is
+ * identical to {@link normalizeCapabilities} (mint/load symmetry). Rejects
+ * unknown op names against the catalog and malformed namespace values;
+ * throws a plain Error — the caller must NOT create a token when this throws.
+ */
+export function validateCapabilitiesForMint(
+  raw: unknown,
+  validOps: readonly string[],
+): TokenCapabilities {
+  const result: TokenCapabilities = { version: TOKEN_CAPABILITIES_VERSION };
+  if (raw === undefined || raw === null) {
+    return result;
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("capabilities must be an object with optional ops/namespaces arrays");
+  }
+  const obj = raw as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(obj, "version") && obj.version !== undefined) {
+    if (obj.version !== TOKEN_CAPABILITIES_VERSION) {
+      throw new Error(`capabilities.version must be ${TOKEN_CAPABILITIES_VERSION}`);
+    }
+  }
+  const validOpSet = new Set(validOps);
+
+  if (Object.prototype.hasOwnProperty.call(obj, "ops") && obj.ops !== undefined && obj.ops !== null) {
+    if (!isStringArray(obj.ops)) {
+      throw new Error("capabilities ops must be an array of non-empty strings");
+    }
+    const ops = obj.ops as unknown[];
+    for (const v of ops) {
+      if (typeof v !== "string" || v.length === 0) {
+        throw new Error("capabilities ops must be an array of non-empty strings");
+      }
+    }
+    // Reject unknown op names against the catalog (unknown ⇒ reject, never drop).
+    const unknown = ops.filter((op) => typeof op === "string" && !validOpSet.has(op));
+    if (unknown.length > 0) {
+      throw new Error(
+        `capabilities ops contains unknown operation name(s): ${unknown.map((o) => JSON.stringify(o)).join(", ")}`,
+      );
+    }
+    // Preserve presence (empty stays [] ⇒ deny all ops).
+    result.ops = dedupeSort(ops as string[]);
+  }
+
+  if (
+    Object.prototype.hasOwnProperty.call(obj, "namespaces") &&
+    obj.namespaces !== undefined &&
+    obj.namespaces !== null
+  ) {
+    if (!isStringArray(obj.namespaces)) {
+      throw new Error("capabilities namespaces must be an array of non-empty strings");
+    }
+    const namespaces = obj.namespaces as unknown[];
+    for (const v of namespaces) {
+      if (typeof v !== "string" || v.length === 0) {
+        throw new Error("capabilities namespaces must be an array of non-empty strings");
+      }
+      if (!isValidNamespaceValue(v)) {
+        throw new Error(`capabilities namespaces contains a malformed namespace: ${JSON.stringify(v)}`);
+      }
+    }
+    result.namespaces = dedupeSort(namespaces as string[]);
+  }
+
+  return result;
+}
+
+/**
+ * True when `caps` imposes any restriction (a present record with at least
+ * one axis key). `undefined` (legacy / absent record) ⇒ unrestricted. A
+ * present `{ version: 1 }` record with no axes ⇒ also unrestricted (but
+ * auditable — it is a deliberate new-token decision, not omission).
+ */
+export function isCapabilityRestricted(caps: TokenCapabilities | undefined | null): boolean {
+  if (!caps) return false;
+  return caps.ops !== undefined || caps.namespaces !== undefined;
+}
+
+/**
+ * True when `caps` permits `op`.
+ *   - record ABSENT (legacy) ⇒ unrestricted (true).
+ *   - ops axis ABSENT        ⇒ unrestricted on this axis (true).
+ *   - ops axis PRESENT       ⇒ `op` must be listed; `[]` ⇒ false (deny all).
+ */
+export function capabilityAllowsOp(caps: TokenCapabilities | undefined | null, op: string): boolean {
+  if (caps?.ops === undefined) return true;
+  return caps.ops.includes(op);
+}
+
+/**
+ * True when `caps` permits `namespace`.
+ *   - record ABSENT / namespaces axis ABSENT ⇒ unrestricted (true).
+ *   - namespaces axis PRESENT ⇒ `namespace` must be listed; undefined
+ *     namespace ⇒ false; `[]` ⇒ false (deny all).
+ */
+export function capabilityAllowsNamespace(
+  caps: TokenCapabilities | undefined | null,
+  namespace: string | undefined,
+): boolean {
+  if (caps?.namespaces === undefined) return true;
+  if (namespace === undefined) return false;
+  return caps.namespaces.includes(namespace);
+}
+
+/**
+ * Throw {@link EngramAccessForbiddenError} when `caps` restricts ops and
+ * `op` is not permitted. No-op for unrestricted tokens.
+ */
+export function assertOperationAllowed(
+  caps: TokenCapabilities | undefined | null,
+  op: string,
+): void {
+  if (!capabilityAllowsOp(caps, op)) {
+    throw new EngramAccessForbiddenError(
+      `token is not permitted to call operation: ${op}`,
+    );
+  }
+}
+
+/**
+ * Throw {@link EngramAccessForbiddenError} when `caps` restricts namespaces
+ * and `namespace` is not permitted. No-op for unrestricted tokens.
+ */
+export function assertNamespaceAllowed(
+  caps: TokenCapabilities | undefined | null,
+  namespace: string | undefined,
+): void {
+  if (!capabilityAllowsNamespace(caps, namespace)) {
+    throw new EngramAccessForbiddenError(
+      namespace === undefined
+        ? "token is scoped to specific namespaces and this operation requires an explicit namespace"
+        : `token is not permitted to access namespace: ${namespace}`,
+    );
+  }
+}
+
+/**
+ * Resolve the EFFECTIVE namespace an operation runs against: a present,
+ * non-empty request namespace wins, otherwise the server default — the same
+ * resolution downstream storage applies
+ * (`getWritableStorageForNamespace(undefined)` → `defaultNamespace`). Empty
+ * strings are treated as absent. Centralized so every invocation surface
+ * (HTTP query/body, MCP `tools/call`, id-loaded records, legacy pairs that
+ * carry no namespace) applies ONE rule and none can dodge the check by
+ * dropping the param. (issue #1850)
+ */
+export function resolveEffectiveNamespace(
+  namespace: string | undefined,
+  defaultNamespace: string | undefined,
+): string | undefined {
+  const normalized = namespace !== undefined && namespace.length > 0 ? namespace : undefined;
+  return normalized ?? defaultNamespace;
+}
+
+/**
+ * The single effective-namespace allow-list chokepoint (issues #1837/#1850).
+ * Throws {@link EngramAccessForbiddenError} when `caps` carries a namespaces
+ * allow-list and the EFFECTIVE namespace (request value OR server default) is
+ * not a member. FAIL CLOSED:
+ *   - a scoped token whose allow-list does not cover the effective namespace
+ *     (explicit OR defaulted) is rejected;
+ *   - an absent server default (unconfigured) is also rejected for scoped
+ *     tokens, so omitting `?namespace=` can never bypass the allow-list.
+ * No-op for unrestricted tokens (no namespaces axis) so legacy/unrestricted
+ * behavior is unchanged. Both the HTTP transport (`resolveNamespace`) and the
+ * MCP dispatch route through this ONE function so no surface is missed.
+ */
+export function enforceNamespaceAllowList(
+  caps: TokenCapabilities | undefined | null,
+  namespace: string | undefined,
+  defaultNamespace: string | undefined,
+): void {
+  if (caps?.namespaces === undefined) return; // unrestricted token — unchanged
+  const effective = resolveEffectiveNamespace(namespace, defaultNamespace);
+  if (effective === undefined || !caps.namespaces.includes(effective)) {
+    throw new EngramAccessForbiddenError(
+      namespace === undefined
+        ? "token is scoped to specific namespaces; the server default namespace is not permitted — supply an allowed namespace"
+        : `token is not permitted to access namespace: ${namespace}`,
+    );
+  }
+}
+
+/**
+ * Fleet-wide / global maintenance operation guard (issue #1850 round 10).
+ *
+ * A distinct escalation class from the id-addressed routes (round 9) and the
+ * param-namespace ops (round 4): some boundary operations inherently run
+ * ACROSS ALL namespaces — or against a single global layer (compression
+ * guidelines, shared context, compounding) that is not namespace-partitioned
+ * — and carry NO `namespace` argument, so the MCP `tools/call` effective-
+ * namespace chokepoint ({@link enforceNamespaceAllowList}, which only fires
+ * when `toolAcceptsNamespace`) never applies. Without this guard a bearer
+ * scoped to ONE tenant could trigger maintenance that mutates state in EVERY
+ * namespace (privilege escalation).
+ *
+ * Fail CLOSED exactly like the other shared guards: a namespace-SCOPED token
+ * (namespaces axis present) is rejected; unrestricted / legacy tokens (absent
+ * record or no namespaces axis — i.e. cron and internal callers that never
+ * bind a capability record) are unaffected. Reuses the EXISTING capability
+ * model via {@link capabilityAllowsNamespace} — no new "all"/"*" scope concept.
+ * Must run BEFORE any side effect so a denial never leaks a partial mutation.
+ */
+export function assertFleetWideOperationAllowed(
+  caps: TokenCapabilities | undefined | null,
+): void {
+  // capabilityAllowsNamespace returns false for ANY scoped token when the
+  // namespace is undefined (a fleet-wide op has no single namespace), and
+  // true for unrestricted/legacy tokens — exactly the desired policy.
+  if (!capabilityAllowsNamespace(caps, undefined)) {
+    throw new EngramAccessForbiddenError(
+      "token is scoped to specific namespaces; this maintenance operation runs across all namespaces and is not permitted for a namespace-scoped token",
+    );
+  }
+}
+
+/**
+ * Per-request AsyncLocalStorage carrying the presenting token's resolved
+ * capabilities. The HTTP surface binds the resolved capabilities with
+ * `.run(caps, handler)` for the WHOLE authorized request dispatch (NOT
+ * `.enterWith()`, which mutates the current async resource and does not
+ * reliably isolate the store across the handler's awaits / concurrent
+ * requests — risking a fail-open read of undefined mid-handler); the
+ * access boundary reads `.getStore()` to enforce the ops allow-list for
+ * every boundary operation without each dispatch site threading the value
+ * explicitly. Unset (CLI, direct boundary callers, tests) ⇒ undefined ⇒
+ * unrestricted (issue #1850 round 7).
+ */
+export const tokenCapabilityStore = new AsyncLocalStorage<TokenCapabilities | undefined>();

package/src/chat/chat-mcp.test.ts

@@ -13,6 +13,7 @@ import { test } from "node:test";
 
 import { EngramMcpServer } from "../access-mcp.js";
 import type { EngramAccessService } from "../access-service.js";
+import { tokenCapabilityStore } from "../access-token-capabilities.js";
 import { parseConfig } from "../config.js";
 import { DEFAULT_CHAT_CONFIG } from "./chat-config.js";
 
@@ -133,3 +134,234 @@ test("MCP memory_chat: strips internal error from structuredContent (Thread 17)"
   assert.ok(typeof parsed.reply === "string", "reply must be present");
   await rm(memoryDir, { recursive: true, force: true });
 });
+
+// ──────────────────────────────────────────────────────────────────────────
+// Issue #1850 round 6: MCP memory_chat dispatches via processChatMessage,
+// bypassing op.run() (the boundary hook every other callTool branch routes
+// through). It must still enforce the per-token ops allow-list (op-gate) AND
+// the chat-session namespace, matching the HTTP /engram/v1/chat/message route.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Narrow a tools/call JSON-RPC response into just the fields the r6 tests
+ * assert on. Reads through `Record<string, unknown>` + `typeof` guards rather
+ * than an inline fabricated-shape cast, so a malformed envelope can never read
+ * a property the compiler never verified.
+ */
+function readToolOutcome(response: Record<string, unknown> | null): {
+  isError: boolean;
+  text: string;
+} {
+  const result = response?.result;
+  if (!(result && typeof result === "object")) return { isError: false, text: "" };
+  const r = result as Record<string, unknown>;
+  const content = r.content;
+  const firstEntry = Array.isArray(content) ? content[0] : undefined;
+  const firstText =
+    firstEntry && typeof firstEntry === "object" && firstEntry !== null
+      ? (firstEntry as Record<string, unknown>).text
+      : undefined;
+  return {
+    isError: r.isError === true,
+    text: typeof firstText === "string" ? firstText : "",
+  };
+}
+
+function makeChatService(memoryDir: string, llm: { chatCompletion: () => Promise<unknown> }): EngramAccessService {
+  return makeBaseService({
+    fallbackLlmRef: llm,
+    memoryDir,
+    configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+  });
+}
+
+test("MCP memory_chat: deny-all (ops:[]) token is rejected before dispatch (issue #1850 r6)", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-opgate-deny-"));
+  let dispatched = false;
+  const service = makeChatService(memoryDir, {
+    chatCompletion: async () => {
+      dispatched = true;
+      return { content: "x" };
+    },
+  });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  const outcome = await tokenCapabilityStore.run({ version: 1, ops: [] }, async () =>
+    readToolOutcome(await server.handleRequest(makeCallRequest("engram.memory_chat", { message: "hi" }))),
+  );
+  assert.equal(outcome.isError, true, "a deny-all token must be rejected at the op-gate");
+  assert.match(outcome.text, /not permitted to call operation/i);
+  assert.equal(dispatched, false, "processChatMessage (the LLM) must never be reached");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: ops-scoped token without chat_message is rejected (issue #1850 r6)", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-opgate-scope-"));
+  let dispatched = false;
+  const service = makeChatService(memoryDir, {
+    chatCompletion: async () => {
+      dispatched = true;
+      return { content: "x" };
+    },
+  });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  // Token permits recall but NOT chat_message.
+  const outcome = await tokenCapabilityStore.run({ version: 1, ops: ["recall"] }, async () =>
+    readToolOutcome(await server.handleRequest(makeCallRequest("engram.memory_chat", { message: "hi" }))),
+  );
+  assert.equal(outcome.isError, true, "an ops-scoped token without chat_message must be rejected");
+  assert.match(outcome.text, /not permitted to call operation/i);
+  assert.equal(dispatched, false, "processChatMessage (the LLM) must never be reached");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: ops-scoped token WITH chat_message is allowed (issue #1850 r6)", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-opgate-allow-"));
+  const service = makeChatService(memoryDir, { chatCompletion: async () => ({ content: "sure [id: x]." }) });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  const outcome = await tokenCapabilityStore.run({ version: 1, ops: ["chat_message"] }, async () =>
+    readToolOutcome(await server.handleRequest(makeCallRequest("engram.memory_chat", { message: "hi" }))),
+  );
+  assert.equal(outcome.isError, false, "a token whose ops include chat_message must pass the gate");
+  const parsed = JSON.parse(outcome.text) as Record<string, unknown>;
+  assert.ok(typeof parsed.reply === "string" && (parsed.reply as string).length > 0, "a reply must be produced");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: unrestricted token is allowed (issue #1850 r6)", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-unrestricted-"));
+  const service = makeChatService(memoryDir, { chatCompletion: async () => ({ content: "hello [id: y]." }) });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  // Explicit-unrestricted record (version present, no axes) ⇒ both gates no-op.
+  const outcome = await tokenCapabilityStore.run({ version: 1 }, async () =>
+    readToolOutcome(await server.handleRequest(makeCallRequest("engram.memory_chat", { message: "hi" }))),
+  );
+  assert.equal(outcome.isError, false, "an unrestricted token must pass both gates");
+  const parsed = JSON.parse(outcome.text) as Record<string, unknown>;
+  assert.ok(typeof parsed.reply === "string", "a reply must be produced");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: namespace-scoped token cannot resume a cross-namespace session (issue #1850 r6)", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-xnamespace-"));
+  let dispatchCount = 0;
+  const llm = {
+    chatCompletion: async () => {
+      dispatchCount += 1;
+      return { content: "ok [id: z]." };
+    },
+  };
+  const service = makeChatService(memoryDir, llm);
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  // 1. Create a session bound to namespace "team-a" under an unrestricted token.
+  const createOutcome = readToolOutcome(
+    await server.handleRequest(makeCallRequest("engram.memory_chat", { message: "remember this" }), {
+      namespaceOverride: "team-a",
+    }),
+  );
+  assert.equal(createOutcome.isError, false, "session creation under an unrestricted token must succeed");
+  const created = JSON.parse(createOutcome.text) as Record<string, unknown>;
+  assert.ok(typeof created.chatSessionId === "string", "a chatSessionId must be returned to resume");
+  const chatSessionId = created.chatSessionId as string;
+  assert.equal(dispatchCount, 1, "the create call dispatched the LLM exactly once");
+
+  // 2. Resume that session under a token scoped to a DIFFERENT namespace. The
+  //    resumed session is an id-loaded record whose stored namespace ("team-a")
+  //    must be gated against the token's allow-list (["team-b"]) — rejected.
+  const resumeOutcome = await tokenCapabilityStore.run({ version: 1, namespaces: ["team-b"] }, async () =>
+    readToolOutcome(
+      await server.handleRequest(
+        makeCallRequest("engram.memory_chat", { message: "follow up", chatSessionId }),
+      ),
+    ),
+  );
+  assert.equal(resumeOutcome.isError, true, "a cross-namespace resume must be rejected");
+  assert.match(resumeOutcome.text, /not permitted to access namespace/i);
+  assert.equal(dispatchCount, 1, "the rejected resume must not have dispatched the LLM a second time");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: NEW session namespace is gated — scoped token cannot start a chat in a disallowed namespace (issue #1850 r8)", async () => {
+  // The resume path already gates the session's stored namespace (r6). A NEW
+  // chat turn (no chatSessionId) previously forwarded scope.namespace straight
+  // to processChatMessage with NO allow-list gate, so a namespace-scoped token
+  // could mint a session in a namespace outside its allow-list. The new-session
+  // path must resolve the EFFECTIVE namespace (scope.namespace OR server
+  // default) and fail closed against the token allow-list — same chokepoint the
+  // HTTP /engram/v1/chat/message route gained in r7.
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-new-ns-gate-"));
+  let dispatchCount = 0;
+  const llm = {
+    chatCompletion: async () => {
+      dispatchCount += 1;
+      return { content: "ok [id: new]." };
+    },
+  };
+  // namespacesEnabled + a server default OUTSIDE the scoped token's allow-list,
+  // so the fail-closed-against-default case is exercisable.
+  const service = makeBaseService({
+    fallbackLlmRef: llm,
+    memoryDir,
+    configRef: parseConfig({
+      memoryDir,
+      namespacesEnabled: true,
+      defaultNamespace: "default",
+      chat: { ...DEFAULT_CHAT_CONFIG, enabled: true },
+    }),
+  });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  // (1) DISALLOWED explicit namespace: token scoped to ["team-a"], but the new
+  //     session would be created under scope.namespace "team-b" (not in the
+  //     allow-list) → rejected BEFORE processChatMessage (LLM never reached).
+  const deniedExplicit = await tokenCapabilityStore.run(
+    { version: 1, ops: ["chat_message"], namespaces: ["team-a"] },
+    async () =>
+      readToolOutcome(
+        await server.handleRequest(
+          makeCallRequest("engram.memory_chat", { message: "hi" }),
+          { namespaceOverride: "team-b" },
+        ),
+      ),
+  );
+  assert.equal(deniedExplicit.isError, true, "a scoped token must not start a new chat in a disallowed namespace");
+  assert.match(deniedExplicit.text, /not permitted to access namespace/i);
+  assert.equal(dispatchCount, 0, "the denied new chat must not dispatch the LLM");
+
+  // (2) ALLOWED explicit namespace: same token, scope.namespace "team-a" (IN
+  //     the allow-list) → gate passes, chat runs, returns a reply + session id.
+  const allowedExplicit = await tokenCapabilityStore.run(
+    { version: 1, ops: ["chat_message"], namespaces: ["team-a"] },
+    async () =>
+      readToolOutcome(
+        await server.handleRequest(
+          makeCallRequest("engram.memory_chat", { message: "hi" }),
+          { namespaceOverride: "team-a" },
+        ),
+      ),
+  );
+  assert.equal(allowedExplicit.isError, false, "a scoped token may start a new chat in an allowed namespace");
+  const allowedParsed = JSON.parse(allowedExplicit.text) as Record<string, unknown>;
+  assert.ok(typeof allowedParsed.reply === "string", "the allowed new chat returns a reply");
+  assert.ok(typeof allowedParsed.chatSessionId === "string", "the allowed new chat returns a chatSessionId");
+  assert.equal(dispatchCount, 1, "only the allowed new chat dispatched the LLM");
+
+  // (3) FAIL CLOSED against the server default: same token scoped to ["team-a"],
+  //     NEW chat with NO scope.namespace → effective namespace is the server
+  //     default ("default"), not in ["team-a"] → rejected. Mirrors the HTTP r7
+  //     new-session gate (omitting the param cannot bypass it).
+  const deniedDefault = await tokenCapabilityStore.run(
+    { version: 1, ops: ["chat_message"], namespaces: ["team-a"] },
+    async () =>
+      readToolOutcome(await server.handleRequest(makeCallRequest("engram.memory_chat", { message: "hi" }))),
+  );
+  assert.equal(deniedDefault.isError, true, "omitting scope.namespace must fail closed against the server default");
+  assert.match(deniedDefault.text, /server default namespace is not permitted/i);
+  assert.equal(dispatchCount, 1, "the denied-against-default new chat must not dispatch the LLM");
+
+  await rm(memoryDir, { recursive: true, force: true });
+});

package/src/chat/chat-session.ts

@@ -11,6 +11,7 @@ import { mkdir, readFile, appendFile, readdir, stat, unlink, open } from "node:f
 import { constants as fsConstants } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { enforceNamespaceAllowList, tokenCapabilityStore } from "../access-token-capabilities.js";
 
 import type { ChatSessionState, ChatTranscriptEntry } from "./chat-types.js";
 
@@ -211,6 +212,39 @@ export async function loadChatSession(
   };
 }
 
+/**
+ * Structural shape {@link enforceChatSessionNamespace} reads from a service —
+ * `memoryDir` to locate the session file and `configRef.defaultNamespace` to
+ * resolve the effective namespace. Kept structural so the chat module need not
+ * depend on the full {@link EngramAccessService} type.
+ */
+export interface ChatSessionNamespaceHost {
+  memoryDir: string;
+  configRef?: { defaultNamespace?: string } | undefined;
+}
+
+/**
+ * The shared effective-namespace chokepoint for a resumed chat session
+ * (issue #1850 round 6). A chat session is an id-loaded record whose stored
+ * namespace bypassed the per-token allow-list; BOTH the HTTP dispatch
+ * (`/engram/v1/chat/message`, `/engram/v1/chat/events/:id`) and the MCP
+ * dispatch (`memory_chat` → processChatMessage) call this ONE function so
+ * neither surface can dodge it. Loads the session and runs
+ * `enforceNamespaceAllowList` (which maps undefined → the server default).
+ * FAIL CLOSED: a scoped token whose allow-list does not cover the session's
+ * effective namespace is rejected; no-op for unrestricted/legacy tokens. A
+ * missing session is left to the downstream handler (404 /
+ * chat_session_not_found) — only FOUND sessions carry a namespace to gate.
+ */
+export async function enforceChatSessionNamespace(
+  service: ChatSessionNamespaceHost,
+  chatSessionId: string,
+): Promise<void> {
+  const session = await loadChatSession(service.memoryDir, chatSessionId);
+  if (!session) return;
+  enforceNamespaceAllowList(tokenCapabilityStore.getStore(), session.namespace, service.configRef?.defaultNamespace);
+}
+
 /**
  * Append a transcript entry to the session file (atomic append, rule 54).
  *