devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/api_keys.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import os
+import subprocess
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any
+from urllib.error import HTTPError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+from uuid import UUID
+
+
+_KEYCHAIN_SERVICE = "devflow-engine.provider-api-key"
+_TRANSPORT_GRANT_PURPOSE = "devflow_settings_transport_wrap"
+
+
+@dataclass(frozen=True)
+class ProviderSecretSpec:
+    provider: str
+    env_var: str
+    aliases: tuple[str, ...] = ()
+
+
+_PROVIDER_SPECS: tuple[ProviderSecretSpec, ...] = (
+    ProviderSecretSpec("anthropic", "ANTHROPIC_API_KEY", aliases=("claude",)),
+    ProviderSecretSpec("openai", "OPENAI_API_KEY", aliases=("codex",)),
+    ProviderSecretSpec("google", "GOOGLE_API_KEY", aliases=("gemini", "gemini-cli")),
+    ProviderSecretSpec("ollama", "OLLAMA_API_KEY"),
+    ProviderSecretSpec("openrouter", "OPENROUTER_API_KEY"),
+    ProviderSecretSpec("mistral", "MISTRAL_API_KEY"),
+    ProviderSecretSpec("deepseek", "DEEPSEEK_API_KEY"),
+    ProviderSecretSpec("xai", "XAI_API_KEY", aliases=("grok",)),
+    ProviderSecretSpec("minimax", "MINIMAX_API_KEY"),
+)
+_PROVIDER_INDEX = {
+    alias: spec
+    for spec in _PROVIDER_SPECS
+    for alias in (spec.provider, *spec.aliases)
+}
+_RUNTIME_PROVIDER_KEYS: dict[str, str] = {}
+
+
+def _resolve_provider_spec(provider: str) -> ProviderSecretSpec:
+    normalized = str(provider or "").strip().lower()
+    if not normalized:
+        raise RuntimeError("API-key provider is required")
+    spec = _PROVIDER_INDEX.get(normalized)
+    if spec is None:
+        raise RuntimeError(f"Unsupported API-key provider: {normalized}")
+    return spec
+
+
+def _run_security_command(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["security", *args],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=10,
+    )
+
+
+def _keychain_get(service: str, account: str) -> str | None:
+    try:
+        proc = _run_security_command(["find-generic-password", "-s", service, "-a", account, "-w"])
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    value = proc.stdout.strip()
+    return value or None
+
+
+def load_provider_api_key_from_keychain(provider: str) -> str | None:
+    spec = _resolve_provider_spec(provider)
+    try:
+        proc = _run_security_command(["find-generic-password", "-s", _KEYCHAIN_SERVICE, "-a", spec.provider, "-w"])
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    value = proc.stdout.strip()
+    return value or None
+
+
+def store_provider_api_key(provider: str, api_key: str) -> None:
+    spec = _resolve_provider_spec(provider)
+    credential = validate_provider_api_key(provider=spec.provider, api_key=api_key)
+    try:
+        proc = _run_security_command(
+            ["add-generic-password", "-U", "-s", _KEYCHAIN_SERVICE, "-a", spec.provider, "-w", credential]
+        )
+    except Exception as exc:
+        raise RuntimeError(f"Failed to write macOS keychain entry for provider {spec.provider}") from exc
+    if proc.returncode != 0:
+        raise RuntimeError(f"Failed to write macOS keychain entry for provider {spec.provider}")
+
+
+def set_runtime_provider_api_key(provider: str, api_key: str, *, env: dict[str, str] | None = None) -> str:
+    spec = _resolve_provider_spec(provider)
+    credential = validate_provider_api_key(provider=spec.provider, api_key=api_key)
+    target_env = os.environ if env is None else env
+    target_env[spec.env_var] = credential
+    _RUNTIME_PROVIDER_KEYS[spec.provider] = credential
+    return spec.env_var
+
+
+def get_provider_api_key(provider: str, *, env: dict[str, str] | None = None) -> str | None:
+    spec = _resolve_provider_spec(provider)
+    target_env = os.environ if env is None else env
+    env_value = str(target_env.get(spec.env_var) or "").strip()
+    if env_value:
+        _RUNTIME_PROVIDER_KEYS[spec.provider] = env_value
+        return env_value
+    cached = _RUNTIME_PROVIDER_KEYS.get(spec.provider)
+    if cached:
+        return cached
+    stored = load_provider_api_key_from_keychain(spec.provider)
+    if stored:
+        set_runtime_provider_api_key(spec.provider, stored, env=target_env)
+        return stored
+    return None
+
+
+def bootstrap_provider_api_keys(*, env: dict[str, str] | None = None) -> dict[str, str]:
+    loaded: dict[str, str] = {}
+    for spec in _PROVIDER_SPECS:
+        value = load_provider_api_key_from_keychain(spec.provider)
+        if not value:
+            continue
+        set_runtime_provider_api_key(spec.provider, value, env=env)
+        loaded[spec.provider] = spec.env_var
+    return loaded
+
+
+def validate_provider_api_key(*, provider: str, api_key: str) -> str:
+    _resolve_provider_spec(provider)
+    credential = str(api_key or "").strip()
+    if not credential:
+        raise RuntimeError("API-key credential is required")
+    if any(token in credential for token in ("\n", "\r", "\x00")):
+        raise RuntimeError("API-key credential failed validation")
+    if len(credential) < 8:
+        raise RuntimeError("API-key credential failed validation")
+    return credential
+
+
+class DevflowTransportGrantStore:
+    def __init__(self, *, endpoint_url: str, auth_secret: str | None = None):
+        self.endpoint_url = endpoint_url.rstrip("/")
+        self.auth_secret = str(auth_secret or "").strip() or None
+
+    @staticmethod
+    def from_env() -> "DevflowTransportGrantStore":
+        endpoint_url = (
+            os.environ.get("DEVFLOW_TRANSPORT_GRANT_RESOLUTION_URL")
+            or os.environ.get("CLARITY_TRANSPORT_GRANT_RESOLUTION_URL")
+        )
+        if not endpoint_url:
+            backend_url = os.environ.get("DEVFLOW_BACKEND_URL") or os.environ.get("CLARITY_BACKEND_URL")
+            if backend_url:
+                normalized_backend_url = backend_url.rstrip("/")
+                if normalized_backend_url.endswith("/api"):
+                    endpoint_url = f"{normalized_backend_url}/devflow/settings/transport-grant"
+                else:
+                    endpoint_url = f"{normalized_backend_url}/api/devflow/settings/transport-grant"
+        if not endpoint_url:
+            raise RuntimeError("DevFlow transport grant resolution endpoint is not configured")
+        auth_secret = (
+            os.environ.get("DEVFLOW_TRANSPORT_GRANT_RESOLUTION_SECRET")
+            or os.environ.get("CLARITY_SECRET_KEY")
+            or os.environ.get("DEVFLOW_BACKEND_SECRET_KEY")
+            or os.environ.get("SECRET_KEY")
+        )
+        return DevflowTransportGrantStore(endpoint_url=endpoint_url, auth_secret=auth_secret)
+
+    @staticmethod
+    def _build_hmac_bearer_token(secret: str, payload: str) -> str:
+        timestamp = str(int(time.time()))
+        message = f"{timestamp}.{payload}"
+        signature = hmac.new(
+            secret.encode("utf-8"),
+            message.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        return f"Bearer {signature}.{timestamp}"
+
+    def fetch(self, *, grant_id: UUID | str) -> dict[str, Any] | None:
+        url = f"{self.endpoint_url}/{quote(str(grant_id), safe='')}"
+        req = Request(url, method="GET")
+        req.add_header("Accept", "application/json")
+        if self.auth_secret:
+            req.add_header("Authorization", self._build_hmac_bearer_token(self.auth_secret, ""))
+        try:
+            with urlopen(req, timeout=30) as resp:
+                raw = resp.read().decode("utf-8")
+        except HTTPError as exc:
+            if exc.code == 404:
+                return None
+            detail = ""
+            try:
+                detail = exc.read().decode("utf-8").strip()
+            except Exception:
+                detail = ""
+            message = detail or exc.reason or f"HTTP {exc.code}"
+            raise RuntimeError(f"DevFlow transport grant resolution request failed: {message}") from exc
+        except Exception as exc:
+            raise RuntimeError("DevFlow transport grant resolution request failed") from exc
+        if not raw:
+            return None
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(payload, dict):
+            return None
+        normalized = dict(payload)
+        aliases = {
+            "grantId": "grant_id",
+            "grantToken": "grant_token",
+            "wrappedKey": "wrapped_key",
+            "wrappingAlgorithm": "wrapping_algorithm",
+            "wrappingKeyId": "wrapping_key_id",
+            "expiresAt": "expires_at",
+        }
+        for source_key, target_key in aliases.items():
+            if source_key in normalized:
+                normalized.setdefault(target_key, normalized.pop(source_key))
+        if normalized.get("grant_token") and "purpose" not in normalized:
+            normalized["purpose"] = _TRANSPORT_GRANT_PURPOSE
+        grant = normalized.get("grant")
+        if isinstance(grant, dict):
+            return grant
+        return normalized
+
+    def close(self) -> None:
+        return None
+
+
+def resolve_transport_grant(*, grant_id: str, grant_store: DevflowTransportGrantStore | None = None) -> dict[str, Any]:
+    own_store = grant_store is None
+    store = grant_store or DevflowTransportGrantStore.from_env()
+    try:
+        payload = store.fetch(grant_id=grant_id)
+    finally:
+        if own_store:
+            store.close()
+    if not isinstance(payload, dict):
+        raise RuntimeError("DevFlow transport grant is unavailable or expired")
+    if str(payload.get("purpose") or "") != _TRANSPORT_GRANT_PURPOSE:
+        raise RuntimeError("DevFlow transport grant purpose is invalid")
+    grant_token = str(payload.get("grant_token") or "").strip()
+    if not grant_token:
+        raise RuntimeError("DevFlow transport grant is missing unwrap material")
+    expires_at = str(payload.get("expires_at") or "").strip()
+    if expires_at:
+        try:
+            expires_dt = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise RuntimeError("DevFlow transport grant metadata is invalid") from exc
+        if expires_dt.astimezone(UTC) <= datetime.now(UTC):
+            raise RuntimeError("DevFlow transport grant is unavailable or expired")
+    return payload
+
+
+def decrypt_transport_payload(*, grant_token: str, transport_payload: dict[str, Any]) -> dict[str, Any]:
+    try:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    except ImportError as exc:
+        raise RuntimeError("cryptography package is required for DevFlow API-key transport unwrap") from exc
+
+    ciphertext_b64 = str(transport_payload.get("ciphertext") or "")
+    iv_b64 = str(transport_payload.get("iv") or "")
+    metadata = transport_payload.get("metadata") or {}
+    if not ciphertext_b64 or not iv_b64 or not isinstance(metadata, dict):
+        raise RuntimeError("DevFlow API-key transport payload is incomplete")
+    if str(metadata.get("algorithm") or "") != "AES-GCM":
+        raise RuntimeError("Unsupported DevFlow transport algorithm")
+    if str(metadata.get("key_derivation") or "") != "SHA-256":
+        raise RuntimeError("Unsupported DevFlow transport key derivation")
+    if str(metadata.get("key_material") or "") != "transport-grant-token":
+        raise RuntimeError("Unsupported DevFlow transport key material")
+    if str(metadata.get("version") or "") != "devflow.api_key.v1":
+        raise RuntimeError("Unsupported DevFlow transport payload version")
+
+    try:
+        ciphertext = base64.b64decode(ciphertext_b64, validate=True)
+        iv = base64.b64decode(iv_b64, validate=True)
+    except (ValueError, binascii.Error) as exc:
+        raise RuntimeError("DevFlow API-key transport payload is malformed") from exc
+
+    key = sha256(grant_token.encode("utf-8")).digest()
+    try:
+        plaintext = AESGCM(key).decrypt(iv, ciphertext, None)
+    except Exception as exc:
+        raise RuntimeError("Unable to decrypt DevFlow API-key transport payload") from exc
+
+    try:
+        payload = json.loads(plaintext.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise RuntimeError("Decrypted DevFlow API-key transport payload is invalid") from exc
+    if not isinstance(payload, dict):
+        raise RuntimeError("Decrypted DevFlow API-key transport payload is invalid")
+    return payload
+
+
+def unwrap_api_key_event_payload(
+    *,
+    payload: dict[str, Any],
+    grant_store: DevflowTransportGrantStore | None = None,
+) -> dict[str, str | None]:
+    transport = payload.get("transport")
+    transport_payload = payload.get("transport_payload")
+    if not isinstance(transport, dict):
+        raise RuntimeError("devflow_API_KEY requires payload.transport object")
+    if not isinstance(transport_payload, dict):
+        raise RuntimeError("devflow_API_KEY requires payload.transport_payload object")
+
+    grant_id = str(transport.get("grant_id") or "").strip()
+    if not grant_id:
+        raise RuntimeError("devflow_API_KEY requires payload.transport.grant_id")
+    grant = resolve_transport_grant(grant_id=grant_id, grant_store=grant_store)
+    decrypted = decrypt_transport_payload(grant_token=str(grant["grant_token"]), transport_payload=transport_payload)
+
+    secret = decrypted.get("secret")
+    if not isinstance(secret, dict):
+        raise RuntimeError("Decrypted DevFlow API-key payload is missing secret material")
+    provider_spec = _resolve_provider_spec(str(secret.get("provider") or ""))
+    credential = validate_provider_api_key(provider=provider_spec.provider, api_key=str(secret.get("credential") or ""))
+    tier = str(secret.get("tier") or "").strip() or None
+
+    descriptor = payload.get("secret_descriptor")
+    if isinstance(descriptor, dict):
+        descriptor_provider = str(descriptor.get("provider") or "").strip().lower()
+        if descriptor_provider and _resolve_provider_spec(descriptor_provider).provider != provider_spec.provider:
+            raise RuntimeError("devflow_API_KEY provider descriptor mismatch")
+        descriptor_last4 = descriptor.get("last4")
+        if descriptor_last4 is not None and str(descriptor_last4) != credential[-4:]:
+            raise RuntimeError("devflow_API_KEY credential descriptor mismatch")
+        descriptor_length = descriptor.get("length")
+        if descriptor_length is not None and int(descriptor_length) != len(credential):
+            raise RuntimeError("devflow_API_KEY credential descriptor mismatch")
+
+    return {
+        "provider": provider_spec.provider,
+        "api_key": credential,
+        "tier": tier,
+        "env_var": provider_spec.env_var,
+    }

devflow_engine/bootstrap/__init__.py

@@ -0,0 +1,2 @@
+"""Bootstrap helpers for project initialization flows."""
+

devflow_engine/bootstrap/provision_from_template.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+CLARIFY_COMMAND_REFERENCE = (
+    "python3 <(gh api repos/Nuosis/clarify/contents/scripts/provision_from_template.py "
+    "--jq '.content' | base64 -d)"
+)
+COPY_PROVISION_STRATEGY = "COPY_PROVISION_SCRIPT"
+LOCAL_ONLY_UNTIL_APPROVED = "LOCAL_ONLY_UNTIL_APPROVED"
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _slug(value: str) -> str:
+    raw = re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+    return raw or "python-backend"
+
+
+def _pkg_name(value: str) -> str:
+    raw = re.sub(r"[^a-z0-9]+", "_", value.strip().lower()).strip("_")
+    return raw or "python_backend"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Provision a deterministic Python backend scaffold.")
+    parser.add_argument("--dest", required=True, type=Path)
+    parser.add_argument("--project-name", required=True)
+    args = parser.parse_args(argv)
+
+    dest = args.dest.resolve()
+    project_name = args.project_name.strip() or "Python Backend"
+    slug = _slug(project_name)
+    package_name = _pkg_name(project_name)
+
+    _write(dest / "README.md", f"# {project_name}\n\nProvisioned via Clarify COPY/provision-script semantics.\n")
+    _write(
+        dest / "pyproject.toml",
+        "\n".join(
+            [
+                "[project]",
+                f'name = "{slug}"',
+                'version = "0.1.0"',
+                'requires-python = ">=3.11"',
+                "",
+                "[build-system]",
+                'requires = ["hatchling"]',
+                'build-backend = "hatchling.build"',
+                "",
+            ]
+        ),
+    )
+    _write(dest / "src" / package_name / "__init__.py", "__all__ = []\n")
+    _write(
+        dest / "src" / package_name / "app.py",
+        "def healthcheck() -> dict[str, str]:\n"
+        "    return {\"status\": \"ok\"}\n",
+    )
+    _write(
+        dest / ".devflow-backend-bootstrap.json",
+        json.dumps(
+            {
+                "provisioning_strategy": COPY_PROVISION_STRATEGY,
+                "clarify_command_reference": CLARIFY_COMMAND_REFERENCE,
+                "backend_default_deploy_behavior": LOCAL_ONLY_UNTIL_APPROVED,
+                "project_name": project_name,
+                "package_name": package_name,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())