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/__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,50 @@
+"""
+Credential helper commands for Cloudsmith.
+
+This module provides credential helper commands for various package managers
+(Docker, pip, npm, etc.) that follow their respective credential helper protocols.
+"""
+
+import click
+
+from ..main import main
+from .cargo import cargo as cargo_cmd
+from .conda import conda as conda_cmd
+from .docker import docker as docker_cmd
+from .npm import npm as npm_cmd
+from .nuget import nuget as nuget_cmd
+from .terraform import terraform as terraform_cmd
+
+
+@click.group()
+def credential_helper():
+    """
+    Credential helpers for package managers.
+
+    These commands provide credentials for package managers like Docker, pip,
+    npm, Terraform, Cargo, Conda, and NuGet. 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
+
+        # Test Terraform credential helper
+        $ cloudsmith credential-helper terraform terraform.cloudsmith.io
+
+        # Test npm/pnpm token helper
+        $ cloudsmith credential-helper npm
+    """
+
+
+# Register subcommands
+credential_helper.add_command(cargo_cmd, name="cargo")
+credential_helper.add_command(conda_cmd, name="conda")
+credential_helper.add_command(docker_cmd, name="docker")
+credential_helper.add_command(npm_cmd, name="npm")
+credential_helper.add_command(nuget_cmd, name="nuget")
+credential_helper.add_command(terraform_cmd, name="terraform")
+
+# Register with main CLI
+main.add_command(credential_helper, name="credential-helper")

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/docker.py

@@ -0,0 +1,75 @@
+"""
+Docker credential helper command.
+
+Implements the Docker credential helper protocol for Cloudsmith registries.
+"""
+
+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 OIDC)
+        CLOUDSMITH_SERVICE_SLUG: Service account slug (required for OIDC)
+    """
+    try:
+        # Read server URL from stdin
+        server_url = sys.stdin.read().strip()
+
+        if not server_url:
+            click.echo("Error: No server URL provided on stdin", err=True)
+            sys.exit(1)
+
+        # Get credentials using the credential provider chain
+        credentials = get_credentials(server_url, debug=False)
+
+        if not credentials:
+            click.echo(
+                "Error: Unable to retrieve credentials. "
+                "Make sure you have either CLOUDSMITH_API_KEY set, "
+                "or CLOUDSMITH_ORG + CLOUDSMITH_SERVICE_SLUG for OIDC authentication.",
+                err=True,
+            )
+            sys.exit(1)
+
+        # Output credentials in Docker credential helper JSON format
+        click.echo(json.dumps(credentials))
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        # Broad exception catch to ensure we never crash without a message
+        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)