@remnic/core 9.3.768 → 9.3.770

package/src/access-http.test.ts

@@ -1454,3 +1454,353 @@ test("HTTP offline apply requires a changeset", async () => {
     await server.stop();
   }
 });
+
+test("HTTP server rejects invalid resourceMetadataUrl at construction", () => {
+  const service = {} as EngramAccessService;
+  for (const bad of ["not a url", "ftp://example.com/oauth", "//relative/path", ""]) {
+    assert.throws(
+      () =>
+        new EngramAccessHttpServer({
+          service,
+          port: 0,
+          authToken: "test-token",
+          adminConsoleEnabled: false,
+          resourceMetadataUrl: bad,
+        }),
+      /access HTTP resourceMetadataUrl/,
+      `resourceMetadataUrl=${JSON.stringify(bad)} must be rejected`,
+    );
+  }
+  // http and https are accepted.
+  for (const ok of [
+    "https://example.com/.well-known/oauth-protected-resource",
+    "http://127.0.0.1:8787/.well-known/oauth-protected-resource",
+  ]) {
+    const server = new EngramAccessHttpServer({
+      service,
+      port: 0,
+      authToken: "test-token",
+      adminConsoleEnabled: false,
+      resourceMetadataUrl: ok,
+    });
+    assert.ok(server, `resourceMetadataUrl=${ok} should be accepted`);
+  }
+});
+
+test("HTTP 401 www-authenticate carries resource_metadata exactly when configured", async () => {
+  const service = {} as EngramAccessService;
+  const metadataUrl = "https://example.test/.well-known/oauth-protected-resource";
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    resourceMetadataUrl: metadataUrl,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/engram/v1/health`);
+    assert.equal(response.status, 401);
+    assert.equal(
+      response.headers.get("www-authenticate"),
+      `Bearer resource_metadata="${metadataUrl}"`,
+    );
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP 401 www-authenticate is the bare Bearer challenge when resourceMetadataUrl is unset", async () => {
+  const service = {} as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/engram/v1/health`);
+    assert.equal(response.status, 401);
+    assert.equal(response.headers.get("www-authenticate"), "Bearer");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP /mcp returns 405 with Allow: POST for GET and DELETE (authorized requests)", async () => {
+  const service = {} as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    for (const method of ["GET", "DELETE"]) {
+      const response = await fetch(`http://127.0.0.1:${status.port}/mcp`, {
+        method,
+        headers: { authorization: "Bearer test-token" },
+      });
+      assert.equal(response.status, 405, `${method} /mcp must be 405`);
+      assert.equal(response.headers.get("allow"), "POST", `${method} /mcp must advertise Allow: POST`);
+      const body = await response.json() as { code?: string };
+      assert.equal(body.code, "method_not_allowed");
+    }
+    // Unauthenticated GET /mcp still gets 401 first (auth gate beats method-conformance).
+    const unauth = await fetch(`http://127.0.0.1:${status.port}/mcp`, { method: "GET" });
+    assert.equal(unauth.status, 401);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP /mcp rejects unknown MCP-Protocol-Version header with 400 JSON-RPC error", async () => {
+  const service = {} as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/mcp`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+        "mcp-protocol-version": "1999-01-01",
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+    });
+    assert.equal(response.status, 400);
+    const body = await response.json() as { jsonrpc?: string; error?: { message?: string } };
+    assert.equal(body.jsonrpc, "2.0");
+    assert.match(body.error?.message ?? "", /unsupported MCP-Protocol-Version/);
+
+    // A supported header is accepted (and a valid request proceeds normally).
+    for (const v of ["2025-06-18", "2025-03-26", "2024-11-05"]) {
+      const ok = await fetch(`http://127.0.0.1:${status.port}/mcp`, {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+          "mcp-protocol-version": v,
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+      });
+      assert.equal(ok.status, 200, `version ${v} should be accepted`);
+    }
+
+    // Absent header is also fine.
+    const absent = await fetch(`http://127.0.0.1:${status.port}/mcp`, {
+      method: "POST",
+      headers: { authorization: "Bearer test-token", "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+    });
+    assert.equal(absent.status, 200);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP externalRequestHandler runs pre-auth, can end responses, and falls through on false", async () => {
+  // Minimal service stub: the fall-through leg hits /engram/v1/health, which
+  // calls service.health(). The stub is signature-faithful (full
+  // EngramAccessHealthResponse via `satisfies`) so interface drift fails here
+  // instead of passing vacuously; everything else in this test bypasses the
+  // service.
+  const healthStub = {
+    health: async () => ({
+      ok: true as const,
+      memoryDir: "/tmp/remnic-test",
+      namespacesEnabled: false,
+      defaultNamespace: "default",
+      searchBackend: "recent",
+      qmdEnabled: false,
+      qmd: {
+        enabled: false,
+        active: false,
+        degraded: false,
+        mode: "disabled" as const,
+        collection: "",
+        collectionState: "skipped" as const,
+        installedVersion: null,
+        supportedVersion: null,
+        supported: null,
+        upgradeAvailable: null,
+        doctorAvailable: null,
+        debugStatus: "disabled",
+      },
+      nativeKnowledgeEnabled: false,
+      projectionAvailable: false,
+    }),
+  } satisfies Pick<EngramAccessService, "health">;
+  const service = healthStub as EngramAccessService;
+  const seen: Array<{ path: string; method: string; authorized: boolean }> = [];
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    externalRequestHandler: async (_req, res, ctx) => {
+      seen.push({
+        path: new URL(_req.url ?? "/", "http://placeholder").pathname,
+        method: _req.method ?? "",
+        authorized: ctx.authorized,
+      });
+      if (new URL(_req.url ?? "/", "http://placeholder").pathname === "/probe/handled") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ handled: true, authorized: ctx.authorized }));
+        return true;
+      }
+      return false; // fall through to the normal pipeline
+    },
+  });
+  const status = await server.start();
+  try {
+    // Pre-auth, the handler sees authorized=false (no token sent).
+    const handled = await fetch(`http://127.0.0.1:${status.port}/probe/handled`);
+    assert.equal(handled.status, 200);
+    const handledBody = await handled.json() as { handled?: boolean; authorized?: boolean };
+    assert.equal(handledBody.handled, true);
+    assert.equal(handledBody.authorized, false, "handler must observe authorized=false pre-token");
+
+    // Fall-through path: same handler returns false, request continues to normal
+    // routing. Hit a real endpoint so we know the request reached it.
+    const passthrough = await fetch(
+      `http://127.0.0.1:${status.port}/engram/v1/health`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    assert.equal(passthrough.status, 200, "fall-through should reach the normal health route");
+    const passthroughBody = await passthrough.json() as { ok?: boolean; memoryDir?: string };
+    assert.equal(passthroughBody.ok, true, "fall-through must return the stubbed health payload");
+    assert.equal(passthroughBody.memoryDir, "/tmp/remnic-test");
+
+    // Authorized request: handler sees ctx.authorized=true.
+    const authed = await fetch(
+      `http://127.0.0.1:${status.port}/probe/handled`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    assert.equal(authed.status, 200);
+    const authedBody = await authed.json() as { authorized?: boolean };
+    assert.equal(authedBody.authorized, true, "handler must observe authorized=true with valid token");
+
+    assert.deepEqual(seen, [
+      { path: "/probe/handled", method: "GET", authorized: false },
+      { path: "/engram/v1/health", method: "GET", authorized: true },
+      { path: "/probe/handled", method: "GET", authorized: true },
+    ]);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP externalRequestHandler errors flow through the existing error handler", async () => {
+  const service = {} as EngramAccessService;
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    externalRequestHandler: async () => {
+      throw new Error("external-handler-explosion");
+    },
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(`http://127.0.0.1:${status.port}/engram/v1/health`);
+    assert.equal(response.status, 500, "thrown errors must produce a 500 via the existing error handler");
+    const body = await response.json() as { code?: string };
+    assert.equal(body.code, "internal_error");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP authTokenEntriesGetter is authoritative: scope policy binds connectors and never falls through", async () => {
+  // Signature-faithful health stub so non-MCP authorization outcomes are
+  // observable as 200-with-body (a bare `{}` service would 500 and mask
+  // accidental policy application).
+  const healthStub = {
+    health: async () => ({
+      ok: true as const,
+      memoryDir: "/tmp/remnic-scope-test",
+      namespacesEnabled: false,
+      defaultNamespace: "default",
+      searchBackend: "recent",
+      qmdEnabled: false,
+      qmd: {
+        enabled: false,
+        active: false,
+        degraded: false,
+        mode: "disabled" as const,
+        collection: "",
+        collectionState: "skipped" as const,
+        installedVersion: null,
+        supportedVersion: null,
+        supported: null,
+        upgradeAvailable: null,
+        doctorAvailable: null,
+        debugStatus: "disabled",
+      },
+      nativeKnowledgeEnabled: false,
+      projectionAvailable: false,
+    }),
+  } satisfies Pick<EngramAccessService, "health">;
+  const entries = [
+    { token: "remnic_cg_scoped", connector: "chatgpt" },
+    { token: "remnic_cx_free", connector: "codex" },
+    { token: "remnic_xx_anon" }, // no connector — must fail closed under a policy
+  ];
+  const server = new EngramAccessHttpServer({
+    service: healthStub as EngramAccessService,
+    port: 0,
+    authToken: "operator-token",
+    // Dangerous shape on purpose: BOTH getters configured, and the string
+    // getter is a superset (extra "string_only_token"). The entries getter
+    // must decide alone; nothing may leak into the string getter.
+    authTokensGetter: () => [...entries.map((entry) => entry.token), "string_only_token"],
+    authTokenEntriesGetter: () => entries,
+    tokenPathPolicy: (connector, pathname) => connector !== "chatgpt" || pathname === "/mcp",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  const request = (token: string, path: string, method = "GET") =>
+    fetch(`http://127.0.0.1:${status.port}${path}`, {
+      method,
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      ...(method === "POST" ? { body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }) } : {}),
+    });
+  try {
+    // Scoped chatgpt token: /mcp only; health denied.
+    assert.equal((await request("remnic_cg_scoped", "/mcp", "POST")).status, 200);
+    assert.equal(
+      (await request("remnic_cg_scoped", "/engram/v1/health")).status,
+      401,
+      "chatgpt token must be denied off /mcp even with a permissive string getter present",
+    );
+    // Other connector tokens are unrestricted by this policy: /mcp AND health.
+    assert.equal((await request("remnic_cx_free", "/mcp", "POST")).status, 200);
+    const codexHealth = await request("remnic_cx_free", "/engram/v1/health");
+    assert.equal(codexHealth.status, 200);
+    assert.equal(((await codexHealth.json()) as { ok?: boolean }).ok, true);
+    // Entry without connector fails closed when a policy is configured.
+    assert.equal((await request("remnic_xx_anon", "/mcp", "POST")).status, 401);
+    // A token present ONLY in the string getter is NOT honored: the entries
+    // getter is authoritative and there is no fall-through.
+    assert.equal((await request("string_only_token", "/mcp", "POST")).status, 401);
+    assert.equal((await request("string_only_token", "/engram/v1/health")).status, 401);
+    // Unknown tokens are rejected everywhere.
+    assert.equal((await request("remnic_zz_unknown", "/mcp", "POST")).status, 401);
+    // Static operator token bypasses the policy entirely: /mcp AND health.
+    assert.equal((await request("operator-token", "/mcp", "POST")).status, 200);
+    const operatorHealth = await request("operator-token", "/engram/v1/health");
+    assert.equal(operatorHealth.status, 200);
+    assert.equal(((await operatorHealth.json()) as { ok?: boolean }).ok, true);
+  } finally {
+    await server.stop();
+  }
+});

package/src/access-http.ts

@@ -8,10 +8,16 @@ import { fileURLToPath, URL } from "node:url";
 import { gunzipSync } from "node:zlib";
 import { log } from "./logger.js";
 import { abortError, isAbortError } from "./abort-error.js";
-import { EngramAccessInputError, type EngramAccessService, type EngramAccessMemoryResponse, type EngramAccessWriteResponse } from "./access-service.js";
+import { EngramAccessForbiddenError } from "./access-errors.js";
+import {
+  EngramAccessInputError,
+  type EngramAccessService,
+  type EngramAccessMemoryResponse,
+  type EngramAccessWriteResponse,
+} from "./access-service.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
 import { WearablesInputError } from "./wearables/errors.js";
-import { EngramMcpServer } from "./access-mcp.js";
+import { EngramMcpServer, MCP_SUPPORTED_PROTOCOL_VERSIONS } from "./access-mcp.js";
 import { validateRequest, type SchemaName, type SchemaTypeFor } from "./access-schema.js";
 import {
   OFFLINE_SYNC_APPLY_MAX_BODY_BYTES,
@@ -54,6 +60,21 @@ export interface EngramAccessHttpServerOptions {
   authTokens?: string[];
   /** Dynamic token loader — called on each auth check so new/revoked tokens take effect without restart. */
   authTokensGetter?: () => string[];
+  /**
+   * Dynamic token-ENTRY loader ({token, connector} pairs from one coherent
+   * snapshot). Preferred over `authTokensGetter` when a `tokenPathPolicy`
+   * is set: the connector used for the policy decision comes from the SAME
+   * entry that validated, so identity can never lag validation.
+   */
+  authTokenEntriesGetter?: () => ReadonlyArray<{ token: string; connector?: string }>;
+  /**
+   * Optional per-request scope policy for tokens sourced from
+   * `authTokenEntriesGetter`. Return false to deny the (validated) token
+   * for this pathname. Static `authToken`/`authTokens` (operator-supplied)
+   * bypass the policy. Entries whose connector is missing FAIL CLOSED when
+   * a policy is configured.
+   */
+  tokenPathPolicy?: (connector: string, pathname: string | undefined) => boolean;
   principal?: string;
   maxBodyBytes?: number;
   adminConsoleEnabled?: boolean;
@@ -78,6 +99,28 @@ export interface EngramAccessHttpServerOptions {
    * existing health behavior.
    */
   readiness?: () => AccessHttpReadinessState;
+  /**
+   * When set, every 401 response includes
+   * `WWW-Authenticate: Bearer resource_metadata="<value>"` so MCP clients
+   * can discover the OAuth 2.0 protected-resource metadata document
+   * (RFC 9728). Must be an absolute http(s) URL; constructor throws on
+   * anything else. Unset → bare `Bearer`.
+   */
+  resourceMetadataUrl?: string;
+  /**
+   * Optional pre-auth request handler (e.g. OAuth facade mounted by
+   * `@remnic/server`). Runs after the admin-console handler and BEFORE
+   * bearer authorization. Return true if the request was fully handled
+   * (response ended). `ctx.authorized` reports whether the request
+   * carries a valid operator bearer token, so the handler can gate
+   * operator-only endpoints without owning token validation.
+   * Errors thrown by the handler flow into the existing error handling.
+   */
+  externalRequestHandler?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    ctx: { authorized: boolean },
+  ) => Promise<boolean>;
 }
 
 export interface EngramAccessHttpServerStatus {
@@ -183,6 +226,23 @@ function parseHttpServerPort(port: number | undefined): number {
   }
   return port;
 }
+function assertResourceMetadataUrl(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(
+      `access HTTP resourceMetadataUrl must be an absolute http(s) URL, got: ${value}`,
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `access HTTP resourceMetadataUrl must use http or https, got: ${parsed.protocol}`,
+    );
+  }
+  return value;
+}
 
 function parseTrustZoneKindFilter(raw: string | null): TrustZoneRecordKind | undefined {
   if (raw === null) return undefined;
@@ -283,6 +343,8 @@ export class EngramAccessHttpServer {
   private readonly authToken?: string;
   private readonly authTokens: string[];
   private readonly authTokensGetter?: () => string[];
+  private readonly authTokenEntriesGetter?: () => ReadonlyArray<{ token: string; connector?: string }>;
+  private readonly tokenPathPolicy?: (connector: string, pathname: string | undefined) => boolean;
   private readonly authenticatedPrincipal?: string;
   private readonly maxBodyBytes: number;
   private readonly adminConsoleEnabled: boolean;
@@ -292,6 +354,12 @@ export class EngramAccessHttpServer {
   private readonly trustPrincipalHeader: boolean;
   private readonly adapterRegistry: AdapterRegistry | null;
   private readonly readiness: () => AccessHttpReadinessState;
+  private readonly resourceMetadataUrl?: string;
+  private readonly externalRequestHandler?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    ctx: { authorized: boolean },
+  ) => Promise<boolean>;
   private readonly writeRequestTimestamps: number[] = [];
   private readonly mcpServer: EngramMcpServer;
   private server: Server | null = null;
@@ -323,6 +391,8 @@ export class EngramAccessHttpServer {
     this.authToken = options.authToken?.trim() || undefined;
     this.authTokens = (options.authTokens ?? []).map((t) => t.trim()).filter(Boolean);
     this.authTokensGetter = options.authTokensGetter;
+    this.authTokenEntriesGetter = options.authTokenEntriesGetter;
+    this.tokenPathPolicy = options.tokenPathPolicy;
     this.authenticatedPrincipal = options.principal?.trim() || undefined;
     this.maxBodyBytes = Number.isFinite(options.maxBodyBytes)
       ? Math.max(1, Math.floor(options.maxBodyBytes ?? 131072))
@@ -333,6 +403,8 @@ export class EngramAccessHttpServer {
     this.adminControls = options.adminControls;
     this.trustPrincipalHeader = options.trustPrincipalHeader === true;
     this.readiness = options.readiness ?? (() => ({ ready: true, warmupAttempts: 0 }));
+    this.resourceMetadataUrl = assertResourceMetadataUrl(options.resourceMetadataUrl);
+    this.externalRequestHandler = options.externalRequestHandler;
     this.adapterRegistry = options.enableAdapters !== false
       ? (options.adapterRegistry ?? new AdapterRegistry())
       : null;
@@ -351,7 +423,7 @@ export class EngramAccessHttpServer {
   }
 
   async start(): Promise<EngramAccessHttpServerStatus> {
-    if (!this.authToken && this.authTokens.length === 0 && !this.authTokensGetter) {
+    if (!this.authToken && this.authTokens.length === 0 && !this.authTokensGetter && !this.authTokenEntriesGetter) {
       throw new Error("engram access HTTP requires authToken or authTokens");
     }
     if (this.server) return this.status();
@@ -385,6 +457,10 @@ export class EngramAccessHttpServer {
             this.respondJson(res, 400, { error: err.message, code: "input_error" });
             return;
           }
+          if (err instanceof EngramAccessForbiddenError) {
+            this.respondJson(res, 403, { error: err.message, code: "forbidden" });
+            return;
+          }
           if (err instanceof CorrectionContractError) {
             this.respondJson(res, 400, { error: err.message, code: "correction_contract_error" });
             return;
@@ -642,11 +718,40 @@ export class EngramAccessHttpServer {
 
     }
 
+    // Run any host-supplied pre-auth request handler. It runs AFTER the
+    // admin-console branch (admin assets are public) and BEFORE the
+    // operator bearer gate. The handler decides whether it has fully
+    // owned the response (return true) or wants the request to fall
+    // through to the normal pipeline. `ctx.authorized` is computed
+    // here so the handler can implement operator-only endpoints
+    // (e.g. /oauth/pending) without owning token validation.
+    if (this.externalRequestHandler) {
+      const authorized = this.isAuthorized(req, pathname);
+      if (await this.externalRequestHandler(req, res, { authorized })) {
+        return;
+      }
+    }
+
     if (!this.isAuthorized(req, pathname)) {
       const body = JSON.stringify({ error: "unauthorized", code: "unauthorized" });
       res.writeHead(401, {
         "content-type": "application/json; charset=utf-8",
-        "www-authenticate": "Bearer",
+        "www-authenticate": this.bearerChallenge(),
+        "x-request-id": correlationId,
+      });
+      res.end(body);
+      return;
+    }
+
+    // Method-conformance for the streamable-HTTP MCP endpoint:
+    // GET/DELETE on /mcp must return 405 + Allow: POST instead of
+    // silently falling through to the generic 404. POST continues
+    // to the normal handler below.
+    if (pathname === "/mcp" && (req.method === "GET" || req.method === "DELETE")) {
+      const body = JSON.stringify({ error: "method_not_allowed", code: "method_not_allowed" });
+      res.writeHead(405, {
+        "content-type": "application/json; charset=utf-8",
+        allow: "POST",
         "x-request-id": correlationId,
       });
       res.end(body);
@@ -1674,6 +1779,27 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (req.method === "GET" && pathname === "/engram/v1/recall/timings") {
+      const op = getOperation("recall_timings"); // boundary dispatch (issue #1830)
+      if (!op) {
+        throw new Error("access-boundary: operation not registered: recall_timings");
+      }
+      // Live diagnostic route; no response (success or denial) is cacheable.
+      // Set before dispatch so the 403 path carries the header too.
+      res.setHeader("cache-control", "no-store");
+      // Dispatch through the registered operation so the HTTP route and the
+      // boundary registration share one gate. The server's own principal is
+      // the transport-level operator fallback; a configured
+      // agentAccessHttp.principal outranks it.
+      const output = (await op.run({}, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        operatorPrincipal: this.authenticatedPrincipal,
+      })) as { result: unknown };
+      this.respondJson(res, 200, output.result);
+      return;
+    }
+
     const memoryMatch = pathname.match(/^\/engram\/v1\/memories\/([^/]+)$/);
     if (req.method === "GET" && memoryMatch) {
       const memoryId = decodeURIComponent(memoryMatch[1] ?? "");
@@ -2682,7 +2808,28 @@ export class EngramAccessHttpServer {
   }
 
   private async handleMcpRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    // Reject requests that advertise an unknown MCP protocol version in
+    // the streamable-HTTP `MCP-Protocol-Version` header. Absent or
+    // valid → proceed. Unknown → 400 with a JSON-RPC-shaped error so
+    // the client surfaces a clear message. The supported set is
+    // exported by @remnic/core's access-mcp module to keep the
+    // version policy in a single place.
+    const headerVersion = req.headers["mcp-protocol-version"];
+    if (typeof headerVersion === "string" && headerVersion.length > 0) {
+      if (!(MCP_SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(headerVersion)) {
+        this.respondJson(res, 400, {
+          jsonrpc: "2.0",
+          id: null,
+          error: {
+            code: -32000,
+            message: `unsupported MCP-Protocol-Version: ${headerVersion}; supported: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`,
+          },
+        });
+        return;
+      }
+    }
     const body = await this.readJsonBody(req);
+
     const request = body as {
       jsonrpc?: string;
       id?: string | number | null;
@@ -3118,8 +3265,29 @@ export class EngramAccessHttpServer {
     return result.data as SchemaTypeFor<S>;
   }
 
-  private isAuthorized(req: IncomingMessage, pathname?: string): boolean {
-    if (!this.authToken && this.authTokens.length === 0 && !this.authTokensGetter) return false;
+  /**
+   * Build the WWW-Authenticate challenge string for 401 responses.
+   * When `resourceMetadataUrl` is configured, includes the RFC 9728
+   * `resource_metadata` parameter so MCP clients (e.g. ChatGPT) can
+   * discover the OAuth 2.0 protected-resource metadata document.
+   * Otherwise the bare `Bearer` challenge is returned (unchanged).
+   */
+  private bearerChallenge(): string {
+    if (this.resourceMetadataUrl) {
+      return `Bearer resource_metadata="${this.resourceMetadataUrl}"`;
+    }
+    return "Bearer";
+  }
+
+   private isAuthorized(req: IncomingMessage, pathname?: string): boolean {
+    if (
+      !this.authToken &&
+      this.authTokens.length === 0 &&
+      !this.authTokensGetter &&
+      !this.authTokenEntriesGetter
+    ) {
+      return false;
+    }
     // Primary path: Authorization: Bearer <token> header.
     const raw = req.headers.authorization;
     let candidate: string | null = null;
@@ -3159,7 +3327,24 @@ export class EngramAccessHttpServer {
     for (const valid of this.authTokens) {
       if (this.timingSafeStringEqual(token, valid)) return true;
     }
-    // Check dynamic tokens (reloaded per request for generate/revoke without restart)
+    // Entry-based dynamic tokens are AUTHORITATIVE when configured: the
+    // dynamic-token decision ends here (no fall-through to the string
+    // getter, which carries no identity and would bypass the policy).
+    // Validation and connector identity come from the same snapshot entry,
+    // so a scope policy can never observe a token fresher than the
+    // identity it scopes (mint/revoke coherence).
+    if (this.authTokenEntriesGetter) {
+      for (const entry of this.authTokenEntriesGetter()) {
+        if (!this.timingSafeStringEqual(token, entry.token)) continue;
+        if (!this.tokenPathPolicy) return true;
+        // Fail closed: a policy without a connector identity denies.
+        if (typeof entry.connector !== "string" || entry.connector.length === 0) return false;
+        return this.tokenPathPolicy(entry.connector, pathname);
+      }
+      return false;
+    }
+    // String-token getter (no identity, no policy) — only consulted when
+    // no entry getter is configured.
     if (this.authTokensGetter) {
       for (const valid of this.authTokensGetter()) {
         if (this.timingSafeStringEqual(token, valid)) return true;