SPB Git

Repository Public License

setup.md 15.5 KB

# Development setup

ORIX Secure is a native iOS/iPadOS app (deployment target iOS 18.0) written in Swift 6 language mode with SwiftUI. It has no third-party code: every dependency is a local Swift package under Packages/.

# Requirements

Tool Version used for this repository Needed for
macOS 27.0 everything
Xcode 27.2 (27B52), Apple Swift 6.4.2 building, simulators, swift test
XcodeGen 2.45.4 generating ORIXSecure.xcodeproj from project.yml
Python 3 3.14 Scripts/localize.py, Scripts/shots.py
Pillow 12.2 Scripts/seed-photos.sh (test images), Scripts/shots.py on iPad, icon generation
rsvg-convert (librsvg) Homebrew only to regenerate the icon (design/icon/*.py)
openssl system optional: some ORIXNetworkLab tests generate certificates and start a loopback TLS server; they print a note and skip their live part without it

Older toolchains were not tried. The packages declare swift-tools-version: 6.0 and swiftLanguageModes: [.v6]; the app builds with SWIFT_VERSION 6.0 and SWIFT_STRICT_CONCURRENCY complete.

bash
brew install xcodegen librsvg
python3 -m pip install Pillow

# Getting the project

bash
git clone https://git.spboucher.ai/orix-secure.git ORIXSecure
cd ORIXSecure
Scripts/build.sh generate      # ORIXSecure.xcodeproj is git-ignored: generate it first
open ORIXSecure.xcodeproj      # or stay on the command line

The Xcode project is an output. Change project.yml and regenerate; never edit the project by hand.

# Build and test commands

Scripts/build.sh <step> prints a filtered summary and keeps the full logs in build/logs/.

Command What it does
Scripts/build.sh generate xcodegen generate
Scripts/build.sh kit swift test in every package that has a Tests folder, on the host Mac (debug); one summary line per package, logs in build/logs/kit-<package>.log
Scripts/build.sh debug Debug build of the app for the simulator named by ORIX_SIM
Scripts/build.sh release Release build for the generic iOS Simulator destination
Scripts/build.sh uitest [xcodebuild args] boots the simulator, re-seeds its photo library, runs ORIXSecureUITests, writes build/results/uitest-<sim>.xcresult and exports the attachments to build/shots/<sim>/
Scripts/build.sh all generate, kit, debug, uitest in sequence
Scripts/benchmark.sh [package …] release-mode engine measurements on the host Mac, see performance.md
Scripts/check.sh repository hygiene, see below

Everything Xcode builds goes to build/DerivedData (git-ignored). A single package can be tested directly:

bash
cd Packages/ORIXURLRisk && swift test
cd Packages/ORIXURLRisk && swift test --filter Corpora

Extra xcodebuild arguments pass through uitest, for example one test:

bash
Scripts/build.sh uitest -only-testing:ORIXSecureUITests/ORIXSecureUITests/testNetworkLabRunsLiveProbes

# Simulators

The scripts address simulators by name, through the ORIX_SIM environment variable:

Name Use
ORIXSecure iPhone default for every script
ORIXSecure iPad ORIX_SIM="ORIXSecure iPad" Scripts/build.sh uitest

Create them once, with any installed iOS runtime and device type (the 2026-11-21 test run used iOS 26.5):

bash
xcrun simctl list devicetypes | grep -E "iPhone|iPad"
xcrun simctl create "ORIXSecure iPhone" "<an iPhone device type>"
xcrun simctl create "ORIXSecure iPad" "<an iPad device type>"

# Launch arguments

Defined in App/Sources/Debug/LaunchOptions.swift. They are read only in Debug builds (#if DEBUG); a Release build ignores all of them.

Argument Effect
-ORIXUITest YES in-memory store, a separate UserDefaults suite (ai.spboucher.orix.secure.uitest), UIKit animations off, welcome screen skipped unless -ORIXWelcome YES
-ORIXReset YES resets the settings at launch
-ORIXWelcome YES with -ORIXUITest, shows the first-launch welcome screen
-ORIXDemo YES answers part of the checklists the way a person would and saves three reports produced by the real engines (security, privacy, device). No fabricated findings.
-ORIXSection <destination> opens a screen directly: dashboard, securityAudit, checklist, privacy, investigations, storage, photoCleanup, fileCleanup, linkAnalyzer, fileScanner, network, device, battery, reports, actions, settings
-ORIXAppearance system|light|dark forces the appearance setting
-ORIXLink <url> opens the Link Analyser with this link
-ORIXSampleFile YES writes a real ZIP archive (invoice.pdf.zip, with a traversal-named entry) in the temporary directory and hands it to the File Scanner
-ORIXSampleFolder YES writes a real folder (three byte-identical files, one different file of the same size, one larger file) and hands it to File Cleanup

Precedence when several are given: sample file, then sample folder, then link, then section.

The UI tests also pass the standard -AppleLanguages (en) and -AppleLocale en_CA.

# Scripts/sim.sh — launch and screenshot

bash
Scripts/build.sh debug
Scripts/sim.sh build/shots/dash.png 3 -ORIXUITest YES -ORIXDemo YES -ORIXSection dashboard
ORIX_SIM="ORIXSecure iPad" Scripts/sim.sh build/shots/ipad.png 3 -ORIXUITest YES -ORIXDemo YES -ORIXAppearance dark

Usage: sim.sh <out.png> <seconds> [launch arguments…]. It boots the simulator, installs build/DerivedData/Build/Products/Debug-iphonesimulator/ORIXSecure.app, relaunches the app with the arguments, waits and saves a screenshot. It needs a Debug build first.

# Scripts/seed-photos.sh — test photo library

Generates 12 PNG images in build/fixtures/photos (six different scenes, three byte-identical copies, a smaller and a larger rendering of the same scene, a brighter variant), adds them to the simulator's photo library with simctl addmedia, and resets the app's photo permission so the UI tests go through the real system prompt. build.sh uitest runs it before every run because the photo tests delete photos for real. Running it repeatedly adds the images again; erase the simulator's content to start from an empty library.

# Scripts/shots.py — screenshots of a UI test run

bash
python3 Scripts/shots.py ORIXSecure_iPhone                        # → build/shots/ORIXSecure_iPhone/named/<name>.png
python3 Scripts/shots.py ORIXSecure_iPhone --hierarchy testName   # accessibility hierarchy captured at a failure

On iPad the captures are rotated by 90° because the framebuffer is captured in portrait while the tests run in landscape.

# Localization

The source language is English; the app ships French (Canada), fr-CA.

  1. App strings are SwiftUI LocalizedStringKeys and String(localized:), extracted by the compiler (SWIFT_EMIT_LOC_STRINGS).
  2. Engine strings go through one function, L(...), in Packages/ORIXSecureModel/Sources/ORIXSecureModel/Localization.swift. The key is the English sentence; interpolations become format arguments. L looks the key up in ORIXLocalization.bundle, which the app sets to .main at launch (App/Sources/Core/ORIXSecureApp.swift). The packages therefore carry no catalog of their own: their strings are translated by the app's catalog. In package tests no catalog is loaded and L returns the English text, which is why engine tests assert on English.
  3. The catalog is App/Resources/Localizable.xcstrings.
  4. The translations are kept in Scripts/translations-fr.json ({"translations": {"<English key>": "<French>"}}).

Workflow after adding or changing text:

bash
Scripts/build.sh debug          # produces the *.stringsdata files under build/DerivedData
python3 Scripts/localize.py     # syncs the catalog, merges the French table, checks it

localize.py:

  • runs xcrun xcstringstool sync with the .stringsdata of the last Debug simulator build (app, share extension and every engine package; UI tests excluded);
  • writes each French value from the table into the catalog, applying French spacing (no-break space before : ; ? ! and inside « »);
  • marks keys that are not text (%@, IPv4, SHA-256, ORIX Secure, …) as not translatable;
  • supports one/other plural variants for keys listed in its PLURALS table (empty at the time of writing);
  • reports stale keys and table entries that no longer match a key;
  • exits with status 1 if a key has no French translation, or if format specifiers or ${…} placeholders differ between the English key and its translation.

python3 Scripts/localize.py --no-sync skips the sync and only merges and checks.

# Scripts/check.sh — repository hygiene

Run it before every commit. It exits non-zero on any finding.

  • Headers: every *.swift, *.sh, *.py file and project.yml (tracked or untracked, not ignored) must contain Author: Simon-Pierre Boucher in its first 12 lines.
  • Signing material: no .p8, .p12, .cer, .mobileprovision, .provisionprofile, .keychain, .pem, .env or AuthKey_* file.
  • Credentials in content: private-key blocks, key/secret/token/password assignments, issuer identifiers, common token prefixes.
  • Private network addresses in docs, scripts and configuration (Swift sources and the string catalog are exempt: the URL and network engines and their tests legitimately contain example addresses).
  • Remote dependencies: any .package(url: in a package manifest or in project.yml fails the check.

Markdown files are not covered by the header check; add the header by hand (see the top of this file).

# Project structure

text
ORIXSecure/
├── project.yml                     XcodeGen definition: app, share extension, UI tests, local packages
├── App/
│   ├── Resources/                  Info.plist, entitlements, PrivacyInfo.xcprivacy, Localizable.xcstrings, Assets.xcassets
│   └── Sources/
│       ├── Core/                   ORIXSecureApp, AppModel, AppSettings, AppLock, LocalStore, Router, RootView,
│       │                           Presentation (finding rows, badges, ring), ReportBuilders
│       ├── Debug/                  LaunchOptions (launch arguments, demo content)
│       ├── Features/               one folder per screen group:
│       │                           Actions, Battery, Dashboard, DeviceDiagnostics, FileScanner, Investigations,
│       │                           Network, PhotoCleanup, Privacy, Reports, SecurityAudit, Settings, Storage, URLAnalysis
│       └── Platform/               ActivityView (share sheet), QRReading
├── ShareExtension/                 share extension: analyses a shared link (ORIXDesign, ORIXSecureModel, ORIXURLRisk)
├── UITests/ORIXSecureUITests.swift 23 XCUITests
├── Packages/
│   ├── ORIXDesign/                 tokens, components, haptics (no tests)
│   ├── ORIXSecureModel/            Finding, Reading, ReportDocument, L() localization
│   ├── ORIXSecureEngines/          security assessment, checklist, privacy audit, storage, device diagnostics, investigations
│   ├── ORIXURLRisk/                link analyzer: parsing, Punycode, scripts, confusables, brands, QR payloads
│   ├── ORIXFileInspection/         magic numbers, file names, ZIP/TAR/GZIP, PDF, structure checks, hashing, duplicates, removal
│   ├── ORIXNetworkLab/             connectivity, interfaces, Wi-Fi, DNS, latency, TLS, X.509/DER, HTTPS probe, Bonjour
│   ├── ORIXMediaCleanup/           fingerprints, cache, grouping, plan, Photos scanner, measurer, deleter
│   └── ORIXReporting/              two products: ORIXReporting (PDF, Markdown, text, JSON, redaction) and ORIXWorkflow
├── Scripts/                        build.sh, benchmark.sh, check.sh, release.sh, sim.sh, seed-photos.sh, shots.py,
│                                   localize.py, translations-fr.json, ExportOptions.plist
├── design/icon/                    build.py, concepts.py, contact.py, master/ (SVG masters), concepts/ (SVG concepts)
├── docs/                           architecture/, research/, development/, design/, assets/
└── build/                          git-ignored: DerivedData, logs, results, shots, fixtures, benchmarks

Dependency rule: ORIXSecureModel depends on nothing; every engine package depends only on ORIXSecureModel; ORIXDesign depends on nothing; only the app (and the share extension) links them together.

# Adding an engine package

  1. Create Packages/ORIX<Name>/Package.swift on the model of Packages/ORIXURLRisk/Package.swift: tools version 6.0, the author header, defaultLocalization: "en", platforms: [.iOS(.v18), .macOS(.v15)] (macOS is what lets swift test run on the host), a dependency on ../ORIXSecureModel only, a test target, swiftLanguageModes: [.v6].
  2. Put sources in Sources/ORIX<Name>/ and tests in Tests/ORIX<Name>Tests/, each file with the author header.
  3. Return results as Finding, Reading and ReportDocument values from ORIXSecureModel. A value that cannot be read is Reading.unavailable with a reason, never a default. Write user-facing text through L(...).
  4. Keep platform frameworks behind #if canImport(...) so the logic stays testable on macOS (see PhotoLibraryScanner.swift).
  5. Register the package in project.yml: one line under packages: and one under the ORIXSecure target's dependencies:. Run Scripts/build.sh generate.
  6. Add tests in the style of the existing ones: no finding without evidence, the forbidden-word check, fuzzing for any parser of untrusted input, a printed measurement for anything whose cost grows with input size. If it prints measurements, add the package to the default list in Scripts/benchmark.sh.
  7. Scripts/build.sh kit picks the package up automatically. Build the app, then run Scripts/localize.py and add the French translations of the new strings.
  8. Scripts/check.sh.

# Signing and release

  • The team identifier (DEVELOPMENT_TEAM) and CODE_SIGN_STYLE: Automatic are set in project.yml; the same team identifier is in Scripts/ExportOptions.plist. Bundle identifiers: ai.spboucher.orix.secure, ai.spboucher.orix.secure.share, ai.spboucher.orix.secure.uitests.
  • Simulator builds and UI tests need no signing identity. Device builds and archives use automatic signing with the Apple ID configured in Xcode. To build under another team, change DEVELOPMENT_TEAM and the bundle identifier prefix.
  • The app has one entitlement, com.apple.developer.networking.wifi-info (App/Resources/ORIXSecure.entitlements).
  • No secret is stored in the repository. .gitignore excludes keys, certificates, profiles and .env files, and Scripts/check.sh fails if one appears.
  • Scripts/release.sh archive | export | validate | upload reads the App Store Connect API key identifiers (ASC_KEY_ID, ASC_ISSUER_ID) from the environment or from ~/.config/orix-secure/asc.env, outside the repository; the .p8 file stays in ~/.appstoreconnect/private_keys/. archive writes build/ORIXSecure.xcarchive (its own derived data in build/DerivedData-release), export writes dist/export/, validate runs altool --validate-app.
  • upload sends a build to Apple and refuses to run unless ORIX_UPLOAD_AUTHORIZED=yes is set. Set it only once the owner has authorized that build.
  • Version and build number are MARKETING_VERSION and CURRENT_PROJECT_VERSION in project.yml.
Files main
Menu

Theme