bot_api

Overview ¶

Module-side composer that wires bot_api.groupService.GetMembers + bot_api.robotService.ExistRobot into the pkg/mentionrewrite.ExpandAisToBotUIDs callback shape.

See modules/message/mention_expand.go for the design rationale — the leaf helper stays free of any modules/* dependency to preserve the import-cycle-free invariant called out in pkg/mentionrewrite/rewrite.go. Each ingress chokepoint owns its own thin composer.

Package bot_api · YUJ-1166 / Mininglamp-OSS/octo-server#81 — Persona Clone OBO REST endpoints.

These endpoints are mounted under /v1/obo behind the standard user-auth middleware (ba.ctx.AuthMiddleware) — they take a USER token, not a bot token. The acting user must be the grantor of the row they CRUD; we do NOT support cross-user persona management in v0 (RFC §2 / out-of-scope).

Status code map (kept narrow on purpose):

200 — success (single object or list)
400 — bad request body / missing required fields
401 — no user token (handled by upstream middleware)
403 — (reserved — production currently uses 404 for cross-user attempts
       as a user-enumeration defense; see requireOwnedGrant comment.)
404 — grant_id / scope_id not found; cross-user grant/scope access
       (existence-leak defense)
409 — duplicate (grantor+grantee already exists / scope already exists,
       with no soft-deleted row to reactivate in place)
500 — DB error

Package bot_api · YUJ-1166 / Mininglamp-OSS/octo-server#81 — Persona Clone authorization check used by sendMessage / stream endpoints.

checkOBO is the single boolean question on the dispatch hot path: "is bot B allowed to act as grantor G in (channel_id, channel_type)?". It is intentionally a thin wrapper over oboStore so:

• the HTTP handler stays tiny (build req → check → dispatch);
• unit tests can swap a fake oboStore without standing up MySQL;
• future cache-aware variants (e.g. negative cache) can land here without touching the handler.

Package bot_api · YUJ-1166 / Mininglamp-OSS/octo-server#81 — Persona Clone (On-Behalf-Of) v0 data layer.

Backing tables: obo_grants, obo_scopes (see SQL migration 20260519000001_obo_v0.sql). Public surface is the oboStore interface so HTTP handlers, checkOBO, and the fan-out listener can all be unit-tested against an in-memory fake without sqlmock plumbing.

Cache strategy (RFC §11 risk row): the two hot-path questions are answered by short-TTL Redis keys, populated on read-through, invalidated on write:

• obo:grantor:{uid} "1" any active grant exists for grantor; "0" no active grant. Read by findActiveGrantByGrantorBot — negative answer short-circuits the (grantor, bot) MySQL probe that checkOBO would otherwise issue per send.
• obo:chan:{ctype}:{cid} "1" channel has at least one (active grant × enabled scope) match; "0" no match. Read by findActiveGrantsForChannel — negative answer short-circuits the JOIN that the fan-out listener would otherwise issue per inbound message system-wide.

Both keys are negative-cache friendly: a "0" answer returned within the 30-second TTL eliminates the MySQL round-trip entirely. Writes that can flip either answer (insertGrant / updateGrant / revokeGrant / insertScope / deleteScope) invalidate the affected keys inline. Stale "1" answers are safe — callers still consult MySQL when the cache says "1", so the cache cannot grant authorization it shouldn't. Stale "0" answers cap at 30s and are acceptable per RFC §11 (risk explicitly accepted for v0). Redis is best-effort throughout: a Redis outage silently degrades to the pre-cache path (full MySQL load), never to a permissions regression.

Package bot_api · YUJ-1166 / Mininglamp-OSS/octo-server#81 — Persona Clone fan-out hook.

Hook design (RFC §5.3): we register a MessagesListener on the shared context — same pattern the robot, botfather, thread, and message modules already use — so the fan-out happens AFTER WuKongIM has persisted the inbound message but BEFORE we deliver the copy. This matches "candidate 1" in the RFC and keeps the listener side-effect free with respect to the original message.

The listener pulls grants by (channel_id, channel_type) — a single index hit per inbound message — then applies the three loop-protection gates from RFC §5.3:

Gate 1: bot self-sent → never replay to that same bot
Gate 2: grantor's own outbound → don't fan it to the grantor's bot
        (covers the "I typed on my phone" case — bot should not echo)
Gate 3: already-OBO-processed → message_extra has __obo_processed__=true
        (the bot's outbound, marked by sendMessage, must not bounce)

PR#82 review #2 P1-2: gate 3's marker key is `__obo_processed__` (double- underscore reserved prefix), NOT the v0-shipped `obo_processed`. The v0 key was a plain JSON field that any bot could set on its own /v1/bot/sendMessage payload — letting a bot suppress its own fan-out by crafting `{"content":"…", "obo_processed":true}`. The new key sits in a reserved namespace (`__obo_*`) that sendMessage strips off inbound payloads (see send.go) before processing, so the marker is now server-only state. Compatibility note: messages persisted under the legacy key during the v0 testing window are NOT honored — gate 3 is strict on the new name. Any in-flight v0 messages would only suppress their own fan-out (a bounded edge case) and the test suite is the only caller that ever wrote the legacy key in this branch.

For each surviving (message, grant) pair we build a MsgSendReq addressed to the grantee bot's own PERSONAL mailbox (ChannelID=grantee_bot_uid, ChannelType=Person, Subscribers OMITTED). The original delivery to real users is untouched.

PR#82 review #5 P0 — WuKongIM /message/send contract: `channel_id` and `subscribers` are MUTUALLY EXCLUSIVE on a single MsgSendReq. The v0 implementation set BOTH (ChannelID = origin conversation, Subscribers = [granteeBot]) and WuKongIM rejected every dispatch with:

【message】channelId和subscribers不能同时存在！

The "OBO fan-out dispatch failed" line in im-test prod showed every inbound message tripping this. Fix: address the fan-out copy at the bot's personal mailbox and drop Subscribers. The original conversation context is preserved in the payload's `obo_origin_*` fields so the bot (and any downstream consumer) can still reason about where the message originated. We go through octo-lib's `NewPersonalMsgSendReq` builder so the PERSONAL DM authoritative-payload contract (Mininglamp-OSS#37) is preserved and the `tools/lint-personal-msgsendreq` invariant holds.

What we do NOT do here:

• We do NOT call SendMessageWithResult (which would create a new persisted message everyone sees). The Person-channel route + NoPersist=1 gives the bot a one-shot copy via its existing subscriber pipeline (the bot is the sole subscriber of its own mailbox channel).
• We do NOT recompute permissions; checkOBO already ran when the bot authored the message that's now bouncing, and inbound messages from real users are by definition allowed in the channel they arrived in.

PR#82 R6 P0 — The fan-out copy's FromUID is the GRANTOR uid (not the original sender). The v0 implementation used `FromUID=m.FromUID` (= the peer who sent the inbound, e.g. u_bob), so for DMs WuKongIM observed a (FromUID=u_bob, ChannelID=granteeBotUID) PERSONAL message and synced the conversation pair `u_bob ↔ granteeBot` to **u_bob's** client — leaking the persona-clone bot into bob's conversation list even though bob only ever spoke to admin. The whole point of "managed persona" is that bob sees ONLY admin as the counterparty; the bot is strictly behind admin's identity.

The fix routes the fan-out copy as "admin (grantor) forwarding to the bot's own mailbox". WuKongIM then syncs the pair `admin ↔ granteeBot` only — which is semantically correct because admin owns the bot (admin is the grantor in the OBO grant row) and the bot is admin's own managed persona. Bob is no longer in either UID of the fan-out copy and therefore cannot see the bot at all. The bot still learns who actually spoke via `obo_origin_from_uid` in the payload.

Package bot_api · YUJ-1166 — PR#82 R6 P0 friend-gate OBO bypass.

Background: the bot send / typing / readReceipt / messages-sync paths require the bot to be a friend of the target user (BotKindUser DM branch). That rule is correct for "bot user is talking directly to you" — the user must opt in.

It is **wrong** for the managed-persona / OBO path. When admin grants the persona-clone bot james OBO authority over the DM pair admin↔bob, bob has chosen to DM admin (not james); admin's clone is expected to reply as admin. Requiring a `bot↔bob` friend row would either:

1. force the server to silently fabricate the friendship behind the real user's back — leaking the bot's existence to bob (R6 P0 Bug A in reverse: bob sees bot as a contact), OR
2. block every managed-persona reply with `bot is not a friend of this user` — which is what im-test 2026-05-19 surfaced for james.

The fix is a server-side conditional bypass: when the request carries a validated OBO context (i.e. the bot is asking to dispatch as a real grantor via the `on_behalf_of` field on sendMessage), and the friend gate would otherwise reject the DM, we check whether an active OBO grant authorises the bot to operate as some grantor in that channel and the grantor still has a valid relation with the target. If so, the friendship requirement is satisfied transitively by the grantor's relation — the bot is acting as the grantor, the grantor is friends with the target, so the send is legitimate.

PR#82 R7 — the bypass is **gated on the caller passing hasOBOContext=true**. The bot adapter sets this when the inbound request carries `on_behalf_of`; the actual `checkOBO` validation (grant + scope + grantor-still-has-access) runs immediately after, so a bot that lies about the header gets short-circuited there. Critically, requests that omit `on_behalf_of` (sendMessage as the bot itself, typing, readReceipt, messages/sync) MUST NOT consult the OBO bypass — otherwise a bot with any unrelated grant covering a target user could dispatch directly bot→target and expose itself as a contact, defeating the user opt-in friend gate. See Jerry-Xin's R7 review on head a07b372 for the regression details.

Hot-path cost (only paid when hasOBOContext=true): one cached `findActiveGrantsForChannel` lookup (the same one the fan-out listener consults — already negative-cached via `obo:chan:*`) PLUS a per-matching-grant `grantorCanReadChannel` re-check. For the common case (no OBO grant covers the target channel) the negative cache makes this a single Redis GET. Requests without OBO context skip the bypass entirely and go straight back to `isFriend`.

Package bot_api · YUJ-644 / Mininglamp-OSS#33 / YUJ-660 / YUJ-688

PERSONAL DM 派发前为 payload 注入 Bot 的权威 SpaceID。WuKongIM 在 DM 上仅按 裸 uid 路由（无 Space 概念），收端客户端 SpaceFilter 唯一可信信号源是 payload.space_id；任何客户端上送的值都不可信，必须服务端覆盖。

解析顺序（自上而下，最快路径优先）：

1. App Bot scope=space —— 直接读 gin-context 里 authAppBot 写入的 CtxKeyAppBotSpaceID（O(1)，无 DB 调用）。
2. 其它情况（User Bot、App Bot scope=platform）—— 用 querySpaceIDByRobotID 查 space_member ⨝ space。结果为空表示 Bot 当前没有归属 Space（孤儿 Bot 或非 Space 部署）。

失败模式：

• 真实 DB 错误 → warn + 不阻断发送（注入是优化，缺失走 fail-closed strip）。
• dbr.ErrNotFound（零结果）→ 视为"Bot 没有归属 Space"，不写 false-positive DB 错误日志，fall through 到 strip-or-warn 分支。

**YUJ-660 R3 Finding A — fail-closed strip语义（HIGH 修复）**：当 resolver 返 回 ""（任何原因：孤儿 Bot / DB 错误 / ErrNotFound），enrichBotPayloadWithSpaceID **必须删除** payload["space_id"]，并 emit `client_space_id_stripped=true` 监控 warn（如果 client 上送过非空值）；payload 本就没有 space_id 时 emit `enrich_payload_space_id_empty=true`。

之前版本在 resolver 返回 "" 时保留 client payload —— 攻击者可以构造 DB 错误条 件（或孤儿 Bot 触发条件）伪造 payload.space_id="victim_space" 通过派发，realtime + offline push 都会信任这个值。strip 是唯一 fail-closed 行为；message 层 R2 High-3 strip 只在 sendMsg 路径生效，bot_api / robot 路径需要本层独立 strip。

**YUJ-688 / PR#43 R1 fix-up — platform App Bot validator gap (Critical from Jerry-Xin + lml2468)**: the X-Space-ID validator previously checked only `space_member`. Platform App Bots are inserted in `app_bot` with `scope='platform'` and never get a `space_member` row, yet they are legitimately visible in every active Space (`pkg/space/query.go:99`). Result: every valid platform App Bot dispatch with a valid X-Space-ID header was rejected by the validator and the caller's strip path downgraded the payload, sending the message as a personal DM with no SpaceID. The fix renames `isBotSpaceMember` to `isBotSpaceAuthorized` and broadens the SQL to honor the production `app_bot` rows (platform OR scope=space-with-match). Trim whitespace from the header value first to avoid noisy reject logs from " space_X " / trailing CR.