mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/devkit/ci_cli.py

@@ -0,0 +1,196 @@
+"""`mobster ci`'s parser and output (ci.py does the work)."""
+
+import json
+import os
+import sys
+import unicodedata
+from pathlib import Path
+
+from . import DevError, main, say, subcommands
+from .ci import HOSTED_HOSTS
+
+MARKS = {"ok": "✓", "warn": "!", "fail": "✗", "skip": "-"}
+
+
+def add_arguments(parser, helpers):
+    add = subcommands(parser, "ci_command")
+    init = add("init", help="write the CI workflow for this repository (GitHub Actions, GitLab CI or a hosted Mac)",
+                           description="Write the workflow that runs `mobster ci run` on every pull request or "
+                                       "merge request: on a Mac of yours as a self-hosted runner, or with --hosted "
+                                       "on a GitHub-hosted macOS runner. --host xcode-cloud, codemagic, bitrise or "
+                                       "circleci writes that service's file, which runs on its hosted Macs.")
+    init.add_argument("--host", choices=("github", "gitlab", *HOSTED_HOSTS),
+                      help="where the repository lives, or the CI service to write for (default: from the origin "
+                           "remote)")
+    init.add_argument("--hosted", action="store_true",
+                      help="run on a GitHub-hosted macOS runner and sign in with a CI token, with no Mac of yours "
+                           "(no iPhone either)")
+    init.add_argument("--device", action="append", metavar="NAME",
+                      help="also test on this iPhone, plugged into the runner; repeatable (the runner must list each "
+                           "in MOBSTER_RUNNER_DEVICES)")
+    init.add_argument("--testflight", action="append", metavar="BUNDLE",
+                      help="with --device: your app's TestFlight build on the phone; repeatable")
+    init.add_argument("--force", action="store_true", help="replace the workflow file if it exists")
+    init.add_argument("--print", dest="print_only", action="store_true",
+                      help="print the workflow instead of writing it")
+
+    doctor = add("doctor", help="check that this Mac is ready to be a CI runner",
+                             description="Check this Mac as a CI runner: Xcode, a simulator runtime, Mobster for "
+                                         "Mac and its plan, system sleep, automatic login, the runner service, "
+                                         "free disk and the phones the runner allows. Reads only.")
+    doctor.add_argument("--json", action="store_true", help="print the rows as JSON")
+    doctor.add_argument("--hosted", action="store_true",
+                        help="check for a hosted runner: skip the rows about keeping a Mac running and check the CI "
+                             "token (automatic inside a hosted job)")
+
+    run = add("run", help="test the PR or MR this job builds; the report goes to .mobster/ci",
+                          description="Run `mobster test pr` for the pull request or merge request this CI job "
+                                      "builds, with a screen recording of each simulator run. The suite's report, "
+                                      "JUnit file, frames, GIFs and videos go to .mobster/ci for the job's "
+                                      "artifacts. Works the same in a terminal.",
+                          epilog="exit codes: 0 passed, 1 failed, 2 needs review, 3 couldn't run\n\n"
+                                 "examples:\n  mobster ci run\n  mobster ci run --device \"Test iPhone\"\n"
+                                 "  mobster ci run --device \"Test iPhone\" --device \"Lab iPhone\" -- --spread\n"
+                                 "  mobster ci run -- --retries 2 --parallel 2")
+    run.add_argument("--base", metavar="REF",
+                     help="the branch the PR merges into (default: the job's target branch, else origin/main)")
+    run.add_argument("--sim", action="append", metavar="TYPE[@RUNTIME]",
+                     help="a simulator device type to run on; repeatable (default: each check's own)")
+    run.add_argument("--device", action="append", metavar="NAME",
+                     help="an iPhone plugged into this Mac; repeatable. In a CI job the runner must list each in "
+                          "MOBSTER_RUNNER_DEVICES, or nothing runs")
+    run.add_argument("--testflight", action="append", metavar="BUNDLE",
+                     help="with --device: your app's TestFlight build on the phone; repeatable")
+    run.add_argument("--no-video", action="store_true", help="don't record the simulator's screen")
+    run.add_argument("extra", nargs="*", metavar="TEST_FLAG",
+                     help="more `mobster test pr` flags, after a --: mobster ci run -- --retries 2")
+
+    comment = add("comment", help="keep one comment on the PR or MR with the verdict and repro steps",
+                              description="Post the verdict in .mobster/ci as one comment on the pull request "
+                                          "(GITHUB_TOKEN) or merge request (MOBSTER_GITLAB_TOKEN), updated in place "
+                                          "on every push: each failure's repro steps, frame, GIF, video and the "
+                                          "command that runs it again. Never fails the job.")
+    comment.add_argument("--artifact-url", metavar="URL",
+                         help="the uploaded report's link (default: $MOBSTER_ARTIFACT_URL, else the job's page)")
+    comment.add_argument("--dry-run", action="store_true", help="print the comment and post nothing")
+
+
+def run(args, *, cwd=None, environ=None):
+    environ = os.environ if environ is None else environ
+    handlers = {"init": _init, "doctor": _doctor, "run": _run, "comment": _comment}
+    return main("ci", handlers, args, cwd=Path(cwd or Path.cwd()), environ=environ)
+
+
+def _phones(args):
+    """(--device, --testflight) as tuples; --testflight goes with --device (a TestFlight build is on an iPhone)."""
+    devices, testflight = tuple(args.device or ()), tuple(args.testflight or ())
+    for flag, value in [*(("--device", name) for name in devices), *(("--testflight", app) for app in testflight)]:
+        # a line break would end the run line of the workflow ci init writes
+        if any(unicodedata.category(char) in ("Cc", "Zl", "Zp") for char in value):
+            raise DevError(f"{flag} {value!r} holds a line break, a tab or another control character, so Mobster did "
+                           "nothing.", "Remove it: no iPhone's name or app's bundle ID has one.")
+    if testflight and not devices:
+        raise DevError("--testflight goes with --device: a TestFlight build is on an iPhone, not a simulator.")
+    return devices, testflight
+
+
+def _init(args, cwd, environ):
+    from . import ci
+    root = ci.repo_root(cwd)
+    host = args.host
+    if host is None:
+        code, url = ci._git(root, "remote", "get-url", "origin")
+        host = ci.remote_host(url) if code == 0 else None
+    devices, testflight = _phones(args)
+    if args.print_only:
+        say(ci.workflow(host, devices=devices, testflight=testflight, hosted=args.hosted)[1], sys.stdout)
+        return 0
+    hosted = args.hosted or host in HOSTED_HOSTS
+    target, notes = ci.init(root, host=host, devices=devices, testflight=testflight, force=args.force,
+                            hosted=args.hosted)
+    if hosted:
+        from . import ci_hosts
+        lines = [f"Wrote {target.relative_to(root)}.", *notes, "", "Next:",
+                 *(f"  {number}. {step}" for number, step in enumerate(ci_hosts.NEXT[host], 1)),
+                 "", "On the runner, `mobster ci doctor` checks this runner before the run."]
+        say("\n".join(lines))
+        return 0
+    github = host == "github"
+    steps = ["On the Mac that runs the checks: mobster ci doctor",
+             ("Register it as a self-hosted runner with the label mobster" if github else
+              "Register it as a GitLab runner (shell executor) with the tag mobster") + f": {ci.DOCS}/ci/mac-runner",
+             f"Add ANTHROPIC_API_KEY as a {'repository secret' if github else 'masked CI/CD variable'}, for checks "
+             "with steps."]
+    if not github:
+        steps.append("Add MOBSTER_GITLAB_TOKEN, a project access token with the api scope, for the MR comment.")
+    if devices:
+        steps.append(f"On the runner, allow the phone{'' if len(devices) == 1 else 's'}: "
+                     f"MOBSTER_RUNNER_DEVICES={','.join(devices)}")
+    steps.append(f"Commit the file and open a {'pull' if github else 'merge'} request.")
+    lines = [f"Wrote {target.relative_to(root)}.", *notes, "", "Next:",
+             *(f"  {number}. {step}" for number, step in enumerate(steps, 1))]
+    if not (root / ".mobster" / "checks").is_dir():
+        lines += ["", "This project has no checks yet. `mobster test pr` drafts one for each screen a PR changes, "
+                      "and `mobster test record` turns a finished task into one."]
+    say("\n".join(lines))
+    return 0
+
+
+def _doctor(args, cwd, environ):
+    from . import ci
+    rows = ci.doctor(environ=environ, hosted=True if args.hosted else None)
+    failed = any(row.status == "fail" for row in rows)
+    if args.json:
+        say(json.dumps({"ok": not failed, "rows": [row.public() for row in rows]}, ensure_ascii=False))
+        return 1 if failed else 0
+    width = max(len(row.name) for row in rows)
+    lines = []
+    for row in rows:
+        lines.append(f"{MARKS[row.status]} {row.name.ljust(width)}  {row.detail}")
+        if row.fix and row.status != "ok":
+            lines.append(f"  {' ' * width}  {row.fix}")
+    if failed:
+        lines += ["", "Fix the rows marked ✗, then run `mobster ci doctor` again."]
+    else:
+        lines += ["", "This Mac is ready to run Mobster's checks. Next, `mobster sim doctor --fix` prepares a "
+                      "simulator, so the first job doesn't wait for one."]
+        if args.hosted or ci.is_hosted(environ):
+            lines[-1:] = ["This runner is ready to run Mobster's checks."]
+    say("\n".join(lines))
+    return 1 if failed else 0
+
+
+def _run(args, cwd, environ):
+    from ..devtools import ProgressLines
+    from . import ci
+    extra = list(args.extra or ())
+    devices, testflight = _phones(args)
+    root = ci.repo_root(cwd)
+    progress = ProgressLines(sys.stderr)
+    code, doc = ci.run_checks(root, devices=devices, testflight=testflight, sims=tuple(args.sim or ()),
+                              video=not args.no_video, base=args.base, extra=extra, environ=environ,
+                              progress=progress)
+    progress.end()
+    say(f"{doc['headline']}. Report: {ci.CI_DIR}/")
+    return code
+
+
+def _comment(args, cwd, environ):
+    from . import ci
+    root = ci.repo_root(cwd)
+    body = ci.comment_markdown(root, environ, args.artifact_url)
+    target = root / ci.CI_DIR / "comment.md"
+    try:
+        target.write_text(body, encoding="utf-8")
+    except OSError:
+        pass
+    if args.dry_run:
+        say(body)
+        return 0
+    ci.job_summary(body, environ)
+    if ci.host_of(environ) is None:
+        say(body)
+        say(f"Not in a CI job, so Mobster posted nothing. The comment is in {ci.CI_DIR}/comment.md.", sys.stderr)
+        return 0
+    say(ci.post(body, environ), sys.stderr)
+    return 0

mobile_agent/devkit/ci_hosts.py

@@ -0,0 +1,194 @@
+"""The files `mobster ci init --hosted` and `--host xcode-cloud|codemagic|bitrise|circleci` write.
+
+Every file installs uv, prepares a simulator and runs the pinned standalone Mobster CLI.
+None of them asks for a phone: a hosted runner has none."""
+
+from .. import __version__
+
+DOCS = "https://docs.mobster.dev"
+INSTALL = "brew install uv"
+COMMAND = f"uvx --python 3.12 --from mobster-cli=={__version__} mobster"
+
+GITHUB_HOSTED = """# Mobster checks on every pull request, on a GitHub-hosted Mac (@DOCS@/ci/github-hosted).
+# Add ANTHROPIC_API_KEY as a repository secret for checks with steps.
+name: mobster
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write   # the one comment Mobster keeps up to date
+concurrency:
+  group: mobster-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+jobs:
+  checks:
+    runs-on: macos-15
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # the diff needs the base branch
+      - name: Install Mobster
+        id: mobster
+        run: |
+          @INSTALL@
+          echo "version=@VERSION@" >> "$GITHUB_OUTPUT"
+          echo "xcode=$(xcodebuild -version | head -1 | tr -d ' ')" >> "$GITHUB_OUTPUT"
+      - name: Cache WebDriverAgent
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Application Support/app.mobster.desktop/wda
+          key: mobster-wda-${{ runner.arch }}-${{ steps.mobster.outputs.xcode }}-${{ steps.mobster.outputs.version }}
+          restore-keys: |
+            mobster-wda-${{ runner.arch }}-${{ steps.mobster.outputs.xcode }}-
+      - name: Prepare a simulator
+        run: |
+          @COMMAND@ sim doctor --fix
+      - name: Test what this PR changed
+        run: |
+          @COMMAND@ ci run
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # only checks with steps use it
+      - name: Upload the report
+        id: upload
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mobster-report
+          path: .mobster/ci/
+          include-hidden-files: true
+          retention-days: 14
+          if-no-files-found: ignore
+      - name: Comment on the PR
+        if: always()
+        run: |
+          @COMMAND@ ci comment
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          MOBSTER_ARTIFACT_URL: ${{ steps.upload.outputs.artifact-url }}
+"""
+
+XCODE_CLOUD = """#!/bin/sh
+# Mobster checks after Xcode Cloud builds a pull request (@DOCS@/ci/xcode-cloud).
+# Add ANTHROPIC_API_KEY as a secret environment variable for checks with steps.
+set -eu
+if [ -z "${CI_PULL_REQUEST_NUMBER:-}" ]; then
+  echo "This build isn't for a pull request, so Mobster tested nothing."
+  exit 0
+fi
+@INSTALL@
+@COMMAND@ sim doctor --fix
+status=0
+@COMMAND@ ci run || status=$?
+@COMMAND@ ci comment || true   # Xcode Cloud has no comment token; the verdict is in this log
+exit "$status"
+"""
+
+CODEMAGIC = """# Mobster checks on every pull request, on a Codemagic Mac (@DOCS@/ci/codemagic).
+# Put ANTHROPIC_API_KEY in a variable group named mobster for checks with steps.
+workflows:
+  mobster:
+    name: Mobster checks
+    instance_type: mac_mini_m2
+    max_build_duration: 60
+    triggering:
+      events:
+        - pull_request
+    environment:
+      groups:
+        - mobster
+      vars:
+        MOBSTER_BASE_BRANCH: main   # the branch your pull requests merge into
+    scripts:
+      - name: Install Mobster
+        script: @INSTALL@
+      - name: Prepare a simulator
+        script: @COMMAND@ sim doctor --fix
+      - name: Test what this PR changed
+        script: @COMMAND@ ci run
+    artifacts:
+      - .mobster/ci/**
+"""
+
+BITRISE = """# Mobster checks on every pull request, on a Bitrise Mac (@DOCS@/ci/bitrise).
+# Add ANTHROPIC_API_KEY as a Secret for checks with steps. Trigger the workflow on pull requests.
+format_version: "13"
+default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
+workflows:
+  mobster:
+    steps:
+      - git-clone@8: {}
+      - script@1:
+          title: Install Mobster
+          inputs:
+            - content: |-
+                #!/usr/bin/env bash
+                set -euo pipefail
+                @INSTALL@
+                @COMMAND@ sim doctor --fix
+      - script@1:
+          title: Test what this PR changed
+          inputs:
+            - content: |-
+                #!/usr/bin/env bash
+                set -uo pipefail
+                @COMMAND@ ci run
+      - deploy-to-bitrise-io@2:
+          is_always_run: true
+          inputs:
+            - deploy_path: .mobster/ci
+"""
+
+CIRCLECI = """# Mobster checks on every pull request, on a CircleCI Mac (@DOCS@/ci/circleci).
+# Add ANTHROPIC_API_KEY for checks with steps. Pick the Xcode version from CircleCI's macOS list.
+version: 2.1
+jobs:
+  mobster:
+    macos:
+      xcode: "16.4.0"
+    resource_class: m4pro.medium
+    environment:
+      MOBSTER_BASE_BRANCH: main   # the branch your pull requests merge into
+    steps:
+      - checkout
+      - run:
+          name: Install Mobster
+          command: |
+            @INSTALL@
+            @COMMAND@ sim doctor --fix
+      - run:
+          name: Test what this PR changed
+          command: |
+            if [ -z "${CIRCLE_PULL_REQUEST:-}" ]; then echo "This build isn't for a pull request."; exit 0; fi
+            @COMMAND@ ci run
+      - store_artifacts:
+          path: .mobster/ci
+workflows:
+  mobster:
+    jobs:
+      - mobster
+"""
+
+TEMPLATES = {"github": GITHUB_HOSTED, "xcode-cloud": XCODE_CLOUD, "codemagic": CODEMAGIC, "bitrise": BITRISE,
+             "circleci": CIRCLECI}
+
+
+def render(host):
+    """The file for ``host`` ("github" means GitHub's hosted macOS runner)."""
+    return (TEMPLATES[host].replace("@DOCS@", DOCS).replace("@COMMAND@", COMMAND)
+            .replace("@INSTALL@", INSTALL).replace("@VERSION@", __version__))
+
+
+NEXT = {
+    "github": ["Add ANTHROPIC_API_KEY as a repository secret, for checks with steps.",
+               "Commit the file and open a pull request."],
+    "xcode-cloud": ["Add ANTHROPIC_API_KEY as a secret environment variable for checks with steps.",
+                    "Run the script after the build: it is `ci_scripts/ci_post_xcodebuild.sh`, and Xcode Cloud finds "
+                    "it by name.",
+                    "Commit the file and open a pull request."],
+    "codemagic": ["Put ANTHROPIC_API_KEY in a Codemagic variable group named mobster for checks with steps.",
+                  "Commit the file and open a pull request."],
+    "bitrise": ["Add ANTHROPIC_API_KEY as a Secret for checks with steps, and trigger the mobster workflow on pull "
+                "requests.", "Commit the file and open a pull request."],
+    "circleci": ["Add ANTHROPIC_API_KEY as a project environment variable for checks with steps.",
+                 "Commit the file and open a pull request."],
+}

mobile_agent/devkit/es256.py

@@ -0,0 +1,197 @@
+"""ES256 signing for App Store Connect's JSON Web Tokens in plain Python: the agent ships no crypto library."""
+
+import base64
+import hashlib
+import hmac
+import json
+
+P = 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF
+A = P - 3
+B = 0x5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B
+N = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551
+G = (0x6B17D1F2E12C4247F8BCE6E563A440F277037D812DEB33A0F4A13945D898C296,
+     0x4FE342E2FE1A7F9B8EE7EB4A7C0F9E162BCE33576B315ECECBB6406837BF51F5)
+EC_PUBLIC_KEY = bytes.fromhex("2a8648ce3d0201")       # 1.2.840.10045.2.1
+PRIME256V1 = bytes.fromhex("2a8648ce3d030107")        # 1.2.840.10045.3.1.7
+# The PEM lines around a .p8 key, built from the label so a secret scanner never reads the source as a key.
+P8_LABEL = "PRIVATE KEY"
+P8_BEGIN = f"-----BEGIN {P8_LABEL}-----"
+P8_END = f"-----END {P8_LABEL}-----"
+
+
+class P8Error(ValueError):
+    """The text isn't a P-256 private key in the .p8 format App Store Connect gives."""
+
+
+# -- the curve, in Jacobian coordinates ------------------------------------------------------------------------------
+
+def _double(point):
+    x, y, z = point
+    if y == 0 or z == 0:
+        return (0, 1, 0)
+    ysq = y * y % P
+    s = 4 * x * ysq % P
+    m = (3 * (x - z * z) * (x + z * z)) % P          # a = -3
+    nx = (m * m - 2 * s) % P
+    ny = (m * (s - nx) - 8 * ysq * ysq) % P
+    nz = 2 * y * z % P
+    return (nx, ny, nz)
+
+
+def _add(p, q):
+    if p[2] == 0:
+        return q
+    if q[2] == 0:
+        return p
+    z1z1, z2z2 = p[2] * p[2] % P, q[2] * q[2] % P
+    u1, u2 = p[0] * z2z2 % P, q[0] * z1z1 % P
+    s1, s2 = p[1] * q[2] * z2z2 % P, q[1] * p[2] * z1z1 % P
+    if u1 == u2:
+        return _double(p) if s1 == s2 else (0, 1, 0)
+    h, r = (u2 - u1) % P, (s2 - s1) % P
+    hh = h * h % P
+    hhh = h * hh % P
+    v = u1 * hh % P
+    nx = (r * r - hhh - 2 * v) % P
+    ny = (r * (v - nx) - s1 * hhh) % P
+    nz = h * p[2] * q[2] % P
+    return (nx, ny, nz)
+
+
+# Not constant-time: the key and every signature stay in this process, and only the token goes to Apple.
+def _multiply(k, point=G):
+    result, addend = (0, 1, 0), (point[0], point[1], 1)
+    while k:
+        if k & 1:
+            result = _add(result, addend)
+        addend = _double(addend)
+        k >>= 1
+    return result
+
+
+def _affine(point):
+    if point[2] == 0:
+        return None
+    inverse = pow(point[2], P - 2, P)
+    return point[0] * inverse * inverse % P, point[1] * inverse ** 3 % P
+
+
+def public_key(d):
+    return _affine(_multiply(d))
+
+
+# -- RFC 6979 nonces ----------------------------------------------------------------------------------------------
+
+def _bits2int(data):
+    return int.from_bytes(data, "big")  # qlen = hlen = 256
+
+
+def _int2octets(value):
+    return value.to_bytes(32, "big")
+
+
+def _nonces(d, digest):
+    h1 = _int2octets(_bits2int(digest) % N)
+    x = _int2octets(d)
+    v, k = b"\x01" * 32, b"\x00" * 32
+    k = hmac.new(k, v + b"\x00" + x + h1, hashlib.sha256).digest()
+    v = hmac.new(k, v, hashlib.sha256).digest()
+    k = hmac.new(k, v + b"\x01" + x + h1, hashlib.sha256).digest()
+    v = hmac.new(k, v, hashlib.sha256).digest()
+    while True:
+        v = hmac.new(k, v, hashlib.sha256).digest()
+        candidate = _bits2int(v)
+        if 1 <= candidate < N:
+            yield candidate
+        k = hmac.new(k, v + b"\x00", hashlib.sha256).digest()
+        v = hmac.new(k, v, hashlib.sha256).digest()
+
+
+def sign(d, message):
+    """(r, s) over SHA-256(``message``) with the private scalar ``d``."""
+    if not 1 <= d < N:
+        raise P8Error("The private key is out of range.")
+    digest = hashlib.sha256(message).digest()
+    e = _bits2int(digest) % N
+    for k in _nonces(d, digest):
+        point = _affine(_multiply(k))
+        r = point[0] % N
+        if r == 0:
+            continue
+        s = pow(k, N - 2, N) * (e + r * d) % N
+        if s:
+            return r, s
+
+
+def verify(public, message, signature):
+    """Whether ``signature`` (r, s) is ``public``'s (x, y) over SHA-256(``message``)."""
+    r, s = signature
+    if not (1 <= r < N and 1 <= s < N):
+        return False
+    e = _bits2int(hashlib.sha256(message).digest()) % N
+    w = pow(s, N - 2, N)
+    point = _affine(_add(_multiply(e * w % N), _multiply(r * w % N, public)))
+    return point is not None and point[0] % N == r
+
+
+# -- the .p8 file (PKCS #8, RFC 5208, wrapping an RFC 5915 ECPrivateKey) ------------------------------------------
+
+def _der(data, at=0):
+    """(tag, value, next offset) of the DER element at ``at``."""
+    if at + 2 > len(data):
+        raise P8Error("The key is cut short.")
+    tag, length, at = data[at], data[at + 1], at + 2
+    if length & 0x80:
+        count = length & 0x7F
+        if not 1 <= count <= 3 or at + count > len(data):
+            raise P8Error("The key isn't valid DER.")
+        length, at = int.from_bytes(data[at:at + count], "big"), at + count
+    if at + length > len(data):
+        raise P8Error("The key is cut short.")
+    return tag, data[at:at + length], at + length
+
+
+def _children(data):
+    out, at = [], 0
+    while at < len(data):
+        tag, value, at = _der(data, at)
+        out.append((tag, value))
+    return out
+
+
+def private_key_from_p8(text):
+    """The private scalar of a .p8 key: a PKCS #8 PEM between ``P8_BEGIN`` and ``P8_END``."""
+    lines = [line.strip() for line in str(text or "").strip().splitlines() if line.strip()]
+    if not lines or lines[0] != P8_BEGIN or lines[-1] != P8_END:
+        raise P8Error(f"That isn't a .p8 key: it starts with {P8_BEGIN}.")
+    try:
+        data = base64.b64decode("".join(lines[1:-1]), validate=True)
+    except ValueError:
+        raise P8Error("The key's text isn't base64.") from None
+    tag, body, _ = _der(data)
+    parts = _children(body) if tag == 0x30 else []
+    if len(parts) < 3 or parts[0] != (0x02, b"\x00") or parts[1][0] != 0x30 or parts[2][0] != 0x04:
+        raise P8Error("That isn't a PKCS #8 private key.")
+    algorithm = _children(parts[1][1])
+    if len(algorithm) < 2 or algorithm[0] != (0x06, EC_PUBLIC_KEY) or algorithm[1] != (0x06, PRIME256V1):
+        raise P8Error("That key isn't on the P-256 curve App Store Connect uses.")
+    tag, inner, _ = _der(parts[2][1])
+    fields = _children(inner) if tag == 0x30 else []
+    if len(fields) < 2 or fields[0] != (0x02, b"\x01") or fields[1][0] != 0x04 or len(fields[1][1]) != 32:
+        raise P8Error("That isn't an EC private key.")
+    d = int.from_bytes(fields[1][1], "big")
+    if not 1 <= d < N:
+        raise P8Error("The private key is out of range.")
+    return d
+
+
+def _b64url(data):
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def jwt(header, claims, d):
+    """A signed JWT: base64url(header).base64url(claims).base64url(r || s)."""
+    signing_input = (_b64url(json.dumps(header, separators=(",", ":")).encode()) + "." +
+                     _b64url(json.dumps(claims, separators=(",", ":")).encode()))
+    r, s = sign(d, signing_input.encode())
+    return signing_input + "." + _b64url(r.to_bytes(32, "big") + s.to_bytes(32, "big"))