imbi-plugin-github 0.1.0__py3-none-any.whl

imbi_plugin_github/identity.py

@@ -0,0 +1,436 @@
+"""GitHub identity plugins.
+
+Three concrete subclasses share one base and differ only by host:
+
+* :class:`GitHubPlugin` — github.com.
+* :class:`GitHubEnterpriseCloudPlugin` — GHEC tenant on ``*.ghe.com``.
+* :class:`GitHubEnterpriseServerPlugin` — operator-managed GHES; the
+  hostname comes from a manifest option.
+
+Phase 1 implements the OAuth App flow only.  GitHub App installation
+tokens (org-scoped automation) are deferred — service principals
+continue to use the legacy ``ServiceApplication`` model.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import secrets
+import typing
+import urllib.parse
+
+import httpx
+from imbi_common.plugins.base import (
+    AuthorizationRequest,
+    CredentialField,
+    IdentityCredentials,
+    IdentityPlugin,
+    IdentityProfile,
+    PluginContext,
+    PluginManifest,
+    PluginOption,
+)
+
+from imbi_plugin_github._hosts import normalize_host, require_ghec_tenant_host
+
+LOGGER = logging.getLogger(__name__)
+
+# Default scope set for the GitHub identity flow. Each scope maps to
+# at least one endpoint the plugin family actually calls:
+#   * ``read:user``   — ``GET /user`` (sign-in / profile)
+#   * ``user:email``  — ``GET /user/emails`` (verified email fallback)
+#   * ``repo``        — ``GET /repos/{owner}/{repo}/...`` (branches,
+#                       tags, commits, compare, check-runs, action
+#                       runs) plus ``POST /git/refs`` and
+#                       ``POST /releases`` for the Promote tab. There
+#                       is no read-only equivalent in OAuth classic
+#                       once private repos are in play.
+#   * ``workflow``    — ``POST /actions/workflows/{file}/dispatches``
+#                       (Deploy tab).
+# ``read:org`` was deliberately dropped — no org/team endpoints are
+# called today. Operators that need a narrower bind can override this
+# on the identity assignment via the ``default_scopes`` plugin option.
+DEFAULT_SCOPES = [
+    'read:user',
+    'user:email',
+    'repo',
+    'workflow',
+]
+
+
+def _build_userinfo(claims: dict[str, typing.Any]) -> IdentityProfile:
+    """Map a GitHub ``/user`` payload onto :class:`IdentityProfile`.
+
+    GitHub does not assert ``email_verified``; the email returned from
+    the API is the user's primary verified email when one is present.
+    The login flow enforces verification by additionally fetching
+    ``/user/emails`` and only accepting the row marked
+    ``primary=true, verified=true``.
+    """
+    return IdentityProfile(
+        subject=str(claims.get('id', '')),
+        email=claims.get('email'),
+        email_verified=True if claims.get('email') else False,
+        name=claims.get('name') or claims.get('login'),
+        avatar_url=claims.get('avatar_url'),
+        groups=[],
+        raw_claims=claims,
+    )
+
+
+class _GitHubBase(IdentityPlugin):
+    """Shared base for GitHub identity plugins.
+
+    Subclasses set :attr:`manifest` and :meth:`_resolve_host`.
+    """
+
+    @classmethod
+    def _resolve_host(cls, options: dict[str, typing.Any]) -> str:
+        """Return the hostname this plugin instance targets."""
+        raise NotImplementedError
+
+    def _endpoints(self, options: dict[str, typing.Any]) -> dict[str, str]:
+        host = self._resolve_host(options)
+        # github.com routes login through github.com/login but API
+        # requests through api.github.com.  GHEC with Data Residency
+        # tenants (``*.ghe.com``) are isolated: OAuth authorize/token
+        # live on the tenant host and REST traffic on
+        # ``api.<tenant>.ghe.com``.  GHES appliances host OAuth at
+        # ``<host>/login/oauth/...`` and REST at ``<host>/api/v3/...``.
+        if host == 'github.com':
+            return {
+                'authorize': 'https://github.com/login/oauth/authorize',
+                'token': 'https://github.com/login/oauth/access_token',
+                'user': 'https://api.github.com/user',
+                'emails': 'https://api.github.com/user/emails',
+            }
+        if host.endswith('.ghe.com'):
+            api_host = f'api.{host}'
+            return {
+                'authorize': f'https://{host}/login/oauth/authorize',
+                'token': f'https://{host}/login/oauth/access_token',
+                'user': f'https://{api_host}/user',
+                'emails': f'https://{api_host}/user/emails',
+            }
+        return {
+            'authorize': f'https://{host}/login/oauth/authorize',
+            'token': f'https://{host}/login/oauth/access_token',
+            'user': f'https://{host}/api/v3/user',
+            'emails': f'https://{host}/api/v3/user/emails',
+        }
+
+    @staticmethod
+    def _scopes(
+        options: dict[str, typing.Any],
+        scopes: list[str] | None,
+    ) -> list[str]:
+        if scopes:
+            return scopes
+        raw = options.get('default_scopes')
+        if isinstance(raw, str) and raw.strip():
+            return raw.split()
+        if isinstance(raw, list):
+            items: list[typing.Any] = raw  # pyright: ignore[reportUnknownVariableType]
+            return [str(s) for s in items]
+        return list(DEFAULT_SCOPES)
+
+    async def authorization_request(
+        self,
+        ctx: PluginContext,
+        credentials: dict[str, str],
+        redirect_uri: str,
+        scopes: list[str] | None = None,
+    ) -> AuthorizationRequest:
+        endpoints = self._endpoints(ctx.assignment_options)
+        scope_list = self._scopes(ctx.assignment_options, scopes)
+        params: dict[str, str] = {
+            'client_id': credentials['client_id'],
+            'redirect_uri': redirect_uri,
+            'scope': ' '.join(scope_list),
+            'state': secrets.token_urlsafe(16),
+        }
+        url = endpoints['authorize'] + '?' + urllib.parse.urlencode(params)
+        return AuthorizationRequest(
+            authorization_url=url,
+            state=params['state'],
+        )
+
+    async def exchange_code(
+        self,
+        ctx: PluginContext,
+        credentials: dict[str, str],
+        code: str,
+        redirect_uri: str,
+        code_verifier: str | None = None,
+    ) -> tuple[IdentityProfile, IdentityCredentials]:
+        endpoints = self._endpoints(ctx.assignment_options)
+        data: dict[str, str] = {
+            'client_id': credentials['client_id'],
+            'client_secret': credentials['client_secret'],
+            'code': code,
+            'redirect_uri': redirect_uri,
+        }
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            token_resp = await client.post(
+                endpoints['token'],
+                data=data,
+                headers={'Accept': 'application/json'},
+            )
+        if token_resp.status_code != 200:
+            raise ValueError(
+                f'GitHub token exchange failed: {token_resp.status_code} '
+                f'{token_resp.text}'
+            )
+        token = typing.cast(dict[str, typing.Any], token_resp.json())
+        if 'access_token' not in token:
+            raise ValueError(
+                f'GitHub token response missing access_token: {token}'
+            )
+
+        access_token = str(token['access_token'])
+        profile = await self._fetch_profile(endpoints, access_token)
+
+        expires_at: datetime.datetime | None = None
+        if 'expires_in' in token:
+            expires_at = datetime.datetime.now(
+                datetime.UTC
+            ) + datetime.timedelta(seconds=int(token['expires_in']))
+
+        raw_scope = token.get('scope', '')
+        scopes: list[str] = (
+            [s for s in str(raw_scope).split(',') if s] if raw_scope else []
+        )
+        return profile, IdentityCredentials(
+            access_token=access_token,
+            token_type=token.get('token_type', 'Bearer'),
+            refresh_token=token.get('refresh_token'),
+            expires_at=expires_at,
+            scopes=scopes,
+        )
+
+    async def refresh(
+        self,
+        ctx: PluginContext,
+        credentials: dict[str, str],
+        refresh_token: str,
+    ) -> IdentityCredentials:
+        endpoints = self._endpoints(ctx.assignment_options)
+        data: dict[str, str] = {
+            'client_id': credentials['client_id'],
+            'client_secret': credentials['client_secret'],
+            'grant_type': 'refresh_token',
+            'refresh_token': refresh_token,
+        }
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.post(
+                endpoints['token'],
+                data=data,
+                headers={'Accept': 'application/json'},
+            )
+        if response.status_code != 200:
+            raise ValueError(
+                f'GitHub token refresh failed: {response.status_code} '
+                f'{response.text}'
+            )
+        token = typing.cast(dict[str, typing.Any], response.json())
+        if 'access_token' not in token:
+            raise ValueError(
+                f'GitHub refresh response missing access_token: {token}'
+            )
+        expires_at: datetime.datetime | None = None
+        if 'expires_in' in token:
+            expires_at = datetime.datetime.now(
+                datetime.UTC
+            ) + datetime.timedelta(seconds=int(token['expires_in']))
+        raw_scope = token.get('scope', '')
+        scopes: list[str] = (
+            [s for s in str(raw_scope).split(',') if s] if raw_scope else []
+        )
+        return IdentityCredentials(
+            access_token=str(token['access_token']),
+            token_type=token.get('token_type', 'Bearer'),
+            refresh_token=token.get('refresh_token', refresh_token),
+            expires_at=expires_at,
+            scopes=scopes,
+        )
+
+    async def _fetch_profile(
+        self, endpoints: dict[str, str], access_token: str
+    ) -> IdentityProfile:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            user_resp = await client.get(
+                endpoints['user'],
+                headers={
+                    'Authorization': f'Bearer {access_token}',
+                    'Accept': 'application/vnd.github+json',
+                },
+            )
+            if user_resp.status_code != 200:
+                raise ValueError(
+                    f'GitHub /user failed: {user_resp.status_code} '
+                    f'{user_resp.text}'
+                )
+            claims = typing.cast(dict[str, typing.Any], user_resp.json())
+            # Fall back to /user/emails when the primary email is
+            # private — GitHub returns email=null on /user in that case.
+            if not claims.get('email'):
+                emails_resp = await client.get(
+                    endpoints['emails'],
+                    headers={
+                        'Authorization': f'Bearer {access_token}',
+                        'Accept': 'application/vnd.github+json',
+                    },
+                )
+                if emails_resp.status_code == 200:
+                    rows = typing.cast(
+                        list[dict[str, typing.Any]], emails_resp.json()
+                    )
+                    primary = next(
+                        (
+                            row
+                            for row in rows
+                            if row.get('primary') and row.get('verified')
+                        ),
+                        None,
+                    )
+                    if primary:
+                        claims['email'] = primary['email']
+        return _build_userinfo(claims)
+
+
+class GitHubPlugin(_GitHubBase):
+    manifest = PluginManifest(
+        slug='github',
+        name='GitHub',
+        description='GitHub.com OAuth App identity provider.',
+        widget_text=(
+            'Connect to enable functionality such as pull-request visibility, '
+            'project creation, and deployments.'
+        ),
+        plugin_type='identity',
+        auth_type='oauth2',
+        login_capable=True,
+        default_scopes=DEFAULT_SCOPES,
+        options=[
+            PluginOption(
+                name='default_scopes',
+                label='Default scopes (space-separated)',
+                type='string',
+            ),
+        ],
+        credentials=[
+            CredentialField(
+                name='client_id',
+                label='Client ID',
+                required=True,
+            ),
+            CredentialField(
+                name='client_secret',
+                label='Client secret',
+                required=True,
+            ),
+        ],
+    )
+
+    @classmethod
+    def _resolve_host(cls, options: dict[str, typing.Any]) -> str:
+        return 'github.com'
+
+
+class GitHubEnterpriseCloudPlugin(_GitHubBase):
+    manifest = PluginManifest(
+        slug='github-enterprise-cloud',
+        name='GitHub Enterprise Cloud',
+        description=(
+            'GitHub Enterprise Cloud OAuth App identity provider '
+            '(tenant.ghe.com).'
+        ),
+        widget_text=(
+            'Connect to enable functionality such as pull-request visibility, '
+            'project creation, and deployments.'
+        ),
+        plugin_type='identity',
+        auth_type='oauth2',
+        login_capable=True,
+        default_scopes=DEFAULT_SCOPES,
+        options=[
+            PluginOption(
+                name='host',
+                label='GHEC tenant host',
+                description='e.g. tenant.ghe.com',
+                type='string',
+                required=True,
+            ),
+            PluginOption(
+                name='default_scopes',
+                label='Default scopes (space-separated)',
+                type='string',
+            ),
+        ],
+        credentials=[
+            CredentialField(
+                name='client_id',
+                label='Client ID',
+                required=True,
+            ),
+            CredentialField(
+                name='client_secret',
+                label='Client secret',
+                required=True,
+            ),
+        ],
+    )
+
+    @classmethod
+    def _resolve_host(cls, options: dict[str, typing.Any]) -> str:
+        return require_ghec_tenant_host(
+            normalize_host(options.get('host'), 'GHEC plugin'),
+            'GHEC plugin',
+        )
+
+
+class GitHubEnterpriseServerPlugin(_GitHubBase):
+    manifest = PluginManifest(
+        slug='github-enterprise-server',
+        name='GitHub Enterprise Server',
+        description=('GitHub Enterprise Server OAuth App identity provider.'),
+        widget_text=(
+            'Connect to enable functionality such as pull-request visibility, '
+            'project creation, and deployments.'
+        ),
+        plugin_type='identity',
+        auth_type='oauth2',
+        login_capable=True,
+        default_scopes=DEFAULT_SCOPES,
+        options=[
+            PluginOption(
+                name='host',
+                label='GHES host',
+                description='Hostname of the GHES install.',
+                type='string',
+                required=True,
+            ),
+            PluginOption(
+                name='default_scopes',
+                label='Default scopes (space-separated)',
+                type='string',
+            ),
+        ],
+        credentials=[
+            CredentialField(
+                name='client_id',
+                label='Client ID',
+                required=True,
+            ),
+            CredentialField(
+                name='client_secret',
+                label='Client secret',
+                required=True,
+            ),
+        ],
+    )
+
+    @classmethod
+    def _resolve_host(cls, options: dict[str, typing.Any]) -> str:
+        return normalize_host(options.get('host'), 'GHES plugin')

imbi_plugin_github-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: imbi-plugin-github
+Version: 0.1.0
+Summary: GitHub identity plugin for Imbi (github.com / GHEC / GHES)
+Author-email: "Gavin M. Roy" <gavinr@aweber.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: imbi-common>=0.8.4
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# imbi-plugin-github
+
+GitHub identity plugin for Imbi. Ships three entry points so the admin UI
+can distinguish github.com, GitHub Enterprise Cloud, and GitHub Enterprise
+Server installations:
+
+| Entry point                | Slug                          | Host                                |
+| -------------------------- | ----------------------------- | ----------------------------------- |
+| `github`                   | `github`                      | `github.com`                        |
+| `github-enterprise-cloud`  | `github-enterprise-cloud`     | `<tenant>.ghe.com`                  |
+| `github-enterprise-server` | `github-enterprise-server`    | operator-supplied via the `host` option |
+
+Phase 1 ships the OAuth App flow only; GitHub App installation tokens are
+deferred. The access token returned by the OAuth grant is passed straight
+to GitHub APIs as a `Bearer` token, so `materialize()` is a no-op.
+
+## Manifest options
+
+| Option           | Required  | Description                                                                |
+| ---------------- | --------- | -------------------------------------------------------------------------- |
+| `host`           | GHEC/GHES | Tenant or appliance host (e.g. `tenant.ghe.com`, `github.example.com`).    |
+| `default_scopes` | no        | Space-separated default OAuth scopes (default: `read:user user:email`).    |
+
+## Credentials
+
+| Field            | Required |
+| ---------------- | -------- |
+| `client_id`      | yes      |
+| `client_secret`  | yes      |
+
+## License
+
+BSD-3-Clause.

imbi_plugin_github-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+imbi_plugin_github/__init__.py,sha256=8ZVhm8XpGqgYRUtpHl0uuZTT3gmMyHNhKd9k6qoatB4,298
+imbi_plugin_github/_hosts.py,sha256=85HWZpXfFsFUUCkUQaH_89um6JZoqX0CBohMxijgYiw,1576
+imbi_plugin_github/deployment.py,sha256=vP2Xy9g6bmimjBweRsuEgIzQKxbHxprUpWxz_OrReis,37007
+imbi_plugin_github/identity.py,sha256=G2sKYRP3E8ranE_2vzU1UKBMojASYOZS6SWvdL7A3Ag,15581
+imbi_plugin_github-0.1.0.dist-info/METADATA,sha256=0k_aEeZz5BJ8nBVibe88tQYaUu0Vat1JagfGmRSIXFs,2203
+imbi_plugin_github-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+imbi_plugin_github-0.1.0.dist-info/entry_points.txt,sha256=68UubEFN70ufwnpNkSnzTUUDSeu2hNNUs6YBN6qOcrI,487
+imbi_plugin_github-0.1.0.dist-info/licenses/LICENSE,sha256=el9B20zOqEcv_mRrHgbdkVyxSC6I8np7am0D6mO2A9Y,1491
+imbi_plugin_github-0.1.0.dist-info/RECORD,,

imbi_plugin_github-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

imbi_plugin_github-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,7 @@
+[imbi.plugins]
+github = imbi_plugin_github.identity:GitHubPlugin
+github-deployment = imbi_plugin_github.deployment:GitHubDeploymentPlugin
+github-deployment-ec = imbi_plugin_github.deployment:GitHubEnterpriseCloudDeploymentPlugin
+github-deployment-es = imbi_plugin_github.deployment:GitHubEnterpriseServerDeploymentPlugin
+github-enterprise-cloud = imbi_plugin_github.identity:GitHubEnterpriseCloudPlugin
+github-enterprise-server = imbi_plugin_github.identity:GitHubEnterpriseServerPlugin

imbi_plugin_github-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Imbi
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.