PON connector-service — Kết nối tài khoản bên thứ ba & AI gọi tool qua MCP Diagram

Hai nửa độc lập: cột 0–1 là kết nối tài khoản (làm một lần, qua popup OAuth); cột 2–5 chạy trong MỖI câu hỏi @AI khi ai-service hỏi connector-service có tool gì rồi gọi tool.
ai-service không bao giờ cầm token bên thứ ba, connector-service không bao giờ thấy prompt: hai bên chỉ trao đổi tên tool mcp__<provider>__<tool>, input JSON và chuỗi kết quả qua header x-internal-key.
Đường đậm là luồng dùng tool; đường đứt là đọc dữ liệu phụ; đường đỏ là nhánh chặn. Mọi lỗi ra ngoài đều là mã: ?error=CODE cho popup, 'Tool error: [CODE] …' cho model (ai-service dựa vào prefix này để bỏ cache).

Thứ tự trong code: member còn active (đọc users/roles trực tiếp từ Mongo, không tin JWT; thiếu role → preset Member) → workspace.connectorAllowList ([] = cho tất cả) → aiSettings.allowedConnectors (null = kế thừa, [] = AI không được dùng gì) → connector còn tồn tại/available → ADD_CUSTOM_MCP cho custom server → actionGroups của connection (view/create/edit/delete) → RUN_SENSITIVE_SKILL cho tool nhạy cảm.
Phân loại tool fail-closed: readOnlyHint=true → view; theo verb trong tên (delete/edit/create); verb không nhận ra → nhóm nghiêm nhất (delete, sensitive). Mọi write (sensitive hay không) đều gắn sensitive=true để ai-service dựng card xác nhận trước khi gọi.
Mỗi provider chỉ lộ MỘT connection: của chính member nếu có, không thì workspace connection mới nhất; connect workspace lần 2 thay thế cái cũ (audit connector.replace). Tool bị role chặn trả về 'withheld' để AI giải thích thay vì bảo 'chưa kết nối'.

Vault AES-256-GCM, IV 12 byte, auth tag ghim 16 byte; key 32 byte base64 từ CONNECTOR_VAULT_KEY, service từ chối boot nếu thiếu. encryptedTokens không bao giờ xuất hiện trong response /connections.
OAuth state ký HMAC-SHA256 bằng INTERNAL_API_KEY, gắn userId+provider+scope, TTL 10 phút; callback không có JWT nên kiểm tra lại member/capability/allow-list từ Mongo trước khi đổi code. Google xin access_type=offline + prompt=consent để có refresh token.
Refresh single-flight theo connection, luôn đọc token ĐANG LƯU (instance khác có thể đã xoay): Google/directory refresh sớm 60s trước hạn hoặc khi 401; Notion xoay refresh token nên chỉ refresh khi 401 và 1 lần. invalid_grant → status=expired → CONNECTION_EXPIRED bảo người dùng reconnect. Mọi fetch ra ngoài qua safeFetch (chặn IP nội bộ, SSRF); MCP thử Streamable HTTP rồi SSE.

Directory connect (MCP-native DCR + PKCE, apikey, none) đi chung ConnectionStore nhưng là service riêng; custom MCP server (admin, ADD_CUSTOM_MCP); disconnect + revoke best-effort; endpoint /mcp JSON-RPC cho Bot Factory (chỉ tool read-only, write trả -32010).
README connector-service ghi 'Notion live; Gmail/Calendar planned', nhưng CATALOG hiện có notion, gmail, calendar available=true (drive=false). README cũng ghi Notion đi remote MCP; thực tế Notion dùng adapter REST vì MCP hosted trả 403 restricted_resource cho token OAuth catalog.
Working tree lúc vẽ có sửa đổi chưa commit (scripts/dev/seed-lumen/*, ai-service package.json, pnpm-lock.yaml) không liên quan connector-service; trích dẫn trỏ vào revision ee42d203 trên origin/dev.