feat: add neutral auth store boundary

2026-06-06 10:18:16 +07:00
parent 71facde1a2
commit 34726433a8
15 changed files with 456 additions and 41 deletions
@@ -0,0 +1,929 @@
+# Auth Store Boundary Slice 1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a neutral auth record/store boundary and make current MCP auth loading prefer source `auth_ref` while preserving legacy connection-id behavior.
+
+**Architecture:** `wf_api` owns neutral auth ids, records, and the read-only auth-store protocol. `wf_mcp` keeps its current `AuthRecord` compatibility type, but adds adapter helpers that convert neutral records into MCP runtime records and centralize MCP payload interpretation. No diagnostics, admin mutation, OAuth, or secret-manager behavior in this slice.
+
+**Tech Stack:** Python 3.14, dataclasses, protocols, pytest, ruff, basedpyright.
+
+---
+
+## Scope
+
+Implement only:
+
+- neutral auth model/protocol in `wf_api`
+- MCP file-store adapter bridge
+- MCP runtime auth resolution by `metadata["auth_ref"]` with legacy fallback
+- central MCP auth payload interpretation helper
+
+Do not implement:
+
+- auth admin CLI/RPC/MCP tools
+- auth diagnostics in deployment validation
+- OAuth/browser flows
+- encrypted file format
+- source-provider packages beyond current `wf_mcp`
+
+## Files
+
+- Create: `src/wf_api/auth.py`
+  - neutral `AUTH_ID_PATTERN`
+  - `validate_auth_id`
+  - frozen `AuthRecord`
+  - read-only `AuthStore` protocol
+- Modify: `src/wf_api/__init__.py`
+  - export neutral auth symbols
+- Create: `tests/wf_api/test_auth.py`
+  - neutral auth model/protocol tests
+- Create: `src/wf_mcp/auth.py`
+  - adapter helpers between neutral auth and `wf_mcp.models.AuthRecord`
+  - centralized MCP header/env extraction
+- Modify: `src/wf_mcp/storage/store.py`
+  - add neutral `load_auth_record(auth_ref)` / `save_auth_record(record)` methods
+  - keep old `save_auth(AuthRecord)` / `load_auth(connection_id)` methods
+- Modify: `src/wf_mcp/broker/service/upstream_transport.py`
+  - add `load_connection_auth(connection)` helper
+  - update all `load_auth(connection.id)` call sites to use the helper
+  - keep `load_auth(connection_id)` facade for compatibility
+- Modify: `src/wf_mcp/broker/service/source_catalog.py`
+  - change `AuthLoader` from `Callable[[str], AuthRecord | None]` to `Callable[[ConnectionConfig], AuthRecord | None]`
+  - update hydrated wrapper calls to pass the connection object
+- Modify: `src/wf_mcp/broker/service/core.py`
+  - pass `self.upstream.load_connection_auth` to `SourceCatalogService`
+- Modify: `src/wf_mcp/sdk/adapter.py`
+  - replace local `_auth_headers` / env payload reads with `wf_mcp.auth` helpers
+- Modify: `src/wf_mcp/runtime/factory.py`
+  - replace local `_auth_headers` / env payload reads with `wf_mcp.auth` helpers
+- Test: `tests/wf_mcp/test_auth.py`
+  - adapter bridge tests
+- Test: `tests/wf_mcp/service/test_upstream_transport.py`
+  - `auth_ref` lookup / fallback tests
+- Test: existing focused suites listed below
+
+## Task 1: Neutral auth model and store protocol
+
+**Files:**
+- Create: `src/wf_api/auth.py`
+- Modify: `src/wf_api/__init__.py`
+- Create: `tests/wf_api/test_auth.py`
+
+- [ ] **Step 1: Write neutral auth tests**
+
+Create `tests/wf_api/test_auth.py`:
+
+```python
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import assert_type
+
+import pytest
+
+from wf_api.auth import AuthRecord, AuthStore, validate_auth_id
+
+
+def test_validate_auth_id_accepts_safe_dotted_ids() -> None:
+    assert validate_auth_id("github.work") == "github.work"
+    assert validate_auth_id("api_ci-1") == "api_ci-1"
+
+
+@pytest.mark.parametrize("auth_id", ["", ".hidden", "../secret", "bad/id"])
+def test_validate_auth_id_rejects_unsafe_ids(auth_id: str) -> None:
+    with pytest.raises(ValueError, match="auth id must start"):
+        validate_auth_id(auth_id)
+
+
+def test_auth_record_is_immutable_and_mapping_typed() -> None:
+    record = AuthRecord(
+        id="github.work",
+        scheme="bearer",
+        payload={"token": "secret"},
+        metadata={"owner": "test"},
+    )
+
+    assert record.id == "github.work"
+    assert record.scheme == "bearer"
+    assert record.payload["token"] == "secret"
+    assert_type(record.payload, Mapping[str, object])
+
+    with pytest.raises(AttributeError):
+        record.scheme = "headers"  # type: ignore[misc]
+
+
+class MemoryAuthStore:
+    def __init__(self, records: dict[str, AuthRecord]) -> None:
+        self.records = records
+
+    def load_auth(self, auth_ref: str) -> AuthRecord | None:
+        return self.records.get(auth_ref)
+
+
+def test_auth_store_protocol_is_read_only_lookup() -> None:
+    record = AuthRecord(id="github.work", scheme="opaque", payload={"x": 1})
+    store: AuthStore = MemoryAuthStore({"github.work": record})
+
+    assert store.load_auth("github.work") is record
+    assert store.load_auth("missing") is None
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+uv run pytest tests/wf_api/test_auth.py -q
+```
+
+Expected: fails because `wf_api.auth` does not exist.
+
+- [ ] **Step 3: Implement neutral auth module**
+
+Create `src/wf_api/auth.py`:
+
+```python
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Protocol
+
+AUTH_ID_PATTERN = r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$"
+
+
+def validate_auth_id(value: str) -> str:
+    """Validate auth refs that are safe as store keys and path segments.
+
+    Auth refs deliberately carry no provider semantics. Source providers decide
+    how a resolved auth record is interpreted.
+    """
+
+    if not re.fullmatch(AUTH_ID_PATTERN, value):
+        raise ValueError(
+            "auth id must start with alphanumeric or underscore and contain "
+            "only [A-Za-z0-9_.-]"
+        )
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class AuthRecord:
+    """Neutral credential record resolved by auth ref.
+
+    `scheme + payload` is a compatibility bridge, not the long-term taxonomy.
+    Keep payload interpretation inside provider adapters so a future
+    discriminated union can replace this without touching workflow/config code.
+    """
+
+    id: str
+    scheme: str
+    payload: Mapping[str, object]
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        validate_auth_id(self.id)
+        if not self.scheme:
+            raise ValueError("auth scheme must be non-empty")
+
+
+class AuthStore(Protocol):
+    """Read-only runtime credential lookup by auth ref."""
+
+    def load_auth(self, auth_ref: str) -> AuthRecord | None: ...
+
+
+__all__ = [
+    "AUTH_ID_PATTERN",
+    "AuthRecord",
+    "AuthStore",
+    "validate_auth_id",
+]
+```
+
+- [ ] **Step 4: Export from `wf_api`**
+
+Modify `src/wf_api/__init__.py`:
+
+```python
+from .auth import AUTH_ID_PATTERN, AuthRecord, AuthStore, validate_auth_id
+```
+
+Add these entries to `__all__`:
+
+```python
+"AUTH_ID_PATTERN",
+"AuthRecord",
+"AuthStore",
+"validate_auth_id",
+```
+
+- [ ] **Step 5: Run focused tests**
+
+Run:
+
+```bash
+uv run pytest tests/wf_api/test_auth.py tests/wf_api/test_import_direction.py -q
+uv run ruff check src/wf_api/auth.py tests/wf_api/test_auth.py
+uv run basedpyright --level error src/wf_api tests/wf_api/test_auth.py
+```
+
+Expected: all pass.
+
+## Task 2: MCP auth adapter helpers
+
+**Files:**
+- Create: `src/wf_mcp/auth.py`
+- Create: `tests/wf_mcp/test_auth.py`
+
+- [ ] **Step 1: Write MCP adapter tests**
+
+Create `tests/wf_mcp/test_auth.py`:
+
+```python
+from __future__ import annotations
+
+from wf_api.auth import AuthRecord as NeutralAuthRecord
+from wf_mcp.auth import (
+    mcp_auth_env,
+    mcp_auth_headers,
+    mcp_auth_from_neutral,
+    neutral_auth_from_mcp,
+)
+from wf_mcp.models import AuthRecord as McpAuthRecord
+
+
+def test_mcp_auth_from_neutral_preserves_scheme_and_payload() -> None:
+    neutral = NeutralAuthRecord(
+        id="github.work",
+        scheme="bearer",
+        payload={"token": "secret"},
+        metadata={"owner": "test"},
+    )
+
+    mcp = mcp_auth_from_neutral(neutral)
+
+    assert mcp == McpAuthRecord(
+        connection_id="github.work",
+        scheme="bearer",
+        payload={"token": "secret"},
+    )
+
+
+def test_neutral_auth_from_mcp_preserves_payload() -> None:
+    mcp = McpAuthRecord(
+        connection_id="github.work",
+        scheme="headers",
+        payload={"headers": {"X-Test": "yes"}},
+    )
+
+    neutral = neutral_auth_from_mcp(mcp)
+
+    assert neutral.id == "github.work"
+    assert neutral.scheme == "headers"
+    assert neutral.payload == {"headers": {"X-Test": "yes"}}
+
+
+def test_mcp_auth_headers_extracts_explicit_headers_and_bearer_token() -> None:
+    auth = McpAuthRecord(
+        connection_id="api.work",
+        scheme="bearer",
+        payload={"headers": {"X-Test": "yes"}, "token": "secret"},
+    )
+
+    assert mcp_auth_headers(auth) == {
+        "X-Test": "yes",
+        "Authorization": "Bearer secret",
+    }
+
+
+def test_mcp_auth_headers_does_not_override_authorization_header() -> None:
+    auth = McpAuthRecord(
+        connection_id="api.work",
+        scheme="bearer",
+        payload={
+            "headers": {"Authorization": "Basic already"},
+            "token": "secret",
+        },
+    )
+
+    assert mcp_auth_headers(auth) == {"Authorization": "Basic already"}
+
+
+def test_mcp_auth_env_returns_string_map_only() -> None:
+    auth = McpAuthRecord(
+        connection_id="mcp.local",
+        scheme="env",
+        payload={"env": {"TOKEN": "secret", "BAD": 123}},
+    )
+
+    assert mcp_auth_env(auth) == {"TOKEN": "secret"}
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/test_auth.py -q
+```
+
+Expected: fails because `wf_mcp.auth` does not exist.
+
+- [ ] **Step 3: Implement MCP adapter module**
+
+Create `src/wf_mcp/auth.py`:
+
+```python
+from __future__ import annotations
+
+from wf_api.auth import AuthRecord as NeutralAuthRecord
+
+from .models import AuthRecord as McpAuthRecord
+
+
+def mcp_auth_from_neutral(record: NeutralAuthRecord) -> McpAuthRecord:
+    """Adapt neutral auth to the current MCP compatibility record."""
+
+    return McpAuthRecord(
+        connection_id=record.id,
+        scheme=record.scheme,
+        payload=dict(record.payload),
+    )
+
+
+def neutral_auth_from_mcp(record: McpAuthRecord) -> NeutralAuthRecord:
+    """Adapt legacy MCP auth into the neutral record shape."""
+
+    return NeutralAuthRecord(
+        id=record.connection_id,
+        scheme=record.scheme,
+        payload=dict(record.payload),
+    )
+
+
+def mcp_auth_headers(auth: McpAuthRecord | None) -> dict[str, str]:
+    """Return HTTP headers understood by MCP HTTP transports.
+
+    This is intentionally MCP-specific. Neutral code must not inspect payload
+    keys such as `headers` or `token`.
+    """
+
+    if auth is None:
+        return {}
+    raw_headers = auth.payload.get("headers", {})
+    headers = {
+        str(key): str(value)
+        for key, value in raw_headers.items()
+        if isinstance(key, str) and isinstance(value, str)
+    } if isinstance(raw_headers, dict) else {}
+    token = auth.payload.get("token")
+    if isinstance(token, str) and "Authorization" not in headers:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def mcp_auth_env(auth: McpAuthRecord | None) -> dict[str, str]:
+    """Return environment variables understood by MCP stdio transports."""
+
+    if auth is None:
+        return {}
+    raw_env = auth.payload.get("env", {})
+    if not isinstance(raw_env, dict):
+        return {}
+    return {
+        str(key): str(value)
+        for key, value in raw_env.items()
+        if isinstance(key, str) and isinstance(value, str)
+    }
+
+
+__all__ = [
+    "mcp_auth_env",
+    "mcp_auth_from_neutral",
+    "mcp_auth_headers",
+    "neutral_auth_from_mcp",
+]
+```
+
+- [ ] **Step 4: Run focused tests**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/test_auth.py -q
+uv run ruff check src/wf_mcp/auth.py tests/wf_mcp/test_auth.py
+uv run basedpyright --level error src/wf_mcp/auth.py tests/wf_mcp/test_auth.py
+```
+
+Expected: all pass.
+
+## Task 3: Store adapter bridge
+
+**Files:**
+- Modify: `src/wf_mcp/storage/store.py`
+- Modify: `tests/wf_mcp/test_auth.py`
+
+- [ ] **Step 1: Add store bridge tests**
+
+Append to `tests/wf_mcp/test_auth.py`:
+
+```python
+from pathlib import Path
+
+from wf_mcp.storage import FileStore
+
+
+def test_file_store_saves_and_loads_neutral_auth_record(tmp_path: Path) -> None:
+    store = FileStore(tmp_path)
+    record = NeutralAuthRecord(
+        id="github.work",
+        scheme="bearer",
+        payload={"token": "secret"},
+        metadata={"owner": "test"},
+    )
+
+    store.save_auth_record(record)
+
+    loaded = store.load_auth_record("github.work")
+    assert loaded == record
+
+
+def test_file_store_legacy_auth_methods_still_work(tmp_path: Path) -> None:
+    store = FileStore(tmp_path)
+    legacy = McpAuthRecord(
+        connection_id="github.work",
+        scheme="bearer",
+        payload={"token": "secret"},
+    )
+
+    store.save_auth(legacy)
+
+    assert store.load_auth("github.work") == legacy
+    assert store.load_auth_record("github.work") == NeutralAuthRecord(
+        id="github.work",
+        scheme="bearer",
+        payload={"token": "secret"},
+    )
+```
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/test_auth.py::test_file_store_saves_and_loads_neutral_auth_record tests/wf_mcp/test_auth.py::test_file_store_legacy_auth_methods_still_work -q
+```
+
+Expected: fails because `FileStore.save_auth_record` / `load_auth_record` do not exist.
+
+- [ ] **Step 3: Extend store interface and file store**
+
+Modify `src/wf_mcp/storage/store.py`:
+
+Add imports:
+
+```python
+from wf_api.auth import AuthRecord as NeutralAuthRecord
+
+from ..auth import mcp_auth_from_neutral, neutral_auth_from_mcp
+```
+
+Add to `class Store`:
+
+```python
+    def save_auth_record(self, record: NeutralAuthRecord) -> None:
+        raise NotImplementedError
+
+    def load_auth_record(self, auth_ref: str) -> NeutralAuthRecord | None:
+        raise NotImplementedError
+```
+
+Add to `class FileStore`:
+
+```python
+    def save_auth_record(self, record: NeutralAuthRecord) -> None:
+        """Save neutral auth through the legacy MCP file shape."""
+
+        self.save_auth(mcp_auth_from_neutral(record))
+
+    def load_auth_record(self, auth_ref: str) -> NeutralAuthRecord | None:
+        """Load neutral auth from the legacy MCP file shape."""
+
+        record = self.load_auth(auth_ref)
+        if record is None:
+            return None
+        return neutral_auth_from_mcp(record)
+```
+
+Do not change the existing on-disk JSON shape in this task.
+
+- [ ] **Step 4: Run focused tests**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/test_auth.py -q
+uv run ruff check src/wf_mcp/storage/store.py tests/wf_mcp/test_auth.py
+uv run basedpyright --level error src/wf_mcp/storage/store.py tests/wf_mcp/test_auth.py
+```
+
+Expected: all pass.
+
+## Task 4: Runtime auth resolution by auth_ref with fallback
+
+**Files:**
+- Modify: `src/wf_mcp/broker/service/upstream_transport.py`
+- Modify: `src/wf_mcp/broker/service/source_catalog.py`
+- Modify: `src/wf_mcp/broker/service/core.py`
+- Modify: `tests/wf_mcp/service/test_upstream_transport.py`
+
+- [ ] **Step 1: Add upstream resolution tests**
+
+Open `tests/wf_mcp/service/test_upstream_transport.py`. Add imports if missing:
+
+```python
+from pathlib import Path
+
+from wf_mcp.models import AuthRecord, ConnectionConfig
+from wf_mcp.storage import FileStore
+```
+
+Add helper if the file does not already have one:
+
+```python
+def _transport(root: Path) -> UpstreamTransportService:
+    events: list[object] = []
+    return UpstreamTransportService(
+        store=FileStore(root),
+        event_sink=events.append,
+    )
+```
+
+Add tests:
+
+```python
+def test_upstream_load_connection_auth_prefers_auth_ref(tmp_path: Path) -> None:
+    service = _transport(tmp_path)
+    service.save_auth(
+        AuthRecord(
+            connection_id="github.creds",
+            scheme="bearer",
+            payload={"token": "secret"},
+        )
+    )
+    service.save_auth(
+        AuthRecord(
+            connection_id="github.work",
+            scheme="bearer",
+            payload={"token": "wrong"},
+        )
+    )
+    connection = ConnectionConfig(
+        id="github.work",
+        server="github",
+        account="work",
+        metadata={"auth_ref": "github.creds"},
+    )
+
+    assert service.load_connection_auth(connection) == AuthRecord(
+        connection_id="github.creds",
+        scheme="bearer",
+        payload={"token": "secret"},
+    )
+
+
+def test_upstream_load_connection_auth_falls_back_to_connection_id(
+    tmp_path: Path,
+) -> None:
+    service = _transport(tmp_path)
+    service.save_auth(
+        AuthRecord(
+            connection_id="github.work",
+            scheme="bearer",
+            payload={"token": "legacy"},
+        )
+    )
+    connection = ConnectionConfig(
+        id="github.work",
+        server="github",
+        account="work",
+    )
+
+    assert service.load_connection_auth(connection) == AuthRecord(
+        connection_id="github.work",
+        scheme="bearer",
+        payload={"token": "legacy"},
+    )
+
+
+def test_upstream_load_connection_auth_ignores_non_string_auth_ref(
+    tmp_path: Path,
+) -> None:
+    service = _transport(tmp_path)
+    service.save_auth(
+        AuthRecord(
+            connection_id="github.work",
+            scheme="bearer",
+            payload={"token": "legacy"},
+        )
+    )
+    connection = ConnectionConfig(
+        id="github.work",
+        server="github",
+        account="work",
+        metadata={"auth_ref": 123},
+    )
+
+    assert service.load_connection_auth(connection) == AuthRecord(
+        connection_id="github.work",
+        scheme="bearer",
+        payload={"token": "legacy"},
+    )
+```
+
+If the file already has a helper for `UpstreamTransportService`, use it instead
+of adding `_transport`.
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/service/test_upstream_transport.py -q
+```
+
+Expected: fails because `load_connection_auth` does not exist.
+
+- [ ] **Step 3: Implement `load_connection_auth`**
+
+Modify `src/wf_mcp/broker/service/upstream_transport.py`.
+
+Add method to `UpstreamTransportService` after `load_auth`:
+
+```python
+    def load_connection_auth(self, connection: ConnectionConfig) -> AuthRecord | None:
+        """Resolve auth for a connection, preferring explicit source auth_ref.
+
+        Legacy MCP auth records are keyed by connection id. New source registry
+        and neutral config entries carry `auth_ref`; keep both paths until the
+        old compatibility surface has no callers.
+        """
+
+        auth_ref = connection.metadata.get("auth_ref")
+        if isinstance(auth_ref, str):
+            return self.load_auth(auth_ref)
+        return self.load_auth(connection.id)
+```
+
+- [ ] **Step 4: Replace direct connection-id auth lookups in upstream transport**
+
+In `src/wf_mcp/broker/service/upstream_transport.py`, replace these patterns:
+
+```python
+auth = self.load_auth(connection.id)
+```
+
+with:
+
+```python
+auth = self.load_connection_auth(connection)
+```
+
+Also replace the live-check lookup:
+
+```python
+auth = self.load_auth(source_id)
+```
+
+with:
+
+```python
+auth = self.load_connection_auth(connection)
+```
+
+Keep `load_auth(connection_id)` unchanged as a compatibility facade.
+
+- [ ] **Step 5: Update source catalog auth callback**
+
+Modify `src/wf_mcp/broker/service/source_catalog.py`.
+
+Change:
+
+```python
+AuthLoader = Callable[[str], AuthRecord | None]
+```
+
+to:
+
+```python
+AuthLoader = Callable[[ConnectionConfig], AuthRecord | None]
+```
+
+Inside `spec_from_snapshot_entry.invoke_tool`, change:
+
+```python
+connection = self.connection_lookup(entry.connection_id)
+auth = self.load_auth(entry.connection_id)
+```
+
+to:
+
+```python
+connection = self.connection_lookup(entry.connection_id)
+auth = self.load_auth(connection)
+```
+
+- [ ] **Step 6: Wire source catalog to the new resolver**
+
+Modify `src/wf_mcp/broker/service/core.py`.
+
+In `SourceCatalogService(...)` construction, change:
+
+```python
+load_auth=self.upstream.load_auth,
+```
+
+to:
+
+```python
+load_auth=self.upstream.load_connection_auth,
+```
+
+- [ ] **Step 7: Run focused tests**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/service/test_upstream_transport.py tests/wf_mcp/service/test_catalog.py tests/wf_mcp/service/test_workflow_runtime.py -q
+uv run ruff check src/wf_mcp/broker/service/upstream_transport.py src/wf_mcp/broker/service/source_catalog.py src/wf_mcp/broker/service/core.py tests/wf_mcp/service/test_upstream_transport.py
+uv run basedpyright --level error src/wf_mcp/broker/service tests/wf_mcp/service/test_upstream_transport.py
+```
+
+Expected: all pass.
+
+## Task 5: Centralize MCP payload interpretation
+
+**Files:**
+- Modify: `src/wf_mcp/sdk/adapter.py`
+- Modify: `src/wf_mcp/runtime/factory.py`
+- Test: existing MCP auth/runtime tests
+
+- [ ] **Step 1: Update SDK adapter imports**
+
+Modify `src/wf_mcp/sdk/adapter.py`.
+
+Add import:
+
+```python
+from ..auth import mcp_auth_env, mcp_auth_headers
+```
+
+Delete local `_auth_headers`.
+
+In stdio branch, replace:
+
+```python
+            if auth is not None:
+                auth_env = auth.payload.get("env")
+                if isinstance(auth_env, dict):
+                    env = {**(env or {}), **auth_env}
+```
+
+with:
+
+```python
+            auth_env = mcp_auth_env(auth)
+            if auth_env:
+                env = {**(env or {}), **auth_env}
+```
+
+In HTTP branch, replace:
+
+```python
+            headers = _auth_headers(auth)
+```
+
+with:
+
+```python
+            headers = mcp_auth_headers(auth)
+```
+
+- [ ] **Step 2: Update runtime factory imports**
+
+Modify `src/wf_mcp/runtime/factory.py`.
+
+Add import:
+
+```python
+from ..auth import mcp_auth_env, mcp_auth_headers
+```
+
+Delete local `_auth_headers`.
+
+In stdio branch, replace:
+
+```python
+            if auth is not None:
+                auth_env = auth.payload.get("env")
+                if isinstance(auth_env, dict):
+                    env = {**(env or {}), **auth_env}
+```
+
+with:
+
+```python
+            auth_env = mcp_auth_env(auth)
+            if auth_env:
+                env = {**(env or {}), **auth_env}
+```
+
+In HTTP branch, replace:
+
+```python
+httpx.AsyncClient(headers=_auth_headers(auth) or None)
+```
+
+with:
+
+```python
+httpx.AsyncClient(headers=mcp_auth_headers(auth) or None)
+```
+
+- [ ] **Step 3: Run focused tests**
+
+Run:
+
+```bash
+uv run pytest tests/wf_mcp/test_auth.py tests/wf_mcp/service/test_adapters.py tests/wf_mcp/service/test_workflow_runtime.py tests/wf_mcp/service/test_upstream_transport.py -q
+uv run ruff check src/wf_mcp/auth.py src/wf_mcp/sdk/adapter.py src/wf_mcp/runtime/factory.py
+uv run basedpyright --level error src/wf_mcp/auth.py src/wf_mcp/sdk/adapter.py src/wf_mcp/runtime/factory.py
+```
+
+Expected: all pass.
+
+## Task 6: Docs and final verification
+
+**Files:**
+- Modify: `docs/current_roadmap.md`
+- Modify: `docs/superpowers/specs/2026-06-06-auth-source-secrets-boundary.md`
+
+- [ ] **Step 1: Update roadmap status**
+
+In `docs/current_roadmap.md`, under the auth/source secrets boundary bullet,
+append:
+
+```markdown
+    First implementation slice complete: neutral auth records/store protocol
+    exist in `wf_api`, MCP runtime auth resolution prefers explicit `auth_ref`
+    with legacy connection-id fallback, and MCP payload interpretation is
+    isolated in provider-specific adapter helpers.
+```
+
+- [ ] **Step 2: Update spec status**
+
+In `docs/superpowers/specs/2026-06-06-auth-source-secrets-boundary.md`, add
+after `## Purpose`:
+
+```markdown
+## Status
+
+Slice 1 implements the neutral auth record/store protocol and MCP compatibility
+bridge. Diagnostics, auth admin surfaces, and provider-specific auth unions are
+future slices.
+```
+
+- [ ] **Step 3: Run final verification**
+
+Run:
+
+```bash
+uv run pytest tests/wf_api/test_auth.py tests/wf_api/test_import_direction.py tests/wf_mcp/test_auth.py tests/wf_mcp/service/test_upstream_transport.py tests/wf_mcp/service/test_catalog.py tests/wf_mcp/service/test_workflow_runtime.py tests/wf_mcp/service/test_adapters.py -q
+uv run ruff check src/wf_api src/wf_mcp tests/wf_api/test_auth.py tests/wf_mcp/test_auth.py tests/wf_mcp/service/test_upstream_transport.py
+uv run basedpyright --level error src/wf_api src/wf_mcp tests/wf_api/test_auth.py tests/wf_mcp/test_auth.py tests/wf_mcp/service/test_upstream_transport.py
+```
+
+Expected: all pass.
+
+- [ ] **Step 4: Final report**
+
+Report:
+
+- files created/modified
+- verification outputs
+- whether any old `auth.payload[...]` reads remain outside `src/wf_mcp/auth.py`
+- deviations from this plan
+
+Search command for the payload check:
+
+```bash
+rg -n 'auth\.payload|get\("headers"|get\("token"|get\("env"' src/wf_mcp
+```
+
+Expected: payload interpretation is either in `src/wf_mcp/auth.py` or unrelated
+connection/source metadata handling. If adapter/runtime files still read
+`auth.payload`, fix before reporting.
+