Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

15.4 KB
Raw Blame
#!/usr/bin/env python3
"""Prove a built macOS app can use its privacy permissions, before it ships.

Why this gate exists (BUG-222). The v2.5.0 ``.dmg`` shipped with two defects
that no headless smoke run can see, because the smoke run starts the executable
directly instead of the way a user does:

* The pyobjc ``AVFoundation`` module was not in the frozen archive. The
  permission port loads it by NAME (``SystemPermissionPort._load``), which
  PyInstaller's static analysis cannot follow, so the app read its microphone
  permission as "unavailable" for good and the voice gate never opened.
* ``Info.plist`` said ``LSBackgroundOnly``. PyInstaller sets it whenever the
  last executable of the COLLECT is a console one (the ``jarvis`` CLI is), and
  LaunchServices then runs the app as a faceless background process.

This script reads the finished ``.app`` itself: the plist, and the module table
of the frozen archive embedded in the main executable (the same data
``pyi-archive_viewer`` prints). It runs on any host that has PyInstaller, and
fails with the exact thing that is missing.

It also asserts the privacy-permission declarations of the bundle:

* every ``NS...UsageDescription`` string of the single table in
  ``dodaios/core/macos_privacy_strings.py`` is in ``Info.plist`` with exactly that
  text, and the keys that table lists as removed (camera, speech recognition,
  system administration) are not;
* the bundle is localised for German, Spanish and European Portuguese: ``Info.plist`` declares
  ``CFBundleLocalizations`` and ``CFBundleDevelopmentRegion``, and
  ``Contents/Resources/<lang>.lproj/InfoPlist.strings`` exists for each language
  with exactly the text of that table (``packaging/macos/add_localizations.py``
  writes them before signing; a file missing here means the build step did not run);
* on a SIGNED build (a certificate identity, i.e. the Developer ID path of
  ``packaging/macos/build.sh``), ``codesign -d --entitlements :-`` must report
  every entitlement of ``packaging/macos/entitlements.plist`` and none of the
  removed ones. An unsigned or ad-hoc build embeds no entitlements, so that
  half is SKIPPED with a message that says so; a skip is not a pass. It also
  needs ``codesign``, which exists on macOS only. The behaviour of a hardened
  signed build on a real Mac is unverified: this reads declarations, it does not
  run the app.

Usage:
    python scripts/ci/check_frozen_macos_app.py --app "dist/Dodaios.app"

Exit codes: 0 = fine (skipped parts are printed as NOTE lines), 1 = the app would
ship broken (problems listed), 2 = could not check (missing file, unreadable
archive, no PyInstaller, a signature codesign cannot read).
"""

from __future__ import annotations

import argparse
import plistlib
import re
import subprocess
import sys
from collections.abc import Callable, Collection, Mapping, Sequence
from pathlib import Path

ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(ROOT))

from dodaios.core import macos_privacy_strings  # noqa: E402
from dodaios.core.branding import MACOS_DMG_BUNDLE_ID  # noqa: E402
from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS  # noqa: E402

ENTITLEMENTS_FILE = ROOT / "packaging" / "macos" / "entitlements.plist"

# Entitlements that must never be embedded: Jarvis has no caller for them, so
# they would grant the right to ask for something nothing asks for.
REMOVED_ENTITLEMENTS: tuple[str, ...] = ("com.apple.security.device.camera",)

# ``codesign`` is invoked as ``codesign <args>``; the seam returns the finished
# process with BYTES in stdout and stderr (the plist may carry any encoding).
CodesignRunner = Callable[[Sequence[str]], "subprocess.CompletedProcess[bytes]"]

# Modules the permission port and the macOS input/capture code reach by NAME or
# through the frameworks' own lazy loaders: all of them must be in the archive.
REQUIRED_FROZEN_MODULES: tuple[str, ...] = (
    "AVFoundation",
    "ApplicationServices",
    "AppKit",
    "Foundation",
    "Quartz",
    "objc",
)


def check_info_plist(info: dict, macos_dir: Path) -> list[str]:
    """What is wrong with the bundle's ``Info.plist`` (empty list = fine)."""
    problems: list[str] = []
    if info.get("CFBundleIdentifier") != MACOS_DMG_BUNDLE_ID:
        problems.append(
            f"CFBundleIdentifier is {info.get('CFBundleIdentifier')!r}, but the permission "
            f"port accepts {MACOS_DMG_BUNDLE_ID!r} for this app"
        )
    if info.get("LSBackgroundOnly"):
        problems.append(
            "LSBackgroundOnly is true: LaunchServices would run the app as a faceless "
            "background process (no Dock icon, no windows). Set it to False in dodaios.spec."
        )
    executable = info.get("CFBundleExecutable")
    if not isinstance(executable, str) or not (macos_dir / executable).is_file():
        problems.append(f"CFBundleExecutable {executable!r} is not in Contents/MacOS")
    problems += check_usage_strings(info)
    problems += check_localization_keys(info)
    return problems


# What a missing string costs, per key. The microphone one is the documented
# process-ending case; the others are third-party reports (silent refusal, no
# prompt) and therefore worded as "may".
_MISSING_STRING_CONSEQUENCE = {
    "NSMicrophoneUsageDescription": "macOS ends the process the moment it asks for the microphone",
}
_DEFAULT_MISSING_STRING_CONSEQUENCE = (
    "macOS may refuse the request without ever showing a permission prompt"
)


def check_usage_strings(info: Mapping[str, object]) -> list[str]:
    """What is wrong with the bundle's usage-description strings (empty = fine).

    The reference is ``dodaios/core/macos_privacy_strings.py``, the one table the
    spec and the managed bundle both load: a missing, blank or different string
    means this bundle was not built from it, and a key from the removed list
    claims access the app never uses.
    """
    problems: list[str] = []
    expected = macos_privacy_strings.usage_descriptions()
    for key in macos_privacy_strings.REQUIRED_USAGE_KEYS:
        value = info.get(key)
        if not isinstance(value, str) or not value.strip():
            consequence = _MISSING_STRING_CONSEQUENCE.get(key, _DEFAULT_MISSING_STRING_CONSEQUENCE)
            problems.append(f"{key} is missing: {consequence}")
        elif value != expected[key]:
            problems.append(
                f"{key} differs from dodaios/core/macos_privacy_strings.py: the bundle was "
                "not built from the single usage-string table (dodaios.spec must load it)"
            )
    for key in macos_privacy_strings.REMOVED_USAGE_KEYS:
        if key in info:
            problems.append(
                f"{key} is in Info.plist but Jarvis has no caller for that permission: "
                "remove it from dodaios.spec (least privilege)"
            )
    return problems


def check_localization_keys(info: Mapping[str, object]) -> list[str]:
    """What is wrong with the localisation declarations of ``Info.plist`` (empty = fine)."""
    expected = macos_privacy_strings.localization_plist_keys()
    problems: list[str] = []
    for key, value in expected.items():
        if info.get(key) != value:
            problems.append(
                f"{key} is {info.get(key)!r}, expected {value!r}: the bundle declares no "
                "German/Spanish localisation (dodaios.spec must spread "
                "localization_plist_keys() into its Info.plist)"
            )
    return problems


def check_localization_files(resources_dir: Path) -> list[str]:
    """Which ``<lang>.lproj/InfoPlist.strings`` are missing or differ from the table."""
    problems: list[str] = []
    for language in macos_privacy_strings.LOCALIZED_LANGUAGES:
        target = resources_dir / f"{language}.lproj" / "InfoPlist.strings"
        if not target.is_file():
            problems.append(
                f"{language}.lproj/InfoPlist.strings is missing from Contents/Resources: "
                "macOS would show the English permission text only (build.sh runs "
                "packaging/macos/add_localizations.py before signing)"
            )
            continue
        try:
            text = target.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            problems.append(f"{language}.lproj/InfoPlist.strings is not valid UTF-8")
            continue
        if text != macos_privacy_strings.info_plist_strings_text(language):
            problems.append(
                f"{language}.lproj/InfoPlist.strings differs from "
                "dodaios/core/macos_privacy_strings.py: it was not written from the "
                "single usage-string table"
            )
    return problems


# --- code signature and entitlements ------------------------------------------


def _run_codesign(args: Sequence[str]) -> subprocess.CompletedProcess[bytes]:
    """The real ``codesign``; raises ``FileNotFoundError`` where it does not exist."""
    return subprocess.run(  # noqa: S603 - fixed argv, no shell
        ["codesign", *args],
        capture_output=True,
        timeout=120,
        check=False,
        creationflags=NO_WINDOW_CREATIONFLAGS,
    )


def _text(blob: bytes) -> str:
    return blob.decode("utf-8", errors="replace")


def signing_kind(app: Path, run: CodesignRunner) -> str:
    """``"identity"`` (signed with a certificate), ``"adhoc"`` or ``"unsigned"``.

    Reads ``codesign -dvv`` (its report goes to stderr). Raises ``RuntimeError``
    for output it cannot classify, because guessing here would either skip a
    check that should run or demand entitlements an ad-hoc build never has.
    """
    result = run(["-dvv", str(app)])
    report = _text(result.stderr) + "\n" + _text(result.stdout)
    if "not signed at all" in report:
        return "unsigned"
    if re.search(r"^Signature=adhoc\s*$", report, re.MULTILINE):
        return "adhoc"
    if re.search(r"^Authority=\S", report, re.MULTILINE):
        return "identity"
    first = next((line for line in report.splitlines() if line.strip()), "<no output>")
    raise RuntimeError(
        f"codesign -dvv gave no signature kind I recognise (exit {result.returncode}): {first}"
    )


_PLIST_XML = re.compile(rb"<\?xml.*?</plist>", re.DOTALL)


def read_entitlements(app: Path, run: CodesignRunner) -> dict[str, object]:
    """The entitlements embedded in the signed ``app`` (empty = none embedded).

    ``codesign -d --entitlements :-`` writes the entitlements as an XML plist
    on stdout; older and newer macOS differ in what else surrounds it (an
    ``Executable=`` line on stderr, sometimes a blob header), so the plist is cut
    out of the output instead of parsing the whole stream.
    """
    result = run(["-d", "--entitlements", ":-", str(app)])
    for stream in (result.stdout, result.stderr):
        match = _PLIST_XML.search(stream)
        if match:
            parsed = plistlib.loads(match.group(0))
            if not isinstance(parsed, dict):
                raise RuntimeError("codesign reported entitlements that are not a dictionary")
            return parsed
    return {}


def check_entitlements(found: Mapping[str, object], expected: Mapping[str, object]) -> list[str]:
    """What an embedded entitlement set lacks, or carries that it must not."""
    problems = [
        f"the signed app lacks entitlement {key} (packaging/macos/entitlements.plist asks for it)"
        for key, value in expected.items()
        if found.get(key) != value
    ]
    problems += [
        f"the signed app carries entitlement {key}, which Jarvis has no caller for "
        "(least privilege)"
        for key in REMOVED_ENTITLEMENTS
        if key in found
    ]
    return problems


def check_signature(
    app: Path,
    *,
    run: CodesignRunner | None = None,
    notes: list[str] | None = None,
    entitlements_file: Path | None = None,
) -> list[str]:
    """Entitlement problems of a SIGNED build; a skip is recorded in ``notes``."""
    notes = notes if notes is not None else []
    runner = run if run is not None else _run_codesign
    try:
        kind = signing_kind(app, runner)
    except FileNotFoundError:
        notes.append(
            "entitlements NOT checked: codesign is not available on this host "
            "(it ships with macOS; run this on the Mac or macOS runner that built the app)"
        )
        return []
    if kind != "identity":
        state = "ad-hoc signed" if kind == "adhoc" else "unsigned"
        notes.append(
            f"entitlements NOT checked: the app is {state}, and build.sh embeds "
            "entitlements only with a Developer ID identity (a skip, not a pass)"
        )
        return []
    expected = plistlib.loads((entitlements_file or ENTITLEMENTS_FILE).read_bytes())
    return check_entitlements(read_entitlements(app, runner), expected)


def check_frozen_modules(names: Collection[str]) -> list[str]:
    """Which required modules the frozen archive lacks (empty list = fine)."""
    present = set(names)
    return [
        f"the frozen archive has no {module!r} module (needs the [desktop-macos] extra "
        "on the build machine and a hidden import in dodaios.spec)"
        for module in REQUIRED_FROZEN_MODULES
        if module not in present
    ]


def frozen_module_names(executable: Path) -> set[str]:
    """Every module name in the PYZ archives embedded in a frozen executable."""
    from PyInstaller.archive.readers import CArchiveReader  # noqa: PLC0415

    archive = CArchiveReader(str(executable))
    names: set[str] = set()
    for entry_name, (*_, typecode) in archive.toc.items():
        if typecode == "z":
            names.update(archive.open_embedded_archive(entry_name).toc.keys())
    return names


def check_app(
    app: Path,
    *,
    read_modules: Callable[[Path], Collection[str]] | None = None,
    run_codesign: CodesignRunner | None = None,
    notes: list[str] | None = None,
) -> list[str]:
    """All problems of the built ``app`` bundle; raises if the bundle cannot be read.

    ``notes`` collects what was SKIPPED (no ``codesign`` on this host, or an
    unsigned/ad-hoc build that embeds no entitlements) so the caller can print it.
    """
    read = read_modules if read_modules is not None else frozen_module_names
    contents = app / "Contents"
    with (contents / "Info.plist").open("rb") as stream:
        info = plistlib.load(stream)
    macos_dir = contents / "MacOS"
    problems = check_info_plist(info, macos_dir)
    problems += check_localization_files(contents / "Resources")
    executable = info.get("CFBundleExecutable")
    if isinstance(executable, str) and (macos_dir / executable).is_file():
        problems += check_frozen_modules(read(macos_dir / executable))
    problems += check_signature(app, run=run_codesign, notes=notes)
    return problems


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    parser.add_argument("--app", required=True, type=Path, help="the built Dodaios.app")
    args = parser.parse_args(argv)
    notes: list[str] = []
    try:
        problems = check_app(args.app, notes=notes)
    except Exception as exc:  # noqa: BLE001 - any unreadable bundle or archive is "cannot check"
        print(f"check_frozen_macos_app: cannot check {args.app}: {type(exc).__name__}: {exc}")
        return 2
    for note in notes:
        print(f"check_frozen_macos_app: NOTE - {note}")
    if problems:
        print(f"check_frozen_macos_app: {args.app} would ship broken:")
        for problem in problems:
            print(f"  - {problem}")
        return 1
    print(f"check_frozen_macos_app: OK - {args.app} can use macOS permissions.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())