conan-auth-source-plugin 0.0.5__py3-none-any.whl

auth_source/auth_source_plugin.py

@@ -0,0 +1,45 @@
+"""
+    The implementation of the auth source plugin
+"""
+import logging
+from typing import Optional
+
+from auth_source.authenticator import AuthenticatorFactory
+from auth_source.config import make_config
+from auth_source.source_credentials import load_source_credentials, find_first_credentials
+from auth_source.types import AuthSourceDetails
+
+# A conan authentication plugin is not given the conan api or a logger, as it
+# might cause recursion problems. Since the logger is not available, reach out
+# and get the logger named conan.
+logger = logging.getLogger("conan")
+
+
+def plugin(url: str) -> Optional[AuthSourceDetails]:
+    """
+        A Conan authentication for source credentials authenticator.
+
+        If the source URL is configured to support generating a github application token
+        then return a valid token.
+    """
+    logging.debug("Loading 'source_credentials.json'")
+    source_credentials = load_source_credentials()
+    if source_credentials:
+        logging.info("Finding credentials for '%s'", url)
+        credentials = find_first_credentials(url, source_credentials)
+        if credentials:
+            config = make_config(credentials)
+            if config:
+                auth = AuthenticatorFactory.make_authenticator(url, config.type)
+                token = auth.make_token(config)
+                if token:
+                    headers = credentials.get("headers")
+                    return {"token": token, "headers": headers} if headers else {"token": token}
+                logger.warning("Failed to get github application token '%s'", url)
+            else:
+                logger.warning("Failed to make configuration for '%s'", url)
+        else:
+            logger.info("No 'source_credentials.json' configuration for '%s'", url)
+    else:
+        logger.warning("No 'source_credentials.json' found")
+    return None

auth_source/authenticator.py

@@ -0,0 +1,52 @@
+"""
+    Plugable authenticator support
+"""
+import logging
+from typing import Protocol, runtime_checkable, Optional
+
+from github import GithubIntegration
+
+from auth_source.config import Config
+
+logger = logging.getLogger("conan")
+
+
+@runtime_checkable
+class Authenticator(Protocol):
+    """
+        Interface for authenticator making an authentication token
+    """
+
+    def make_token(self, config: Config) -> Optional[str]:
+        """
+            Make a token given a configuration.
+
+            The token is a short-lived (1 hour) cryptographic string starting with 'ghs_'.
+        """
+        ...
+
+
+class GithubApplicationAuthenticator(Authenticator):
+
+    def make_token(self, config: Config) -> str:
+        """
+            Create an authentication token for the given github application id.
+        """
+        logger.info("GitHub App %d auth for Installation ID: %d", config.id, config.installation_id)
+
+        integration = GithubIntegration(config.id, config.private_key)
+        auth_connection = integration.get_access_token(config.installation_id)
+        return auth_connection.token
+
+
+class AuthenticatorFactory:
+    """
+        A factory for making authentication instances. Only one so far...
+    """
+
+    @staticmethod
+    def make_authenticator(_url: str, _auth_type: Optional[str]) -> Authenticator:
+        """
+            For now, only a github application authenticator is supported.
+        """
+        return GithubApplicationAuthenticator()

auth_source/config.py

@@ -0,0 +1,81 @@
+"""
+    Config POCO
+"""
+import os
+from dataclasses import dataclass
+from typing import Optional, Any
+
+from auth_source.types import CredentialBlock
+
+
+@dataclass(frozen=True)
+class Config:
+    """
+        A top level state to hold command line arguments and program state.
+    """
+    type: Optional[str]
+    """ 
+        What type of authentication should be performed to get the token.
+        
+        This is expected to be set if multiple authentication implementations are support. At
+        this stage this is a github application only provider, so the value is ignored (for now).
+        What we can see is that bitbucket self hosted doesn't support this style of auth (and a static 
+        token is as good as it gets).  
+    """
+
+    id: str | int
+    """ 
+        The application id used for authentication.
+        
+        Identifies your application globally to sign JSON Web Tokens (JWTs). This id is
+        generated by github when the application is created.
+        
+        Note: This **not** the app name, the client id, or the app slug.
+     
+     """
+
+    private_key: str
+    """
+        A string containing the installation access 
+    """
+
+    installation_id: int
+    """
+        The installation id used for authentication.
+        
+        Identifies a specific account (user/org) that installed your app. This is an integer that 
+        is createdby github when a user installs the application.
+    """
+
+
+def make_config(credential_block: Optional[CredentialBlock]) -> Optional[Config]:
+    """
+        Create an authentication configuration for the given github application if possible.
+    """
+
+    # If the credential block has a credential, then don't attempt to authenticate.  It is assumed
+    # that a statically define token or user/password means we don't need to get an authentication token.
+    # Note: the main Conan logic requires a token or a user/password or headers. This might create
+    # an issue in the future and highlights how this plugin is using the `source_credentials.json`
+    # in an adhoc unapproved way.
+    if not credential_block.get("token") and not credential_block.get("user"):
+
+        app_id = _get_value_with_fallbacks(credential_block, "app_id", "CONAN_GITHUB_APP_ID")
+        private_key = _get_value_with_fallbacks(credential_block, "app_private_key", "CONAN_GITHUB_APP_PRIVATE_KEY")
+        installation_id = _get_value_with_fallbacks(credential_block, "app_installation_id",
+                                                    "CONAN_GITHUB_APP_INSTALLATION_ID")
+        if all([app_id, private_key, installation_id]):
+            return Config(
+                type=credential_block.get("type"),
+                id=app_id,
+                private_key=private_key,
+                installation_id=installation_id)
+    return None
+
+
+def _get_value_with_fallbacks(data: Optional[CredentialBlock], data_name: str, primary_env: str) -> Optional[Any]:
+    """
+        Checks a dictionary key, then a primary environment variable,
+        then a backup environment variable, defaulting to None.
+    """
+    return data.get(data_name) or os.getenv(primary_env) or None

auth_source/installer.py

@@ -0,0 +1,55 @@
+"""
+    A script to install the cci-build command into Conan.
+"""
+import logging
+import os
+import shutil
+from importlib.resources import files, as_file
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+def get_conan_home() -> Path:
+    """
+        Resolve Conan 2 home directory.
+
+        This is the root directory where Conan stores:
+            - cache
+            - extensions
+            - configuration
+            - remotes
+
+        Resolution order:
+            1. CONAN_HOME environment variable (if set)
+            2. Default platform-specific location (~/.conan2)
+
+        Returns:
+            Path to Conan home directory.
+    """
+
+    # 1. Explicit override (highest priority)
+    env_home = os.environ.get("CONAN_HOME")
+    if env_home:
+        return Path(env_home).expanduser().resolve()
+
+    # 2. Default Conan 2 home directory
+    # Conan 2 standard default is ~/.conan2 unless overridden
+    return Path.home() / ".conan2"
+
+
+def main():
+    """
+       Entry point for the conan auth source installer. This entry point is
+       installed by the setup.py script when the module is installed.
+    """
+    conan_home = get_conan_home()
+    target_dir = conan_home / "extensions" / "plugins"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    destination = target_dir / "auth_source.py"
+
+    resource = files("extensions.plugins").joinpath("auth_source.py")
+    with as_file(resource) as src:
+        shutil.copyfile(src, destination)
+
+    log.info("Installed Conan auth source plugin to '%s'", destination)

auth_source/source_credentials.py

@@ -0,0 +1,42 @@
+import json
+import os
+import platform
+from typing import Optional
+
+from conan.errors import ConanException
+from conan.internal.paths import get_conan_user_home
+from conan.internal.util.files import load
+from jinja2 import Template
+
+from auth_source.types import SourceCredentials, CredentialBlock
+
+
+def load_source_credentials() -> Optional[SourceCredentials]:
+    """
+        Reach out into Conan and load the source credentials file. This is not provided as a
+        plugin API parameter, so this needs to be loaded again. The `source_credentials.json`
+        file is a jinja2 template that must render as JSON.
+    """
+    home_folder = get_conan_user_home()
+    creds_path = os.path.join(home_folder, "source_credentials.json")
+    if os.path.exists(creds_path):
+        try:
+            template = Template(load(creds_path))
+            content = template.render({"platform": platform, "os": os})
+            return json.loads(content)
+        except Exception as e:
+            raise ConanException(f"Error loading 'source_credentials.json' {creds_path}: {repr(e)}")
+    return None
+
+
+def find_first_credentials(url: str, source_credentials: Optional[SourceCredentials]) -> Optional[CredentialBlock]:
+    """
+        Find the first credential block that has a 'url' that is at the start of the source url.
+    """
+    credentials_list = source_credentials.get("credentials", [])
+    for block in credentials_list:
+        # Extract the configuration URL pattern from the current block
+        config_url = block.get("url")
+        if config_url and url.startswith(config_url):
+            return block
+    return None  # not found

auth_source/types.py

@@ -0,0 +1,38 @@
+"""
+    Python typing definitions.
+"""
+from typing import Dict, Optional, TypedDict, List
+
+CredentialBlock = TypedDict(
+    "CredentialBlock",
+    {
+        "url": str,
+        "username": Optional[str],
+        "password": Optional[str],
+        "token": Optional[str],
+        "headers": Optional[Dict[str, str]],
+        "type": str,
+
+        "app_id": str,
+        "app_installation_id": Optional[str],
+        "app_private_key": Optional[str],
+    },
+)
+
+# 2. Define the outer file layout without using a class
+SourceCredentials = TypedDict(
+    "SourceCredentials",
+    {
+        "credentials": List[CredentialBlock]
+    }
+)
+
+AuthSourceDetails = TypedDict(
+    "AuthSourceDetails",
+    {
+        "token": Optional[str],
+        "username": Optional[str],
+        "password": Optional[str],
+        "headers": Optional[Dict[str, str]],
+    }
+)

auth_source_extensions/plugins/auth_source.py

@@ -0,0 +1,28 @@
+"""
+    A Conan plugin module.
+"""
+
+
+def auth_source_plugin(url: str, **kwargs):
+    """
+        This is a conan plugin, that conforms to the plugin definition in Conan.
+
+        This implementation thunks the call through to the plugin entry point
+        in the Conan auth source authentication plugin module.
+
+        In the current implementation, defined here:
+          - https://github.com/conan-io/conan/blob/develop2/conan/internal/rest/conan_requester.py#L66
+
+        At the time of writing, Conan invokes this plugin with the request URL and
+        no additional keyword arguments. Perhaps in the future Conan could pass:
+           - a logger instance
+           - the best matching section of the `source_credentials.json` file, or the whole contents
+           - the `www-authenticate` headers upon a 401 request failing
+    """
+
+    # Import the python module at this point, so that module loading issues
+    # are reported during authentication.
+    #
+    # pylint: disable=import-outside-toplevel
+    from auth_source.auth_source_plugin import plugin
+    return plugin(url, **kwargs)

conan_auth_source_plugin-0.0.5.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: conan-auth-source-plugin
+Version: 0.0.5
+Summary: A python module to provide GitHub application authorisation for source downloads
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: conan<3.0,>=2.25
+Requires-Dist: packaging>=26.2
+Requires-Dist: PyGithub>=2.9.1
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# [conan-auth-source-plugin](https://github.com/conan-py/conan-auth-source-plugin)
+
+A Conan authentication source plugin, implemented as a python module. Conan supports both a *remote*
+and a *source* authentication, where the remotes are used for interacting with a remote for
+packages, whereas the *source* is used for getting source using the `get()` or `download()`
+method in a `conanfile.py`.
+
+# Installation
+
+Install the conan authentication source Python module, then install the plugin in that module
+into the conan installation.
+
+```shell
+python -m pip install conan-auth-source-plugin
+conan-auth-source-plugin-install
+```
+
+# Configuration
+
+This plugin uses the
+[`source_creditials.json`](https://docs.conan.io/2/reference/config_files/source_credentials.html)
+file for configuration. This file is marked as experimental at this stage. This module further
+experiments and extends its usage.
+
+**Note**: The conan source configuration code uses a first match (begins with) strategy with URLs.
+Thus, it is important to order the credentials in longest url first if there is any overlap in
+matching the URL being fetched with the configuration.
+
+## Sample
+
+```json
+{
+  "credentials": [
+    {
+      "url": "https://github.com/...",
+      "type": "github.app",
+      "app_id": "4459267",
+      "app_installation_id": "150620648",
+      "app_private_key" : "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
+    }
+  ]
+}
+```
+
+# Create App
+
+The following procedure can be used to create an application in github. This procedure requires an
+organisation owner, or a team member with app management permissions.
+
+This procedure is documented as a GitHub app that act on their 
+[own behalf](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#github-apps-that-act-on-their-own-behalf).
+This requires an installation access token for authentication.
+
+1. Go to the organisation (or user) settings
+   
+   https://github.com/organizations/conan-py/settings/apps
+   https://github.com/<org name>/conan-py/settings/apps
+
+2. App settings
+   
+  - provide a github app name
+  - write a description
+  - add a homepage URL (e.g. to the organisation landing page), even though it isn't explicitly used
+  - disable web hook
+  - add repository permission 'Contents', set to 'Read-Only' 
+
+3. Once the app is created, the 'App ID' and the 'Client ID' (not used for this workflow) are known
+
+4. Go to the bottom of the application and generate a private key. This will
+   generate a 2048bit RSA key pair without a pass phrase. 
+
+5. On the side bar of the application, select the "Install App" menu item. Once installed
+   the installation id can be taken from the installation URL. For example if the installation
+   URL is 'https://github.com/organizations/conan-py/settings/installations/150620648', then the
+   installation id is 150620648. The installation id is not displayed in the web UI of github.
+
+# Why use this plugin module
+
+This module is a shift-left style strategy for authentication. Instead of using this pluing
+a build pipeline (or any Conan build) can pre-authenticate with all github organisation/repositores
+that *may* be needed during a build.
+
+This module goes half-way towards "authentication on demand". This is a concept where http
+authentication is only attempted by a client if a 
+[401 (Not authenticated)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/401)
+response is received, and the
+[`WWW-Authenticate` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate)
+provides
+[authentication schemes](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml)
+that are semantically understood by the client. Once authenticated the client should reissue the
+http request with the new credentials.
+
+*Residual*: This plugin does not defer authentication until after it is needed. This is not
+supported by the Conan client.
+
+# Known issues
+
+- this implementation stores private keys by value in memory. e.g. if using AWS it
+  would be better to use a HSM or AWS KMS, but this would require an implementation
+  of the `github.Auth.Auth` class. Using AWS Secrets Manager at least stores the
+  key more securely at rest, even though it will be stored in memory non-securely.
+
+- when using the `get()` method in a `conanfile.py`, provide a filename parameter
+  with a representative name (e.g. 'archive.tgz') so that conan can write the download
+  to disk.  The filename should be expressed in the `conandat.yml`.
+
+# Development
+
+To install the plugin in a local Conan environment, the whole of the plugin repository
+can be installed, as the `.conanignore` will exclude everything except the plugin
+python file that thunks to the module.
+
+```shell
+conan config install .
+```
+
+Install the plugin Python for development as an editable module. From the root of the
+repository/project:
+
+```shell
+pip install --editable .
+```
+
+# Links
+
+ - https://pypi.org/project/conan-auth-source-plugin 
+ - https://github.com/conan-io/conan-extensions/tree/main
+ - https://docs.conan.io/2/reference/extensions/authorization_plugins.html
+ - https://docs.conan.io/2/reference/config_files/source_credentials.html
+ - https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
+ - https://docs.github.com/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps
+
+## pygithub
+
+ - https://github.com/PyGithub/PyGithub/tree/main
+ - https://pygithub.readthedocs.io/en/stable/introduction.html
+
+# Appendices
+
+## github tarball URLs
+
+For getting source from a private github repo, use a URL/http request of the form: 
+
+```
+GET https://api.github.com/repos/{owner}/{repo}/tarball/{ref}
+Authorization: Bearer <installation_token>
+```

conan_auth_source_plugin-0.0.5.dist-info/RECORD

@@ -0,0 +1,14 @@
+auth_source/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auth_source/auth_source_plugin.py,sha256=PcoW-23hVg0WB5u-T2TmmdOrYdF_zkgtmsavsKcpg_o,1861
+auth_source/authenticator.py,sha256=o9OElnlNOsGfUwjs42QKV3qd-aPf_ayH0wCk9M2jlIA,1467
+auth_source/config.py,sha256=gWwM3iw29A2C5nHNtHtxVJh7Kp6hCfk4Um_c80EJMoc,3137
+auth_source/installer.py,sha256=LrxtkpMI-ubmlaPZKazhbuh8bDlDxRhHOduDwvi_cys,1539
+auth_source/source_credentials.py,sha256=YduTSilKECR6I33eF6OIpUVNVNqmfmolW7PikhKhqkc,1639
+auth_source/types.py,sha256=e7GuJF5X0XKHFzfS0ADoq95x6ncQ5oGeBHdW2OOIOuA,848
+auth_source_extensions/plugins/auth_source.py,sha256=9xok3PYVQVub1bA-slPksvd5U7lQseLolHPt4tqlePc,1102
+conan_auth_source_plugin-0.0.5.dist-info/licenses/LICENSE,sha256=P9a82Ofi3oMxuvQ85tZT84Un2FYz9yHndiwP2XIBzqQ,1117
+conan_auth_source_plugin-0.0.5.dist-info/METADATA,sha256=9vFHhBlrY6fHzJhi3ySrI3z7PT9szViMJuYBD-gbZf8,6316
+conan_auth_source_plugin-0.0.5.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+conan_auth_source_plugin-0.0.5.dist-info/entry_points.txt,sha256=rzPCZZ5__pTwem1OZmaJ6Ufk0BoKZa3igq36rc0NkrA,80
+conan_auth_source_plugin-0.0.5.dist-info/top_level.txt,sha256=uYNHnySICBwxjdmitoWBFvHVSfesW-1YGhZWxPB7SkM,35
+conan_auth_source_plugin-0.0.5.dist-info/RECORD,,

conan_auth_source_plugin-0.0.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

conan_auth_source_plugin-0.0.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+conan-auth-source-plugin-install = auth_source.installer:main

conan_auth_source_plugin-0.0.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utilties, plugins and extesions for Conan package management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

conan_auth_source_plugin-0.0.5.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+auth_source
+auth_source_extensions