Digital Worker Phase 1.5 — Self-Service Identity Verification Design

Summary

Self-service identity verification inverts who does the work: instead of an admin sourcing opaque platform IDs by hand, the user proves ownership by DMing the worker a short-lived, single-use code, and the inbound webhook supplies the authoritative external_user_id. The output is the same verified dw_external_identities row Phase 1 already trusts — only enrollment changes, the security gate does not.

• Phase 1.5 — promotes the deferred Phase 1 DM-code challenge
• Providers (v1) Telegram (gold path) + WhatsApp; Discord stays admin-assert
• New surface One table + one resolution branch; no new transport
• New ADRs 0035 · 0036

Scope & goals

Success criteria

• A user with no prior mapping self-verifies in one tap, no ID copying.
• An admin fans out invite links/QRs to a roster and watches state advance live ("7 of 12 verified").
• Every issued code, consumption, expiry, and failure is auditable.
• An unverified messager is told how to verify, without leaking whether any identity is known.
• No path produces a verified row without a live, unconsumed, correctly-bound code.

Key decisions

Provider matrix — how initiation differs

The resolution is identical once a message lands; only the way a user is steered into the DM and how much can be prefilled varies.

Data model

dw_verification_codes

One row per issued challenge, binding an opaque high-entropy token to exactly one Gremlin user, one org, and (optionally) a target provider.

Indexes: UNIQUE (code_lookup); (org_id, gremlin_user_id, status); partial index WHERE status = 'pending' for the resolver hot path.

Atomic consume

Success is a single guarded UPDATE that flips pending → consumed and, in the same transaction, inserts the identity row. Zero rows updated = failed attempt.

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 — dedicated insert branch

After a successful consume returns U, with (org, provider, Y) from the envelope, the branch resolves the existing mapping first:

If U already holds a different verified external id for this provider, treat as flag-for-admin / no auto-add (possible account change). Structural backstop: ON CONFLICT DO NOTHING.

Pre-provisioning — codes-only

Issuance authorization

A code is a bearer token that, on consume, writes (consumed_external_user_id → gremlin_user_id) — so whoever controls gremlin_user_id at issue time controls which chat account can become which Gremlin user.

The residual "admin issues for V, link leaks to an attacker" exposure is exactly the accepted TTL + single-use bearer-link risk (same trust model as a click-to-verify email), which is why invites go out through the panel/email, never as bot-initiated messages.

Resolution logic — webhook to verified row

In EventProcessor.Process the branch slots after the !res.NeedsAIPath early-return and before policy.Evaluate. That placement buys three properties for free:

1. Audited first

   ingest.Ingest has already written the received dw_chat_events row, so the verification DM is logged before the branch touches it.

2. Two races, two guards

   A re-delivered same DM is filtered as Duplicate (transport idempotency); the atomic DB consume independently guards the different-message-same-code race.

3. Intercept before default-deny

   The not-yet-mapped sender never reaches policy.Evaluate, which would otherwise correctly deny them.

The logic lives behind an optional verification dependency on EventProcessor (nil disables, mirroring sender/learning). New IngestDecision terminal values verified and denied_verification keep verification DMs out of the decision IN ('received','processed') extraction/context windows.

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"]
    

Deciding "is this a verification attempt?" — cheaply, before any AI

• Telegram — the message is literally /start <payload> (or /verify <code>); deterministic string match, the payload is the candidate token.
• WhatsApp — the prefilled body carries a namespaced sentinel prefix, so a plain text DM is distinguishable. Free-typed look-alikes simply fail the atomic consume — safe by construction.
• Discord (deferred) — would be a /verify slash command or a sentinel-prefixed DM, but Discord self-service is out of scope (Gateway-only ingest).

Slotting into the safe-vs-consequential model (ADR-0029)

The DM-challenge is composed entirely of safe-executable actions — the user initiated it, and the worker is not acting on the org's behalf.

The crucial line: verification establishes who a chat identity is; it never establishes what they may do. Capabilities, approval gates, and AccessGate behavior are untouched — a freshly self-verified user can do precisely what their Gremlin role allows, no more.

Onboarding surfaces (panel)

Sequenced by leverage-per-effort:

1. Per-user invite link / QR

   On the channel-binding or member screen, generate a code and get a wa.me / t.me?start= link plus QR (Telegram/WhatsApp only; Discord uses admin-assert). The backbone.

2. Bulk "invite the team"

   Fan out pre-provisioned links to the known roster; the screen shows live verification state per member.

3. Self-explaining first contact

   Wire the unverified-solicited reply so every failed interaction becomes a recovery path.

4. Guided binding wizard

   Walk create-role-agent → soul → bind-channel → capabilities → verify-members with a live "N of M verified" counter.

Error handling

Safety & security

• Output is still a verified row. Nothing weakens UNIQUE (organization_id, provider, external_user_id) + status='verified'; only enrollment changed.
• Store only the keyed hash. Persist a single code_lookup = HMAC-SHA256(token, server_pepper) and match on it; never store the raw token, a second hash, or log either.
• Single-use, short-TTL, atomic consume. Closes replay and the concurrent double-bind race.
• No oracle. Every failure returns the same generic message. Per-sender rate limit is a windowed COUNT of denied-verification dw_chat_events keyed on (org_id, provider, external_user_id) (e.g. >5 in 10 min) → suppress the reply. No new table; reuse the events already written, with a supporting index if hot.
• Self-binding ≠ self-elevation. Verification grants identity, not capability (ADR-0029/0032).
• Reuse the gate downstream. The moment the row exists, the Phase 2 auto-save poisoning defense and Phase 3 owner-coercion rule apply automatically.
• Audit everything. Issue/consume/revoke and every failed attempt land in audit per ADR-0007 (human actions → audit_log; observability → dw_chat_events).

Rollout plan

Every step is reversible and additive; none alters the Phase 1 gate.

1. Schema + resolver

   Add dw_verification_codes, the atomic-consume branch, the pre-identity webhook check. Telegram /start first.

2. WhatsApp initiation

   wa.me prefill sentinel (Discord stays admin-assert).

3. Invite link / QR

   Per-user link + QR in the panel; success/failure safe replies.

4. First contact

   Unverified-solicited hint, rate-limited.

5. Bulk + live state

   Roster fan-out, "N of M verified".

6. Guided wizard

   Fold the above into an ordered setup flow.

New ADRs introduced

Builds on: ADR-0023 (single-owner lease, Discord Gateway), ADR-0029 (safe-vs-consequential + verified identity), ADR-0031 (direct provider integration), ADR-0032 (identity/memory is context not authority), ADR-0007 (two audit systems).

Open questions