Settle In

How Settle In works

Settle In installs Mac apps from outside the App Store and refuses anything it cannot verify. This page explains each step, what the checks prove, and what they leave unproven.

What happens when you install an app

  1. Settle In finds the download address for the app in its built-in list of apps. For some apps it makes one lookup request to find the newest address. You can seethe apps Settle In knows.
  2. It downloads the app over HTTPS, the encrypted web connection, and only from hosts the built-in list allows for that app. It refuses a redirect to any other host.
  3. It unpacks the download into a temporary folder that only you can read.
  4. It runs five checks on the unpacked app. The first failure stops that app.
  5. If all five checks pass, it copies the app into Applications. The copy gets a hidden temporary name first and is renamed when it finishes, so a failed copy never leaves a half-installed app.

If any check fails, Settle In installs nothing, removes the temporary files, and prints the reason.

The five checks

The checks run in this order.

  1. Code signature

    A Mac app from a known developer carries a seal, called a code signature, that breaks if anyone changes the app after it was signed. This check proves the seal is intact and nothing inside the app was altered. Settle In uses codesign --verify --deep --strictfor it.

  2. Certificate requirement

    A seal only matters if the right developer made it. This check proves the app was signed with a developer certificate whose Team ID matches the one in Settle In's list. A Team ID is a ten-character code that names a developer. An app signed without a developer certificate fails here. Settle In uses codesign --verify --strict with a requirement for this.

  3. Team identifier

    The app also reports which Team ID signed it. This check proves the app reports exactly one Team ID and that it equals the one in the list. Zero or several reports fail, because an app can print forged lines. This check and the certificate requirement must agree. Settle In reads the report with codesign -dv --verbose=4.

  4. Bundle identifier

    Every Mac app has an internal name, such as com.microsoft.VSCode for Visual Studio Code. This check proves the app's internal name equals the one in the list, so the download is the app Settle In expected.

  5. Notarization

    Notarization means Apple's notarization service has accepted the app. This check needs network access, because Settle In asks Apple online. Settle In usesspctl --assess --type execute for it.

A real example

This output comes from Settle In's command-line tool for developers, run here as a dry run. A dry run shows the plan for an app. It changes nothing, downloads nothing and writes nothing. This one is for Visual Studio Code on a Mac with Apple silicon. The five numbered lines are the five checks, in order. The last line appears only when the app is already in Applications.

$ swift run settlein install --dry-run vscode
Dry run: nothing is downloaded, staged or written. A release or appcast source makes one lookup request.

Visual Studio Code (vscode)
  download: https://update.code.visualstudio.com/latest/darwin-arm64/stable (arm64, zip)
  allowed hosts: update.code.visualstudio.com, vscode.download.prss.microsoft.com
  checks, in order:
    1. code signature: codesign --verify --deep --strict must pass
    2. certificate requirement: codesign --verify --strict must pass the requirement anchor apple generic and certificate leaf[subject.OU] = "UBF8T346G9"
    3. team identifier: codesign must print exactly one TeamIdentifier line, and it must equal the catalog value UBF8T346G9
    4. bundle identifier: must equal the catalog value com.microsoft.VSCode
    5. notarization: spctl --assess --type execute must accept the app, print exactly one source line, and give the source Notarized Developer ID
  quarantine: add com.apple.quarantine to the staged app (web download, agent settlein) before the copy
  install path: /Applications/Visual Studio Code.app
  note: already installed (version 1.145.3), install would skip it

What this does not prove

Settle In proves a download matches the pinned identity and does not judge whether that list is trustworthy.

First launch on your Mac

After the checks pass, Settle In marks the app as downloaded from the internet. macOS then shows its normal first-open prompt, the same one a browser download gets. Settle In never removes that mark.