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,115 @@
+"""
+Shared utilities for credential helpers.
+
+Provides credential resolution and domain checking used by all helpers.
+Configuration is resolved via :class:`ConfigResolver` which reads from
+environment variables, config files, and defaults — the same sources
+used by the main CLI.
+"""
+
+import logging
+
+from ..core.config_resolver import ConfigResolver
+from ..core.credentials import CredentialContext, CredentialProviderChain
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_credentials(debug=False):
+    """Resolve Cloudsmith credentials using the provider chain.
+
+    Configuration (proxy, SSL, headers, etc.) is resolved automatically
+    from environment variables and config files via :class:`ConfigResolver`.
+
+    Args:
+        debug: Enable debug logging
+
+    Returns:
+        CredentialResult with .api_key, or None if no credentials available
+    """
+    config = ConfigResolver().resolve(debug=debug)
+    context = CredentialContext(config=config, debug=debug)
+
+    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
+    config = ConfigResolver().resolve()
+    org = config.oidc_org
+    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
+
+    custom_domains = get_custom_domains_for_org(org, config, result.api_key)
+
+    return hostname in [d.lower() for d in custom_domains]