feat: two-step IM pairing with YES confirmation + DynamoDB MAPPING# write

JiaDe · claude · JiaDe · commit 0cc91bece7d0 · 2026-04-03T11:04:16.000+08:00
Binding flow (H2 Proxy + main.py):
- /start TOKEN → pair-pending (validate, return employee name)
  → inject "reply YES to confirm binding to [Name · Position]"
  → store pending in H2 Proxy memory Map (10 min TTL)
- YES → pair-complete → write DynamoDB MAPPING# + SSM → inject success
- NO  → cancel → inject cancel message
- already_bound_other → block with explanation

Security fixes:
- pair-complete now writes DynamoDB MAPPING#{channel}__{userId} (was SSM-only)
- duplicate binding check: same IM userId cannot bind to two different employees
- same employee rebinding: allowed, shows "重新绑定" phrasing
- token consumed only on YES, not on /start (prevents replay if user says NO)

Co-Authored-By: Claude Sonnet 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/enterprise/admin-console/server/main.py b/enterprise/admin-console/server/main.py
@@ -1815,20 +1815,70 @@ def pair_status(token: str, authorization: str = Header(default="")):
     return {"status": item.get("status", "pending")}
 
 
+class PairPendingRequest(BaseModel):
+    token: str
+    channelUserId: str
+    channel: str
+
+@app.post("/api/v1/bindings/pair-pending")
+def pair_pending(body: PairPendingRequest):
+    """Called by H2 Proxy on /start TOKEN — validates token and returns employee info
+    for the YES/NO confirmation message. Does NOT consume the token.
+    H2 Proxy caches the result and calls pair-complete only after YES."""
+    import time as _t
+    item = db.get_pair_token(body.token)
+    if not item:
+        return {"valid": False, "reason": "not_found"}
+    if item.get("ttl", 0) < int(_t.time()):
+        return {"valid": False, "reason": "expired"}
+    if item.get("status") not in ("pending",):
+        return {"valid": False, "reason": "already_used"}
+
+    emp_id = item["employeeId"]
+
+    # Check: is this IM userId already bound to a DIFFERENT employee?
+    existing = db.get_user_mapping(body.channel, body.channelUserId)
+    if existing and existing.get("employeeId") != emp_id:
+        other_emps = db.get_employees()
+        other_emp = next((e for e in other_emps if e["id"] == existing["employeeId"]), None)
+        return {
+            "valid": False,
+            "reason": "already_bound_other",
+            "boundTo": other_emp.get("name", existing["employeeId"]) if other_emp else existing["employeeId"],
+        }
+
+    emps = db.get_employees()
+    emp = next((e for e in emps if e["id"] == emp_id), {})
+    is_rebind = existing is not None and existing.get("employeeId") == emp_id
+
+    return {
+        "valid": True,
+        "employeeId": emp_id,
+        "employeeName": emp.get("name", emp_id),
+        "positionName": emp.get("positionName", ""),
+        "isRebind": is_rebind,
+    }
+
+
 @app.post("/api/v1/bindings/pair-complete")
 def pair_complete(body: PairCompleteRequest):
-    """Called by H2 Proxy when employee sends /start TOKEN to the bot.
+    """Called by H2 Proxy after employee confirms YES.
     No auth — called from internal network only (H2 Proxy on same EC2).
-    Validates token, writes SSM user mapping, logs audit entry."""
+    Consumes token, writes DynamoDB MAPPING# + SSM, logs audit entry."""
     item = db.consume_pair_token(body.token)
     if not item:
         raise HTTPException(400, "Token invalid, already used, or expired")
 
     emp_id = item["employeeId"]
     channel = item.get("channel", body.channel)
 
-    # Write SSM mapping — must use us-east-1 (where agent container reads from)
-    # pair_complete is the only endpoint called by H2 Proxy, so we need explicit region
+    # Write DynamoDB MAPPING# (primary, used by tenant_router and workspace_assembler)
+    try:
+        db.create_user_mapping(channel, body.channelUserId, emp_id)
+    except Exception as e:
+        print(f"[pair-complete] DynamoDB MAPPING# write failed: {e}")
+
+    # Write SSM (dual-write for backward compat during transition)
     import boto3 as _b3_pair
     _ssm_pair = _b3_pair.client("ssm", region_name=_GATEWAY_REGION)
     _prefix = _mapping_prefix()
diff --git a/enterprise/gateway/bedrock_proxy_h2.js b/enterprise/gateway/bedrock_proxy_h2.js
@@ -49,6 +49,11 @@ function log(msg) {
 // States: 'cold' -> 'warming' -> 'warm' -> (TTL expires) -> 'cold'
 const tenantState = new Map();
 
+// Pending IM pairing confirmations (two-step: /start TOKEN → YES/NO)
+// key: `${channel}:${userId}` → { token, empName, expiresAt }
+// Stored in-memory only; a proxy restart loses pending pairings (user re-scans QR to retry)
+const pendingPairings = new Map();
+
 function getTenantKey(channel, userId) {
   return `${channel}__${userId}`;
 }
@@ -596,58 +601,114 @@ server.on('stream', (stream, headers) => {
       }
 
       // =====================================================================
-      // PATH C: IM Self-Service Pairing — intercept /start TOKEN commands
-      // When an employee scans the Portal QR code, Telegram sends "/start TOKEN".
-      // We validate the token against Admin Console and write the SSM mapping
-      // WITHOUT invoking AgentCore — fast, free, no microVM spin-up.
+      // PATH C: IM Self-Service Pairing — two-step confirmation flow
+      //
+      // Step 1: /start TOKEN → pair-pending (validate) → inject "reply YES to confirm"
+      //         Pending state stored in memory (pendingPairings Map, 10 min TTL)
+      // Step 2: YES → pair-complete → inject success
+      //         NO  → cancel → inject cancel
       //
-      // Safety: only intercepts exact pattern /start [A-Z0-9]{10,16}
-      // On any error (invalid token, network, etc.) → falls through to normal routing
+      // Safety: errors fall through to normal routing (employee gets agent response)
       // =====================================================================
-      // Search anywhere in userText — the /start TOKEN appears after OpenClaw's metadata blocks
+
+      // Helper: call Admin Console API (internal only, no auth needed)
+      const callAdminAPI = (path, payload) => new Promise((resolve, reject) => {
+        const http = require('node:http');
+        const body = JSON.stringify(payload);
+        const req = http.request({
+          hostname: '127.0.0.1', port: 8099, path,
+          method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+        }, (res) => {
+          let data = '';
+          res.on('data', c => data += c);
+          res.on('end', () => {
+            try { resolve({ status: res.statusCode, body: JSON.parse(data) }); }
+            catch { resolve({ status: res.statusCode, body: {} }); }
+          });
+        });
+        req.on('error', reject);
+        req.setTimeout(5000, () => { req.destroy(); reject(new Error('timeout')); });
+        req.write(body);
+        req.end();
+      });
+
+      // Helper: inject a fake Bedrock response without calling AgentCore
+      const injectResponse = (text) => {
+        if (isStream) {
+          stream.respond({ ':status': 200, 'content-type': 'application/vnd.amazon.eventstream' });
+          for (const e of buildEventStream(text)) stream.write(e);
+          stream.end();
+        } else {
+          stream.respond({ ':status': 200, 'content-type': 'application/json' });
+          stream.end(JSON.stringify(buildConverseResponse(text)));
+        }
+      };
+
+      const pendingKey = `${channel}:${userId}`;
+      const msgTrim = userText.trim();
+
+      // ── Step 2a: YES confirmation ──────────────────────────────────────
+      if (/^(yes|YES|Yes|Y|y|确认|绑定)$/.test(msgTrim) && pendingPairings.has(pendingKey)) {
+        const pending = pendingPairings.get(pendingKey);
+        if (Date.now() > pending.expiresAt) {
+          pendingPairings.delete(pendingKey);
+          injectResponse('⏱ 绑定超时，请回到 Portal 重新生成二维码。');
+          return;
+        }
+        try {
+          const result = await callAdminAPI('/api/v1/bindings/pair-complete', {
+            token: pending.token, channel, channelUserId: userId,
+          });
+          pendingPairings.delete(pendingKey);
+          if (result.status === 200 && result.body.success) {
+            log(`PATH C: Pairing confirmed ${channel} ${userId} → ${result.body.employeeId}`);
+            injectResponse(`✅ 绑定成功！你现在可以在这里直接与 AI Agent 对话了。`);
+          } else {
+            injectResponse(`绑定失败：${result.body.detail || '请重试'}。`);
+          }
+        } catch (e) {
+          log(`PATH C: pair-complete error: ${e.message}`);
+          injectResponse('绑定时出错，请稍后重试。');
+        }
+        return;
+      }
+
+      // ── Step 2b: NO / cancel ───────────────────────────────────────────
+      if (/^(no|NO|No|N|n|取消|cancel|CANCEL)$/.test(msgTrim) && pendingPairings.has(pendingKey)) {
+        pendingPairings.delete(pendingKey);
+        injectResponse('已取消。如需重新绑定请回到 Portal 生成二维码。');
+        return;
+      }
+
+      // ── Step 1: /start TOKEN ───────────────────────────────────────────
       const pairMatch = userText.match(/\/start\s+([A-Za-z0-9]{10,16})/);
       if (pairMatch && userId !== 'unknown' && channel !== 'unknown') {
         const token = pairMatch[1].toUpperCase();
         try {
-          const http = require('node:http');
-          const pairResult = await new Promise((resolve, reject) => {
-            const payload = JSON.stringify({ channel, channelUserId: userId, token });
-            const req = http.request({
-              hostname: '127.0.0.1', port: 8099, path: '/api/v1/bindings/pair-complete',
-              method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
-            }, (res) => {
-              let data = '';
-              res.on('data', c => data += c);
-              res.on('end', () => {
-                try { resolve({ status: res.statusCode, body: JSON.parse(data) }); }
-                catch { resolve({ status: res.statusCode, body: {} }); }
-              });
-            });
-            req.on('error', reject);
-            req.setTimeout(5000, () => { req.destroy(); reject(new Error('pair-complete timeout')); });
-            req.write(payload);
-            req.end();
+          const pending = await callAdminAPI('/api/v1/bindings/pair-pending', {
+            token, channel, channelUserId: userId,
           });
-
-          if (pairResult.status === 200 && pairResult.body.success) {
-            const { employeeName, positionName } = pairResult.body;
-            const confirmMsg = `✅ Connected! Hi ${employeeName} — your ${positionName || 'AI'} Agent is ready. Just send me a message to get started!`;
-            log(`PATH C: Pairing complete ${channel} ${userId} → ${pairResult.body.employeeId}`);
-            if (isStream) {
-              stream.respond({ ':status': 200, 'content-type': 'application/vnd.amazon.eventstream' });
-              for (const e of buildEventStream(confirmMsg)) stream.write(e);
-              stream.end();
-            } else {
-              stream.respond({ ':status': 200, 'content-type': 'application/json' });
-              stream.end(JSON.stringify(buildConverseResponse(confirmMsg)));
-            }
-            return; // ← pairing handled, do NOT route to AgentCore
+          if (pending.status === 200 && pending.body.valid) {
+            const { employeeName, positionName, isRebind } = pending.body;
+            pendingPairings.set(pendingKey, {
+              token,
+              empName: employeeName,
+              expiresAt: Date.now() + 10 * 60 * 1000,
+            });
+            const action = isRebind ? '重新绑定' : '绑定';
+            const msg = `你正在将此账号${action}到 [${employeeName}${positionName ? ' · ' + positionName : ''}]。\n\n回复 YES 确认，回复 NO 取消（10 分钟内有效）。`;
+            log(`PATH C: Pending pairing ${channel} ${userId} → ${employeeName}`);
+            injectResponse(msg);
+            return;
+          }
+          if (pending.status === 200 && pending.body.reason === 'already_bound_other') {
+            injectResponse(`此账号已绑定到 ${pending.body.boundTo}，请联系 IT 管理员解绑后再试。`);
+            return;
           }
-          // Token invalid/expired — fall through to normal routing with a hint
-          log(`PATH C: Pairing token invalid/expired for ${userId}, routing normally`);
+          // Token invalid/expired — fall through to normal routing
+          log(`PATH C: pair-pending invalid (${pending.body?.reason}), routing normally`);
         } catch (pairErr) {
           log(`PATH C: Pairing error (falling through): ${pairErr.message}`);
-          // Fall through to normal routing — employee gets regular agent response
         }
       }
 
