Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<UTC timestamp>_<sanitised name>`; 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

Expand Down
2 changes: 2 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Expand Down
7 changes: 7 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
37 changes: 35 additions & 2 deletions src/bot/orchestrator.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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:
Expand Down
34 changes: 34 additions & 0 deletions src/bot/utils/uploads.py
Original file line number Diff line number Diff line change
@@ -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)
44 changes: 44 additions & 0 deletions src/config/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"""

import json
import re
from pathlib import Path
from typing import Any, List, Literal, Optional

Expand Down Expand Up @@ -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"
)
Expand Down Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions src/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
20 changes: 15 additions & 5 deletions src/security/validators.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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
)
Expand Down Expand Up @@ -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),
Expand Down
53 changes: 53 additions & 0 deletions tests/unit/test_bot/test_uploads.py
Original file line number Diff line number Diff line change
@@ -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)
27 changes: 27 additions & 0 deletions tests/unit/test_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading