feat: Add credential helpers for package manager authentication

Add credential helpers that automatically authenticate package managers
with Cloudsmith registries using the credential provider chain
(Environment Variable → Config File → Keyring → OIDC).

Supported formats:

  Docker          docker-credential-cloudsmith
  Terraform       terraform-credentials-cloudsmith
  Cargo           cargo-credential-cloudsmith
  pnpm            cloudsmith-token-helper
  NuGet           CredentialProvider.Cloudsmith
  pip/twine       keyring backend (auto-discovered)
  Conda           conda plugin (auto-discovered)

## Docker

Configure `~/.docker/config.json`:

  {
    "credHelpers": {
      "docker.cloudsmith.io": "cloudsmith"
    }
  }

Then:

  docker pull docker.cloudsmith.io/myorg/myrepo/myimage:latest

## Terraform

Install the helper and configure `~/.terraformrc`:

  mkdir -p ~/.terraform.d/plugins
  ln -sf "$(which terraform-credentials-cloudsmith)" ~/.terraform.d/plugins/

  credentials_helper "cloudsmith" {
    args = []
  }

Requires CLOUDSMITH_ORG and CLOUDSMITH_REPO environment variables.
Token format is org/repo/token per Cloudsmith's Terraform registry API.

## Cargo

Configure `~/.cargo/config.toml`:

  [registries.cloudsmith]
  index = "sparse+https://cargo.cloudsmith.io/myorg/myrepo/"
  credential-provider = ["cargo-credential-cloudsmith"]

Then:

  cargo add my-crate --registry cloudsmith

## pnpm

Configure `~/.npmrc` (requires absolute path to helper):

  registry=https://npm.cloudsmith.io/myorg/myrepo/
  //npm.cloudsmith.io/myorg/myrepo/:tokenHelper=/usr/local/bin/cloudsmith-token-helper

Returns "Bearer <token>" as pnpm does not auto-add the prefix.

## NuGet

Set NUGET_CREDENTIALPROVIDERS_PATH to the directory containing
CredentialProvider.Cloudsmith and add a package source:

  <packageSources>
    <add key="cloudsmith"
         value="https://nuget.cloudsmith.io/myorg/myrepo/v3/index.json" />
  </packageSources>

Then:

  dotnet restore

## pip / twine

Auto-discovered via the keyring.backends entry point. No configuration
needed beyond installing cloudsmith-cli:

  pip install --index-url=https://dl.cloudsmith.io/basic/myorg/myrepo/python/simple/ mypkg

## Conda

Auto-discovered via the conda plugin entry point. Install cloudsmith-cli
into conda's base Python environment. Configure `~/.condarc`:

  channel_settings:
    - channel: https://conda.cloudsmith.io/myorg/myrepo/
      auth: cloudsmith
  channels:
    - https://conda.cloudsmith.io/myorg/myrepo/
    - defaults

Then:

  conda install my-package

## Architecture

- cloudsmith_cli/credential_helpers/common.py: shared resolve_credentials(),
  extract_hostname(), is_cloudsmith_domain() used by all helpers
- CredentialProviderChain defaults to the standard 4-provider chain
- Networking config (proxy, TLS, headers) read from CLOUDSMITH_API_PROXY,
  CLOUDSMITH_WITHOUT_API_SSL_VERIFY, CLOUDSMITH_API_USER_AGENT,
  CLOUDSMITH_API_HEADERS env vars and config.ini
- Custom domain discovery via GET /orgs/{org}/custom-domains/ with
  1-hour filesystem cache in ~/.cloudsmith/cache/custom_domains/

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

Author: cloudsmith-iduffy

cloudsmith_cli/cli/commands/credential_helper/cargo.py

@@ -0,0 +1,61 @@
+"""
+Cargo credential helper command.
+
+Implements credential retrieval for Cargo registries hosted on Cloudsmith.
+"""
+
+import json
+import sys
+
+import click
+
+from ....credential_helpers.cargo import get_credentials
+
+
+@click.command()
+@click.argument("index_url", required=False, default=None)
+def cargo(index_url):
+    """
+    Cargo credential helper for Cloudsmith registries.
+
+    Returns credentials as a Bearer token for Cargo sparse registries.
+
+    If INDEX_URL is provided as an argument, uses it directly.
+    Otherwise reads from stdin.
+
+    Examples:
+        # Direct usage
+        $ cloudsmith credential-helper cargo sparse+https://cargo.cloudsmith.io/org/repo/
+        Bearer eyJ0eXAiOiJKV1Qi...
+
+        # Via wrapper (called by Cargo)
+        $ cargo-credential-cloudsmith --cargo-plugin
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG: Organization slug (required for OIDC)
+        CLOUDSMITH_SERVICE_SLUG: Service account slug (required for OIDC)
+    """
+    try:
+        if not index_url:
+            index_url = sys.stdin.read().strip()
+
+        if not index_url:
+            click.echo("Error: No index URL provided", err=True)
+            sys.exit(1)
+
+        token = get_credentials(index_url, debug=False)
+
+        if not token:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Set CLOUDSMITH_API_KEY or configure OIDC.",
+                err=True,
+            )
+            sys.exit(1)
+
+        click.echo(json.dumps({"token": f"Bearer {token}"}))
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

cloudsmith_cli/cli/commands/credential_helper/conda.py

@@ -0,0 +1,62 @@
+"""
+Conda credential helper command.
+
+Provides credential retrieval for Conda channels hosted on Cloudsmith.
+"""
+
+import json
+import sys
+
+import click
+
+from ....credential_helpers.conda import get_credentials
+
+
+@click.command()
+@click.argument("channel_url", required=False, default=None)
+def conda(channel_url):
+    """
+    Conda credential helper for Cloudsmith channels.
+
+    Returns credentials as JSON for Cloudsmith Conda channels.
+
+    If CHANNEL_URL is provided as an argument, uses it directly.
+    Otherwise reads from stdin.
+
+    Examples:
+        # Direct usage
+        $ cloudsmith credential-helper conda https://conda.cloudsmith.io/org/repo/
+        {"username":"token","password":"eyJ0eXAiOiJKV1Qi..."}
+
+    The conda plugin (cloudsmith_cli.credential_helpers.conda.plugin) provides
+    automatic authentication when installed as a conda plugin.
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG: Organization slug (required for OIDC)
+        CLOUDSMITH_SERVICE_SLUG: Service account slug (required for OIDC)
+    """
+    try:
+        if not channel_url:
+            channel_url = sys.stdin.read().strip()
+
+        if not channel_url:
+            click.echo("Error: No channel URL provided", err=True)
+            sys.exit(1)
+
+        creds = get_credentials(channel_url, debug=False)
+
+        if not creds:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Set CLOUDSMITH_API_KEY or configure OIDC.",
+                err=True,
+            )
+            sys.exit(1)
+
+        username, password = creds
+        click.echo(json.dumps({"username": username, "password": password}))
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

cloudsmith_cli/cli/commands/credential_helper/npm.py

@@ -0,0 +1,57 @@
+"""
+npm/pnpm token helper command.
+
+Prints a raw Cloudsmith API token for use with pnpm's tokenHelper.
+"""
+
+import sys
+
+import click
+
+from ....credential_helpers.npm import get_token
+
+
+@click.command()
+def npm():
+    """
+    npm/pnpm token helper for Cloudsmith registries.
+
+    Prints a raw API token to stdout for use with pnpm's tokenHelper configuration.
+
+    Examples:
+        # Direct usage
+        $ cloudsmith credential-helper npm
+        eyJ0eXAiOiJKV1Qi...
+
+        # Via wrapper (called by pnpm)
+        $ cloudsmith-token-helper
+        eyJ0eXAiOiJKV1Qi...
+
+    Configuration in ~/.npmrc:
+        //npm.cloudsmith.io/:tokenHelper=/absolute/path/to/cloudsmith-token-helper
+
+    Find the path with: which cloudsmith-token-helper
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG: Organization slug (required for OIDC)
+        CLOUDSMITH_SERVICE_SLUG: Service account slug (required for OIDC)
+    """
+    try:
+        token = get_token(debug=False)
+
+        if not token:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Set CLOUDSMITH_API_KEY or configure OIDC.",
+                err=True,
+            )
+            sys.exit(1)
+
+        # Raw token output — no JSON, no trailing newline issues
+        sys.stdout.write(token)
+        sys.stdout.flush()
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

cloudsmith_cli/cli/commands/credential_helper/nuget.py

@@ -0,0 +1,62 @@
+"""
+NuGet credential helper command.
+
+Implements credential retrieval for NuGet feeds hosted on Cloudsmith.
+"""
+
+import json
+import sys
+
+import click
+
+from ....credential_helpers.nuget import get_credentials
+
+
+@click.command()
+@click.argument("uri", required=False, default=None)
+def nuget(uri):
+    """
+    NuGet credential helper for Cloudsmith feeds.
+
+    Returns credentials in NuGet's expected JSON format:
+    {"Username": "token", "Password": "...", "Message": ""}
+
+    If URI is provided as an argument, uses it directly.
+    Otherwise reads from stdin.
+
+    Examples:
+        # Direct usage
+        $ cloudsmith credential-helper nuget https://nuget.cloudsmith.io/org/repo/v3/index.json
+        {"Username":"token","Password":"eyJ0eXAiOiJKV1Qi...","Message":""}
+
+        # Via wrapper (called by NuGet)
+        $ CredentialProvider.Cloudsmith -uri https://nuget.cloudsmith.io/org/repo/v3/index.json
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG: Organization slug (required for OIDC)
+        CLOUDSMITH_SERVICE_SLUG: Service account slug (required for OIDC)
+    """
+    try:
+        if not uri:
+            uri = sys.stdin.read().strip()
+
+        if not uri:
+            click.echo("Error: No URI provided", err=True)
+            sys.exit(1)
+
+        credentials = get_credentials(uri, debug=False)
+
+        if not credentials:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Set CLOUDSMITH_API_KEY or configure OIDC.",
+                err=True,
+            )
+            sys.exit(1)
+
+        click.echo(json.dumps({**credentials, "Message": ""}))
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

cloudsmith_cli/cli/commands/credential_helper/terraform.py

@@ -0,0 +1,63 @@
+"""
+Terraform credential helper command.
+
+Implements the Terraform credential helper protocol for Cloudsmith registries.
+"""
+
+import json
+import sys
+
+import click
+
+from ....credential_helpers.terraform import get_credentials
+
+
+@click.command()
+@click.argument("hostname", required=False, default=None)
+def terraform(hostname):
+    """
+    Terraform credential helper for Cloudsmith registries.
+
+    Returns credentials in Terraform's expected JSON format: {"token": "..."}
+
+    Can be used directly or via the terraform-credentials-cloudsmith wrapper.
+
+    If HOSTNAME is provided as an argument, uses it directly.
+    Otherwise reads from stdin (for use with the wrapper binary).
+
+    Examples:
+        # Direct usage
+        $ cloudsmith credential-helper terraform terraform.cloudsmith.io
+        {"token":"eyJ0eXAiOiJKV1Qi..."}
+
+        # Via wrapper
+        $ terraform-credentials-cloudsmith get terraform.cloudsmith.io
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG: Organization slug (required for OIDC)
+        CLOUDSMITH_SERVICE_SLUG: Service account slug (required for OIDC)
+    """
+    try:
+        if not hostname:
+            hostname = sys.stdin.read().strip()
+
+        if not hostname:
+            click.echo("Error: No hostname provided", err=True)
+            sys.exit(1)
+
+        token = get_credentials(hostname, debug=False)
+
+        if not token:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Set CLOUDSMITH_API_KEY or configure OIDC.",
+                err=True,
+            )
+            sys.exit(1)
+
+        click.echo(json.dumps({"token": token}))
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

cloudsmith_cli/core/credentials/__init__.py

@@ -51,10 +51,29 @@ def resolve(self, context: CredentialContext) -> CredentialResult | None:
 
 
 class CredentialProviderChain:
-    """Evaluates credential providers in order, returning the first valid result."""
-
-    def __init__(self, providers: list[CredentialProvider]):
-        self.providers = providers
+    """Evaluates credential providers in order, returning the first valid result.
+
+    If no providers are given, uses the default chain:
+    EnvironmentVariable → ConfigFile → Keyring → OIDC.
+    """
+
+    def __init__(self, providers: list[CredentialProvider] | None = None):
+        if providers is not None:
+            self.providers = providers
+        else:
+            from .providers import (
+                ConfigFileProvider,
+                EnvironmentVariableProvider,
+                KeyringProvider,
+                OidcProvider,
+            )
+
+            self.providers = [
+                EnvironmentVariableProvider(),
+                ConfigFileProvider(),
+                KeyringProvider(),
+                OidcProvider(),
+            ]
 
     def resolve(self, context: CredentialContext) -> CredentialResult | None:
         """Evaluate each provider in order. Return the first successful result."""

cloudsmith_cli/credential_helpers/cargo/__init__.py

@@ -0,0 +1,32 @@
+"""
+Cargo credential provider logic for Cloudsmith.
+
+This module provides functions for retrieving credentials for Cargo registries
+using the existing Cloudsmith credential provider chain (OIDC, API keys, config, keyring).
+"""
+
+from ..common import is_cloudsmith_domain, resolve_credentials
+
+
+def get_credentials(index_url, debug=False):
+    """
+    Get a token for a Cloudsmith Cargo registry.
+
+    Resolves credentials first, then verifies the URL is a Cloudsmith registry
+    (including custom domains, authenticated via the resolved token).
+
+    Args:
+        index_url: The registry index URL (e.g., "sparse+https://cargo.cloudsmith.io/org/repo/")
+        debug: Enable debug logging
+
+    Returns:
+        str: API token or None if not available
+    """
+    result = resolve_credentials(debug)
+    if not result:
+        return None
+
+    if not is_cloudsmith_domain(index_url):
+        return None
+
+    return result.api_key