deepctl-core 0.3.0__tar.gz → 0.3.1__tar.gz

{deepctl_core-0.3.0 → deepctl_core-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-core
-Version: 0.3.0
+Version: 0.3.1
 Summary: Core components for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>

{deepctl_core-0.3.0 → deepctl_core-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-core"
-version = "0.3.0" # x-release-please-version
+version = "0.3.1" # x-release-please-version
 description = "Core components for deepctl"
 readme = "README.md"
 license = "MIT"

{deepctl_core-0.3.0 → deepctl_core-0.3.1}/src/deepctl_core/__init__.py

@@ -5,8 +5,10 @@ from .base_command import BaseCommand
 from .base_group_command import BaseGroupCommand
 from .client import DeepgramClient
 from .config import Config
+from .hosts import CredentialHostError
 from .models import (
     BaseResult,
+    CodedErrorResult,
     ErrorResult,
     PluginInfo,
     ProfileInfo,
@@ -18,6 +20,7 @@ from .output import (
     get_output_format,
     get_status_console,
     is_agentic,
+    is_ai_agent,
     print_error,
     print_info,
     print_output,
@@ -41,7 +44,9 @@ __all__ = [
     "BaseCommand",
     "BaseGroupCommand",
     "BaseResult",
+    "CodedErrorResult",
     "Config",
+    "CredentialHostError",
     "DeepgramClient",
     "ErrorResult",
     "OutputFormatter",
@@ -56,6 +61,7 @@ __all__ = [
     "get_status_console",
     "get_timing_summary",
     "is_agentic",
+    "is_ai_agent",
     "is_timing_enabled",
     "print_error",
     "print_info",

deepctl_core-0.3.1/src/deepctl_core/_launcher.py

@@ -0,0 +1,67 @@
+"""Which wrapper, if any, started deepctl (internal; not a public API).
+
+The ``@deepgram/cli`` npm package runs deepctl from a private venv and says
+so in ``DEEPCTL_LAUNCHER``: ``npm`` for an installed package (global, or a
+project dependency: the launcher can't tell them apart), ``npx`` for
+``npx``/``npm exec``. Nothing else sets it.
+
+The variable is read once and removed from ``os.environ``, so it describes
+this process only. Anything deepctl spawns -- a starter app, a shell, another
+``dg`` -- must not inherit a claim about how *it* was installed.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+LAUNCHER_ENV_VAR = "DEEPCTL_LAUNCHER"
+NPM_LAUNCHERS = frozenset({"npm", "npx"})
+
+_captured = False
+_launcher: str | None = None
+
+
+def capture_launcher() -> str | None:
+    """The launcher that started deepctl, captured on the first call.
+
+    Reads and removes ``DEEPCTL_LAUNCHER``, unless ``deepctl.main`` already
+    did and says so with ``LAUNCHER_CAPTURED``: then its ``LAUNCHER`` is the
+    value. From 0.5.0 (#165), ``deepctl.main`` is stdlib-only and removes the
+    variable before deepctl_core is imported, so it is gone from
+    ``os.environ`` by the time this runs. A ``deepctl.main`` that calls this
+    function itself sets no flag, and the check falls through.
+    """
+    global _captured, _launcher
+    if not _captured:
+        entry = sys.modules.get("deepctl.main")
+        if entry is not None and getattr(entry, "LAUNCHER_CAPTURED", False):
+            _launcher = entry.LAUNCHER
+        else:
+            _launcher = os.environ.pop(LAUNCHER_ENV_VAR, None) or None
+        _captured = True
+    return _launcher
+
+
+def get_launcher() -> str | None:
+    """Return the launcher that started deepctl, or ``None``."""
+    return capture_launcher()
+
+
+def launched_via_npm() -> bool:
+    """Return True if the npm package (global install or npx) started deepctl."""
+    return get_launcher() in NPM_LAUNCHERS
+
+
+def npm_upgrade_command() -> str:
+    """Return the command that upgrades an npm-launched deepctl."""
+    if get_launcher() == "npx":
+        return "npx @deepgram/cli@latest"
+    return "npm install -g @deepgram/cli@latest"
+
+
+def reset_launcher_for_tests() -> None:
+    """Forget the captured value so the next call re-reads the environment."""
+    global _captured, _launcher
+    _captured = False
+    _launcher = None

deepctl_core-0.3.1/src/deepctl_core/_plugin_trust.py

@@ -0,0 +1,118 @@
+"""Trusted locations for plugin settings and the plugin venv.
+
+Built on the config module's real-home trust helpers: the account's home
+comes from the OS (``HOME`` aside, the known-folder API on Windows), and in
+an AI agent session the user config is read only through the checked open
+of the trust root (no symlinked component, owned by this user, one link, no
+group or other write).
+"""
+
+import os
+from pathlib import Path
+
+import yaml
+
+from . import config as _config
+from .output import is_ai_agent
+
+__all__ = [
+    "agent_plugin_venv",
+    "allow_override_names",
+    "contained_in",
+    "is_ai_agent",
+    "real_home_plugin_venv",
+    "trusted_user_config_file",
+]
+
+
+def _agent_trust_root() -> Path | None:
+    """The trust root's config path, unless it lies inside the working
+    directory (and that directory isn't the home itself)."""
+    location = _config._trust_root_location()
+    home = _config._real_home()
+    if location is None or home is None:
+        return None
+    real = location[1]
+    try:
+        resolved = os.path.realpath(real)
+        cwd = os.path.realpath(os.getcwd())
+        at_home = cwd == os.path.realpath(home)
+    except (OSError, ValueError):
+        return None
+    if not at_home and _under(resolved, cwd):
+        return None
+    return real
+
+
+def trusted_user_config_file() -> Path | None:
+    """The user config file at its default location. Under an AI-agent
+    signal, only the one derived from the real home directory."""
+    if is_ai_agent():
+        return _agent_trust_root()
+    return _config._default_config_file()
+
+
+def allow_override_names() -> frozenset[str]:
+    """Command paths listed in ``plugins.allow_override`` of the trusted file.
+
+    Never read from a ``--config`` file, ``deepgram.yaml`` or the environment.
+    Under an AI-agent signal the file must also pass the trust-root checks.
+    Any read or parse problem yields an empty set.
+    """
+    try:
+        if is_ai_agent():
+            if _agent_trust_root() is None:
+                return frozenset()
+            root = _config._open_trust_root()
+            data = root[1] if root is not None else None
+        else:
+            _, data = _config._read_yaml_fd(_config._default_config_file())
+    except (OSError, ValueError, yaml.YAMLError):
+        return frozenset()
+    plugins = data.get("plugins") if isinstance(data, dict) else None
+    names = plugins.get("allow_override") if isinstance(plugins, dict) else None
+    if not isinstance(names, list):
+        return frozenset()
+    return frozenset(" ".join(n.split()) for n in names if isinstance(n, str))
+
+
+def _under(path: str, directory: str) -> bool:
+    return path == directory or path.startswith(directory.rstrip(os.sep) + os.sep)
+
+
+def real_home_plugin_venv() -> Path | None:
+    """``.deepctl/plugins/venv`` under the real home directory, unchecked."""
+    home = _config._real_home()
+    return None if home is None else Path(home, ".deepctl", "plugins", "venv")
+
+
+def agent_plugin_venv() -> Path | None:
+    """The plugin venv to load under an AI-agent signal, or ``None``.
+
+    It is ``.deepctl/plugins/venv`` under the account's real home directory
+    (``HOME`` aside). ``None`` when the home can't be read, when a directory
+    below the home on the way to the venv is a symlink, or when the venv lies
+    inside the working directory and that directory isn't the home itself.
+    """
+    home = _config._real_home()
+    if home is None:
+        return None
+    try:
+        real_home = os.path.realpath(home)
+        venv = os.path.join(real_home, ".deepctl", "plugins", "venv")
+        if os.path.realpath(venv) != venv:
+            return None
+        cwd = os.path.realpath(os.getcwd())
+    except (OSError, ValueError):
+        return None
+    if cwd != real_home and _under(venv, cwd):
+        return None
+    return Path(venv)
+
+
+def contained_in(path: Path, directory: Path) -> bool:
+    """True when ``path`` resolves inside ``directory`` (resolved)."""
+    try:
+        return _under(os.path.realpath(path), os.path.realpath(directory))
+    except (OSError, ValueError):
+        return False

{deepctl_core-0.3.0 → deepctl_core-0.3.1}/src/deepctl_core/auth.py

@@ -10,10 +10,14 @@ import httpx
 import keyring
 from keyring.errors import PasswordDeleteError
 from pydantic import BaseModel
+from rich.markup import escape
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
+from . import hosts, output
+from . import messages as msg
 from .client import _split_base_url
 from .config import Config
+from .hosts import check_credential_host, check_identity_host
 from .models import ProfileInfo, ProfilesResult
 from .output import stderr_console
 
@@ -22,10 +26,8 @@ from .output import stderr_console
 # command writes to stdout. See get_status_console() in output.py.
 console = stderr_console
 
-# Auth provider base URL (dx-id OIDC provider)
-AUTH_BASE_URL = os.getenv("DEEPGRAM_CLI_BASE_URL", "https://id.dx.deepgram.com")
-DEVICE_CODE_URL = f"{AUTH_BASE_URL}/device/code"
-TOKEN_POLL_URL = f"{AUTH_BASE_URL}/device/token"
+# Auth provider (dx-id OIDC) base URL: hosts.DEFAULT_IDENTITY_URL, or
+# DEEPGRAM_CLI_BASE_URL, resolved per login through check_identity_host().
 
 # Registered OIDC client ID for the CLI
 CLIENT_ID = "deepgram-cli"
@@ -54,6 +56,54 @@ class TokenResponse(BaseModel):
     dg_expires_in: int | None = None
 
 
+def _insecure_allowed() -> bool:
+    """Whether DEEPGRAM_CLI_INSECURE may turn off TLS verification.
+
+    Only ``1`` or ``true`` count (``0``, ``false`` or anything else keeps
+    verification on), and never in an AI agent session. Even then it only
+    applies to localhost, 127.0.0.1 and [::1]: see ``_insecure_mounts``.
+    """
+    value = os.getenv("DEEPGRAM_CLI_INSECURE", "").strip().lower()
+    if value not in ("1", "true"):
+        return False
+    if output.is_ai_agent():
+        if hosts._first_time(("W-INSECURE-AGENT", "")):
+            output.print_security_warning(msg.W_INSECURE_AGENT)
+        return False
+    return True
+
+
+#: Hosts DEEPGRAM_CLI_INSECURE applies to: local dev servers only. Other
+#: 127.0.0.0/8 addresses keep verification (mounts match exact hosts).
+_INSECURE_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+
+def _insecure_mounts() -> dict[str, httpx.BaseTransport]:
+    """Unverified transports for the loopback hosts only.
+
+    Host-specific mounts take precedence over the scheme-wide proxy mounts
+    httpx builds from HTTPS_PROXY/ALL_PROXY/NO_PROXY, so every other host
+    keeps both certificate verification and the proxy settings.
+    """
+    unverified = httpx.HTTPTransport(verify=False)
+    return {
+        f"all://{'[::1]' if host == '::1' else host}": unverified
+        for host in _INSECURE_HOSTS
+    }
+
+
+def _warn_if_verified(request: httpx.Request) -> None:
+    """Say once per host that DEEPGRAM_CLI_INSECURE did not apply to it."""
+    host = request.url.host
+    if host in _INSECURE_HOSTS:
+        return
+    if hosts._first_time(("W-INSECURE-REMOTE", host)):
+        output.print_security_warning(
+            escape(msg.W_INSECURE_REMOTE.format(host=msg.display(host)))
+        )
+        output.print_hint(escape(msg.W_INSECURE_REMOTE_HINT))
+
+
 class AuthenticationError(Exception):
     """Authentication related errors."""
 
@@ -79,9 +129,27 @@ class AuthManager:
         self.config = config
         self.explicit_api_key = explicit_api_key
         self.explicit_project_id = explicit_project_id
-        # Disable SSL verification for local dev (DEEPGRAM_CLI_INSECURE=1)
-        verify = not bool(os.getenv("DEEPGRAM_CLI_INSECURE"))
-        self.client = httpx.Client(timeout=30.0, verify=verify)
+        # DEEPGRAM_CLI_INSECURE=1 skips TLS verification for localhost,
+        # 127.0.0.1 and [::1] (local dev), never for any other host and never
+        # in an AI agent session: the agent may have set it. Proxy settings
+        # from the environment still apply to every other host.
+        if _insecure_allowed():
+            self.client = httpx.Client(
+                timeout=30.0,
+                verify=True,
+                mounts=_insecure_mounts(),
+                event_hooks={"request": [_warn_if_verified]},
+            )
+        else:
+            self.client = httpx.Client(timeout=30.0, verify=True)
+
+    def check_base_url(self) -> str:
+        """Return the base URL credentials may be sent to.
+
+        Raises ``hosts.CredentialHostError`` (already reported on stderr)
+        when the effective host isn't trusted; nothing has been sent.
+        """
+        return check_credential_host(self.config)
 
     def has_env_credentials(self) -> tuple[bool, bool]:
         """Check if environment variables are set.
@@ -294,17 +362,19 @@ class AuthManager:
         if not api_key:
             return False, "No API key provided or stored", "auth"
 
+        # Verify against the configured base URL (not hardcoded prod), so a
+        # custom base (e.g. staging) validates its own keys correctly -- but
+        # only once that host is trusted with the key.
+        base = self.check_base_url()
+
         try:
             headers = {
                 "Authorization": f"Token {api_key}",
                 "Content-Type": "application/json",
             }
 
-            # Verify against the configured base URL (not hardcoded prod), so a
-            # custom base (e.g. staging) validates its own keys correctly.
             # Preserve the input scheme so a plaintext endpoint isn't forced
             # onto TLS.
-            base = self.config.get_profile().base_url or "https://api.deepgram.com"
             rest_scheme, _, host = _split_base_url(base)
             response = self.client.get(
                 f"{rest_scheme}://{host}/v1/projects",
@@ -362,6 +432,8 @@ class AuthManager:
         if not api_key:
             return False, "No API key provided or stored", "auth"
 
+        base = self.check_base_url()
+
         # If no project_id, just verify the API key alone
         if not project_id:
             return self.verify_api_key(api_key)
@@ -373,9 +445,10 @@ class AuthManager:
                 "Content-Type": "application/json",
             }
 
-            # Make request to get project details
+            # Project details from the same (checked) base URL as the key
+            rest_scheme, _, host = _split_base_url(base)
             response = self.client.get(
-                f"https://api.deepgram.com/v1/projects/{project_id}",
+                f"{rest_scheme}://{host}/v1/projects/{project_id}",
                 headers=headers,
             )
 
@@ -412,9 +485,23 @@ class AuthManager:
 
         Only validates that the API key works. Project ID validation
         is handled separately by requires_project on BaseCommand.
+        Refuses first, before reading or sending any key, when the base URL
+        isn't trusted with credentials.
         """
+        self.check_base_url()
         api_key = self.get_api_key()
 
+        if not api_key and getattr(self.config, "api_key_untrusted", False) is True:
+            # The file's key was left unused (W-PERM-AGENT / W-CFG-UNTRUSTED):
+            # say so, and send the agent to a person, not to dg login.
+            from rich.markup import escape
+
+            text = msg.E_KEY_UNTRUSTED.format(
+                user_config=msg.display_path(self.config.config_path)
+            )
+            output.print_error(escape(text))
+            output.print_hint(msg.W_CFG_UNTRUSTED_FILE_HINT)
+            raise AuthenticationError(text)
         if not api_key:
             console.print(
                 "[red]Error:[/red] DEEPGRAM_API_KEY is not set in the "
@@ -488,6 +575,8 @@ class AuthManager:
         # Store API key in keyring for security
         profile_name = self.config.profile or "default"
         keyring_available = False
+        # Nothing goes to the keyring when the profile can't be saved.
+        self.config.check_saveable()
 
         try:
             keyring.set_password(KEYRING_SERVICE, f"api-key.{profile_name}", api_key)
@@ -504,7 +593,6 @@ class AuthManager:
             profile_name,
             api_key=api_key if not keyring_available else None,
             project_id=project_id,  # Always store project ID in config
-            base_url=self.config.get_profile(profile_name).base_url,
         )
 
         console.print("[green]✓[/green] Successfully logged in with API key")
@@ -517,12 +605,15 @@ class AuthManager:
         """Login using device flow (interactive method)."""
         console.print("[blue]Starting device flow authentication...[/blue]")
 
+        # The token exchange mints the API key: check the identity host first.
+        identity_url = check_identity_host(self.config)
+
         try:
             # Get hostname for device identification
             hostname = os.uname().nodename if hasattr(os, "uname") else "unknown"
 
             # Request device code from dx-id auth provider
-            device_response = self._request_device_code()
+            device_response = self._request_device_code(identity_url)
 
             verification_uri = (
                 device_response.verification_uri_complete
@@ -549,7 +640,9 @@ class AuthManager:
             )
 
             # Poll for token (starts immediately — user may have clicked the link)
-            token_response = self._poll_for_token(device_response, hostname)
+            token_response = self._poll_for_token(
+                device_response, hostname, identity_url
+            )
 
             # Store token and get user info
             self._store_token(token_response)
@@ -561,7 +654,9 @@ class AuthManager:
             console.print(f"[red]Error during device flow:[/red] {e}")
             raise AuthenticationError(f"Device flow failed: {e}")
 
-    def _request_device_code(self) -> DeviceCodeResponse:
+    def _request_device_code(
+        self, identity_url: str | None = None
+    ) -> DeviceCodeResponse:
         """Request device code from auth provider.
 
         Returns:
@@ -576,8 +671,9 @@ class AuthManager:
         }
 
         try:
+            base = identity_url or check_identity_host(self.config)
             response = self.client.post(
-                DEVICE_CODE_URL,
+                f"{base}/device/code",
                 json=payload,
                 headers={"Content-Type": "application/json"},
             )
@@ -596,6 +692,7 @@ class AuthManager:
         self,
         device_response: DeviceCodeResponse,
         hostname: str,
+        identity_url: str | None = None,
     ) -> TokenResponse:
         """Poll for token using device code."""
         console.print("\n[blue]Waiting for authentication...[/blue]")
@@ -608,7 +705,8 @@ class AuthManager:
             "hostname": hostname,
         }
 
-        poll_url = f"{TOKEN_POLL_URL}?{urlencode(query_params)}"
+        base = identity_url or check_identity_host(self.config)
+        poll_url = f"{base}/device/token?{urlencode(query_params)}"
 
         with Progress(
             SpinnerColumn(),
@@ -666,6 +764,8 @@ class AuthManager:
             ).isoformat()
 
             keyring_available = False
+            # Nothing goes to the keyring when the profile can't be saved.
+            self.config.check_saveable()
             try:
                 keyring.set_password(
                     KEYRING_SERVICE, f"api-key.{profile_name}", api_key
@@ -684,7 +784,6 @@ class AuthManager:
                 profile_name,
                 api_key=api_key if not keyring_available else None,
                 project_id=token_response.project_id,
-                base_url=self.config.get_profile(profile_name).base_url,
             )
             profile = self.config.get_profile(profile_name)
             profile.dg_token_expires_at = expires_at
@@ -711,6 +810,8 @@ class AuthManager:
                         and only clear credentials. If False, remove profile completely.
         """
         profile_name = self.config.profile or "default"
+        # Nothing is cleared from the keyring when the profile can't be saved.
+        self.config.check_saveable()
 
         # Clear all credential types from keyring.
         for keyring_key in (
@@ -727,12 +828,9 @@ class AuthManager:
         if keep_config:
             # Clear sensitive data from config but keep profile
             if profile_name in self.config.list_profiles():
-                profile = self.config.get_profile(profile_name)
-                self.config.create_profile(
-                    profile_name,
-                    api_key=None,  # Clear API key
-                    project_id=profile.project_id,  # Keep project ID
-                    base_url=profile.base_url,  # Keep base URL
+                # Only the credential changes; project ID and base URL stay.
+                self.config.update_profile(
+                    profile_name, api_key=None, dg_token_expires_at=None
                 )
         else:
             # Clear profile completely from config