[Design Discussion] Runtime User Disambiguation in Identifying Executor

[DonOmalVindula]

Related Feature Issue

#2019

Problem Summary

The identifying executor expects exactly one user to match the provided identifiers. When multiple users share the same identifier (e.g., two users with the same username), the executor fails with a generic error. There is no mechanism to resolve this ambiguity at runtime by prompting the user for additional distinguishing attributes.

---

High-Level Approach

• Introduce two explicit modes for the identifying executor: identify (current behavior, default) and resolve (disambiguation-enabled).
• In resolve mode, when multiple users match, the executor returns ExecUserInputRequired (triggering the onIncomplete flow path) instead of failing.
• The full list of matching users is stored internally and filtered in-memory on subsequent steps — only 1 database query is made.
• The flow definition drives disambiguation: the flow author configures which additional attributes to prompt for, how many disambiguation steps to allow, and what happens when disambiguation is exhausted.
• No changes to the flow engine are required — this leverages existing primitives (onIncomplete, input accumulation, executor modes).

---

Architecture Overview

Executor Modes

Mode	Behavior
identify (default)	Current behavior — fails if 0 or >1 users match. Backward compatible.
resolve	On ambiguity (>1 matches), stores candidate users internally and triggers onIncomplete path to collect additional attributes.

Not specifying a mode falls back to identify. Existing flows remain unaffected.

Disambiguation Lifecycle

Key design decisions:

• Single database query: Only step 1 queries the store. All subsequent steps filter the stored candidates in-memory by unmarshaling each user's Attributes (json.RawMessage) and comparing against new inputs.
• Step-by-step collection: One additional attribute at a time, controlled by the flow definition.
• No credential attributes: Password, OTP, etc. are never used for disambiguation.
• Generic errors only: The system never reveals "multiple users found" to the end user — it generically requests additional information to prevent user enumeration.

---

Flow Definition Structure

The flow author wires disambiguation using existing flow primitives — TASK_EXECUTION nodes with onIncomplete edges to PROMPT nodes:

{
    "id": "identify_user",
    "type": "TASK_EXECUTION",
    "executor": {
        "name": "IdentifyingExecutor",
        "mode": "resolve",
        "inputs": [
            {"identifier": "username", "type": "TEXT_INPUT", "required": true}
        ]
    },
    "onSuccess": "next_step",
    "onIncomplete": "prompt_disambiguate"
}

{
    "id": "prompt_disambiguate",
    "type": "PROMPT",
    "prompts": [{
        "inputs": [
            {"identifier": "firstName", "type": "TEXT_INPUT", "required": true}
        ],
        "action": {"nextNode": "identify_user_2"}
    }]
}

{
    "id": "identify_user_2",
    "type": "TASK_EXECUTION",
    "executor": {
        "name": "IdentifyingExecutor",
        "mode": "resolve",
        "inputs": [
            {"identifier": "username", "type": "TEXT_INPUT", "required": true},
            {"identifier": "firstName", "type": "TEXT_INPUT", "required": true}
        ]
    },
    "onSuccess": "next_step",
    "onFailure": "error_node"
}

Each identifying executor node declares its own set of inputs. The flow engine's existing input accumulation (prepareContext merge) ensures all previously submitted inputs are available to subsequent nodes.

What the flow author controls

• Which attributes to ask for at each disambiguation step (via prompt node inputs)
• Which attributes the executor uses for searching/filtering (via executor node inputs)
• How many disambiguation steps to allow (by chaining executor → prompt → executor nodes)
• What happens when disambiguation fails (via onFailure on the final executor node)

---

Leveraging Existing Flow Engine Capabilities

This design requires no changes to the flow engine:

Capability	How it's used	Already exists?
ExecUserInputRequired → onIncomplete path	Triggers disambiguation prompt	✅
Input accumulation via prepareContext()	Preserves all inputs across steps	✅
Executor modes (ctx.ExecutorMode)	Switches between identify/resolve	✅ (SMS OTP, Passkey)
Per-node input overrides (ctx.NodeInputs)	Different inputs per executor node	✅
RuntimeData persistence	Stores candidate users across steps	✅

---

Store Layer: Differentiating 0 vs >1 Results

Currently IdentifyUser returns a generic error for both "0 results" and ">1 results". This design introduces:

• A distinct ErrAmbiguousUser sentinel error for the >1 case (in existing IdentifyUser)
• A new SearchUsers method that returns full user objects for all matches (used by resolve mode)

The existing IdentifyUser remains unchanged in signature and behavior for all current callers.

---

Frontend Flow Builder

The flow builder UI needs to:

• Allow switching the identifying executor's mode between identify and resolve (following the existing pattern used by SMS OTP and Passkey executor mode dropdowns)
• The prompt node configuration and onIncomplete edge wiring already work with the existing builder UI

---

Security Considerations

• No information leakage: Error messages are generic ("additional information required") — never "multiple users found". This prevents user enumeration attacks.
• No credential-based disambiguation: Password, OTP, and other sensitive inputs are excluded from disambiguation filters.
• Rate limiting: Can be added as a future improvement to prevent enumeration via repeated disambiguation attempts.
• Short-lived data: Candidate user data stored in RuntimeData is cleaned up when the flow session ends.

---

Questions for Discussion

1. Should we impose a maximum number of disambiguation steps to prevent infinite loops, or is the flow definition's finite node graph sufficient?
2. Should the resolve mode support a fallback behavior when all configured disambiguation steps are exhausted but ambiguity persists (e.g., configurable error message)?
3. Are there attribute types that should be explicitly excluded from disambiguation filters beyond credentials (e.g., system-managed attributes)?