gowalk-cicd 1.0.0

package/action/scripts/auto_detect.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""
+Xcode project / scheme / bundle_id auto-detection.
+
+Ported from gowalk-step/fastlane_standalone.sh — keeps us in Python (our
+ecosystem) while still shelling out to ``xcodebuild`` for the two queries
+only it can reliably answer:
+
+    ``xcodebuild -list -json``                  -> enumerate schemes
+    ``xcodebuild -showBuildSettings -json``     -> PRODUCT_TYPE + bundle id
+
+The detection lets ``ci.config.yaml`` become entirely optional: with just
+``creds/AuthKey_*.p8`` + the 18-line ``deploy.yml`` the pipeline can still
+figure out what to build.
+
+Rules (kept intentionally boring — if auto-detect is ambiguous we log a
+warning and return a deterministic choice, falling back to a clear
+``::error::`` only when truly nothing works):
+
+1. ``auto_detect_project(workspace)``
+   - Prefer a single ``*.xcworkspace`` at the repo root.
+   - Else a single ``*.xcodeproj``.
+   - When multiple ``.xcodeproj`` exist, prefer one matching the repo
+     basename, else alphabetically first (with a warning).
+
+2. ``auto_detect_scheme(workspace, project, workspace_file)``
+   - ``xcodebuild -list -json`` to enumerate schemes.
+   - For each scheme, ``-showBuildSettings -json`` and keep those whose
+     ``PRODUCT_TYPE == com.apple.product-type.application``.
+   - Single application scheme -> that one. Multiple: prefer repo-basename
+     match, else alphabetical first.
+
+3. ``auto_detect_bundle_id(workspace, project, workspace_file, scheme, configuration)``
+   - Read ``PRODUCT_BUNDLE_IDENTIFIER`` from the same ``-showBuildSettings``
+     invocation (cached from step 2 when possible).
+   - Reject unresolved variable references like ``$(PRODUCT_NAME)``.
+
+All xcodebuild invocations are cached per-process so repeated calls in the
+same ``read_config.py`` run don't re-shell.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from cfg_io import log, notice
+
+
+APP_PRODUCT_TYPE = "com.apple.product-type.application"
+# Timeouts (seconds) — xcodebuild can hang on missing toolchains or
+# package resolution. CI should fail fast rather than spin forever.
+LIST_TIMEOUT = 60
+SETTINGS_TIMEOUT = 120
+
+# Process-local caches keyed by (project, workspace_file) or
+# (project, workspace_file, scheme, configuration). Cleared between test
+# cases via ``_clear_caches`` but otherwise persist for the lifetime of
+# the read_config.py process.
+_list_cache: dict[tuple, Optional[list[str]]] = {}
+_settings_cache: dict[tuple, Optional[dict]] = {}
+
+
+def _clear_caches() -> None:
+    """Reset caches — used by tests. Not part of the public API."""
+    _list_cache.clear()
+    _settings_cache.clear()
+
+
+def _find_xcodegen_spec(workspace: Path) -> Path | None:
+    """Locate an xcodegen spec file (project.yml / Project.yml / project.yaml).
+
+    xcodegen accepts any of these names. We check them in this order. Case
+    mismatch on case-sensitive filesystems has bitten us before.
+    """
+    for candidate in ("project.yml", "project.yaml", "Project.yml", "Project.yaml"):
+        path = workspace / candidate
+        if path.is_file():
+            return path
+    return None
+
+
+def auto_detect_project(workspace: Path) -> tuple[str, str]:
+    """Discover the repo-root Xcode project / workspace.
+
+    Returns ``(project, workspace_file)`` where exactly one is a non-empty
+    filename. ``("", "")`` means nothing was found.
+
+    If no ``.xcworkspace``/``.xcodeproj`` is present but a ``project.yml``
+    exists (xcodegen spec), we invoke ``xcodegen generate`` once to
+    materialize the ``.xcodeproj`` and retry. xcodegen-based projects
+    commonly gitignore the generated ``.xcodeproj``, so the runner sees
+    only the spec.
+    """
+    log(f"auto-detect: scanning workspace={workspace}")
+    workspaces = sorted(workspace.glob("*.xcworkspace"))
+    if workspaces:
+        picked = _pick_by_basename(workspaces, workspace, "xcworkspace")
+        log(f"auto-detect: workspace={picked.name}")
+        return "", picked.name
+
+    projects = sorted(workspace.glob("*.xcodeproj"))
+    if not projects:
+        spec = _find_xcodegen_spec(workspace)
+        if spec is not None:
+            log(f"auto-detect: xcodegen spec found at {spec.name}")
+            if _run_xcodegen(workspace):
+                projects = sorted(workspace.glob("*.xcodeproj"))
+        else:
+            # Surface what we DID see so CI logs are actionable when the
+            # expected spec file is missing / misnamed / gitignored.
+            entries = sorted(p.name for p in workspace.iterdir() if not p.name.startswith("."))
+            log(
+                f"auto-detect: no .xcodeproj / .xcworkspace / project.yml at "
+                f"{workspace}; root entries={entries[:20]}"
+            )
+
+    if not projects:
+        return "", ""
+    picked = _pick_by_basename(projects, workspace, "xcodeproj")
+    log(f"auto-detect: project={picked.name}")
+    return picked.name, ""
+
+
+def _run_xcodegen(workspace: Path) -> bool:
+    """Run ``xcodegen generate`` in ``workspace``. Returns True on success.
+
+    Logs a notice on failure but never raises — the caller will see an
+    empty project/workspace result and the normal ``::error::`` path
+    will guide the user.
+    """
+    log("auto-detect: no .xcodeproj/.xcworkspace found, xcodegen spec present — running xcodegen")
+    try:
+        result = subprocess.run(
+            ["xcodegen", "generate"],
+            cwd=str(workspace),
+            capture_output=True,
+            text=True,
+            timeout=LIST_TIMEOUT,
+        )
+    except FileNotFoundError:
+        notice(
+            "xcodegen not on PATH — installing via Homebrew (one-shot). "
+            "If this fails, pre-install xcodegen or commit the generated .xcodeproj."
+        )
+        if not _install_xcodegen():
+            return False
+        try:
+            result = subprocess.run(
+                ["xcodegen", "generate"],
+                cwd=str(workspace),
+                capture_output=True,
+                text=True,
+                timeout=LIST_TIMEOUT,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            notice(f"xcodegen still unavailable after install: {exc!r}")
+            return False
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        notice(
+            f"xcodegen not available or timed out ({exc!r}); "
+            "install xcodegen or commit the generated .xcodeproj."
+        )
+        return False
+
+    if result.returncode != 0:
+        notice(
+            f"xcodegen generate failed (rc={result.returncode}): "
+            f"{result.stderr.strip() or result.stdout.strip()}"
+        )
+        return False
+
+    log("auto-detect: xcodegen generate succeeded")
+    return True
+
+
+def _install_xcodegen() -> bool:
+    """Install xcodegen via Homebrew. Returns True on success.
+
+    Called only when `xcodegen` is missing from PATH. macOS GitHub runners
+    normally preinstall it, but when they don't we need a self-bootstrap
+    path — otherwise the entire action fails at auto-detect for
+    xcodegen-based projects with no actionable error.
+    """
+    try:
+        result = subprocess.run(
+            ["brew", "install", "xcodegen"],
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        notice(f"brew install xcodegen failed: {exc!r}")
+        return False
+
+    if result.returncode != 0:
+        notice(
+            f"brew install xcodegen failed (rc={result.returncode}): "
+            f"{result.stderr.strip() or result.stdout.strip()}"
+        )
+        return False
+
+    log("auto-detect: xcodegen installed via Homebrew")
+    return True
+
+
+def _pick_by_basename(matches: list[Path], workspace: Path, label: str) -> Path:
+    """Pick the match whose name stem equals the repo basename, else first."""
+    if len(matches) == 1:
+        return matches[0]
+    repo_base = workspace.resolve().name.lower()
+    for match in matches:
+        if match.stem.lower() == repo_base:
+            return match
+    notice(
+        f"multiple *.{label} found; picking {matches[0].name} alphabetically. "
+        f"Set xcode.project in ci.config.yaml to disambiguate."
+    )
+    return matches[0]
+
+
+def _list_schemes(
+    workspace: Path, project: str, workspace_file: str
+) -> Optional[list[str]]:
+    """Run ``xcodebuild -list -json`` and return the schemes list (cached)."""
+    key = (project, workspace_file)
+    if key in _list_cache:
+        return _list_cache[key]
+
+    cmd = ["xcodebuild", "-list", "-json"]
+    if workspace_file:
+        cmd += ["-workspace", workspace_file]
+    elif project:
+        cmd += ["-project", project]
+    else:
+        _list_cache[key] = None
+        return None
+
+    try:
+        result = subprocess.run(
+            cmd, cwd=str(workspace), capture_output=True, text=True,
+            timeout=LIST_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        log(f"auto-detect: xcodebuild -list failed: {exc!r}")
+        _list_cache[key] = None
+        return None
+
+    if result.returncode != 0:
+        log(
+            f"auto-detect: xcodebuild -list returned {result.returncode}: "
+            f"{result.stderr.strip()}"
+        )
+        _list_cache[key] = None
+        return None
+
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        log(f"auto-detect: xcodebuild -list produced invalid JSON: {exc!r}")
+        _list_cache[key] = None
+        return None
+
+    # Workspace output has {"workspace": {"schemes": [...]}}; project has
+    # {"project": {"schemes": [...]}}.
+    container = data.get("workspace") or data.get("project") or {}
+    schemes = container.get("schemes") or []
+    _list_cache[key] = list(schemes)
+    return _list_cache[key]
+
+
+def _show_build_settings(
+    workspace: Path,
+    project: str,
+    workspace_file: str,
+    scheme: str,
+    configuration: str,
+) -> Optional[dict]:
+    """Run ``xcodebuild -showBuildSettings -json`` and return buildSettings (cached)."""
+    key = (project, workspace_file, scheme, configuration or "Release")
+    if key in _settings_cache:
+        return _settings_cache[key]
+
+    cmd = ["xcodebuild", "-showBuildSettings", "-json", "-scheme", scheme]
+    if configuration:
+        cmd += ["-configuration", configuration]
+    if workspace_file:
+        cmd += ["-workspace", workspace_file]
+    elif project:
+        cmd += ["-project", project]
+    else:
+        _settings_cache[key] = None
+        return None
+
+    try:
+        result = subprocess.run(
+            cmd, cwd=str(workspace), capture_output=True, text=True,
+            timeout=SETTINGS_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        log(f"auto-detect: showBuildSettings({scheme!r}) failed: {exc!r}")
+        _settings_cache[key] = None
+        return None
+
+    if result.returncode != 0:
+        log(
+            f"auto-detect: showBuildSettings({scheme!r}) returned "
+            f"{result.returncode}: {result.stderr.strip()}"
+        )
+        _settings_cache[key] = None
+        return None
+
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        log(f"auto-detect: showBuildSettings({scheme!r}) invalid JSON: {exc!r}")
+        _settings_cache[key] = None
+        return None
+
+    if not isinstance(data, list) or not data:
+        _settings_cache[key] = None
+        return None
+    settings = data[0].get("buildSettings") or {}
+    _settings_cache[key] = settings if isinstance(settings, dict) else None
+    return _settings_cache[key]
+
+
+def auto_detect_scheme(
+    workspace: Path, project: str, workspace_file: str
+) -> Optional[str]:
+    """Pick the single ``com.apple.product-type.application`` scheme."""
+    schemes = _list_schemes(workspace, project, workspace_file)
+    if not schemes:
+        return None
+
+    app_schemes: list[str] = []
+    for scheme in schemes:
+        settings = _show_build_settings(
+            workspace, project, workspace_file, scheme, "Release",
+        )
+        if not settings:
+            continue
+        if settings.get("PRODUCT_TYPE") == APP_PRODUCT_TYPE:
+            app_schemes.append(scheme)
+
+    if not app_schemes:
+        return None
+    if len(app_schemes) == 1:
+        log(f"auto-detect: scheme={app_schemes[0]}")
+        return app_schemes[0]
+
+    repo_base = workspace.resolve().name.lower()
+    for scheme in app_schemes:
+        if scheme.lower() == repo_base:
+            log(f"auto-detect: scheme={scheme} (basename match)")
+            return scheme
+
+    picked = sorted(app_schemes)[0]
+    notice(
+        f"multiple application schemes found ({', '.join(sorted(app_schemes))}); "
+        f"picking {picked} alphabetically. Set xcode.scheme in ci.config.yaml "
+        f"to disambiguate."
+    )
+    return picked
+
+
+def auto_detect_bundle_id(
+    workspace: Path,
+    project: str,
+    workspace_file: str,
+    scheme: str,
+    configuration: str,
+) -> Optional[str]:
+    """Extract ``PRODUCT_BUNDLE_IDENTIFIER`` for the given scheme/config."""
+    settings = _show_build_settings(
+        workspace, project, workspace_file, scheme, configuration or "Release",
+    )
+    if not settings:
+        return None
+    bundle = settings.get("PRODUCT_BUNDLE_IDENTIFIER")
+    if not bundle or not isinstance(bundle, str):
+        return None
+    # xcodebuild sometimes emits unresolved variable references when build
+    # settings depend on xcconfig files that aren't in the default context.
+    if "$(" in bundle or bundle.startswith("$") or "=" in bundle:
+        log(f"auto-detect: bundle_id {bundle!r} contains unresolved variable — rejecting")
+        return None
+    log(f"auto-detect: bundle_id={bundle}")
+    return bundle

package/action/scripts/autoupdate_check.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Checks npm for newer gowalk-cicd, re-vendors via npx if newer.
+# Stages refreshed files for commit. Exits 0 on no-op or non-fatal failure.
+#
+# DESIGN DECISION (intentional, not a bug):
+# This script runs `npx --yes gowalk-cicd@<latest>` on every default-
+# branch CI run with `permissions: contents: write`. That means the consumer
+# repo trusts whatever code gowalk-cicd publishes to npm.
+#
+# Trust model — internally consistent with the rest of the action:
+#   - Consumers initially install via the same `npx --yes gowalk-cicd`
+#     command. They've already accepted the trust relationship.
+#   - The package is published from gowalk-cicd via a dedicated GitHub Actions
+#     workflow using npm Trusted Publishing (OIDC after initial bootstrap).
+#     Compromise of that release workflow would already be catastrophic
+#     regardless of this autoupdate path.
+#   - We pin to the exact version returned by `npm view` immediately above
+#     (`@$latest`) so the small TOCTOU window between view and exec can't
+#     swap a different version.
+#   - Consumers who want to pin can set `with: { auto-update: 'false' }` in
+#     their workflow.
+#
+# Hardening considered, not adopted:
+#   - `npm audit signatures` provenance check: requires npm to have published
+#     with --provenance, which the gowalk-cicd publish workflow does not currently
+#     emit. Worth revisiting if/when gowalk-cicd enables provenance.
+#   - Pinning to a fixed hash: defeats the autoupdate purpose.
+#   - Out-of-band verification (signed manifest): overkill for the threat
+#     model described above.
+set -euo pipefail
+
+VERSION_FILE=".github/actions/swift-app/.daemux-version"
+PKG="gowalk-cicd"
+
+current=""
+if [[ -f "$VERSION_FILE" ]]; then
+  current="$(tr -d '[:space:]' < "$VERSION_FILE")"
+fi
+
+if ! latest="$(npm view "$PKG" version 2>/dev/null)"; then
+  echo "::warning::autoupdate: failed to query npm for $PKG"
+  exit 0
+fi
+latest="$(printf '%s' "$latest" | tr -d '[:space:]')"
+
+if [[ -z "$latest" ]]; then
+  echo "::warning::autoupdate: empty version returned for $PKG"
+  exit 0
+fi
+
+if [[ "$current" == "$latest" ]]; then
+  echo "autoupdate: $PKG already at $latest"
+  exit 0
+fi
+
+echo "autoupdate: $PKG $current -> $latest; re-vendoring"
+
+if ! npx --yes "$PKG@$latest"; then
+  echo "::warning::autoupdate: npx $PKG@$latest failed"
+  exit 0
+fi
+
+git config user.name  >/dev/null 2>&1 || git config user.name  "github-actions[bot]"
+git config user.email >/dev/null 2>&1 || \
+  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+# NOTE: We deliberately do NOT stage .github/workflows/deploy.yml here.
+# GITHUB_TOKEN cannot push workflow-file changes regardless of
+# `permissions: contents: write` (GH security policy: prevents CI from
+# modifying its own triggers). Consumer-side deploy.yml updates require
+# manual `npx --yes gowalk-cicd` by the user. Document this in
+# the action README and changelog when shipping a deploy.yml schema change.
+
+# Stage everything under the vendored action dir EXCEPT Python bytecode
+# caches. The action's own scripts run during this CI job and Python
+# generates `__pycache__/*.pyc` files inside scripts/ as a side effect of
+# importing them. Those caches are build artifacts of *this* run, not part
+# of the action distribution -- sweeping them into the autoupdate bot
+# commit is benign but noisy (every clean run emits a "refresh
+# __pycache__" diff).
+#
+# DESIGN DECISION: use `git add -A` (stages additions, modifications, AND
+# deletions) instead of the previous `git ls-files -mo` flow. `ls-files
+# -mo` enumerates modified + other (untracked) paths but NOT deletions:
+# when an autoupdate cycle removes a script (e.g. `prepare_signing.py`
+# gets renamed to `prepare_signing_v2.py` in a new release), the old
+# file would stay tracked in the consumer repo forever -- the bot
+# commit would add the new file but never remove the orphan. `git add
+# -A` handles all three change kinds in one call. We then unstage any
+# pycache paths that the broad `-A` swept in.
+#
+# Force flag (`-f`) is implicit in `git add -A` for explicitly listed
+# pathspecs that match .gitignore patterns? No -- `-A` still honors
+# .gitignore for untracked files. To preserve the prior semantics
+# (consumer's .gitignore must not silently drop autoupdate-managed
+# files like `.daemux-version`), we pass `--force` explicitly.
+#
+# BSD xargs (default on macos-15 runners) does NOT support
+# `-r`/`--no-run-if-empty`, so we capture pycache paths into a variable
+# and skip the xargs call when empty -- portable across BSD and GNU.
+git add -A --force -- \
+  .github/actions/swift-app/ \
+  .github/actions/android-app/ 2>/dev/null || true
+
+# Unstage Python bytecode that the broad `-A` swept in. `git diff
+# --cached --name-only` lists every staged path; we filter to pycache
+# entries and `git reset HEAD --` to drop them from the index. Working
+# tree is left untouched (the .pyc files remain on disk; only their
+# index entries are removed).
+pycache="$(git diff --cached --name-only -- \
+  .github/actions/swift-app/ .github/actions/android-app/ \
+  | grep -E '(/__pycache__/|\.pyc$)' || true)"
+if [[ -n "$pycache" ]]; then
+  printf '%s\n' "$pycache" \
+    | tr '\n' '\0' \
+    | xargs -0 git reset HEAD -- 2>/dev/null || true
+fi
+echo "autoupdate: staged refreshed iOS + Android actions (deploy.yml not staged; __pycache__ excluded)"

package/action/scripts/cert_factory.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Cert-creation primitives for the iOS native TestFlight action.
+
+Owns the cryptographic legwork (RSA key + CSR), Apple's per-team cert
+cap rotation (revoke OLDEST on 409), and PKCS12 serialisation. Split
+from ``prepare_signing.py`` so the orchestrator there stays focused on
+the load-or-regen control flow and the file count stays under the
+project's per-file limits.
+
+Nothing here touches the on-disk cache — callers receive raw bytes and
+hand them to ``creds_store`` for atomic persistence.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+
+from asc_common import get_json, request
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.serialization import pkcs12
+from cryptography.x509.oid import NameOID
+
+# Apple's cert revoke -> create pipeline is eventually consistent: a
+# DELETE on the per-team cap-blocking cert sometimes still shows up as
+# "active" to a follow-up POST for a second or two, returning a fresh
+# 409 even though we just freed a slot. Sleep then retry-with-backoff
+# rather than failing the whole CI run on a known-transient race.
+CERT_REVOKE_PROPAGATION_DELAY_SEC = float(
+    os.getenv("CERT_REVOKE_PROPAGATION_DELAY_SEC", "2.0")
+)
+CERT_POST_RETRIES_AFTER_REVOKE = int(
+    os.getenv("CERT_POST_RETRIES_AFTER_REVOKE", "2")
+)
+
+
+def generate_key_and_csr() -> tuple[rsa.RSAPrivateKey, bytes]:
+    """Generate a fresh 2048-bit RSA key + PEM CSR (base64 body only).
+
+    Returns the private key (kept in memory; the caller serialises it
+    into the PKCS12) and the CSR with PEM headers stripped, ready for
+    Apple's ``csrContent`` field.
+    """
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    csr = (
+        x509.CertificateSigningRequestBuilder()
+        .subject_name(
+            x509.Name(
+                [
+                    x509.NameAttribute(NameOID.COMMON_NAME, "Daemux CI"),
+                    x509.NameAttribute(NameOID.COUNTRY_NAME, "US"),
+                ]
+            )
+        )
+        .sign(private_key, hashes.SHA256())
+    )
+    csr_pem = csr.public_bytes(serialization.Encoding.PEM)
+    csr_payload = b"".join(
+        line for line in csr_pem.splitlines() if not line.startswith(b"-----")
+    )
+    return private_key, csr_payload
+
+
+def oldest_distribution_cert_id(token: str) -> str | None:
+    """Return the DISTRIBUTION cert with the EARLIEST expirationDate.
+
+    Apple caps each team at 2 distribution certs; when CI hits the cap
+    we must revoke one. Picking the OLDEST is the safest choice — the
+    NEWEST cert signed the most recent build that may still be in ASC
+    processing, and revoking that mid-processing produces ITMS-90035
+    ("signed with an ad-hoc certificate, not a distribution
+    certificate") on the prior run. Older certs have long since cleared
+    processing.
+    """
+    data = get_json(
+        "/certificates",
+        token,
+        params={
+            "limit": "200",
+            "sort": "-id",
+            "filter[certificateType]": "DISTRIBUTION",
+        },
+    )
+    oldest_id = None
+    oldest_exp: str | None = None
+    for cert in data.get("data", []):
+        attrs = cert.get("attributes") or {}
+        exp = attrs.get("expirationDate") or ""
+        if not exp:
+            continue
+        if oldest_exp is None or exp < oldest_exp:
+            oldest_exp = exp
+            oldest_id = cert["id"]
+    return oldest_id
+
+
+def _post_with_revoke_backoff(token: str, body: dict):
+    """POST a cert create after a revoke, tolerating ASC propagation lag.
+
+    Apple's DELETE -> POST pipeline is eventually consistent: a freshly
+    revoked cert may still count against the per-team cap for a brief
+    window, producing a spurious 409 on the immediate re-POST. Sleep
+    once for ``CERT_REVOKE_PROPAGATION_DELAY_SEC`` then retry up to
+    ``CERT_POST_RETRIES_AFTER_REVOKE`` times with exponential backoff.
+    The final attempt drops ``allow_status`` so a real 409 surfaces as
+    Apple's full body via ``request``'s SystemExit.
+    """
+    time.sleep(CERT_REVOKE_PROPAGATION_DELAY_SEC)
+    delay = CERT_REVOKE_PROPAGATION_DELAY_SEC
+    for attempt in range(CERT_POST_RETRIES_AFTER_REVOKE):
+        resp = request(
+            "POST", "/certificates", token, json_body=body, allow_status={409}
+        )
+        if resp.status_code != 409:
+            return resp
+        print(
+            f"Post-revoke 409 on attempt {attempt + 1}/"
+            f"{CERT_POST_RETRIES_AFTER_REVOKE}; "
+            f"sleeping {delay}s before final retry"
+        )
+        time.sleep(delay)
+        delay *= 2
+    # Final attempt without allow_status — let Apple's body surface via
+    # request()'s SystemExit if the cap is genuinely still hit.
+    return request("POST", "/certificates", token, json_body=body)
+
+
+def create_distribution_cert(token: str, csr_b64: str) -> tuple[str, bytes]:
+    """POST a CSR to ASC; return ``(cert_id, cert_der)``.
+
+    On 409 (per-team cap of 2 hit) revoke the OLDEST existing cert
+    (see :func:`oldest_distribution_cert_id` for why) and retry with
+    backoff to absorb Apple's revoke -> create propagation lag (see
+    :func:`_post_with_revoke_backoff`).
+    """
+    body = {
+        "data": {
+            "type": "certificates",
+            "attributes": {
+                "csrContent": csr_b64,
+                "certificateType": "DISTRIBUTION",
+            },
+        }
+    }
+    resp = request(
+        "POST", "/certificates", token, json_body=body, allow_status={409}
+    )
+    if resp.status_code == 409:
+        # Revoke the OLDEST cert, NOT the newest. The newest cert signed
+        # the previous build that may still be in ASC processing — revoking
+        # it during processing yields ITMS-90035 on the prior build.
+        # See oldest_distribution_cert_id() for the full rationale.
+        print("Distribution cert cap hit; revoking oldest existing cert")
+        target = oldest_distribution_cert_id(token)
+        if not target:
+            raise SystemExit(
+                "409 from cert create but no existing DISTRIBUTION cert "
+                "found to revoke"
+            )
+        request("DELETE", f"/certificates/{target}", token)
+        resp = _post_with_revoke_backoff(token, body)
+    data = resp.json()["data"]
+    cert_id = data["id"]
+    cert_der = base64.b64decode(data["attributes"]["certificateContent"])
+    print(f"Created DISTRIBUTION cert {cert_id}")
+    return cert_id, cert_der
+
+
+def serialize_p12(
+    private_key: rsa.RSAPrivateKey, cert_der: bytes, passwd: str
+) -> bytes:
+    """Return the PKCS12 bytes encrypted with ``passwd``.
+
+    Caller decides whether to write to disk via the cache layer or as a
+    transient artifact in ``$RUNNER_TEMP``.
+    """
+    cert = x509.load_der_x509_certificate(cert_der)
+    return pkcs12.serialize_key_and_certificates(
+        name=b"Daemux CI",
+        key=private_key,
+        cert=cert,
+        cas=None,
+        encryption_algorithm=serialization.BestAvailableEncryption(
+            passwd.encode()
+        ),
+    )