feat(im): add pending bind approvals and harden bind flow

Author: ChesterRa

docs/guide/im-bridge/telegram.md

@@ -106,10 +106,11 @@ New chats must be authorized before they can use the bot:
 2. Start a chat with the bot
 3. Send `/subscribe` — the bot replies with a one-time binding key:
    ```
-   /bind abc123xyz
+   abc123xyz
    ```
 4. **Authorize the chat** (choose one):
-   - **Web chat (recommended):** Copy the `/bind <key>` line and paste it in the CCCC Web chat — the foreman will complete the binding automatically
+   - **Web (recommended):** Open **CCCC Web → Settings → IM Bridge**, find it in **Pending Requests**, and click **Approve** (or paste the key in **Bind**)
+   - **Foreman-assisted:** If foreman is online, send the key to foreman and ask foreman to bind it
    - **CLI:** Run `cccc im bind --key <key>` on the server
 5. Once authorized, the chat can immediately send and receive messages — no further commands needed
 
@@ -174,7 +175,6 @@ Attach files to your message. They're downloaded and stored in CCCC's blob stora
 | Command | Description |
 |---------|-------------|
 | `/subscribe` | Start authorization flow — generates a one-time binding key |
-| `/bind <key>` | Authorize this chat using a binding key (paste in CCCC Web chat) |
 | `/unsubscribe` | Stop receiving messages |
 | `/send <message>` | Send to foreman (default) |
 | `/send @<actor> <message>` | Send to a specific agent |
@@ -213,7 +213,7 @@ Your token is invalid. Get a new one from BotFather:
 
 ### Messages not delivered
 
-1. Ensure the chat is authorized (run `/subscribe` → bind the key via Web or CLI)
+1. Ensure the chat is authorized (run `/subscribe` → bind the key via Web, foreman-assisted bind, or CLI)
 2. Check that the CCCC daemon is running
 3. Verify the bridge status in Web UI or via `cccc im status`
 
@@ -229,6 +229,6 @@ Telegram has rate limits. If you're sending many messages:
 - Consider enabling 2FA on your Telegram account
 - Review who has access to chats where the bot is subscribed
 - The bot can see all messages in groups where it's added
-- **New chats require key-based authorization** before they can interact with the bot — send `/subscribe` to generate a one-time key, then confirm it from the server side (Web chat or CLI); once bound, the chat is fully authorized
+- **New chats require key-based authorization** before they can interact with the bot — send `/subscribe` to generate a one-time key, then confirm it from the server side (Web Settings > IM Bridge, foreman-assisted bind, or CLI); once bound, the chat is fully authorized
 - Binding keys expire after **10 minutes**; generate a new one with `/subscribe` if it lapses
-- The bind operation must be performed via CCCC Web chat or `cccc im bind --key` on the server — Telegram users cannot self-authorize
+- The bind operation must be performed via CCCC Web Settings (IM Bridge), foreman-assisted bind, or `cccc im bind --key` on the server — Telegram users cannot self-authorize

docs/standards/CCCC_DAEMON_IPC_V1.md

@@ -1433,6 +1433,53 @@ Errors:
 - `missing_group_id` – `group_id` is empty.
 - `group_not_found` – group does not exist.
 
+#### `im_list_pending`
+
+List pending one-time bind requests for a group (expired keys are omitted).
+
+Args:
+```ts
+{ group_id: string }
+```
+
+Result:
+```ts
+{
+  pending: Array<{
+    key: string
+    chat_id: string
+    thread_id: number
+    platform: string
+    created_at: number
+    expires_at: number
+    expires_in_seconds: number
+  }>
+}
+```
+
+Errors:
+- `missing_group_id` – `group_id` is empty.
+- `group_not_found` – group does not exist.
+
+#### `im_reject_pending`
+
+Reject a pending one-time bind key.
+
+Args:
+```ts
+{ group_id: string; key: string }
+```
+
+Result:
+```ts
+{ rejected: boolean } // idempotent: false when key is already absent/expired
+```
+
+Errors:
+- `missing_key` – `key` is empty.
+- `missing_group_id` – `group_id` is empty.
+- `group_not_found` – group does not exist.
+
 #### `im_revoke_chat`
 
 Revoke authorization for an IM chat.

src/cccc/daemon/ops/chat_ops.py

@@ -171,9 +171,13 @@ def handle_send(
         src_event_id = ""
     to_raw = args.get("to")
     to_tokens: list[str] = []
-    to_explicitly_set = isinstance(to_raw, list) and len(to_raw) > 0
     if isinstance(to_raw, list):
         to_tokens = [str(x).strip() for x in to_raw if isinstance(x, str) and str(x).strip()]
+    elif isinstance(to_raw, str):
+        token = to_raw.strip()
+        if token:
+            to_tokens = [token]
+    to_explicitly_set = len(to_tokens) > 0
 
     if priority not in ("normal", "attention"):
         return _error("invalid_priority", "priority must be 'normal' or 'attention'")

src/cccc/daemon/ops/im_ops.py

@@ -67,6 +67,26 @@ def handle_im_list_authorized(args: Dict[str, Any]) -> DaemonResponse:
     return DaemonResponse(ok=True, result={"authorized": km.list_authorized()})
 
 
+def handle_im_list_pending(args: Dict[str, Any]) -> DaemonResponse:
+    """List pending bind requests for a group."""
+    err, km, _group = _load_km(args)
+    if err is not None:
+        return err
+    return DaemonResponse(ok=True, result={"pending": km.list_pending()})
+
+
+def handle_im_reject_pending(args: Dict[str, Any]) -> DaemonResponse:
+    """Reject a pending bind request key."""
+    key = str(args.get("key") or "").strip()
+    if not key:
+        return _error("missing_key", "key is required")
+    err, km, _group = _load_km(args)
+    if err is not None:
+        return err
+    rejected = km.reject_pending(key)
+    return DaemonResponse(ok=True, result={"rejected": bool(rejected)})
+
+
 def handle_im_revoke_chat(args: Dict[str, Any]) -> DaemonResponse:
     """Revoke authorization for a chat."""
     chat_id = str(args.get("chat_id") or "").strip()
@@ -98,6 +118,10 @@ def try_handle_im_op(op: str, args: Dict[str, Any]) -> Optional[DaemonResponse]:
         return handle_im_bind_chat(args)
     if op == "im_list_authorized":
         return handle_im_list_authorized(args)
+    if op == "im_list_pending":
+        return handle_im_list_pending(args)
+    if op == "im_reject_pending":
+        return handle_im_reject_pending(args)
     if op == "im_revoke_chat":
         return handle_im_revoke_chat(args)
     return None

src/cccc/ports/im/auth.py

@@ -138,11 +138,48 @@ def revoke(self, chat_id: str, thread_id: int) -> bool:
     def list_authorized(self) -> List[Dict[str, Any]]:
         return list(self._authorized.values())
 
+    def list_pending(self) -> List[Dict[str, Any]]:
+        """List pending bind requests (expired keys are purged first)."""
+        removed = self._purge_expired()
+        if removed:
+            self._save_pending()
+        now = time.time()
+        items: List[Dict[str, Any]] = []
+        for key, entry in self._pending.items():
+            created_at = float(entry.get("created_at", 0) or 0)
+            expires_at = created_at + KEY_TTL_SECONDS
+            items.append({
+                "key": str(key),
+                "chat_id": str(entry.get("chat_id") or ""),
+                "thread_id": int(entry.get("thread_id") or 0),
+                "platform": str(entry.get("platform") or ""),
+                "created_at": created_at,
+                "expires_at": expires_at,
+                "expires_in_seconds": max(0, int(expires_at - now)),
+            })
+        items.sort(key=lambda item: float(item.get("created_at") or 0), reverse=True)
+        return items
+
+    def reject_pending(self, key: str) -> bool:
+        """Reject a pending bind key. Returns True when removed."""
+        token = str(key or "").strip()
+        if not token:
+            return False
+        removed = self._purge_expired()
+        existed = token in self._pending
+        if existed:
+            self._pending.pop(token, None)
+            self._save_pending()
+            return True
+        if removed:
+            self._save_pending()
+        return False
+
     # ------------------------------------------------------------------
     # Internal
     # ------------------------------------------------------------------
 
-    def _purge_expired(self) -> None:
+    def _purge_expired(self) -> bool:
         """Remove expired pending keys (best-effort, no save)."""
         now = time.time()
         expired = [
@@ -151,3 +188,4 @@ def _purge_expired(self) -> None:
         ]
         for k in expired:
             del self._pending[k]
+        return bool(expired)

src/cccc/ports/im/bridge.py

@@ -641,6 +641,9 @@ def _should_forward(self, event: Dict[str, Any], verbose: bool) -> bool:
 
     def _handle_subscribe(self, chat_id: str, chat_title: str, thread_id: int = 0) -> None:
         """Handle /subscribe command."""
+        # Reload auth state on-demand as subscribe semantics depend on current
+        # authorization truth (bind/revoke can happen in daemon/web concurrently).
+        self.key_manager._load()
         platform = str(getattr(self.adapter, "platform", "") or "").strip().lower()
 
         # If the chat is not yet authorized, generate a binding key.
@@ -649,8 +652,11 @@ def _handle_subscribe(self, chat_id: str, chat_title: str, thread_id: int = 0) -
             self.adapter.send_message(
                 chat_id,
                 f"🔑 Authorization required.\n\n"
-                f"Copy and paste in CCCC Web chat:\n"
-                f"`/bind {key}`\n\n"
+                f"Open CCCC Web → Settings → IM Bridge, then approve this request in Pending Requests "
+                f"(or paste this key in Bind):\n"
+                f"`{key}`\n\n"
+                f"If foreman is online, send this message to foreman:\n"
+                f"`Please help bind my IM key: {key}`\n\n"
                 f"Or run in terminal:\n"
                 f"`cccc im bind --key {key}`\n\n"
                 f"Key expires in 10 minutes.",
@@ -659,6 +665,7 @@ def _handle_subscribe(self, chat_id: str, chat_title: str, thread_id: int = 0) -
             self._log(f"[subscribe] Pending auth key generated for chat={chat_id} thread={thread_id}")
             return
 
+        was_subscribed = self.subscribers.is_subscribed(chat_id, thread_id=thread_id)
         sub = self.subscribers.subscribe(chat_id, chat_title, thread_id=thread_id, platform=platform)
         verbose_str = "on" if sub.verbose else "off"
         platform = str(getattr(self.adapter, "platform", "") or "").strip().lower() or "telegram"
@@ -668,9 +675,14 @@ def _handle_subscribe(self, chat_id: str, chat_title: str, thread_id: int = 0) -
             tip = "Channel tip: @mention the bot to route plain text. Use /send for explicit recipients."
         else:
             tip = "Tip: plain text routes to foreman by default; use /send for explicit recipients."
+        target_label = self.group.doc.get("title", self.group.group_id)
+        if was_subscribed:
+            headline = f"✅ Already authorized for this chat ({target_label})"
+        else:
+            headline = f"✅ Subscribed to {target_label}"
         self.adapter.send_message(
             chat_id,
-            f"✅ Subscribed to {self.group.doc.get('title', self.group.group_id)}\n"
+            f"{headline}\n"
             f"Verbose mode: {verbose_str}\n"
             f"{tip}\n"
             f"Use /help for commands.",

src/cccc/ports/mcp/toolspecs.py

@@ -1182,8 +1182,8 @@
         "name": "cccc_im_bind",
         "description": (
             "Bind a Telegram (or other IM) chat using a one-time key.\n\n"
-            "Typical flow: user runs /subscribe in Telegram, gets a key, pastes `/bind <key>` in CCCC Web chat, "
-            "and the foreman calls this tool to complete the binding.\n\n"
+            "Typical flow: user runs /subscribe in IM chat, gets a key, opens CCCC Web > Settings > IM Bridge > Bind, "
+            "and the foreman can also call this tool to complete the binding.\n\n"
             "The key expires after 10 minutes."
         ),
         "inputSchema": {

src/cccc/ports/web/app.py

@@ -309,6 +309,16 @@ class IMActionRequest(BaseModel):
     group_id: str
 
 
+class IMBindRequest(BaseModel):
+    group_id: str
+    key: str
+
+
+class IMPendingRejectRequest(BaseModel):
+    group_id: str
+    key: str
+
+
 def _is_env_var_name(value: str) -> bool:
     # Shell-friendly env var name (portable).
     return bool(re.fullmatch(r"[A-Z_][A-Z0-9_]*", (value or "").strip()))
@@ -2879,12 +2889,18 @@ async def im_stop(req: IMActionRequest) -> Dict[str, Any]:
 
         return {"ok": True, "result": {"group_id": req.group_id, "stopped": stopped}}
 
-    # ----- IM auth (bind / list / revoke) -----
+    # ----- IM auth (bind / pending / list / revoke) -----
 
     @app.post("/api/im/bind")
-    async def im_bind(group_id: str, key: str) -> Dict[str, Any]:
-        """Bind a pending authorization key to authorize a Telegram chat."""
-        resp = await _daemon({"op": "im_bind_chat", "args": {"group_id": group_id, "key": key}})
+    async def im_bind(req: Optional[IMBindRequest] = None, group_id: str = "", key: str = "") -> Dict[str, Any]:
+        """Bind a pending authorization key to authorize an IM chat."""
+        gid = str((req.group_id if isinstance(req, IMBindRequest) else group_id) or "").strip()
+        k = str((req.key if isinstance(req, IMBindRequest) else key) or "").strip()
+        if not gid:
+            raise HTTPException(status_code=400, detail={"code": "missing_group_id", "message": "group_id is required"})
+        if not k:
+            raise HTTPException(status_code=400, detail={"code": "missing_key", "message": "key is required"})
+        resp = await _daemon({"op": "im_bind_chat", "args": {"group_id": gid, "key": k}})
         if not resp.get("ok"):
             err = resp.get("error") if isinstance(resp.get("error"), dict) else {}
             code = str(err.get("code") or "bind_failed")
@@ -2901,6 +2917,36 @@ async def im_list_authorized(group_id: str) -> Dict[str, Any]:
             raise HTTPException(status_code=400, detail=err)
         return resp
 
+    @app.get("/api/im/pending")
+    async def im_list_pending(group_id: str) -> Dict[str, Any]:
+        """List pending bind requests for a group."""
+        resp = await _daemon({"op": "im_list_pending", "args": {"group_id": group_id}})
+        if not resp.get("ok"):
+            err = resp.get("error") if isinstance(resp.get("error"), dict) else {}
+            raise HTTPException(status_code=400, detail=err)
+        return resp
+
+    @app.post("/api/im/pending/reject")
+    async def im_reject_pending(
+        req: Optional[IMPendingRejectRequest] = None,
+        group_id: str = "",
+        key: str = "",
+    ) -> Dict[str, Any]:
+        """Reject a pending bind request key."""
+        gid = str((req.group_id if isinstance(req, IMPendingRejectRequest) else group_id) or "").strip()
+        k = str((req.key if isinstance(req, IMPendingRejectRequest) else key) or "").strip()
+        if not gid:
+            raise HTTPException(status_code=400, detail={"code": "missing_group_id", "message": "group_id is required"})
+        if not k:
+            raise HTTPException(status_code=400, detail={"code": "missing_key", "message": "key is required"})
+        resp = await _daemon({"op": "im_reject_pending", "args": {"group_id": gid, "key": k}})
+        if not resp.get("ok"):
+            err = resp.get("error") if isinstance(resp.get("error"), dict) else {}
+            code = str(err.get("code") or "reject_failed")
+            msg = str(err.get("message") or "reject failed")
+            raise HTTPException(status_code=400, detail={"code": code, "message": msg})
+        return resp
+
     @app.post("/api/im/revoke")
     async def im_revoke(group_id: str, chat_id: str, thread_id: int = 0) -> Dict[str, Any]:
         """Revoke authorization for a chat."""

tests/test_chat_ops.py

@@ -168,6 +168,22 @@ def test_send_to_array_is_routed_correctly(self) -> None:
         finally:
             cleanup()
 
+    def test_send_to_string_direct_payload_is_routed_correctly(self) -> None:
+        """T067 scenario: daemon send op tolerates string `to` payload."""
+        group_id, cleanup = self._setup_group_with_actors()
+        try:
+            resp, _ = self._call("send", {
+                "group_id": group_id,
+                "by": "user",
+                "to": "peer1",
+                "text": "hello peer1",
+            })
+            self.assertTrue(resp.ok, getattr(resp, "error", None))
+            event = (resp.result or {}).get("event", {})
+            self.assertEqual(event.get("data", {}).get("to", []), ["peer1"])
+        finally:
+            cleanup()
+
     def test_send_empty_to_uses_default(self) -> None:
         """T067 scenario 3: empty `to` falls back to group default."""
         group_id, cleanup = self._setup_group_with_actors()
@@ -184,6 +200,22 @@ def test_send_empty_to_uses_default(self) -> None:
         finally:
             cleanup()
 
+    def test_send_to_malformed_list_entries_falls_back_to_default(self) -> None:
+        """T067 edge: malformed list entries should not become broadcast."""
+        group_id, cleanup = self._setup_group_with_actors()
+        try:
+            resp, _ = self._call("send", {
+                "group_id": group_id,
+                "by": "user",
+                "to": [None, ""],
+                "text": "malformed to payload",
+            })
+            self.assertTrue(resp.ok, getattr(resp, "error", None))
+            event = (resp.result or {}).get("event", {})
+            self.assertEqual(event.get("data", {}).get("to", []), ["@foreman"])
+        finally:
+            cleanup()
+
     def test_send_multiple_recipients(self) -> None:
         """T067 scenario 4: multiple explicit recipients."""
         group_id, cleanup = self._setup_group_with_actors()