@coreyuan/vector-mind 1.0.54 → 1.1.0

package/admin-panel/server/security.mjs

@@ -0,0 +1,117 @@
+import crypto from "node:crypto";
+
+export const ADMIN_TOKEN_HEADER = "x-vectormind-admin-token";
+
+function normalizeHostname(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.$/, "");
+}
+
+function effectivePort(protocol, port) {
+  if (port) return Number(port);
+  return protocol === "https:" ? 443 : 80;
+}
+
+function parseRequestHost(hostHeader, protocol = "http") {
+  if (!hostHeader) return null;
+  const normalizedProtocol = String(protocol).endsWith(":") ? String(protocol) : `${protocol}:`;
+  try {
+    const url = new URL(`${normalizedProtocol}//${hostHeader}`);
+    return {
+      hostname: normalizeHostname(url.hostname),
+      port: effectivePort(url.protocol, url.port),
+      protocol: url.protocol,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function isLoopbackHostname(hostname) {
+  const normalized = normalizeHostname(hostname);
+  if (normalized === "localhost" || normalized === "::1") return true;
+  const match = normalized.match(/^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  return Boolean(match && match.slice(1).every((part) => Number(part) <= 255));
+}
+
+export function isLoopbackAddress(address) {
+  const normalized = String(address ?? "").trim().toLowerCase().split("%")[0];
+  if (normalized === "::1") return true;
+  if (normalized.startsWith("::ffff:")) return isLoopbackHostname(normalized.slice(7));
+  return isLoopbackHostname(normalized);
+}
+
+export function isAllowedAdminOrigin({ origin, hostHeader, protocol = "http" }) {
+  if (!origin) return true;
+  const requestHost = parseRequestHost(hostHeader, protocol);
+  if (!requestHost) return false;
+  try {
+    const parsedOrigin = new URL(origin);
+    if (parsedOrigin.protocol !== "http:" && parsedOrigin.protocol !== "https:") return false;
+    return (
+      normalizeHostname(parsedOrigin.hostname) === requestHost.hostname &&
+      effectivePort(parsedOrigin.protocol, parsedOrigin.port) === requestHost.port &&
+      parsedOrigin.protocol === requestHost.protocol
+    );
+  } catch {
+    return false;
+  }
+}
+
+function tokensEqual(providedToken, expectedToken) {
+  if (!providedToken || !expectedToken) return false;
+  const provided = Buffer.from(String(providedToken));
+  const expected = Buffer.from(String(expectedToken));
+  return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
+}
+
+export function createAdminSecurityPolicy({ host, port, configuredToken, generateToken } = {}) {
+  const normalizedHost = normalizeHostname(host);
+  const normalizedPort = Number(port);
+  if (!normalizedHost || !Number.isInteger(normalizedPort) || normalizedPort < 1 || normalizedPort > 65535) {
+    throw new Error("管理面板监听地址或端口无效。");
+  }
+
+  const mode = isLoopbackHostname(normalizedHost) ? "automatic" : "explicit";
+  const explicitToken = String(configuredToken ?? "").trim();
+  if (mode === "explicit" && !explicitToken) {
+    throw new Error("非回环监听必须设置 VECTORMIND_ADMIN_TOKEN。");
+  }
+
+  const token = explicitToken || (generateToken ? generateToken() : crypto.randomBytes(32).toString("hex"));
+  return Object.freeze({ host: normalizedHost, port: normalizedPort, mode, token });
+}
+
+export function evaluateAdminRequest({
+  policy,
+  path,
+  origin,
+  hostHeader,
+  protocol = "http",
+  remoteAddress,
+  providedToken,
+}) {
+  const originAllowed = isAllowedAdminOrigin({ origin, hostHeader, protocol });
+  const requestHost = parseRequestHost(hostHeader, protocol);
+  const tokenValid = tokensEqual(providedToken, policy.token);
+  const publicEndpoint = path === "/config" || path === "/health";
+  const automaticSessionAvailable = Boolean(
+    policy.mode === "automatic" &&
+      originAllowed &&
+      requestHost &&
+      requestHost.port === policy.port &&
+      isLoopbackHostname(requestHost.hostname) &&
+      isLoopbackAddress(remoteAddress),
+  );
+
+  return {
+    originAllowed,
+    tokenValid,
+    publicEndpoint,
+    authorized: originAllowed && (publicEndpoint || tokenValid),
+    exposeSessionToken: path === "/config" && automaticSessionAvailable,
+  };
+}

package/admin-panel/server/security.test.mjs

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createAdminSecurityPolicy,
+  evaluateAdminRequest,
+  isAllowedAdminOrigin,
+  isLoopbackAddress,
+  isLoopbackHostname,
+} from "./security.mjs";
+
+test("loopback detection accepts only concrete loopback hosts and addresses", () => {
+  assert.equal(isLoopbackHostname("localhost"), true);
+  assert.equal(isLoopbackHostname("127.15.2.9"), true);
+  assert.equal(isLoopbackHostname("localhost.example.com"), false);
+  assert.equal(isLoopbackAddress("::1"), true);
+  assert.equal(isLoopbackAddress("::ffff:127.0.0.1"), true);
+  assert.equal(isLoopbackAddress("192.168.1.8"), false);
+});
+
+test("origin validation requires the browser origin to match the request host", () => {
+  assert.equal(
+    isAllowedAdminOrigin({ origin: "http://localhost:16860", hostHeader: "localhost:16860", protocol: "http" }),
+    true,
+  );
+  assert.equal(
+    isAllowedAdminOrigin({ origin: "http://evil.example:16860", hostHeader: "localhost:16860", protocol: "http" }),
+    false,
+  );
+});
+
+test("loopback mode exposes an automatic session only to a loopback request host", () => {
+  const policy = createAdminSecurityPolicy({
+    host: "127.0.0.1",
+    port: 16860,
+    generateToken: () => "automatic-test-token",
+  });
+  const localConfig = evaluateAdminRequest({
+    policy,
+    path: "/config",
+    hostHeader: "localhost:16860",
+    remoteAddress: "::ffff:127.0.0.1",
+  });
+  const reboundConfig = evaluateAdminRequest({
+    policy,
+    path: "/config",
+    hostHeader: "attacker.example:16860",
+    remoteAddress: "127.0.0.1",
+  });
+
+  assert.equal(policy.mode, "automatic");
+  assert.equal(localConfig.exposeSessionToken, true);
+  assert.equal(reboundConfig.exposeSessionToken, false);
+});
+
+test("non-loopback mode requires an explicit token and never exposes it through config", () => {
+  assert.throws(
+    () => createAdminSecurityPolicy({ host: "0.0.0.0", port: 16860 }),
+    /VECTORMIND_ADMIN_TOKEN/,
+  );
+  const policy = createAdminSecurityPolicy({ host: "0.0.0.0", port: 16860, configuredToken: "explicit-test-token" });
+  const configRequest = evaluateAdminRequest({
+    policy,
+    path: "/config",
+    hostHeader: "192.168.1.20:16860",
+    remoteAddress: "192.168.1.30",
+  });
+  const unauthenticatedRequest = evaluateAdminRequest({
+    policy,
+    path: "/projects",
+    hostHeader: "192.168.1.20:16860",
+    remoteAddress: "192.168.1.30",
+  });
+  const authenticatedRequest = evaluateAdminRequest({
+    policy,
+    path: "/projects",
+    hostHeader: "192.168.1.20:16860",
+    remoteAddress: "192.168.1.30",
+    providedToken: "explicit-test-token",
+  });
+
+  assert.equal(policy.mode, "explicit");
+  assert.equal(configRequest.exposeSessionToken, false);
+  assert.equal(unauthenticatedRequest.authorized, false);
+  assert.equal(authenticatedRequest.authorized, true);
+});
+
+test("a missing Origin does not authorize a protected endpoint without a token", () => {
+  const policy = createAdminSecurityPolicy({ host: "10.0.0.4", port: 16860, configuredToken: "explicit-test-token" });
+  const decision = evaluateAdminRequest({
+    policy,
+    path: "/projects/discover",
+    origin: undefined,
+    hostHeader: "10.0.0.4:16860",
+    remoteAddress: "10.0.0.5",
+  });
+  assert.equal(decision.originAllowed, true);
+  assert.equal(decision.authorized, false);
+});
+
+test("a mismatched Origin is rejected even when the token is valid", () => {
+  const policy = createAdminSecurityPolicy({ host: "0.0.0.0", port: 16860, configuredToken: "explicit-test-token" });
+  const decision = evaluateAdminRequest({
+    policy,
+    path: "/projects",
+    origin: "http://evil.example:16860",
+    hostHeader: "192.168.1.20:16860",
+    remoteAddress: "192.168.1.30",
+    providedToken: "explicit-test-token",
+  });
+  assert.equal(decision.originAllowed, false);
+  assert.equal(decision.authorized, false);
+});

package/admin-panel/server/storage.mjs

@@ -0,0 +1,49 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export function projectPathIdentity(projectPath, platform = process.platform) {
+  const raw = String(projectPath ?? "").trim();
+  if (!raw) return "";
+  const resolved = path.resolve(raw);
+  return platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+export function atomicWriteTextFile(filePath, content, options = {}) {
+  const fsImpl = options.fsImpl ?? fs;
+  const directory = path.dirname(filePath);
+  const tempPath = path.join(
+    directory,
+    `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`,
+  );
+  let fd = null;
+  fsImpl.mkdirSync(directory, { recursive: true });
+  try {
+    fd = fsImpl.openSync(tempPath, "wx", 0o600);
+    fsImpl.writeFileSync(fd, content, "utf8");
+    fsImpl.fsyncSync(fd);
+    fsImpl.closeSync(fd);
+    fd = null;
+    fsImpl.renameSync(tempPath, filePath);
+    try {
+      const directoryFd = fsImpl.openSync(directory, "r");
+      try {
+        fsImpl.fsyncSync(directoryFd);
+      } finally {
+        fsImpl.closeSync(directoryFd);
+      }
+    } catch {
+      // Directory fsync is not available on every platform/filesystem.
+    }
+  } catch (err) {
+    if (fd != null) {
+      try {
+        fsImpl.closeSync(fd);
+      } catch {}
+    }
+    try {
+      fsImpl.rmSync(tempPath, { force: true });
+    } catch {}
+    throw err;
+  }
+}

package/admin-panel/server/storage.test.mjs

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { atomicWriteTextFile, projectPathIdentity } from "./storage.mjs";
+
+test("project path identity is case-sensitive except on Windows", () => {
+  assert.equal(projectPathIdentity("", "linux"), "");
+  assert.notEqual(projectPathIdentity("/tmp/VectorMind", "linux"), projectPathIdentity("/tmp/vectormind", "linux"));
+  assert.equal(projectPathIdentity("/tmp/VectorMind", "win32"), projectPathIdentity("/tmp/vectormind", "win32"));
+});
+
+test("atomic writes replace the index and preserve the prior file when rename fails", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "vectormind-admin-storage-"));
+  const indexFile = path.join(root, "projects.json");
+  try {
+    fs.writeFileSync(indexFile, "old\n", "utf8");
+    atomicWriteTextFile(indexFile, "new\n");
+    assert.equal(fs.readFileSync(indexFile, "utf8"), "new\n");
+
+    const failingFs = Object.create(fs);
+    failingFs.renameSync = () => {
+      throw new Error("simulated interrupted replace");
+    };
+    assert.throws(
+      () => atomicWriteTextFile(indexFile, "truncated\n", { fsImpl: failingFs }),
+      /simulated interrupted replace/,
+    );
+    assert.equal(fs.readFileSync(indexFile, "utf8"), "new\n");
+    assert.deepEqual(fs.readdirSync(root).filter((name) => name.endsWith(".tmp")), []);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/dist/checkpoint-snapshot.d.ts

@@ -0,0 +1,56 @@
+import type Database from "better-sqlite3";
+import type { ChangeLogRow, MemoryItemRow, PendingChangeRow } from "./types.js";
+import { toMemoryItemPreview } from "./memory-recall.js";
+export declare const CHECKPOINT_SNAPSHOT_VERSION = 2;
+export declare const CHECKPOINT_SNAPSHOT_MAX_CHARS = 24000;
+export declare const CHECKPOINT_METADATA_MAX_CHARS = 1200;
+export declare const CHECKPOINT_DECISION_LIMIT = 10;
+export declare const CHECKPOINT_RECENT_CHANGE_LIMIT = 10;
+export declare const CHECKPOINT_CHANGE_FILES_LIMIT = 20;
+export declare const CHECKPOINT_MEMORY_KINDS: readonly ["requirement", "change_intent", "note", "decision", "memory_compaction", "project_summary", "convention", "fix_pattern"];
+export declare const LEGACY_CHECKPOINT_MEMORY_KINDS: readonly ["requirement", "change_intent", "note", "decision", "memory_compaction", "project_summary", "convention"];
+type JsonRecord = Record<string, unknown>;
+export type CheckpointCollectionState = {
+    total: number;
+    returned: number;
+    truncated: boolean;
+    window_truncated?: boolean;
+    total_is_lower_bound?: boolean;
+};
+export type CheckpointSnapshotBasis = {
+    snapshot_version: number;
+    recent_limit: number;
+    decision_limit: number;
+    recent_change_limit: number;
+    pending_limit: number;
+    included_kinds: string[];
+};
+export declare function boundedMetadataJson(raw: string | null | undefined, options?: {
+    maxChars?: number;
+    omitKeys?: readonly string[];
+}): string | null;
+export declare function toCheckpointSnapshotMemoryPreview(row: MemoryItemRow): JsonRecord;
+export declare function toCheckpointRecordPreview(row: MemoryItemRow, includeContent: boolean, previewChars: number, contentMaxChars: number): ReturnType<typeof toMemoryItemPreview>;
+export declare function toCheckpointChangePreview(change: ChangeLogRow): JsonRecord;
+export declare function checkpointPendingRows(rows: PendingChangeRow[]): JsonRecord[];
+export declare function checkpointSnapshotBasis(recentLimit: number, pendingLimit: number): CheckpointSnapshotBasis;
+export declare function getVisibleCheckpointMemory(db: Database.Database, limit: number, excludeIds?: readonly number[], includedKinds?: readonly string[]): {
+    rows: MemoryItemRow[];
+    truncated: boolean;
+};
+export declare function getVisibleCheckpointDecisions(db: Database.Database, limit: number): {
+    rows: MemoryItemRow[];
+    truncated: boolean;
+};
+export declare function readCheckpointBasis(value: unknown, fallback: CheckpointSnapshotBasis): CheckpointSnapshotBasis;
+export declare function isCheckpointSnapshot(value: unknown): value is JsonRecord;
+export declare function normalizeCheckpointSnapshot(raw: JsonRecord, options?: {
+    maxChars?: number;
+    fallbackBasis?: CheckpointSnapshotBasis;
+}): JsonRecord;
+export declare function checkpointSnapshotFromMetadata(metadataJson: string | null | undefined, fallbackBasis: CheckpointSnapshotBasis): {
+    valid: boolean;
+    snapshot: JsonRecord;
+    metadata: JsonRecord;
+};
+export {};