codna 0.1.6__tar.gz → 0.1.7__tar.gz

{codna-0.1.6 → codna-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codna
-Version: 0.1.6
+Version: 0.1.7
 Summary: Local-first repo intelligence and agent fixing for Codna.
 Author: Thyn
 Maintainer: Thyn

{codna-0.1.6 → codna-0.1.7}/codna/__init__.py

@@ -5,4 +5,4 @@ This package is the `codna` CLI. Users never touch "algenta" directly — the en
 is an internal dependency reached over HTTP.
 """
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"

{codna-0.1.6 → codna-0.1.7}/codna/cli.py

@@ -658,6 +658,32 @@ def cmd_secure_open_pr(args) -> None:
     print(f"✓ opened draft PR: {url}")
 
 
+def cmd_webhook(args):
+    """Run Codna's GitHub App webhook — the App channel, owned in Codna.
+
+    Verifies each delivery's signature, classifies the event into a Codna job
+    (fix on failing CI / `codna-fix`; security-autofix on `codna-secure` /
+    code-scanning alerts), and dispatches by invoking the `codna` CLI. All of
+    this is Codna-specific product wiring and lives in Codna, never in the
+    Algenta SDK/engine (which ships generic to other users).
+    """
+    from .webhook import WebhookError, serve
+
+    action = getattr(args, "action", "serve") or "serve"
+    if action != "serve":
+        _die(f"unknown `codna webhook` action: {action}")
+    host = getattr(args, "host", "0.0.0.0")
+    port = int(getattr(args, "port", 8080))
+    try:
+        print(f"codna webhook: listening on {host}:{port}/webhooks/github", file=sys.stderr)
+        serve(host=host, port=port)
+    except WebhookError as exc:
+        _die(str(exc))
+    except KeyboardInterrupt:
+        return 0
+    return 0
+
+
 def cmd_mcp(args):
     action = getattr(args, "action", "start") or "start"
     if action == "install":
@@ -875,6 +901,14 @@ def build_parser() -> argparse.ArgumentParser:
     po.add_argument("--base-branch", help="PR base branch (default: main)")
     po.set_defaults(func=cmd_secure_open_pr)
 
+    pw = sub.add_parser("webhook", help="Run Codna's GitHub App webhook (the App channel, owned in Codna).")
+    pw_sub = pw.add_subparsers(dest="action")
+    pw_serve = pw_sub.add_parser("serve", help="Serve the webhook: verify → classify → run codna fix/secure.")
+    pw_serve.add_argument("--host", default="0.0.0.0", help="bind host (default: 0.0.0.0)")
+    pw_serve.add_argument("--port", type=int, default=8080, help="bind port (default: 8080)")
+    pw_serve.set_defaults(func=cmd_webhook, action="serve")
+    pw.set_defaults(func=cmd_webhook, action="serve")
+
     pm = sub.add_parser("mcp", help="Run codna as an MCP server, or install it into a client (Cursor / Claude).")
     pm.add_argument("action", nargs="?", choices=["start", "install"], default="start",
                     help="start the MCP server (default), or install it into a client config")

{codna-0.1.6 → codna-0.1.7}/codna/packaged_git.py

@@ -225,13 +225,15 @@ def _checkout_requested_ref(
 ) -> None:
     ref = request.get("ref")
     if isinstance(ref, str) and ref.strip():
-        clean_ref = ref.strip()
+        clean_ref = _validated_ref(ref)  # reject option-like / malformed refs (arg-injection RCE)
         fetch = _run_git(
             repo_root,
             ["fetch", "--depth=1", "origin", clean_ref],
             env=_git_auth_env(repository_url, access_token),
             check=False,
         )
+        # On a clean fetch use the literal FETCH_HEAD; otherwise fall back to the validated ref
+        # (guaranteed not to begin with '-', so git can never read it as an option).
         target = "FETCH_HEAD" if fetch.returncode == 0 else clean_ref
         _run_git(repo_root, ["checkout", "--detach", target])
     else:
@@ -262,6 +264,31 @@ def _reset_owned_checkout(repo_root: Path) -> None:
     _run_git(repo_root, ["clean", "-fdx"])
 
 
+_HEX_DIGITS = frozenset("0123456789abcdefABCDEF")
+
+
+def _validated_ref(ref: str) -> str:
+    """Validate a user/webhook-supplied git ref before it reaches a git positional.
+
+    Closes an argument-injection RCE: an unvalidated ref that begins with ``-`` (e.g.
+    ``--upload-pack=<cmd>``) is parsed by git as an option and can execute arbitrary
+    commands. A ref must be either a hex commit SHA or a well-formed refname, and must
+    never begin with ``-``.
+    """
+    clean = ref.strip()
+    if not clean or clean != ref or clean.startswith("-"):
+        raise PackagedGitError("repository_invalid_ref", "Requested git ref is invalid.", {"ref": ref})
+    if 7 <= len(clean) <= 64 and all(c in _HEX_DIGITS for c in clean):
+        return clean  # commit SHA — safe positional, cannot be an option
+    result = subprocess.run(
+        ["git", "check-ref-format", "--allow-onelevel", clean],
+        capture_output=True, text=True, check=False, timeout=10,
+    )
+    if result.returncode != 0:
+        raise PackagedGitError("repository_invalid_ref", "Requested git ref is invalid.", {"ref": ref})
+    return clean
+
+
 def _validated_branch(branch: str) -> str:
     if not branch or branch.strip() != branch:
         raise PackagedGitError("repository_remote_pr_invalid_branch", "Git branch name is invalid.", {"branch": branch})
@@ -317,6 +344,11 @@ def _reject_embedded_credentials(repository_url: str) -> None:
 
 def _git_auth_env(repository_url: str, token: str | None) -> dict[str, str] | None:
     env = dict(os.environ)
+    # Hermetic: never inherit ambient GIT_CONFIG_* injection from the caller's shell.
+    # codna's git operations must use only the config codna sets here — a security product
+    # cannot let the surrounding environment silently alter how it clones or pushes.
+    for key in [k for k in env if k == "GIT_CONFIG_COUNT" or k.startswith(("GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_"))]:
+        env.pop(key, None)
     env["GIT_TERMINAL_PROMPT"] = "0"
     if token and repository_url.startswith(("http://", "https://")):
         credential = b64encode(f"x-access-token:{token}".encode("utf-8")).decode("ascii")

codna-0.1.7/codna/webhook.py

@@ -0,0 +1,281 @@
+"""Codna's GitHub App webhook — the App channel, owned in Codna.
+
+Codna is always local; the GitHub App is the only hosted surface. Anything Codna-specific —
+the ``codna-fix`` / ``codna-secure`` labels, deciding what a GitHub event means, running
+``codna fix`` / ``codna secure`` — lives HERE in the Codna repo, never in the Algenta SDK or
+the engine (which ships standalone to other users).
+
+Architecture (thin ingress → durable queue → worker pool), all inside the one hosted app:
+  * this module is the pure core (:func:`verify_signature`, :func:`classify_event`,
+    :func:`codna_command`) + a stdlib ``http.server`` ingress that VERIFIES and ENQUEUES only
+    (fast ack — GitHub times out at 10s);
+  * :mod:`codna.webhook_queue` is a durable, dedup'd, local SQLite queue;
+  * :mod:`codna.webhook_worker` is the in-process worker pool that runs the codna CLI in an
+    isolated, scrubbed workspace with a scoped installation token and reports via a Check Run.
+
+Fail-closed: an unsigned/mis-signed delivery → 401; an event Codna doesn't act on → 204; a
+recognized event → 202 (accepted, enqueued); a duplicate delivery → 200 (already queued).
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Mapping
+
+# --- Codna-specific policy (labels + which CI outcomes are actionable) ---------------
+FIX_LABEL = "codna-fix"
+SECURE_LABEL = "codna-secure"
+_FAILING_CONCLUSIONS = {"failure", "timed_out", "startup_failure", "action_required"}
+_WEBHOOK_SECRET_ENV = "CODNA_GITHUB_WEBHOOK_SECRET"
+_MAX_BODY_BYTES = 25 * 1024 * 1024  # GitHub caps webhook payloads at ~25 MB; reject anything larger
+
+
+class WebhookError(RuntimeError):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+# --- pure core: verify · classify · command (stdlib only, unit-tested) ----------------
+def verify_signature(secret: str, body: bytes, signature_header: str | None) -> bool:
+    """Constant-time verify GitHub's ``X-Hub-Signature-256`` (``sha256=<hex hmac>``)."""
+    if not secret or not signature_header or not signature_header.startswith("sha256="):
+        return False
+    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    provided = signature_header[len("sha256="):]
+    return hmac.compare_digest(expected, provided)
+
+
+@dataclass(frozen=True)
+class WebhookJob:
+    """A Codna job derived from a verified GitHub event."""
+
+    kind: str  # "fix" | "secure"
+    repo_full_name: str
+    ref: str | None = None
+    installation_id: int | None = None
+    issue_number: int | None = None
+    reason: str = ""
+
+
+def _repo_full_name(payload: Mapping[str, Any]) -> str | None:
+    name = (payload.get("repository") or {}).get("full_name")
+    return name if isinstance(name, str) and "/" in name else None
+
+
+def _installation_id(payload: Mapping[str, Any]) -> int | None:
+    value = (payload.get("installation") or {}).get("id")
+    return value if isinstance(value, int) else None
+
+
+def _safe_ref(value: Any) -> str | None:
+    """A ref is forwarded only if it can't be read by git as an option (no leading '-').
+
+    Defense-in-depth at the trust boundary; packaged_git._validated_ref is the hard sink.
+    """
+    return value if isinstance(value, str) and value and not value.startswith("-") else None
+
+
+def classify_event(event: str, payload: Mapping[str, Any]) -> WebhookJob | None:
+    """Map a GitHub ``(event, payload)`` to a Codna job, or ``None`` to ignore it.
+
+    fix    — a failing CI ``check_suite``, or an issue labeled ``codna-fix``.
+    secure — an issue labeled ``codna-secure``, or a ``code_scanning_alert`` appearing.
+    """
+    action = str(payload.get("action") or "")
+    repo = _repo_full_name(payload)
+    if not repo:
+        return None
+    installation = _installation_id(payload)
+
+    if event == "check_suite" and action == "completed":
+        node = payload.get("check_suite") or {}
+        if node.get("conclusion") in _FAILING_CONCLUSIONS:
+            ref = _safe_ref(node.get("head_sha") or node.get("head_branch"))
+            return WebhookJob("fix", repo, ref=ref, installation_id=installation, reason="ci_check_suite_failed")
+        return None
+
+    if event == "issues" and action == "labeled":
+        label = (payload.get("label") or {}).get("name")
+        number = (payload.get("issue") or {}).get("number")
+        if label == FIX_LABEL:
+            return WebhookJob("fix", repo, installation_id=installation, issue_number=number, reason="labeled_codna_fix")
+        if label == SECURE_LABEL:
+            return WebhookJob("secure", repo, installation_id=installation, issue_number=number, reason="labeled_codna_secure")
+        return None
+
+    if event == "code_scanning_alert" and action in {"created", "reopened", "appeared_in_branch"}:
+        return WebhookJob("secure", repo, ref=_safe_ref(payload.get("ref")),
+                          installation_id=installation, reason="code_scanning_alert")
+
+    return None
+
+
+def webhook_marker(job: WebhookJob) -> str:
+    """Deterministic idempotency marker embedded in each fix PR body.
+
+    Keyed on the trigger (repo/kind/ref-or-issue), NOT on the delivery id, so a recover_stale
+    re-run after a hard crash produces the SAME marker — the worker then finds the PR the first
+    run already opened and reuses it instead of opening a duplicate.
+    """
+    key = job.ref or (str(job.issue_number) if job.issue_number else "default")
+    return f"codna-webhook-id: {job.repo_full_name}#{job.kind}#{key}"
+
+
+def codna_command(job: WebhookJob, *, repo_url: str | None = None, sarif_path: str | None = None) -> list[str]:
+    """Build the ``codna`` argv for a classified job.
+
+    fix    — ``codna fix <url> [--ref] --open-pr``.
+    secure — ``codna secure <url> [--ref] --from-sarif <sarif>`` (read-only Tier-1
+             classification; opening security PRs uses the privilege-separated two-job
+             workflow, never a single server process).
+    """
+    url = repo_url or f"https://github.com/{job.repo_full_name}.git"
+    if job.kind == "secure":
+        if not sarif_path:
+            raise WebhookError("secure_requires_sarif", "secure jobs need a SARIF report (fetched from code scanning).")
+        args = ["codna", "secure", url, "--from-sarif", sarif_path]
+        if job.ref:
+            args += ["--ref", job.ref]
+        return args
+    if job.kind == "fix":
+        args = ["codna", "fix", url, "--open-pr"]
+        if job.ref:
+            args += ["--ref", job.ref]
+        # Embed the idempotency marker in the PR body so a re-run can find + reuse this PR.
+        args += ["--pr-body", f"Automated fix opened by the Codna GitHub App.\n\n{webhook_marker(job)}"]
+        return args
+    raise WebhookError("unknown_job_kind", f"unknown job kind {job.kind!r}")
+
+
+def default_queue_path() -> str:
+    """Where the durable job queue lives (override with CODNA_WEBHOOK_QUEUE, e.g. a Fly volume)."""
+    override = os.environ.get("CODNA_WEBHOOK_QUEUE")
+    if override:
+        return override
+    root = Path(os.environ.get("CODNA_RUNTIME_ROOT") or (Path.home() / ".codna"))
+    path = root / "webhook" / "queue.db"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return str(path)
+
+
+# --- self-hostable server: verify + enqueue (thin ingress) ----------------------------
+class _Handler(BaseHTTPRequestHandler):
+    server_version = "codna-webhook/2"
+
+    def _reply(self, status: int, payload: Mapping[str, Any]) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *_args: Any) -> None:  # keep the server quiet by default
+        return
+
+    def do_GET(self) -> None:  # noqa: N802 (stdlib naming)
+        # Liveness/readiness for load balancers + Fly health checks. Never leaks config.
+        if self.path.rstrip("/") in ("/health", "/healthz", "/ready", ""):
+            configured = bool(os.environ.get(_WEBHOOK_SECRET_ENV))
+            self._reply(200 if configured else 503, {"service": "codna-webhook", "ok": configured})
+            return
+        self._reply(404, {"error": "not_found"})
+
+    def do_POST(self) -> None:  # noqa: N802 (stdlib naming)
+        if self.path.rstrip("/") not in ("/webhooks/github", "/webhook"):
+            self._reply(404, {"error": "not_found"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            self._reply(400, {"error": "invalid_content_length"})
+            return
+        if length < 0 or length > _MAX_BODY_BYTES:
+            self._reply(400, {"error": "invalid_content_length"})
+            return
+        body = self.rfile.read(length) if length else b""
+        secret = os.environ.get(_WEBHOOK_SECRET_ENV, "")
+        if not verify_signature(secret, body, self.headers.get("X-Hub-Signature-256")):
+            self._reply(401, {"error": "invalid_signature"})
+            return
+        event = self.headers.get("X-GitHub-Event", "")
+        try:
+            payload = json.loads(body or b"{}")
+        except ValueError:
+            self._reply(400, {"error": "invalid_json"})
+            return
+        if not isinstance(payload, dict):  # valid JSON that isn't an object (array/number/null)
+            self._reply(400, {"error": "invalid_json"})
+            return
+        job = classify_event(event, payload)
+        if job is None:
+            self._reply(204, {"status": "ignored", "event": event})
+            return
+        # Idempotency key: prefer X-GitHub-Delivery; if absent (redelivery via a header-stripping
+        # proxy, replay, etc.), synthesize a stable one from event+body so a NULL never reaches the
+        # UNIQUE column and identical deliveries still collapse to one row.
+        delivery_id = self.headers.get("X-GitHub-Delivery") or (
+            "synth-" + hashlib.sha256(event.encode("utf-8") + b"\x00" + body).hexdigest()
+        )
+        queue = getattr(self.server, "queue", None)
+        if queue is None:  # no durable queue (e.g. bare handler in a test) — accept without persisting
+            self._reply(202, {"status": "accepted", "kind": job.kind, "repo": job.repo_full_name})
+            return
+        fresh = queue.enqueue(job, delivery_id=delivery_id)
+        self._reply(
+            202 if fresh else 200,
+            {"status": "accepted" if fresh else "duplicate", "kind": job.kind,
+             "repo": job.repo_full_name, "reason": job.reason},
+        )
+
+
+def serve(host: str = "0.0.0.0", port: int = 8080) -> None:
+    """Run the Codna App webhook (blocking): ingress + durable queue + worker pool.
+
+    Requires ``CODNA_GITHUB_WEBHOOK_SECRET``. App auth is ``GITHUB_APP_ID`` /
+    ``GITHUB_APP_PRIVATE_KEY`` (a plain ``GITHUB_TOKEN`` also works for single-repo
+    self-hosting). The fix agent needs a provider LLM key set under its own env var
+    (``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` / ``GEMINI_API_KEY`` / ...) and, for the
+    engine-behind path, ``CODNA_ENGINE_URL`` (or ``ALGENTA_ENGINE_URL``) + ``CODNA_API_KEY`` —
+    the worker forwards exactly those into each job's scrubbed env.
+    """
+    if not os.environ.get(_WEBHOOK_SECRET_ENV):
+        raise WebhookError("webhook_secret_required", f"set {_WEBHOOK_SECRET_ENV} to the GitHub App webhook secret.")
+    import signal
+    import threading
+
+    from .webhook_queue import WebhookQueue
+    from .webhook_worker import WorkerPool
+
+    queue = WebhookQueue(default_queue_path())
+    pool = WorkerPool(
+        queue,
+        concurrency=int(os.environ.get("CODNA_WEBHOOK_CONCURRENCY", "2")),
+        app_id=os.environ.get("GITHUB_APP_ID"),
+        private_key=os.environ.get("GITHUB_APP_PRIVATE_KEY"),
+        provider_key=os.environ.get(os.environ.get("CODNA_WEBHOOK_PROVIDER_KEY_ENV", "CODNA_MODEL_KEY")),
+    )
+    pool.start()
+    httpd = ThreadingHTTPServer((host, port), _Handler)
+    httpd.queue = queue  # type: ignore[attr-defined]
+
+    def _graceful(_sig: int, _frame: Any) -> None:
+        # serve_forever() can't shut itself down from its own thread — do it from another.
+        threading.Thread(target=httpd.shutdown, daemon=True).start()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            signal.signal(sig, _graceful)
+        except (ValueError, OSError):
+            pass  # not the main thread (e.g. under a test harness) — skip handler install
+    try:
+        httpd.serve_forever()
+    finally:
+        pool.stop()          # drain in-flight jobs up to the grace window (no abandon on redeploy)
+        httpd.server_close()

codna-0.1.7/codna/webhook_github.py

@@ -0,0 +1,185 @@
+"""GitHub App API glue for Codna's webhook: scoped tokens, Check Runs, SARIF fetch.
+
+Lazily imports httpx / cryptography (not base Codna deps) so the pure webhook core stays
+stdlib-only. The token/check-run *payload builders* are pure and unit-tested; only the HTTP
+calls need the network.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Mapping
+
+from .webhook import WebhookError
+
+_API = "https://api.github.com"
+
+
+def token_permissions_for(kind: str) -> dict[str, str]:
+    """Least-privilege installation-token permissions for a job kind.
+
+    fix needs to push a branch + open a PR; secure only reads code + code-scanning results.
+    Both may post a Check Run for status.
+    """
+    if kind == "fix":
+        return {"contents": "write", "pull_requests": "write", "checks": "write"}
+    if kind == "secure":
+        return {"contents": "read", "security_events": "read", "checks": "write"}
+    raise WebhookError("unknown_job_kind", f"no token scope for job kind {kind!r}")
+
+
+def scoped_token_request(repo_full_name: str, kind: str) -> dict[str, Any]:
+    """Body for POST /app/installations/{id}/access_tokens — scoped to the one repo + minimal perms."""
+    repo_name = repo_full_name.split("/", 1)[-1]
+    return {"repositories": [repo_name], "permissions": token_permissions_for(kind)}
+
+
+def _app_jwt(app_id: str, private_key_pem: str, *, now: int) -> str:
+    import base64
+
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import padding
+
+    def _b64url(raw: bytes) -> str:
+        return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+    header = _b64url(json.dumps({"alg": "RS256", "typ": "JWT"}).encode())
+    claims = _b64url(json.dumps({"iat": now - 60, "exp": now + 540, "iss": str(app_id)}).encode())
+    signing_input = f"{header}.{claims}".encode()
+    key = serialization.load_pem_private_key(private_key_pem.encode(), password=None)
+    signature = key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
+    return f"{header}.{claims}.{_b64url(signature)}"
+
+
+def installation_token(
+    app_id: str,
+    private_key_pem: str,
+    installation_id: int,
+    *,
+    repo_full_name: str,
+    kind: str,
+) -> str:
+    """Mint a short-lived installation token scoped to one repo with least-privilege perms."""
+    if not (app_id and private_key_pem and installation_id):
+        raise WebhookError("github_app_not_configured", "App id / private key / installation id required.")
+    try:
+        import time as _time
+
+        import httpx
+    except Exception as exc:  # noqa: BLE001
+        raise WebhookError("github_app_auth_unavailable", f"App auth needs cryptography+httpx: {exc}") from exc
+    try:
+        jwt = _app_jwt(app_id, private_key_pem, now=int(_time.time()))
+    except Exception as exc:  # noqa: BLE001
+        raise WebhookError("github_app_auth_unavailable", f"cannot sign App JWT: {exc}") from exc
+
+    resp = httpx.post(
+        f"{_API}/app/installations/{installation_id}/access_tokens",
+        headers={"Authorization": f"Bearer {jwt}", "Accept": "application/vnd.github+json"},
+        json=scoped_token_request(repo_full_name, kind),
+        timeout=30.0,
+    )
+    if resp.status_code >= 300:
+        raise WebhookError("installation_token_failed", f"installation token: {resp.status_code} {resp.text[:200]}")
+    token = resp.json().get("token")
+    if not token:
+        raise WebhookError("installation_token_missing", "GitHub returned no installation token.")
+    return str(token)
+
+
+def check_run_payload(name: str, head_sha: str, *, status: str, conclusion: str | None, summary: str) -> dict[str, Any]:
+    """Pure builder for a Check Run create/update body (queued -> in_progress -> completed)."""
+    body: dict[str, Any] = {"name": name, "head_sha": head_sha, "status": status,
+                            "output": {"title": name, "summary": summary}}
+    if status == "completed":
+        body["conclusion"] = conclusion or "neutral"
+    return body
+
+
+def create_check_run(repo_full_name: str, token: str, *, name: str, head_sha: str, summary: str) -> int | None:
+    """Create an in_progress Check Run so status shows in the PR UI. Returns its id (or None)."""
+    try:
+        import httpx
+    except Exception:  # noqa: BLE001
+        return None
+    resp = httpx.post(
+        f"{_API}/repos/{repo_full_name}/check-runs",
+        headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"},
+        json=check_run_payload(name, head_sha, status="in_progress", conclusion=None, summary=summary),
+        timeout=30.0,
+    )
+    if resp.status_code >= 300:
+        return None
+    return resp.json().get("id")
+
+
+def update_check_run(repo_full_name: str, token: str, check_run_id: int, *, conclusion: str, summary: str,
+                     name: str = "codna") -> None:
+    try:
+        import httpx
+    except Exception:  # noqa: BLE001
+        return
+    httpx.patch(
+        f"{_API}/repos/{repo_full_name}/check-runs/{check_run_id}",
+        headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"},
+        json=check_run_payload(name, "", status="completed", conclusion=conclusion, summary=summary),
+        timeout=30.0,
+    )
+
+
+def find_open_pr_by_marker(repo_full_name: str, token: str, marker: str, *, max_pages: int = 3) -> str | None:
+    """Return the html_url of an existing PR whose body carries ``marker``, else None.
+
+    Used for idempotency: before a fix job opens a PR, the worker checks whether a prior
+    (possibly crashed-then-recovered) attempt already opened one. Lists PRs newest-first
+    (state=all), so a just-opened PR is found immediately — no search-index lag.
+    """
+    try:
+        import httpx
+    except Exception:  # noqa: BLE001
+        return None
+    headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
+    for page in range(1, max_pages + 1):
+        resp = httpx.get(
+            f"{_API}/repos/{repo_full_name}/pulls",
+            headers=headers,
+            params={"state": "all", "sort": "created", "direction": "desc", "per_page": 100, "page": page},
+            timeout=30.0,
+        )
+        if resp.status_code >= 300:
+            return None
+        items = resp.json()
+        if not items:
+            break
+        for pr in items:
+            if marker in (pr.get("body") or ""):
+                return pr.get("html_url")
+    return None
+
+
+def fetch_code_scanning_sarif(repo_full_name: str, token: str, *, dest_dir: str) -> str:
+    """Download the latest code-scanning analysis SARIF to dest_dir; returns the path."""
+    try:
+        import httpx
+    except Exception as exc:  # noqa: BLE001
+        raise WebhookError("sarif_fetch_unavailable", f"SARIF fetch needs httpx: {exc}") from exc
+    headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
+    listing = httpx.get(
+        f"{_API}/repos/{repo_full_name}/code-scanning/analyses",
+        headers=headers, params={"per_page": 1}, timeout=30.0,
+    )
+    if listing.status_code >= 300:
+        raise WebhookError("code_scanning_list_failed", f"list analyses: {listing.status_code} {listing.text[:200]}")
+    analyses = listing.json()
+    if not analyses:
+        raise WebhookError("no_code_scanning_analysis", f"no code-scanning analysis for {repo_full_name}.")
+    sarif = httpx.get(
+        f"{_API}/repos/{repo_full_name}/code-scanning/analyses/{analyses[0]['id']}",
+        headers={**headers, "Accept": "application/sarif+json"}, timeout=60.0,
+    )
+    if sarif.status_code >= 300:
+        raise WebhookError("code_scanning_sarif_failed", f"fetch SARIF: {sarif.status_code} {sarif.text[:200]}")
+    path = os.path.join(dest_dir, "code-scanning.sarif")
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(sarif.text)
+    return path