mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/team_signing/apple_ca.py

@@ -0,0 +1,37 @@
+"""Apple's Worldwide Developer Relations intermediate certificate (G3), which issues Apple Development certificates.
+
+A Mac without Xcode doesn't have it, and ``codesign`` accepts a signing certificate only when it can build the chain to
+Apple's root. Mobster puts this public certificate in its own signing keychain. It is Apple's published
+https://www.apple.com/certificateauthority/AppleWWDRCAG3.cer, valid to 20 February 2030, and is checked against its
+SHA-256 before it is imported.
+"""
+
+import base64
+import hashlib
+
+SHA256 = "dcf21878c77f4198e4b4614f03d696d89c66c66008d4244e1b99161aac91601f"
+_DER = (
+    "MIIEUTCCAzmgAwIBAgIQfK9pCiW3Of57m0R6wXjF7jANBgkqhkiG9w0BAQsFADBiMQswCQYDVQQGEwJVUzETMBEGA1UEChMKQXBw"
+    "bGUgSW5jLjEmMCQGA1UECxMdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxFjAUBgNVBAMTDUFwcGxlIFJvb3QgQ0EwHhcN"
+    "MjAwMjE5MTgxMzQ3WhcNMzAwMjIwMDAwMDAwWjB1MUQwQgYDVQQDDDtBcHBsZSBXb3JsZHdpZGUgRGV2ZWxvcGVyIFJlbGF0aW9u"
+    "cyBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTELMAkGA1UECwwCRzMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMIIB"
+    "IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2PWJ/KhZC4fHTJEuLVaQ03gdpDDppUjvC0O/LYT7JF1FG+XrWTYSXFRknmxi"
+    "LbTGl8rMPPbWBpH85QKmHGq0edVny6zpPwcR4YS8Rx1mjjmi6LRJ7TrS4RBgeo6TjMrA2gzAg9Dj+ZHWp4zIwXPirkbRYp2SqJBg"
+    "N31ols2N4Pyb+ni743uvLRfdW/6AWSN1F7gSwe0b5TTO/iK1nkmw5VW/j4SiPKi6xYaVFuQAyZ8D0MyzOhZ71gVcnetHrg21LYwO"
+    "aU1A0EtMOwSejSGxrC5DVDDOwYqGlJhL32oNP/77HK6XF8J4CjDgXx9UO0m3JQAaN4LSVpelUkl8YDib7wIDAQABo4HvMIHsMBIG"
+    "A1UdEwEB/wQIMAYBAf8CAQAwHwYDVR0jBBgwFoAUK9BpR5R2Cf70a40uQKb3R01/CF4wRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUF"
+    "BzABhihodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDAzLWFwcGxlcm9vdGNhMC4GA1UdHwQnMCUwI6AhoB+GHWh0dHA6Ly9jcmwu"
+    "YXBwbGUuY29tL3Jvb3QuY3JsMB0GA1UdDgQWBBQJ/sAVkPmvZAqSErkmKGMMl+ynsjAOBgNVHQ8BAf8EBAMCAQYwEAYKKoZIhvdj"
+    "ZAYCAQQCBQAwDQYJKoZIhvcNAQELBQADggEBAK1lE+j24IF3RAJHQr5fpTkg6mKp/cWQyXMT1Z6b0KoPjY3L7QHPbChAW8dVJEH4"
+    "/M/BtSPp3Ozxb8qAHXfCxGFJJWevD8o5Ja3T43rMMygNDi6hV0Bz+uZcrgZRKe3jhQxPYdwyFot30ETKXXIDMUacrptAGvr04NM+"
+    "+i+MZp+XxFRZ79JI9AeZSWBZGcfdlNHAwWx/eCHvDOs7bJmCS1JgOLU5gm3sUjFTvg+RTElJdI+mUcuER04ddSduvfnSXPN/wmwL"
+    "CTbiZOTCNwMUGdXqapSqqdv+9poIZ4vvK7iqF0mDr8/LvOnP6pVxsLRFoszlh6oKw0E6eVzaUDSdlTs="
+)
+
+
+def wwdr_g3():
+    """The certificate's DER bytes. ValueError if the bytes in this file are not Apple's."""
+    der = base64.b64decode(_DER)
+    if hashlib.sha256(der).hexdigest() != SHA256:
+        raise ValueError("The built-in Apple certificate does not match its fingerprint")
+    return der

mobile_agent/team_signing/bundle.py

@@ -0,0 +1,136 @@
+"""Path C: a signed helper and its profile, exported from one Mac and installed from another.
+
+One Mac with a team's App Store Connect key (or with Xcode) signs the helper once; the other Macs, which need neither,
+import it and only install and launch it. A bundle is a gzip tar of ``manifest.json`` and ``Runner.app``. The signature
+inside is Apple's team signature, so what the bundle can do on a phone is fixed by its profile: it runs only on the
+phones the profile lists, until the profile ends.
+
+Importing trusts nothing in the file. It extracts into a private folder with tar's ``data`` filter (no absolute paths,
+no links out, no devices), then refuses unless: the person named the team the bundle says it is from, the digest of
+every file matches the manifest, the signature verifies, the profile inside says what the manifest says, it was built
+with this Mobster's patches, and it has more than a day left. The team check is the person's: a bundle signed by
+another team would verify too.
+"""
+
+import datetime
+import io
+import json
+import shutil
+import tarfile
+import tempfile
+from pathlib import Path
+
+from ..devkit import DevError
+from ..wda import patches as wda_patches
+from . import resign
+
+KIND = "mobster-signed-helper"
+VERSION = 1
+MIN_LEFT = 86400
+
+
+def export(runner, destination, *, run=None, decode=None, now=None):
+    """Write the signed ``runner`` (…/Runner.app) as a bundle at ``destination`` (a file path). Returns the manifest.
+    DevError when the runner's signature doesn't verify, or it is a runner this Mobster didn't sign with its patches."""
+    runner, destination = Path(runner), Path(destination)
+    facts = resign.check(runner, run=run, decode=decode)
+    now = datetime.datetime.now(datetime.timezone.utc).timestamp() if now is None else now
+    manifest = {
+        "kind": KIND,
+        "version": VERSION,
+        "team": facts["team"],
+        "bundle_id": facts["bundle_id"],
+        "udids": facts["udids"],
+        "expires": facts["expires"],
+        "profile": facts["uuid"],
+        "profile_name": facts["name"],
+        "patches": wda_patches.patch_digest(),
+        "tree": resign.tree_digest(runner),
+        "created": now,
+    }
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    partial = destination.with_name(destination.name + ".part")
+    try:
+        with tarfile.open(partial, "w:gz") as archive:
+            data = json.dumps(manifest, indent=1, sort_keys=True).encode()
+            info = tarfile.TarInfo("manifest.json")
+            info.size, info.mtime, info.mode = len(data), now, 0o600
+            archive.addfile(info, io.BytesIO(data))
+            archive.add(runner, arcname="Runner.app")
+        partial.replace(destination)
+        destination.chmod(0o600)
+    finally:
+        partial.unlink(missing_ok=True)
+    return manifest
+
+
+def read_manifest(path):
+    """The manifest of a bundle, without extracting the runner (so a person can be shown the team before importing)."""
+    try:
+        with tarfile.open(path, "r:gz") as archive:
+            member = archive.getmember("manifest.json")
+            if member.size > 1 << 20:
+                raise DevError("That isn't a Mobster helper bundle.")
+            manifest = json.loads(archive.extractfile(member).read())
+    except (OSError, KeyError, ValueError, tarfile.TarError):
+        raise DevError("That isn't a Mobster helper bundle.", "Export one with `mobster signing export`.") from None
+    if not isinstance(manifest, dict) or manifest.get("kind") != KIND or manifest.get("version") != VERSION:
+        raise DevError("That isn't a Mobster helper bundle this Mobster can read.")
+    return manifest
+
+
+def import_bundle(path, destination, *, team, udid=None, run=None, decode=None, now=None):
+    """Check a bundle and put its runner at ``destination``/Runner.app. ``team`` is the team id the person says it is
+    from. Returns {path, manifest-facts}. DevError, with the fix, on any refusal; nothing is left behind then."""
+    manifest = read_manifest(path)
+    if manifest.get("team") != team:
+        raise DevError(
+            f"That bundle is from team {manifest.get('team')}, not {team}, so Mobster didn't open it.",
+            "Use the bundle from the team you mean.",
+        )
+    now = datetime.datetime.now(datetime.timezone.utc).timestamp() if now is None else now
+    if manifest.get("patches") != wda_patches.patch_digest():
+        raise DevError(
+            "That helper was built with other patches than this Mobster has.",
+            "Export a new bundle from a Mobster of the same version.",
+        )
+    if not isinstance(manifest.get("expires"), (int, float)) or manifest["expires"] < now + MIN_LEFT:
+        raise DevError("That helper's profile has ended or ends within a day.", "Export a new bundle.")
+    if udid is not None and udid not in (manifest.get("udids") or ()):
+        raise DevError(
+            "That bundle's profile doesn't list this iPhone.",
+            "Register the iPhone on the signing Mac, sign again and export a new bundle.",
+        )
+    destination = Path(destination)
+    scratch = Path(tempfile.mkdtemp(prefix="mobster-import-"))
+    try:
+        with tarfile.open(path, "r:gz") as archive:
+            members = [m for m in archive.getmembers() if m.name == "Runner.app" or m.name.startswith("Runner.app/")]
+            if not members:
+                raise DevError("That bundle has no helper in it.")
+            archive.extractall(scratch, members=members, filter="data")
+        runner = scratch / "Runner.app"
+        if resign.tree_digest(runner) != manifest.get("tree"):
+            raise DevError("That bundle changed after it was exported, so Mobster didn't use it.")
+        facts = resign.check(runner, run=run, decode=decode)
+        if (facts["team"], facts["bundle_id"], facts["udids"]) != (
+            manifest["team"],
+            manifest["bundle_id"],
+            manifest["udids"],
+        ):
+            raise DevError("That bundle's profile doesn't say what its label says, so Mobster didn't use it.")
+        destination.mkdir(parents=True, exist_ok=True)
+        target = destination / "Runner.app"
+        shutil.rmtree(target, ignore_errors=True)
+        shutil.move(str(runner), str(target))
+    finally:
+        shutil.rmtree(scratch, ignore_errors=True)
+    return {
+        "path": str(target),
+        "team": manifest["team"],
+        "bundle_id": manifest["bundle_id"],
+        "udids": manifest["udids"],
+        "expires": manifest["expires"],
+        "profile": manifest.get("profile"),
+        "certificate": None,
+    }

mobile_agent/team_signing/cli.py

@@ -0,0 +1,208 @@
+"""`mobster signing`: put Mobster's helper on an iPhone without Xcode, for a paid Apple Developer team.
+
+    mobster signing status
+    mobster signing card                      # reads your team and prints exactly what Mobster would send to Apple
+    mobster signing apply --approve DIGEST    # sends it, signs the helper here and installs it
+    mobster signing resolve DIGEST --made     # after a change whose answer Mobster never saw
+    mobster signing export helper.tgz         # the signed helper, for Macs without a key or Xcode
+    mobster signing import helper.tgz --team ABCDE12345
+
+Off unless ``MOBSTER_EXPERIMENTAL_NO_XCODE=1``. Exit codes: 0 done, 3 couldn't (usage too).
+"""
+
+import json
+import sys
+
+from ..devkit import main, say, subcommands
+
+
+def add_arguments(parser, helpers):
+    add = subcommands(parser, "signing_command")
+
+    def phone_options(sub):
+        sub.add_argument(
+            "--phone-udid",
+            metavar="UDID",
+            help="the iPhone to register and sign for (default: the iPhone chosen in Setup)",
+        )
+        sub.add_argument("--phone-name", metavar="NAME", help="with --phone-udid: its name on your team")
+        sub.add_argument("--bundle-id", metavar="ID", help="sign for this bundle id instead of the helper's (a test)")
+        sub.add_argument(
+            "--team", metavar="ID", help="your team's 10-character id (default: read from App Store Connect)"
+        )
+        sub.add_argument("--json", action="store_true", help="print JSON")
+
+    status = add("status", help="say whether signing without Xcode is on, what it has and what it waits for")
+    status.add_argument("--json", action="store_true", help="print JSON")
+
+    card = add(
+        "card",
+        help="read your team and print the requests Mobster would send to Apple, with a digest",
+        description="Reads App Store Connect with your key and prints each request Mobster would send: register "
+        "your iPhone, create a development certificate from a request made on this Mac, create a "
+        "development profile. Sends nothing. Approve it with `mobster signing apply --approve DIGEST`.",
+    )
+    phone_options(card)
+
+    apply = add(
+        "apply",
+        help="send the card you approved, sign the helper on this Mac and install it",
+        description="Reads your team again and sends the card only if its digest is the one you approved. Each "
+        "request is recorded before it is sent. A request whose answer never arrives is not sent "
+        "again.",
+    )
+    apply.add_argument("--approve", required=True, metavar="DIGEST", help="the digest `mobster signing card` printed")
+    apply.add_argument(
+        "--writes-only",
+        action="store_true",
+        help="make the changes at Apple and stop: sign and install nothing (a test with no iPhone)",
+    )
+    phone_options(apply)
+
+    resolve = add("resolve", help="say whether a change whose answer Mobster never saw was made")
+    resolve.add_argument("digest", metavar="DIGEST", help="the change, from `mobster signing status`")
+    which = resolve.add_mutually_exclusive_group(required=True)
+    which.add_argument("--made", action="store_true", help="you found it at developer.apple.com")
+    which.add_argument("--not-made", action="store_true", help="it isn't there; Mobster may send it once more")
+
+    export = add("export", help="write the signed helper and its profile to a file other Macs can install")
+    export.add_argument("file", metavar="FILE", help="where to write it (a .tgz)")
+    export.add_argument("--phone-udid", metavar="UDID", help="the iPhone it was signed for (default: the one chosen)")
+
+    imp = add(
+        "import",
+        help="install a helper that another Mac signed",
+        description="Opens the file only if it is from the team you name, still has a day of profile left, lists "
+        "this iPhone and is intact. The team is your check: any team's signature verifies.",
+    )
+    imp.add_argument("file", metavar="FILE", help="the .tgz `mobster signing export` wrote")
+    imp.add_argument("--team", required=True, metavar="ID", help="the team id you expect the file to be from")
+    imp.add_argument("--phone-udid", metavar="UDID", help="the iPhone to install on (default: the one chosen)")
+    imp.add_argument("--phone-name", metavar="NAME", help="with --phone-udid: its name")
+
+
+def run(args, *, service=None):
+    handlers = {
+        "status": _status,
+        "card": _card,
+        "apply": _apply,
+        "resolve": _resolve,
+        "export": _export,
+        "import": _import,
+    }
+    return main("signing", handlers, args, service=service)
+
+
+def _service(service):
+    if service is not None:
+        return service
+    from .. import device_manager, paths
+    from .service import TeamSigning
+
+    return TeamSigning(device_manager.DeviceManager(paths.user_data_dir()))
+
+
+def _phones(args):
+    udid = getattr(args, "phone_udid", None)
+    if not udid:
+        return None
+    return [{"udid": udid, "name": getattr(args, "phone_name", None) or "iPhone"}]
+
+
+def _status(args, *, service, **_):
+    from . import enabled
+
+    if not enabled():
+        say("Without Xcode is off. Turn it on with MOBSTER_EXPERIMENTAL_NO_XCODE=1.")
+        return 0
+    info = _service(service).status()
+    if getattr(args, "json", False):
+        say(json.dumps(info, ensure_ascii=False, default=str))
+        return 0
+    key = info["key"]
+    lines = [
+        "Key       "
+        + (
+            f"{key['keyId']} ({key['kind']})"
+            if key
+            else "none: mobster asc key add --key-id KEY_ID --issuer-id ISSUER_ID --p8 FILE"
+        ),
+        f"Driver    {info['driver'] or 'none: pipx install pymobiledevice3'}",
+        f"Stage     {info['stage']}",
+    ]
+    for open_write in info["unresolved"]:
+        lines.append(
+            f"Waiting   {open_write['write'].replace('_', ' ')} was sent and never answered "
+            f"({open_write['digest'][:12]}): mobster signing resolve {open_write['digest']} --made | --not-made"
+        )
+    say("\n".join(lines))
+    return 0
+
+
+def render(card):
+    lines = [
+        f"App ID    {card['bundle']['identifier']}"
+        + ("  (your team's wildcard)" if card["bundle"]["identifier"] == "*" else "")
+    ]
+    if not card["steps"]:
+        lines.append("Mobster sends nothing to Apple: your team already has everything the helper needs.")
+    for step in card["steps"]:
+        lines += ["", f"{step['number']}. {step['title']}", f"   {step['method']} {step['url']}"]
+        lines += [f"   {item['label']:<10}{item['value']}" for item in step["lines"]]
+    lines += ["", f"Digest    {card['digest']}"]
+    return "\n".join(lines)
+
+
+def _card(args, *, service, **_):
+    card = _service(service).card(_phones(args), args.bundle_id, args.team)
+    say(
+        json.dumps(card, ensure_ascii=False)
+        if args.json
+        else render(card) + f"\n\nApprove: mobster signing apply --approve {card['digest']}"
+    )
+    return 0
+
+
+def _apply(args, *, service, **_):
+    info = _service(service).apply(args.approve, _phones(args), args.bundle_id, args.team, args.writes_only)
+    if info["stage"] == "failed":
+        say(f"mobster signing: {info['error']} {info['fix'] or ''}".rstrip(), sys.stderr)
+        return 3
+    say(
+        json.dumps(info["result"], ensure_ascii=False, default=str)
+        if args.json
+        else "Done: "
+        + (
+            ", ".join(f"{name} {ident}" for name, ident in (info["result"].get("writes") or {}).items())
+            if args.writes_only
+            else f"the helper {info['result']['runner']} is on the iPhone."
+        )
+    )
+    return 0
+
+
+def _resolve(args, *, service, **_):
+    _service(service).resolve(args.digest, bool(args.made))
+    say("Recorded." + ("" if args.made else " Mobster may send it once more."))
+    return 0
+
+
+def _export(args, *, service, **_):
+    manifest = _service(service).export_bundle(args.file, args.phone_udid)
+    say(
+        f"Wrote {args.file}: team {manifest['team']}, {len(manifest['udids'])} iPhone(s), profile ends "
+        f"{_date(manifest['expires'])}."
+    )
+    return 0
+
+
+def _import(args, *, service, **_):
+    manifest = _service(service).import_bundle(args.file, args.team, _phones(args))
+    say(f"Installed {manifest['bundle_id']} (team {manifest['team']}, profile ends {_date(manifest['expires'])}).")
+    return 0
+
+
+def _date(epoch):
+    import datetime
+
+    return datetime.datetime.fromtimestamp(epoch, datetime.timezone.utc).strftime("%-d %B %Y")

mobile_agent/team_signing/identity.py

@@ -0,0 +1,248 @@
+"""The signing key and certificate on this Mac, in a Keychain only Mobster opens.
+
+Mobster makes the key pair here and sends Apple only a certificate signing request (CSR). The private key is made in
+a private temporary folder, imported into a keychain file of Mobster's own (``mobster-signing.keychain-db`` in the
+signing folder, not on the login keychain's search list), and the temporary file is deleted. That keychain's password is
+random and kept in the login Keychain (keychain_acl, readable only by Mobster's own programs); it is never put on a
+command line. Apple's certificate comes back as a public file, and ``security import`` pairs it with the key.
+
+``run`` is the one place a command is executed, so a test records the commands and needs no Keychain.
+"""
+
+import base64
+import hashlib
+import json
+import os
+import re
+import secrets
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from ..devkit import DevError
+
+SECURITY = "/usr/bin/security"
+OPENSSL = "/usr/bin/openssl"
+KEYCHAIN_FILE = "mobster-signing.keychain-db"
+SERVICE = "Mobster Team Signing"
+ACCOUNT = "keychain"
+SUBJECT = "/CN=Mobster helper signing"
+KEY_BITS = 2048
+HEX40 = re.compile(r"[0-9A-F]{40}")
+
+
+def _run(argv, stdin=None, timeout=60):
+    try:
+        done = subprocess.run(argv, input=stdin, capture_output=True, text=True, timeout=timeout)
+    except (OSError, subprocess.SubprocessError) as error:
+        return 127, "", type(error).__name__
+    return done.returncode, done.stdout, done.stderr
+
+
+def _store():
+    from ..keychain_acl import Store
+
+    return Store(SERVICE)
+
+
+class Identity:
+    """The key pair and certificate of this Mac's signing for one folder (``team_signing.state_dir()``)."""
+
+    def __init__(self, folder, *, store=None, run=_run):
+        self.folder, self.run = Path(folder), run
+        self._store = store
+        self.keychain = self.folder / KEYCHAIN_FILE
+        self.state_path = self.folder / "identity.json"
+
+    # -- what is on disk ------------------------------------------------------------------------------------
+
+    def state(self):
+        try:
+            value = json.loads(self.state_path.read_text())
+            return value if isinstance(value, dict) else {}
+        except (OSError, ValueError):
+            return {}
+
+    def _save(self, **changes):
+        from .. import env_file
+
+        merged = {**self.state(), **changes}  # read before the file is opened for writing, which empties it
+        env_file.private_dir(self.folder)
+        with env_file.open_private(self.state_path, "w") as stream:
+            stream.write(json.dumps(merged, indent=1))
+
+    # -- the keychain ---------------------------------------------------------------------------------------
+
+    def _password(self, create=False):
+        store = self._store if self._store is not None else _store()
+        self._store = store
+        stored = store.get(ACCOUNT)
+        if stored is None and create:
+            stored = secrets.token_urlsafe(32)
+            store.set(ACCOUNT, stored)
+        return stored
+
+    def _security(self, *commands):
+        """Commands for security(1)'s interactive mode, fed on stdin: a password never reaches an argument list."""
+        code, out, err = self.run([SECURITY, "-i"], "\n".join(commands) + "\n")
+        if code != 0:
+            raise DevError(
+                "macOS's Keychain tool refused Mobster's signing keychain.",
+                "Unlock your Mac's login Keychain and try again.",
+            )
+        return out
+
+    def _search_list(self):
+        code, out, _ = self.run([SECURITY, "list-keychains", "-d", "user"])
+        return [line.strip().strip('"') for line in out.splitlines() if line.strip()] if code == 0 else []
+
+    def ensure_keychain(self):
+        """Create Mobster's signing keychain if it isn't there, and unlock it. It never stays on the search list."""
+        from .. import env_file
+
+        env_file.private_dir(self.folder)
+        password = self._password(create=not self.keychain.exists())
+        if password is None:
+            raise DevError(
+                "Mobster's signing keychain is missing its password, so it can't open.",
+                "Remove the team-signing folder in Mobster's data folder to start again.",
+            )
+        quoted = _quote(password)
+        if not self.keychain.exists():
+            before = self._search_list()
+            self._security(f"create-keychain -p {quoted} {_quote(str(self.keychain))}")
+            if before and str(self.keychain) in " ".join(self._search_list()):
+                self.run([SECURITY, "list-keychains", "-d", "user", "-s", *before])
+            self._security(f"set-keychain-settings {_quote(str(self.keychain))}")  # no lock timeout
+            self._save(intermediate=None, pending_key=None, certificate_sha1=None)
+        self._security(f"unlock-keychain -p {quoted} {_quote(str(self.keychain))}")
+        if not self.state().get("intermediate"):
+            self._import_intermediate()
+        return password
+
+    def _import_intermediate(self):
+        """Apple's WWDR G3 certificate, so codesign can build the chain on a Mac without Xcode (apple_ca.py)."""
+        from .. import env_file
+        from . import apple_ca
+
+        certificate = self.folder / "AppleWWDRCAG3.cer"
+        with env_file.open_private(certificate, "wb") as stream:
+            stream.write(apple_ca.wwdr_g3())
+        try:
+            self._security(f"import {_quote(str(certificate))} -k {_quote(str(self.keychain))}")
+        finally:
+            certificate.unlink(missing_ok=True)
+        self._save(intermediate=apple_ca.SHA256)
+
+    # -- the request ----------------------------------------------------------------------------------------
+
+    def request(self):
+        """The CSR (PEM) for the key in the signing keychain; a pending one is returned again, so the same card
+        shows the same request. The private key is made here and never leaves this Mac."""
+        pending = self.folder / "pending.csr"
+        if pending.exists() and self.state().get("pending_key") == "imported":
+            return pending.read_text()
+        password = self.ensure_keychain()
+        workspace = Path(tempfile.mkdtemp(prefix="mobster-csr-"))
+        try:
+            os.chmod(workspace, 0o700)
+            key, csr = workspace / "key.pem", workspace / "request.csr"
+            key.touch(mode=0o600)  # openssl keeps this mode when it writes the key into the file
+            code, _, _ = self.run(
+                [
+                    OPENSSL,
+                    "req",
+                    "-new",
+                    "-newkey",
+                    f"rsa:{KEY_BITS}",
+                    "-nodes",
+                    "-keyout",
+                    str(key),
+                    "-out",
+                    str(csr),
+                    "-subj",
+                    SUBJECT,
+                ]
+            )
+            if code != 0 or not key.exists() or not csr.exists():
+                raise DevError(
+                    "Mobster couldn't make a certificate signing request on this Mac.",
+                    "Check that /usr/bin/openssl runs.",
+                )
+            self._security(f"import {_quote(str(key))} -k {_quote(str(self.keychain))} -x -T /usr/bin/codesign")
+            self._security(
+                f"set-key-partition-list -S apple-tool:,apple:,codesign: -s -k {_quote(password)} "
+                f"{_quote(str(self.keychain))}"
+            )
+            text = csr.read_text()
+        finally:
+            shutil.rmtree(workspace, ignore_errors=True)
+        from .. import env_file
+
+        with env_file.open_private(pending, "w") as stream:
+            stream.write(text)
+        self._save(pending_key="imported")
+        return text
+
+    # -- the certificate ------------------------------------------------------------------------------------
+
+    def add_certificate(self, certificate_content, serial=None):
+        """Keep the certificate Apple made (``certificateContent``, base64 DER) beside its key. Returns
+        {sha1, serial}. DevError when it isn't a certificate or the key isn't here."""
+        try:
+            der = base64.b64decode(certificate_content, validate=True)
+        except (ValueError, TypeError):
+            raise DevError("Apple's certificate wasn't readable.") from None
+        if len(der) < 64 or der[:1] != b"\x30":
+            raise DevError("Apple's certificate wasn't readable.")
+        sha1 = hashlib.sha1(der).hexdigest().upper()
+        self.ensure_keychain()
+        from .. import env_file
+
+        env_file.private_dir(self.folder)
+        certificate = self.folder / "certificate.cer"
+        with env_file.open_private(certificate, "wb") as stream:
+            stream.write(der)
+        self._security(f"import {_quote(str(certificate))} -k {_quote(str(self.keychain))} -T /usr/bin/codesign")
+        if sha1 not in self.identities():
+            raise DevError(
+                "Apple's certificate doesn't match the key on this Mac.",
+                "Remove the team-signing folder in Mobster's data folder and start again.",
+            )
+        (self.folder / "pending.csr").unlink(missing_ok=True)
+        self._save(pending_key=None, certificate_sha1=sha1, certificate_serial=serial)
+        return {"sha1": sha1, "serial": serial}
+
+    def identities(self):
+        """SHA-1s of the code-signing identities (a certificate with its key) in the signing keychain."""
+        if not self.keychain.exists():
+            return []
+        self.ensure_keychain()
+        code, out, _ = self.run([SECURITY, "find-identity", "-p", "codesigning", str(self.keychain)])
+        return [match for match in re.findall(r"\b([0-9A-F]{40})\b", out)] if code == 0 else []
+
+    def signing_identity(self):
+        """{sha1, serial} of the certificate Mobster made here, while its key is still in the keychain; else None."""
+        state = self.state()
+        sha1 = state.get("certificate_sha1")
+        if sha1 and HEX40.fullmatch(sha1) and sha1 in self.identities():
+            return {"sha1": sha1, "serial": state.get("certificate_serial")}
+        return None
+
+    def forget(self):
+        """Delete the signing keychain and its password, e.g. after the test certificate is revoked."""
+        password_store = self._store if self._store is not None else _store()
+        if self.keychain.exists():
+            self.run([SECURITY, "delete-keychain", str(self.keychain)])
+        for name in ("pending.csr", "certificate.cer", "identity.json"):
+            (self.folder / name).unlink(missing_ok=True)
+        try:
+            password_store.delete(ACCOUNT)
+        except Exception:  # noqa: BLE001 -- nothing stored is fine
+            pass
+
+
+def _quote(value):
+    """One word for security(1)'s interactive parser: double-quoted, with \\ and " escaped."""
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'