secondshift 0.1.0b12__py3-none-any.whl

secondshift/github/credentials.py

@@ -0,0 +1,59 @@
+"""One way to get a GitHub token, whatever kind of credential stands behind it."""
+
+from dataclasses import dataclass
+
+from secondshift.github import app
+
+READ = {"contents": "read"}
+WRITE = {"contents": "write", "pull_requests": "write"}
+ISSUES_WRITE = {"issues": "write"}
+
+
+@dataclass(frozen=True)
+class AppInstallation:
+    """A GitHub App installation. Each token is minted for one request."""
+
+    installation_id: str
+
+
+@dataclass(frozen=True)
+class PersonalToken:
+    """A fine-grained personal access token. It cannot be narrowed per request."""
+
+    token: str
+
+
+Source = AppInstallation | PersonalToken
+
+
+def token_for(
+    source: Source, repository_id: int | None, permissions: dict[str, str]
+) -> str:
+    """A token for one repository, or for the whole source when repository_id is None.
+
+    App tokens carry only the permissions asked for and expire within an hour.
+    A personal token is returned as it is. GitHub refuses what it cannot do.
+    """
+    if isinstance(source, PersonalToken):
+        return source.token
+    return app.installation_token(source.installation_id, repository_id, permissions)
+
+
+def read_token_for(
+    source: Source, repository_id: int | None, wanted: tuple[str, ...]
+) -> str:
+    """A read-only token with the wanted permissions the source has.
+
+    An App token never asks for more than the installation granted, so a
+    missing permission fails only the calls that need it. A personal token
+    has whatever its owner gave it.
+    """
+    if isinstance(source, PersonalToken):
+        return source.token
+    granted = app.installation_permissions(source.installation_id)
+    permissions = {
+        name: "read" for name in wanted if granted.get(name) in {"read", "write"}
+    }
+    return app.installation_token(
+        source.installation_id, repository_id, permissions or {"metadata": "read"}
+    )

secondshift/github/errors.py

@@ -0,0 +1,2 @@
+class GitHubError(ValueError):
+    """A GitHub step failed. The message never contains a credential."""

secondshift/github/git.py

@@ -0,0 +1,56 @@
+"""Run git against GitHub with a token that never leaves the process."""
+
+import base64
+import os
+import subprocess
+from pathlib import Path
+
+from secondshift.config.constants import GITHUB_BASE_URL
+from secondshift.github.errors import GitHubError
+
+
+def authenticated_git(root: Path, token: str, *arguments: str) -> str:
+    """Run one git command in root, sending the token only as a header."""
+    # Never put credentials in URLs, arguments, persisted config, or errors.
+    authorization = base64.b64encode(f"x-access-token:{token}".encode()).decode()
+    return run_git(
+        root,
+        arguments,
+        {
+            "GIT_CONFIG_COUNT": "1",
+            "GIT_CONFIG_KEY_0": f"http.{GITHUB_BASE_URL}/.extraheader",
+            "GIT_CONFIG_VALUE_0": f"AUTHORIZATION: basic {authorization}",
+        },
+    )
+
+
+def public_git(root: Path, *arguments: str) -> str:
+    """Run one git command in root without any credentials."""
+    return run_git(root, arguments, {"GIT_CONFIG_COUNT": "0"})
+
+
+def run_git(root: Path, arguments: tuple[str, ...], config: dict[str, str]) -> str:
+    environment = {
+        **os.environ,
+        "GIT_TERMINAL_PROMPT": "0",
+        "GIT_CONFIG_NOSYSTEM": "1",
+        "GIT_CONFIG_GLOBAL": os.devnull,
+        # No helper may answer a password prompt with stored credentials.
+        "GIT_ASKPASS": "",
+        "SSH_ASKPASS": "",
+        **config,
+    }
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), *arguments],
+            env=environment,
+            capture_output=True,
+            text=True,
+            timeout=120,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as error:
+        raise GitHubError("GitHub repository fetch timed out.") from error
+    if result.returncode:
+        raise GitHubError("Could not fetch the GitHub repository and branch.")
+    return result.stdout.strip()

secondshift/github/identity.py

@@ -0,0 +1,35 @@
+"""Repository names from GitHub remotes."""
+
+import re
+from urllib.parse import urlsplit
+
+from secondshift.config.constants import (
+    GITHUB_BASE_URL,
+    GITHUB_HOST,
+    GITHUB_REPOSITORY_PATTERN,
+    GITHUB_SSH_PREFIX,
+)
+
+
+def github_remote_name(remote: str) -> str | None:
+    """The owner/name a GitHub remote points at, or None for anything else."""
+    if remote.startswith(GITHUB_SSH_PREFIX):
+        path = remote.removeprefix(GITHUB_SSH_PREFIX)
+    else:
+        try:
+            parts = urlsplit(remote)
+            if parts.hostname != GITHUB_HOST or parts.scheme not in {"https", "ssh"}:
+                return None
+            path = parts.path.removeprefix("/")
+        except ValueError:
+            return None
+    name = path.removesuffix("/").removesuffix(".git")
+    return name if valid_name(name) else None
+
+
+def valid_name(full_name: str) -> bool:
+    return bool(re.fullmatch(GITHUB_REPOSITORY_PATTERN, full_name))
+
+
+def clone_url(full_name: str) -> str:
+    return f"{GITHUB_BASE_URL}/{full_name}.git"

secondshift/github/installations.py

@@ -0,0 +1,74 @@
+"""Find the App installations a person can use, through their own sign-in.
+
+The person's token proves which installations they may link. It is used for
+two requests and never stored.
+"""
+
+from dataclasses import dataclass
+from urllib.parse import urlencode
+
+from django.conf import settings
+
+from secondshift.config.constants import (
+    GITHUB_API_URL,
+    GITHUB_BASE_URL,
+    GITHUB_OAUTH_URL,
+)
+from secondshift.github.errors import GitHubError
+from secondshift.github.rest import paginated, request_json
+
+
+@dataclass(frozen=True)
+class Installation:
+    installation_id: str
+    account: str
+
+
+def authorization_url(state: str, redirect_uri: str) -> str:
+    return f"{GITHUB_OAUTH_URL}/authorize?" + urlencode(
+        {
+            "client_id": settings.GITHUB_APP_CLIENT_ID,
+            "state": state,
+            "redirect_uri": redirect_uri,
+        }
+    )
+
+
+def installation_url(state: str) -> str:
+    return (
+        f"{GITHUB_BASE_URL}/apps/{settings.GITHUB_APP_SLUG}/installations/new?"
+        + urlencode({"state": state})
+    )
+
+
+def user_token(code: str, redirect_uri: str) -> str:
+    data = request_json(
+        "POST",
+        f"{GITHUB_OAUTH_URL}/access_token",
+        json={
+            "client_id": settings.GITHUB_APP_CLIENT_ID,
+            "client_secret": settings.GITHUB_APP_CLIENT_SECRET,
+            "code": code,
+            "redirect_uri": redirect_uri,
+        },
+    )
+    token = data.get("access_token")
+    if not token:
+        raise GitHubError("GitHub did not authorize this user.")
+    return token
+
+
+def user_installations(token: str) -> list[Installation]:
+    """This App's installations that the person can reach. Other apps are skipped."""
+    listed = paginated(
+        f"{GITHUB_API_URL}/user/installations",
+        token,
+        "installations",
+        "You can reach too many GitHub App installations to list.",
+    )
+    return [
+        Installation(str(item["id"]), item["account"]["login"])
+        for item in listed
+        if isinstance(item, dict)
+        and str(item.get("app_id")) == str(settings.GITHUB_APP_ID)
+    ]

secondshift/github/issues.py

@@ -0,0 +1,75 @@
+"""Open issues through the REST API."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from secondshift.config.constants import GITHUB_API_URL
+from secondshift.github.errors import GitHubError
+from secondshift.github.rest import parsed, reason, send
+
+# GitHub refuses a longer title or body.
+MAX_TITLE_CHARS = 256
+MAX_BODY_CHARS = 65_000
+
+
+@dataclass(frozen=True)
+class Issue:
+    number: int
+    url: str
+
+
+def same_title(left: str, right: str) -> bool:
+    return " ".join(left.split()).casefold() == " ".join(right.split()).casefold()
+
+
+def open_issue_titled(token: str, full_name: str, title: str) -> Issue | None:
+    """An open issue with this exact title, so a weekly job does not repeat it.
+
+    Search is a little behind new issues, so this catches older duplicates,
+    not one opened seconds ago.
+    """
+    words = title.replace('"', " ").strip()
+    response = send(
+        "GET",
+        f"{GITHUB_API_URL}/search/issues",
+        token,
+        params={
+            "q": f'repo:{full_name} is:issue is:open in:title "{words}"',
+            "per_page": 20,
+        },
+    )
+    if response.status_code != 200:
+        raise GitHubError(f"GitHub could not search issues: {reason(response)}")
+    payload = parsed(response)
+    items = payload.get("items") if isinstance(payload, dict) else None
+    for item in items if isinstance(items, list) else []:
+        if isinstance(item, dict) and same_title(str(item.get("title", "")), title):
+            return checked(item)
+    return None
+
+
+def open_issue(
+    token: str, full_name: str, title: str, body: str, labels: list[str]
+) -> Issue:
+    payload: dict[str, Any] = {
+        "title": title[:MAX_TITLE_CHARS],
+        "body": body[:MAX_BODY_CHARS],
+    }
+    if labels:
+        payload["labels"] = labels
+    created = send(
+        "POST", f"{GITHUB_API_URL}/repos/{full_name}/issues", token, json=payload
+    )
+    if created.status_code != 201:
+        raise GitHubError(f"GitHub did not open the issue: {reason(created)}")
+    return checked(parsed(created))
+
+
+def checked(payload: Any) -> Issue:
+    if (
+        not isinstance(payload, dict)
+        or not isinstance(payload.get("html_url"), str)
+        or not isinstance(payload.get("number"), int)
+    ):
+        raise GitHubError("GitHub returned an invalid issue.")
+    return Issue(payload["number"], payload["html_url"])

secondshift/github/permissions.py

@@ -0,0 +1,49 @@
+"""What a GitHub credential may do, by feature.
+
+An App installation lists its permissions. A personal token does not, so each
+read permission is probed with one cheap request. Write access cannot be
+probed without writing, so it is never reported for a token.
+"""
+
+from urllib.parse import quote
+
+from secondshift.config.constants import GITHUB_API_URL
+from secondshift.github.rest import send
+
+# The feature each permission serves, as GitHub names them.
+SYNC = ("contents",)
+TOOLS = ("pull_requests", "actions", "statuses")
+DRAFT_PULL_REQUESTS = ("contents", "pull_requests")
+ISSUES = ("issues",)
+
+
+def probe_paths(branch: str) -> dict[str, str]:
+    """A read request per permission. Each fails without that permission."""
+    return {
+        "contents": "commits?per_page=1",
+        "pull_requests": "pulls?per_page=1",
+        "actions": "actions/runs?per_page=1",
+        "statuses": f"commits/{quote(branch, safe='')}/status",
+    }
+
+
+def token_reads(
+    token: str, full_name: str, branch: str, names: tuple[str, ...]
+) -> dict[str, bool]:
+    """Whether the token can read each named permission on this repository."""
+    paths = probe_paths(branch)
+    return {
+        name: send(
+            "GET", f"{GITHUB_API_URL}/repos/{full_name}/{paths[name]}", token
+        ).status_code
+        == 200
+        for name in names
+    }
+
+
+def granted_reads(granted: dict[str, str], names: tuple[str, ...]) -> dict[str, bool]:
+    return {name: granted.get(name) in {"read", "write"} for name in names}
+
+
+def granted_writes(granted: dict[str, str], names: tuple[str, ...]) -> dict[str, bool]:
+    return {name: granted.get(name) == "write" for name in names}

secondshift/github/pulls.py

@@ -0,0 +1,49 @@
+"""Open draft pull requests through the REST API."""
+
+from typing import Any
+
+from secondshift.config.constants import GITHUB_API_URL
+from secondshift.github.errors import GitHubError
+from secondshift.github.rest import parsed, reason, send
+
+# GitHub refuses a longer description.
+MAX_BODY_CHARS = 60_000
+
+
+def open_draft(
+    token: str, full_name: str, title: str, head: str, base: str, body: str
+) -> dict[str, Any]:
+    """Open the draft, or find the one an earlier attempt opened."""
+    url = f"{GITHUB_API_URL}/repos/{full_name}/pulls"
+    created = send(
+        "POST",
+        url,
+        token,
+        json={
+            "title": title,
+            "head": head,
+            "base": base,
+            "body": body[:MAX_BODY_CHARS],
+            "draft": True,
+        },
+    )
+    if created.status_code == 201:
+        return checked(parsed(created))
+    owner = full_name.split("/", 1)[0]
+    existing = send(
+        "GET", url, token, params={"head": f"{owner}:{head}", "state": "all"}
+    )
+    found = parsed(existing) if existing.status_code == 200 else []
+    if isinstance(found, list) and found:
+        return checked(found[0])
+    raise GitHubError(f"GitHub did not open the pull request: {reason(created)}")
+
+
+def checked(payload: object) -> dict[str, Any]:
+    if (
+        not isinstance(payload, dict)
+        or not isinstance(payload.get("html_url"), str)
+        or not isinstance(payload.get("number"), int)
+    ):
+        raise GitHubError("GitHub returned an invalid pull request.")
+    return payload

secondshift/github/repos.py

@@ -0,0 +1,52 @@
+"""Repository lookups that work with any token."""
+
+from urllib.parse import quote
+
+from secondshift.config.constants import GITHUB_API_URL
+from secondshift.github.errors import GitHubError
+from secondshift.github.identity import valid_name
+from secondshift.github.rest import paginated, request_json
+
+
+def repository(token: str, repository_id: int) -> dict:
+    """The repository with this ID. Its name may change, its ID never does."""
+    data = request_json("GET", f"{GITHUB_API_URL}/repositories/{repository_id}", token)
+    if data.get("id") != repository_id:
+        raise GitHubError("GitHub repository identity changed.")
+    if not valid_name(str(data.get("full_name", ""))):
+        raise GitHubError("Invalid GitHub repository name.")
+    return data
+
+
+def branch_head(token: str, repository_id: int, branch: str) -> str:
+    data = request_json(
+        "GET",
+        f"{GITHUB_API_URL}/repositories/{repository_id}/commits/{quote(branch, safe='')}",
+        token,
+    )
+    return data["sha"]
+
+
+def branches(token: str, full_name: str) -> list[str]:
+    batch = paginated(
+        f"{GITHUB_API_URL}/repos/{full_name}/branches",
+        token,
+        None,
+        "This repository has too many branches to list.",
+    )
+    if any(
+        not isinstance(item, dict) or not isinstance(item.get("name"), str)
+        for item in batch
+    ):
+        raise GitHubError("GitHub returned an invalid branch listing.")
+    return [item["name"] for item in batch]
+
+
+def token_repositories(token: str) -> list[dict]:
+    """The repositories a personal access token was given."""
+    return paginated(
+        f"{GITHUB_API_URL}/user/repos",
+        token,
+        None,
+        "This token reaches too many repositories to list.",
+    )

secondshift/github/rest.py

@@ -0,0 +1,93 @@
+"""The one way SecondShift calls GitHub's REST API.
+
+Errors raised here never include the token, the request, or GitHub's reply.
+"""
+
+from typing import Any
+
+import httpx
+
+from secondshift.config.constants import GITHUB_API_VERSION
+from secondshift.github.errors import GitHubError
+
+PAGE_SIZE = 100
+MAX_PAGES = 100
+TIMEOUT_SECONDS = 30
+
+
+def headers(token: str = "") -> dict[str, str]:
+    return {
+        "Accept": "application/json",
+        **({"Authorization": f"Bearer {token}"} if token else {}),
+        "X-GitHub-Api-Version": GITHUB_API_VERSION,
+    }
+
+
+def client() -> httpx.Client:
+    return httpx.Client(timeout=TIMEOUT_SECONDS)
+
+
+def send(method: str, url: str, token: str = "", **kwargs: Any) -> httpx.Response:
+    """The raw response, for callers that read GitHub's status codes."""
+    try:
+        with client() as session:
+            return session.request(method, url, headers=headers(token), **kwargs)
+    except (httpx.HTTPError, httpx.InvalidURL) as error:
+        raise GitHubError("GitHub could not be reached.") from error
+
+
+def request_payload(method: str, url: str, token: str = "", **kwargs: Any) -> object:
+    try:
+        response = send(method, url, token, **kwargs)
+        response.raise_for_status()
+        return response.json()
+    except (httpx.HTTPError, ValueError, GitHubError) as error:
+        raise GitHubError(
+            "GitHub access failed. Check the installation and permissions."
+        ) from error
+
+
+def request_json(method: str, url: str, token: str = "", **kwargs: Any) -> dict:
+    result = request_payload(method, url, token, **kwargs)
+    if not isinstance(result, dict) or "error" in result:
+        raise GitHubError("GitHub returned an invalid authorization response.")
+    return result
+
+
+def paginated(url: str, token: str, key: str | None, too_many: str) -> list[Any]:
+    """Every item of a listing, page by page. key names the list in each page."""
+    items: list[Any] = []
+    separator = "&" if "?" in url else "?"
+    for page in range(1, MAX_PAGES + 1):
+        payload = request_payload(
+            "GET", f"{url}{separator}per_page={PAGE_SIZE}&page={page}", token
+        )
+        batch = payload.get(key) if key and isinstance(payload, dict) else payload
+        if not isinstance(batch, list):
+            raise GitHubError("GitHub returned an invalid listing.")
+        items.extend(batch)
+        if len(batch) < PAGE_SIZE:
+            return items
+    raise GitHubError(too_many)
+
+
+def parsed(response: httpx.Response) -> object:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def reason(response: httpx.Response) -> str:
+    """GitHub's own short reason, which never contains the token."""
+    payload = parsed(response)
+    errors = payload.get("errors") if isinstance(payload, dict) else None
+    details = [
+        str(item.get("message"))
+        for item in errors or []
+        if isinstance(item, dict) and item.get("message")
+    ]
+    message = details[0] if details else ""
+    if not message and isinstance(payload, dict):
+        message = str(payload.get("message", ""))
+    return (message or f"HTTP {response.status_code}")[:200]

secondshift/github/ruff.toml

@@ -0,0 +1,16 @@
+# This package must not depend on the Django apps, so every app can use it.
+# This list replaces the root one, so the root ban on requests is repeated.
+extend = "../../pyproject.toml"
+
+[lint.flake8-tidy-imports.banned-api]
+"requests".msg = "Use httpx, the project's one HTTP client."
+"secondshift.connections".msg = "secondshift.github must not import Django apps."
+"secondshift.core".msg = "secondshift.github must not import Django apps."
+"secondshift.gateway".msg = "secondshift.github must not import Django apps."
+"secondshift.jobs".msg = "secondshift.github must not import Django apps."
+"secondshift.mcp_server".msg = "secondshift.github must not import Django apps."
+"secondshift.repositories".msg = "secondshift.github must not import Django apps."
+"secondshift.runner".msg = "secondshift.github must not import Django apps."
+"secondshift.runs".msg = "secondshift.github must not import Django apps."
+"secondshift.triggers".msg = "secondshift.github must not import Django apps."
+"secondshift.workspaces".msg = "secondshift.github must not import Django apps."

secondshift/github/tokens.py

@@ -0,0 +1,52 @@
+"""Check a personal access token before SecondShift stores it."""
+
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+import httpx
+
+from secondshift.config.constants import (
+    GITHUB_API_URL,
+    GITHUB_FINE_GRAINED_TOKEN_PATTERN,
+    GITHUB_TOKEN_HINT,
+)
+from secondshift.github.errors import GitHubError
+from secondshift.github.rest import send
+
+# GitHub sends a token's expiry with every response it answers with that token.
+EXPIRY_HEADER = "github-authentication-token-expiration"
+
+
+@dataclass(frozen=True)
+class TokenOwner:
+    login: str
+    expires_at: datetime | None
+
+
+def inspect_token(token: str) -> TokenOwner:
+    """Whose token this is and when it expires. Refuses classic tokens."""
+    if not re.fullmatch(GITHUB_FINE_GRAINED_TOKEN_PATTERN, token):
+        raise GitHubError(GITHUB_TOKEN_HINT)
+    response = send("GET", f"{GITHUB_API_URL}/user", token)
+    if response.status_code == 401:
+        raise GitHubError("GitHub refused this token. It may have expired.")
+    try:
+        response.raise_for_status()
+        login = response.json()["login"]
+    except (httpx.HTTPError, ValueError, KeyError, TypeError) as error:
+        raise GitHubError("GitHub could not check this token.") from error
+    if not isinstance(login, str) or not login:
+        raise GitHubError("GitHub could not check this token.")
+    return TokenOwner(login, expiry(response.headers.get(EXPIRY_HEADER, "")))
+
+
+def expiry(value: str) -> datetime | None:
+    """Parse "2026-12-01 08:00:00 UTC" or "... -0800". None for no expiry."""
+    value = value.strip().replace(" UTC", " +0000")
+    if not value:
+        return None
+    try:
+        return datetime.strptime(value, "%Y-%m-%d %H:%M:%S %z").astimezone(UTC)
+    except ValueError:
+        return None

secondshift/jobs/access.py

@@ -0,0 +1,12 @@
+from django.http import Http404, HttpRequest
+
+from secondshift.jobs.dao import find_active_job
+from secondshift.jobs.models import Job
+from secondshift.workspaces.access import current_workspace
+
+
+def job_for_request(request: HttpRequest, job_id: int) -> Job:
+    job = find_active_job(current_workspace(request), job_id)
+    if job is None:
+        raise Http404
+    return job