Skip to content

docs: declare shared-state-dir multi-instance security boundary (#1724) - #1745

Merged
ranxianglei merged 2 commits into
masterfrom
2026-09-30_shared-state-security-boundary
Sep 30, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-09-30_shared-state-security-boundary

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Part of #1724 (issue direction #5 — security declaration). Docs-only; no code change.

Documents the actual security posture of the shared state dir in TECHNICAL-NOTES (en + zh-CN), which previously only carried the lane-aware #394 coexistence warning without stating what that implies for the data plane:

This is issue direction #5 verbatim in intent: "在文档中写明共享 state dir 的安全边界当前仅由 loopback gate + 文件系统权限承担,多用户宿主必须分区". It records the boundary as-is; it changes no behavior and adds no config surface.

Pre-flight

typecheck ✓ · build ✓ · full test suite unaffected by a docs-only diff (CI still runs it on the PR).

Record in TECHNICAL-NOTES (en/zh-CN) that all instances share one state dir whose control plane is lane-aware but whose data plane is not partitioned — no per-session owner, no per-lane isolation. State the two consequences (cross-instance session visibility in every instance's web UI; the restart drain race and its #1737/#1742/#405 mitigations) and the current security posture: only the admin loopback gate + filesystem permissions, i.e. no per-session authorization. Sufficient single-user, insufficient multi-user (must partition). Issue direction #5. Docs-only.
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-30_shared-state-security-boundary (ee77f0f)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1695-pr.1745.4d5068e

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1745.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Reviewing PR #1745 now. Verified the core claims against master: shared unpartitioned per-host storage ✓, Web UI re-scans the whole disk store (buildSessionList → loadDiskSessions) ✓, admin loopback gate ✓ (src/server.ts:1072), #405 guard present ✓ (src/persist.ts:580). Found one factual error (directory attribution — sessions live in the XDG data dir, not the state dir) which I'm fixing directly on the branch, plus one merge-order note. Full conclusion shortly.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Reviewed the PR against live master — direction is right, all factual claims check out, but the diff had three accuracy problems which I fixed directly on the branch (commit ee77f0ff, pushed).

Verified against master (all hold):

Fixes made in ee77f0ff (docs-only, same two files):

  1. Dir attribution was wrong. The section said everything (sessions, CCR content-store, prefix-affinity, registry) lives in ~/.local/state/billion-context/. Per src/paths.ts, session records + CCR store + prefix-affinity live in the XDG data dir ~/.local/share/billion-context/; the state dir holds the log + instance registry. As written, the "partition the state dir" advice would have left the session data unprotected — it now says partition the per-host storage (both dirs).
  2. "Mitigations shipped in 多实例共享 sessions 目录的重启竞态:丢失更新、前缀缓存击穿与会话跨实例暴露(#394 扩展) #1724" was premature — fix: multi-instance shared-state hardening — activePack round-trip + affinity clobber guard (#1724) #1737 and fix: flush durable state before spawning self-restart replacement (#1724) #1742 are still open. Reworded to "The 多实例共享 sessions 目录的重启竞态:丢失更新、前缀缓存击穿与会话跨实例暴露(#394 扩展) #1724 mitigations:" with explicit per-item PR citations (fix: multi-instance shared-state hardening — activePack round-trip + affinity clobber guard (#1724) #1737 union-on-write guard, fix: flush durable state before spawning self-restart replacement (#1724) #1742 flush-before-spawn), so the text stays true regardless of merge order.
  3. Mis-citation: the restart-ordering fix was attributed to feat(update): surface stale-install state to the human + opt-in self-restart (#806 §3) #811, which is the stale-install web badge. The flush-before-spawn fix is fix: flush durable state before spawning self-restart replacement (#1724) #1742 — corrected.

Regression surface: none — docs-only diff, no code path touched; existing lane-aware #394 warning text untouched. CI runs the full suite on the PR regardless.

Merge order: with fix #2 the wording no longer asserts #1737/#1742 have landed, so this PR can merge independently of them (no longer needs to wait behind either).

Status: CI running on head ee77f0ff (all jobs in progress; PR shows blocked purely on pending required checks, no merge conflict). Verdict: mergeable once CI is green.

中文摘要:审查了共享 state 目录安全边界文档 PR,核实了全部事实性声明(存储无会话属主、Web UI 全量重扫、回环门禁、#405 守卫均在 master 上成立),并直接在分支上修正了三处错误——目录归属写错(sessions 实际在 XDG data 目录而非 state 目录)、"已落地缓解"措辞超前(#1737/#1742 尚未合并,已改为带 PR 编号的中性表述)、#811 误引(自重启顺序修复实为 #1742);纯文档改动无行为回归,CI 绿后可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

CI update: all 12 checks green on head ee77f0ff (typecheck/test/build + all e2e lanes), PR mergeable_state: clean. Ready for human merge whenever you are — merge stays human-only per repo rules.

@ranxianglei
ranxianglei merged commit 38d3b33 into master Sep 30, 2026
12 checks passed
ranxianglei pushed a commit that referenced this pull request Sep 30, 2026
Rebased onto master (post #1713 NO_RANGE manifest locals, post #1745):
goldens now reflect zero-injection manifests — every conversation_id
param block removed (routing param, search_context cross-session param,
one tool left with empty properties). Regenerated via
scripts/update-wire-contract-goldens.ts; manifest arrays keep the
NO_RANGE-aware locals instead of the pre-rebase plain BILI_ACP_TOOLS_*
arrays.
ranxianglei pushed a commit that referenced this pull request Sep 30, 2026
Rebased onto master (post #1713 NO_RANGE manifest locals, post #1745):
goldens now reflect zero-injection manifests — every conversation_id
param block removed (routing param, search_context cross-session param,
one tool left with empty properties). Regenerated via
scripts/update-wire-contract-goldens.ts; manifest arrays keep the
NO_RANGE-aware locals instead of the pre-rebase plain BILI_ACP_TOOLS_*
arrays.
@github-actions github-actions Bot mentioned this pull request Sep 30, 2026
@ranxianglei
ranxianglei deleted the 2026-09-30_shared-state-security-boundary branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant