sage-mem 1.6.2 → 1.6.3

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `1.6.2`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `1.6.3`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.
@@ -460,6 +460,8 @@ sage-mem does three things only, all of them on your own machine:
 
 Your memories are the files in that directory, openable at any time for confirmation — which is also why file-based was chosen.
 
+**Trust boundary for the memory directory.** Anyone who can write the memory directory can change what gets injected into the model — that is **inside** the trust model, not a vulnerability in the plugin. The read path rejects symlinks, reserved-name aliases and files over 512 KB at check time, and re-verifies file identity when reading (a file swapped in after the check is refused instead of injected); it cannot defend against a writer who is already allowed to modify your memories. Keep the directory's permissions to your own account.
+
 ## Compatibility
 
 sage-mem is a pure DSH plugin and declares its host requirement through **`engines.dsh`** in `package.json`: `>=0.1.2-rc.1` — **a one-sided open interval with no upper bound**, so no future DSH version will be blocked by this declaration. `engines.node` requires `>= 18`.
@@ -524,6 +526,7 @@ npm test          # all assertions (including the three guards)
 ```
 
 - The assertion scripts depend only on `node:` built-in modules and **introduce no test framework**; each script hand-writes `ok()` and ends with a summary line.
+- This repository uses **npm** for install / test / CI. No `pnpm-lock.yaml` is kept: a stale one could not be frozen-installed from a fresh clone (its workspace file was untracked), so it was removed rather than left to mislead.
 - **Three guards** watch over "whether the tests themselves hold up": `suite-registry-test.mjs` (is there a suite that was written but never runs), `contract-binding-test.mjs` (is there a commitment that was made but never verified), `doc-consistency-test.mjs` (do the two documents characterize things identically line by line).
 - CI runs twice on `ubuntu-latest` (the second time with `TZ=UTC`) — a case-sensitive volume catches defects that are invisible on Windows.
 - When you change **user-visible behaviour**, please also update the corresponding line in the [contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md) and the CHANGELOG; a commitment you cannot write an assertion for can only be marked "best-effort".

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`1.6.2`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`1.6.3`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -462,6 +462,8 @@ sage-mem 只做三件事，全都在你本机：
 
 记忆就是那个目录里的文件，随时可以打开确认 —— 这也是选文件式的原因。
 
+**记忆目录的信任边界**：能写记忆目录的人就能改变注入给模型的内容 —— 这属于**信任模型内部**，不是插件的漏洞。读路径在检查时会拒绝符号链接、保留名别名与超过 512 KB 的文件，读取时还会复核文件身份（检查之后被换掉的文件会被拒绝，而不是照读）；但它防不住一个已经被允许修改你记忆的人。把目录权限收到你自己的账号。
+
 ## 兼容性
 
 sage-mem 是纯 DSH 插件，用 `package.json` 的 **`engines.dsh`** 声明宿主要求：`>=0.1.2-rc.1` —— **单边开区间、不设上界**，所以任何未来的 DSH 版本都不会被这道声明挡住。`engines.node` 要求 `>= 18`。
@@ -526,6 +528,7 @@ npm test          # 全部断言（含三条守卫）
 ```
 
 - 断言脚本只依赖 `node:` 内置模块，**不引测试框架**，各脚本手写 `ok()` 并以汇总行收尾。
+- 本仓库统一用 **npm** 安装 / 测试 / CI。不留 `pnpm-lock.yaml`：旧的锁在 fresh clone 里 `--frozen-lockfile` 装不动（它依赖的 workspace 文件未入库），留着只会误导。
 - **三条守卫**盯的是「测试本身站不站得住」：`suite-registry-test.mjs`（有没有写了不跑的套件）、
   `contract-binding-test.mjs`（有没有说了不验的承诺）、`doc-consistency-test.mjs`（两份文档的定性是否逐行一致）。
 - CI 在 `ubuntu-latest` 上跑两遍（第二遍 `TZ=UTC`）—— 区分大小写的卷能逮到 Windows 上看不见的缺陷。

package/lib/index.js

@@ -22,14 +22,14 @@ import { INDEX_FILE_KEY, SESSION_LOG_KEY, isPlainMdName } from './shared/md-name
 import { parseAliases, parseBaseline, parseBaselinePriority, parseFrontmatter, parseTags } from './memory/frontmatter.js'
 import { ageDays, bigrams, score, selectBaseline, selectRelevant } from './memory/retrieval.js'
 import { isReserved, nameKey, safeName } from './memory/naming.js'
-import { MEMORY_ARCHIVE_DIR, addArchiveMeta, extractTitle, inspectDir, inspectMemoryEntry, readArchivedMeta, scanArchived, scanMemoryFiles, scanStars, shadowsReserved } from './memory/scan.js'
+import { MEMORY_ARCHIVE_DIR, addArchiveMeta, extractTitle, inspectDir, inspectMemoryEntry, readArchivedMeta, readVerified, scanArchived, scanMemoryFiles, scanStars, shadowsReserved } from './memory/scan.js'
 import { archiveMemory, deleteArchivedMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
 import { readLockSet, setLocked as setLockedImpl } from './memory/lock.js'
 import { openMemoryFolder } from './memory/open-folder.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
-import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { checkUpdate as checkUpdateImpl } from './update.js'
 import { autodreamConfigSnapshot, clampInt, MAX_RAW_BYTES, pendingLimits, rawName, readReservedFile, readSettingsFile, RESERVED_FILE, SETTINGS_FILE } from './settings.js'
@@ -126,7 +126,7 @@ export class MemoryGateway extends TypertRemoteService {
     }
     const gate = await inspectMemoryEntry(full)
     if (!gate.ok) throw new Error(`sage-mem: refusing to read ${safe}: ${gate.error}`)
-    const content = await readFile(full, 'utf8')
+    const content = await readVerified(full, gate, 'utf8')
     return { name: safe, content }
   }
 
@@ -284,7 +284,7 @@ export class MemoryGateway extends TypertRemoteService {
       if (gate.code === 'missing') throw new Error(`sage-mem: archived file not found: ${safe}`)
       throw new Error(`sage-mem: refusing to read archived ${safe}: ${gate.error}`)
     }
-    const content = await readFile(full, 'utf8')
+    const content = await readVerified(full, gate, 'utf8')
     return { name: safe, content }
   }
 
@@ -327,7 +327,7 @@ export class MemoryGateway extends TypertRemoteService {
     const given = readArchivedMeta(content)
     let toWrite = content
     if (!given.archivedAt && !given.archivedReason) {
-      const onDisk = readArchivedMeta(await readFile(full, 'utf8'))
+      const onDisk = readArchivedMeta(await readVerified(full, gate, 'utf8'))
       if (onDisk.archivedAt || onDisk.archivedReason) {
         toWrite = addArchiveMeta(content, onDisk.archivedReason, onDisk.archivedAt)
       }
@@ -518,7 +518,7 @@ export class MemoryGateway extends TypertRemoteService {
     if (!gate.ok) throw new Error(`sage-mem: refusing to read ${safe}: ${gate.error}`)
     // 读不到就抛（与 readFile 一致）：静默返回空串会让面板显示一份「空的索引」，
     // 用户一存就把真索引顶掉。
-    const content = await readFile(full, 'utf8')
+    const content = await readVerified(full, gate, 'utf8')
     return { name: safe, content }
   }
 
@@ -620,7 +620,15 @@ export class StarmapGateway extends TypertRemoteService {
     // MEMORY.md 与 session-log.md，且大小写不敏感。
     const safe = safeName(name)
     if (!safe) throw new Error('sage-starmap: invalid file name')
-    const content = await readFile(join(MEMORY_DIR, safe), 'utf8')
+    const full = join(MEMORY_DIR, safe)
+    // 2026-10-23 审查 R19：面板读原先只过 safeName，与注入链 / 工具读不是同一套闸门。
+    // 面板读不进模型上下文，但「同一个名字在不同入口有不同含义」本身就是缺陷面 —— 收口。
+    if (await shadowsReserved(full)) {
+      throw new Error(`sage-starmap: refusing to read ${safe}: 这是某个保留名（索引 / 流水）的另一个名字`)
+    }
+    const gate = await inspectMemoryEntry(full)
+    if (!gate.ok) throw new Error(`sage-starmap: refusing to read ${safe}: ${gate.error}`)
+    const content = await readVerified(full, gate, 'utf8')
     return { name: safe, content }
   }
 }

package/lib/memory/reader.js

@@ -16,10 +16,9 @@
  */
 
 import { MEMORY_DIR } from './config.js'
-import { inspectMemoryEntry, shadowsReserved } from './scan.js'
+import { inspectMemoryEntry, readVerified, shadowsReserved } from './scan.js'
 import { safeName } from './naming.js'
 import { revisionOf } from './chunks.js'
-import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 /** 一屏默认给多少字节。4 KB ≈ 一屏可读正文，比一次注入的 60 KB 会话预算小一个量级。 */
@@ -231,7 +230,9 @@ export async function readSlice(req = {}) {
       return { ok: false, code: 'denied', error: `拒绝读取 ${norm.name}：${gate.error}` }
     }
 
-    const content = await readFile(full, 'utf8')
+    // 读的是闸门检查过的同一个句柄（SEC-01）：路径在检查与读取之间被换掉会返回 changed，
+    // 而不是把没检查过的内容当记忆交出去。
+    const content = await readVerified(full, gate, 'utf8')
     const revision = revisionOf(content)
     /**
      * 带了 revision 就一定校验，且**不返回任何内容 / 行号**：过期行号比「读不到」危险得多 ——
@@ -284,6 +285,7 @@ export async function readSlice(req = {}) {
   } catch (err) {
     // 扫到读之间被删是正常状态（不是故障）；其余一律出声，别让「读不到」变成无声空内容。
     if (err?.code === 'ENOENT') return { ok: false, code: 'not_found', error: '这份记忆在读取过程中被删掉了' }
+    if (err?.code === 'changed') return { ok: false, code: 'io_error', error: err.message }
     return { ok: false, code: 'io_error', error: `读取失败（${err?.code ?? err?.message ?? err}）` }
   }
 }

package/lib/memory/scan.js

@@ -15,7 +15,7 @@ import { parseBaseline, parseFrontmatter } from './frontmatter.js'
 import { isMemoryEntry, isReserved } from './naming.js'
 import { warnLog } from './util.js'
 import { createDirWatcher } from './watch.js'
-import { lstat, readFile, readdir } from 'node:fs/promises'
+import { lstat, open, readFile, readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 
 /** 归档区目录名。与 autodream 工具里的 ARCHIVE_DIR 同名同义（同一个目录）。 */
@@ -167,6 +167,56 @@ export function identityOf(info) {
   return info && info.ino ? `${info.dev}:${info.ino}` : null
 }
 
+/**
+ * 读一份**已经过 `inspectMemoryEntry` 闸门**的文件，并确认「读到的就是闸门检查过的那一份」。
+ *
+ * 为什么需要它（2026-10-23 外部审查 SEC-01）：`inspectMemoryEntry` 用的是 `lstat(路径)`，
+ * 而调用方随后用 `readFile(路径)` —— 两次**按路径**操作之间，另一个进程可以把路径换成
+ * 符号链接 / 另一个文件。窗口已被确定性复现：闸门看到 57 B 的正常文件，换入 5 MB 文件后
+ * `readFile` 实际读进 5,242,896 B，**512 KB 单文件上限被绕过**。
+ *
+ * 修法不是「再 stat 一次路径」（那只是把窗口挪小），而是：
+ *   1. `open(路径)` 拿到**文件句柄**；
+ *   2. 对**同一个句柄** `fstat`，用 `dev:ino` 与闸门给出的身份比对，并复核大小；
+ *   3. 只从这个句柄读内容。
+ * 这样即使路径在 open 之后被换掉，读的仍是 open 时的那个对象；若在 open 之前被换掉，
+ * 身份/大小对不上 → 拒绝，绝不把「没检查过的内容」交出去。
+ *
+ * 平台差异：Node 没有跨平台的 `O_NOFOLLOW`（Windows 上符号链接还要管理员权限），
+ * 所以这里用「身份比对」而不是「不跟随链接」；`inspectMemoryEntry` 的 `lstat` 仍负责
+ * 在 open 之前识别链接。两者合起来覆盖「链接被换成普通文件」「普通文件被换成链接/别的文件」
+ * 两个方向。拿不到 inode 的平台（`gate.id === null`）退化为只比大小。
+ *
+ * @param {string} full — 绝对路径
+ * @param {{id?: string|null, size?: number}} gate — `inspectMemoryEntry` 的成功返回值
+ * @param {string|false} [encoding] — `'utf8'` 返回字符串；`false` 返回 Buffer
+ * @returns {Promise<string|Buffer>}
+ */
+export async function readVerified(full, gate, encoding = 'utf8') {
+  const handle = await open(full, 'r')
+  try {
+    const info = await handle.stat()
+    if (!info.isFile()) {
+      const err = new Error('文件在检查与读取之间变成了非普通文件')
+      err.code = 'changed'
+      throw err
+    }
+    if (gate?.id && identityOf(info) !== gate.id) {
+      const err = new Error('文件在检查与读取之间被替换（身份不一致）')
+      err.code = 'changed'
+      throw err
+    }
+    if (gate && Number.isFinite(gate.size) && info.size !== gate.size) {
+      const err = new Error(`文件在检查与读取之间变过（${gate.size} → ${info.size} 字节）`)
+      err.code = 'changed'
+      throw err
+    }
+    return encoding === false ? await handle.readFile() : await handle.readFile({ encoding })
+  } finally {
+    await handle.close().catch(() => {})
+  }
+}
+
 /**
  * 保留名在磁盘上的**文件身份**集合（`dev:ino`）。
  *
@@ -394,7 +444,7 @@ async function fullScanMemoryDir(ctx, sessionId, dir) {
         return null
       }
       try {
-        const content = await readFile(full, 'utf8')
+        const content = await readVerified(full, gate, 'utf8')
         const meta = parseFrontmatter(content)
         return {
           file: name,
@@ -455,7 +505,7 @@ async function readStarDir(dir, ctx, opts = {}) {
       return null
     }
     try {
-      const content = await readFile(full, 'utf8')
+      const content = await readVerified(full, gate, 'utf8')
       return { name, content, bytes: gate.size, mtimeMs: gate.mtimeMs }
     } catch (err) {
       if (err?.code !== 'ENOENT') warnLog(ctx, `cannot read ${full}: ${err?.message ?? err}`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "type": "module",
   "main": "lib/index.js",
   "exports": {