Digital Worker Phase 1.5 — Self-Service Identity Verification Design

概述

自助式身份验证颠倒了"谁来干活"：不再由管理员手动获取不透明的平台 ID，而是由用户通过向 worker 私信一个短时效、一次性的验证码来证明所有权，入站 webhook 则提供权威的 external_user_id。 其产出仍是 Phase 1 早已信任的同一行已验证 dw_external_identities —— 只是入册方式变了， 安全闸门并未改变。

• 阶段 1.5 —— 将 Phase 1 中被推迟的 DM 验证码挑战正式落地
• 提供方（v1） Telegram（黄金路径）+ WhatsApp；Discord 仍走管理员断言
• 新增面 一张表 + 一个解析分支；不新增任何传输通道
• 新增 ADR 0035 · 0036

范围与目标

成功标准

• 此前没有任何映射的用户，一次点击即可自助验证，无需复制 ID。
• 管理员把邀请链接/二维码分发给一份名册，并实时观察状态推进（"12 人中已验证 7 人"）。
• 每一次验证码签发、消费、过期与失败都可审计。
• 未验证的发送者会被告知如何验证，且不会泄露是否已知任何身份。
• 没有任何路径能在缺少一个存活、未消费、绑定正确的验证码的情况下产出 verified 记录。

关键决策

提供方矩阵 —— 发起方式的差异

一旦消息落地，解析过程完全一致；只有把用户引导进私信的方式、以及可预填的内容多少有所不同。

数据模型

dw_verification_codes

每签发一次挑战即一行，把一个不透明的高熵令牌精确绑定到一个 Gremlin 用户、一个组织，以及（可选的）一个目标提供方。

索引：UNIQUE (code_lookup)；(org_id, gremlin_user_id, status)；为解析器热路径建立的部分索引 WHERE status = 'pending'。

原子消费

成功即一条带守卫的 UPDATE，把 pending → consumed，并在同一事务中插入身份行。更新到零行即失败尝试。

UPDATE dw_verification_codes SET status='consumed', consumed_at=now(),
       consumed_external_user_id=$uid, consumed_provider=$provider
WHERE code_lookup=$1 AND org_id=$worker_org AND status='pending'
      AND expires_at>now() AND (target_provider IS NULL OR target_provider=$provider)
RETURNING gremlin_user_id, role_agent_id;

dw_external_identities —— 专用插入分支

当一次成功消费返回 U 后，结合信封中的 (org, provider, Y)，该分支先解析已有映射：

若 U 在该提供方上已持有一个不同的已验证 external id，按标记给管理员 / 不自动新增处理（可能是账号变更）。结构性兜底：ON CONFLICT DO NOTHING。

预置 —— 仅验证码

签发授权

验证码是一种持有者令牌，消费时会写入 (consumed_external_user_id → gremlin_user_id) —— 因此谁在签发时控制 gremlin_user_id，谁就控制了哪个聊天账号能成为哪个 Gremlin 用户。

"管理员为 V 签发，链接却泄露给攻击者"这一残余暴露，恰好就是我们接受的 TTL + 一次性持有者链接风险（与点击验证邮件同一信任模型），这也是为什么邀请通过面板/邮件发出，而绝不以 bot 主动发起的消息发出。

解析逻辑 —— 从 webhook 到已验证记录

在 EventProcessor.Process 中，该分支恰好插在 !res.NeedsAIPath 早返回之后、policy.Evaluate 之前。这一摆位免费换来三项性质：

1. 先被审计

   ingest.Ingest 已写入 received 的 dw_chat_events 行，因此验证私信在分支动它之前就被记录。

2. 两种竞态，两道守卫

   被重复投递的同一条私信会被作为 Duplicate 过滤（传输幂等）；而原子 DB 消费独立地守护不同消息同一验证码的竞态。

3. 在默认拒绝之前拦截

   尚未映射的发送者永远到不了 policy.Evaluate —— 否则那里本会（正确地）拒绝他们。

该逻辑位于 EventProcessor 上的一个可选 verification 依赖之后（为 nil 即禁用，与 sender/learning 一致）。新的 IngestDecision 终态值 verified 和 denied_verification 把验证私信挡在 decision IN ('received','processed') 的抽取/上下文窗口之外。

flowchart TD
    wh["Inbound webhook event"] --> norm["Normalize to dw_chat_events (cheap ingest)"]
    norm --> vcheck{"Is this a verification attempt?"}
    vcheck -->|"yes: /start, prefilled code, or /verify"| extract["Extract candidate token"]
    extract --> match{"Atomic consume: pending, unexpired, org-ok, provider-ok?"}
    match -->|"hit"| write["TX: code to consumed + INSERT verified identity"]
    write --> ack["Safe reply: you are verified (solicited)"]
    write --> audit1["Audit: identity_verified_self_service"]
    match -->|"miss / expired / revoked"| denyv["denied_verification event; attempt_count++"]
    denyv --> hint["Safe reply: generic invalid-or-expired hint (rate-limited)"]
    vcheck -->|"no"| resolve["Phase 1 identity resolution (unchanged)"]
    resolve -->|"verified"| policy["Capability policy: mention / proactive"]
    resolve -->|"miss"| unknown["Phase 1 default-deny: unknown_user"]
    unknown -.->|"solicited DM/mention only"| firstcontact["Safe reply: verify-here hint"]
    

如何在任何 AI 之前廉价判断"这是不是一次验证尝试？"

• Telegram —— 消息字面上就是 /start <payload>（或 /verify <code>）；确定性字符串匹配，payload 即候选令牌。
• WhatsApp —— 预填正文带有命名空间哨兵前缀，因此一条纯文本私信可被区分。自由键入的仿冒只会在原子消费时失败 —— 从构造上安全。
• Discord （推迟） —— 本应是 /verify 斜杠命令或带哨兵前缀的私信，但 Discord 自助不在范围内（仅 Gateway 入站）。

嵌入"安全 vs 有后果"模型（ADR-0029）

DM 挑战完全由安全可执行动作组成 —— 由用户发起，且 worker 并非代表组织行事。

关键一句：验证确立一个聊天身份是谁；它从不确立他们可做什么。 能力、审批闸门与 AccessGate 行为均未触动 —— 一个刚刚自助验证的用户，能做的恰好就是其 Gremlin 角色所允许的，不多一分。

入职界面（面板）

按"单位投入产出的杠杆"排序：

1. 按用户邀请链接 / 二维码

   在渠道绑定或成员界面，生成一个验证码并得到 wa.me / t.me?start= 链接外加二维码（仅 Telegram/WhatsApp；Discord 用管理员断言）。这是主干。

2. 批量"邀请整个团队"

   向已知名册分发预置链接；界面按成员展示实时验证状态。

3. 自解释式首次接触

   接好"未验证—被邀约"回复，让每次失败的互动都成为一条恢复路径。

4. 引导式绑定向导

   带着实时"M 中 N 人已验证"计数器，走完 建 role-agent → soul → 绑渠道 → 能力 → 验证成员。

错误处理

安全与防护

• 产出仍是一行已验证记录。没有任何东西削弱 UNIQUE (organization_id, provider, external_user_id) + status='verified'；改变的只是入册。
• 只存带 key 的哈希。持久化单个 code_lookup = HMAC-SHA256(token, server_pepper) 并以此匹配；从不存储原始令牌、第二个哈希，也不记录二者。
• 一次性、短 TTL、原子消费。封住重放与并发双绑定竞态。
• 无 oracle。每次失败都返回同一句通用消息。按发送者限流即对被拒绝验证 dw_chat_events 按 (org_id, provider, external_user_id) 做窗口 COUNT（如 10 分钟内 >5 次）→ 抑制回复。无需新表；复用已写入的事件，必要时加一个支撑索引。
• 自我绑定 ≠ 自我提权。验证授予的是身份，不是能力（ADR-0029/0032）。
• 下游复用闸门。记录一旦存在，Phase 2 的自动保存投毒防御与 Phase 3 的属主强制规则便自动生效。
• 事事审计。签发/消费/撤销以及每一次失败尝试都按 ADR-0007 落账（人类动作 → audit_log；可观测性 → dw_chat_events）。

上线计划

每一步都可逆且为增量；没有一步改动 Phase 1 闸门。

1. Schema + 解析器

   加 dw_verification_codes、原子消费分支、身份解析前的 webhook 检查。先做 Telegram /start。

2. WhatsApp 发起

   wa.me 预填哨兵（Discord 仍走管理员断言）。

3. 邀请链接 / 二维码

   面板内按用户链接 + 二维码；成功/失败安全回复。

4. 首次接触

   未验证—被邀约提示，限流。

5. 批量 + 实时状态

   名册分发，"M 中 N 人已验证"。

6. 引导向导

   把上述折叠进一条有序的设置流程。

新增的 ADR

建立在：ADR-0023（单属者租约，Discord Gateway）、ADR-0029（安全 vs 有后果 + 已验证身份）、ADR-0031（直连提供方集成）、ADR-0032（身份/记忆是上下文而非权威）、ADR-0007（两套审计系统）之上。

待解问题