security: comprehensive hardening for external deployment

.cursor/rules/pull-requests.mdc

@@ -0,0 +1,10 @@
+---
+description: Open pull requests for code changes; integrate via PR review
+alwaysApply: true
+---
+
+# Pull requests
+
+- Work on a branch. After substantive changes, open a pull request to the default branch (use `gh pr create` with a clear title and description when available).
+- Do not push feature work directly to `main` or the repository default branch unless the user explicitly requests a hotfix or direct push.
+- Integrate changes through the PR; that is the normal path for merging.

CLAUDE.md

@@ -0,0 +1,61 @@
+# nanobot — Claude Instructions
+
+## Auto-commit policy
+
+After making any substantial change, automatically commit without asking. Use conventional prefixes (`fix:`, `feat:`, `chore:`, `refactor:`).
+
+## Quick reference
+
+```bash
+# Run a single command
+nanobot agent -m "Hello"
+
+# Start the gateway (HTTP API + channels + cron)
+nanobot gateway --api-key <key>
+
+# Build Docker image (from ../fairy-bot-e2e/ for e2e testing)
+make build
+```
+
+## Gateway architecture
+
+`nanobot gateway` starts:
+1. An **aiohttp HTTP server** on port 18790 (`POST /agent/run` with bearer auth)
+2. The **agent loop** (`AgentLoop.run()`) — connects MCP servers, processes messages
+3. **Channel managers** (telegram relay, etc.)
+4. **CronService** + **HeartbeatService**
+
+All four run under `asyncio.gather`. If any raises an unhandled exception the entire gateway exits (restart policy: `unless-stopped`).
+
+The log line `"Gateway HTTP API listening on port 18790"` appears immediately after the HTTP server binds, before MCP init. This is the correct health signal — docker status `running` lags behind.
+
+## Cron jobs
+
+- Jobs are persisted to `~/.nanobot/cron/jobs.json`
+- `CronService` loads them at startup and runs them in-memory
+- When a job fires, `on_cron_job` calls `agent.process_direct()` with:
+  - **Session key**: `{channel}:{chat_id}` (the user's real session, so the agent has personality and history)
+  - **Message**: `[SCHEDULED REMINDER] A reminder you scheduled is now due. Deliver this message to the user in your own voice: {original_message}`
+- `every_seconds` is for recurring jobs only; use `at` with an ISO datetime for one-time reminders
+
+## Common crash causes in e2e
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| Gateway exits ~300ms after start | MCP host unreachable (e.g. `charlotte`) | Set `CHARLOTTE_MCP_URL=` in `.env.test` |
+| Gateway exits, telegram relay log shows `nanobot-coordinator` | Wrong coordinator hostname | Set `NANOBOT_COORDINATOR_URL=http://e2e-coordinator:8000` |
+| `NameError: cannot access free variable 'logger'` | `logger` imported inside `if verbose:` block but used outside | Import `from loguru import logger` before the `if verbose:` check in `gateway()` |
+| ConnectError on chat after container shows "running" | HTTP server not yet bound | Wait for log line `"Gateway HTTP API listening on port"` instead of sleeping |
+
+## E2E testing
+
+Tests live in `../fairy-bot-e2e/`. After nanobot changes:
+
+```bash
+cd ../fairy-bot-e2e
+make build   # rebuilds nanobot:latest
+make up      # restarts stack
+make test    # runs Playwright tests
+```
+
+Use `bot-helpers.ts` functions (`waitForBotHealthy`, `getContainerLogs`, etc.) — see `fairy-bot-e2e/CLAUDE.md` for the full reference.

docker-compose.yml

@@ -6,11 +6,13 @@ x-common-config: &common-config
     - ~/.nanobot:/home/nanobot/.nanobot
   cap_drop:
     - ALL
-  cap_add:
-    - SYS_ADMIN
-  security_opt:
-    - apparmor=unconfined
-    - seccomp=unconfined
+  # SYS_ADMIN + seccomp/apparmor unconfined only needed if exec sandbox=bwrap.
+  # Uncomment below lines if you enable tools.exec with sandbox: "bwrap":
+  #   cap_add:
+  #     - SYS_ADMIN
+  #   security_opt:
+  #     - apparmor=unconfined
+  #     - seccomp=unconfined
 
 services:
   nanobot-gateway:
@@ -19,7 +21,7 @@ services:
     command: ["gateway"]
     restart: unless-stopped
     ports:
-      - 18790:18790
+      - "127.0.0.1:18790:18790"
     deploy:
       resources:
         limits:

nanobot/agent/loop.py

@@ -6,6 +6,7 @@
 import dataclasses
 import json
 import os
+import re
 import time
 from contextlib import AsyncExitStack, nullcontext
 from pathlib import Path
@@ -29,6 +30,7 @@
 from nanobot.agent.tools.shell import ExecTool
 from nanobot.agent.tools.spawn import SpawnTool
 from nanobot.agent.tools.web import WebFetchTool, WebSearchTool
+from nanobot.agent.types import AgentResponse, PendingAction
 from nanobot.bus.events import InboundMessage, OutboundMessage
 from nanobot.command import CommandContext, CommandRouter, register_builtin_commands
 from nanobot.bus.queue import MessageBus
@@ -200,6 +202,10 @@ def __init__(
         )
         self._unified_session = unified_session
         self._running = False
+        self._scopes_fetched = False
+        self._confirmation_supported = False
+        self._pending_actions: list[PendingAction] = []
+        self._last_final_content: str = ""
         self._mcp_servers = mcp_servers or {}
         self._mcp_stacks: dict[str, AsyncExitStack] = {}
         self._mcp_connected = False
@@ -274,11 +280,61 @@ def _register_default_tools(self) -> None:
             self.tools.register(WebFetchTool(proxy=self.web_config.proxy))
         self.tools.register(MessageTool(send_callback=self.bus.publish_outbound))
         self.tools.register(SpawnTool(manager=self.subagents))
+        from nanobot.agent.tools.memory import SaveMemoryTool, UpdateBotIdentityTool, UpdateUserProfileTool
+        for cls in (UpdateBotIdentityTool, UpdateUserProfileTool, SaveMemoryTool):
+            self.tools.register(cls(workspace=self.workspace))
         if self.cron_service:
             self.tools.register(
                 CronTool(self.cron_service, default_timezone=self.context.timezone or "UTC")
             )
 
+    def sync_scoped_tools(
+        self,
+        google_scopes: list[str] | None = None,
+        x_scopes: list[str] | None = None,
+        github_scopes: list[str] | None = None,
+    ) -> None:
+        """Register/deregister Google, X, and GitHub tools based on granted OAuth scopes."""
+        from nanobot.agent.tools.scope_registry import (
+            ALL_SCOPED_TOOL_NAMES,
+            get_tools_for_scopes,
+        )
+
+        desired = get_tools_for_scopes(google_scopes, x_scopes, github_scopes)
+        current_scoped = {
+            name for name in self.tools.tool_names if name in ALL_SCOPED_TOOL_NAMES
+        }
+
+        to_add = set(desired.keys()) - current_scoped
+        to_remove = current_scoped - set(desired.keys())
+
+        for name in to_remove:
+            self.tools.unregister(name)
+        if to_remove:
+            logger.info("Deregistered {} scoped tool(s): {}", len(to_remove), ", ".join(sorted(to_remove)))
+
+        for name in to_add:
+            self.tools.register(desired[name]())
+        if to_add:
+            logger.info("Registered {} scoped tool(s): {}", len(to_add), ", ".join(sorted(to_add)))
+
+        if not to_add and not to_remove:
+            logger.debug("Scoped tools unchanged ({} active)", len(current_scoped))
+
+    async def _fetch_and_sync_scopes(self) -> None:
+        """Fetch current OAuth scopes from the coordinator and sync tools (once)."""
+        if self._scopes_fetched:
+            return
+        if not os.environ.get("BOT_ID") or not os.environ.get("COORDINATOR_URL"):
+            return
+        try:
+            from nanobot.coordinator.client import fetch_scopes
+            google_scopes, x_scopes, github_scopes = await fetch_scopes()
+            self.sync_scoped_tools(google_scopes, x_scopes, github_scopes)
+            self._scopes_fetched = True
+        except Exception as e:
+            logger.warning("Failed to fetch scopes from coordinator: {}", e)
+
     async def _connect_mcp(self) -> None:
         """Connect to configured MCP servers (one-time, lazy)."""
         if self._mcp_connected or self._mcp_connecting or not self._mcp_servers:
@@ -396,6 +452,21 @@ async def _drain_pending(*, limit: int = _MAX_INJECTIONS_PER_TURN) -> list[dict[
                 items.append({"role": "user", "content": merged})
             return items
 
+        async def _on_confirmation_needed(
+            tool_call_id: str, tool_name: str, arguments: dict,
+        ) -> PendingAction | None:
+            if not self._confirmation_supported:
+                return None
+            import uuid as _uuid
+            pa = PendingAction(
+                action_id=str(_uuid.uuid4()),
+                tool_call_id=tool_call_id,
+                tool_name=tool_name,
+                arguments=arguments,
+            )
+            self._pending_actions.append(pa)
+            return pa
+
         result = await self.runner.run(AgentRunSpec(
             initial_messages=initial_messages,
             tools=self.tools,
@@ -413,6 +484,7 @@ async def _drain_pending(*, limit: int = _MAX_INJECTIONS_PER_TURN) -> list[dict[
             progress_callback=on_progress,
             checkpoint_callback=_checkpoint,
             injection_callback=_drain_pending,
+            confirmation_callback=_on_confirmation_needed,
         ))
         self._last_usage = result.usage
         if result.stop_reason == "max_iterations":
@@ -424,6 +496,7 @@ async def _drain_pending(*, limit: int = _MAX_INJECTIONS_PER_TURN) -> list[dict[
     async def run(self) -> None:
         """Run the agent loop, dispatching messages as tasks to stay responsive to /stop."""
         self._running = True
+        await self._fetch_and_sync_scopes()
         await self._connect_mcp()
         logger.info("Agent loop started")
 
@@ -706,6 +779,8 @@ async def _bus_progress(content: str, *, tool_hint: bool = False) -> None:
         if final_content is None or not final_content.strip():
             final_content = EMPTY_FINAL_RESPONSE_MESSAGE
 
+        self._last_final_content = final_content
+
         self._save_turn(session, all_msgs, 1 + len(history))
         self._clear_runtime_checkpoint(session)
         self.sessions.save(session)
@@ -893,6 +968,19 @@ def _restore_runtime_checkpoint(self, session: Session) -> bool:
         self._clear_runtime_checkpoint(session)
         return True
 
+    async def consolidate_and_reset_session(self, session_key: str) -> bool:
+        """Consolidate memory for the given session, then clear it."""
+        session = self.sessions.get_or_create(session_key)
+        try:
+            await self.consolidator.maybe_consolidate_by_tokens(session)
+        except Exception:
+            logger.exception("Consolidation failed for {}", session_key)
+            return False
+        session.clear()
+        self.sessions.save(session)
+        self.sessions.invalidate(session_key)
+        return True
+
     async def process_direct(
         self,
         content: str,
@@ -902,14 +990,75 @@ async def process_direct(
         on_progress: Callable[[str], Awaitable[None]] | None = None,
         on_stream: Callable[[str], Awaitable[None]] | None = None,
         on_stream_end: Callable[..., Awaitable[None]] | None = None,
-    ) -> OutboundMessage | None:
-        """Process a message directly and return the outbound payload."""
+        on_message: Callable[[OutboundMessage], Awaitable[None]] | None = None,
+        on_stream_event: Callable[[dict], Awaitable[None]] | None = None,
+        confirmation_supported: bool = False,
+        timezone: str | None = None,
+    ) -> AgentResponse:
+        """Process a message directly (for CLI, HTTP gateway, or cron usage).
+
+        Args:
+            on_message: If provided, called for every MessageTool send.
+                Allows SSE streaming endpoints to capture intermediate bot
+                messages without registering a fake channel.
+            confirmation_supported: If True, tools with requires_confirmation
+                will queue PendingAction instead of executing.
+            on_stream_event: Callback for structured events (e.g. bot_name_updated).
+        """
+        self._confirmation_supported = confirmation_supported
+        self._pending_actions = []
+        await self._fetch_and_sync_scopes()
         await self._connect_mcp()
-        msg = InboundMessage(channel=channel, sender_id="user", chat_id=chat_id, content=content)
-        return await self._process_message(
-            msg,
-            session_key=session_key,
-            on_progress=on_progress,
-            on_stream=on_stream,
-            on_stream_end=on_stream_end,
-        )
+
+        original_cb: Callable[[OutboundMessage], Awaitable[None]] | None = None
+        mt = self.tools.get("message")
+        if on_message and isinstance(mt, MessageTool):
+            original_cb = mt._send_callback
+
+            async def _stream_callback(msg: OutboundMessage) -> None:
+                await on_message(msg)
+
+            mt.set_send_callback(_stream_callback)
+
+        from nanobot.agent.tools.memory import UpdateBotIdentityTool
+        identity_tool = self.tools.get("update_bot_identity")
+        old_stream_event = None
+        if isinstance(identity_tool, UpdateBotIdentityTool):
+            old_stream_event = identity_tool._on_stream_event
+            identity_tool._on_stream_event = on_stream_event
+
+        try:
+            msg = InboundMessage(channel=channel, sender_id="user", chat_id=chat_id, content=content)
+            response = await self._process_message(
+                msg,
+                session_key=session_key,
+                on_progress=on_progress,
+                on_stream=on_stream,
+                on_stream_end=on_stream_end,
+            )
+
+            if response is not None:
+                resolved_content = response.content
+            elif isinstance(mt, MessageTool) and mt._sent_in_turn:
+                if on_message:
+                    suppressed = self._last_final_content or ""
+                    follow_match = re.search(
+                        r"<follow[-_]ups>\s*.*?\s*</follow[-_]ups>",
+                        suppressed,
+                        re.DOTALL | re.IGNORECASE,
+                    )
+                    resolved_content = follow_match.group(0) if follow_match else ""
+                else:
+                    resolved_content = "\n\n".join(mt._sent_contents)
+            else:
+                resolved_content = ""
+
+            return AgentResponse(
+                content=resolved_content,
+                pending_actions=list(self._pending_actions),
+            )
+        finally:
+            if original_cb is not None and isinstance(mt, MessageTool):
+                mt.set_send_callback(original_cb)
+            if isinstance(identity_tool, UpdateBotIdentityTool):
+                identity_tool._on_stream_event = old_stream_event

nanobot/agent/runner.py

@@ -73,6 +73,7 @@ class AgentRunSpec:
     progress_callback: Any | None = None
     checkpoint_callback: Any | None = None
     injection_callback: Any | None = None
+    confirmation_callback: Any | None = None
 
 
 @dataclass(slots=True)
@@ -622,6 +623,29 @@ async def _run_tool(
                 "detail": prep_error.split(": ", 1)[-1][:120],
             }
             return prep_error + _HINT, event, RuntimeError(prep_error) if spec.fail_on_tool_error else None
+
+        resolved_tool = tool if tool is not None else spec.tools.get(tool_call.name)
+        if (
+            spec.confirmation_callback is not None
+            and resolved_tool is not None
+            and getattr(resolved_tool, "requires_confirmation", False)
+        ):
+            pending = await spec.confirmation_callback(
+                tool_call.id, tool_call.name, params
+            )
+            if pending is not None:
+                event = {
+                    "name": tool_call.name,
+                    "status": "pending_confirmation",
+                    "detail": "Queued for user confirmation",
+                }
+                return (
+                    "[This action requires user confirmation before it can be executed. "
+                    "The user has been notified and will approve or reject it.]",
+                    event,
+                    None,
+                )
+
         try:
             if tool is not None:
                 result = await tool.execute(**params)

nanobot/agent/tools/base.py

@@ -151,6 +151,11 @@ def parameters(self) -> dict[str, Any]:
         """JSON Schema for tool parameters."""
         ...
 
+    @property
+    def requires_confirmation(self) -> bool:
+        """Whether this tool requires user confirmation before execution."""
+        return False
+
     @property
     def read_only(self) -> bool:
         """Whether this tool is side-effect free and safe to parallelize."""