"""Verify a Gitea release and its exact uploaded descriptor through gitea-api.""" from __future__ import annotations import base64 import hashlib import json import os import re import resource import signal import stat import subprocess import tempfile import zipfile from pathlib import Path, PurePosixPath from urllib.parse import urlencode from release_handoff import descriptor_request, latest_main_sha, validate_source from validate_release import read_json, unique_object, validate_manifest REPOSITORY = "admin/akyldash" RELEASE_WORKFLOW = ".gitea/workflows/release-images.yaml" CI_WORKFLOW = ".gitea/workflows/ci.yaml" MAX_DESCRIPTOR_BYTES = 1024 * 1024 MAX_API_RESPONSE_BYTES = 1024 * 1024 MAX_API_DOWNLOAD_BYTES = 10 * 1024 * 1024 MAX_CANDIDATE_RELEASE_RUNS = 10 API_TIMEOUT_SECONDS = 15 RUNTIME_FILES = ( "deploy/production/compose.yaml", "deploy/production/Caddyfile", "infra/deploy/release-policy.json", ) MAX_RUNTIME_FILE_BYTES = 256 * 1024 def run_api_helper(command: list[str], *, env: dict | None, timeout: int, max_stdout_bytes: int, max_file_bytes: int) -> bytes: def limit_files() -> None: _soft, hard = resource.getrlimit(resource.RLIMIT_FSIZE) limit = max_file_bytes + 1 if hard == resource.RLIM_INFINITY else min(max_file_bytes + 1, hard) resource.setrlimit(resource.RLIMIT_FSIZE, (limit, hard)) with tempfile.TemporaryFile() as output: process = subprocess.Popen( command, stdout=output, stderr=subprocess.DEVNULL, env=env, start_new_session=True, preexec_fn=limit_files, ) try: return_code = process.wait(timeout=timeout) except subprocess.TimeoutExpired as error: try: os.killpg(process.pid, signal.SIGTERM) except ProcessLookupError: pass try: process.wait(timeout=2) except subprocess.TimeoutExpired: pass try: os.killpg(process.pid, signal.SIGKILL) except ProcessLookupError: pass process.wait() raise ValueError("Gitea helper request timed out") from error if return_code: raise ValueError("Gitea helper request failed") output.seek(0, os.SEEK_END) if output.tell() > max_stdout_bytes: raise ValueError("Gitea helper response exceeds its size limit") output.seek(0) return output.read(max_stdout_bytes + 1) def api_json(path: str, *, helper: str = "gitea-api", env: dict | None = None) -> dict: try: response = run_api_helper( [helper, "GET", path], env=env, timeout=API_TIMEOUT_SECONDS, max_stdout_bytes=MAX_API_RESPONSE_BYTES, max_file_bytes=MAX_API_RESPONSE_BYTES, ) except (OSError, subprocess.SubprocessError) as error: raise ValueError("Gitea API request failed") from error if len(response) > MAX_API_RESPONSE_BYTES: raise ValueError("Gitea helper response exceeds its size limit") try: value = json.loads(response.decode("utf-8"), object_pairs_hook=unique_object) except (UnicodeError, json.JSONDecodeError) as error: raise ValueError("Gitea API response is invalid JSON") from error if not isinstance(value, dict): raise ValueError("Gitea API returned a non-object response") return value def repository_file(path: str, commit: str, *, api=api_json) -> bytes: """Fetch one small, pinned repository file and verify Gitea's git blob identity.""" if not re.fullmatch(r"[0-9a-f]{40}", commit) or path not in RUNTIME_FILES: raise ValueError("runtime file request is not allowlisted or commit-pinned") query = urlencode({"ref": commit}) value = api(f"/repos/{REPOSITORY}/contents/{path}?{query}") if (value.get("type") != "file" or value.get("path") != path or value.get("encoding") != "base64"): raise ValueError("Gitea runtime file metadata is invalid") encoded, blob_sha, size = value.get("content"), value.get("sha"), value.get("size") if (not isinstance(encoded, str) or not isinstance(blob_sha, str) or not re.fullmatch(r"[0-9a-f]{40}", blob_sha) or isinstance(size, bool) or not isinstance(size, int) or size < 0 or size > MAX_RUNTIME_FILE_BYTES): raise ValueError("Gitea runtime file exceeds its limit or has invalid metadata") try: content = base64.b64decode(encoded, validate=True) except (ValueError, base64.binascii.Error) as error: raise ValueError("Gitea runtime file content is invalid base64") from error git_blob_sha = hashlib.sha1(b"blob " + str(len(content)).encode("ascii") + b"\0" + content).hexdigest() if len(content) != size or git_blob_sha != blob_sha: raise ValueError("Gitea runtime file content does not match its pinned git blob") return content def runtime_compatibility_reason(commit: str, *, checkout: Path, policy_file: Path, api=api_json) -> str | None: """Require the bootstrap host's fixed runtime/configuration to match target source.""" for relative in RUNTIME_FILES: local_path = policy_file if relative == "infra/deploy/release-policy.json" else checkout / relative try: info = local_path.lstat() if not stat.S_ISREG(info.st_mode): raise ValueError(f"protected runtime file is not a regular file: {relative}") local_content = local_path.read_bytes() except OSError as error: raise ValueError(f"protected runtime file is unavailable: {relative}") from error remote_content = repository_file(relative, commit, api=api) if local_content != remote_content: return "release_policy_changed" if relative.endswith("release-policy.json") else "runtime_config_changed" return None def require_runtime_compatibility(commit: str, *, checkout: Path, policy_file: Path, api=api_json) -> None: reason = runtime_compatibility_reason( commit, checkout=checkout, policy_file=policy_file, api=api, ) if reason is not None: raise ValueError(f"host {reason.replace('_', ' ')}; reviewed bootstrap update is required") def latest_release_request(*, current_main: str, api=api_json, checkout: Path | None = None) -> dict | None: if not re.fullmatch(r"[0-9a-f]{40}", current_main): raise ValueError("current main commit is invalid") query = urlencode({ "event": "workflow_run", "branch": "main", "status": "success", "head_sha": current_main, "page": 1, "limit": MAX_CANDIDATE_RELEASE_RUNS, }) runs_response = api( f"/repos/{REPOSITORY}/actions/workflows/{Path(RELEASE_WORKFLOW).name}/runs?{query}" ) runs = runs_response.get("workflow_runs") total = runs_response.get("total_count") if type(total) is not int or total < 0 or not isinstance(runs, list): raise ValueError("Gitea release-run listing is invalid") if total > MAX_CANDIDATE_RELEASE_RUNS or len(runs) != total: raise ValueError("Gitea release-run listing is incomplete") if not runs: return None run_ids = [] for run in runs: if not isinstance(run, dict): raise ValueError("Gitea release-run listing contains an invalid entry") run_id = run.get("id") if (isinstance(run_id, bool) or not isinstance(run_id, (int, str)) or not str(run_id).isdigit() or len(str(run_id)) > 20): raise ValueError("Gitea release-run listing contains an invalid run ID") head_sha = run.get("head_sha") if head_sha is not None and head_sha != current_main: raise ValueError("Gitea release-run listing does not match current main") run_ids.append(str(run_id)) run_id = max(run_ids, key=int) verify_run(run_id, stage="handoff", commit=current_main, api=api, current_main=current_main, checkout=checkout) metadata = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}/artifacts") return descriptor_request(metadata, run_id=run_id, head_sha=current_main) def ensure_private_scratch(path: Path) -> None: path.mkdir(mode=0o700, parents=True, exist_ok=True) if path.is_symlink() or path.stat().st_uid != 0 or path.stat().st_mode & 0o077: raise ValueError("artifact scratch directory must be a private root-owned directory") def verify_run(run_id: str, *, stage: str, commit: str, api=api_json, current_main: str | None = None, checkout: Path | None = None) -> dict: if not run_id.isdigit() or not re.fullmatch(r"[0-9a-f]{40}", commit): raise ValueError("Gitea run identity is invalid") run = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}") if not isinstance(run, dict) or str(run.get("id")) != run_id: raise ValueError("Gitea returned a different workflow run") if run.get("status") not in {"completed", "success"} or run.get("conclusion") != "success": raise ValueError("workflow run is not successful") workflow_id = run.get("workflow_id") if not isinstance(workflow_id, (int, str)) or not str(workflow_id): raise ValueError("workflow run has no workflow identity") workflow = api(f"/repos/{REPOSITORY}/actions/workflows/{workflow_id}") expected_workflow, path, event = ( ("CI", CI_WORKFLOW, "push") if stage == "ci" else ("Release production images", RELEASE_WORKFLOW, "workflow_run") ) if (workflow.get("name") != expected_workflow or workflow.get("path") != path or str(workflow.get("id")) != str(workflow_id)): raise ValueError("workflow ID does not resolve to the approved workflow name and path") if run.get("name") not in {None, expected_workflow}: raise ValueError("workflow run name is not approved") if run.get("head_sha") != commit: raise ValueError("workflow run commit does not match the release request") branch = run.get("head_branch") if branch != "main" or run.get("event") != event: raise ValueError("workflow run is not the approved main event") validate_source( workflow=expected_workflow, workflow_path=f"{Path(path).name}@refs/heads/main", event=event, conclusion="success", branch=branch, run_id=run_id, head_sha=commit, repository=REPOSITORY, stage="release" if stage == "ci" else "handoff", current_main=current_main or latest_main_sha(checkout), ) return run def validate_artifact_zip(path: Path, *, descriptor_sha256: str, release_run_id: str, ci_run_id: str | None, commit: str, policy: object) -> tuple[dict, bytes]: if not re.fullmatch(r"[0-9a-f]{64}", descriptor_sha256): raise ValueError("requested descriptor digest is invalid") try: with zipfile.ZipFile(path) as archive: members = archive.infolist() names = [member.filename for member in members] expected = {"release-manifest.json", "release-manifest.json.sha256"} if len(names) != 2 or set(names) != expected: raise ValueError("release artifact must contain exactly the manifest and checksum files") payloads = {} for member in members: name = PurePosixPath(member.filename) mode = member.external_attr >> 16 kind = stat.S_IFMT(mode) if (member.is_dir() or name.is_absolute() or len(name.parts) != 1 or name.as_posix() != member.filename or kind not in {0, stat.S_IFREG} or member.file_size > MAX_DESCRIPTOR_BYTES or member.compress_size > MAX_DESCRIPTOR_BYTES): raise ValueError("release artifact contains an unsafe or oversized member") with archive.open(member) as stream: chunks = [] size = 0 while chunk := stream.read(64 * 1024): size += len(chunk) if size > MAX_DESCRIPTOR_BYTES: raise ValueError("release artifact member exceeds its size limit") chunks.append(chunk) if size != member.file_size: raise ValueError("release artifact member size does not match its ZIP metadata") payloads[member.filename] = b"".join(chunks) except (OSError, zipfile.BadZipFile, RuntimeError) as error: raise ValueError(f"release artifact ZIP is invalid: {error}") from error manifest_bytes = payloads["release-manifest.json"] if hashlib.sha256(manifest_bytes).hexdigest() != descriptor_sha256: raise ValueError("release descriptor bytes do not match the requested SHA-256") checksum = payloads["release-manifest.json.sha256"] expected_sidecar = f"{descriptor_sha256} release-manifest.json\n".encode("ascii") if checksum != expected_sidecar: raise ValueError("release descriptor checksum sidecar is invalid") try: manifest = json.loads(manifest_bytes, object_pairs_hook=unique_object) except (UnicodeError, json.JSONDecodeError) as error: raise ValueError("release descriptor JSON is invalid") from error validated = validate_manifest(manifest, policy) if (validated["run_id"] != release_run_id or (ci_run_id is not None and validated["source_run_id"] != ci_run_id) or validated["commit"] != commit): raise ValueError("release descriptor does not bind the verified CI and release runs") return validated, manifest_bytes def fetch_release(request: dict, *, policy: object, helper: str = "gitea-api", temp_dir: Path = Path("/run/akyldash"), env: dict | None = None, api=api_json, current_main: str | None = None, checkout: Path | None = None) -> tuple[dict, bytes]: run_id, commit, descriptor_sha256 = ( request["run_id"], request["commit"], request["descriptor_sha256"] ) current_main = current_main or latest_main_sha(checkout) release_run = verify_run(run_id, stage="handoff", commit=commit, api=api, current_main=current_main, checkout=checkout) metadata = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}/artifacts") tuple_data = descriptor_request(metadata, run_id=run_id, head_sha=commit) if tuple_data["descriptor_sha256"] != descriptor_sha256: raise ValueError("requested descriptor digest does not match the Gitea run artifact") artifact = metadata["artifacts"][0] artifact_id = artifact.get("id") if not isinstance(artifact_id, (int, str)) or not str(artifact_id).isdigit(): raise ValueError("release descriptor artifact has no numeric ID") ensure_private_scratch(temp_dir) from tempfile import TemporaryDirectory with TemporaryDirectory(prefix="akyldash-release-", dir=temp_dir) as scratch: zip_path = Path(scratch) / "artifact.zip" run_api_helper( [helper, "DOWNLOAD", f"/repos/{REPOSITORY}/actions/artifacts/{artifact_id}/zip", str(zip_path)], env=env, timeout=30, max_stdout_bytes=4096, max_file_bytes=MAX_API_DOWNLOAD_BYTES, ) manifest, manifest_bytes = validate_artifact_zip( zip_path, descriptor_sha256=tuple_data["descriptor_sha256"], release_run_id=run_id, ci_run_id=None, commit=commit, policy=policy, ) source_run_id = manifest["source_run_id"] verify_run(source_run_id, stage="ci", commit=commit, api=api, current_main=current_main, checkout=checkout) return manifest, manifest_bytes