ticket: add plugin host api followups

2026-06-19 16:54:40 +09:00
parent 8940262618
commit f1876321c5
15 changed files with 533 additions and 2 deletions
@@ -0,0 +1,88 @@
+---
+title: 'Plugin: implement fs host API for Tool runtime'
+state: 'ready'
+created_at: '2026-06-19T07:53:13Z'
+updated_at: '2026-06-19T07:54:32Z'
+assignee: null
+readiness: 'implementation_ready'
+risk_flags: ['plugin', 'fs', 'host-api', 'sandbox', 'path-safety', 'permission-grants', 'file-mutation']
+---
+
+## Background
+
+Plugin Tool runtime は minimal WASM execution と permission grants まで実装済みだが、Plugin-layer scoped filesystem access はまだ未実装である。
+
+この Ticket では、WASM Plugin Tool から明示 grant された scoped paths のみを read/list/write できる `fs` host API を追加する。Plugin は Pod / workspace の filesystem authority を自動継承しない。Plugin-specific grant だけが有効な authority になる。
+
+## Requirements
+
+- WASM Plugin Tool runtime に `fs` host API import を追加する。
+  - API 名・ABI は既存 `yoi-plugin-wasm-1` / host import 設計と整合させる。
+  - Plugin は ambient filesystem access を持たず、host API 経由のみで fs operation できる。
+- Plugin-layer scoped paths を grant で表現する。
+  - read
+  - list
+  - write の初期 subset
+  - optional path root / glob / prefix policy は implementation-time に最小安全形を選ぶ。
+- Workspace filesystem scope を自動継承しない。
+  - Pod が workspace write authority を持っていても Plugin は grant なしでは読めない/書けない。
+- Path safety を徹底する。
+  - normalization
+  - `..` traversal reject
+  - symlink/root escape reject
+  - absolute/relative path policy を明確化
+  - allowed root 外は fail closed
+- Bounds を設ける。
+  - read size bound
+  - write size bound
+  - directory entry count bound
+  - path length bound
+  - diagnostic size bound
+- Writes は既存 file mutation safety と整合させる。
+  - normalized target file ごとの serialization / atomic-ish behavior を検討する。
+  - broad Worker scheduler は追加しない。
+- Diagnostics は safe にする。
+  - file content を error/log に漏らさない。
+  - rejected path は必要最小限にする。
+- Tool result path は通常 Tool result/history 経路を使う。
+  - hidden context injection しない。
+
+## Acceptance criteria
+
+- Granted Plugin Tool can read an allowed file through `fs` host API.
+- Granted Plugin Tool can list an allowed directory within bounds.
+- Granted Plugin Tool can write an allowed file within bounds.
+- Plugin without matching `host_api.fs` grant cannot read/list/write.
+- Workspace write authority is not inherited by Plugin without Plugin grant.
+- `../` traversal, symlink escape, and allowed-root escape are rejected.
+- Oversize read/write/list results fail closed or truncate according to explicit policy.
+- File mutation safety does not race unsafely with existing Write/Edit semantics.
+- Diagnostics do not include file content or secret-like data.
+- Tests cover:
+  - allowed read
+  - allowed list
+  - allowed write
+  - missing grant denied
+  - workspace authority not inherited
+  - path traversal rejected
+  - symlink/root escape rejected
+  - read/write/list bounds
+  - diagnostics redaction
+  - write serialization or safe conflict behavior
+- Validation: focused plugin fs tests, relevant cargo check/test, `cargo fmt --check`, `git diff --check`, and `nix build .#yoi` because host API / packaging behavior may change.
+
+## Non-goals
+
+- `https` host API implementation.
+- General workspace Read/Write tool delegation.
+- Service / Ingress surface.
+- File watcher / background sync.
+- Broad WASI filesystem exposure.
+- Plugin package manager / install/update.
+
+## Related work
+
+- `00001KV5W3PHW` — Plugin Tool execution with minimal WASM runtime.
+- `00001KV5W3PJ3` — Plugin permission grant enforcement.
+- `00001KVFD3YSV` — Plugin read-only CLI inspection list/show.
+- `00001KSXRQ4G8` — Plugin runtime / surface / minimal host API model design.