multi-forge 0.2.0__py3-none-any.whl

forge/core/auth/capabilities.py

@@ -0,0 +1,219 @@
+"""Credential registry and capability metadata.
+
+Single source of truth for Forge credential definitions. Each credential
+maps to one or more env vars and describes what features it unlocks.
+
+Dependency direction: this module imports TEMPLATE_SECRETS from
+template_secrets.py (one-way). template_secrets.py must NOT import
+from this module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EnvVar:
+    """Metadata for one environment variable within a credential."""
+
+    name: str
+    required: bool = True
+    secret: bool = True
+    connection_value: bool = False
+    default_value: str | None = None
+
+
+@dataclass(frozen=True)
+class Credential:
+    """A Forge credential with its env vars and capability metadata."""
+
+    name: str
+    env_vars: tuple[EnvVar, ...] = ()
+    unlocks_features: tuple[str, ...] = ()
+    signup_url: str | None = None
+    note: str | None = None
+    not_needed_for: tuple[str, ...] | None = None
+
+
+CREDENTIALS: dict[str, Credential] = {
+    "openrouter": Credential(
+        name="openrouter",
+        env_vars=(
+            EnvVar("OPENROUTER_API_KEY"),
+            EnvVar(
+                "OPENROUTER_BASE_URL",
+                required=False,
+                secret=False,
+                connection_value=True,
+                default_value="https://openrouter.ai/api/v1",
+            ),
+        ),
+        unlocks_features=("OpenRouter proxy templates", "OSS workflow model workers"),
+        signup_url="https://openrouter.ai/keys",
+        note="Routes to Claude, GPT, Gemini, DeepSeek, etc. via OpenRouter",
+    ),
+    "anthropic-api": Credential(
+        name="anthropic-api",
+        env_vars=(EnvVar("ANTHROPIC_API_KEY"),),
+        unlocks_features=(
+            "Forge subprocesses (supervisor, handoff agent)",
+            "direct Anthropic panel/debate workers",
+            "litellm-anthropic-local proxy",
+        ),
+        signup_url="https://console.anthropic.com/",
+        note="Pay-per-token API key. Not Claude Code login.",
+        not_needed_for=(
+            "forge session start (uses Claude Code's own auth)",
+            "Claude via openrouter-anthropic (uses OPENROUTER_API_KEY)",
+            "Claude via litellm-anthropic (uses LITELLM_API_KEY)",
+        ),
+    ),
+    "openai-api": Credential(
+        name="openai-api",
+        env_vars=(EnvVar("OPENAI_API_KEY"),),
+        unlocks_features=("litellm-openai-local proxy",),
+        signup_url="https://platform.openai.com/api-keys",
+        note="OpenAI API key for local LiteLLM proxy routing",
+    ),
+    "gemini-api": Credential(
+        name="gemini-api",
+        env_vars=(EnvVar("GEMINI_API_KEY"),),
+        unlocks_features=("litellm-gemini-local proxy",),
+        signup_url="https://aistudio.google.com/apikey",
+        note="Gemini API key for local LiteLLM proxy routing",
+    ),
+    "litellm-remote": Credential(
+        name="litellm-remote",
+        env_vars=(
+            EnvVar("LITELLM_API_KEY"),
+            EnvVar("LITELLM_BASE_URL", secret=False, connection_value=True),
+        ),
+        unlocks_features=("Remote LiteLLM proxy templates",),
+        note="Shared/internal LiteLLM server (team setups)",
+    ),
+}
+
+RETIRED_NAMES: dict[str, str] = {
+    "anthropic": (
+        "Unknown credential 'anthropic'. Did you mean 'anthropic-api'?\n"
+        "\n"
+        "  'anthropic-api' is for Forge subprocess auth (pay-per-token API key).\n"
+        "  It is NOT your Claude Code login.\n"
+        "\n"
+        "  Run: forge auth login -c anthropic-api"
+    ),
+    "litellm-local": (
+        "'litellm-local' is not a credential. It's a setup that uses upstream API keys.\n"
+        "\n"
+        "  Configure the providers you need:\n"
+        "    forge auth login -c gemini-api       # for litellm-gemini-local\n"
+        "    forge auth login -c openai-api       # for litellm-openai-local\n"
+        "    forge auth login -c anthropic-api    # for litellm-anthropic-local"
+    ),
+}
+
+
+def credential_for_env_var(var_name: str) -> Credential | None:
+    """Find the credential that owns a given env var name."""
+    for cred in CREDENTIALS.values():
+        if any(ev.name == var_name for ev in cred.env_vars):
+            return cred
+    return None
+
+
+def credentials_for_template(template: str) -> list[Credential]:
+    """Which credentials does a template need?
+
+    Bridges TEMPLATE_SECRETS (template -> env var names) to CREDENTIALS
+    (credential -> env var metadata) via reverse lookup.
+    """
+    from forge.core.auth.template_secrets import TEMPLATE_SECRETS
+
+    required_vars = TEMPLATE_SECRETS.get(template, [])
+    if not required_vars:
+        return []
+
+    seen: set[str] = set()
+    result: list[Credential] = []
+    for var_name in required_vars:
+        cred = credential_for_env_var(var_name)
+        if cred and cred.name not in seen:
+            seen.add(cred.name)
+            result.append(cred)
+    return result
+
+
+def format_missing_credential_error(
+    credential: Credential,
+    *,
+    missing_vars: list[str],
+    template: str | None = None,
+    context: str | None = None,
+    extra_hint: str | None = None,
+    profile: str | None = None,
+    env_ignored: bool = False,
+) -> str:
+    """Build an actionable error message for missing credentials.
+
+    Includes what failed, which key(s), signup URL, and the exact
+    ``forge auth login`` command. Renders ``not_needed_for`` only for
+    anthropic-api (where false urgency is common).
+    """
+    key_word = "key" if len(missing_vars) == 1 else "keys"
+    var_list = ", ".join(missing_vars)
+
+    if context and template:
+        header = f"{context} requires {var_list} (template '{template}')."
+    elif context:
+        header = f"{context} requires {var_list}."
+    elif template:
+        header = f"Template '{template}' requires {key_word}: {var_list}."
+    else:
+        header = f"Missing {key_word}: {var_list}."
+
+    lines = [f"Error: {header}"]
+
+    if credential.note:
+        lines.append(f"\n  {credential.note}")
+
+    if credential.not_needed_for:
+        lines.append("")
+        lines.append("  NOT needed for:")
+        for item in credential.not_needed_for:
+            lines.append(f"    - {item}")
+
+    unlocks = credential.unlocks_features
+    if unlocks:
+        lines.append(f"\n  Unlocks: {', '.join(unlocks)}")
+
+    if credential.signup_url:
+        lines.append(f"  Get one at {credential.signup_url}")
+
+    login_cmd = f"forge auth login -c {credential.name}"
+    if profile:
+        login_cmd += f" --profile {profile}"
+    lines.append(f"  Tip: Run '{login_cmd}' to configure.")
+
+    if extra_hint:
+        lines.append(f"       {extra_hint}")
+
+    if env_ignored:
+        present_in_env = [v for v in missing_vars if _env_has(v)]
+        if present_in_env:
+            env_list = ", ".join(present_in_env)
+            verb = "is" if len(present_in_env) == 1 else "are"
+            pronoun = "it" if len(present_in_env) == 1 else "them"
+            lines.append(
+                f"\n  Note: {env_list} {verb} set in env but auth_ignore_env is active."
+                f"\n  Run 'forge config set auth_ignore_env=false' to use {pronoun}."
+            )
+
+    return "\n".join(lines)
+
+
+def _env_has(var_name: str) -> bool:
+    """Check if an env var is set (for env_ignored diagnostic only)."""
+    import os
+
+    return bool(os.environ.get(var_name))

forge/core/auth/credentials_file.py

@@ -0,0 +1,244 @@
+"""File-based credential store (~/.forge/credentials.yaml).
+
+Provides atomic read/write for the credential file with named profiles.
+The FileSecretsProvider (in secrets.py) reads from this store;
+CLI commands (forge auth login/status/logout) write via these functions.
+
+Schema:
+    version: 1
+    profiles:
+      default:
+        LITELLM_API_KEY: "sk-..."
+      personal:
+        ANTHROPIC_API_KEY: "sk-ant-..."
+
+Security: file permissions set to 0o600 (owner read/write only).
+Concurrency: advisory file lock on write to prevent concurrent clobber.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from forge.core.paths import get_forge_home
+from forge.core.state.lock import file_lock_for_target
+
+CREDENTIALS_FILENAME = "credentials.yaml"
+SCHEMA_VERSION = 1
+
+
+class CredentialVersionError(Exception):
+    """Credential file has an incompatible schema version.
+
+    Distinct from ValueError (YAML corruption) so callers can distinguish
+    "safe to overwrite" from "don't touch — upgrade Forge first".
+    """
+
+
+# Profile names: alphanumeric, hyphens, underscores only
+_PROFILE_NAME_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def get_credentials_path() -> Path:
+    """Return path to ~/.forge/credentials.yaml."""
+    return get_forge_home() / CREDENTIALS_FILENAME
+
+
+def resolve_profile(profile: str | None = None) -> str:
+    """Resolve active profile name.
+
+    Args:
+        profile: Explicit profile name (from CLI --profile flag).
+                 If None, falls back to FORGE_PROFILE env var, then "default".
+    """
+    if profile is not None:
+        return profile
+    return os.environ.get("FORGE_PROFILE", "default")
+
+
+def _validate_profile_name(name: str) -> None:
+    """Validate profile name contains only safe characters.
+
+    Raises:
+        ValueError: If name contains path separators, spaces, or control chars.
+    """
+    if not _PROFILE_NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid profile name '{name}': "
+            f"must match [A-Za-z0-9_-] (no spaces, path separators, or special chars)"
+        )
+
+
+def load_credentials(path: Path | None = None) -> dict[str, dict[str, str]]:
+    """Load all profiles from the credentials file.
+
+    Returns:
+        Dict mapping profile names to their key-value secrets.
+        Returns empty dict if file doesn't exist.
+
+    Raises:
+        ValueError: If file exists but is malformed.
+    """
+    creds_path = path or get_credentials_path()
+    if not creds_path.exists():
+        return {}
+
+    try:
+        with open(creds_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ValueError(
+            f"Corrupt credentials file: {creds_path}\n"
+            f"Recovery: mv {creds_path} {creds_path}.corrupt && forge auth login\n"
+            f"Parse error: {e}"
+        ) from e
+
+    if data is None:
+        return {}
+
+    if not isinstance(data, dict):
+        raise ValueError(f"credentials.yaml must be a YAML mapping, got {type(data).__name__}")
+
+    version = data.get("version")
+    if version is not None and version != SCHEMA_VERSION:
+        raise CredentialVersionError(
+            f"credentials.yaml has version {version}, but this Forge only supports version {SCHEMA_VERSION}. "
+            f"Upgrade Forge or recreate the file with 'forge auth login'."
+        )
+
+    profiles = data.get("profiles", {})
+    if not isinstance(profiles, dict):
+        raise ValueError("credentials.yaml 'profiles' must be a mapping")
+
+    # Validate all profile values are flat string dicts
+    for name, secrets in profiles.items():
+        if not isinstance(secrets, dict):
+            raise ValueError(f"Profile '{name}' must be a mapping")
+        for k, v in secrets.items():
+            if not isinstance(v, str):
+                raise ValueError(f"Profile '{name}' key '{k}' must be a string, got {type(v).__name__}")
+
+    return profiles
+
+
+def load_profile(profile: str, *, path: Path | None = None) -> dict[str, str]:
+    """Load a single profile's secrets.
+
+    Returns empty dict if the profile or file doesn't exist.
+    """
+    profiles = load_credentials(path)
+    return profiles.get(profile, {})
+
+
+def save_profile(
+    profile: str,
+    secrets: dict[str, str],
+    *,
+    path: Path | None = None,
+    merge: bool = True,
+) -> Path:
+    """Save secrets to a profile in the credentials file.
+
+    Uses advisory file lock, atomic write (tempfile + os.replace),
+    and 0o600 permissions.
+
+    Args:
+        profile: Profile name to save to.
+        secrets: Key-value pairs to store.
+        path: Override credentials file path (for testing).
+        merge: If True, merge with existing profile secrets.
+               If False, replace the profile entirely.
+
+    Returns:
+        Path to credentials file.
+
+    Raises:
+        ValueError: If profile name is invalid.
+    """
+    _validate_profile_name(profile)
+
+    creds_path = path or get_credentials_path()
+
+    with file_lock_for_target(target_path=creds_path, timeout_s=5.0):
+        # Read-modify-write under lock
+        try:
+            profiles = load_credentials(creds_path)
+        except ValueError:
+            # Corrupt file — start fresh under lock
+            profiles = {}
+
+        if merge and profile in profiles:
+            profiles[profile].update(secrets)
+        else:
+            profiles[profile] = dict(secrets)
+
+        _write_credentials(creds_path, profiles)
+
+    return creds_path
+
+
+def delete_profile(profile: str, *, path: Path | None = None) -> bool:
+    """Delete a profile from the credentials file.
+
+    Returns True if the profile existed, False otherwise.
+
+    Raises:
+        ValueError: If profile name is invalid.
+    """
+    _validate_profile_name(profile)
+
+    creds_path = path or get_credentials_path()
+
+    with file_lock_for_target(target_path=creds_path, timeout_s=5.0):
+        try:
+            profiles = load_credentials(creds_path)
+        except ValueError:
+            return False
+
+        if profile not in profiles:
+            return False
+
+        del profiles[profile]
+        _write_credentials(creds_path, profiles)
+
+    return True
+
+
+def list_profiles(path: Path | None = None) -> list[str]:
+    """Return sorted list of profile names."""
+    profiles = load_credentials(path)
+    return sorted(profiles.keys())
+
+
+def _write_credentials(creds_path: Path, profiles: dict[str, dict[str, str]]) -> None:
+    """Atomic write of credentials file with 0o600 permissions."""
+    creds_path.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict[str, Any] = {
+        "version": SCHEMA_VERSION,
+        "profiles": profiles,
+    }
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(creds_path.parent),
+        prefix=f".{creds_path.stem}.",
+        suffix=".tmp",
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write("# Forge Credential Store — managed by `forge auth login`\n\n")
+            yaml.safe_dump(data, f, default_flow_style=False, sort_keys=False)
+        os.chmod(tmp_path, 0o600)
+        os.replace(tmp_path, str(creds_path))
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise

forge/core/auth/protocols.py

@@ -0,0 +1,18 @@
+"""Authentication protocols shared across auth and LLM modules."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SecretsProvider(Protocol):
+    """Protocol for optional and required secret lookup."""
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a secret value, returning default if not found or empty."""
+        ...
+
+    def require(self, key: str) -> str:
+        """Get a required secret value, raising if not found or empty."""
+        ...