diff --git a/.env.example b/.env.example index fec147dd6..f320c9108 100644 --- a/.env.example +++ b/.env.example @@ -127,6 +127,13 @@ ENABLE_GIT_INTEGRATION=true # Enable file upload handling (including archives) ENABLE_FILE_UPLOADS=true +# Extra upload types, agentic mode (comma-separated, e.g. .pdf,.png). Empty keeps +# text-only uploads. Matching files are saved under UPLOAD_SAVE_DIR (relative to the +# current working directory, always inside APPROVED_DIRECTORY) and Claude is told the +# path instead of receiving inlined text. +UPLOAD_SAVE_EXTENSIONS= +UPLOAD_SAVE_DIR=.telegram-uploads + # Enable quick action buttons (context-aware actions) ENABLE_QUICK_ACTIONS=true diff --git a/CHANGELOG.md b/CHANGELOG.md index 874799ca6..7fcee649a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **The `review` check no longer goes red when the reviewer runs out of turns**: exhausting `--max-turns` is not a graceful stop — the action exits with no output, so the check fails and reads like the pull request is broken, which is what happened on #236 once its diff reached thirteen files. The narrower prompt above is the fix; the ceiling also moves from 40 to 80 for headroom ### Added +- **Opt-in binary uploads (`UPLOAD_SAVE_EXTENSIONS`, `UPLOAD_SAVE_DIR`)**: a PDF sent to the bot was refused twice over — `.pdf` is not in the security validator's upload allowlist, and the agentic document handler only accepts UTF-8 text it can inline into the prompt. Extensions listed in `UPLOAD_SAVE_EXTENSIONS` are now accepted by the validator and, in agentic mode, saved under `UPLOAD_SAVE_DIR` (default `.telegram-uploads`, relative to the current working directory) as `_`; Claude is given the saved path instead of the content. The path is resolved and refused if it falls outside `APPROVED_DIRECTORY`, and `UPLOAD_SAVE_DIR` must be relative without `..`. The default is empty, so behaviour is unchanged unless configured. Classic mode is unchanged - **Blocked tool calls are reported to the user**: `ResultMessage.permission_denials` is now surfaced as a footer line listing what was refused and its most identifying argument, e.g. `🚫 2 tool calls were blocked: Write(/etc/hosts), Bash(cd /)`. This bot generates those denials itself — every `APPROVED_DIRECTORY` rejection, every Bash boundary violation, every Deny on an interactive approval prompt — and until now the only account of them a user saw was Claude's own narration of what it thought had happened, which is not authoritative. The line appears on successful runs too, since a denial does not by itself end a run - **`stop_reason`, `terminal_reason` and `errors` on `ClaudeResponse`**: the remaining stop-reason fields the 0.2 SDK added are captured and written to the structlog event for any run that did not end cleanly, so the reason is in the logs even where it is not worth showing in Telegram. They are not persisted yet; that is a `claude_interactions` schema change diff --git a/CLAUDE.md b/CLAUDE.md index c7b24d168..0ae9e6825 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -102,6 +102,8 @@ Settings loaded from environment variables via Pydantic Settings. Required: `TEL Agentic platform settings: `AGENTIC_MODE` (default true), `ENABLE_API_SERVER`, `API_SERVER_PORT` (default 8080), `GITHUB_WEBHOOK_SECRET`, `WEBHOOK_API_SECRET`, `ENABLE_SCHEDULER`, `NOTIFICATION_CHAT_IDS`. +Uploads: `ENABLE_FILE_UPLOADS` (default true), `UPLOAD_SAVE_EXTENSIONS` (default empty; extra extensions such as `.pdf` that agentic mode saves to `UPLOAD_SAVE_DIR`, default `.telegram-uploads`, inside `APPROVED_DIRECTORY` and passes to Claude as a path). + Security relaxation (trusted environments only): `DISABLE_SECURITY_PATTERNS` (default false), `DISABLE_TOOL_VALIDATION` (default false). Interactive tool approval: `INTERACTIVE_TOOL_APPROVAL` (default false), `INTERACTIVE_TOOL_APPROVAL_TOOLS` (default `Bash,Write,Edit`), `INTERACTIVE_TOOL_APPROVAL_TIMEOUT_SECONDS` (default 60), `INTERACTIVE_TOOL_APPROVAL_TIMEOUT_ACTION` (default `deny`). diff --git a/docs/configuration.md b/docs/configuration.md index ecd91207f..340b03bf7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -147,6 +147,13 @@ ENABLE_GIT_INTEGRATION=true # Enable file upload handling ENABLE_FILE_UPLOADS=true +# Extra upload types, agentic mode (comma-separated, e.g. .pdf,.png). Empty keeps +# text-only uploads. Matching files are saved under UPLOAD_SAVE_DIR (relative to the +# current working directory, always inside APPROVED_DIRECTORY) and Claude is told the +# path instead of receiving inlined text. +UPLOAD_SAVE_EXTENSIONS= +UPLOAD_SAVE_DIR=.telegram-uploads + # Enable quick action buttons (classic mode) ENABLE_QUICK_ACTIONS=true diff --git a/src/bot/orchestrator.py b/src/bot/orchestrator.py index 5801772e5..d03499a79 100644 --- a/src/bot/orchestrator.py +++ b/src/bot/orchestrator.py @@ -1264,7 +1264,40 @@ async def agentic_document( file_handler = features.get_file_handler() if features else None prompt: Optional[str] = None - if file_handler: + # Opted-in binary types (UPLOAD_SAVE_EXTENSIONS): save to disk, pass the path + ext = Path(document.file_name or "").suffix.lower() + if ext and ext in self.settings.upload_save_extensions: + from .utils.uploads import resolve_upload_path + + work_dir = Path( + context.user_data.get( + "current_directory", self.settings.approved_directory + ) + ) + try: + dest = resolve_upload_path( + work_dir, + self.settings.upload_save_dir, + self.settings.approved_directory, + document.file_name, + ) + dest.parent.mkdir(parents=True, exist_ok=True) + file = await document.get_file() + await file.download_to_drive(str(dest)) + except Exception as e: + logger.warning("Saving upload failed", error=str(e)) + await progress_msg.edit_text(f"Could not save the file: {e}") + return + logger.info("Saved upload", user_id=user_id, path=str(dest)) + caption = update.message.caption or "Please review this file:" + prompt = ( + f"{caption}\n\nThe user uploaded `{document.file_name}` " + f"({document.file_size} bytes). It was saved to `{dest}`. " + "Open it from there with suitable tools." + ) + file_handler = None + + if file_handler and prompt is None: try: processed_file = await file_handler.handle_document_upload( document, @@ -1275,7 +1308,7 @@ async def agentic_document( except Exception: file_handler = None - if not file_handler: + if not file_handler and prompt is None: file = await document.get_file() file_bytes = await file.download_as_bytearray() try: diff --git a/src/bot/utils/uploads.py b/src/bot/utils/uploads.py new file mode 100644 index 000000000..8987c77c6 --- /dev/null +++ b/src/bot/utils/uploads.py @@ -0,0 +1,34 @@ +"""Save opted-in binary uploads (UPLOAD_SAVE_EXTENSIONS) to disk for Claude to open.""" + +import re +from datetime import UTC, datetime +from pathlib import Path +from typing import Optional + +_UNSAFE_CHARS = re.compile(r"[^A-Za-z0-9._-]+") + + +def safe_upload_name(file_name: Optional[str], now: Optional[datetime] = None) -> str: + """Return a timestamped file name with no directory parts or unusual characters.""" + base = Path(file_name or "upload").name # drop any directory components + base = _UNSAFE_CHARS.sub("_", base).lstrip(".") or "upload" + stamp = (now or datetime.now(UTC)).strftime("%Y%m%d-%H%M%S") + return f"{stamp}_{base[:150]}" + + +def resolve_upload_path( + working_directory: Path, + save_dir: str, + approved_directory: Path, + file_name: Optional[str], + now: Optional[datetime] = None, +) -> Path: + """Path for a saved upload under ``working_directory/save_dir``. + + Raises ValueError if the result would fall outside ``approved_directory``. + """ + target_dir = (Path(working_directory) / save_dir).resolve() + approved = Path(approved_directory).resolve() + if target_dir != approved and approved not in target_dir.parents: + raise ValueError("Upload directory is outside the approved directory") + return target_dir / safe_upload_name(file_name, now) diff --git a/src/config/settings.py b/src/config/settings.py index 9802ada43..bfb4a9076 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -9,6 +9,7 @@ """ import json +import re from pathlib import Path from typing import Any, List, Literal, Optional @@ -219,6 +220,21 @@ class Settings(BaseSettings): ) enable_git_integration: bool = Field(True, description="Enable git commands") enable_file_uploads: bool = Field(True, description="Enable file upload handling") + upload_save_extensions: List[str] = Field( + default=[], + description=( + "Extra file extensions (for example .pdf) accepted as uploads in agentic " + "mode. Such files are saved to UPLOAD_SAVE_DIR and Claude is given the " + "path instead of inlined text. Empty keeps text-only uploads." + ), + ) + upload_save_dir: str = Field( + ".telegram-uploads", + description=( + "Directory for saved uploads, relative to the current working directory " + "and kept inside APPROVED_DIRECTORY" + ), + ) enable_voice_messages: bool = Field( True, description="Enable voice message transcription" ) @@ -383,6 +399,34 @@ def parse_claude_allowed_tools(cls, v: Any) -> Optional[List[str]]: return [str(tool) for tool in v] return v # type: ignore[no-any-return] + @field_validator("upload_save_extensions", mode="before") + @classmethod + def parse_upload_save_extensions(cls, v: Any) -> List[str]: + """Parse comma-separated extensions into lowercase '.ext' form.""" + if v is None: + return [] + items = v.split(",") if isinstance(v, str) else list(v) + exts = [] + for item in items: + ext = str(item).strip().lower() + if not ext: + continue + if not ext.startswith("."): + ext = "." + ext + if not re.fullmatch(r"\.[a-z0-9]{1,10}", ext): + raise ValueError(f"Invalid upload extension: {item!r}") + exts.append(ext) + return exts + + @field_validator("upload_save_dir") + @classmethod + def validate_upload_save_dir(cls, v: str) -> str: + """Require a relative path without '..' components.""" + p = Path(v) + if not v.strip() or p.is_absolute() or ".." in p.parts: + raise ValueError("UPLOAD_SAVE_DIR must be a relative path without '..'") + return v + @field_validator("approved_directory") @classmethod def validate_approved_directory(cls, v: Any) -> Path: diff --git a/src/main.py b/src/main.py index 5600da336..3110e7349 100644 --- a/src/main.py +++ b/src/main.py @@ -130,6 +130,7 @@ async def create_application(config: Settings) -> Dict[str, Any]: security_validator = SecurityValidator( config.approved_directory, disable_security_patterns=config.disable_security_patterns, + extra_allowed_extensions=config.upload_save_extensions, ) rate_limiter = RateLimiter(config) diff --git a/src/security/validators.py b/src/security/validators.py index 381ba321d..f07b6f5a9 100644 --- a/src/security/validators.py +++ b/src/security/validators.py @@ -9,7 +9,7 @@ import re from pathlib import Path -from typing import Any, Dict, List, Optional, Tuple +from typing import Any, Dict, Iterable, List, Optional, Tuple import structlog @@ -132,11 +132,21 @@ class SecurityValidator: ] def __init__( - self, approved_directory: Path, disable_security_patterns: bool = False + self, + approved_directory: Path, + disable_security_patterns: bool = False, + extra_allowed_extensions: Optional[Iterable[str]] = None, ): - """Initialize validator with approved directory.""" + """Initialize validator with approved directory. + + ``extra_allowed_extensions`` (from UPLOAD_SAVE_EXTENSIONS) are accepted by + ``validate_filename`` in addition to ``ALLOWED_EXTENSIONS``. + """ self.approved_directory = approved_directory.resolve() self.disable_security_patterns = disable_security_patterns + self.allowed_extensions = set(self.ALLOWED_EXTENSIONS) | { + e.lower() for e in (extra_allowed_extensions or []) + } logger.info( "Security validator initialized", approved_directory=str(self.approved_directory), @@ -257,7 +267,7 @@ def validate_filename(self, filename: str) -> Tuple[bool, Optional[str]]: path_obj = Path(filename) ext = path_obj.suffix.lower() - if ext and ext not in self.ALLOWED_EXTENSIONS: + if ext and ext not in self.allowed_extensions: logger.warning( "File extension not allowed", filename=filename, extension=ext ) @@ -380,7 +390,7 @@ def get_security_summary(self) -> Dict[str, Any]: """Get summary of security validation rules.""" return { "approved_directory": str(self.approved_directory), - "allowed_extensions": sorted(list(self.ALLOWED_EXTENSIONS)), + "allowed_extensions": sorted(self.allowed_extensions), "forbidden_filenames": sorted(list(self.FORBIDDEN_FILENAMES)), "dangerous_patterns_count": len(self.DANGEROUS_PATTERNS), "dangerous_file_patterns_count": len(self.DANGEROUS_FILE_PATTERNS), diff --git a/tests/unit/test_bot/test_uploads.py b/tests/unit/test_bot/test_uploads.py new file mode 100644 index 000000000..9ab463332 --- /dev/null +++ b/tests/unit/test_bot/test_uploads.py @@ -0,0 +1,53 @@ +"""Tests for saving opted-in binary uploads (UPLOAD_SAVE_EXTENSIONS).""" + +from datetime import UTC, datetime +from pathlib import Path + +import pytest + +from src.bot.utils.uploads import resolve_upload_path, safe_upload_name + +NOW = datetime(2026, 11, 2, 9, 30, 5, tzinfo=UTC) + + +def test_safe_upload_name_timestamps_and_keeps_simple_names() -> None: + assert safe_upload_name("paper.pdf", NOW) == "20261102-093005_paper.pdf" + + +@pytest.mark.parametrize( + "name, expected", + [ + ("../../etc/passwd.pdf", "20261102-093005_passwd.pdf"), + ("/abs/dir/x.pdf", "20261102-093005_x.pdf"), + ("my paper (v2).pdf", "20261102-093005_my_paper_v2_.pdf"), + (".hidden.pdf", "20261102-093005_hidden.pdf"), + ("", "20261102-093005_upload"), + (None, "20261102-093005_upload"), + ], +) +def test_safe_upload_name_strips_unsafe_parts(name: str, expected: str) -> None: + assert safe_upload_name(name, NOW) == expected + + +def test_resolve_upload_path_inside_working_directory(tmp_path: Path) -> None: + work = tmp_path / "proj" + work.mkdir() + p = resolve_upload_path(work, ".telegram-uploads", tmp_path, "a.pdf", NOW) + assert p == (work / ".telegram-uploads" / "20261102-093005_a.pdf").resolve() + + +def test_resolve_upload_path_rejects_dir_outside_approved(tmp_path: Path) -> None: + approved = tmp_path / "approved" + approved.mkdir() + outside = tmp_path / "elsewhere" + outside.mkdir() + with pytest.raises(ValueError): + resolve_upload_path(outside, "uploads", approved, "a.pdf", NOW) + + +def test_resolve_upload_path_rejects_symlink_escape(tmp_path: Path) -> None: + approved = tmp_path / "approved" + approved.mkdir() + (approved / "link").symlink_to(tmp_path) + with pytest.raises(ValueError): + resolve_upload_path(approved, "link", approved / "sub", "a.pdf", NOW) diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py index 2f0dcd9ee..db894c2e4 100644 --- a/tests/unit/test_config.py +++ b/tests/unit/test_config.py @@ -698,3 +698,30 @@ def test_configuration_error_handling(): "APPROVED_DIRECTORY", ]: os.environ.pop(key, None) + + +def test_upload_save_extensions_default_empty(tmp_path): + """Binary uploads are off unless configured.""" + settings = create_test_config(approved_directory=str(tmp_path)) + assert settings.upload_save_extensions == [] + assert settings.upload_save_dir == ".telegram-uploads" + + +def test_upload_save_extensions_parsing(tmp_path): + """Comma-separated extensions are normalised to lowercase '.ext'.""" + settings = create_test_config( + approved_directory=str(tmp_path), upload_save_extensions=" .PDF, png ,,cif" + ) + assert settings.upload_save_extensions == [".pdf", ".png", ".cif"] + + +@pytest.mark.parametrize("bad", [".p/df", "../x", ".toolongextension"]) +def test_upload_save_extensions_rejects_invalid(tmp_path, bad): + with pytest.raises(ValueError): + create_test_config(approved_directory=str(tmp_path), upload_save_extensions=bad) + + +@pytest.mark.parametrize("bad", ["/abs/uploads", "../uploads", "a/../../b", " "]) +def test_upload_save_dir_rejects_unsafe(tmp_path, bad): + with pytest.raises(ValueError): + create_test_config(approved_directory=str(tmp_path), upload_save_dir=bad) diff --git a/tests/unit/test_orchestrator.py b/tests/unit/test_orchestrator.py index 1902f1898..88339645a 100644 --- a/tests/unit/test_orchestrator.py +++ b/tests/unit/test_orchestrator.py @@ -1166,3 +1166,74 @@ async def test_agentic_text_does_not_say_stopped_twice(agentic_settings, deps): assert "No final response. Tools used: Bash, Read" in body assert "turn limit reached after 10 turns" in body assert body.count("⚠️") == 1 + + +async def test_agentic_document_saves_opted_in_binary_and_passes_path(tmp_dir, deps): + """With UPLOAD_SAVE_EXTENSIONS=.pdf a PDF is saved to disk and Claude gets the path.""" + settings = create_test_config( + approved_directory=str(tmp_dir), + agentic_mode=True, + upload_save_extensions=".pdf", + ) + orchestrator = MessageOrchestrator(settings, deps) + + async def fake_download(path: str) -> None: + Path(path).write_bytes(b"%PDF-1.7 test") + + tg_file = MagicMock() + tg_file.download_to_drive = AsyncMock(side_effect=fake_download) + tg_file.download_as_bytearray = AsyncMock() + + update = MagicMock() + update.effective_user.id = 123 + update.message.document.file_name = "../paper.pdf" + update.message.document.file_size = 1024 + update.message.document.get_file = AsyncMock(return_value=tg_file) + update.message.caption = "Read this" + update.message.chat.send_action = AsyncMock() + progress = MagicMock() + progress.edit_text = AsyncMock() + progress.delete = AsyncMock() + update.message.reply_text = AsyncMock(return_value=progress) + + claude = MagicMock() + claude.run_command = AsyncMock(side_effect=RuntimeError("stop after prompt")) + context = MagicMock() + context.bot_data = {"security_validator": None, "claude_integration": claude} + context.user_data = {} + + await orchestrator.agentic_document(update, context) + + saved = list((tmp_dir / ".telegram-uploads").iterdir()) + assert len(saved) == 1 and saved[0].name.endswith("_paper.pdf") + assert saved[0].read_bytes() == b"%PDF-1.7 test" + tg_file.download_as_bytearray.assert_not_called() + prompt = claude.run_command.call_args.kwargs["prompt"] + assert prompt.startswith("Read this") + assert str(saved[0]) in prompt + + +async def test_agentic_document_binary_not_saved_by_default(agentic_settings, deps): + """Without UPLOAD_SAVE_EXTENSIONS nothing is written to disk.""" + orchestrator = MessageOrchestrator(agentic_settings, deps) + tg_file = MagicMock() + tg_file.download_to_drive = AsyncMock() + tg_file.download_as_bytearray = AsyncMock(return_value=bytearray(b"\xff\xfe\x00")) + + update = MagicMock() + update.effective_user.id = 123 + update.message.document.file_name = "paper.pdf" + update.message.document.file_size = 1024 + update.message.document.get_file = AsyncMock(return_value=tg_file) + update.message.chat.send_action = AsyncMock() + progress = MagicMock() + progress.edit_text = AsyncMock() + update.message.reply_text = AsyncMock(return_value=progress) + context = MagicMock() + context.bot_data = {"security_validator": None} + context.user_data = {} + + await orchestrator.agentic_document(update, context) + + tg_file.download_to_drive.assert_not_called() + assert "Unsupported file format" in progress.edit_text.call_args.args[0] diff --git a/tests/unit/test_security/test_validators.py b/tests/unit/test_security/test_validators.py index a15f5c31a..579bf6214 100644 --- a/tests/unit/test_security/test_validators.py +++ b/tests/unit/test_security/test_validators.py @@ -349,3 +349,19 @@ def test_whitespace_handling(self, validator): assert " " not in sanitized # No double spaces assert not sanitized.startswith(" ") # No leading space assert not sanitized.endswith(" ") # No trailing space + + +def test_pdf_rejected_by_default(tmp_path): + """.pdf is not in the built-in upload allowlist.""" + validator = SecurityValidator(tmp_path) + valid, error = validator.validate_filename("paper.pdf") + assert not valid + assert ".pdf" in error + + +def test_extra_allowed_extensions_accept_pdf(tmp_path): + """UPLOAD_SAVE_EXTENSIONS extends the allowlist without relaxing other checks.""" + validator = SecurityValidator(tmp_path, extra_allowed_extensions=[".pdf"]) + assert validator.validate_filename("paper.pdf") == (True, None) + assert not validator.validate_filename(".hidden.pdf")[0] + assert not validator.validate_filename("tool.exe")[0]