flode 0.60.3__py3-none-any.whl

flode/server/runtime.py

@@ -0,0 +1,354 @@
+"""シミュレーション実行マネージャ (ADR-0011 §(4))。
+
+``ThreadPoolExecutor`` で ``Simulator.run()`` を背景実行し、Scope データを
+``asyncio.Queue`` に push して WebSocket クライアントへ配信する。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import logging
+import threading
+import time
+import uuid
+from collections.abc import AsyncIterator
+from concurrent.futures import Future, ThreadPoolExecutor
+from typing import Any
+
+import numpy as np
+
+from ..core.persistence import serialize_t_end
+from ..core.simulator import Simulator
+from ..exceptions import FlodeError, SimulationStillRunningError
+from .errors import build_failure_payload
+
+_logger = logging.getLogger("flode.server.runtime")
+
+
+@dataclasses.dataclass
+class SimulationState:
+    """シミュレーションの公開状態 (REST ``GET /simulations/{id}`` 用)。
+
+    ADR-0042 §論点 3-A: ``t_end`` は ``float`` (有限値) または ``"inf"`` 文字列
+    リテラル (= unbounded、``Stop Time = inf``) を取る Union。
+    """
+
+    simulation_id: str
+    model_id: str
+    status: str  # "running" / "completed" / "failed" / "stopped"
+    current_t: float
+    t_end: float | str
+    started_at: float
+    finished_at: float | None = None
+    error: str | None = None
+
+
+class _SimulationRecord:
+    """内部追跡: Simulator インスタンス + 背景タスク + asyncio キュー。"""
+
+    def __init__(
+        self,
+        *,
+        simulation_id: str,
+        model_id: str,
+        simulator: Simulator,
+        loop: asyncio.AbstractEventLoop,
+        scope_batch_size: int,
+    ) -> None:
+        self.simulation_id = simulation_id
+        self.model_id = model_id
+        self.simulator = simulator
+        self.loop = loop
+        self.scope_batch_size = scope_batch_size
+        self.queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=1024)
+        self.state = SimulationState(
+            simulation_id=simulation_id,
+            model_id=model_id,
+            status="running",
+            current_t=0.0,
+            # ADR-0042 §論点 3-A: ``math.inf`` は wire 上 ``"inf"`` 文字列で
+            # 配信する (= JS 側 JSON.stringify(Infinity)==="null" の罠回避)。
+            t_end=serialize_t_end(simulator.t_end),
+            started_at=time.time(),
+        )
+        self.future: Future[None] | None = None
+        # 各 Scope の前回送信済みインデックス (バッチ送信用)
+        self._scope_cursors: dict[str, int] = {}
+        # ADR-0056 §B-4: WS 再接続時の terminal メッセージ replay 用。
+        # ``_run_in_thread`` の finally で最終 ``completed`` / ``stopped`` / ``failed``
+        # メッセージをここに保持し、``SimulationManager.stream`` が再接続時に冒頭で 1
+        # 回 yield してから queue 処理に入る。
+        self.last_terminal_msg: dict[str, Any] | None = None
+
+
+class SimulationManager:
+    """背景タスクで ``Simulator.run`` を回し WS にイベントを配信するマネージャ。
+
+    ``FastAPI`` の lifespan 内で 1 つだけ生成し、リクエストハンドラから利用する。
+    """
+
+    def __init__(self, max_concurrent: int = 4) -> None:
+        self._executor = ThreadPoolExecutor(max_workers=max_concurrent)
+        self._records: dict[str, _SimulationRecord] = {}
+        self._lock = threading.Lock()
+
+    def shutdown(self) -> None:
+        self._executor.shutdown(wait=False, cancel_futures=True)
+
+    def list_simulations(self) -> list[SimulationState]:
+        with self._lock:
+            return [dataclasses.replace(r.state) for r in self._records.values()]
+
+    def get_state(self, sim_id: str) -> SimulationState:
+        with self._lock:
+            if sim_id not in self._records:
+                raise FlodeError(f"Unknown simulation_id: {sim_id!r}")
+            return dataclasses.replace(self._records[sim_id].state)
+
+    def stop(self, sim_id: str) -> None:
+        with self._lock:
+            if sim_id not in self._records:
+                raise FlodeError(f"Unknown simulation_id: {sim_id!r}")
+            rec = self._records[sim_id]
+        rec.simulator.request_stop()
+
+    def start(
+        self,
+        *,
+        model_id: str,
+        simulator: Simulator,
+        loop: asyncio.AbstractEventLoop,
+        scope_batch_size: int,
+    ) -> str:
+        """既に構築済の ``Simulator`` インスタンスからシミュレーションを開始する。
+
+        ADR-0041 §論点 5-A 以前は ``model_path`` を受け取って ``Simulator.load``
+        を内部で呼んでいたが、ファイル ロード / インラインモデル / 旧 ``model_id``
+        の 3 形式が混在するようになったため **ロード責務を呼び出し側に委譲**
+        した。route handler が文字列引数を Simulator に解決してから start を
+        呼ぶ形に統一。
+
+        Args:
+            model_id: 表示用モデル識別子 (= ファイル path / 旧 model_id /
+                ``"<inline>"`` のいずれか)。トラッキング表示用で fs にアクセス
+                しない。
+            simulator: 構築済の ``Simulator`` インスタンス (= ``Simulator.load`` /
+                ``Simulator.from_dict`` のどちらかで生成済)。
+            loop: WS dispatch 用の asyncio loop。
+            scope_batch_size: Scope バッチ送信のサイズ。
+        """
+        sim_id = uuid.uuid4().hex[:12]
+        record = _SimulationRecord(
+            simulation_id=sim_id,
+            model_id=model_id,
+            simulator=simulator,
+            loop=loop,
+            scope_batch_size=scope_batch_size,
+        )
+
+        # on_step_callback を設定 (バッチ送信トリガー)
+        simulator.on_step_callback = lambda t, t_end: self._on_step(record, t, t_end)
+
+        with self._lock:
+            self._records[sim_id] = record
+        record.future = self._executor.submit(self._run_in_thread, record)
+        return sim_id
+
+    # ---------- 内部実装 ----------
+
+    def _on_step(self, rec: _SimulationRecord, t: float, t_end: float) -> bool:
+        rec.state.current_t = t
+        # 各 Scope について新規サンプル数が batch_size に達したら送信
+        for b in rec.simulator.blocks:
+            scope = _as_scope(b)
+            if scope is None:
+                continue
+            assert scope.id is not None
+            cursor = rec._scope_cursors.get(scope.id, 0)
+            n_total = len(scope.times)
+            if n_total - cursor >= rec.scope_batch_size:
+                self._dispatch_scope_batch(rec, scope, cursor, n_total)
+                rec._scope_cursors[scope.id] = n_total
+        # progress イベント (バッチサイズに関わらず毎ステップ送る)。
+        # ADR-0042 §論点 3-A: ``t_end`` は ``serialize_t_end`` 経由で
+        # ``math.inf → "inf"`` 文字列にする (= wire 形式統一)。
+        self._dispatch(
+            rec,
+            {
+                "type": "progress",
+                "current_t": t,
+                "t_end": serialize_t_end(t_end),
+            },
+        )
+        return True
+
+    def _flush_remaining_scopes(self, rec: _SimulationRecord) -> None:
+        """終了時に残った scope サンプルを送る。"""
+        for b in rec.simulator.blocks:
+            scope = _as_scope(b)
+            if scope is None:
+                continue
+            assert scope.id is not None
+            cursor = rec._scope_cursors.get(scope.id, 0)
+            n_total = len(scope.times)
+            if n_total > cursor:
+                self._dispatch_scope_batch(rec, scope, cursor, n_total)
+                rec._scope_cursors[scope.id] = n_total
+
+    def _dispatch_scope_batch(
+        self, rec: _SimulationRecord, scope: Any, start: int, end: int
+    ) -> None:
+        # ADR-0042 §論点 2-A: ``Scope.buffer_mode='ring'`` で ``scope.times`` が
+        # ``deque`` の場合、slice 直接適用は非対応。一度 list / np.asarray に
+        # 変換してから slice することで両モード対応する。
+        # NOTE: ring wrap 後に最古サンプルが drop されると ``cursor`` が
+        # stale になる edge case があるが、Step 5 (WS scope_overflow message
+        # 配信) で本格対応する。本ステップでは finite t_end 既存挙動の
+        # 完全互換のみを保証する。
+        times = list(scope.times)[start:end]
+        values_arr = np.asarray(scope.values)[start:end]
+        msg = {
+            "type": "scope_batch",
+            "scope_id": scope.id,
+            "times": times,
+            "values": values_arr.tolist(),
+        }
+        self._dispatch(rec, msg)
+
+    def _dispatch(self, rec: _SimulationRecord, msg: dict[str, Any]) -> None:
+        """thread から asyncio.Queue へ thread-safe に push (ADR-0011 Risk #1)。
+
+        Queue が満杯 (= 1024 件) の場合は **古いメッセージを drop** して新しい
+        メッセージを優先する (back-pressure ではなく fail-fast)。これにより thread
+        側が put で永続的に block するのを防ぐ (code-reviewer MUST #4 修正)。
+        """
+
+        async def _put_or_drop() -> None:
+            try:
+                rec.queue.put_nowait(msg)
+            except asyncio.QueueFull:
+                # 古いものを 1 件 drop して空きを作って入れ直す
+                try:
+                    _ = rec.queue.get_nowait()
+                except asyncio.QueueEmpty:
+                    pass
+                try:
+                    rec.queue.put_nowait(msg)
+                except asyncio.QueueFull:
+                    _logger.warning(
+                        "WS queue still full after eviction; dropping message type=%r "
+                        "(simulation_id=%s)",
+                        msg.get("type"),
+                        rec.simulation_id,
+                    )
+
+        try:
+            asyncio.run_coroutine_threadsafe(_put_or_drop(), rec.loop)
+        except RuntimeError:
+            # loop が閉じている場合は drop (シャットダウン途中)
+            _logger.debug("event loop closed; dropping message %r", msg.get("type"))
+
+    def _run_in_thread(self, rec: _SimulationRecord) -> None:
+        # ADR-0056 §B-3: 失敗時の構造化 payload は finally 内で `failed` 1 件にまとめる
+        # (= 旧 `error` メッセージの事前送出を廃止)。例外捕捉時は payload を保持する
+        # だけ、実際の送出は finally で実施する。
+        failure_payload: dict[str, Any] | None = None
+        try:
+            rec.simulator.run()
+            self._flush_remaining_scopes(rec)
+            if rec.simulator.is_stopped:
+                rec.state.status = "stopped"
+            else:
+                rec.state.status = "completed"
+        except Exception as e:  # noqa: BLE001 - server境界でドメイン例外もシステム例外も補足
+            _logger.exception("simulation %s failed", rec.simulation_id)
+            rec.state.status = "failed"
+            rec.state.error = f"{type(e).__name__}: {e}"
+            failure_payload = build_failure_payload(
+                e,
+                simulator=rec.simulator,
+                t=rec.state.current_t,
+            )
+        finally:
+            rec.state.finished_at = time.time()
+            duration = rec.state.finished_at - rec.state.started_at
+            terminal: dict[str, Any] = {
+                "type": rec.state.status,  # completed / stopped / failed
+                "duration_sec": duration,
+            }
+            if failure_payload is not None:
+                # ADR-0056 §B-1: 失敗時のみ構造化フィールドをマージ。
+                terminal.update(failure_payload)
+            # ADR-0056 §B-4: replay 用に保持 (= 再接続クライアントが冒頭で受信できる)。
+            # code-reviewer MUST-2: dispatch を先に行ってから last_terminal_msg をセット
+            # することで、stream() の replay 判定 (last_terminal_msg is not None and
+            # queue.empty()) が「dispatch 前 / queue 未投入」窓で誤発火するレースを
+            # 防ぐ (= dispatch 後は queue に入っているので queue.empty() が False、
+            # 通常 drain ルートへ確実に流れる)。
+            self._dispatch(rec, terminal)
+            rec.last_terminal_msg = terminal
+
+    async def stream(self, sim_id: str) -> AsyncIterator[dict[str, Any]]:
+        with self._lock:
+            if sim_id not in self._records:
+                raise FlodeError(f"Unknown simulation_id: {sim_id!r}")
+            rec = self._records[sim_id]
+        # ADR-0056 §B-4: 終端済みシミュレーションへの **再接続** (= queue 既消費)
+        # 時、保存済みの terminal を 1 回 yield して即クローズ。失敗詳細を
+        # 取り損ねないことが目的。初回接続で queue にメッセージが残っている
+        # ケースは下の通常ループに任せる (= progress / scope_batch / 最後に
+        # terminal を順に yield)。
+        if rec.last_terminal_msg is not None and rec.queue.empty():
+            yield dict(rec.last_terminal_msg)
+            return
+        terminal_types = {"completed", "stopped", "failed"}
+        while True:
+            msg = await rec.queue.get()
+            yield msg
+            if msg.get("type") in terminal_types:
+                break
+
+    def get_results(self, sim_id: str) -> dict[str, Any]:
+        """完了後に Scope データを一括取得 (ADR-0011 §(1) GET /results)。"""
+        with self._lock:
+            if sim_id not in self._records:
+                raise FlodeError(f"Unknown simulation_id: {sim_id!r}")
+            rec = self._records[sim_id]
+        if rec.state.status == "running":
+            raise SimulationStillRunningError(
+                f"Simulation {sim_id!r} is still running; results not yet available"
+            )
+        scopes: dict[str, Any] = {}
+        for b in rec.simulator.blocks:
+            scope = _as_scope(b)
+            if scope is None:
+                continue
+            assert scope.id is not None
+            scopes[scope.id] = {
+                "labels": list(scope.labels),
+                "times": list(scope.times),
+                "values": np.asarray(scope.values).tolist(),
+            }
+        return {
+            "simulation_id": sim_id,
+            "status": rec.state.status,
+            "scopes": scopes,
+        }
+
+
+def _as_scope(b: Any) -> Any:
+    """``Scope`` 互換のブロックなら ``b`` を返し、そうでなければ ``None``。
+
+    duck-typing で ``record`` / ``times`` / ``values`` / ``labels`` を持つかを確認
+    する。``Block`` 基底に直接の attr 宣言がないため、mypy は ``Any`` 経由で呼び
+    出す形にする。
+    """
+    if (
+        hasattr(b, "record")
+        and hasattr(b, "times")
+        and hasattr(b, "values")
+        and hasattr(b, "labels")
+    ):
+        return b
+    return None

flode/server/security/__init__.py

@@ -0,0 +1,7 @@
+"""サーバ側のセキュリティユーティリティ (ADR-0041)。"""
+
+from __future__ import annotations
+
+from .paths import resolve_workspace_path
+
+__all__ = ["resolve_workspace_path"]

flode/server/security/origin.py

@@ -0,0 +1,122 @@
+"""ブラウザ由来の cross-site 書き込み要求 (CSRF) を拒否する request guard (SPEC-0023 追補)。
+
+背景 (security-reviewer 指摘、v0.49.0): flode は loopback bind を「ローカルの信頼できる
+利用者しか到達しない」前提で無認証だが、**ブラウザ** はその前提の外にいる。利用者が
+任意のサイトを閲覧しているだけで、そのページの JS は
+``fetch("http://127.0.0.1:8770/api/v1/simulations", {method: "POST", mode: "no-cors",
+headers: {"Content-Type": "text/plain"}, body: ...})`` (= preflight の要らない
+*simple request*) を送れる。``PythonFunction`` 導入後はこれが任意コード実行に直結する。
+
+防御 (state-changing = ``POST`` / ``PUT`` / ``PATCH`` / ``DELETE`` にのみ適用):
+
+1. **Content-Type 強制**: 本文を持つ要求は ``application/json`` 以外を 415 で拒否する。
+   これで simple request が成立しなくなり、cross-origin 送信には preflight が必須になる
+   (CORS ミドルウェアが ``allow_origins`` 未設定なら preflight は失敗する)
+2. **Origin 検証**: ``Origin`` ヘッダがある要求は、(a) ``settings.allow_origins`` に
+   含まれる、または (b) 要求の ``Host`` と同一オリジンで **かつ** そのホストが IP
+   リテラル / ``localhost`` (= DNS rebinding で偽装できない名前) のときだけ通す。
+   ``Origin: null`` (sandbox iframe / file://) は拒否。``Origin`` が無い要求
+   (= curl 等の非ブラウザクライアント) はそのまま通す — ブラウザは書き込み要求に
+   必ず ``Origin`` を付けるので、無いものはブラウザ由来ではない
+
+ホスト名 (``http://mypc.local:8770`` 等) で自サーバーにアクセスする運用は
+``--allow-origin http://mypc.local:8770`` で明示的に許可する。
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+STATE_CHANGING_METHODS: frozenset[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+JSON_MEDIA_TYPE = "application/json"
+
+
+@dataclass(frozen=True)
+class RequestRejection:
+    """guard が要求を拒否する理由 (HTTP status + 人間可読メッセージ)。"""
+
+    status_code: int
+    detail: str
+
+
+def _hostname_of(host_with_port: str) -> str:
+    """``Host`` / origin の ``host[:port]`` からホスト名部分 (小文字、``[]`` 除去) を返す。"""
+    h = host_with_port.strip().lower()
+    if h.startswith("["):
+        end = h.find("]")
+        return h[1:end] if end > 0 else h
+    if h.count(":") == 1:
+        return h.rsplit(":", 1)[0]
+    return h
+
+
+def is_unspoofable_host(hostname: str) -> bool:
+    """DNS rebinding で偽装できないホスト名か (= IP リテラルまたは ``localhost``)。"""
+    name = hostname.strip().lower().strip("[]")
+    if name == "localhost":
+        return True
+    try:
+        ipaddress.ip_address(name)
+    except ValueError:
+        return False
+    return True
+
+
+def _media_type(content_type: str | None) -> str:
+    if not content_type:
+        return ""
+    return content_type.split(";", 1)[0].strip().lower()
+
+
+def check_state_changing_request(
+    *,
+    method: str,
+    origin: str | None,
+    host: str | None,
+    content_type: str | None,
+    has_body: bool,
+    allow_origins: list[str] | tuple[str, ...],
+) -> RequestRejection | None:
+    """書き込み要求を通してよいか判定する純粋関数。``None`` = 許可。
+
+    Args:
+        method: HTTP メソッド。
+        origin: ``Origin`` ヘッダ (無ければ ``None``)。
+        host: ``Host`` ヘッダ (無ければ ``None``)。
+        content_type: ``Content-Type`` ヘッダ。
+        has_body: 本文があるか (``Content-Length > 0`` または ``Transfer-Encoding`` あり)。
+        allow_origins: ``settings.allow_origins`` (CORS 許可オリジンと共用)。
+    """
+    if method.upper() not in STATE_CHANGING_METHODS:
+        return None
+    if has_body and _media_type(content_type) != JSON_MEDIA_TYPE:
+        return RequestRejection(
+            415,
+            f"State-changing requests must use Content-Type: {JSON_MEDIA_TYPE} "
+            f"(got {content_type!r}). This blocks cross-site form/simple requests.",
+        )
+    if origin is None:
+        return None
+    origin_norm = origin.strip().lower()
+    if origin_norm in {o.strip().lower().rstrip("/") for o in allow_origins}:
+        return None
+    if origin_norm == "null":
+        return RequestRejection(403, "Requests from an opaque (null) origin are rejected.")
+    parts = urlsplit(origin_norm)
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        return RequestRejection(403, f"Malformed Origin header: {origin!r}.")
+    if host is not None and parts.netloc == host.strip().lower():
+        if is_unspoofable_host(_hostname_of(parts.netloc)):
+            return None
+        return RequestRejection(
+            403,
+            f"Same-origin request via hostname {parts.netloc!r} is rejected to prevent DNS "
+            f"rebinding; add it explicitly with --allow-origin {origin}.",
+        )
+    return RequestRejection(
+        403,
+        f"Cross-origin request from {origin!r} is rejected. Add it with --allow-origin "
+        f"if this is your own frontend.",
+    )

flode/server/security/paths.py

@@ -0,0 +1,143 @@
+"""Workspace path resolution with traversal defense (ADR-0041 §論点 2-A)。
+
+REST ``/api/v1/files/*`` で利用者が渡す ``?path=...`` を **workspace root 配下**
+に解決し、root 外への traversal や OS 固有の罠 (= Windows reserved name、
+trailing space/dot、UNC、null byte) を一括検証する。
+
+セキュリティ上の責務は本モジュールに集約する (= File API endpoint 各位置で
+個別に検証しない、SSOT 原則)。
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from urllib.parse import unquote
+
+from ...exceptions import PathTraversalError
+
+_CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f]")
+"""null byte 含む ASCII control char (\\x00-\\x1f)。
+
+path injection 防御のため、URL decode 後の文字列にこれが残っていれば拒否。
+``\\t`` ``\\n`` ``\\r`` も含まれる (= path として正当な用途がない)。
+"""
+
+_WIN_DRIVE_RE = re.compile(r"^[A-Za-z]:")
+"""Windows ドライブ指定 (= ``C:`` や ``c:``) の検出。"""
+
+_WIN_RESERVED_NAMES = frozenset(
+    {
+        "con",
+        "prn",
+        "aux",
+        "nul",
+        *(f"com{i}" for i in range(0, 10)),
+        *(f"lpt{i}" for i in range(0, 10)),
+    }
+)
+"""Windows 予約デバイス名 (case-insensitive で判定)。
+
+Microsoft 公式仕様 (= "Naming a File"、CON / PRN / AUX / NUL / COM0-COM9 /
+LPT0-LPT9) に準拠。Linux / macOS でも cross-platform portability を維持
+するため拒否。``CON.flw.json`` のような拡張子付きも、basename 部分が
+予約名なら全 OS で拒否される (= Windows ではこれらは reserved file として
+アクセス不能)。``COM10`` 以降は予約名ではない。
+"""
+
+
+def resolve_workspace_path(workspace_root: Path, raw: str) -> Path:
+    """``raw`` (URL encoded relative path) を ``workspace_root`` 配下に解決する。
+
+    呼び出し側との契約:
+        * ``raw`` は **単段 URL encoded** path を想定 (= REST query param
+          ``?path=`` から取り出した文字列)。本関数で ``urllib.parse.unquote`` を
+          1 回適用する。
+        * **二重 encoded** (例: ``%252e%252e``) は意図的に decode せず、リテラル
+          ``%2e`` として扱う (= reverse proxy 等で 2 段 decode される構成は
+          File API 実装側の責務として扱わない)。
+        * FastAPI ``Request.query_params["path"]`` は既に 1 段 decode 済の値を
+          返すため、Starlette の挙動 (= ``%2F`` を ``/`` に展開する) と本関数の
+          unquote が二重適用される懸念は **冪等の範囲内** (= リテラル ``%2F`` を
+          含まない通常 path では影響なし)。File API 実装時にフレームワークの
+          decode 挙動を確認すること。
+        * 本関数は I/O を行わない (= TOCTOU race の対象外)。File API 側で
+          ``resolve_workspace_path`` 通過後の path に対して ``open`` / ``stat``
+          する間の symlink 差し替えは別途扱う。
+
+    Args:
+        workspace_root: ``--workspace=PATH`` で指定された絶対 path。本関数内部で
+            ``resolve(strict=False)`` する。
+        raw: 単段 URL encoded 相対 path (POSIX 形式、``/`` 区切り限定)。
+
+    Returns:
+        絶対 ``Path``。存在しない path も resolve 可能 (= ``strict=False``)。
+
+    Raises:
+        PathTraversalError: 以下のいずれか:
+            * null byte / ASCII control char を含む
+            * backslash (``\\``) を含む (POSIX 形式限定の API)
+            * 絶対 path (``/`` 始まり) または Windows ドライブ (``C:`` 等)
+            * 単体 ``..`` (= root の親に出る、resolve 前の fail-fast)
+            * Windows 予約名 (CON / PRN / AUX / NUL / COM0-9 / LPT0-9、
+              case-insensitive、拡張子付き含む)
+            * 各セグメントが trailing space / dot で終わる (Windows トリミング
+              挙動回避)
+            * resolve 後 ``workspace_root`` 配下から外れる
+
+            File API 側で 4xx response を返す際は **エラーメッセージに利用者の
+            decoded 入力を含めない** こと (log injection / 情報漏洩の多層防御)。
+    """
+    decoded = unquote(raw)
+
+    # Step 1: null byte / control char 拒否
+    # backslash 検査より先に置く理由 — control char は injection の最も危険な
+    # ベクタで、後続のメッセージや FS 操作に到達する前に最初に弾く。
+    if _CONTROL_CHAR_RE.search(decoded):
+        raise PathTraversalError("Path contains control characters or null byte")
+
+    # Step 2: backslash 拒否 (POSIX path 形式限定の API)
+    # UNC ``\\server\share`` や Windows-style ``\Windows\System32`` を同時に弾く。
+    if "\\" in decoded:
+        raise PathTraversalError("Backslash not allowed in workspace path; use forward slash")
+
+    # Step 3: 絶対 path / Windows ドライブ拒否
+    if decoded.startswith("/"):
+        raise PathTraversalError("Absolute path not allowed")
+    if _WIN_DRIVE_RE.match(decoded):
+        raise PathTraversalError("Drive-qualified path not allowed")
+
+    # Step 4: 単体 ``..`` の fail-fast 拒否
+    # 安全性は Step 6/7 (resolve + containment check) で十分担保されているが、
+    # ``raw == ".."`` の典型ケースで早期に明確なエラーメッセージを返すための
+    # 保険。``.strip()`` で先頭/末尾の whitespace のみ除去 (= ``"  ..  "`` も
+    # ここで拾う)。``foo/..`` のような compound は Step 6/7 で扱う。
+    if decoded.strip() == "..":
+        raise PathTraversalError("Parent escape not allowed")
+
+    # Step 5: 各セグメント検証 (Windows 予約名 + trailing space/dot)
+    # ``.`` ``..`` ``""`` セグメントは通常 path 構成要素なので skip、resolve +
+    # containment check で扱う。
+    for seg in decoded.split("/"):
+        if seg in ("", ".", ".."):
+            continue
+        if seg.endswith((" ", ".")):
+            raise PathTraversalError(f"Path segment with trailing space or dot: {seg!r}")
+        # 拡張子前の base 部分のみで予約名判定 (= ``CON.flw.json`` も拒否)。
+        base = seg.split(".", 1)[0].lower()
+        if base in _WIN_RESERVED_NAMES:
+            raise PathTraversalError(f"Windows reserved name: {seg!r}")
+
+    # Step 6: resolve under workspace_root
+    # ``strict=False`` で存在しない path も resolve、symlink は辿る。
+    root_resolved = workspace_root.resolve(strict=False)
+    candidate = (root_resolved / decoded).resolve(strict=False)
+
+    # Step 7: containment check
+    # symlink 経由での root 外脱出はここで弾かれる (resolve が symlink を辿るため)。
+    try:
+        candidate.relative_to(root_resolved)
+    except ValueError as e:
+        raise PathTraversalError(f"Path escapes workspace root: {decoded!r}") from e
+
+    return candidate

flode/server/settings.py

@@ -0,0 +1,42 @@
+"""サーバ設定 (ADR-0011 §(6) / ADR-0041 §3、v0.21.0 で legacy ``model_dir`` を削除)。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Settings:
+    """``create_app`` に渡す設定。
+
+    Attributes:
+        workspace_root: File API ``/api/v1/files/*`` のルートディレクトリ
+            (ADR-0041 §3、v0.15.0 新設、v0.21.0 で必須化)。``--workspace=PATH``
+            CLI 引数または ``Settings(workspace_root=...)`` 直接指定で設定。
+        scope_batch_size: WebSocket での Scope データ送信のバッチサイズ
+            (default 100、ADR-0011 §(2))。
+        max_concurrent: 同時実行可能なシミュレーション数 (default 4)。
+        allow_origins: CORS 許可オリジン (default 空 = CORS 無効)。
+            Frontend 別ホスト開発時に opt-in。
+        library_paths: ``.flwlib.json`` のロード対象 path リスト (ADR-0029、v0.11.1)。
+            ファイル / ディレクトリのいずれも可 (ディレクトリの場合は ``*.flwlib.json``
+            を再帰的に検索する) 。空リスト + ``bundle_builtin_libraries=True`` だけでも
+            組み込み ``std`` が利用可能になる。
+        bundle_builtin_libraries: 組み込み ``flode/libraries/std.flwlib.json`` を
+            自動的に library registry に追加するか (default ``True``、ADR-0029 §LOC-A)。
+        python_blocks_allowed: ``PythonFunction`` の実行可否 (SPEC-0023 / ADR-0073 hard gate)。
+            ``create_app`` がプロセス policy に適用する。CLI は bind host とフラグから
+            決めた値を入れる (loopback → True、非 loopback はフラグ必須)。``create_app`` を
+            直接使う埋め込み利用者は **公開 bind なら必ず False にする** こと。
+        python_blocks_reason: 拒否理由 (エラーメッセージに埋め込む、``allowed=False`` 時のみ)。
+    """
+
+    workspace_root: Path
+    scope_batch_size: int = 100
+    max_concurrent: int = 4
+    allow_origins: list[str] = field(default_factory=list)
+    library_paths: list[Path] = field(default_factory=list)
+    bundle_builtin_libraries: bool = True
+    python_blocks_allowed: bool = True
+    python_blocks_reason: str = ""

flode/server/static/.app-version

@@ -0,0 +1 @@
+0.60.3