Repository Public License
1<!--2ORIX Secure3File: docs/development/setup.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Development setup910ORIX Secure is a native iOS/iPadOS app (deployment target iOS 18.0) written in Swift 6 language mode with SwiftUI.11It has no third-party code: every dependency is a local Swift package under `Packages/`.1213## Requirements1415| Tool | Version used for this repository | Needed for |16|---|---|---|17| macOS | 27.0 | everything |18| Xcode | 27.2 (27B52), Apple Swift 6.4.2 | building, simulators, `swift test` |19| XcodeGen | 2.45.4 | generating `ORIXSecure.xcodeproj` from `project.yml` |20| Python 3 | 3.14 | `Scripts/localize.py`, `Scripts/shots.py` |21| Pillow | 12.2 | `Scripts/seed-photos.sh` (test images), `Scripts/shots.py` on iPad, icon generation |22| `rsvg-convert` (librsvg) | Homebrew | only to regenerate the icon (`design/icon/*.py`) |23| `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 |2425Older toolchains were not tried. The packages declare `swift-tools-version: 6.0` and `swiftLanguageModes: [.v6]`;26the app builds with `SWIFT_VERSION 6.0` and `SWIFT_STRICT_CONCURRENCY complete`.2728```bash29brew install xcodegen librsvg30python3 -m pip install Pillow31```3233## Getting the project3435```bash36git clone https://git.spboucher.ai/orix-secure.git ORIXSecure37cd ORIXSecure38Scripts/build.sh generate # ORIXSecure.xcodeproj is git-ignored: generate it first39open ORIXSecure.xcodeproj # or stay on the command line40```4142The Xcode project is an output. Change `project.yml` and regenerate; never edit the project by hand.4344## Build and test commands4546`Scripts/build.sh <step>` prints a filtered summary and keeps the full logs in `build/logs/`.4748| Command | What it does |49|---|---|50| `Scripts/build.sh generate` | `xcodegen generate` |51| `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` |52| `Scripts/build.sh debug` | Debug build of the app for the simulator named by `ORIX_SIM` |53| `Scripts/build.sh release` | Release build for the generic iOS Simulator destination |54| `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>/` |55| `Scripts/build.sh all` | `generate`, `kit`, `debug`, `uitest` in sequence |56| `Scripts/benchmark.sh [package …]` | release-mode engine measurements on the host Mac, see [performance.md](performance.md) |57| `Scripts/check.sh` | repository hygiene, see below |5859Everything Xcode builds goes to `build/DerivedData` (git-ignored). A single package can be tested directly:6061```bash62cd Packages/ORIXURLRisk && swift test63cd Packages/ORIXURLRisk && swift test --filter Corpora64```6566Extra `xcodebuild` arguments pass through `uitest`, for example one test:6768```bash69Scripts/build.sh uitest -only-testing:ORIXSecureUITests/ORIXSecureUITests/testNetworkLabRunsLiveProbes70```7172## Simulators7374The scripts address simulators by name, through the `ORIX_SIM` environment variable:7576| Name | Use |77|---|---|78| `ORIXSecure iPhone` | default for every script |79| `ORIXSecure iPad` | `ORIX_SIM="ORIXSecure iPad" Scripts/build.sh uitest` |8081Create them once, with any installed iOS runtime and device type (the 2026-11-21 test run used iOS 26.5):8283```bash84xcrun simctl list devicetypes | grep -E "iPhone|iPad"85xcrun simctl create "ORIXSecure iPhone" "<an iPhone device type>"86xcrun simctl create "ORIXSecure iPad" "<an iPad device type>"87```8889## Launch arguments9091Defined in `App/Sources/Debug/LaunchOptions.swift`. They are read only in Debug builds (`#if DEBUG`); a Release build92ignores all of them.9394| Argument | Effect |95|---|---|96| `-ORIXUITest YES` | in-memory store, a separate `UserDefaults` suite (`ai.spboucher.orix.secure.uitest`), UIKit animations off, welcome screen skipped unless `-ORIXWelcome YES` |97| `-ORIXReset YES` | resets the settings at launch |98| `-ORIXWelcome YES` | with `-ORIXUITest`, shows the first-launch welcome screen |99| `-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. |100| `-ORIXSection <destination>` | opens a screen directly: `dashboard`, `securityAudit`, `checklist`, `privacy`, `investigations`, `storage`, `photoCleanup`, `fileCleanup`, `linkAnalyzer`, `fileScanner`, `network`, `device`, `battery`, `reports`, `actions`, `settings` |101| `-ORIXAppearance system\|light\|dark` | forces the appearance setting |102| `-ORIXLink <url>` | opens the Link Analyser with this link |103| `-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 |104| `-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 |105106Precedence when several are given: sample file, then sample folder, then link, then section.107108The UI tests also pass the standard `-AppleLanguages (en)` and `-AppleLocale en_CA`.109110## `Scripts/sim.sh` — launch and screenshot111112```bash113Scripts/build.sh debug114Scripts/sim.sh build/shots/dash.png 3 -ORIXUITest YES -ORIXDemo YES -ORIXSection dashboard115ORIX_SIM="ORIXSecure iPad" Scripts/sim.sh build/shots/ipad.png 3 -ORIXUITest YES -ORIXDemo YES -ORIXAppearance dark116```117118Usage: `sim.sh <out.png> <seconds> [launch arguments…]`. It boots the simulator, installs119`build/DerivedData/Build/Products/Debug-iphonesimulator/ORIXSecure.app`, relaunches the app with the arguments, waits120and saves a screenshot. It needs a Debug build first.121122## `Scripts/seed-photos.sh` — test photo library123124Generates 12 PNG images in `build/fixtures/photos` (six different scenes, three byte-identical copies, a smaller and a125larger rendering of the same scene, a brighter variant), adds them to the simulator's photo library with126`simctl addmedia`, and resets the app's photo permission so the UI tests go through the real system prompt.127`build.sh uitest` runs it before every run because the photo tests delete photos for real. Running it repeatedly adds128the images again; erase the simulator's content to start from an empty library.129130## `Scripts/shots.py` — screenshots of a UI test run131132```bash133python3 Scripts/shots.py ORIXSecure_iPhone # → build/shots/ORIXSecure_iPhone/named/<name>.png134python3 Scripts/shots.py ORIXSecure_iPhone --hierarchy testName # accessibility hierarchy captured at a failure135```136137On iPad the captures are rotated by 90° because the framebuffer is captured in portrait while the tests run in landscape.138139## Localization140141The source language is English; the app ships French (Canada), `fr-CA`.1421431. **App strings** are SwiftUI `LocalizedStringKey`s and `String(localized:)`, extracted by the compiler144 (`SWIFT_EMIT_LOC_STRINGS`).1452. **Engine strings** go through one function, `L(...)`, in146 `Packages/ORIXSecureModel/Sources/ORIXSecureModel/Localization.swift`. The key is the English sentence;147 interpolations become format arguments. `L` looks the key up in `ORIXLocalization.bundle`, which the app sets to148 `.main` at launch (`App/Sources/Core/ORIXSecureApp.swift`). The packages therefore carry no catalog of their own:149 their strings are translated by the app's catalog. In package tests no catalog is loaded and `L` returns the English150 text, which is why engine tests assert on English.1513. **The catalog** is `App/Resources/Localizable.xcstrings`.1524. **The translations** are kept in `Scripts/translations-fr.json` (`{"translations": {"<English key>": "<French>"}}`).153154Workflow after adding or changing text:155156```bash157Scripts/build.sh debug # produces the *.stringsdata files under build/DerivedData158python3 Scripts/localize.py # syncs the catalog, merges the French table, checks it159```160161`localize.py`:162163- runs `xcrun xcstringstool sync` with the `.stringsdata` of the last Debug simulator build (app, share extension and164 every engine package; UI tests excluded);165- writes each French value from the table into the catalog, applying French spacing (no-break space before `: ; ? !`166 and inside `« »`);167- marks keys that are not text (`%@`, `IPv4`, `SHA-256`, `ORIX Secure`, …) as not translatable;168- supports one/other plural variants for keys listed in its `PLURALS` table (empty at the time of writing);169- reports stale keys and table entries that no longer match a key;170- exits with status 1 if a key has no French translation, or if format specifiers or `${…}` placeholders differ171 between the English key and its translation.172173`python3 Scripts/localize.py --no-sync` skips the sync and only merges and checks.174175## `Scripts/check.sh` — repository hygiene176177Run it before every commit. It exits non-zero on any finding.178179- **Headers**: every `*.swift`, `*.sh`, `*.py` file and `project.yml` (tracked or untracked, not ignored) must contain180 `Author: Simon-Pierre Boucher` in its first 12 lines.181- **Signing material**: no `.p8`, `.p12`, `.cer`, `.mobileprovision`, `.provisionprofile`, `.keychain`, `.pem`,182 `.env` or `AuthKey_*` file.183- **Credentials in content**: private-key blocks, key/secret/token/password assignments, issuer identifiers, common184 token prefixes.185- **Private network addresses** in docs, scripts and configuration (Swift sources and the string catalog are exempt:186 the URL and network engines and their tests legitimately contain example addresses).187- **Remote dependencies**: any `.package(url:` in a package manifest or in `project.yml` fails the check.188189Markdown files are not covered by the header check; add the header by hand (see the top of this file).190191## Project structure192193```194ORIXSecure/195├── project.yml XcodeGen definition: app, share extension, UI tests, local packages196├── App/197│ ├── Resources/ Info.plist, entitlements, PrivacyInfo.xcprivacy, Localizable.xcstrings, Assets.xcassets198│ └── Sources/199│ ├── Core/ ORIXSecureApp, AppModel, AppSettings, AppLock, LocalStore, Router, RootView,200│ │ Presentation (finding rows, badges, ring), ReportBuilders201│ ├── Debug/ LaunchOptions (launch arguments, demo content)202│ ├── Features/ one folder per screen group:203│ │ Actions, Battery, Dashboard, DeviceDiagnostics, FileScanner, Investigations,204│ │ Network, PhotoCleanup, Privacy, Reports, SecurityAudit, Settings, Storage, URLAnalysis205│ └── Platform/ ActivityView (share sheet), QRReading206├── ShareExtension/ share extension: analyses a shared link (ORIXDesign, ORIXSecureModel, ORIXURLRisk)207├── UITests/ORIXSecureUITests.swift 23 XCUITests208├── Packages/209│ ├── ORIXDesign/ tokens, components, haptics (no tests)210│ ├── ORIXSecureModel/ Finding, Reading, ReportDocument, L() localization211│ ├── ORIXSecureEngines/ security assessment, checklist, privacy audit, storage, device diagnostics, investigations212│ ├── ORIXURLRisk/ link analyzer: parsing, Punycode, scripts, confusables, brands, QR payloads213│ ├── ORIXFileInspection/ magic numbers, file names, ZIP/TAR/GZIP, PDF, structure checks, hashing, duplicates, removal214│ ├── ORIXNetworkLab/ connectivity, interfaces, Wi-Fi, DNS, latency, TLS, X.509/DER, HTTPS probe, Bonjour215│ ├── ORIXMediaCleanup/ fingerprints, cache, grouping, plan, Photos scanner, measurer, deleter216│ └── ORIXReporting/ two products: ORIXReporting (PDF, Markdown, text, JSON, redaction) and ORIXWorkflow217├── Scripts/ build.sh, benchmark.sh, check.sh, release.sh, sim.sh, seed-photos.sh, shots.py,218│ localize.py, translations-fr.json, ExportOptions.plist219├── design/icon/ build.py, concepts.py, contact.py, master/ (SVG masters), concepts/ (SVG concepts)220├── docs/ architecture/, research/, development/, design/, assets/221└── build/ git-ignored: DerivedData, logs, results, shots, fixtures, benchmarks222```223224Dependency rule: `ORIXSecureModel` depends on nothing; every engine package depends only on `ORIXSecureModel`;225`ORIXDesign` depends on nothing; only the app (and the share extension) links them together.226227## Adding an engine package2282291. Create `Packages/ORIX<Name>/Package.swift` on the model of `Packages/ORIXURLRisk/Package.swift`: tools version 6.0,230 the author header, `defaultLocalization: "en"`, `platforms: [.iOS(.v18), .macOS(.v15)]` (macOS is what lets231 `swift test` run on the host), a dependency on `../ORIXSecureModel` only, a test target, `swiftLanguageModes: [.v6]`.2322. Put sources in `Sources/ORIX<Name>/` and tests in `Tests/ORIX<Name>Tests/`, each file with the author header.2333. Return results as `Finding`, `Reading` and `ReportDocument` values from `ORIXSecureModel`. A value that cannot be234 read is `Reading.unavailable` with a reason, never a default. Write user-facing text through `L(...)`.2354. Keep platform frameworks behind `#if canImport(...)` so the logic stays testable on macOS (see236 `PhotoLibraryScanner.swift`).2375. Register the package in `project.yml`: one line under `packages:` and one under the `ORIXSecure` target's238 `dependencies:`. Run `Scripts/build.sh generate`.2396. Add tests in the style of the existing ones: no finding without evidence, the forbidden-word check, fuzzing for240 any parser of untrusted input, a printed measurement for anything whose cost grows with input size. If it prints241 measurements, add the package to the default list in `Scripts/benchmark.sh`.2427. `Scripts/build.sh kit` picks the package up automatically. Build the app, then run `Scripts/localize.py` and add243 the French translations of the new strings.2448. `Scripts/check.sh`.245246## Signing and release247248- The team identifier (`DEVELOPMENT_TEAM`) and `CODE_SIGN_STYLE: Automatic` are set in `project.yml`; the same team249 identifier is in `Scripts/ExportOptions.plist`. Bundle identifiers: `ai.spboucher.orix.secure`,250 `ai.spboucher.orix.secure.share`, `ai.spboucher.orix.secure.uitests`.251- Simulator builds and UI tests need no signing identity. Device builds and archives use automatic signing with the252 Apple ID configured in Xcode. To build under another team, change `DEVELOPMENT_TEAM` and the bundle identifier prefix.253- The app has one entitlement, `com.apple.developer.networking.wifi-info` (`App/Resources/ORIXSecure.entitlements`).254- **No secret is stored in the repository.** `.gitignore` excludes keys, certificates, profiles and `.env` files, and255 `Scripts/check.sh` fails if one appears.256- `Scripts/release.sh archive | export | validate | upload` reads the App Store Connect API key identifiers257 (`ASC_KEY_ID`, `ASC_ISSUER_ID`) from the environment or from `~/.config/orix-secure/asc.env`, outside the258 repository; the `.p8` file stays in `~/.appstoreconnect/private_keys/`. `archive` writes259 `build/ORIXSecure.xcarchive` (its own derived data in `build/DerivedData-release`), `export` writes260 `dist/export/`, `validate` runs `altool --validate-app`.261- `upload` sends a build to Apple and refuses to run unless `ORIX_UPLOAD_AUTHORIZED=yes` is set. Set it only once262 the owner has authorized that build.263- Version and build number are `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION` in `project.yml`.264