@remnic/core 9.54.5 → 9.54.7

package/src/relay/mission-access.test.ts

@@ -367,25 +367,25 @@ test("Relay write quota releases the exact reservation when timestamps collide",
     adminConsoleEnabled: false,
   });
   const internals = server as unknown as {
-    writeLimiter: { slotsFor(principal?: string): ReadonlyArray<{ readonly recordedAt: number }> };
-    reserveWriteRateLimitSlot: () => () => void;
+    writeLimiter: {
+      slotsFor(principal?: string): ReadonlyArray<{ readonly recordedAt: number }>;
+      inFlightFor(principal?: string): number;
+    };
+    reserveWriteRateLimitSlot: () => { commit(): void; release(): void };
   };
   const originalNow = Date.now;
   try {
     Date.now = () => 1_754_000_000_000;
-    const releaseCommitted = internals.reserveWriteRateLimitSlot();
+    const committed = internals.reserveWriteRateLimitSlot();
+    committed.commit();
     const committedSlot = internals.writeLimiter.slotsFor()[0];
-    const releaseFailed = internals.reserveWriteRateLimitSlot();
-    const failedSlot = internals.writeLimiter.slotsFor()[1];
+    const failed = internals.reserveWriteRateLimitSlot();
     assert.ok(committedSlot);
-    assert.ok(failedSlot);
-    assert.notEqual(committedSlot, failedSlot);
+    assert.equal(internals.writeLimiter.inFlightFor(), 1);
 
-    releaseFailed();
+    failed.release();
     assert.deepEqual(internals.writeLimiter.slotsFor(), [committedSlot]);
-
-    releaseCommitted();
-    assert.deepEqual(internals.writeLimiter.slotsFor(), []);
+    assert.equal(internals.writeLimiter.inFlightFor(), 0);
   } finally {
     Date.now = originalNow;
   }

package/src/relay/mission-ui.test.ts

@@ -62,7 +62,9 @@ test("Relay Mission Control serves both aliases from one exact static allow-list
         });
         assert.equal(authorizedShell.status, 200);
         assert.equal(authorizedShell.headers.get("cache-control"), "private, no-store");
-        assert.match(await authorizedShell.text(), /__REMNIC_ADMIN_CONSOLE_PREFILL_TOKEN__="relay-token"/);
+        const authorizedShellText = await authorizedShell.text();
+        assert.match(authorizedShellText, /Object\.defineProperty\(window,key/);
+        assert.match(authorizedShellText, /\}\)\("relay-token",document\.currentScript\)/);
 
         const expectedAssets = new Map([
           ["relay.css", /^text\/css/],

package/src/storage/tombstone-blocked-capture-sync.ts

@@ -11,6 +11,7 @@ import { pathMayCarryEntityRefs, requestEntityCanonicalIdReconcile } from "./ent
 import { withRawEntityPageMutation } from "./entity-canonical-id-lock.js";
 import { readMaybeEncryptedFileFromChunks, writeMaybeEncryptedFileFromChunks } from "../secure-store/secure-fs.js";
 import * as archiveMutation from "../archive-mutation-version.js";
+import { invalidationCommitFingerprint } from "./deletion-revision-store.js";
 import {
   buildExplicitCaptureDedupKey,
   buildCapturePathLockIdentity,
@@ -236,6 +237,36 @@ export abstract class TombstoneBlockedCaptureIndexHost {
     return await this.getTombstoneBlockedCaptureIndex().withCaptureWriteLock(task, identity);
   }
 
+  /** Read selected memories while their mutation locks remain held. */
+  async readMemorySnapshotsIfUnchanged(expected: readonly MemoryFile[]): Promise<MemoryFile[] | null> {
+    return await this.withMemorySnapshotsIfUnchanged(expected, async (memories) => memories);
+  }
+
+  async withMemorySnapshotsIfUnchanged<T>(
+    expected: readonly MemoryFile[],
+    task: (memories: MemoryFile[]) => Promise<T>,
+  ): Promise<T | null> {
+    if (expected.length === 0) return await task([]);
+    const pathnames = [...new Set(expected.map((memory) => memory.path))];
+    if (pathnames.length !== expected.length) return null;
+    return await this.withTombstoneBlockedCaptureWriteLock(async () => {
+      const current = await Promise.all(pathnames.map((pathname) => this.readMemoryByPath(pathname)));
+      for (let index = 0; index < expected.length; index += 1) {
+        const actual = current[index];
+        const snapshot = expected[index];
+        if (
+          !actual ||
+          !snapshot ||
+          actual.frontmatter.id !== snapshot.frontmatter.id ||
+          invalidationCommitFingerprint(actual) !== invalidationCommitFingerprint(snapshot)
+        ) {
+          return null;
+        }
+      }
+      return await task(current as MemoryFile[]);
+    }, pathnames.map(buildCapturePathLockIdentity));
+  }
+
   protected async withTombstoneBlockedCaptureWriteLockAndHashes<T>(
     task: () => Promise<T>,
     identity: string | readonly string[] | undefined,

package/src/storage-contract/failure-semantics.test.ts

@@ -52,6 +52,108 @@ test("failure-semantics: getMemoryById on empty store returns null (not throw)",
   }
 });
 
+test("failure-semantics: selected memory snapshots reject a changed member", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const first = await storage.writeMemory("preference", "First source");
+    const second = await storage.writeMemory("preference", "Second source");
+    const firstSnapshot = await storage.readMemoryByPath(first.memory.path);
+    const secondSnapshot = await storage.readMemoryByPath(second.memory.path);
+    assert.ok(firstSnapshot);
+    assert.ok(secondSnapshot);
+    assert.equal(await storage.updateMemory(second.id, "Changed source"), true);
+
+    assert.equal(await storage.readMemorySnapshotsIfUnchanged([firstSnapshot, secondSnapshot]), null);
+    assert.deepEqual(
+      (await storage.readMemorySnapshotsIfUnchanged([firstSnapshot]))?.map((memory) => memory.frontmatter.id),
+      [first.id]
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: selected memory snapshots block member writes until every read completes", async () => {
+  const { storage, cleanup } = await makeStorage();
+  const secondReadStarted = Promise.withResolvers<void>();
+  const releaseSecondRead = Promise.withResolvers<void>();
+  try {
+    const first = await storage.writeMemory("preference", "First source");
+    const second = await storage.writeMemory("preference", "Second source");
+    const firstSnapshot = await storage.readMemoryByPath(first.memory.path);
+    const secondSnapshot = await storage.readMemoryByPath(second.memory.path);
+    assert.ok(firstSnapshot);
+    assert.ok(secondSnapshot);
+    const readMemoryByPath = storage.readMemoryByPath.bind(storage);
+    let pauseSecond = true;
+    storage.readMemoryByPath = async (filePath) => {
+      const memory = await readMemoryByPath(filePath);
+      if (pauseSecond && filePath === second.memory.path) {
+        pauseSecond = false;
+        secondReadStarted.resolve();
+        await releaseSecondRead.promise;
+      }
+      return memory;
+    };
+
+    const snapshotPromise = storage.readMemorySnapshotsIfUnchanged([firstSnapshot, secondSnapshot]);
+    await secondReadStarted.promise;
+    let writeSettled = false;
+    const writePromise = storage.updateMemory(first.id, "Changed source").finally(() => {
+      writeSettled = true;
+    });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(writeSettled, false);
+
+    releaseSecondRead.resolve();
+    assert.deepEqual(
+      (await snapshotPromise)?.map((memory) => memory.frontmatter.id),
+      [first.id, second.id]
+    );
+    assert.equal(await writePromise, true);
+  } finally {
+    releaseSecondRead.resolve();
+    await cleanup();
+  }
+});
+
+test("failure-semantics: selected memory snapshot tasks hold every member lock", async () => {
+  const { storage, cleanup } = await makeStorage();
+  const taskStarted = Promise.withResolvers<void>();
+  const releaseTask = Promise.withResolvers<void>();
+  try {
+    const first = await storage.writeMemory("preference", "First source");
+    const second = await storage.writeMemory("preference", "Second source");
+    const firstSnapshot = await storage.readMemoryByPath(first.memory.path);
+    const secondSnapshot = await storage.readMemoryByPath(second.memory.path);
+    assert.ok(firstSnapshot);
+    assert.ok(secondSnapshot);
+
+    const snapshotTask = storage.withMemorySnapshotsIfUnchanged(
+      [firstSnapshot, secondSnapshot],
+      async (memories) => {
+        taskStarted.resolve();
+        await releaseTask.promise;
+        return memories.map((memory) => memory.frontmatter.id);
+      },
+    );
+    await taskStarted.promise;
+    let writeSettled = false;
+    const writePromise = storage.updateMemoryIfUnchanged(firstSnapshot, "Changed source").finally(() => {
+      writeSettled = true;
+    });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    assert.equal(writeSettled, false);
+
+    releaseTask.resolve();
+    assert.deepEqual(await snapshotTask, [first.id, second.id]);
+    assert.equal(await writePromise, true);
+  } finally {
+    releaseTask.resolve();
+    await cleanup();
+  }
+});
+
 test("failure-semantics: readMemoryByPath on a non-existent file returns null (not throw)", async () => {
   const { storage, baseDir, cleanup } = await makeStorage();
   try {

package/src/support-passport/access-http-base.ts

@@ -0,0 +1,143 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import path from "node:path";
+
+import { EngramAccessForbiddenError } from "../access-errors.js";
+import type { EngramAccessService } from "../access-service.js";
+import { enforceNamespaceAllowList, tokenCapabilityStore } from "../access-token-capabilities.js";
+import type { WriteRateLimitReservation } from "../write-rate-limiter.js";
+import { handleSupportPassportOwnerHttp } from "./access-http.js";
+import { buildSupportPassportPublicRequestHandler } from "./public-http.js";
+
+const SUPPORT_PASSPORT_QUOTA_LIMITED_WRITE_TOOLS = new Set([
+  "engram.support_passport_draft_create",
+  "remnic.support_passport_draft_create",
+  "engram.support_passport_drafts_generate",
+  "remnic.support_passport_drafts_generate",
+  "engram.support_passport_card_replace",
+  "remnic.support_passport_card_replace",
+  "engram.support_passport_card_approve",
+  "remnic.support_passport_card_approve",
+  "engram.support_passport_card_reject",
+  "remnic.support_passport_card_reject",
+  "engram.support_passport_card_withdraw",
+  "remnic.support_passport_card_withdraw",
+  "engram.support_passport_grant_create",
+  "remnic.support_passport_grant_create",
+  "engram.support_passport_grant_revoke",
+  "remnic.support_passport_grant_revoke",
+]);
+const SUPPORT_PASSPORT_ADMIN_CONSOLE_ASSETS = new Map<string, string>([
+  ["what-helps-me.css", "text/css; charset=utf-8"],
+  ["model.js", "application/javascript; charset=utf-8"],
+  ["app.js", "application/javascript; charset=utf-8"],
+]);
+
+export abstract class SupportPassportAccessHttpBase {
+  private supportPassportPublicHandler: ReturnType<typeof buildSupportPassportPublicRequestHandler> | undefined;
+  protected abstract readonly service: EngramAccessService;
+  protected abstract readonly adminConsolePublicDir: string;
+  protected abstract resolveRequestPrincipal(req: IncomingMessage): string | undefined;
+  protected abstract readJsonBody(req: IncomingMessage, maxBodyBytes?: number): Promise<Record<string, unknown>>;
+  protected abstract respondJson(res: ServerResponse, status: number, payload: unknown): void;
+  protected abstract reserveWriteRateLimitSlot(req?: IncomingMessage): WriteRateLimitReservation;
+  protected abstract respondAdminConsoleShell(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string,
+    relativePath?: string,
+    allowPrefill?: boolean,
+  ): Promise<void>;
+  protected abstract respondStatic(res: ServerResponse, filePath: string, contentType: string): Promise<void>;
+
+  protected handleSupportPassportOwnerRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string,
+    hasQuery: boolean,
+    abortSignal: AbortSignal
+  ): Promise<boolean> {
+    return handleSupportPassportOwnerHttp({
+      req,
+      res,
+      pathname,
+      hasQuery,
+      service: this.service,
+      principal: this.resolveRequestPrincipal(req),
+      abortSignal,
+      readJsonBody: () => this.readJsonBody(req),
+      respondJson: (status, payload) => {
+        res.setHeader("cache-control", "private, no-store");
+        res.setHeader("vary", "Authorization");
+        this.respondJson(res, status, payload);
+      },
+      reserveWriteRateLimitSlot: () => this.reserveWriteRateLimitSlot(req),
+    });
+  }
+
+  protected handleSupportPassportPublicRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+    this.supportPassportPublicHandler ??= buildSupportPassportPublicRequestHandler(this.service, {
+      trustedProxyAddresses: this.service.configRef?.supportPassport?.trustedProxyAddresses ?? [],
+    });
+    return this.supportPassportPublicHandler(req, res, {
+      authorized: false,
+      tokenAuthorized: false,
+    });
+  }
+
+  protected async enforceSupportPassportAuthorizationProbe(req: IncomingMessage): Promise<void> {
+    const principal = this.resolveRequestPrincipal(req)?.trim();
+    if (!principal) {
+      throw new EngramAccessForbiddenError("A trusted principal is required for support passport access.");
+    }
+    const owner = await this.service.getWritableStorageForNamespace(undefined, principal);
+    enforceNamespaceAllowList(
+      tokenCapabilityStore.getStore(),
+      owner.namespace,
+      this.service.configRef.defaultNamespace
+    );
+  }
+
+  protected isSupportPassportQuotaLimitedWriteTool(toolName: string): boolean {
+    return SUPPORT_PASSPORT_QUOTA_LIMITED_WRITE_TOOLS.has(toolName);
+  }
+
+  protected async handleSupportPassportUi(
+    req: IncomingMessage,
+    res: ServerResponse,
+    pathname: string
+  ): Promise<boolean> {
+    if (req.method !== "GET") return false;
+    const isSupportPassportPath =
+      pathname === "/remnic/ui/what-helps-me" ||
+      pathname === "/engram/ui/what-helps-me" ||
+      pathname.startsWith("/remnic/ui/what-helps-me/") ||
+      pathname.startsWith("/engram/ui/what-helps-me/");
+    if (!isSupportPassportPath) return false;
+    if (!this.service.supportPassportEnabled) {
+      this.respondJson(res, 404, { error: "not_found" });
+      return true;
+    }
+    if (pathname === "/remnic/ui/what-helps-me" || pathname === "/engram/ui/what-helps-me") {
+      const search = new URL(req.url ?? pathname, "http://placeholder").search;
+      res.statusCode = 301;
+      res.setHeader("location", `${pathname}/${search}`);
+      res.end();
+      return true;
+    }
+    if (pathname === "/remnic/ui/what-helps-me/" || pathname === "/engram/ui/what-helps-me/") {
+      const helperRequest = new URL(req.url ?? pathname, "http://placeholder").searchParams.has("grant");
+      res.setHeader("content-security-policy", "frame-ancestors 'none'");
+      res.setHeader("x-frame-options", "DENY");
+      await this.respondAdminConsoleShell(req, res, pathname, "what-helps-me/index.html", !helperRequest);
+      return true;
+    }
+    const fileName = pathname.split("/").at(-1) ?? "";
+    const assetType = SUPPORT_PASSPORT_ADMIN_CONSOLE_ASSETS.get(fileName);
+    if (assetType && pathname.split("/").length === 5) {
+      await this.respondStatic(res, path.join(this.adminConsolePublicDir, "what-helps-me", fileName), assetType);
+      return true;
+    }
+    this.respondJson(res, 404, { error: "not_found" });
+    return true;
+  }
+}

package/src/support-passport/access-http.ts

@@ -0,0 +1,172 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { type OperationName, getOperation } from "../access-boundary.js";
+import type { EngramAccessService } from "../access-service.js";
+import { SupportPassportError } from "./errors.js";
+import { SupportPassportOwnerCreateGrantRequestSchema } from "./grant-contracts.js";
+
+export interface SupportPassportOwnerHttpDependencies {
+  req: IncomingMessage;
+  res: ServerResponse;
+  pathname: string;
+  hasQuery: boolean;
+  service: EngramAccessService;
+  principal?: string;
+  abortSignal: AbortSignal;
+  readJsonBody(): Promise<Record<string, unknown>>;
+  respondJson(status: number, payload: unknown): void;
+  reserveWriteRateLimitSlot(): { commit(): void; release(): void };
+}
+
+const OWNER_ROOT = "/engram/v1/support-passport";
+
+export const SUPPORT_PASSPORT_OWNER_HTTP_ROUTES = [
+  { method: "GET", pathname: `${OWNER_ROOT}/cards`, operation: "support_passport_cards_list" },
+  { method: "POST", pathname: `${OWNER_ROOT}/drafts`, operation: "support_passport_draft_create" },
+  { method: "POST", pathname: `${OWNER_ROOT}/drafts/generate`, operation: "support_passport_drafts_generate" },
+  { method: "GET", pathname: `${OWNER_ROOT}/grants`, operation: "support_passport_grants_list" },
+  { method: "POST", pathname: `${OWNER_ROOT}/grants`, operation: "support_passport_grant_create" },
+  { method: "GET", pathname: `${OWNER_ROOT}/memories/:id`, operation: "support_passport_memory_preview" },
+  { method: "PUT", pathname: `${OWNER_ROOT}/cards/:id`, operation: "support_passport_card_replace" },
+  { method: "POST", pathname: `${OWNER_ROOT}/cards/:id/approve`, operation: "support_passport_card_approve" },
+  { method: "POST", pathname: `${OWNER_ROOT}/cards/:id/reject`, operation: "support_passport_card_reject" },
+  { method: "POST", pathname: `${OWNER_ROOT}/cards/:id/withdraw`, operation: "support_passport_card_withdraw" },
+  { method: "POST", pathname: `${OWNER_ROOT}/grants/:id/revoke`, operation: "support_passport_grant_revoke" },
+] as const satisfies ReadonlyArray<{ method: string; pathname: string; operation: OperationName }>;
+
+function decodeId(value: string, label: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new SupportPassportError("invalid_input", `${label} is invalid.`, 400);
+  }
+}
+
+function closeUnreadRequestAfterResponse(req: IncomingMessage, res: ServerResponse): void {
+  const contentLength = req.headers["content-length"];
+  const declaresBody =
+    req.headers["transfer-encoding"] !== undefined ||
+    (contentLength !== undefined && contentLength !== "0");
+  if (!declaresBody || req.readableEnded || req.destroyed) return;
+  res.shouldKeepAlive = false;
+  res.setHeader("connection", "close");
+  res.once("finish", () => req.destroy());
+}
+
+async function runOperation(
+  name: OperationName,
+  input: Record<string, unknown>,
+  dependencies: SupportPassportOwnerHttpDependencies,
+  recordWriteCommit?: () => void
+): Promise<unknown> {
+  const operation = getOperation(name);
+  if (!operation) throw new Error(`access-boundary: operation not registered: ${name}`);
+  const output = (await operation.run(input, {
+    service: dependencies.service,
+    authenticatedPrincipal: dependencies.principal,
+    abortSignal: dependencies.abortSignal,
+    ...(recordWriteCommit ? { hooks: { recordWriteCommit } } : {}),
+  })) as { result: unknown };
+  return output.result;
+}
+
+async function runWrite(
+  name: OperationName,
+  input: Record<string, unknown>,
+  dependencies: SupportPassportOwnerHttpDependencies
+): Promise<unknown> {
+  const writeQuota = dependencies.reserveWriteRateLimitSlot();
+  try {
+    const result = await runOperation(name, input, dependencies, writeQuota.commit);
+    writeQuota.commit();
+    return result;
+  } catch (error) {
+    writeQuota.release();
+    throw error;
+  }
+}
+
+export async function handleSupportPassportOwnerHttp(
+  dependencies: SupportPassportOwnerHttpDependencies
+): Promise<boolean> {
+  const { req, pathname } = dependencies;
+  try {
+    let operation: OperationName | undefined;
+    let input: Record<string, unknown> = {};
+    let quotaLimitedWrite = false;
+
+    if (req.method === "GET" && pathname === `${OWNER_ROOT}/cards`) {
+      operation = "support_passport_cards_list";
+    } else if (req.method === "POST" && pathname === `${OWNER_ROOT}/drafts`) {
+      operation = "support_passport_draft_create";
+      quotaLimitedWrite = true;
+    } else if (req.method === "POST" && pathname === `${OWNER_ROOT}/drafts/generate`) {
+      operation = "support_passport_drafts_generate";
+      quotaLimitedWrite = true;
+    } else if (pathname === `${OWNER_ROOT}/grants` && req.method === "GET") {
+      operation = "support_passport_grants_list";
+    } else if (pathname === `${OWNER_ROOT}/grants` && req.method === "POST") {
+      operation = "support_passport_grant_create";
+      quotaLimitedWrite = true;
+    } else {
+      const memoryMatch = new RegExp(`^${OWNER_ROOT}/memories/([^/]+)$`).exec(pathname);
+      const cardMatch = new RegExp(`^${OWNER_ROOT}/cards/([^/]+)(?:/(approve|reject|withdraw))?$`).exec(pathname);
+      const grantMatch = new RegExp(`^${OWNER_ROOT}/grants/([^/]+)/revoke$`).exec(pathname);
+      if (memoryMatch && req.method === "GET") {
+        operation = "support_passport_memory_preview";
+        input.memoryId = decodeId(memoryMatch[1] ?? "", "memoryId");
+      } else if (cardMatch && req.method === "PUT" && !cardMatch[2]) {
+        operation = "support_passport_card_replace";
+        input.cardId = decodeId(cardMatch[1] ?? "", "cardId");
+        quotaLimitedWrite = true;
+      } else if (cardMatch && req.method === "POST" && cardMatch[2]) {
+        operation = `support_passport_card_${cardMatch[2]}` as OperationName;
+        input.cardId = decodeId(cardMatch[1] ?? "", "cardId");
+        quotaLimitedWrite = true;
+      } else if (grantMatch && req.method === "POST") {
+        operation = "support_passport_grant_revoke";
+        input.grantId = decodeId(grantMatch[1] ?? "", "grantId");
+        quotaLimitedWrite = true;
+      }
+    }
+
+    if (!operation) return false;
+    dependencies.res.setHeader("cache-control", "private, no-store");
+    dependencies.res.setHeader("vary", "Authorization");
+    if (dependencies.hasQuery) {
+      throw new SupportPassportError("invalid_input", "Support passport routes do not accept query values.", 400);
+    }
+    if (req.method !== "GET") {
+      const body = await dependencies.readJsonBody();
+      for (const pathField of Object.keys(input)) {
+        if (Object.hasOwn(body, pathField)) {
+          throw new SupportPassportError("invalid_input", `${pathField} belongs in the URL path.`, 400);
+        }
+      }
+      input = { ...input, ...body };
+    }
+    if (operation === "support_passport_drafts_generate" && !Object.hasOwn(input, "sourceMemoryRevisions")) {
+      throw new SupportPassportError("invalid_input", "Review the selected notes again before drafting.", 400);
+    }
+    if (operation === "support_passport_grant_create") {
+      const grant = SupportPassportOwnerCreateGrantRequestSchema.safeParse(input);
+      if (!grant.success) throw new SupportPassportError("invalid_input", "The share link request is invalid.", 400);
+      input = {
+        cardIds: grant.data.cardIds,
+        cardRevisions: grant.data.cardRevisions,
+        ...(grant.data.expiresAt !== undefined
+          ? { expiresAt: grant.data.expiresAt }
+          : { durationMs: grant.data.durationMs }),
+      };
+    }
+    const result = quotaLimitedWrite
+      ? await runWrite(operation, input, dependencies)
+      : await runOperation(operation, input, dependencies);
+    dependencies.respondJson(200, result);
+  } catch (error) {
+    if (!(error instanceof SupportPassportError)) throw error;
+    closeUnreadRequestAfterResponse(req, dependencies.res);
+    dependencies.respondJson(error.status, { error: error.message, code: error.code });
+  }
+  return true;
+}