SPB Git

Repository Public

signing.md 12.7 KB

# Code signing

ORIX Sheet is distributed outside the Mac App Store, signed with a Developer ID Application certificate and the hardened runtime. Signing is implemented by one script, Scripts/sign.sh (65 lines), also reachable as Scripts/build.sh release. This document describes that script and the build settings it relies on, and records what was observed on the signed bundle present in dist/ on 2026-11-21.

Next steps in the chain: notarization, distribution, release checklist. Threat model: security.md.

# Inputs

Input Value Where it is set
Bundle identifier ai.spboucher.orix.sheet project.yml (PRODUCT_BUNDLE_IDENTIFIER)
Team 3YM54G49SN project.yml (DEVELOPMENT_TEAM); also hard-coded in the verification loop of sign.sh
Version / build 1.0.0 / 1 project.yml (MARKETING_VERSION, CURRENT_PROJECT_VERSION)
Signing style Manual project.yml (CODE_SIGN_STYLE)
Identity, Debug Apple Development project.yml (target base settings)
Identity, Release Developer ID Application, with OTHER_CODE_SIGN_FLAGS: --timestamp project.yml (Release config)
Architectures, Release arm64 x86_64, ONLY_ACTIVE_ARCH: NO project.yml
Hardened runtime ENABLE_HARDENED_RUNTIME: YES project.yml
App Sandbox ENABLE_APP_SANDBOX: NO project.yml
Entitlements file App/Resources/ORIXSheet.entitlements (empty dictionary) project.yml (CODE_SIGN_ENTITLEMENTS)
Injected base entitlements CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NO project.yml
Runpath @executable_path/../Frameworks project.yml (LD_RUNPATH_SEARCH_PATHS)

Source: project.yml, Scripts/sign.sh.

The certificate and its private key are expected in the login keychain. The script never creates, exports or prints key material; no certificate, .p8, .p12 or provisioning profile is stored in the repository (.gitignore excludes them and Scripts/secret-scan.sh fails on such files).

# What Scripts/sign.sh does

flowchart TD
    A["Find Developer ID identity<br/>in the keychain"] --> B["fetch-duckdb.sh<br/>xcodegen generate"]
    B --> C["xcodebuild Release<br/>(universal, signed by Xcode)"]
    C --> D["ditto to<br/>dist/ORIX Sheet.app"]
    D --> CLI["swift build orix-sheet<br/>(universal), copy to<br/>Contents/MacOS, fix runpaths"]
    CLI --> E["Sign Mach-O files:<br/>dylibs, Helpers, Resources"]
    E --> F["Sign frameworks and<br/>bundles, deepest first"]
    F --> T["Sign the orix-sheet tool"]
    T --> G["Sign the app with<br/>the entitlements file"]
    G --> H["Verify: strict deep check,<br/>no get-task-allow,<br/>team and runtime on every Mach-O"]

SVG fallback: Signing pipeline of Scripts/sign.sh

Step by step, with the exact behaviour of the script:

  1. Identity. security find-identity -v -p codesigning is filtered for the first line containing Developer ID Application: …. If none is found the script stops with an error. If several Developer ID identities are installed, the first one listed is used; there is no option to choose.
  2. Project. Scripts/fetch-duckdb.sh makes sure Vendor/duckdb/CDuckDB.xcframework exists (pinned DuckDB v2.0.1, SHA-256 checked on download), then xcodegen generate rebuilds ORIXSheet.xcodeproj from project.yml.
  3. Build. xcodebuild -configuration Release -derivedDataPath build/DerivedData-release build. Output is filtered to error lines and the ** BUILD … ** line. The previous Release product is deleted first. A failing xcodebuild stops the script at this line (set -euo pipefail); a second guard stops it if the app is missing afterwards.
  4. Copy. dist/ORIX Sheet.app is replaced by a ditto copy of the built product. Signing is done on the copy.
  5. Command-line tool. swift build -c release --arch arm64 --arch x86_64 --product orix-sheet in Packages/SheetAutomation builds a universal orix-sheet, which is copied to dist/ORIX Sheet.app/Contents/MacOS/orix-sheet. Every runpath of the copy other than /usr/lib/swift is deleted with install_name_tool -delete_rpath (they point into the build machine), and @executable_path/../Frameworks is added, so that the tool loads libduckdb.dylib from the app's Contents/Frameworks. FeatureAutomation looks for the tool at that location when the user installs a schedule (WorkflowSchedule.bundledTool).
  6. Nested code, inside-out.
    • every regular file under Contents/ that is a *.dylib, or lies under a Helpers/ or Resources/ directory, and that file identifies as Mach-O, is signed with codesign --force --timestamp --options runtime --sign "$IDENTITY";
    • every *.framework and *.bundle directory is signed with the same options, deepest first (find -depth);
    • Contents/MacOS/orix-sheet is signed with the same options (no entitlements);
    • the application itself is signed last, the only step that passes --entitlements App/Resources/ORIXSheet.entitlements.
  7. Verification (the script fails if any check fails):
    • codesign --verify --deep --strict --verbose=2;
    • prints architectures (lipo -archs), identifier, authorities, team, timestamp, runtime version and the code-directory flags;
    • refuses a build that carries get-task-allow in its entitlements;
    • walks every file of the bundle and requires each Mach-O to show TeamIdentifier=3YM54G49SN and flags=…runtime;
    • runs the embedded tool (orix-sheet version) and prints its first line, which shows that it starts and finds DuckDB from inside the bundle;
    • prints the version from Info.plist and ends with RESULT: … is built and signed. It is NOT notarized yet (run Scripts/notarize.sh).

Nothing is uploaded by this script.

# Why every nested binary is re-signed

Xcode already signs the product during the Release build. The script signs again, explicitly, for three reasons that can be read from its code:

  • a secure timestamp on every signature (--timestamp), which notarization requires;
  • the hardened runtime on every Mach-O, including libraries that Xcode copies as they are;
  • one team for everything, checked afterwards file by file, so that library validation cannot reject a nested library at launch.

--deep is used only for verification, never for signing: nested code is signed explicitly, inside-out, and the outer signature then seals the already-signed contents.

# Entitlements: an empty dictionary

App/Resources/ORIXSheet.entitlements is:

xml
<plist version="1.0">
<dict/>
</plist>

The file carries no comment. The reasons below are derived from the build settings and from the package documents; they describe why no key is needed, not a recorded decision.

Entitlement that is absent Why the app works without it
com.apple.security.app-sandbox The app is not sandboxed (ENABLE_APP_SANDBOX: NO). Consequently no file-access or network sandbox entitlement applies either.
com.apple.security.cs.disable-library-validation The only third-party library, DuckDB, is re-signed with the app's own identity (next section), so library validation stays on, for the app and for the embedded orix-sheet tool.
com.apple.security.cs.allow-jit, allow-unsigned-executable-memory No JIT and no in-process interpreter: Python runs as a separate process of an interpreter found on the Mac (docs/research/technology-evaluation.md; see python-runtime).
com.apple.security.cs.allow-dyld-environment-variables Not used by the app.
com.apple.security.get-task-allow A debugging entitlement; CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NO stops Xcode from injecting it and sign.sh fails if it is present. Notarization rejects it.
com.apple.security.automation.apple-events, camera, microphone, etc. No such capability is requested by the entitlements file.

Source: App/Resources/ORIXSheet.entitlements, project.yml, Scripts/sign.sh.

An empty entitlements file means the hardened runtime applies with no exception. That is the strictest configuration available to a non-sandboxed Developer ID app. It does not make the app sandboxed: the process has the user's file-system and network rights. What the app actually does with them is covered in security.md.

# DuckDB re-signing

The data engine links the official DuckDB shared library, fetched by Scripts/fetch-duckdb.sh (not kept in git) and wrapped in Vendor/duckdb/CDuckDB.xcframework.

Fact Value Observed with
Vendored file Vendor/duckdb/dl/libduckdb.dylib, 133,735,472 bytes, x86_64 arm64 ls -l, lipo -archs
Upstream signature Developer ID Application: Stichting DuckDB Foundation (7NCTQWA3HA), hardened runtime codesign -dvv on the vendored file
Location in a built app Contents/Frameworks/libduckdb.dylib Debug product in build/DerivedData, Release bundle in dist/
Signature in the Debug product Apple Development: Simon-Pierre Boucher (NYGTAPU4ZN) (re-signed by Xcode's embed step) codesign -dvv on the embedded copy
Signature in the Release bundle Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), flags=0x10000(runtime), timestamp Nov 21, 2026 at 3:50:29 AM, 133,735,472 bytes, x86_64 arm64 codesign -dvv, ls -l, lipo -archs on dist/ORIX Sheet.app/Contents/Frameworks/libduckdb.dylib

Source: commands run on 2026-11-21 against the working tree; Packages/SheetData/README.md ("Embedding DuckDB in the app") for the requirement.

Because the upstream library is signed by another team, a hardened-runtime app with library validation would refuse to load it unchanged. sign.sh handles it with its first loop: the file matches *.dylib, is Mach-O, and is therefore signed with the Developer ID identity, a timestamp and the hardened runtime, replacing the upstream signature; the final loop then requires TeamIdentifier=3YM54G49SN on it.

Not done: the library is not thinned. Packages/SheetData/README.md notes that lipo -thin arm64 would save about 68 MB; the Release configuration is universal, so both slices ship.

# State of dist/ORIX Sheet.app observed on 2026-11-21

A signed Release bundle was produced by Scripts/sign.sh on 2026-11-21. The table is a read-only inspection of that bundle (codesign -dvv, codesign --verify, lipo, otool -l, find, du).

Property Observed
Identifier ai.spboucher.orix.sheet
Format app bundle with Mach-O universal (x86_64 arm64)
Flags 0x10000(runtime) (hardened runtime)
Authority Developer ID Application: Simon-Pierre Boucher (3YM54G49SN) → Developer ID Certification Authority → Apple Root CA
Timestamp Nov 21, 2026 at 3:50:32 AM
Runtime version 27.2.0
Entitlements in the signature empty dictionary; no get-task-allow
codesign --verify --deep --strict passes
Version 1.0.0
Bundle size 259 MB (du -sh)
Mach-O files in the bundle 3, all universal (x86_64 arm64), all signed by team 3YM54G49SN with the hardened runtime and a secure timestamp
Contents/MacOS/ORIX Sheet main executable, 99,143,360 bytes
Contents/MacOS/orix-sheet embedded command-line tool, 36,545,024 bytes; runpaths /usr/lib/swift and @executable_path/../Frameworks; orix-sheet version prints orix-sheet 1.0.0 (473 worksheet functions, DuckDB v2.0.1, workflow schema 1)
Contents/Frameworks/libduckdb.dylib 133,735,472 bytes, re-signed (previous section)
Contents/Resources 14 resource bundles of the packages, Assets.car, AppIcon.icns, fr-CA.lproj, Metadata.appintents

Source: codesign -dvv, codesign -d --entitlements - --xml, codesign --verify --deep --strict, lipo -archs, otool -l, ls -l, du -sh on dist/ORIX Sheet.app and its three Mach-O files, run on 2026-11-21.

The DuckDB re-signing path and the tool-embedding step of sign.sh are therefore observed on a Release bundle. Notarization, stapling, checksums and the Gatekeeper assessment of this bundle are not recorded here: see RELEASE-REPORT.md.

# Known limits of the script

  • The team identifier in the verification loop is a literal; signing with another team's Developer ID would build correctly and then fail verification.
  • Build warnings are filtered out of the console output; only errors and the build result are shown.
  • The script signs dist/ORIX Sheet.app in place. There is no dry-run mode and no option to sign an existing bundle without rebuilding.
  • No xcodebuild archive/exportArchive is used; the Release product of a plain build is taken. dSYM handling is not part of the script.
Files main
Menu

Theme