@remnic/core 10.0.85 → 10.0.86

package/src/access-http-peer-fleet-wide.test.ts

@@ -0,0 +1,192 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { EngramAccessHttpServer } from "./access-http.js";
+import { EngramAccessService } from "./access-service.js";
+import { Orchestrator } from "./orchestrator.js";
+import { parseConfig } from "./config.js";
+import { writePeer, writePeerProfile } from "./peers/index.js";
+
+// Issue #3225 B3: the HTTP peer routes dispatch to global stores, so REST
+// must enforce the same operation policy as MCP — a namespace-scoped token
+// (any namespaces axis, including []) must be denied before any file in the
+// store changes, while ops-scoped and legacy tokens keep working.
+
+const PEER_ID = "b3-target-peer";
+const NOW = "2026-11-11T00:00:00.000Z";
+
+async function createService(): Promise<{ root: string; service: EngramAccessService; cleanup: () => Promise<void> }> {
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-http-peer-fleet-wide-"));
+  const orchestrator = new Orchestrator(
+    parseConfig({ memoryDir: root, namespacesEnabled: false, defaultNamespace: "global" }),
+  );
+  const storage = await orchestrator.getStorage();
+  await storage.ensureDirectories();
+  await writePeer(root, {
+    id: PEER_ID,
+    kind: "agent",
+    displayName: "seeded peer",
+    createdAt: NOW,
+    updatedAt: NOW,
+  });
+  await writePeerProfile(root, {
+    peerId: PEER_ID,
+    updatedAt: NOW,
+    fields: { communication_style: "seeded" },
+    provenance: {},
+  });
+  return { root, service: new EngramAccessService(orchestrator), cleanup: () => rm(root, { recursive: true, force: true }) };
+}
+
+/** Sorted relpath:content lines for every file under root (mutation detector). */
+async function snapshotDir(root: string): Promise<string[]> {
+  const entries = await readdir(root, { recursive: true, withFileTypes: true });
+  const lines: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const abs = path.join(entry.parentPath, entry.name);
+    const content = await readFile(abs, "utf8");
+    lines.push(`${path.relative(root, abs)}:${content}`);
+  }
+  return lines.sort();
+}
+
+test("HTTP peer routes deny namespace-scoped tokens before the stores, REST policy matches MCP (issue #3225 B3)", async () => {
+  const { root, service, cleanup } = await createService();
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "legacy-operator",
+    authTokenEntriesGetter: () => [
+      { token: "ns-scoped", capabilities: { version: 1, namespaces: ["ns_a"] } },
+      { token: "ns-empty", capabilities: { version: 1, namespaces: [] } },
+      {
+        token: "ops-peer",
+        capabilities: {
+          version: 1,
+          ops: ["peer_list", "peer_get", "peer_set", "peer_delete", "peer_profile_get", "peer_forget"],
+        },
+      },
+    ],
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  const call = (token: string, pathname: string, init?: RequestInit) =>
+    fetch(`http://127.0.0.1:${status.port}${pathname}`, {
+      ...init,
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}`, ...(init?.headers ?? {}) },
+    });
+
+  try {
+    const before = await snapshotDir(root);
+
+    // Namespace-scoped token (single namespace): every peer route is denied
+    // BEFORE the store is touched — including the destructive purge.
+    assert.equal((await call("ns-scoped", "/engram/v1/peers")).status, 403, "peer_list denied");
+    assert.equal((await call("ns-scoped", `/engram/v1/peers/${PEER_ID}`)).status, 403, "peer_get denied");
+    assert.equal(
+      (await call("ns-scoped", `/engram/v1/peers/${PEER_ID}`, { method: "PUT", body: JSON.stringify({ displayName: "hijack" }) })).status,
+      403,
+      "peer_set denied",
+    );
+    assert.equal((await call("ns-scoped", `/engram/v1/peers/${PEER_ID}`, { method: "DELETE" })).status, 403, "peer_delete denied");
+    assert.equal(
+      (
+        await call("ns-scoped", `/engram/v1/peers/${PEER_ID}?forget=true`, {
+          method: "DELETE",
+          body: JSON.stringify({ confirm: "yes" }),
+        })
+      ).status,
+      403,
+      "peer_forget denied",
+    );
+    assert.equal((await call("ns-scoped", `/engram/v1/peers/${PEER_ID}/profile`)).status, 403, "peer_profile_get denied");
+
+    // Empty namespace allow-list: denied too.
+    assert.equal((await call("ns-empty", "/engram/v1/peers")).status, 403, "empty namespace list denied");
+
+    // Denials never reached the stores — no file read effect, no mutation.
+    assert.deepEqual(await snapshotDir(root), before, "denied requests must not change any peer file");
+
+    // An ops-scoped token without a namespace axis keeps full peer access.
+    const listed = await call("ops-peer", "/engram/v1/peers");
+    assert.equal(listed.status, 200, "ops-scoped token lists peers");
+    // SAFETY: the peer_list REST route returns the service envelope { peers }.
+    const listedBody = (await listed.json()) as { peers: { id: string }[] };
+    assert.deepEqual(listedBody.peers.map((p) => p.id), [PEER_ID], "ops-scoped token sees the seeded peer");
+
+    const created = await call("ops-peer", "/engram/v1/peers/ops-peer-1", {
+      method: "PUT",
+      body: JSON.stringify({ displayName: "ops token peer" }),
+    });
+    assert.equal(created.status, 201, "ops-scoped token registers a peer");
+    // SAFETY: the peer_set REST route returns the upsert outcome { created, peer }.
+    const createdBody = (await created.json()) as { created: boolean; peer: { displayName: string } };
+    assert.equal(createdBody.created, true);
+    assert.equal(createdBody.peer.displayName, "ops token peer");
+
+    const purged = await call("ops-peer", "/engram/v1/peers/ops-peer-1?forget=true", {
+      method: "DELETE",
+      body: JSON.stringify({ confirm: "yes" }),
+    });
+    assert.equal(purged.status, 200, "ops-scoped token purges a peer");
+    await purged.text();
+    const afterPurge = await snapshotDir(root);
+    assert.ok(
+      !afterPurge.some((line) => line.startsWith("peers/ops-peer-1/")),
+      "the destructive purge removed the peer directory",
+    );
+
+    // Legacy unrestricted token (static authToken, no capability record).
+    const legacyList = await call("legacy-operator", "/engram/v1/peers");
+    assert.equal(legacyList.status, 200, "legacy token lists peers");
+    await legacyList.text();
+
+    // Peer-forget confirmation behavior is unchanged: no confirm body, no purge.
+    const unconfirmed = await call("legacy-operator", `/engram/v1/peers/${PEER_ID}?forget=true`, {
+      method: "DELETE",
+      body: JSON.stringify({}),
+    });
+    assert.equal(unconfirmed.status, 400, "missing confirm still fails with 400");
+    assert.match(await unconfirmed.text(), /confirm_required/);
+    const seededIntact = await snapshotDir(root);
+    assert.ok(
+      seededIntact.some((line) => line.startsWith(`peers/${PEER_ID}/identity.md`)),
+      "the seeded peer survived the rejected confirmation",
+    );
+
+    // A malformed PUT body still fails loudly instead of silently defaulting.
+    const malformed = await call("legacy-operator", "/engram/v1/peers/malformed-peer", {
+      method: "PUT",
+      body: JSON.stringify({ displayName: 5 }),
+    });
+    assert.equal(malformed.status, 400, "a non-string displayName is rejected");
+    assert.match(await malformed.text(), /displayName/);
+    assert.ok(
+      !(await snapshotDir(root)).some((line) => line.startsWith("peers/malformed-peer/")),
+      "the rejected write created no peer file",
+    );
+
+    // An explicit null is a malformed field too (rule 51): the operation
+    // schema strips nulls, so the route must reject them before dispatch
+    // instead of registering the peer with default kind/name/notes.
+    for (const field of ["kind", "displayName", "notes"]) {
+      const nullField = await call("legacy-operator", `/engram/v1/peers/null-${field}-peer`, {
+        method: "PUT",
+        body: JSON.stringify({ [field]: null }),
+      });
+      assert.equal(nullField.status, 400, `an explicit null ${field} is rejected`);
+      assert.match(await nullField.text(), new RegExp(field));
+      assert.ok(
+        !(await snapshotDir(root)).some((line) => line.startsWith(`peers/null-${field}-peer/`)),
+        `the null ${field} request created no peer file`,
+      );
+    }
+  } finally {
+    await server.stop();
+    await cleanup();
+  }
+});

package/src/access-http.test.ts

@@ -13,8 +13,8 @@ import {
 import { peerManifestRevision } from "./reconcile/manifest.js";
 import {
   EngramAccessInputError,
+  EngramAccessService,
   type EngramAccessRecallRequest,
-  type EngramAccessService,
   type EngramAccessBriefingRequest,
 } from "./access-service.js";
 import {
@@ -815,6 +815,48 @@ test("HTTP coding-context endpoint accepts projectTag shorthand", async () => {
   }
 });
 
+test("HTTP observe answers 503 buffer_admission_refused when durable capture hits the entry cap", async () => {
+  const refusal = new Error("buffer at session-entry cap");
+  refusal.name = "ReplayAdmissionRefusedError";
+  // SAFETY: this fixture drives only the observe route; the remaining service members are unreachable.
+  const service = Object.assign({} as EngramAccessService, {
+    observe: async () => {
+      throw refusal;
+    },
+  });
+  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/observe`,
+      {
+        method: "POST",
+        headers: {
+          authorization: "Bearer test-token",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          sessionKey: "capacity-test-session",
+          messages: [{ role: "user", content: "retry me" }],
+        }),
+      },
+    );
+    assert.equal(response.status, 503, "admission backpressure is retryable, not a server fault");
+    assert.deepEqual(await response.json(), {
+      error: "buffer at session-entry cap",
+      code: "buffer_admission_refused",
+    });
+  } finally {
+    await server.stop();
+  }
+});
+
 test("HTTP briefing endpoint dispatches through the briefing operation", async () => {
   const calls: unknown[] = [];
   const service = {
@@ -2996,11 +3038,11 @@ test("HTTP scoped-token namespace allow-list is enforced on every namespace rout
       "scoped memory_get: the allowed namespace reaches the service",
     );
 
-    // ── a non-namespace-scoped route is unaffected by namespace scoping ──
+    // ── a global-store route is fleet-wide: a namespace-scoped token is denied (issue #3225 B3) ──
     assert.equal(
       (await request("scoped-ns-a", "/engram/v1/peers")).status,
-      200,
-      "a non-namespace-scoped route must be unaffected",
+      403,
+      "peer routes touch global stores, so a namespace-scoped token is denied",
     );
 
     // ── unrestricted token: omitting namespace still reaches the default tenant ──
@@ -6515,3 +6557,206 @@ test("a budget above the backend cap still gets the rows it asked for", async ()
     "the excluded hit was replaced, not subtracted",
   );
 });
+
+/**
+ * Prototype-backed service stub for the write-quota tests: the constructor's
+ * surface getters read only `orchestrator.config`, and each test overrides the
+ * single member its route dispatches.
+ */
+function quotaStubService(): EngramAccessService {
+  // SAFETY: the prototype supplies the untouched service surface; each quota test overrides only the member its route dispatches.
+  const service = Object.create(EngramAccessService.prototype) as EngramAccessService;
+  // SAFETY: startup reads only orchestrator.config from the service; an empty config keeps every surface flag false.
+  Reflect.set(service, "orchestrator", { config: {} });
+  return service;
+}
+
+test("concurrent distinct-payload writes cannot overshoot the write quota (issue #3225 C4)", async () => {
+  // Checking hasCapacity before the operation and calling record after it
+  // left a window where N in-flight writes all pass against the same
+  // committed count. Admission must reserve a slot, so only LIMIT of TOTAL
+  // overlapping writes proceed and the rest get 429.
+  const LIMIT = 2;
+  const TOTAL = 6;
+  let dispatches = 0;
+  const firstDispatched = Promise.withResolvers<void>();
+  const releaseWrites = Promise.withResolvers<void>();
+  const service = quotaStubService();
+  service.capsuleExport = async (request) => {
+    dispatches += 1;
+    if (dispatches === 1) firstDispatched.resolve();
+    await releaseWrites.promise;
+    // SAFETY: the route serializes this stub result into the HTTP response; the test asserts statuses, not this shape.
+    return { ok: true, name: request.name } as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: LIMIT,
+  });
+  const status = await server.start();
+  const post = (index: number) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/capsules/export`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ name: `quota-race-${index}` }),
+    });
+  try {
+    const first = post(0);
+    await firstDispatched.promise;
+    const rest = Array.from({ length: TOTAL - 1 }, (_, index) => post(index + 1));
+    // The first write is admitted and held open inside the service, so every
+    // other request must run its admission check against an unrecorded
+    // window. Loopback arrival needs a bounded grace; the overlap cannot be
+    // driven deterministically because admission is server-internal.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    releaseWrites.resolve();
+    const responses = await Promise.all([first, ...rest]);
+    const statuses = responses.map((response) => response.status).sort((a, b) => a - b);
+    assert.deepEqual(
+      statuses,
+      [...Array<number>(LIMIT).fill(200), ...Array<number>(TOTAL - LIMIT).fill(429)],
+      `expected exactly ${LIMIT} admitted writes and ${TOTAL - LIMIT} rejections, got ${JSON.stringify(statuses)}`,
+    );
+  } finally {
+    releaseWrites.resolve();
+    await server.stop();
+  }
+});
+
+test("a failed write releases its reserved quota slot (issue #3225 C4)", async () => {
+  let calls = 0;
+  const service = quotaStubService();
+  service.capsuleExport = async (request) => {
+    calls += 1;
+    if (calls === 1) throw new Error("export backend failed");
+    // SAFETY: the route serializes this stub result into the HTTP response; the test asserts statuses, not this shape.
+    return { ok: true, name: request.name } as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  const post = (name: string) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/capsules/export`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ name }),
+    });
+  try {
+    // The first export fails in the backend; the slot it reserved at
+    // admission must be released, so the retry is admitted and only then
+    // does the window fill.
+    assert.equal((await post("quota-fail-1")).status, 500);
+    assert.equal((await post("quota-fail-2")).status, 200);
+    assert.equal((await post("quota-fail-3")).status, 429);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("a replayed observe never 429s and never consumes a second quota slot (issue #1434, #3225 C4)", async () => {
+  const stored = new Map<string, { sessionKey: string }>();
+  let hookCalls = 0;
+  const service = quotaStubService();
+  service.observe = async (request, hooks) => {
+    const key = request.idempotencyKey?.trim();
+    const cached = key ? stored.get(key) : undefined;
+    if (cached) {
+      // SAFETY: the route only forwards this result into the HTTP response and reads its dryRun/idempotencyReplay flags.
+      return { ...cached, idempotencyReplay: true } as never;
+    }
+    // Mirror the real service contract: the quota hook fires exactly once,
+    // immediately before an actual write commits, never on a replay.
+    await hooks?.enforceWriteQuota?.();
+    hookCalls += 1;
+    const response = { sessionKey: request.sessionKey };
+    stored.set(key ?? "", response);
+    // SAFETY: the route only forwards this result into the HTTP response and reads its dryRun/idempotencyReplay flags.
+    return response as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  const post = (idempotencyKey: string) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/observe`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        sessionKey: "quota-replay",
+        messages: [{ role: "user", content: "hello" }],
+        idempotencyKey,
+      }),
+    });
+  try {
+    assert.equal((await post("quota-replay-1")).status, 202);
+    const replay = await post("quota-replay-1");
+    assert.equal(replay.status, 202);
+    // SAFETY: our own server serialized this body; the test reads only the idempotencyReplay flag.
+    const replayBody = (await replay.json()) as { idempotencyReplay?: boolean };
+    assert.equal(replayBody.idempotencyReplay, true);
+    assert.equal(hookCalls, 1, "the replay must not re-run the quota hook");
+    // The window still holds exactly the first write's slot: a different
+    // payload is rejected, proving the replay consumed nothing.
+    assert.equal((await post("quota-replay-2")).status, 429);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("a dreams dry run neither 429s nor consumes quota at a full window (#3225 C4)", async () => {
+  const service = quotaStubService();
+  service.dreamsRun = async (options) => {
+    // SAFETY: the route serializes this stub result into the HTTP response and reads its dryRun flag.
+    return { phase: options.phase, dryRun: options.dryRun === true } as never;
+  };
+  const server = new EngramAccessHttpServer({
+    service,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+    writeRateLimitMaxRequests: 1,
+  });
+  const status = await server.start();
+  const post = (body: Record<string, boolean>) =>
+    fetch(`http://127.0.0.1:${status.port}/engram/v1/dreams/run`, {
+      method: "POST",
+      headers: {
+        authorization: "Bearer test-token",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ phase: "lightSleep", ...body }),
+    });
+  try {
+    assert.equal((await post({})).status, 200);
+    // The window is full; the dry run must pass and leave the count alone.
+    const dry = await post({ dryRun: true });
+    assert.equal(dry.status, 200);
+    // SAFETY: our own server serialized this body; the test reads only the dryRun flag.
+    const dryBody = (await dry.json()) as { dryRun?: boolean };
+    assert.equal(dryBody.dryRun, true);
+    assert.equal((await post({})).status, 429);
+  } finally {
+    await server.stop();
+  }
+});