devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/api_key_flow_harness.py

@@ -0,0 +1,539 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import threading
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime, timedelta
+from hashlib import sha256
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Literal
+from urllib.parse import parse_qs, urlparse
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from . import api_keys
+from .devflow_event_worker import DevflowEventWorkerService
+import devflow_engine.devflow_event_worker as worker_module
+
+FailureMode = Literal["success", "caller_contract", "grant_resolution", "decrypt", "storage"]
+StorageMode = Literal["mock", "real"]
+
+
+@dataclass(frozen=True)
+class ApiKeyTransportSmokeScenario:
+    provider: str = "openai"
+    api_key: str = "smoke-openai-key-12345678"
+    tier: str = "light"
+    storage_mode: StorageMode = "mock"
+    failure_mode: FailureMode = "success"
+    worker_id: str = "devflow-api-key-smoke"
+    project_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    grant_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    grant_token: str = "temporary-transport-secret"
+    occurred_at: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+
+@dataclass(frozen=True)
+class ApiKeyTransportSmokeResult:
+    ok: bool
+    failure_seam: str | None
+    message: str | None
+    scenario: dict[str, Any]
+    dispatch_result: dict[str, Any] | None
+    final_event: dict[str, Any] | None
+    execution_runs: list[dict[str, Any]]
+    execution_step_runs: list[dict[str, Any]]
+    grant_requests: list[dict[str, Any]]
+    supabase_requests: list[dict[str, Any]]
+    storage: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class _MockStorageRecorder:
+    def __init__(self) -> None:
+        self.keychain_writes: list[dict[str, Any]] = []
+        self.runtime_writes: list[dict[str, Any]] = []
+        self.runtime_env_vars: list[str] = []
+
+    def store_provider_api_key(self, provider: str, api_key: str) -> None:
+        spec = api_keys._resolve_provider_spec(provider)
+        credential = api_keys.validate_provider_api_key(provider=spec.provider, api_key=api_key)
+        self.keychain_writes.append(
+            {
+                "provider": spec.provider,
+                "length": len(credential),
+                "last4": credential[-4:],
+            }
+        )
+
+    def set_runtime_provider_api_key(self, provider: str, api_key: str) -> str:
+        spec = api_keys._resolve_provider_spec(provider)
+        credential = api_keys.validate_provider_api_key(provider=spec.provider, api_key=api_key)
+        self.runtime_writes.append(
+            {
+                "provider": spec.provider,
+                "env_var": spec.env_var,
+                "length": len(credential),
+                "last4": credential[-4:],
+            }
+        )
+        self.runtime_env_vars.append(spec.env_var)
+        return spec.env_var
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "mode": "mock",
+            "keychain_writes": list(self.keychain_writes),
+            "runtime_writes": list(self.runtime_writes),
+            "runtime_env_vars": list(self.runtime_env_vars),
+        }
+
+
+class _InMemorySupabase:
+    def __init__(self, *, scenario: ApiKeyTransportSmokeScenario, event_payload: dict[str, Any]) -> None:
+        self._lock = threading.Lock()
+        self.next_run_id = 1
+        self.next_step_id = 1
+        self.requests: list[dict[str, Any]] = []
+        self.tables: dict[str, list[dict[str, Any]]] = {
+            "devflow_projects": [
+                {
+                    "id": scenario.project_id,
+                    "name": "API Key Smoke Project",
+                    "environment": "development",
+                    "metadata": {},
+                    "devflow_repo_root": None,
+                }
+            ],
+            "devflow_execution_events": [
+                {
+                    "id": scenario.event_id,
+                    "project_id": scenario.project_id,
+                    "event_type": "devflow_API_KEY",
+                    "status": "queued",
+                    "stage": None,
+                    "error": None,
+                    "run_id": None,
+                    "producer": None,
+                    "occurred_at": scenario.occurred_at,
+                    "payload": event_payload,
+                }
+            ],
+            "devflow_execution_runs": [],
+            "devflow_execution_step_runs": [],
+        }
+
+    def handle(self, *, method: str, path: str, headers: dict[str, str], body: Any | None) -> tuple[int, Any]:
+        parsed = urlparse(path)
+        table = parsed.path.removeprefix("/rest/v1/")
+        query = parse_qs(parsed.query, keep_blank_values=True)
+        with self._lock:
+            self.requests.append(
+                {
+                    "method": method,
+                    "path": parsed.path,
+                    "query": {key: list(values) for key, values in query.items()},
+                    "body": body,
+                }
+            )
+            if table not in self.tables:
+                return 404, {"detail": f"Unknown table: {table}"}
+            if method == "GET":
+                return 200, self._select(table=table, query=query)
+            if method == "PATCH":
+                rows = self._patch(table=table, query=query, fields=body or {})
+                prefer = str(headers.get("Prefer") or "")
+                return 200, rows if "return=representation" in prefer else []
+            if method == "POST":
+                row = self._insert(table=table, payload=body or {})
+                prefer = str(headers.get("Prefer") or "")
+                return 201, [row] if "return=representation" in prefer else []
+        return 405, {"detail": f"Unsupported method: {method}"}
+
+    def _select(self, *, table: str, query: dict[str, list[str]]) -> list[dict[str, Any]]:
+        rows = [dict(row) for row in self.tables[table] if self._matches(row=row, query=query)]
+        order = self._single_value(query, "order")
+        if order:
+            field, _, direction = order.partition(".")
+            rows.sort(key=lambda item: item.get(field))
+            if direction.lower() == "desc":
+                rows.reverse()
+        limit = self._single_value(query, "limit")
+        if limit and limit.isdigit():
+            rows = rows[: int(limit)]
+        return rows
+
+    def _patch(self, *, table: str, query: dict[str, list[str]], fields: dict[str, Any]) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+        for row in self.tables[table]:
+            if not self._matches(row=row, query=query):
+                continue
+            row.update(fields)
+            rows.append(dict(row))
+        return rows
+
+    def _insert(self, *, table: str, payload: dict[str, Any]) -> dict[str, Any]:
+        row = dict(payload)
+        if table == "devflow_execution_runs":
+            row.setdefault("id", self.next_run_id)
+            self.next_run_id += 1
+        elif table == "devflow_execution_step_runs":
+            row.setdefault("id", self.next_step_id)
+            self.next_step_id += 1
+        self.tables[table].append(row)
+        return dict(row)
+
+    def _matches(self, *, row: dict[str, Any], query: dict[str, list[str]]) -> bool:
+        for key, values in query.items():
+            if key in {"select", "order", "limit"}:
+                continue
+            if not values:
+                continue
+            raw = values[-1]
+            if raw.startswith("eq."):
+                expected = raw[3:]
+                if str(row.get(key)) != expected:
+                    return False
+                continue
+            if raw == "is.null":
+                if row.get(key) is not None:
+                    return False
+                continue
+        return True
+
+    @staticmethod
+    def _single_value(query: dict[str, list[str]], key: str) -> str | None:
+        values = query.get(key)
+        if not values:
+            return None
+        return values[-1]
+
+
+class _SupabaseHandler(BaseHTTPRequestHandler):
+    server: "_HarnessHttpServer"
+
+    def do_GET(self) -> None:  # noqa: N802
+        self._handle()
+
+    def do_PATCH(self) -> None:  # noqa: N802
+        self._handle()
+
+    def do_POST(self) -> None:  # noqa: N802
+        self._handle()
+
+    def _handle(self) -> None:
+        length = int(self.headers.get("Content-Length") or "0")
+        raw = self.rfile.read(length) if length else b""
+        body = json.loads(raw.decode("utf-8")) if raw else None
+        status, payload = self.server.dispatch(method=self.command, path=self.path, headers=dict(self.headers), body=body)
+        encoded = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def log_message(self, format: str, *args: object) -> None:
+        return None
+
+
+class _GrantResolutionServer:
+    def __init__(self, *, scenario: ApiKeyTransportSmokeScenario) -> None:
+        self.scenario = scenario
+        self.secret = "smoke-grant-secret"
+        self.requests: list[dict[str, Any]] = []
+        self.base_url: str = ""
+
+    def handle(self, *, method: str, path: str, headers: dict[str, str], body: Any | None) -> tuple[int, Any]:
+        parsed = urlparse(path)
+        request = {
+            "method": method,
+            "path": parsed.path,
+            "authorization": headers.get("Authorization"),
+        }
+        self.requests.append(request)
+
+        canonical_path = f"/api/devflow/settings/transport-grant/{self.scenario.grant_id}"
+        legacy_resolve_path = "/api/devflow/settings/transport-grant/resolve"
+
+        if self.scenario.failure_mode == "caller_contract":
+            if method == "POST" and parsed.path == legacy_resolve_path:
+                return 200, {"detail": "legacy endpoint available"}
+            request["response_status"] = 404
+            return 404, {"detail": "Not Found"}
+
+        if method != "GET" or parsed.path != canonical_path:
+            request["response_status"] = 404
+            return 404, {"detail": "Not Found"}
+
+        if self.scenario.failure_mode == "grant_resolution":
+            request["response_status"] = 404
+            return 404, {"detail": "DevFlow transport grant not found or expired"}
+
+        grant_token = self.scenario.grant_token
+        if self.scenario.failure_mode == "decrypt":
+            grant_token = "wrong-transport-secret"
+
+        payload = {
+            "grantId": self.scenario.grant_id,
+            "grantToken": grant_token,
+            "wrappedKey": "ciphertext",
+            "wrappingAlgorithm": "AES-GCM",
+            "wrappingKeyId": "kid-smoke-123",
+            "iv": "nonce-smoke",
+            "metadata": {
+                "algorithm": "AES-GCM",
+                "version": "devflow.api_key.v1",
+            },
+            "expiresAt": (datetime.now(UTC) + timedelta(minutes=5)).isoformat(),
+        }
+        request["response_status"] = 200
+        return 200, payload
+
+
+class _GrantHandler(BaseHTTPRequestHandler):
+    server: "_HarnessHttpServer"
+
+    def do_GET(self) -> None:  # noqa: N802
+        self._handle()
+
+    def do_POST(self) -> None:  # noqa: N802
+        self._handle()
+
+    def _handle(self) -> None:
+        length = int(self.headers.get("Content-Length") or "0")
+        raw = self.rfile.read(length) if length else b""
+        body = json.loads(raw.decode("utf-8")) if raw else None
+        status, payload = self.server.dispatch(method=self.command, path=self.path, headers=dict(self.headers), body=body)
+        encoded = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def log_message(self, format: str, *args: object) -> None:
+        return None
+
+
+class _HarnessHttpServer(ThreadingHTTPServer):
+    def __init__(self, server_address: tuple[str, int], handler_class: type[BaseHTTPRequestHandler], dispatcher) -> None:
+        super().__init__(server_address, handler_class)
+        self._dispatcher = dispatcher
+
+    def dispatch(self, *, method: str, path: str, headers: dict[str, str], body: Any | None) -> tuple[int, Any]:
+        return self._dispatcher(method=method, path=path, headers=headers, body=body)
+
+
+class _ServerThread:
+    def __init__(self, server: _HarnessHttpServer) -> None:
+        self.server = server
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+
+    def __enter__(self) -> "_ServerThread":
+        self.thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.server.shutdown()
+        self.server.server_close()
+        self.thread.join(timeout=5)
+
+
+def _encrypt_transport_payload(*, grant_token: str, provider: str, credential: str, tier: str) -> dict[str, Any]:
+    plaintext = json.dumps(
+        {
+            "submitted_at": datetime.now(UTC).isoformat(),
+            "secret": {
+                "tier": tier,
+                "provider": provider,
+                "credential": credential,
+            },
+        }
+    ).encode("utf-8")
+    iv = b"0123456789ab"
+    key = sha256(grant_token.encode("utf-8")).digest()
+    ciphertext = AESGCM(key).encrypt(iv, plaintext, None)
+    return {
+        "ciphertext": base64.b64encode(ciphertext).decode("ascii"),
+        "iv": base64.b64encode(iv).decode("ascii"),
+        "metadata": {
+            "algorithm": "AES-GCM",
+            "key_derivation": "SHA-256",
+            "key_material": "transport-grant-token",
+            "content_type": "application/json",
+            "content_encoding": "utf-8",
+            "version": "devflow.api_key.v1",
+        },
+    }
+
+
+def _build_event_payload(scenario: ApiKeyTransportSmokeScenario) -> dict[str, Any]:
+    return {
+        "transport": {
+            "format": "devflow.api_key.v1",
+            "grant_id": scenario.grant_id,
+            "expires_at": (datetime.now(UTC) + timedelta(minutes=5)).isoformat(),
+            "secret_count": 1,
+            "wrapping_key_id": "kid-smoke-123",
+        },
+        "secret_descriptor": {
+            "tier": scenario.tier,
+            "provider": scenario.provider,
+            "last4": scenario.api_key[-4:],
+            "length": len(scenario.api_key),
+        },
+        "transport_payload": _encrypt_transport_payload(
+            grant_token=scenario.grant_token,
+            provider=scenario.provider,
+            credential=scenario.api_key,
+            tier=scenario.tier,
+        ),
+    }
+
+
+def _classify_failure(*, exc: Exception, scenario: ApiKeyTransportSmokeScenario, grant_requests: list[dict[str, Any]]) -> str:
+    message = str(exc)
+    if scenario.failure_mode == "caller_contract":
+        return "dfe_caller_contract"
+    if scenario.failure_mode == "grant_resolution":
+        return "clarity_grant_resolution"
+    if scenario.failure_mode == "decrypt":
+        return "decrypt_logic"
+    if scenario.failure_mode == "storage":
+        return "keychain_env_setting"
+    if "transport grant resolution request failed" in message:
+        last_status = None if not grant_requests else grant_requests[-1].get("response_status")
+        if last_status in {404, 405}:
+            return "dfe_caller_contract"
+        return "clarity_grant_resolution"
+    if "transport grant" in message or "unwrap material" in message:
+        return "clarity_grant_resolution"
+    if "decrypt" in message or "transport payload" in message:
+        return "decrypt_logic"
+    if "keychain" in message or "storage" in message:
+        return "keychain_env_setting"
+    return "worker_runtime"
+
+
+def _restore_environ(previous: dict[str, str | None]) -> None:
+    for key, value in previous.items():
+        if value is None:
+            os.environ.pop(key, None)
+        else:
+            os.environ[key] = value
+
+
+def run_api_key_transport_smoke(
+    scenario: ApiKeyTransportSmokeScenario | None = None,
+) -> ApiKeyTransportSmokeResult:
+    scenario = scenario or ApiKeyTransportSmokeScenario()
+    event_payload = _build_event_payload(scenario)
+    supabase = _InMemorySupabase(scenario=scenario, event_payload=event_payload)
+    grant_server = _GrantResolutionServer(scenario=scenario)
+    storage = _MockStorageRecorder()
+
+    supabase_http = _HarnessHttpServer(("127.0.0.1", 0), _SupabaseHandler, supabase.handle)
+    grant_http = _HarnessHttpServer(("127.0.0.1", 0), _GrantHandler, grant_server.handle)
+    grant_server.base_url = f"http://127.0.0.1:{grant_http.server_address[1]}/api/devflow/settings/transport-grant"
+    supabase_url = f"http://127.0.0.1:{supabase_http.server_address[1]}"
+
+    env_previous = {
+        key: os.environ.get(key)
+        for key in (
+            "DEVFLOW_TRANSPORT_GRANT_RESOLUTION_URL",
+            "DEVFLOW_TRANSPORT_GRANT_RESOLUTION_SECRET",
+        )
+    }
+    original_bootstrap = worker_module.bootstrap_provider_api_keys
+    original_resolve_config = worker_module._resolve_supabase_rest_config
+    original_store = worker_module.store_provider_api_key
+    original_set_runtime = worker_module.set_runtime_provider_api_key
+
+    dispatch_result: dict[str, Any] | None = None
+    failure_seam: str | None = None
+    message: str | None = None
+
+    try:
+        os.environ["DEVFLOW_TRANSPORT_GRANT_RESOLUTION_URL"] = grant_server.base_url
+        os.environ["DEVFLOW_TRANSPORT_GRANT_RESOLUTION_SECRET"] = grant_server.secret
+        worker_module.bootstrap_provider_api_keys = lambda env=None: {}
+        worker_module._resolve_supabase_rest_config = lambda: (supabase_url, "svc-key")
+
+        if scenario.storage_mode == "mock":
+            worker_module.store_provider_api_key = storage.store_provider_api_key
+            worker_module.set_runtime_provider_api_key = storage.set_runtime_provider_api_key
+        if scenario.failure_mode == "storage":
+            worker_module.store_provider_api_key = lambda provider, api_key: (_ for _ in ()).throw(
+                RuntimeError("Failed to write macOS keychain entry for provider smoke")
+            )
+
+        with _ServerThread(supabase_http), _ServerThread(grant_http):
+            service = DevflowEventWorkerService(worker_id=scenario.worker_id)
+            result = service.dispatch_next_event()
+            if result is None:
+                raise RuntimeError("No queued devflow_API_KEY event was dispatched")
+
+            dispatch_result = {
+                "event_id": result.event_id,
+                "execution_run_id": result.execution_run_id,
+                "workflow_key": result.workflow_key,
+                "command": result.command,
+                "result": result.result,
+            }
+            if result.workflow_key != "api_key":
+                raise RuntimeError(f"Unexpected workflow_key: {result.workflow_key}")
+            if result.result.get("provider") != scenario.provider:
+                raise RuntimeError("Worker reported an unexpected provider")
+            if not grant_server.requests:
+                raise RuntimeError("Worker never requested transport grant resolution")
+            request = grant_server.requests[-1]
+            if request.get("method") != "GET":
+                raise RuntimeError("Worker did not use GET for transport grant resolution")
+            auth_header = str(request.get("authorization") or "")
+            if not auth_header.startswith("Bearer "):
+                raise RuntimeError("Worker omitted HMAC auth for transport grant resolution")
+    except Exception as exc:
+        failure_seam = _classify_failure(exc=exc, scenario=scenario, grant_requests=grant_server.requests)
+        message = str(exc)
+    finally:
+        worker_module.bootstrap_provider_api_keys = original_bootstrap
+        worker_module._resolve_supabase_rest_config = original_resolve_config
+        worker_module.store_provider_api_key = original_store
+        worker_module.set_runtime_provider_api_key = original_set_runtime
+        _restore_environ(env_previous)
+
+    final_event = None
+    for row in supabase.tables["devflow_execution_events"]:
+        if str(row.get("id")) == scenario.event_id:
+            final_event = dict(row)
+            break
+
+    storage_snapshot = storage.snapshot() if scenario.storage_mode == "mock" else {"mode": "real"}
+    return ApiKeyTransportSmokeResult(
+        ok=failure_seam is None,
+        failure_seam=failure_seam,
+        message=message,
+        scenario={
+            "provider": scenario.provider,
+            "tier": scenario.tier,
+            "storage_mode": scenario.storage_mode,
+            "failure_mode": scenario.failure_mode,
+            "project_id": scenario.project_id,
+            "event_id": scenario.event_id,
+            "grant_id": scenario.grant_id,
+        },
+        dispatch_result=dispatch_result,
+        final_event=final_event,
+        execution_runs=[dict(row) for row in supabase.tables["devflow_execution_runs"]],
+        execution_step_runs=[dict(row) for row in supabase.tables["devflow_execution_step_runs"]],
+        grant_requests=list(grant_server.requests),
+        supabase_requests=list(supabase.requests),
+        storage=storage_snapshot,
+    )