@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/credential_cli.py

@@ -0,0 +1,104 @@
+"""Terminal controller for persisted provider credentials."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialCliPolicy:
+    required_providers: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialCliPorts:
+    normalize_provider: Callable[[str], str]
+    load_config: Callable[[], dict[str, Any]]
+    key_count: Callable[[str, dict[str, Any]], int]
+    primary_key: Callable[[str, dict[str, Any]], str]
+    mask: Callable[[str | None], str]
+    fingerprint: Callable[[str | None], str]
+    clear_requested: Callable[[Any], bool]
+    clear: Callable[[str], list[str]]
+    store_input: Callable[[str, str], list[str]]
+    store_many: Callable[[str, list[str]], list[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialCliIO:
+    stdin_isatty: Callable[[], bool]
+    prompt_secret: Callable[[str], str]
+    write_line: Callable[[str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialCliController:
+    policy: CredentialCliPolicy
+    ports: CredentialCliPorts
+    io: CredentialCliIO
+
+    def set_one(self, args: Any) -> None:
+        provider = self.ports.normalize_provider(args.provider)
+        key = args.key.strip()
+        if not key:
+            raise SystemExit("No key provided; unchanged.")
+        self._write(self.ports.store_input(provider, key))
+
+    def set_many(self, args: Any) -> None:
+        provider = self.ports.normalize_provider(args.provider)
+        raw = "\n".join(str(item) for item in getattr(args, "keys", []) if str(item).strip())
+        keys = self._parse_cli_keys(raw)
+        if not keys:
+            raise SystemExit("No API keys provided; unchanged.")
+        self._write(self.ports.store_many(provider, keys))
+
+    def manage(self, args: Any) -> None:
+        if not args.provider:
+            self._write_status()
+            return
+        provider = self.ports.normalize_provider(args.provider)
+        action = str(getattr(args, "action", "") or "").strip()
+        if self.ports.clear_requested(action):
+            self._write(self.ports.clear(provider))
+            return
+        if not self.io.stdin_isatty():
+            self.io.write_line("For security, do not paste API keys into Claude Code chat.")
+            self.io.write_line(f"Run this in the SSH terminal instead: ciel-runtimectl api-key {provider}")
+            return
+        key = self.io.prompt_secret(f"API key for {provider}: ").strip()
+        if not key:
+            raise SystemExit("No key entered; unchanged.")
+        self._write(self.ports.store_input(provider, key))
+
+    def _write_status(self) -> None:
+        config = self.ports.load_config()
+        self.io.write_line("API key status:")
+        for provider, provider_config in config["providers"].items():
+            count = self.ports.key_count(provider, provider_config)
+            if count > 1:
+                label = f"{count} keys (round-robin)"
+            elif count == 1:
+                label = "set"
+            else:
+                label = "missing" if provider in self.policy.required_providers else "not required"
+            primary = self.ports.primary_key(provider, provider_config)
+            suffix = (
+                f" (primary {self.ports.mask(primary)}; fp {self.ports.fingerprint(primary)})"
+                if count
+                else ""
+            )
+            self.io.write_line(f" {provider:<15} {label}{suffix}")
+        self.io.write_line("\nSet securely from terminal: ciel-runtimectl api-key anthropic")
+        self.io.write_line("Set multiple keys: ciel-runtimectl set-api-keys deepseek KEY1,KEY2")
+        self.io.write_line("For NVIDIA hosted, use: ciel-runtimectl api-key nvidia-hosted")
+
+    def _parse_cli_keys(self, raw: str) -> list[str]:
+        # store_many owns canonical parsing; preserve separate CLI empty-input validation.
+        return [item.strip() for item in raw.splitlines() if item.strip()]
+
+    def _write(self, lines: list[str]) -> None:
+        for line in lines:
+            self.io.write_line(line)
+
+
+__all__ = ["CredentialCliController", "CredentialCliIO", "CredentialCliPolicy", "CredentialCliPorts"]

package/ciel_runtime_support/credential_management.py

@@ -0,0 +1,261 @@
+"""Credential persistence transactions for provider API keys."""
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import os
+from pathlib import Path
+from threading import Lock, RLock
+from typing import Any, Callable
+
+
+def parse_dotenv_file(path: Path) -> dict[str, str]:
+    """Read the simple KEY=VALUE format used by runtime-owned env files."""
+
+    environment: dict[str, str] = {}
+    if not path.exists():
+        return environment
+    for line in path.read_text(errors="ignore").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        environment[key.strip()] = value.strip().strip("'\"")
+    return environment
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialPersistencePorts:
+    load_config: Callable[[], dict[str, Any]]
+    save_config: Callable[[dict[str, Any]], None]
+    clear_model_cache: Callable[[], None]
+    parse_keys: Callable[[Any], list[str]]
+    clear_requested: Callable[[Any], bool]
+    rotation_name: Callable[[str, dict[str, Any]], str]
+    error_text: Callable[[Any], bool] = lambda _value: False
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalCredentialPorts:
+    enabled: Callable[[str], bool]
+    store: Callable[[str], None]
+    clear: Callable[[], None]
+    has_key: Callable[[], bool]
+    normalize_provider_config: Callable[[dict[str, Any]], bool]
+    location: Any
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialPresentationPorts:
+    mask: Callable[[str | None], str]
+    fingerprint: Callable[[str | None], str]
+
+
+class CredentialRotationRepository:
+    def __init__(self, cursor: dict[str, int], lock: Lock | RLock) -> None:
+        self._cursor = cursor
+        self._lock = lock
+
+    def reset(self, name: str) -> None:
+        with self._lock:
+            self._cursor.pop(name, None)
+
+
+@dataclass(frozen=True, slots=True)
+class EnvCredentialRepository:
+    """Persist one credential in a chmod-protected dotenv file."""
+
+    path: Path
+    key_name: str
+    defaults: dict[str, str]
+    read_env_file: Callable[[Path], dict[str, str]]
+    parse_values: Callable[[Any], list[str]]
+
+    def store(self, value: str) -> None:
+        environment = self.read_env_file(self.path)
+        environment[self.key_name] = value
+        for name, default in self.defaults.items():
+            environment.setdefault(name, default)
+        self._write(environment)
+
+    def clear(self) -> None:
+        environment = self.read_env_file(self.path)
+        if self.key_name not in environment:
+            return
+        environment.pop(self.key_name, None)
+        self._write(environment)
+
+    def has_key(self) -> bool:
+        return bool(self.parse_values(self.read_env_file(self.path).get(self.key_name)))
+
+    def _write(self, environment: dict[str, str]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text("".join(f"{key}={value}\n" for key, value in environment.items()))
+        os.chmod(self.path, 0o600)
+
+
+def nvidia_env_credential_repository(
+    path: Path,
+    read_env_file: Callable[[Path], dict[str, str]],
+    parse_values: Callable[[Any], list[str]],
+    base_url: str,
+) -> EnvCredentialRepository:
+    return EnvCredentialRepository(
+        path=path,
+        key_name="NVIDIA_API_KEY",
+        defaults={
+            "NVIDIA_BASE_URL": base_url,
+            "PROXY_HOST": "127.0.0.1",
+            "PROXY_PORT": "8788",
+            "STORAGE_ENGINE": "sqlite",
+        },
+        read_env_file=read_env_file,
+        parse_values=parse_values,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialManagementService:
+    persistence: CredentialPersistencePorts
+    external: ExternalCredentialPorts
+    presentation: CredentialPresentationPorts
+    rotation: CredentialRotationRepository
+    config_location: Any
+
+    def store_one(self, provider: str, key: str) -> list[str]:
+        if self.persistence.clear_requested(key):
+            return self.clear(provider)
+        config = self.persistence.load_config()
+        provider_config = config["providers"][provider]
+        if self.external.enabled(provider):
+            self.external.store(key)
+            provider_config.pop("api_keys", None)
+            if self.external.normalize_provider_config(provider_config):
+                self.persistence.save_config(config)
+            location = self.external.location
+        else:
+            provider_config["api_key"] = key
+            provider_config.pop("api_keys", None)
+            self.persistence.save_config(config)
+            location = self.config_location
+        self.persistence.clear_model_cache()
+        return [
+            f"Stored API key for {provider}.",
+            f"Saved: {self.presentation.mask(key)}; "
+            f"fp {self.presentation.fingerprint(key)} in {location}",
+        ]
+
+    def clear(self, provider: str) -> list[str]:
+        config = self.persistence.load_config()
+        providers = config["providers"]
+        other_key_fields = self._snapshot_other_provider_keys(providers, provider)
+        provider_config = providers[provider]
+        had_key = bool(
+            self.persistence.parse_keys(provider_config.get("api_key"))
+            or self.persistence.parse_keys(provider_config.get("api_keys"))
+        )
+        provider_config.pop("api_key", None)
+        provider_config.pop("api_keys", None)
+        if self.external.enabled(provider):
+            had_key = had_key or self.external.has_key()
+            self.external.clear()
+            self.external.normalize_provider_config(provider_config)
+        self._restore_other_provider_keys(providers, other_key_fields)
+        self.persistence.save_config(config)
+        self.persistence.clear_model_cache()
+        self.rotation.reset(self.persistence.rotation_name(provider, provider_config))
+        if had_key:
+            return [f"Cleared stored API key(s) for {provider}. Other providers unchanged."]
+        return [f"No stored API key(s) for {provider}; other providers unchanged."]
+
+    def store_many(self, provider: str, keys: list[str]) -> list[str]:
+        parsed = self.persistence.parse_keys(keys)
+        if len(parsed) == 1 and self.persistence.clear_requested(parsed[0]):
+            return self.clear(provider)
+        if not parsed:
+            raise SystemExit("No API keys provided; unchanged.")
+        config = self.persistence.load_config()
+        provider_config = config["providers"][provider]
+        provider_config["api_key"] = parsed[0]
+        if len(parsed) > 1:
+            provider_config["api_keys"] = parsed
+        else:
+            provider_config.pop("api_keys", None)
+        if self.external.enabled(provider):
+            self.external.store(parsed[0])
+            self.external.normalize_provider_config(provider_config)
+        self.persistence.save_config(config)
+        self.persistence.clear_model_cache()
+        self.rotation.reset(self.persistence.rotation_name(provider, provider_config))
+        return [
+            f"Stored {len(parsed)} API key{'s' if len(parsed) != 1 else ''} for {provider}.",
+            f"Round-robin: {'enabled' if len(parsed) > 1 else 'disabled'}",
+            f"Primary: {self.presentation.mask(parsed[0])}; "
+            f"fp {self.presentation.fingerprint(parsed[0])}",
+        ]
+
+    def store_input(self, provider: str, raw_value: str) -> list[str]:
+        if self.persistence.clear_requested(raw_value):
+            return self.clear(provider)
+        keys = self.persistence.parse_keys(raw_value)
+        # Refuse to persist a "key" that is actually an upstream error string
+        # (operator 2026-07-29: the ollama-cloud api_key held the literal text
+        # of a 504 URLError; every chat call then failed 401 while the
+        # unauthenticated /api/tags kept working, masking the corruption).
+        rejected = [key for key in keys if self.persistence.error_text(key)]
+        if rejected:
+            raise SystemExit(
+                "Refusing to store an API key that looks like an error message "
+                f"({len(rejected)} item(s) contain error prose). Paste the key "
+                "itself, not the error output. Unchanged."
+            )
+        if len(keys) > 1:
+            return self.store_many(provider, keys)
+        if len(keys) == 1:
+            return self.store_one(provider, keys[0])
+        raise SystemExit("No API key provided; unchanged.")
+
+    @staticmethod
+    def _snapshot_other_provider_keys(
+        providers: dict[str, Any], target_provider: str
+    ) -> dict[str, tuple[bool, Any, bool, Any]]:
+        snapshots: dict[str, tuple[bool, Any, bool, Any]] = {}
+        for name, provider_config in providers.items():
+            if name == target_provider or not isinstance(provider_config, dict):
+                continue
+            snapshots[name] = (
+                "api_key" in provider_config,
+                deepcopy(provider_config.get("api_key")),
+                "api_keys" in provider_config,
+                deepcopy(provider_config.get("api_keys")),
+            )
+        return snapshots
+
+    @staticmethod
+    def _restore_other_provider_keys(
+        providers: dict[str, Any], snapshots: dict[str, tuple[bool, Any, bool, Any]]
+    ) -> None:
+        for name, (has_key, key, has_keys, keys) in snapshots.items():
+            provider_config = providers.get(name)
+            if not isinstance(provider_config, dict):
+                continue
+            if has_key:
+                provider_config["api_key"] = key
+            else:
+                provider_config.pop("api_key", None)
+            if has_keys:
+                provider_config["api_keys"] = keys
+            else:
+                provider_config.pop("api_keys", None)
+
+
+__all__ = [
+    "CredentialManagementService",
+    "CredentialPersistencePorts",
+    "CredentialPresentationPorts",
+    "CredentialRotationRepository",
+    "EnvCredentialRepository",
+    "ExternalCredentialPorts",
+    "nvidia_env_credential_repository",
+    "parse_dotenv_file",
+]

package/ciel_runtime_support/credentials.py

@@ -0,0 +1,269 @@
+"""Credential resolution ports for API keys, OAuth pass-through, and future stores."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import re
+from typing import Any, Mapping, Protocol
+
+from ciel_runtime_support.architecture import ProviderConfig
+
+
+API_KEY_CLEAR_TOKENS = frozenset({"clear", "unset", "none", "null", "off", "delete", "remove"})
+
+# Persisted credential hygiene: these substrings mean the stored "key" is not a
+# key at all but an upstream error string that was pasted or written into the
+# credential field (operator 2026-07-29: the ollama-cloud api_key held the
+# literal text "504 URLError: <urlopen error EOF occurred in violation of
+# protocol (_ssl.c:2406" — every chat call then failed 401 while /api/tags,
+# which is unauthenticated, kept working and made the key look valid).
+SECRET_ERROR_MARKERS = (
+    "urlerror",
+    "httperror",
+    "http error",
+    "<urlopen error",
+    "eof occurred in violation of protocol",
+    "traceback (most recent call last)",
+    "connection refused",
+    "connection reset",
+    "timed out",
+    "unauthorized",
+    "401 client error",
+    "403 client error",
+    "404 client error",
+    "500 internal server error",
+    "502 bad gateway",
+    "503 service unavailable",
+    "504 gateway",
+)
+
+# Structural shapes shared by every common API key format (Anthropic sk-ant-*,
+# Ollama, DeepSeek, OpenRouter sk-or-*, etc.): single line, no whitespace, no
+# error prose. A credential is a token, not a sentence.
+_KEY_PLAUSIBLE_RE = re.compile(r"^\S{8,512}$")
+
+
+def looks_like_error_text(value: Any) -> bool:
+    text = str(value or "").strip().lower()
+    if not text:
+        return False
+    return any(marker in text for marker in SECRET_ERROR_MARKERS)
+
+
+def plausible_api_key(value: Any) -> bool:
+    """Minimal structural sanity check: one non-space token, no error prose."""
+
+    text = str(value or "").strip()
+    if not _KEY_PLAUSIBLE_RE.match(text):
+        return False
+    return not looks_like_error_text(text)
+SECRET_TEXT_PATTERNS = (
+    re.compile(r"ak_key_[A-Za-z0-9_-]+_secret_[A-Za-z0-9_-]+"),
+    re.compile(r"(AINET_API_KEY\s*=\s*)(\S+)", re.IGNORECASE),
+    re.compile(r"(Authorization\s*:\s*Bearer\s+)(\S+)", re.IGNORECASE),
+    re.compile(r"(token=)(ak_key_[A-Za-z0-9_-]+_secret_[A-Za-z0-9_-]+)", re.IGNORECASE),
+)
+
+
+def meaningful_key_value(value: Any) -> bool:
+    text = str(value or "").strip()
+    return bool(text and text not in {"dummy", "not-used", "ollama"})
+
+
+def api_key_clear_requested(value: Any) -> bool:
+    return str(value or "").strip().lower() in API_KEY_CLEAR_TOKENS
+
+
+def parse_api_key_list(value: Any) -> list[str]:
+    """Parse pasted, delimited, and soft-wrapped key input deterministically."""
+
+    if value is None:
+        return []
+    raw_items: list[Any]
+    if isinstance(value, (list, tuple, set)):
+        raw_items = [key for item in value for key in parse_api_key_list(item)]
+    else:
+        text = str(value)
+        if re.search(r"[,;]", text):
+            raw_items = []
+            for field in re.split(r"[,;]+", text):
+                current = ""
+                for line in str(field).splitlines() or [str(field)]:
+                    if not line.strip():
+                        continue
+                    if current and line[:1].isspace():
+                        current += line.strip()
+                    else:
+                        if current:
+                            raw_items.append(current)
+                        current = line.strip()
+                if current:
+                    raw_items.append(current)
+        else:
+            raw_items = re.split(r"[\r\n]+", text)
+    return list(
+        dict.fromkeys(
+            key
+            for item in raw_items
+            if meaningful_key_value(key := str(item or "").strip())
+        )
+    )
+
+
+def mask_secret(value: str | None) -> str:
+    text = value or ""
+    if not text:
+        return "not set"
+    if len(text) <= 8:
+        return "*" * len(text)
+    return f"{text[:4]}...{text[-4:]}"
+
+
+def secret_fingerprint(value: str | None, length: int = 12) -> str:
+    text = value or ""
+    if not text:
+        return "-"
+    digest = hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()
+    return digest[: max(4, length)]
+
+
+def redact_sensitive_text(text: str) -> str:
+    redacted = SECRET_TEXT_PATTERNS[0].sub(lambda match: mask_secret(match.group(0)), text)
+    for pattern in SECRET_TEXT_PATTERNS[1:]:
+        redacted = pattern.sub(
+            lambda match: f"{match.group(1)}{mask_secret(match.group(2))}",
+            redacted,
+        )
+    return redacted
+
+
+def redact_sensitive_obj(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_sensitive_text(value)
+    if isinstance(value, list):
+        return [redact_sensitive_obj(item) for item in value]
+    if isinstance(value, dict):
+        return {
+            key: mask_secret(str(item))
+            if str(key).lower() in {"api_key", "api_keys", "apikey", "token", "authorization", "bearer_token"}
+            else redact_sensitive_obj(item)
+            for key, item in value.items()
+        }
+    return value
+
+
+def provider_config_api_keys(
+    pcfg: Mapping[str, Any],
+    supplemental_keys: Any = (),
+) -> list[str]:
+    keys = [
+        *parse_api_key_list(supplemental_keys),
+        *parse_api_key_list(pcfg.get("api_keys")),
+        *parse_api_key_list(pcfg.get("api_key")),
+    ]
+    return list(dict.fromkeys(keys))
+
+
+def provider_contract_config(
+    provider: str,
+    pcfg: Mapping[str, Any],
+    api_keys: list[str] | tuple[str, ...],
+) -> ProviderConfig:
+    return ProviderConfig(
+        name=provider,
+        base_url=str(pcfg.get("base_url") or ""),
+        model=str(pcfg.get("current_model") or pcfg.get("model") or ""),
+        api_keys=tuple(api_keys),
+        options=pcfg,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialContext:
+    provider: str
+    api_key: str = ""
+    inbound_headers: Any | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCredential:
+    source: str
+    headers: Mapping[str, str]
+
+
+class CredentialSource(Protocol):
+    def resolve(self, context: CredentialContext) -> ResolvedCredential | None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCredentialSource:
+    header: str = "x-api-key"
+
+    def resolve(self, context: CredentialContext) -> ResolvedCredential | None:
+        key = str(context.api_key or "").strip()
+        return ResolvedCredential("api_key", {self.header: key}) if key else None
+
+
+@dataclass(frozen=True, slots=True)
+class InboundHeaderCredentialSource:
+    """Resolve credentials from an explicit inbound authentication allowlist."""
+
+    allowed_headers: tuple[str, ...]
+    required_any: tuple[str, ...] = ("authorization", "x-api-key")
+
+    def resolve(self, context: CredentialContext) -> ResolvedCredential | None:
+        inbound = context.inbound_headers
+        if inbound is None:
+            return None
+        try:
+            inbound_by_name = {
+                str(raw_name).lower(): raw_value
+                for raw_name, raw_value in inbound.items()
+            }
+        except Exception:
+            inbound_by_name = {}
+        headers: dict[str, str] = {}
+        for name in self.allowed_headers:
+            try:
+                value = inbound.get(name)
+            except Exception:
+                value = None
+            if value is None:
+                value = inbound_by_name.get(name.lower())
+            if value:
+                headers[name] = str(value)
+        if not any(headers.get(name) for name in self.required_any):
+            return None
+        return ResolvedCredential("inbound", headers)
+
+
+class CredentialChain:
+    """Chain of Responsibility: first available credential wins."""
+
+    def __init__(self, *sources: CredentialSource) -> None:
+        self._sources = sources
+
+    def resolve(self, context: CredentialContext) -> ResolvedCredential | None:
+        for source in self._sources:
+            if credential := source.resolve(context):
+                return credential
+        return None
+
+
+ANTHROPIC_INBOUND_CREDENTIAL_SOURCE = InboundHeaderCredentialSource(
+    allowed_headers=(
+        "authorization",
+        "x-api-key",
+    )
+)
+
+
+def resolve_anthropic_credentials(
+    api_key: str,
+    inbound_headers: Any | None,
+) -> ResolvedCredential | None:
+    return CredentialChain(
+        ApiKeyCredentialSource(),
+        ANTHROPIC_INBOUND_CREDENTIAL_SOURCE,
+    ).resolve(CredentialContext("anthropic", api_key, inbound_headers))