cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/core/credentials/oidc/cache.py

@@ -0,0 +1,220 @@
+"""OIDC token cache.
+
+Caches Cloudsmith API tokens obtained via OIDC exchange to avoid unnecessary
+re-exchanges. Uses system keyring when available (respecting CLOUDSMITH_NO_KEYRING),
+with automatic fallback to filesystem storage when keyring is unavailable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import time
+
+from ...cache_utils import atomic_write_json
+
+logger = logging.getLogger(__name__)
+
+EXPIRY_MARGIN_SECONDS = 60
+
+_CACHE_DIR_NAME = "oidc_token_cache"
+
+
+def _get_cache_dir() -> str:
+    """Return the cache directory path, creating it if needed."""
+    from ....cli.config import get_default_config_path
+
+    base = get_default_config_path()
+    cache_dir = os.path.join(base, _CACHE_DIR_NAME)
+    if not os.path.isdir(cache_dir):
+        os.makedirs(cache_dir, mode=0o700, exist_ok=True)
+    return cache_dir
+
+
+def _cache_key(api_host: str, org: str, service_slug: str) -> str:
+    """Compute a deterministic cache filename from the exchange parameters."""
+    raw = f"{api_host}|{org}|{service_slug}"
+    digest = hashlib.sha256(raw.encode()).hexdigest()[:32]
+    return f"oidc_{digest}.json"
+
+
+def _decode_jwt_exp(token: str) -> float | None:
+    """Read the exp claim from a JWT payload.
+
+    The token is only inspected to determine a cache TTL; it is never used to
+    make an authorization decision, so the signature is deliberately not
+    verified (the API rejects tampered tokens regardless).
+    """
+    try:
+        import jwt
+
+        payload = jwt.decode(token, options={"verify_signature": False})
+        exp = payload.get("exp")
+        if exp is not None:
+            return float(exp)
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to decode JWT expiry", exc_info=True)
+    return None
+
+
+def get_cached_token(api_host: str, org: str, service_slug: str) -> str | None:
+    """Return a cached token if it exists and is not expired."""
+    token = _get_from_keyring(api_host, org, service_slug)
+    if token:
+        return token
+    return _get_from_disk(api_host, org, service_slug)
+
+
+def _get_from_keyring(api_host: str, org: str, service_slug: str) -> str | None:
+    """Try to get token from keyring."""
+    try:
+        from ...keyring import get_oidc_token
+
+        token_data = get_oidc_token(api_host, org, service_slug)
+        if not token_data:
+            return None
+
+        data = json.loads(token_data)
+        token = data.get("token")
+        expires_at = data.get("expires_at")
+
+        if not token:
+            return None
+
+        if expires_at is not None:
+            remaining = expires_at - time.time()
+            if remaining < EXPIRY_MARGIN_SECONDS:
+                logger.debug(
+                    "Keyring OIDC token expired or expiring soon "
+                    "(%.0fs remaining, margin=%ds)",
+                    remaining,
+                    EXPIRY_MARGIN_SECONDS,
+                )
+                from ...keyring import delete_oidc_token
+
+                delete_oidc_token(api_host, org, service_slug)
+                return None
+            logger.debug("Using keyring OIDC token (expires in %.0fs)", remaining)
+        else:
+            logger.debug("Using keyring OIDC token (no expiry information)")
+
+        return token
+
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to read OIDC token from keyring", exc_info=True)
+        return None
+
+
+def _get_from_disk(api_host: str, org: str, service_slug: str) -> str | None:
+    """Try to get token from disk cache."""
+    cache_dir = _get_cache_dir()
+    cache_file = os.path.join(cache_dir, _cache_key(api_host, org, service_slug))
+
+    if not os.path.isfile(cache_file):
+        return None
+
+    try:
+        with open(cache_file) as f:
+            data = json.load(f)
+
+        token = data.get("token")
+        expires_at = data.get("expires_at")
+
+        if not token:
+            return None
+
+        if expires_at is not None:
+            remaining = expires_at - time.time()
+            if remaining < EXPIRY_MARGIN_SECONDS:
+                logger.debug(
+                    "Disk cached OIDC token expired or expiring soon "
+                    "(%.0fs remaining, margin=%ds)",
+                    remaining,
+                    EXPIRY_MARGIN_SECONDS,
+                )
+                _remove_cache_file(cache_file)
+                return None
+            logger.debug("Using disk cached OIDC token (expires in %.0fs)", remaining)
+        else:
+            logger.debug("Using disk cached OIDC token (no expiry information)")
+
+        return token
+
+    except (json.JSONDecodeError, OSError, KeyError):
+        logger.debug("Failed to read OIDC token from disk cache", exc_info=True)
+        _remove_cache_file(cache_file)
+        return None
+
+
+def store_cached_token(api_host: str, org: str, service_slug: str, token: str) -> None:
+    """Cache a token in keyring (if available) or filesystem."""
+    expires_at = _decode_jwt_exp(token)
+
+    data = {
+        "token": token,
+        "expires_at": expires_at,
+        "api_host": api_host,
+        "org": org,
+        "service_slug": service_slug,
+        "cached_at": time.time(),
+    }
+
+    if _store_in_keyring(api_host, org, service_slug, data):
+        return
+
+    _store_on_disk(api_host, org, service_slug, data)
+
+
+def _store_in_keyring(api_host: str, org: str, service_slug: str, data: dict) -> bool:
+    """Try to store token in keyring."""
+    try:
+        from ...keyring import store_oidc_token
+
+        token_data = json.dumps(data)
+        success = store_oidc_token(api_host, org, service_slug, token_data)
+        if success:
+            logger.debug(
+                "Stored OIDC token in keyring (expires_at=%s)", data.get("expires_at")
+            )
+        return success
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to store OIDC token in keyring", exc_info=True)
+        return False
+
+
+def _store_on_disk(api_host: str, org: str, service_slug: str, data: dict) -> None:
+    """Store token on disk."""
+    cache_dir = _get_cache_dir()
+    cache_file = os.path.join(cache_dir, _cache_key(api_host, org, service_slug))
+
+    try:
+        atomic_write_json(cache_file, data)
+        logger.debug(
+            "Stored OIDC token on disk (expires_at=%s)", data.get("expires_at")
+        )
+    except OSError:
+        logger.debug("Failed to write OIDC token to disk cache", exc_info=True)
+
+
+def invalidate_cached_token(api_host: str, org: str, service_slug: str) -> None:
+    """Remove a cached token from both keyring and disk."""
+    try:
+        from ...keyring import delete_oidc_token
+
+        delete_oidc_token(api_host, org, service_slug)
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to delete OIDC token from keyring", exc_info=True)
+
+    cache_dir = _get_cache_dir()
+    cache_file = os.path.join(cache_dir, _cache_key(api_host, org, service_slug))
+    _remove_cache_file(cache_file)
+
+
+def _remove_cache_file(path: str) -> None:
+    """Safely remove a cache file."""
+    try:
+        os.unlink(path)
+    except (OSError, TypeError):
+        pass

cloudsmith_cli/core/credentials/oidc/detectors/__init__.py

@@ -0,0 +1,122 @@
+"""Environment detectors for OIDC token retrieval."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .aws import AWSDetector
+from .azure_devops import AzureDevOpsDetector
+from .base import EnvironmentDetector
+from .bitbucket_pipelines import BitbucketPipelinesDetector
+from .circleci import CircleCIDetector
+from .generic import GenericDetector
+from .github_actions import GitHubActionsDetector
+from .gitlab_ci import GitLabCIDetector
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from ... import CredentialContext
+
+logger = logging.getLogger(__name__)
+
+_DETECTORS: list[type[EnvironmentDetector]] = [
+    CircleCIDetector,
+    AzureDevOpsDetector,
+    GitHubActionsDetector,
+    BitbucketPipelinesDetector,
+    GitLabCIDetector,
+    AWSDetector,
+    GenericDetector,
+]
+
+
+def registered_detectors() -> list[type[EnvironmentDetector]]:
+    """Return the registered OIDC detectors in their default priority order."""
+    return list(_DETECTORS)
+
+
+def disable_env_var(identifier: str) -> str:
+    """The environment variable that disables the detector with this id."""
+    return f"CLOUDSMITH_OIDC_{identifier.upper()}_DISABLED"
+
+
+def _is_disabled_value(value: str | None) -> bool:
+    """Only the literal string ``true`` (case-insensitive) disables a detector."""
+    return (value or "").strip().lower() == "true"
+
+
+def disabled_detectors_from_env(environ: Mapping[str, str]) -> frozenset[str]:
+    """Detector ids disabled via their CLOUDSMITH_OIDC_<ID>_DISABLED variable."""
+    return frozenset(
+        detector_cls.id
+        for detector_cls in _DETECTORS
+        if _is_disabled_value(environ.get(disable_env_var(detector_cls.id)))
+    )
+
+
+def _ordered_detectors(order: str | None) -> list[type[EnvironmentDetector]]:
+    """Detectors in evaluation order, honouring an explicit order string.
+
+    When ``order`` is unset/empty the default registration order is used.
+    Otherwise only the listed ids are considered, in the listed order;
+    unknown ids are logged and skipped, and duplicate ids keep their first
+    position so each detector is evaluated at most once.
+    """
+    raw_order = (order or "").strip()
+    if not raw_order:
+        return list(_DETECTORS)
+
+    detectors_by_id = {detector_cls.id: detector_cls for detector_cls in _DETECTORS}
+    ordered: dict[str, type[EnvironmentDetector]] = {}
+    for token in raw_order.split(","):
+        identifier = token.strip().lower()
+        if not identifier or identifier in ordered:
+            continue
+        detector_cls = detectors_by_id.get(identifier)
+        if detector_cls is None:
+            logger.debug("Ignoring unknown OIDC detector id: %s", identifier)
+            continue
+        ordered[identifier] = detector_cls
+    return list(ordered.values())
+
+
+def _enabled_detectors(
+    order: str | None, disabled: frozenset[str]
+) -> list[type[EnvironmentDetector]]:
+    """Ordered detectors with disabled ones removed (disable always wins)."""
+    return [
+        detector_cls
+        for detector_cls in _ordered_detectors(order)
+        if detector_cls.id not in disabled
+    ]
+
+
+def detect_environment(
+    context: CredentialContext,
+) -> EnvironmentDetector | None:
+    """Try each detector in order, returning the first that matches."""
+    enabled = _enabled_detectors(
+        context.oidc_detector_order, context.oidc_disabled_detectors
+    )
+    if not enabled:
+        logger.debug("No OIDC detectors enabled after applying order/disable controls")
+    for detector_cls in enabled:
+        detector = detector_cls(context=context)
+        try:
+            if detector.detect():
+                if context.debug:
+                    logger.debug("Detected OIDC environment: %s", detector.name)
+                return detector
+        except Exception:  # pylint: disable=broad-exception-caught
+            logger.debug(
+                "Detector %s raised an exception during detection",
+                detector.name,
+                exc_info=True,
+            )
+            continue
+
+    if context.debug:
+        logger.debug("No supported OIDC environment detected")
+    return None

cloudsmith_cli/core/credentials/oidc/detectors/aws.py

@@ -0,0 +1,85 @@
+"""AWS OIDC detector.
+
+Uses boto3 to auto-discover AWS credentials and calls STS GetWebIdentityToken
+to obtain a signed JWT for Cloudsmith.
+
+Requires boto3 (optional dependency): pip install cloudsmith-cli[aws]
+
+References:
+    https://cloudsmith.com/blog/authenticate-to-cloudsmith-with-your-aws-identity
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .base import EnvironmentDetector
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_AUDIENCE = "cloudsmith"
+
+
+class AWSDetector(EnvironmentDetector):
+    """Detects AWS environments and obtains a JWT via STS GetWebIdentityToken."""
+
+    name = "AWS"
+    id = "aws"
+
+    def __init__(self, context):
+        super().__init__(context)
+        self._session = None
+
+    def detect(self) -> bool:
+        try:
+            import boto3
+            from botocore.exceptions import (
+                BotoCoreError,
+                ClientError,
+                MissingDependencyException,
+                NoCredentialsError,
+            )
+        except ImportError:
+            logger.debug("AWSDetector: boto3 not installed, skipping")
+            return False
+
+        try:
+            self._session = boto3.Session()
+            credentials = self._session.get_credentials()
+            if credentials is None:
+                return False
+            # Resolve to verify credentials are usable
+            credentials = credentials.get_frozen_credentials()
+            return bool(credentials.access_key)
+        except MissingDependencyException as e:
+            logger.debug(
+                "AWSDetector: Missing boto3 dependency for SSO credentials: %s. "
+                "Install with: pip install 'botocore[crt]' or 'boto3[crt]'",
+                e,
+            )
+            return False
+        except (BotoCoreError, NoCredentialsError, ClientError):
+            return False
+        except Exception:  # pylint: disable=broad-exception-caught
+            logger.debug(
+                "AWSDetector: unexpected error during detection", exc_info=True
+            )
+            return False
+
+    def get_token(self) -> str:
+        import boto3  # pylint: disable=import-error
+
+        audience = self.context.oidc_audience or DEFAULT_AUDIENCE
+        session = self._session or boto3.Session()
+        sts = session.client("sts")
+        response = sts.get_web_identity_token(
+            Audience=[audience],
+            SigningAlgorithm="RS256",
+        )
+
+        token = response.get("WebIdentityToken")
+        if not token:
+            raise ValueError(
+                "AWS STS GetWebIdentityToken did not return a WebIdentityToken"
+            )
+        return token

cloudsmith_cli/core/credentials/oidc/detectors/azure_devops.py

@@ -0,0 +1,70 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Azure DevOps OIDC detector.
+
+Fetches an OIDC token via the ``SYSTEM_OIDCREQUESTURI`` HTTP endpoint using
+the pipeline's ``SYSTEM_ACCESSTOKEN`` for authorization.
+
+The audience is not caller-configurable: Azure DevOps always mints the token
+with a fixed audience (``api://AzureADTokenExchange``) and ignores any audience
+supplied in the request, so the request is an empty POST (matching the Azure
+SDK's AzurePipelinesCredential).
+
+References:
+    https://learn.microsoft.com/en-us/azure/devops/release-notes/2024/sprint-240-update#pipelines-and-tasks-populate-variables-to-customize-workload-identity-federation-authentication
+    https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/azure_pipelines_credential.go
+    https://docs.cloudsmith.com/integrations/integrating-with-azure-devops
+    https://cloudsmith.com/changelog/native-oidc-authentication-for-azure-devops
+"""
+
+from __future__ import annotations
+
+import os
+
+from ....rest import create_requests_session as create_session
+from .base import EnvironmentDetector
+
+API_VERSION = "7.1"
+
+
+class AzureDevOpsDetector(EnvironmentDetector):
+    """Detects Azure DevOps and fetches an OIDC token via HTTP POST."""
+
+    name = "Azure DevOps"
+    id = "azure_devops"
+
+    def detect(self) -> bool:
+        return bool(os.environ.get("SYSTEM_OIDCREQUESTURI")) and bool(
+            os.environ.get("SYSTEM_ACCESSTOKEN")
+        )
+
+    def get_token(self) -> str:
+        request_uri = os.environ["SYSTEM_OIDCREQUESTURI"]
+        access_token = os.environ["SYSTEM_ACCESSTOKEN"]
+
+        # The Azure DevOps OIDC endpoint rejects requests without an explicit
+        # api-version (HTTP 400), so it must always be supplied.
+        separator = "&" if "?" in request_uri else "?"
+        url = f"{request_uri}{separator}api-version={API_VERSION}"
+
+        session = self.context.session or create_session()
+        try:
+            response = session.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {access_token}",
+                    "X-TFS-FedAuthRedirect": "Suppress",
+                },
+                timeout=30,
+            )
+            response.raise_for_status()
+
+            data = response.json()
+            token = data.get("oidcToken")
+            if not token:
+                raise ValueError(
+                    "Azure DevOps OIDC response did not contain an oidcToken"
+                )
+            return token
+        finally:
+            if not self.context.session:
+                session.close()

cloudsmith_cli/core/credentials/oidc/detectors/base.py

@@ -0,0 +1,26 @@
+"""Base class and utilities for OIDC environment detectors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ... import CredentialContext
+
+
+class EnvironmentDetector:
+    """Base class for OIDC environment detectors."""
+
+    name: str = "base"
+    id: str = "base"
+
+    def __init__(self, context: CredentialContext):
+        self.context = context
+
+    def detect(self) -> bool:
+        """Return True if running in a supported OIDC environment."""
+        raise NotImplementedError
+
+    def get_token(self) -> str:
+        """Retrieve the OIDC JWT from this environment. Raises on failure."""
+        raise NotImplementedError

cloudsmith_cli/core/credentials/oidc/detectors/bitbucket_pipelines.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Bitbucket Pipelines OIDC detector.
+
+Reads an OIDC token from the ``BITBUCKET_STEP_OIDC_TOKEN`` environment variable,
+which Bitbucket populates when ``oidc: true`` is set on a pipeline step.
+
+References:
+    https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/
+    https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import EnvironmentDetector
+
+
+class BitbucketPipelinesDetector(EnvironmentDetector):
+    """Detects Bitbucket Pipelines and reads its OIDC token from environment."""
+
+    name = "Bitbucket Pipelines"
+    id = "bitbucket"
+
+    def detect(self) -> bool:
+        return bool(os.environ.get("BITBUCKET_STEP_OIDC_TOKEN"))
+
+    def get_token(self) -> str:
+        token = os.environ.get("BITBUCKET_STEP_OIDC_TOKEN")
+        if not token:
+            raise ValueError(
+                "BITBUCKET_STEP_OIDC_TOKEN is not set. Enable OIDC on the "
+                "pipeline step with 'oidc: true'."
+            )
+        return token

cloudsmith_cli/core/credentials/oidc/detectors/circleci.py

@@ -0,0 +1,40 @@
+# Copyright 2026 Cloudsmith Ltd
+"""CircleCI OIDC detector.
+
+Reads OIDC token from the ``CIRCLE_OIDC_TOKEN_V2`` or ``CIRCLE_OIDC_TOKEN``
+environment variables set by CircleCI's OIDC support.
+
+References:
+    https://circleci.com/docs/guides/permissions-authentication/openid-connect-tokens/
+    https://docs.cloudsmith.com/integrations/integrating-with-circleci
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import EnvironmentDetector
+
+
+class CircleCIDetector(EnvironmentDetector):
+    """Detects CircleCI and reads OIDC token from environment variable."""
+
+    name = "CircleCI"
+    id = "circleci"
+
+    def detect(self) -> bool:
+        return os.environ.get("CIRCLECI") == "true" and bool(
+            os.environ.get("CIRCLE_OIDC_TOKEN_V2")
+            or os.environ.get("CIRCLE_OIDC_TOKEN")
+        )
+
+    def get_token(self) -> str:
+        token = os.environ.get("CIRCLE_OIDC_TOKEN_V2") or os.environ.get(
+            "CIRCLE_OIDC_TOKEN"
+        )
+        if not token:
+            raise ValueError(
+                "CircleCI detected but neither CIRCLE_OIDC_TOKEN_V2 nor "
+                "CIRCLE_OIDC_TOKEN is set"
+            )
+        return token

cloudsmith_cli/core/credentials/oidc/detectors/generic.py

@@ -0,0 +1,42 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Generic fallback OIDC detector.
+
+Reads an OIDC token from the ``CLOUDSMITH_OIDC_TOKEN`` environment variable.
+Works for Jenkins (with the credentials binding plugin), or any custom CI/CD
+system that can inject an OIDC token via an environment variable.
+
+References:
+    https://docs.cloudsmith.com/authentication/setup-jenkins-to-authenticate-to-cloudsmith-using-oidc
+    https://plugins.jenkins.io/credentials-binding/
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import EnvironmentDetector
+
+TOKEN_ENV_VAR = "CLOUDSMITH_OIDC_TOKEN"
+
+
+class GenericDetector(EnvironmentDetector):
+    """Generic fallback: reads the OIDC token from CLOUDSMITH_OIDC_TOKEN.
+
+    Works for Jenkins (with the credentials binding plugin), or any custom
+    CI/CD system that can inject an OIDC token via an environment variable.
+    """
+
+    name = "Generic"
+    id = "generic"
+
+    def detect(self) -> bool:
+        return bool((os.environ.get(TOKEN_ENV_VAR) or "").strip())
+
+    def get_token(self) -> str:
+        token = (os.environ.get(TOKEN_ENV_VAR) or "").strip()
+        if not token:
+            raise ValueError(
+                f"Generic OIDC detector selected but {TOKEN_ENV_VAR} is not "
+                "set. Set it to the OIDC JWT to exchange for a Cloudsmith token."
+            )
+        return token