aizuchi 0.4.0 → 0.7.2

package/dist/server/app.js

@@ -10,7 +10,8 @@ import { loadArchive, loadBoard, loadConfig, loadTaskView } from './board.js';
 import { createEventBus } from './events.js';
 import { allocateNextId, createSerialQueue } from './lib/id.js';
 import { assertDirInsideKanban, collectKanbanFilesNoSymlink, FileExistsError, PathValidationError, readKanbanFile, resolveKanbanReal, safeWriteFile, statKanbanFile, } from './lib/fs-safe.js';
-import { buildDocsTree, readDoc } from './lib/docs.js';
+import { buildDocsTree, buildDocsWriteTree, deleteDoc, readDoc, TrashSnapshotError, writeDoc } from './lib/docs.js';
+import { assertRelatedDocsAllowed } from './lib/related-docs-validate.js';
 import { findCommitsForTask } from './lib/git.js';
 import { buildCatalog, buildFileTree, buildGlobalCatalog, fileMtime, globalFileMtime, readConfigFile, readGlobalConfigFile, saveConfigFile, saveGlobalConfigFile, } from './lib/files.js';
 import { applyPinpointPatch, renameTaskId, replaceDependsOnId, replaceMemberKeys, verifyMemberRename, verifyPinpointResult, verifyRename, } from './lib/pinpoint.js';
@@ -18,7 +19,7 @@ import { appendCommentLine, appendWorkLogLine, replaceBody, reviseWorkLogText }
 import { REVISABLE_STATUSES } from './lib/task-ops.js';
 import { parseTaskFile, serializeTaskFile, TaskFileParseError } from './lib/task-file.js';
 import { archiveMonth, nowIso, workLogTimestamp } from './lib/time.js';
-import { DEFAULT_TRASH_KEEP, listTrash, snapshotToTrash } from './lib/trash.js';
+import { DEFAULT_TRASH_KEEP, listTrash, snapshotBestEffort, snapshotToTrash } from './lib/trash.js';
 /**
  * Hono アプリ (REST API + SSE)。要件 §6.7 のうち Phase 1 スコープの
  * board / tasks / events のみを実装する (アーカイブ・承認・却下 API は Phase 2)。
@@ -75,7 +76,7 @@ export function applySecurityMiddleware(app) {
     // GET は読出専用 (CORS ヘッダ無しでクロスオリジン読出不可) なので対象外。
     app.use('/api/*', async (c, next) => {
         const method = c.req.method;
-        if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+        if (method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE') {
             const contentType = c.req.header('content-type') ?? '';
             // "application/json" / "application/json; charset=utf-8" を許可。それ以外は 415
             const mediaType = contentType.split(';')[0].trim().toLowerCase();
@@ -167,14 +168,11 @@ export function createApp(options) {
      *   containment で再検証するためパス安全 (検証済み前提に依存しない)。
      */
     const snapshot = async (id, currentContent, kanbanReal) => {
-        try {
-            const { config } = await loadConfig(projectRoot);
-            const keep = config.trashKeep ?? DEFAULT_TRASH_KEEP;
-            await snapshotToTrash(id, currentContent, kanbanDir, kanbanReal, keep);
-        }
-        catch {
-            // 退避はベストエフォート安全網。失敗しても本処理 (破壊的書込) は止めない
-        }
+        // M9 (LEARN#8b): 退避のベストエフォート握り潰し自体は snapshotBestEffort (trash.ts) に集約。
+        // loadConfig は失敗しない (常に既定値へフォールバック) ため try/catch の外に出しても挙動は不変。
+        const { config } = await loadConfig(projectRoot);
+        const keep = config.trashKeep ?? DEFAULT_TRASH_KEEP;
+        await snapshotBestEffort(id, currentContent, kanbanDir, kanbanReal, keep);
     };
     // セキュリティミドルウェア (CSP / Host / CSRF / bodyLimit) は overview と共通 (R14-5)
     applySecurityMiddleware(app);
@@ -223,6 +221,17 @@ export function createApp(options) {
         if (violations.length > 0) {
             return c.json({ error: violations.join(' / ') }, 400);
         }
+        // 波 VIII: related_docs は docsDirs / docsWriteDirs 配下の妥当な .md 相対パスのみ受け付ける
+        // (frontmatter に保存して良い参照値かの検証。読取時の symlink/TOCTOU 防御は docs.ts が担保)
+        if (input.data.related_docs !== undefined && input.data.related_docs.length > 0) {
+            try {
+                assertRelatedDocsAllowed(projectRoot, config, input.data.related_docs);
+            }
+            catch (error) {
+                const message = error instanceof PathValidationError ? error.message : 'related_docs が不正です';
+                return c.json({ error: message }, 400);
+            }
+        }
         // 走査 → 採番 → 書込 をアトミックに直列化する (同時起票の ID 重複防止)。
         // 書込は排他作成 (exclusive) にし、採番後の窓で AI が同 ID を直書きしていた場合は
         // 上書きせず再採番 retry する (N-3: POST が外部データを silent 上書きするのを防ぐ)
@@ -239,6 +248,7 @@ export function createApp(options) {
                     created_by: input.data.created_by,
                     priority: input.data.priority ?? 'medium',
                     labels: input.data.labels ?? [],
+                    related_docs: input.data.related_docs,
                     blocked_type: null,
                     blocked_reason: null,
                     created: now,
@@ -1120,6 +1130,124 @@ export function createApp(options) {
             throw error;
         }
     });
+    // GET /api/docs/write-tree — docsWriteDirs 配下の .md ツリー (保存先フォルダ選択 UI 用・symlink 非追従)
+    app.get('/api/docs/write-tree', async (c) => {
+        const { config } = await loadConfig(projectRoot);
+        return c.json({ trees: await buildDocsWriteTree(projectRoot, config) });
+    });
+    // POST /api/docs — 資料を新規作成 (exclusive)。親フォルダ未作成なら作成する。既存は 409。
+    app.post('/api/docs', async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (body === null || typeof body.path !== 'string' || body.path === '' || typeof body.content !== 'string') {
+            return c.json({ error: 'path (文字列) と content (文字列) が必要です' }, 400);
+        }
+        const relPath = body.path;
+        const content = body.content;
+        const { config } = await loadConfig(projectRoot);
+        return enqueue(async () => {
+            try {
+                const result = await writeDoc(projectRoot, config, relPath, content, 'create');
+                return c.json(result, 201);
+            }
+            catch (error) {
+                if (error instanceof FileExistsError)
+                    return c.json({ error: '同じパスの資料が既に存在します' }, 409);
+                if (error instanceof PathValidationError)
+                    return c.json({ error: error.message }, 403);
+                throw error;
+            }
+        });
+    });
+    // PUT /api/docs?path=... — 資料を上書き保存 (mtime 厳密比較で競合検知)。範囲外 403 / drift 409。
+    app.put('/api/docs', async (c) => {
+        const relPath = c.req.query('path');
+        if (relPath === undefined || relPath === '') {
+            return c.json({ error: 'path クエリが必要です' }, 400);
+        }
+        const body = (await c.req.json().catch(() => null));
+        if (body === null || typeof body.content !== 'string' || typeof body.baseMtimeMs !== 'number') {
+            return c.json({ error: 'content (文字列) と baseMtimeMs (数値) が必要です' }, 400);
+        }
+        const content = body.content;
+        const baseMtimeMs = body.baseMtimeMs;
+        const { config } = await loadConfig(projectRoot);
+        return enqueue(async () => {
+            try {
+                const result = await writeDoc(projectRoot, config, relPath, content, 'overwrite', baseMtimeMs);
+                if ('conflict' in result) {
+                    return c.json({ error: '外部で変更されています', serverContent: result.conflict.serverContent, serverMtimeMs: result.conflict.serverMtimeMs }, 409);
+                }
+                return c.json(result);
+            }
+            catch (error) {
+                if (error instanceof PathValidationError)
+                    return c.json({ error: error.message }, 403);
+                if (error.code === 'ENOENT')
+                    return c.json({ error: '資料が見つかりません' }, 404);
+                throw error;
+            }
+        });
+    });
+    // DELETE /api/docs?path=... — 資料を削除 (unlink 前に .kanban/.trash へ退避)。不在 404 / 範囲外 403。
+    app.delete('/api/docs', async (c) => {
+        const relPath = c.req.query('path');
+        if (relPath === undefined || relPath === '') {
+            return c.json({ error: 'path クエリが必要です' }, 400);
+        }
+        const { config } = await loadConfig(projectRoot);
+        return enqueue(async () => {
+            try {
+                const result = await deleteDoc(projectRoot, config, relPath);
+                return c.json({ path: result.path, deleted: true });
+            }
+            catch (error) {
+                if (error instanceof PathValidationError)
+                    return c.json({ error: error.message }, 403);
+                // fail-closed: 退避できなかったので削除は中止済み (本体は消えていない)。DELETE /api/tasks と対称に 500。
+                if (error instanceof TrashSnapshotError)
+                    return c.json({ error: error.message }, 500);
+                if (error.code === 'ENOENT')
+                    return c.json({ error: '資料が見つかりません' }, 404);
+                throw error;
+            }
+        });
+    });
+    // ---------------------------------------------------------------------
+    // DELETE /api/tasks/:id — タスク本体を削除 (unlink 前に .kanban/.trash へ退避)
+    // archive (moveToArchive) とは別物: archive=復元前提の所在移動、delete=本体削除+ごみ箱退避。
+    // N-2: taskIdSchema で検証 + readKanbanFile (containment + symlink 非追従)。
+    // 存在しない ID は 404。CSRF ミドルウェアが DELETE を対象化済み (資料削除で追加済)。
+    // ---------------------------------------------------------------------
+    app.delete('/api/tasks/:id', async (c) => {
+        const idResult = taskIdSchema.safeParse(c.req.param('id'));
+        if (!idResult.success) {
+            return c.json({ error: '不正なタスク ID' }, 400);
+        }
+        const filePath = path.join(tasksDir, `${idResult.data}.md`);
+        return enqueue(async () => {
+            const kanbanReal = await getKanbanReal();
+            let raw;
+            try {
+                raw = await readKanbanFile(filePath, kanbanReal); // N-2: containment + symlink 非追従
+            }
+            catch {
+                return c.json({ error: `タスクが見つからない: ${idResult.data}` }, 404);
+            }
+            // unlink 前に .trash へ退避。DELETE は他の破壊的書込と違い、退避が「唯一の生き残りコピー」のため
+            // fail-closed にする: 退避に失敗したら 500 で中止し fs.rm はしない (静かな完全消失を防ぐ)。
+            // 他経路の snapshot() はベストエフォート (本体が別の形で残る) だが、削除だけは退避成功を必須とする。
+            try {
+                const { config } = await loadConfig(projectRoot);
+                await snapshotToTrash(idResult.data, raw, kanbanDir, kanbanReal, config.trashKeep ?? DEFAULT_TRASH_KEEP);
+            }
+            catch {
+                return c.json({ error: 'ごみ箱への退避に失敗したため削除を中止しました' }, 500);
+            }
+            // 退避できたときだけ tasks/<id>.md を削除
+            await fs.rm(filePath, { force: true });
+            return c.json({ id: idResult.data, deleted: true });
+        });
+    });
     // ---------------------------------------------------------------------
     // GET /api/tasks/:id/commits — タスク ID を含む git コミット (S-1・read-only)
     // ID をパスから取得 → taskIdSchema で検証 → git.ts が更に厳格バリデーション + execFile (シェル非経由)。

package/dist/server/lib/docs.js

@@ -1,6 +1,28 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { isSecretPath, isStrictlyInside, PathValidationError, readFileNoFollow, sanitizeConfigDirEntries, } from './fs-safe.js';
+import { DOC_BASENAME_RE, isSecretPath, isStrictlyInside, PathValidationError, readFileNoFollow, resolveKanbanReal, safeWriteFile, sanitizeConfigDirEntries, } from './fs-safe.js';
+import { snapshotToTrash, snapshotBestEffort, DEFAULT_TRASH_KEEP } from './trash.js';
+/**
+ * deleteDoc の fail-closed 用エラー。退避 (.kanban/.trash へのコピー) に失敗したため削除を中止したことを表す。
+ * 呼び出し側 (DELETE /api/docs) はこれを 500 にマップする (PathValidationError=403 / ENOENT=404 と区別するため別型)。
+ */
+export class TrashSnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TrashSnapshotError';
+    }
+}
+/**
+ * docsWriteDir 相対の canonical からごみ箱退避 ID を組み立てる。
+ * rootReal からの相対パスをサニタイズ (`[^A-Za-z0-9._-]` → `_`) して含めることで、
+ * 別ディレクトリの同名資料 (docs/a/notes.md と docs/b/notes.md) が同 trashId に潰れて
+ * 世代が混在 (pruneTrash の巻き添え削除 / 復元取り違え) するのを防ぐ。
+ * `.md` 拡張子は除いてから組み立てる。writeDoc(overwrite) と deleteDoc で同一ロジックを共有する。
+ */
+function docTrashId(canonical, rootReal) {
+    const relNoExt = path.relative(rootReal, canonical).replace(/\.md$/i, '');
+    return `doc-${relNoExt.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+}
 /**
  * 関連資料 (波 VIII) の読取専用ファイル I/O。
  * config.docsDirs に列挙されたディレクトリ配下の .md のみを対象にする。
@@ -23,6 +45,15 @@ function effectiveDocsDirs(root, config) {
     const kanbanDir = path.join(root, '.kanban');
     return sanitizeConfigDirEntries(root, config.docsDirs).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
 }
+/**
+ * config.docsWriteDirs を root 配下の有効な書込先ディレクトリ集合 (絶対パス) に正規化する。
+ * effectiveDocsDirs (読取) と同一ロジック: root 自身 / root 外 / .kanban 配下 / 秘匿パスを除外する
+ * (読取と書込で許可リストを分離するため別関数。docsWriteDirs 既定は空 = 書込オフ)。
+ */
+function effectiveDocsWriteDirs(root, config) {
+    const kanbanDir = path.join(root, '.kanban');
+    return sanitizeConfigDirEntries(root, config.docsWriteDirs).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
+}
 /** 要求された相対パスが docsDirs 配下の .md であることを検証し、正規化済み絶対パスを返す */
 export async function resolveDocPath(projectRoot, config, requestedRelPath) {
     const root = path.resolve(projectRoot);
@@ -87,11 +118,12 @@ export async function readDoc(projectRoot, config, relPath) {
     // R14-4: resolveDocPath の lstat (symlink 拒否) と readFile の間で対象が symlink に差し替わる
     // TOCTOU 窓を O_NOFOLLOW で塞ぐ (対象が symlink なら open が ELOOP で失敗する)。
     const content = await readFileNoFollow(absPath);
+    const mtimeMs = (await fs.lstat(absPath)).mtimeMs;
     // absPath は realpath ベースの canonical のため、相対化も realpath 済み root を基準にする
     // (macOS の /var → /private/var のような root 側 symlink で相対パスがずれないように)
     const root = path.resolve(projectRoot);
     const rootReal = await fs.realpath(root).catch(() => root);
-    return { path: path.relative(rootReal, absPath), content };
+    return { path: path.relative(rootReal, absPath), content, mtimeMs };
 }
 /**
  * docsDirs 配下の .md ファイルツリーを構築する。buildFileTree (files.ts) と同じ手動再帰で
@@ -152,3 +184,178 @@ async function buildDocsNode(root, absPath) {
     }
     return null;
 }
+/**
+ * target の祖先のうち realpath できる最も近いものと、未作成 segment 列を返す
+ * (config-paths.ts の同名非 export 関数と同型。docs 書込でも親未作成を許すために複製・LEARN#8b N=2 で defer)。
+ * 未作成 segment は実体が無く symlink になり得ないため、containment 判定は実在祖先の realpath で足りる。
+ */
+async function resolveNearestExistingAncestor(target) {
+    const missing = [];
+    let cur = target;
+    for (;;) {
+        try {
+            return { real: await fs.realpath(cur), missing };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                throw new PathValidationError('親ディレクトリが解決できません');
+            missing.unshift(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/**
+ * 書込要求の相対パスが docsWriteDirs 配下の .md であることを検証し、正規化済み canonical と rootReal を返す
+ * (resolveDocPath の write 版)。読取と異なり「親ディレクトリが未作成」を許す (新規フォルダ作成 + ファイル新規作成のため)。
+ * 多段検査: .md 拡張子 → root 配下 → docsWriteDirs 接頭辞 → isSecretPath → 実在祖先 realpath containment
+ *  → docsWriteDirs realpath 再確認 → 対象 symlink 拒否。
+ */
+export async function resolveDocWritePath(projectRoot, config, requestedRelPath) {
+    const root = path.resolve(projectRoot);
+    if (!requestedRelPath.endsWith('.md')) {
+        throw new PathValidationError('資料は .md ファイルのみ書き込めます');
+    }
+    const resolved = path.resolve(root, requestedRelPath);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new PathValidationError('プロジェクトルート外への書込は許可されていません');
+    }
+    const writeDirs = effectiveDocsWriteDirs(root, config);
+    if (!writeDirs.some((dir) => isStrictlyInside(dir, resolved))) {
+        throw new PathValidationError('docsWriteDirs 外への書込は許可されていません');
+    }
+    if (isSecretPath(resolved)) {
+        throw new PathValidationError('秘匿ファイルへの書込は許可されていません');
+    }
+    // 親 (や中間 dir) が未作成なら「最も近い実在祖先」で containment を判定する (config-paths.ts と同方式)。
+    const rootReal = await fs.realpath(root).catch(() => root);
+    const { real: ancestorReal, missing } = await resolveNearestExistingAncestor(path.dirname(resolved));
+    // 新規作成される中間フォルダ名も basename と同じ規則 (DOC_BASENAME_RE) で検証する (I2)。
+    // containment (下の realpath 判定) とは別軸の「名前」検査で、これを通さないと mkdir recursive で
+    // `.hidden` や bidi 偽装のフォルダ名が docsWriteDirs 配下に作られうる。
+    for (const segment of missing) {
+        if (!DOC_BASENAME_RE.test(segment)) {
+            throw new PathValidationError('作成するフォルダ名に使用できない文字が含まれています');
+        }
+    }
+    if (ancestorReal !== rootReal && !ancestorReal.startsWith(rootReal + path.sep)) {
+        throw new PathValidationError('symlink 経由でプロジェクトルート外を指しています');
+    }
+    const parentReal = missing.length > 0 ? path.join(ancestorReal, ...missing) : ancestorReal;
+    // docsWriteDirs realpath 解決後も配下か再確認する
+    const allowedReals = await Promise.all(writeDirs.map((dir) => fs.realpath(dir).catch(() => dir)));
+    const stillInside = allowedReals.some((dir) => parentReal === dir || parentReal.startsWith(dir + path.sep));
+    if (!stillInside) {
+        throw new PathValidationError('symlink 経由で docsWriteDirs 外を指しています');
+    }
+    const canonical = path.join(parentReal, path.basename(resolved));
+    if (isSecretPath(canonical)) {
+        throw new PathValidationError('秘匿ファイルへの書込は許可されていません');
+    }
+    // 対象が既存 symlink なら拒否 (symlink 越しの書込防止)。未存在は ENOENT で素通り (新規作成)。
+    try {
+        const lst = await fs.lstat(canonical);
+        if (lst.isSymbolicLink()) {
+            throw new PathValidationError('symlink への書込は許可されていません');
+        }
+    }
+    catch (error) {
+        if (error instanceof PathValidationError)
+            throw error;
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return { canonical, rootReal };
+}
+/**
+ * canonical の親ディレクトリを作成する (新規フォルダ込みの保存用)。
+ * resolveDocWritePath が親の realpath containment を済ませた canonical を渡す前提なので、
+ * ここでは未作成 segment を recursive mkdir するだけ (containment 再検査は呼び出し前提条件)。
+ */
+async function ensureDir(canonical) {
+    await fs.mkdir(path.dirname(canonical), { recursive: true });
+}
+export async function writeDoc(projectRoot, config, relPath, content, mode, baseMtimeMs) {
+    const { canonical, rootReal } = await resolveDocWritePath(projectRoot, config, relPath);
+    const writeDirs = effectiveDocsWriteDirs(path.resolve(projectRoot), config);
+    if (mode === 'overwrite') {
+        let serverContent = null;
+        let serverMtimeMs = null;
+        try {
+            serverContent = await readFileNoFollow(canonical);
+            serverMtimeMs = (await fs.lstat(canonical)).mtimeMs;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (serverMtimeMs === null) {
+            const err = new Error('資料が見つかりません');
+            err.code = 'ENOENT';
+            throw err;
+        }
+        if (serverMtimeMs !== null && serverMtimeMs !== baseMtimeMs) {
+            return { conflict: { serverContent: serverContent ?? '', serverMtimeMs } };
+        }
+        // 上書き前に旧版を .kanban/.trash へ退避する (ベストエフォート安全網・deleteDoc と同方式)。
+        // M9 (LEARN#8b): 実際の退避握り潰しは snapshotBestEffort (trash.ts) に集約。resolveKanbanReal は
+        // throw しうるため従来どおり try/catch で包む。
+        try {
+            const kanbanDir = path.join(rootReal, '.kanban');
+            const kanbanReal = await resolveKanbanReal(path.resolve(projectRoot));
+            const trashId = docTrashId(canonical, rootReal);
+            await snapshotBestEffort(trashId, serverContent ?? '', kanbanDir, kanbanReal, config.trashKeep ?? DEFAULT_TRASH_KEEP);
+        }
+        catch {
+            // 退避できなくても上書きは進める (安全網のベストエフォート)
+        }
+        // I2: docsWriteDirs は一般ドキュメント用途のため DOC_BASENAME_RE (Unicode 許可) で basename を検証する
+        // (`.kanban/` システム生成用の ASCII 限定 SAFE_BASENAME_RE とは分離)。
+        await safeWriteFile(canonical, content, writeDirs, {}, DOC_BASENAME_RE);
+    }
+    else {
+        await ensureDir(canonical);
+        await safeWriteFile(canonical, content, writeDirs, { exclusive: true }, DOC_BASENAME_RE);
+    }
+    const mtimeMs = (await fs.lstat(canonical)).mtimeMs;
+    return { path: path.relative(rootReal, canonical), mtimeMs };
+}
+/**
+ * docsWriteDirs 配下の資料を削除する。unlink の前に現内容を .kanban/.trash へコピー退避する (誤削除の安全網)。
+ * 削除は **fail-closed** (DELETE /api/tasks と対称): 退避が「唯一の生き残りコピー」になるため、退避に失敗したら
+ * TrashSnapshotError を投げて削除を中止する (呼び出し側で 500・静かな完全消失を防ぐ)。対象不在は ENOENT (404)。
+ */
+export async function deleteDoc(projectRoot, config, relPath) {
+    const { canonical, rootReal } = await resolveDocWritePath(projectRoot, config, relPath);
+    // 現内容を読む (不在なら ENOENT → 呼び出し側 404)。symlink は resolveDocWritePath が既に拒否済み。
+    const content = await readFileNoFollow(canonical);
+    // 退避に成功したときだけ削除する (退避失敗は TrashSnapshotError で中止)。
+    try {
+        const kanbanDir = path.join(rootReal, '.kanban');
+        const kanbanReal = await resolveKanbanReal(projectRoot);
+        const trashId = docTrashId(canonical, rootReal);
+        await snapshotToTrash(trashId, content, kanbanDir, kanbanReal, config.trashKeep ?? DEFAULT_TRASH_KEEP);
+    }
+    catch {
+        // .kanban 未作成 / .trash 退避不能等で退避できなかった場合は削除を中止する (fail-closed)
+        throw new TrashSnapshotError('ごみ箱への退避に失敗したため削除を中止しました');
+    }
+    await fs.rm(canonical, { force: false }); // 不在なら ENOENT (404)。symlink は事前拒否済み
+    return { path: path.relative(rootReal, canonical) };
+}
+/**
+ * docsWriteDirs 配下の .md ファイルツリーを構築する (buildDocsTree の write 版・保存先選択 UI 用)。
+ * buildDocsNode を共有し symlink 非追従・秘匿除外・空 dir 除外は同一。
+ */
+export async function buildDocsWriteTree(projectRoot, config) {
+    const root = path.resolve(projectRoot);
+    const trees = [];
+    for (const absDir of effectiveDocsWriteDirs(root, config)) {
+        const node = await buildDocsNode(root, absDir);
+        if (node && node.type === 'dir')
+            trees.push(node);
+    }
+    return trees;
+}

package/dist/server/lib/files.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
 import matter from 'gray-matter';
 import path from 'node:path';
 import { GLOBAL_BROWSE_DIRS, resolveConfigPath, resolveGlobalConfigPath } from './config-paths.js';
-import { hasSafeConfigExt, isSecretPath, PathValidationError, readFileNoFollow, sanitizeConfigDirEntries, writeFileAtomic, } from './fs-safe.js';
+import { hasSafeConfigExt, isSecretPath, PathValidationError, readFileNoFollow, resolveAllowedReals, sanitizeConfigDirEntries, writeFileAtomic, } from './fs-safe.js';
 /**
  * AI 設定ファイル管理 (F-4) のファイル I/O。
  * 全ての読み書きは resolveConfigPath で aiConfigPaths 許可リストを通す (N-2)。
@@ -41,21 +41,35 @@ export async function readGlobalConfigFile(homeDir, relPath) {
  * - 既存があれば `.bak` を作成 (上書き前のバックアップ・mode 保全 R8-2)
  * - 本体も mode 保全 (秘匿ファイルの権限が緩まないように、N-8 / Round 1 #7)
  * mtime 不一致は呼び出し側で 409 にする (この関数は検証済み前提で書く)。
+ *
+ * 呼び出し側 (saveConfigFile / saveGlobalConfigFile) は resolveConfigPath / resolveGlobalConfigPath で
+ * 検証済みの absPath と、その検証に用いた containment root (projectRoot / homeDir) を渡す。
+ * export は containment 再検査の白箱回帰テスト用 (app-files の API 統合テストと併せて固定する)。
  */
-async function writeResolved(root, absPath, content) {
+export async function writeResolved(root, absPath, content) {
     // absPath は resolveConfigPath / resolveGlobalConfigPath で検証済み (root 配下・許可リスト内・symlink 非経由)
     await fs.mkdir(path.dirname(absPath), { recursive: true });
+    // resolveConfigPath / resolveGlobalConfigPath は親 realpath が root の realpath 配下であることを検証する
+    // (config-paths.ts: ancestorReal が rootReal 配下か)。検証〜rename の窓で親 dir を root 外 symlink へ
+    // 差し替えると root 外へ着地しうるため、同じ root 境界を containmentReals として writeFileAtomic に渡し、
+    // rename / link 直前の containment 再検査を効かせる (Task 1 の writeFileAtomic 再検査を config 書込経路にも適用)。
+    // .bak (同一親 dir 配下) も同じ境界を渡す。
+    // root の realpath が解決できない (理論上の init 前など) ときは [] になる。空配列を渡すと再検査が全 reject に
+    // 倒れてしまうため、その場合は containmentReals を渡さず (undefined) hard-deny のみの従来挙動に戻す (後方互換)。
+    // 実運用では projectRoot / homeDir は常に存在し非空配列になる。
+    const reals = await resolveAllowedReals([root]);
+    const containmentReals = reals.length > 0 ? reals : undefined;
     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 });
+        await writeFileAtomic(`${absPath}.bak`, prev, { mode: prevStat.mode & 0o777, containmentReals });
     }
     catch (error) {
         if (error.code !== 'ENOENT')
             throw error;
     }
-    await writeFileAtomic(absPath, content, { preserveMode: true });
+    await writeFileAtomic(absPath, content, { preserveMode: true, containmentReals });
     const stat = await fs.stat(absPath);
     return { path: await relPathFromRealRoot(root, absPath), content, mtimeMs: stat.mtimeMs };
 }

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

@@ -21,8 +21,28 @@ export class FileExistsError extends Error {
         this.name = 'FileExistsError';
     }
 }
-// パス区切り・制御文字・先頭ドットを含むファイル名を拒否する (ファイル名サニタイズ)
+// パス区切り・制御文字・先頭ドットを含むファイル名を拒否する (ファイル名サニタイズ)。
+// `.kanban/` 配下のシステム生成ファイル名 (task/config/trash) 専用。ASCII 限定。
 const SAFE_BASENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * 一般ドキュメント (docsWriteDirs) 用の basename 検証 (I2)。SAFE_BASENAME_RE と異なり
+ * 日本語・全角等の Unicode 文字を許可する (このリポ自身が日本語ファイル名を運用しているため)。
+ * 拒否するのは危険側のみ (LEARN#13: 不可視 unicode は regex literal に直書きせず \uXXXX escape で書く):
+ * - 先頭ドット (`(?!\.)`): 隠しファイル化・`..` 系を防ぐ
+ * - パス区切り (`/` `\`): POSIX の `path.basename` は `\` を区切りと解釈せず素通りしうるため、
+ *   Windows 由来の混乱・ツール間差異を避けるため明示的に拒否する
+ * - 制御・書式・区切りを Unicode プロパティで網羅拒否 (列挙 denylist では \p{Cf} 全体を塞げず
+ *   tag 文字等が素通りしたため切替。敵対的検証 wej3c4m14):
+ *   \p{Cc} (C0/C1/DEL) / \p{Zl} (U+2028) / \p{Zp} (U+2029) /
+ *   \p{Cf} (bidi 制御 U+202A-202E・U+2066-2069、方向マーク、zero-width、WORD JOINER、
+ *   tag 文字 U+E0000-E007F、SOFT HYPHEN U+00AD、interlinear 等の不可視 format 全般)
+ * - Hangul filler (U+115F/U+1160/U+3164/U+FFA0): \p{Lo} だが不可視スペース状のため明示拒否
+ * - `u` フラグで supplementary plane (tag 文字) も 1 code point として判定する
+ * - 許可の非対称: 単体絵文字・国旗・VS16 付き絵文字は許可するが、ZWJ 合成絵文字は結合子
+ *   U+200D (\p{Cf}) を含むため拒否 (spoofing 耐性優先の許容トレードオフ)
+ * - 空文字 (`+` により 1 文字以上を要求)
+ */
+export const DOC_BASENAME_RE = /^(?!\.)[^/\\\p{Cc}\p{Cf}\p{Zl}\p{Zp}\u115f\u1160\u3164\uffa0]+$/u;
 /**
  * 解決済み絶対パスが root の「真の配下」かを判定する (root 自身は含めない)。
  * config 由来の許可リスト (browseDirs / docsDirs / settingsFiles / rootFiles) の各エントリが
@@ -126,14 +146,37 @@ export function sanitizeConfigDirEntries(root, entries) {
     }
     return result;
 }
+/**
+ * 許可ディレクトリ群を realpath 解決した配列を返す (assertWritablePath と writeFileAtomic の
+ * containment 再検査で共有するヘルパ)。realpath に失敗するもの (init 前で未存在など) は
+ * 候補から外す。返り値は writeFileAtomic に containmentReals として渡し、rename / link 直前の
+ * 再検査でも同じ許可境界を使うことで、検証〜書込間の親 dir 差し替え (TOCTOU) を遮断する。
+ *
+ * files.ts:writeResolved (config 書込経路) も resolveConfigPath が validate した containment 境界
+ * (= root の realpath) を渡すために本ヘルパを再利用する (realpath 解決の単一ソース化)。
+ */
+export async function resolveAllowedReals(allowedDirs) {
+    const allowedReals = [];
+    for (const dir of allowedDirs) {
+        try {
+            allowedReals.push(await fs.realpath(path.resolve(dir)));
+        }
+        catch {
+            // 許可ディレクトリ自体が無い場合は候補から外す (init 前など)
+        }
+    }
+    return allowedReals;
+}
 /**
  * 書込先パスを検証し、正規化済みの絶対パスを返す。
  * allowedDirs は書込を許可するディレクトリの一覧 (Phase 1 は `.kanban/` のみ)。
+ * basenameRe は basename 検証に使う正規表現 (I2: 既定は `.kanban/` システム生成用の ASCII 限定
+ * `SAFE_BASENAME_RE`。docsWriteDirs 書込 (docs.ts) は日本語等を許可する `DOC_BASENAME_RE` を渡す)。
  */
-export async function assertWritablePath(targetPath, allowedDirs) {
+export async function assertWritablePath(targetPath, allowedDirs, basenameRe = SAFE_BASENAME_RE) {
     const resolved = path.resolve(targetPath);
     const base = path.basename(resolved);
-    if (!SAFE_BASENAME_RE.test(base)) {
+    if (!basenameRe.test(base)) {
         throw new PathValidationError(`不正なファイル名のため書込を拒否: ${JSON.stringify(base)}`);
     }
     let parentReal;
@@ -144,15 +187,7 @@ export async function assertWritablePath(targetPath, allowedDirs) {
         // 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 allowedReals = await resolveAllowedReals(allowedDirs);
     const inside = allowedReals.some((dir) => parentReal === dir || parentReal.startsWith(dir + path.sep));
     if (!inside) {
         // R17-F (M3): 絶対パス (targetPath) を出さない
@@ -185,10 +220,14 @@ 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)。
-    // 直前再検証で「秘匿パスへの差し替え」を検知して中止する。
+    // R17-C (#C-1) + Task 1: rename / link 直前に親 realpath を再解決し、書込先 canonical を
+    // (1) 秘匿 deny (hard-deny) と (2) 許可リスト containment の両方で再評価する。
+    // resolveConfigPath / assertWritablePath の検証〜ここまでの窓で親ディレクトリが差し替えられると、
+    // - .git/hooks への symlink: canonical 文字列に `.git` が現れず deny を素通りし rename が
+    //   .git/hooks/pre-commit に着地しうる (RCE)。→ hard-deny 再検査で遮断。
+    // - 許可リスト外 dir への symlink: assertWritablePath が確認した親が rename 時には root 外を指し、
+    //   root 外へ書込が着地しうる。→ containmentReals 再検査で遮断 (containmentReals 指定時のみ)。
+    // 直前再検証で「秘匿パス / 許可リスト外への差し替え」を検知して中止する。
     // micro-window: 再 realpath〜rename の間は残存する (Node に renameat (fd ベース atomic rename) が無く、
     // パス文字列ベースの rename しか使えないため完全封じは標準 API 外)。実害は極小だが受容する。
     const reCheckHardDeny = async () => {
@@ -203,6 +242,15 @@ export async function writeFileAtomic(filePath, content, options = {}) {
         if (isHardDeniedConfigPath(reCanonical)) {
             throw new PathValidationError('書込直前に秘匿パスへの差し替えを検知したため中止しました');
         }
+        // containmentReals が渡されていれば許可リスト containment も再検査する (Task 1)。
+        // 未指定 (CLI 固定パス・テスト直叩き) では従来どおり hard-deny のみで後方互換。
+        const containmentReals = options.containmentReals;
+        if (containmentReals !== undefined) {
+            const stillInside = containmentReals.some((d) => reParent === d || reParent.startsWith(d + path.sep));
+            if (!stillInside) {
+                throw new PathValidationError('書込直前に許可リスト外への差し替えを検知したため中止しました');
+            }
+        }
     };
     try {
         await fs.writeFile(tmpPath, content, 'utf8');
@@ -249,10 +297,17 @@ export async function writeFileAtomic(filePath, content, options = {}) {
         throw error;
     }
 }
-/** 許可リスト検証 + アトミック書込。書き込んだ正規化済みパスを返す */
-export async function safeWriteFile(targetPath, content, allowedDirs, options = {}) {
-    const canonical = await assertWritablePath(targetPath, allowedDirs);
-    await writeFileAtomic(canonical, content, options);
+/**
+ * 許可リスト検証 + アトミック書込。書き込んだ正規化済みパスを返す。
+ * basenameRe は assertWritablePath へそのまま渡す (I2: 既定は SAFE_BASENAME_RE。docs.ts は
+ * DOC_BASENAME_RE を渡して日本語等の basename を許可する)。
+ */
+export async function safeWriteFile(targetPath, content, allowedDirs, options = {}, basenameRe = SAFE_BASENAME_RE) {
+    const canonical = await assertWritablePath(targetPath, allowedDirs, basenameRe);
+    // Task 1: 検証で使った許可境界 (realpath) を writeFileAtomic に渡し、rename / link 直前の
+    // containment 再検査で同じ境界を使う (検証〜書込間の親 dir 差し替え TOCTOU を遮断)。
+    const allowedReals = await resolveAllowedReals(allowedDirs);
+    await writeFileAtomic(canonical, content, { ...options, containmentReals: allowedReals });
     return canonical;
 }
 /**
@@ -352,13 +407,18 @@ export async function statKanbanFile(absPath, kanbanReal) {
     return stat;
 }
 /**
- * `.kanban/` 配下のファイルを symlink を辿らずに読む (R17-D・#A-1/#D-2)。
+ * `.kanban/` 配下のファイルを symlink を辿らずに読む (R17-D・#A-1/#D-2 + Task 1: 親 symlink TOCTOU 緩和)。
  * statKanbanFile (親 realpath containment で中間 dir symlink を捕捉 + lstat で最終成分 symlink を
  * PathValidationError 拒否) を通してから readFileNoFollow (O_NOFOLLOW) で読む。最終成分は lstat と
  * O_NOFOLLOW の両方で弾き、lstat→open の窓の TOCTOU も二重化する。
+ * さらに open 直前に assertInsideKanban で親 realpath を再確認し、statKanbanFile〜open の窓で
+ * 中間 dir が外部 symlink へ差し替えられても root 外を読まないようにする (書込側 reCheckHardDeny と
+ * 同じ micro-window 強度)。残存 micro-window は受容する (Node に openat (fd ベース atomic open) が
+ * 無く、パス文字列ベースの open しか使えないため完全封じは標準 API 外)。
  */
 export async function readKanbanFile(absPath, kanbanReal) {
     await statKanbanFile(absPath, kanbanReal); // 中間 dir symlink + 最終成分 symlink を捕捉 (PathValidationError)
+    await assertInsideKanban(absPath, kanbanReal); // open 直前に親 realpath を再確認 (中間 dir 差し替えの TOCTOU 緩和)
     return readFileNoFollow(absPath); // 最終成分 symlink を O_NOFOLLOW でも捕捉 (TOCTOU 二重化)
 }
 /**