aizuchi 0.1.0

package/dist/server/lib/files.js

@@ -0,0 +1,208 @@
+import { promises as fs } from 'node:fs';
+import matter from 'gray-matter';
+import path from 'node:path';
+import { resolveConfigPath } from './config-paths.js';
+import { hasSafeConfigExt, isSecretPath, PathValidationError, readFileNoFollow, sanitizeConfigDirEntries, writeFileAtomic, } from './fs-safe.js';
+/**
+ * AI 設定ファイル管理 (F-4) のファイル I/O。
+ * 全ての読み書きは resolveConfigPath で aiConfigPaths 許可リストを通す (N-2)。
+ * 秘匿ファイル (settings.local.json 等) の内容はサーバーログに出さない (N-8)。
+ */
+/**
+ * 許可リスト内ファイルの相対パスを realpath 済み root 基準で算出する (R14-7 / docs.ts:79-81 と同型)。
+ * absPath は resolveConfigPath で realpath ベースの canonical のため、非正規化 projectRoot で相対化すると
+ * root 側 symlink (macOS /var → /private/var) で `../` 連鎖になり絶対パスを露出しうる。realpath 済み root を
+ * 基準にしてレスポンスに絶対パス / 余計な `../` が混ざらないようにする (N-8)。
+ */
+async function relPathFromRealRoot(projectRoot, absPath) {
+    const root = path.resolve(projectRoot);
+    const rootReal = await fs.realpath(root).catch(() => root);
+    return path.relative(rootReal, absPath);
+}
+/** 許可リスト内ファイルを読む (F-4-1 / F-4-6)。許可外は PathValidationError */
+export async function readConfigFile(projectRoot, config, relPath) {
+    const { absPath } = await resolveConfigPath(projectRoot, config, relPath);
+    const stat = await fs.stat(absPath);
+    // R14-4 再修正 (#5): docs だけでなく config 読取も O_NOFOLLOW で TOCTOU を塞ぐ (resolveConfigPath の
+    // lstat symlink 拒否と読取の間で対象が symlink へ差し替わる窓を閉じる)。config はより秘匿性が高い。
+    const content = await readFileNoFollow(absPath);
+    return { path: await relPathFromRealRoot(projectRoot, absPath), content, mtimeMs: stat.mtimeMs };
+}
+/**
+ * 許可リスト内ファイルを保存する (F-4-1/F-4-3/F-4-6)。
+ * - 既存があれば `.bak` を作成 (上書き前のバックアップ)
+ * - mode を保全 (秘匿ファイルの権限が緩まないように、N-8 / Round 1 #7)
+ * mtime 不一致は呼び出し側で 409 にする (この関数は検証済み前提で書く)。
+ */
+export async function saveConfigFile(projectRoot, config, relPath, content) {
+    const { absPath } = await resolveConfigPath(projectRoot, config, relPath);
+    // 既存があれば .bak を作る (内容をそのままコピー)。新規作成時はバックアップ不要。
+    // .bak はコピー元 (秘匿ファイル) の mode を継がせる (R8-2: settings.local.json 0o600 の .bak が
+    // 0o644 で漏れないように)。preserveMode は .bak の既存 mode を見るため未存在だと効かない → mode を明示
+    try {
+        const prevStat = await fs.stat(absPath);
+        // R14-4 再修正 (#5): prev 読取も O_NOFOLLOW に統一 (config 読取経路の TOCTOU を docs と対称に塞ぐ)
+        const prev = await readFileNoFollow(absPath);
+        await writeFileAtomic(`${absPath}.bak`, prev, { mode: prevStat.mode & 0o777 });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await writeFileAtomic(absPath, content, { preserveMode: true });
+    const stat = await fs.stat(absPath);
+    return { path: await relPathFromRealRoot(projectRoot, absPath), content, mtimeMs: stat.mtimeMs };
+}
+/** ファイルの現在 mtime を返す (PUT の競合検知用)。存在しなければ null */
+export async function fileMtime(projectRoot, config, relPath) {
+    const { absPath } = await resolveConfigPath(projectRoot, config, relPath);
+    try {
+        return (await fs.stat(absPath)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** browseDirs 配下のファイルツリーを構築する (F-4-2)。各 browseDir をルートにした木の配列 */
+export async function buildFileTree(projectRoot, config) {
+    const root = path.resolve(projectRoot);
+    const trees = [];
+    // R14-1: browseDir が `.` 等で root 自身を指すと木全体が root 配下を列挙し秘匿ファイルが見える。
+    // sanitizeConfigDirEntries で root の真の配下のエントリだけに正規化する (root 自身 / 外を除外)。
+    for (const absDir of sanitizeConfigDirEntries(root, config.aiConfigPaths.browseDirs)) {
+        // R14-1 再修正 (#3): browseDir 自体が .git 等の秘匿パスを指す場合は丸ごと列挙しない (発見面に deny を適用)
+        if (isSecretPath(absDir))
+            continue;
+        const node = await buildTreeNode(root, absDir);
+        if (node)
+            trees.push(node);
+    }
+    return trees;
+}
+async function buildTreeNode(root, absPath) {
+    // R14-1 再修正 (#3): 走査中の .git 配下 / 秘匿 basename は列挙しない (read API の deny と発見面を揃える)
+    if (isSecretPath(absPath))
+        return null;
+    let stat;
+    try {
+        stat = await fs.lstat(absPath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink())
+        return null; // symlink は辿らない (N-2)
+    const rel = path.relative(root, absPath);
+    const name = path.basename(absPath);
+    if (stat.isDirectory()) {
+        let entries = [];
+        try {
+            entries = (await fs.readdir(absPath)).sort();
+        }
+        catch {
+            entries = [];
+        }
+        const children = [];
+        for (const entry of entries) {
+            const child = await buildTreeNode(root, path.join(absPath, entry));
+            if (child)
+                children.push(child);
+        }
+        return { path: rel, name, type: 'dir', children };
+    }
+    if (stat.isFile()) {
+        // R17-F (M4/M5): read できる拡張子 (allow-list) のファイルだけツリーに出す。read API (resolveConfigPath)
+        // は allow-list 外を 403 にするため、出しても開けないファイルを列挙するのは名前露出のみで益がない。
+        // tree と readability を整合させ、allow 拡張子以外 (例 .env / .sh) の名前露出を削減する。
+        // ディレクトリは従来通り表示する (中の .md 等に辿り着くため)。
+        if (!hasSafeConfigExt(name))
+            return null;
+        return { path: rel, name, type: 'file' };
+    }
+    return null;
+}
+/**
+ * ディレクトリを手動再帰し .md ファイルの絶対パスを集める。
+ * symlink ディレクトリ・symlink ファイルは辿らない (R8-1: fs.readdir(recursive) は中間 symlink を
+ * 辿ってしまい N-2 境界を抜けるため、buildFileTree と同じ手動再帰で symlink を skip する)。
+ *
+ * R14-1 再々修正 (FIX-7・#2): **先頭 absDir 自体にも lstat を掛けて symlink を拒否する**。
+ * sanitizeConfigDirEntries / isSecretPath は lexical 判定のため、root 内に作った symlink browseDir
+ * (`evilbrowse` → root 外 or `.git`) を見逃し、readdir が辿って frontmatter を漏洩していた
+ * (buildTreeNode / buildDocsNode は top-level lstat で symlink を弾くのに catalog だけ非対称だった)。
+ */
+async function collectMarkdownFilesNoSymlink(absDir) {
+    // FIX-7 (#2): 先頭ディレクトリ自体が symlink なら辿らない (top-level の N-2 containment 破りを塞ぐ)。
+    // 再帰下層の dir は per-entry lstat で symlink でないことが保証済みのため、実質 top-level 呼出で効く。
+    let topLst;
+    try {
+        topLst = await fs.lstat(absDir);
+    }
+    catch {
+        return [];
+    }
+    if (topLst.isSymbolicLink())
+        return [];
+    let entries = [];
+    try {
+        entries = await fs.readdir(absDir);
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries.sort()) {
+        const abs = path.join(absDir, entry);
+        // R14-1 再修正 (#3): .git 配下 / 秘匿 basename は catalog 読取対象から除外 (発見面に deny を適用)
+        if (isSecretPath(abs))
+            continue;
+        let lst;
+        try {
+            lst = await fs.lstat(abs);
+        }
+        catch {
+            continue;
+        }
+        if (lst.isSymbolicLink())
+            continue; // symlink (dir/file 問わず) は辿らない
+        if (lst.isDirectory()) {
+            results.push(...(await collectMarkdownFilesNoSymlink(abs)));
+        }
+        else if (lst.isFile() && abs.endsWith('.md')) {
+            results.push(abs);
+        }
+    }
+    return results;
+}
+/**
+ * browseDirs 配下の skill / agent の frontmatter (name / description) を抽出してカタログ化する (F-4-4)。
+ * .md ファイルのみ対象。frontmatter が無い / パース不能ならそれぞれ null。
+ * symlink 中間ディレクトリ・symlink ファイルは辿らない (R8-1: プロジェクト外漏洩を防ぐ)。
+ */
+export async function buildCatalog(projectRoot, config) {
+    const root = path.resolve(projectRoot);
+    const items = [];
+    // R14-1: buildFileTree と同じく root 自身 / 外を指す browseDir を除外する
+    for (const absDir of sanitizeConfigDirEntries(root, config.aiConfigPaths.browseDirs)) {
+        // R14-1 再修正 (#3): browseDir 自体が .git 等の秘匿パスなら catalog 化しない
+        if (isSecretPath(absDir))
+            continue;
+        for (const abs of await collectMarkdownFilesNoSymlink(absDir)) {
+            try {
+                const raw = await fs.readFile(abs, 'utf8');
+                const data = matter(raw).data;
+                items.push({
+                    path: path.relative(root, abs),
+                    name: typeof data.name === 'string' ? data.name : null,
+                    description: typeof data.description === 'string' ? data.description : null,
+                });
+            }
+            catch {
+                // 読めない / パース不能はスキップ
+            }
+        }
+    }
+    items.sort((a, b) => a.path.localeCompare(b.path));
+    return items;
+}
+export { PathValidationError };

package/dist/server/lib/fs-safe.js

@@ -0,0 +1,428 @@
+import { constants as fsConstants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * 書込の安全装置 (N-2 / N-3):
+ * - assertWritablePath: ①パス正規化 → ②親ディレクトリの realpath 解決 (対象ファイルは
+ *   未存在のことがある) → ③許可ディレクトリの接頭辞検査。`../` も symlink 経由もここで拒否する
+ * - writeFileAtomic: 同一ディレクトリの一時ファイル → rename によるアトミック書込
+ */
+export class PathValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PathValidationError';
+    }
+}
+/** 排他書込 (exclusive) で書込先が既に存在したときに投げる (呼び出し側で再採番 retry する) */
+export class FileExistsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FileExistsError';
+    }
+}
+// パス区切り・制御文字・先頭ドットを含むファイル名を拒否する (ファイル名サニタイズ)
+const SAFE_BASENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * 解決済み絶対パスが root の「真の配下」かを判定する (root 自身は含めない)。
+ * config 由来の許可リスト (browseDirs / docsDirs / settingsFiles / rootFiles) の各エントリが
+ * `.` / 末尾スラッシュ等で root 自身を指すと、接頭辞検査が root 配下全件に一致してしまう
+ * (R14-1: PUT /api/files で任意上書き = RCE、GET /api/files で .env / settings.local.json 読取 = N-8 破り)。
+ * `files.ts:30` / `docs.ts:27` の既存ゲートは「root 自身は許可」だが、許可リストの「エントリ自身」は
+ * root より真に下でなければならないため、ここでは root 自身を弾く。
+ */
+export function isStrictlyInside(root, resolved) {
+    return resolved !== root && resolved.startsWith(root + path.sep);
+}
+/**
+ * 秘匿 deny-list は 2 層に分ける (R14-1 再修正・PM Round 14 残存脆弱性 #1〜#7)。
+ *
+ * - {@link isHardDeniedConfigPath}: **いかなる経路 (完全一致 exactFiles 含む) でも遮断する** 強い deny。
+ *   `.git/**` (case-insensitive) + 鍵 / 認証情報類 (`.env`/`.env.*` / `*.pem` / `*.key` / `*.p12` / `*.pfx` /
+ *   `id_rsa` / `id_dsa` / `id_ecdsa` / `id_ed25519` / `.npmrc` / `.netrc`)。
+ *   `settings.local.json` は **含めない** (設定ファイル管理の正規編集ユースケースのため)。
+ *   `.git/hooks/*` 書込は RCE、鍵類は N-8 漏洩に直結するため、悪意 config が settingsFiles/rootFiles に
+ *   列挙しても完全一致で素通りさせない。
+ * - {@link isSecretPath}: 上記の **superset** = `isHardDeniedConfigPath` + `settings.local.json`。
+ *   browse / tree / catalog / docs の「発見」面に適用し、settings.local.json を一覧・ツリーで晒さない。
+ */
+/**
+ * パス成分に秘匿ディレクトリ (case-insensitive) を含むか。
+ * macOS の case-insensitive FS で `.GIT` / `.SSH` 等の大文字回避も防ぐ。
+ * R17-B (#B-1): `.git` 単独判定を一般化し、認証情報・鍵を格納する標準ディレクトリ
+ * (`.ssh` / `.aws` / `.gnupg` / `.kube` / `.docker`) を basename 非依存で全遮断する。
+ * これにより `.ssh/known_hosts` / `.aws/credentials` / `.docker/config.json` / `.kube/config` を
+ * 個別 basename に頼らず遮断できる (`.git/hooks/*` 書込 = RCE、鍵類 = N-8 漏洩を全経路で防ぐ)。
+ * R17-E (#E-2): `.config` / `.composer` を追加 (allow 拡張子を持つ秘密 `.config/gh/hosts.yml` (.yml) /
+ * `.composer/auth.json` (.json) を dir 単位で遮断・allow-list と defense-in-depth で二重化)。
+ */
+const SECRET_DIR_SEGMENTS = new Set(['.git', '.ssh', '.aws', '.gnupg', '.kube', '.docker', '.config', '.composer']);
+function hasSecretDirComponent(resolved) {
+    return resolved.split(path.sep).some((seg) => SECRET_DIR_SEGMENTS.has(seg.toLowerCase()));
+}
+/**
+ * 強い deny の basename (settings.local.json を含まない・鍵 / 認証情報類のみ)。case-insensitive。
+ * FIX-8 (#3): SSH 鍵の他形式 (id_dsa / id_ecdsa) / 認証情報 (.netrc) / PKCS#12 鍵束 (*.p12 / *.pfx) を追加。
+ * R17-B (#B-2): 認証情報系 basename を網羅追加 (`.git-credentials` / `.gitconfig` (core.hooksPath 経由 RCE) /
+ * `.pgpass` / `.htpasswd` / `.dockercfg` / `.s3cfg` / `known_hosts` / `authorized_keys`) と
+ * 証明書・鍵束の拡張子 (crt|cer|der|keystore|jks|ovpn|asc|gpg|pgp|p7b|p8) を追加。
+ * **`.gitignore` / `.gitattributes` / `.gitkeep` は誤遮断しない** (`\.gitconfig` / `\.git-credentials` は
+ * 完全一致なので衝突しない。テスト F22 で ALLOW を pinning)。
+ */
+const HARD_DENY_BASENAME_RE = /^(\.env(\..*)?|.*\.(pem|key|p12|pfx|crt|cer|der|keystore|jks|ovpn|asc|gpg|pgp|p7b|p8)|id_rsa|id_dsa|id_ecdsa|id_ed25519|\.npmrc|\.netrc|\.git-credentials|\.gitconfig|\.pgpass|\.htpasswd|\.dockercfg|\.s3cfg|known_hosts|authorized_keys)$/i;
+/**
+ * いかなる経路 (完全一致 exactFiles 含む) でも遮断する強い deny (R14-1 再修正)。
+ * 秘匿 dir 成分 (`.git`/`.ssh`/`.aws`/`.gnupg`/`.kube`/`.docker`、case-insensitive) + 鍵 / 認証情報類。
+ * settings.local.json は含めない (正規編集を許す)。
+ */
+export function isHardDeniedConfigPath(resolved) {
+    if (hasSecretDirComponent(resolved))
+        return true; // .git/.ssh/.aws/... 配下を全経路で拒否 (RCE / N-8)
+    return HARD_DENY_BASENAME_RE.test(path.basename(resolved));
+}
+/**
+ * 「発見」面 (browse / tree / catalog / docs) に適用する deny-list (isHardDeniedConfigPath の superset)。
+ * 強い deny に settings.local.json を加える (一覧・ツリーで秘匿ファイルを晒さない)。
+ */
+export function isSecretPath(resolved) {
+    if (isHardDeniedConfigPath(resolved))
+        return true;
+    return /^settings\.local\.json$/i.test(path.basename(resolved));
+}
+/**
+ * F-4 設定ファイル管理で read / write を許可する拡張子の allow-list (R17-E: 主ゲート・#E-1)。
+ *
+ * deny-list は列挙のため収束しない (認証情報・鍵の新種が毎ラウンド出る whack-a-mole)。read/write/browse の
+ * **主ゲートを allow-list に切替える**。既定の F-4 対象 (settings.json/settings.local.json = .json、CLAUDE.md /
+ * skill / rule / agent = .md) は全通過する。許可拡張子に無い `kubeconfig` / `github_token` / `credentials` /
+ * `terraform.tfstate` / `.envrc` / `.pypirc` / `prod.env` / `.flaskenv` 等は一律ブロックされる。
+ * deny-list は defense-in-depth で残す (両方が独立に効く)。
+ */
+export const SAFE_CONFIG_EXT = new Set(['.json', '.jsonc', '.md', '.markdown', '.txt', '.toml', '.yaml', '.yml']);
+/** パスの拡張子が SAFE_CONFIG_EXT に含まれるか (case-insensitive)。allow-list の判定 (R17-E・#E-1) */
+export function hasSafeConfigExt(p) {
+    return SAFE_CONFIG_EXT.has(path.extname(p).toLowerCase());
+}
+/**
+ * config 由来のパスエントリ配列を root 配下に正規化・フィルタする (R14-1 / R14-3)。
+ * 各エントリを `path.resolve(root, entry)` し、root の真の配下 (isStrictlyInside) のものだけを残す。
+ * `.` / `..` / 絶対パスで root 自身 / root 外を許可リストに載せる攻撃は黙って除外する
+ * (config は trusted だが、悪意ある config を含むリポを開いた場合の被害を局所化する)。
+ *
+ * 秘匿 deny-list は **ここでは適用しない** (root 封じ込めのみ責務)。deny は解決後パスに対し
+ * 呼び出し側が 2 層で適用する (R14-1 再修正):
+ * - resolveConfigPath: 完全一致 / 接頭辞一致を問わず {@link isHardDeniedConfigPath} (.git/鍵類) を遮断。
+ *   接頭辞一致 (browseDirs) のみ追加で {@link isSecretPath} (= settings.local.json も) を遮断。
+ *   完全一致 (settingsFiles) の settings.local.json は正規編集ユースケースのため許す。
+ * - buildFileTree / buildCatalog / docs: 発見面なので isSecretPath を走査時に適用。
+ */
+export function sanitizeConfigDirEntries(root, entries) {
+    const result = [];
+    for (const entry of entries) {
+        const resolved = path.resolve(root, entry);
+        if (!isStrictlyInside(root, resolved))
+            continue; // root 自身 / root 外を除外
+        result.push(resolved);
+    }
+    return result;
+}
+/**
+ * 書込先パスを検証し、正規化済みの絶対パスを返す。
+ * allowedDirs は書込を許可するディレクトリの一覧 (Phase 1 は `.kanban/` のみ)。
+ */
+export async function assertWritablePath(targetPath, allowedDirs) {
+    const resolved = path.resolve(targetPath);
+    const base = path.basename(resolved);
+    if (!SAFE_BASENAME_RE.test(base)) {
+        throw new PathValidationError(`不正なファイル名のため書込を拒否: ${JSON.stringify(base)}`);
+    }
+    let parentReal;
+    try {
+        parentReal = await fs.realpath(path.dirname(resolved));
+    }
+    catch {
+        // R17-F (M3): エラー文に絶対パスを出さない (home/username の info leak 防止)
+        throw new PathValidationError('書込先の親ディレクトリが存在しません');
+    }
+    const allowedReals = [];
+    for (const dir of allowedDirs) {
+        try {
+            allowedReals.push(await fs.realpath(path.resolve(dir)));
+        }
+        catch {
+            // 許可ディレクトリ自体が無い場合は候補から外す (init 前など)
+        }
+    }
+    const inside = allowedReals.some((dir) => parentReal === dir || parentReal.startsWith(dir + path.sep));
+    if (!inside) {
+        // R17-F (M3): 絶対パス (targetPath) を出さない
+        throw new PathValidationError('許可リスト外への書込は許可されていません');
+    }
+    // 対象自体が symlink の場合も拒否する (symlink 越しの書込防止)
+    const canonical = path.join(parentReal, base);
+    try {
+        const stat = await fs.lstat(canonical);
+        if (stat.isSymbolicLink()) {
+            // R17-F (M3): 絶対パス (targetPath) を出さない
+            throw new PathValidationError('symlink への書込は許可されていません');
+        }
+    }
+    catch (error) {
+        if (error instanceof PathValidationError)
+            throw error;
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return canonical;
+}
+/**
+ * 同一ディレクトリの一時ファイルに書いてから rename するアトミック書込 (N-3)。
+ * 許可リスト検証を含まないため、サーバーコードからは safeWriteFile を使うこと。
+ * 直接呼出は CLI の固定パス書込 (init の CLAUDE.md 追記等) とテスト専用。
+ * exclusive 指定時は上書きせず、既存があれば FileExistsError を投げる。
+ */
+export async function writeFileAtomic(filePath, content, options = {}) {
+    const dir = path.dirname(filePath);
+    // .tmp 拡張子にして watcher の .md フィルタに掛からないようにする
+    const tmpPath = path.join(dir, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    // R17-C (#C-1): rename / link 直前に親 realpath を再解決し、書込先 canonical を秘匿 deny で再評価する。
+    // resolveConfigPath の検証〜ここまでの窓で親ディレクトリが .git/hooks への symlink へ差し替えられると、
+    // canonical 文字列に `.git` が現れず deny を素通りしたまま rename が .git/hooks/pre-commit に着地しうる (RCE)。
+    // 直前再検証で「秘匿パスへの差し替え」を検知して中止する。
+    // micro-window: 再 realpath〜rename の間は残存する (Node に renameat (fd ベース atomic rename) が無く、
+    // パス文字列ベースの rename しか使えないため完全封じは標準 API 外)。実害は極小だが受容する。
+    const reCheckHardDeny = async () => {
+        let reParent;
+        try {
+            reParent = await fs.realpath(dir);
+        }
+        catch {
+            return; // 親が消えていれば rename 自体が失敗するので、ここでは追加判定しない
+        }
+        const reCanonical = path.join(reParent, path.basename(filePath));
+        if (isHardDeniedConfigPath(reCanonical)) {
+            throw new PathValidationError('書込直前に秘匿パスへの差し替えを検知したため中止しました');
+        }
+    };
+    try {
+        await fs.writeFile(tmpPath, content, 'utf8');
+        // 明示 mode 指定 (.bak がコピー元の権限を継ぐ等、R8-2) を優先する
+        if (options.mode !== undefined) {
+            await fs.chmod(tmpPath, options.mode & 0o777);
+        }
+        else if (options.preserveMode) {
+            // 既存ファイルの mode を保全する (秘匿ファイルの権限が rename で緩まないように、N-8 / Round 1 #7)
+            try {
+                const existing = await fs.stat(filePath);
+                await fs.chmod(tmpPath, existing.mode & 0o777);
+            }
+            catch (error) {
+                // 既存が無い (新規作成) 場合は保全対象なし。それ以外のエラーは無視せず投げる
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (options.exclusive) {
+            await reCheckHardDeny(); // R17-C: link 直前にも秘匿パス差し替えを再検知
+            // link は対象が存在すると EEXIST で原子的に失敗する (rename と違い上書きしない)
+            try {
+                await fs.link(tmpPath, filePath);
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    throw new FileExistsError(`書込先が既に存在するため上書きしない: ${path.basename(filePath)}`);
+                }
+                throw error;
+            }
+            finally {
+                // link 成否に関わらず tmp は不要 (成功時は hardlink が本体、失敗時は破棄)
+                await fs.rm(tmpPath, { force: true }).catch(() => { });
+            }
+            return;
+        }
+        await reCheckHardDeny(); // R17-C: rename 直前に秘匿パス差し替えを再検知 (.git/hooks への着地を防ぐ)
+        await fs.rename(tmpPath, filePath);
+    }
+    catch (error) {
+        // クリーンアップ自体の失敗で元の書込エラーを隠さない
+        await fs.rm(tmpPath, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+/** 許可リスト検証 + アトミック書込。書き込んだ正規化済みパスを返す */
+export async function safeWriteFile(targetPath, content, allowedDirs, options = {}) {
+    const canonical = await assertWritablePath(targetPath, allowedDirs);
+    await writeFileAtomic(canonical, content, options);
+    return canonical;
+}
+/**
+ * symlink を辿らずにファイルを読む (R14-4: TOCTOU 緩和)。
+ * lstat (symlink 拒否) → readFile の間に対象が symlink へ差し替わる窓を、O_NOFOLLOW で fd を
+ * 開くことで閉じる (対象が symlink なら open 自体が ELOOP で失敗する)。読取専用 (O_RDONLY)。
+ * O_NOFOLLOW は対象パスの最終要素のみに効く (親ディレクトリの symlink は resolveDocPath /
+ * resolveConfigPath 側の parent realpath 検査で既に弾いている)。
+ */
+export async function readFileNoFollow(absPath) {
+    // O_NOFOLLOW が未定義の環境 (理論上 Windows) では通常 readFile にフォールバックする
+    const noFollow = fsConstants.O_NOFOLLOW ?? 0;
+    const fh = await fs.open(absPath, fsConstants.O_RDONLY | noFollow);
+    try {
+        return await fh.readFile('utf8');
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * `.kanban/` の canonical realpath (信頼境界) を確立する (R17-D: 中間 dir symlink containment・#D-1)。
+ *
+ * 旧 R17-A の read ヘルパは「最終成分 lstat / O_NOFOLLOW」だけで symlink を弾いていたが、これらは
+ * **最終成分しか見ない**ため、中間ディレクトリ (`.kanban` 自体 / `.kanban/tasks` / `.kanban/archive`) を
+ * 外部 dir への symlink に差し替えると素通りし、root 外ファイルが漏洩 / 削除されうる
+ * (兄弟ヘルパ config-paths.ts / docs.ts / files.ts は親 realpath containment をやっており、ここだけ非対称・LEARN#6)。
+ *
+ * projectRoot を realpath 解決 (macOS の /tmp→/private/tmp も吸収) し、その直下 `.kanban` を realpath 解決した
+ * 結果が「親 + '.kanban'」と一致するか (= `.kanban` 自体が symlink でないか) を検査する。一致しなければ拒否。
+ * `.kanban` が無ければ realpath が ENOENT を投げる (呼び出し側で graceful: 空ボード / 既定 config に倒す)。
+ */
+export async function resolveKanbanReal(projectRoot) {
+    const rootReal = await fs.realpath(path.resolve(projectRoot));
+    const kanbanDir = path.join(rootReal, '.kanban');
+    const kanbanReal = await fs.realpath(kanbanDir); // .kanban 不在なら ENOENT
+    if (kanbanReal !== kanbanDir) {
+        throw new PathValidationError('.kanban が symlink のためアクセスを拒否しました');
+    }
+    return kanbanReal;
+}
+/**
+ * 対象パスの**親ディレクトリ realpath**が信頼境界 (kanbanReal) 配下かを検査する (R17-D・#D-1)。
+ * realpath は path 全成分の symlink を解決するため、中間ディレクトリ symlink (.kanban/tasks → 外部) も
+ * ここで捕捉できる (最終成分は呼び出し側の lstat / O_NOFOLLOW が二重に弾く)。
+ */
+export async function assertInsideKanban(absPath, kanbanReal) {
+    let parentReal;
+    try {
+        parentReal = await fs.realpath(path.dirname(absPath));
+    }
+    catch {
+        throw new PathValidationError('親ディレクトリが存在しません');
+    }
+    if (parentReal !== kanbanReal && !parentReal.startsWith(kanbanReal + path.sep)) {
+        throw new PathValidationError('.kanban 外 (symlink 経由を含む) へのアクセスを拒否しました');
+    }
+}
+/**
+ * ディレクトリ自体の realpath が信頼境界 (kanbanReal) 配下かを検査する (R17-D: tasksDir 等の中間 dir symlink 用)。
+ * `assertInsideKanban` は「親」realpath を見るが、これは「対象 dir 自身」の realpath を見るため、
+ * tasksDir 自体が外部 dir への symlink のケース (A18-2) を readdir の前に捕捉できる。
+ */
+export async function assertDirInsideKanban(dir, kanbanReal) {
+    if ((await realpathInsideKanban(dir, kanbanReal)) === null) {
+        throw new PathValidationError('.kanban 外 (symlink 経由を含む) のディレクトリへのアクセスを拒否しました');
+    }
+}
+/**
+ * 信頼境界 (kanbanReal) 配下のディレクトリであることを realpath で検査する (walk の中間 dir 用)。
+ * 配下なら realpath を返し、外 (symlink 経由含む) なら null (呼び出し側で skip)。
+ */
+async function realpathInsideKanban(dir, kanbanReal) {
+    let real;
+    try {
+        real = await fs.realpath(dir);
+    }
+    catch {
+        return null;
+    }
+    if (real !== kanbanReal && !real.startsWith(kanbanReal + path.sep))
+        return null;
+    return real;
+}
+/**
+ * `.kanban/` 配下のファイルを stat する (R17-D: realpath containment + 最終成分 symlink 拒否・#A-1/#D-2)。
+ * 親 realpath が kanbanReal 配下かを先に検査し (中間 dir symlink を捕捉)、続けて最終成分を lstat で
+ * symlink 拒否する。通常ファイルは lstat と stat の mtime が一致するため mtimeMs もここで取れる。
+ * 存在しなければ ENOENT をそのまま投げる (呼び出し側の catch で 404 / skip に倒す)。
+ */
+export async function statKanbanFile(absPath, kanbanReal) {
+    await assertInsideKanban(absPath, kanbanReal); // 中間 dir symlink を捕捉
+    const stat = await fs.lstat(absPath);
+    if (stat.isSymbolicLink()) {
+        throw new PathValidationError('.kanban 配下の symlink は許可されていません');
+    }
+    return stat;
+}
+/**
+ * `.kanban/` 配下のファイルを symlink を辿らずに読む (R17-D・#A-1/#D-2)。
+ * statKanbanFile (親 realpath containment で中間 dir symlink を捕捉 + lstat で最終成分 symlink を
+ * PathValidationError 拒否) を通してから readFileNoFollow (O_NOFOLLOW) で読む。最終成分は lstat と
+ * O_NOFOLLOW の両方で弾き、lstat→open の窓の TOCTOU も二重化する。
+ */
+export async function readKanbanFile(absPath, kanbanReal) {
+    await statKanbanFile(absPath, kanbanReal); // 中間 dir symlink + 最終成分 symlink を捕捉 (PathValidationError)
+    return readFileNoFollow(absPath); // 最終成分 symlink を O_NOFOLLOW でも捕捉 (TOCTOU 二重化)
+}
+/**
+ * `.kanban/` 配下を手動再帰し、predicate に該当するファイルの絶対パスを集める (R17-D・#A-1/#D-3)。
+ * top-level `dir` と各再帰 dir の **realpath が kanbanReal 配下か**を検査し、外 (symlink 経由含む) なら skip。
+ * entry の symlink (dir/file 問わず) も skip。`fs.readdir({recursive:true})` は中間 symlink dir を辿るため使わない。
+ * predicate 既定は「`.md` 末尾のファイル」。返すのは絶対パス (呼び出し側で basename / id を扱いやすい)。
+ *
+ * files.ts の collectMarkdownFilesNoSymlink とは「isSecretPath を走査時に適用するか (browse 面は適用 /
+ * .kanban 面は不要)」「predicate を引数化するか」「containment 基準 (kanbanReal vs browseDir)」で分かれるため
+ * 別関数にする (LEARN#8b: 型・フィルタ・境界が揃わないため統合せず別関数。decisions.md に記録)。
+ */
+export async function collectKanbanFilesNoSymlink(dir, kanbanReal, predicate = (p) => p.endsWith('.md')) {
+    // top-level / 再帰下層の dir realpath が kanbanReal 配下でなければ辿らない (中間 dir symlink 防止)
+    if ((await realpathInsideKanban(dir, kanbanReal)) === null)
+        return [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isSymbolicLink())
+            continue; // symlink (dir/file 問わず) は辿らない
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await collectKanbanFilesNoSymlink(abs, kanbanReal, predicate)));
+        }
+        else if (entry.isFile() && predicate(abs)) {
+            results.push(abs);
+        }
+    }
+    return results;
+}
+/**
+ * プロセスクラッシュ時に残った一時ファイル (.<name>.<uuid>.tmp) を削除する (R17-D: containment 限定削除・#D-4)。
+ * serve 起動時に .kanban/ に対して呼ぶ。削除した件数を返す。
+ *
+ * 旧実装は `fs.readdir({recursive:true})` が中間 symlink dir を辿るため、`.kanban/sub → 外部dir` の symlink 下に
+ * `.x.tmp` を置かれると **root 外の任意ファイルを削除**しうる脆弱性があった。collectKanbanFilesNoSymlink で
+ * symlink 非追従 + realpath containment 済みのファイルだけを集め、各削除対象が kanbanReal 配下であることを
+ * 再確認してから削除する。kanbanReal は呼び出し側で resolveKanbanReal して渡す (失敗時は cleanup skip)。
+ */
+export async function cleanupStaleTmpFiles(rootDir, kanbanReal) {
+    const tmpFiles = await collectKanbanFilesNoSymlink(rootDir, kanbanReal, (p) => path.basename(p).startsWith('.') && path.basename(p).endsWith('.tmp'));
+    let removed = 0;
+    for (const abs of tmpFiles) {
+        // 削除直前にも親 realpath が kanbanReal 配下であることを再確認する (二重 guard)
+        try {
+            await assertInsideKanban(abs, kanbanReal);
+        }
+        catch {
+            continue; // containment 外は削除しない
+        }
+        try {
+            await fs.rm(abs, { force: true });
+            removed += 1;
+        }
+        catch {
+            // 消せない残骸はスキップして続行する
+        }
+    }
+    return removed;
+}