fix(flows): report an entry position, not the caller's step id

A step id is a caller-controlled key, and these rejections reach the usage
log unmasked the same way a value would. Nothing echoed a NESTED caller key
before this directive existed — the walker's supplied_keys reports only
top-level names — so this was new exposure rather than an existing one.

Errors now name the entry's position (step_values entry #2) and its types.
That still says which entry is wrong, and cannot carry anything the caller
typed.

Found by CodeRabbit review on homeassistant-ai#2256.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012d29UJTiH4Uy2Pm37SBPtr

Author: kingpanther13

src/ha_mcp/tools/config_entry_flow_form.py

@@ -883,21 +883,27 @@ def validate_step_values(config: dict[str, Any]) -> None:
             )
         )
 
-    for step_id, entry in directive.items():
+    # The step id is a caller-controlled key, and nothing echoed a NESTED one
+    # before this directive existed — the walker's own supplied_keys reports
+    # only top-level names. These errors reach the usage log unmasked (see the
+    # note above), so report the entry's POSITION instead: it is what the
+    # caller needs to find the entry in their own directive, and it cannot
+    # carry a value they typed (CodeRabbit review, issue #2254).
+    for index, entry in enumerate(directive.values(), start=1):
+        where = f"{_PER_STEP_VALUES_KEY} entry #{index}"
         entries = entry if isinstance(entry, list) else [entry]
         if any(not isinstance(item, dict) for item in entries):
             raise_tool_error(
                 create_error_response(
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    f"'{_PER_STEP_VALUES_KEY}[{step_id!r}]' must be an object "
-                    "of field values, or a list of them for a step the flow "
-                    "presents more than once",
+                    f"{where} must be an object of field values, or a list "
+                    "of them for a step the flow presents more than once",
                     suggestions=[
                         f"Pass {_PER_STEP_VALUES_KEY}={example}, or a list of "
                         "those objects to supply one per encounter.",
                     ],
                     context={
-                        "step_id": step_id,
+                        "entry_index": index,
                         "entry_types": [type(item).__name__ for item in entries],
                     },
                 )
@@ -911,12 +917,11 @@ def validate_step_values(config: dict[str, Any]) -> None:
             raise_tool_error(
                 create_error_response(
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    f"'{_PER_STEP_VALUES_KEY}[{step_id!r}]' supplies no field "
-                    "values, so it would apply nothing",
+                    f"{where} supplies no field values, so it would apply nothing",
                     suggestions=[
                         "Name at least one field for the step, or drop the entry.",
                     ],
-                    context={"step_id": step_id, "entry_count": len(entries)},
+                    context={"entry_index": index, "entry_count": len(entries)},
                 )
             )
 

tests/src/unit/test_flow_options_preserve.py

@@ -1301,6 +1301,21 @@ def test_a_rejection_reports_shapes_not_submitted_values(self) -> None:
         assert "entry_types" in message
         assert "str" in message
 
+    def test_a_rejection_reports_a_position_not_the_step_id(self) -> None:
+        """A step id is a caller-controlled key and reaches the same log.
+
+        Nothing echoed a NESTED caller key before this directive existed —
+        the walker's supplied_keys reports only top-level names — so the
+        position is reported instead. It still says WHICH entry is wrong
+        without carrying anything the caller typed (CodeRabbit review).
+        """
+        secret = "sk-not-in-the-log"
+        with pytest.raises(ToolError) as exc_info:
+            validate_step_values({"step_values": {"init": {"a": 1}, secret: {}}})
+        message = str(exc_info.value)
+        assert secret not in message, "A step id reached the error payload"
+        assert "entry #2" in message, message
+
     async def test_the_walker_rejects_before_driving_any_step(self) -> None:
         """It must raise before a single step is submitted."""
         submit_fn = AsyncMock()