feat: add Docker credential helper for Cloudsmith registries

Implement the Docker credential helper protocol so Docker can
automatically authenticate with Cloudsmith registries (including
custom domains) without manual `docker login`.

Key changes:
- Add `cloudsmith credential-helper docker` CLI command
- Add `docker-credential-cloudsmith` wrapper binary (entry point)
- Add credential resolution using the existing provider chain
  (OIDC, API keys, config, keyring)
- Add custom domain discovery via Cloudsmith API with filesystem caching
- Extract shared `create_session` helper, reused by SAML auth flow

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: cloudsmith-iduffy

cloudsmith_cli/cli/commands/__init__.py

@@ -4,6 +4,7 @@
     auth,
     check,
     copy,
+    credential_helper,
     delete,
     dependencies,
     docs,

cloudsmith_cli/cli/commands/credential_helper/__init__.py

@@ -0,0 +1,31 @@
+"""
+Credential helper commands for Cloudsmith.
+
+This module provides credential helper commands for package managers
+that follow their respective credential helper protocols.
+"""
+
+import click
+
+from ..main import main
+from .docker import docker as docker_cmd
+
+
+@click.group()
+def credential_helper():
+    """
+    Credential helpers for package managers.
+
+    These commands provide credentials for package managers like Docker.
+    They are typically called by wrapper binaries
+    (e.g., docker-credential-cloudsmith) or used directly for debugging.
+
+    Examples:
+        # Test Docker credential helper
+        $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
+    """
+
+
+credential_helper.add_command(docker_cmd, name="docker")
+
+main.add_command(credential_helper, name="credential-helper")

cloudsmith_cli/cli/commands/credential_helper/docker.py

@@ -0,0 +1,72 @@
+"""
+Docker credential helper command.
+
+Implements the Docker credential helper protocol for Cloudsmith registries.
+
+See: https://github.com/docker/docker-credential-helpers
+"""
+
+import json
+import sys
+
+import click
+
+from ....credential_helpers.docker import get_credentials
+
+
+@click.command()
+def docker():
+    """
+    Docker credential helper for Cloudsmith registries.
+
+    Reads a Docker registry server URL from stdin and returns credentials in JSON format.
+    This command implements the 'get' operation of the Docker credential helper protocol.
+
+    Only provides credentials for Cloudsmith Docker registries (docker.cloudsmith.io).
+
+    Input (stdin):
+        Server URL as plain text (e.g., "docker.cloudsmith.io")
+
+    Output (stdout):
+        JSON: {"Username": "token", "Secret": "<cloudsmith-token>"}
+
+    Exit codes:
+        0: Success
+        1: Error (no credentials available, not a Cloudsmith registry, etc.)
+
+    Examples:
+        # Manual testing
+        $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
+        {"Username":"token","Secret":"eyJ0eXAiOiJKV1Qi..."}
+
+        # Called by Docker via wrapper
+        $ echo "docker.cloudsmith.io" | docker-credential-cloudsmith get
+        {"Username":"token","Secret":"eyJ0eXAiOiJKV1Qi..."}
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG: Organization slug (required for custom domain support)
+    """
+    try:
+        server_url = sys.stdin.read().strip()
+
+        if not server_url:
+            click.echo("Error: No server URL provided on stdin", err=True)
+            sys.exit(1)
+
+        credentials = get_credentials(server_url, debug=False)
+
+        if not credentials:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Make sure you have a valid cloudsmith-cli session, "
+                "this can be checked with `cloudsmith whoami`.",
+                err=True,
+            )
+            sys.exit(1)
+
+        click.echo(json.dumps(credentials))
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

cloudsmith_cli/cli/saml.py

@@ -3,27 +3,19 @@
 import requests
 
 from ..core.api.exceptions import ApiException
+from ..core.credentials.session import create_session
 
 
 def create_configured_session(opts):
     """
     Create a requests session configured with the options from opts.
     """
-    session = requests.Session()
-
-    if hasattr(opts, "api_ssl_verify") and opts.api_ssl_verify is not None:
-        session.verify = opts.api_ssl_verify
-
-    if hasattr(opts, "api_proxy") and opts.api_proxy:
-        session.proxies = {"http": opts.api_proxy, "https": opts.api_proxy}
-
-    if hasattr(opts, "api_user_agent") and opts.api_user_agent:
-        session.headers.update({"User-Agent": opts.api_user_agent})
-
-    if hasattr(opts, "api_headers") and opts.api_headers:
-        session.headers.update(opts.api_headers)
-
-    return session
+    return create_session(
+        proxy=getattr(opts, "api_proxy", None),
+        ssl_verify=getattr(opts, "api_ssl_verify", True),
+        user_agent=getattr(opts, "api_user_agent", None),
+        headers=getattr(opts, "api_headers", None),
+    )
 
 
 def get_idp_url(api_host, owner, session):

cloudsmith_cli/credential_helpers/__init__.py

@@ -0,0 +1,6 @@
+"""
+Credential helpers for various package managers.
+
+This package provides credential helper implementations for Docker, pip, npm, etc.
+Each helper follows its respective package manager's credential helper protocol.
+"""

cloudsmith_cli/credential_helpers/common.py

@@ -0,0 +1,195 @@
+"""
+Shared utilities for credential helpers.
+
+Provides credential resolution and domain checking used by all helpers.
+Networking configuration (proxy, TLS, headers) is read from the same
+environment variables and config files used by the main CLI so that
+credential helpers work correctly behind proxies and with custom certs.
+"""
+
+import logging
+import os
+
+from ..core.credentials import CredentialContext, CredentialProviderChain
+
+logger = logging.getLogger(__name__)
+
+
+def _get_networking_config():
+    """Read networking configuration from env vars and the CLI config file.
+
+    Sources (in priority order):
+        1. Environment variables: CLOUDSMITH_API_PROXY,
+           CLOUDSMITH_WITHOUT_API_SSL_VERIFY, CLOUDSMITH_API_USER_AGENT,
+           CLOUDSMITH_API_HEADERS
+        2. CLI config file (config.ini): api_proxy, api_ssl_verify
+
+    Returns:
+        dict with keys: proxy, ssl_verify, user_agent, headers
+    """
+    proxy = os.environ.get("CLOUDSMITH_API_PROXY", "").strip() or None
+    user_agent = os.environ.get("CLOUDSMITH_API_USER_AGENT", "").strip() or None
+
+    # SSL verify: env var is an opt-out flag (presence means disable)
+    ssl_verify_env = os.environ.get("CLOUDSMITH_WITHOUT_API_SSL_VERIFY", "").strip()
+    ssl_verify = (
+        ssl_verify_env.lower() not in ("1", "true", "yes") if ssl_verify_env else True
+    )
+
+    # Parse extra headers from CSV "key=value,key2=value2"
+    headers = None
+    headers_env = os.environ.get("CLOUDSMITH_API_HEADERS", "").strip()
+    if headers_env:
+        headers = {}
+        for pair in headers_env.split(","):
+            if "=" in pair:
+                k, v = pair.split("=", 1)
+                headers[k.strip()] = v.strip()
+
+    # Fall back to CLI config file for proxy and ssl_verify
+    if not proxy or ssl_verify is True:
+        try:
+            from ..cli.config import ConfigReader
+
+            raw_config = ConfigReader.read_config()
+            defaults = raw_config.get("default", {})
+
+            if not proxy:
+                cfg_proxy = defaults.get("api_proxy", "").strip()
+                if cfg_proxy:
+                    proxy = cfg_proxy
+
+            # Only override ssl_verify if the env var wasn't explicitly set
+            if not ssl_verify_env:
+                cfg_ssl = defaults.get("api_ssl_verify", "true").strip().lower()
+                if cfg_ssl in ("0", "false", "no"):
+                    ssl_verify = False
+        except Exception:  # pylint: disable=broad-exception-caught
+            logger.debug("Failed to read CLI config for networking", exc_info=True)
+
+    return {
+        "proxy": proxy,
+        "ssl_verify": ssl_verify,
+        "user_agent": user_agent,
+        "headers": headers,
+    }
+
+
+def resolve_credentials(debug=False):
+    """
+    Resolve Cloudsmith credentials using the provider chain.
+
+    Tries providers in order: environment variables, config file, keyring, OIDC.
+    Networking configuration is read from env vars and the CLI config file so
+    that OIDC token exchange works behind proxies.
+
+    Args:
+        debug: Enable debug logging
+
+    Returns:
+        CredentialResult with .api_key, or None if no credentials available
+    """
+    api_host = os.environ.get("CLOUDSMITH_API_HOST", "https://api.cloudsmith.io")
+    net = _get_networking_config()
+
+    context = CredentialContext(
+        api_host=api_host,
+        debug=debug,
+        proxy=net["proxy"],
+        ssl_verify=net["ssl_verify"],
+        user_agent=net["user_agent"],
+        headers=net["headers"],
+    )
+
+    chain = CredentialProviderChain()
+    result = chain.resolve(context)
+
+    if not result or not result.api_key:
+        return None
+
+    return result
+
+
+def extract_hostname(url):
+    """
+    Extract bare hostname from any URL format.
+
+    Handles protocols, sparse+ prefix, ports, paths, and trailing slashes.
+
+    Args:
+        url: URL in any format (e.g., "sparse+https://cargo.cloudsmith.io/org/repo/")
+
+    Returns:
+        str: Lowercase hostname (e.g., "cargo.cloudsmith.io")
+    """
+    if not url:
+        return ""
+
+    normalized = url.lower().strip()
+
+    # Remove sparse+ prefix (Cargo)
+    if normalized.startswith("sparse+"):
+        normalized = normalized[7:]
+
+    # Remove protocol
+    if "://" in normalized:
+        normalized = normalized.split("://", 1)[1]
+
+    # Remove userinfo (user@host)
+    if "@" in normalized.split("/")[0]:
+        normalized = normalized.split("@", 1)[1]
+
+    # Extract hostname (before first / or :)
+    hostname = normalized.split("/")[0].split(":")[0]
+
+    return hostname
+
+
+def is_cloudsmith_domain(url, _credential_result=None):
+    """
+    Check if a URL points to a Cloudsmith service.
+
+    Checks standard *.cloudsmith.io domains first (no auth needed).
+    If not a standard domain, uses the provided credential result (or
+    resolves credentials) and queries the Cloudsmith API for custom domains.
+
+    Args:
+        url: URL or hostname to check
+        _credential_result: Pre-resolved CredentialResult to avoid duplicate
+            credential resolution. If None, resolves credentials internally.
+
+    Returns:
+        bool: True if this is a Cloudsmith domain
+    """
+    hostname = extract_hostname(url)
+    if not hostname:
+        return False
+
+    # Standard Cloudsmith domains — no auth needed
+    if hostname.endswith("cloudsmith.io") or hostname == "cloudsmith.io":
+        return True
+
+    # Custom domains require org + auth
+    org = os.environ.get("CLOUDSMITH_ORG", "").strip()
+    if not org:
+        return False
+
+    result = _credential_result or resolve_credentials()
+    if not result:
+        return False
+
+    from .custom_domains import get_custom_domains_for_org
+
+    api_host = os.environ.get("CLOUDSMITH_API_HOST", "https://api.cloudsmith.io")
+    net = _get_networking_config()
+    custom_domains = get_custom_domains_for_org(
+        org,
+        api_host,
+        result.api_key,
+        proxy=net["proxy"],
+        ssl_verify=net["ssl_verify"],
+        user_agent=net["user_agent"],
+        headers=net["headers"],
+    )
+
+    return hostname in [d.lower() for d in custom_domains]