security(gateway): add path validation and security comments to media store

- Add validate_path() — Core must call before reading any Attachment.path
- Canonicalize resolves symlinks and '..' to prevent path traversal
- Sanitize ext in store_media() to strip path separators
- Document security considerations learned from OpenClaw CVE-2026-25475
- Explain why our design is safe: UUID filenames, Gateway-only path generation,
  agent never controls paths, TTL bounds exposure window

Author: Kiro

gateway/src/media_store.rs

@@ -1,5 +1,28 @@
-use std::path::{Path, PathBuf};
-use std::time::{Duration, Instant};
+//! Media Store — co-locate filesystem mode
+//!
+//! Gateway downloads media from platform APIs (LINE, Telegram, Feishu) and writes
+//! to `~/.openab/media/inbound/<uuid>.<ext>`. Core reads from the same path.
+//!
+//! # Security Considerations (learned from OpenClaw CVE-2026-25475)
+//!
+//! 1. **Path is Gateway-generated only** — filenames are UUID v4, never derived
+//!    from user input or agent output. This prevents path traversal attacks.
+//!
+//! 2. **Core must validate paths before reading** — use `validate_path()` to
+//!    ensure the path is within the allowed media directory. This guards against
+//!    a compromised Gateway or malformed event injecting `../../etc/passwd`.
+//!
+//! 3. **Agent cannot control paths** — the `Attachment.path` field flows from
+//!    Gateway → Core only. Agent subprocess never sees or influences it.
+//!
+//! 4. **TTL eviction** — files are deleted after 2 minutes. Even if a path leaks,
+//!    the window of exposure is bounded.
+//!
+//! 5. **No symlink following** — `validate_path()` uses `canonicalize()` to resolve
+//!    symlinks before checking the prefix, preventing symlink-based escapes.
+
+use std::path::PathBuf;
+use std::time::Duration;
 use tokio::fs;
 use tracing::{info, warn};
 
@@ -16,12 +39,17 @@ pub fn media_dir() -> PathBuf {
 }
 
 /// Write media bytes to disk, return the absolute path.
+///
+/// Filenames are always `<uuid>.<ext>` — never user-supplied names.
+/// This eliminates path traversal via crafted filenames.
 pub async fn store_media(data: &[u8], ext: &str) -> Option<String> {
     let dir = media_dir();
     if let Err(e) = fs::create_dir_all(&dir).await {
         warn!(err = %e, "failed to create media dir");
         return None;
     }
+    // Sanitize ext: strip any path separators or dots that could escape
+    let ext = ext.trim_start_matches('.').replace(['/', '\\', '.'], "");
     let filename = format!("{}.{}", uuid::Uuid::new_v4(), ext);
     let path = dir.join(&filename);
     if let Err(e) = fs::write(&path, data).await {
@@ -32,6 +60,25 @@ pub async fn store_media(data: &[u8], ext: &str) -> Option<String> {
     Some(path.to_string_lossy().into_owned())
 }
 
+/// Validate that a path is within the allowed media directory.
+///
+/// Core MUST call this before reading any file from `Attachment.path`.
+/// Guards against path traversal (e.g. `../../etc/passwd`) and symlink escapes.
+///
+/// Returns the canonicalized path if valid, None otherwise.
+pub fn validate_path(path: &str) -> Option<PathBuf> {
+    let path = PathBuf::from(path);
+    // Canonicalize resolves symlinks and `..` components
+    let canonical = path.canonicalize().ok()?;
+    let allowed_dir = media_dir().canonicalize().ok()?;
+    if canonical.starts_with(&allowed_dir) {
+        Some(canonical)
+    } else {
+        warn!(path = %canonical.display(), "media path outside allowed directory — rejecting");
+        None
+    }
+}
+
 /// Spawn a background task that removes files older than TTL.
 pub fn spawn_cleanup_task() {
     tokio::spawn(async {