SPB Git

Repository Public License

overview.md 15.0 KB

# ORIX Secure — Architecture overview

ORIX Secure is an iOS/iPadOS 18+ app (Swift 6 language mode, strict concurrency complete, SwiftUI) built from eight local Swift packages, one app target and one share extension. The project is generated by XcodeGen from project.yml. There is no third-party dependency and no server.

Companion documents: security-engine.md, diagnostics.md, storage.md, network.md, privacy.md.

# 1. Module map

An arrow A --> B reads "A depends on B".

graph TD
    subgraph Targets
        APP["ORIXSecure (app)<br/>App/Sources: Core, Features, Platform, Debug"]
        EXT["ORIXSecureShare (share extension)<br/>ShareExtension/Sources"]
        UIT["ORIXSecureUITests"]
    end
    subgraph Packages
        MODEL["ORIXSecureModel<br/>Reading, Finding, ReportDocument, L()"]
        ENG["ORIXSecureEngines<br/>probes, assessment, checklist, privacy,<br/>storage, diagnostics, investigations"]
        URL["ORIXURLRisk<br/>URL parser, risk analyzer, QR classifier"]
        FILE["ORIXFileInspection<br/>file inspector, duplicates, large files, remover"]
        NET["ORIXNetworkLab<br/>path, interfaces, DNS, TCP, TLS, HTTPS, Bonjour, Wi-Fi"]
        MEDIA["ORIXMediaCleanup<br/>fingerprints, analyzer, plan, Photos adaptors"]
        REP["ORIXReporting<br/>PDF / Markdown / JSON / text, redaction"]
        WF["ORIXWorkflow<br/>(second target of the ORIXReporting package)"]
        DES["ORIXDesign<br/>tokens, components, haptics"]
    end
    ENG --> MODEL
    URL --> MODEL
    FILE --> MODEL
    NET --> MODEL
    MEDIA --> MODEL
    REP --> MODEL
    WF --> MODEL
    APP --> ENG
    APP --> URL
    APP --> FILE
    APP --> NET
    APP --> MEDIA
    APP --> REP
    APP --> WF
    APP --> DES
    APP --> MODEL
    APP -. embeds .-> EXT
    EXT --> URL
    EXT --> DES
    EXT --> MODEL
    UIT -. tests .-> APP

Facts taken from the Package.swift files and project.yml:

  • Every engine package depends on ORIXSecureModel only. No engine package depends on another engine package.
  • ORIXDesign depends on nothing and is the only package that imports SwiftUI.
  • All packages declare platforms: [.iOS(.v18), .macOS(.v15)] and swiftLanguageModes: [.v6], so the package tests run on a Mac with swift test.
  • ORIXReporting (renderers) and ORIXWorkflow (workflow runner) are two independent targets of one package; neither imports the other.
  • The share extension links ORIXDesign, ORIXSecureModel and ORIXURLRisk only.

# Rule: diagnostics never import SwiftUI

No file under Packages/*/Sources other than ORIXDesign imports SwiftUI. Engines return value types (Finding, Reading, reports); views live in App/Sources/Features. Two engine files import UIKit behind #if canImport(UIKit), because the data they read exists only there:

File UIKit use
ORIXSecureEngines/SystemDeviceProbe.swift UIDevice (model, system name, idiom, battery), UIScreen via the first UIWindowScene
ORIXMediaCleanup/PhotoLibraryScanner.swift UIImage.cgImage of the thumbnail returned by PHImageManager (AppKit on macOS)

# 2. Result vocabulary (ORIXSecureModel)

Type Role
Reading<Value> .measured(Value) or .unavailable(Unavailability). Unavailability.Kind: notExposedByiOS, permissionRequired, entitlementRequired, unsupportedOnDevice, simulator, failed, notRequested, plus a localized detail.
Finding One assessed item: id, category, title, state, severity, confidence, verification, evidence, explanation, recommendation, notInspected, assessedAt.
AssessmentState verified, attention, userConfirmed, userConfirmationRequired, notAvailable, notAssessed. There is no "secure" or "safe" case.
Severity none < low < moderate < high (Comparable).
Confidence measured, heuristic, userReported, none.
VerificationMethod publicAPI, parsedData, heuristic, userConfirmed, notVerifiable.
Evidence label, value, optional technical source (an API name, "user", "URL parsing"); the source is not localized.
FindingCategory device, authentication, appIntegrity, network, privacy, storage, url, file, account, configuration, performance.
ReportDocument Format-neutral report: kind, title, summary, sections (paragraphs, facts, findings, bullets), unavailable, generator.

Why Reading exists: iOS withholds many values (battery cycles, other apps' data, Wi-Fi details without permission). A field that can be missing is typed Reading<T>, so an engine cannot return a default in place of a value it did not obtain; the reason travels with the absence and is shown to the user. Engines turn an .unavailable reading into a notAvailable finding whose explanation is the detail (SecurityAssessmentEngine.passcodeFinding is the pattern).

userConfirmed is distinct from verified: it is produced only by SecurityChecklistEngine for a setting the app cannot read and the user reported as being in the expected condition, with confidence: .userReported and verification: .userConfirmed.

Helpers on Sequence<Finding>: prioritized() (attention first, then awaiting confirmation, then the rest; by descending severity, then title), count(_:), highestSeverity (over attention findings only).

# 3. Localization flow

  1. Engines write English source text through L(_ key: String.LocalizationValue) in ORIXSecureModel/Localization.swift; interpolations become format arguments.
  2. L resolves the key with String(localized:bundle:) against ORIXLocalization.bundle (and ORIXLocalization.locale when set). Both are nonisolated(unsafe) statics.
  3. ORIXSecureApp.init sets ORIXLocalization.bundle = .main before any engine runs; the app's string catalog is App/Resources/Localizable.xcstrings. The share extension also sets .main, which there is the extension bundle; project.yml adds the same Localizable.xcstrings to the extension target's sources so engine text is translated there too. InfoPlist.xcstrings files localize the Info.plist strings.
  4. In package tests no catalog is loaded and L returns the English source text.
  5. Scripts/localize.py is written to refresh the catalog from the compiler's extracted strings and merge French (Canada) translations from Scripts/translations-fr.json.

State of the resources: the catalog's source language is en; it holds 2111 keys, of which 2103 are translated to fr-CA and 8 are marked not translatable. Scripts/translations-fr.json holds the 2103 translations. The Xcode project's known regions are Base, en and fr-CA. Scripts/localize.py exits with code 1 when a translatable key lacks a French translation.

View text uses SwiftUI LocalizedStringKey / String(localized:) directly; technical evidence sources and brand names ("Face ID", "App Attest") are not localized.

# 4. Persistence

# SwiftData (App/Sources/Core/LocalStore.swift)

Model Unique key Fields Content
StoredReport id: UUID kindRaw, createdAt, title, summary, attentionCount, payload (@Attribute(.externalStorage)) The ReportDocument, JSON-encoded with ISO 8601 dates.
StoredAnswer itemID: String answerRaw, answeredAt One checklist answer per item; setAnswer deletes the previous row.
StoredWorkflow id: String name, createdAt, payload A user workflow definition, JSON-encoded.

LocalStore owns one ModelContainer and one ModelContext, keeps a revision counter that observing views read, and saves with try? context.save() after every mutation. If the on-disk store cannot be opened, ORIXSecureApp.init falls back to an in-memory store so the diagnostics stay usable. UI tests (-ORIXUITest YES) always use the in-memory configuration and a separate UserDefaults suite.

# Folders (AppFolders)

Folder Location Use
database Application Support/ORIXSecure/Database ORIXSecure.store (SwiftData).
caches Caches/ORIXSecure orix-media-fingerprints.cache (photo fingerprint cache).
exports tmp/ORIXSecureExports Files rendered for the share sheet.
temporary tmp/ORIXSecureWork Working files.

Saved reports have no folder of their own: they are rows of the SwiftData store.

File protection: AppFolders.prepare() (exports, temporary, caches) and LocalStore.init (database) create these directories with the attribute .protectionKey: FileProtectionType.complete. The code sets the attribute on the directories; it does not set a protection option on each file write (ReportGenerator.export writes with .withoutOverwriting only) and the entitlements file declares no data-protection entitlement. The protection class effectively applied to a new file in the container is measured at run time by SystemSecurityProbe.fileProtection and reported as the app.dataProtection finding (not available in the Simulator).

# UserDefaults (AppSettings)

appLockEnabled (default off), keepLinkHistory (default off), redactExports (default on), appearance, hasSeenWelcome.

# 5. Concurrency model

  • App and extension targets set SWIFT_DEFAULT_ACTOR_ISOLATION: MainActor. AppModel, LocalStore, Router, AppLock, AppSettings, NetworkController, PhotoCleanupController are @Observable classes isolated to the main actor by that default.
  • Packages have no default isolation. Engines are Sendable structs or caseless enums. Pure evaluators (SecurityAssessmentEngine.assess, DeviceDiagnosticsEngine, URLRiskAnalyzer.analyze, NetworkAssessment.findings, TLSAssessment.findings) are synchronous; I/O is async (DNSProbe.resolve, LatencyProbe.measure, TLSInspector.inspect, HTTPSProbe.head, CleanupPipeline.run, FileInspector.inspect, DuplicateFinder.findDuplicates).
  • DeviceProbing.snapshot() is the one engine entry point marked @MainActor (it touches UIKit).
  • Actors: PhotoLibraryScanner, WorkflowRunner, WorkflowContext.
  • Lock-protected @unchecked Sendable classes bridge callback APIs: ConnectivityMonitor, OneShot (resume-once continuation), PendingRequest (Photos requests), the Bonjour BrowseSession.
  • Opt-outs in the app target: nonisolated enum ReportBuilder, nonisolated static QRImageReader.payloads, nonisolated CLLocationManagerDelegate callback that hops back with Task { @MainActor in … }.
  • Engine progress callbacks are @Sendable; views re-enter the main actor with Task { @MainActor in … }.
  • Cancellation: long operations check Task.isCancelled / Task.checkCancellation(); a cancelled photo scan saves the fingerprint cache before throwing.

# 6. Navigation

Router.swift defines one Destination enum (16 cases: dashboard, securityAudit, checklist, privacy, investigations, storage, photoCleanup, fileCleanup, linkAnalyzer, fileScanner, network, device, battery, reports, actions, settings) and DestinationView maps each case to its screen.

Layout Condition in RootView Structure
TabLayout horizontalSizeClass != .regular (iPhone, and iPad in a compact width) TabView over AppTab (overview, security, storage, tools, reports), one NavigationStack per tab bound to Router.paths[tab]. The Tools tab root is ToolsHubView, which is not a Destination.
SidebarLayout horizontalSizeClass == .regular NavigationSplitView; sidebar list grouped as Security / Storage / Tools / Results, selection Router.sidebar, detail stack Router.sidebarPath.

Router.open(_:) updates both layouts at once (sidebar selection, tab, tab path). Router.push(_:) appends a Route (.destination, .investigation(Symptom), .report(UUID)) to both stacks. Incoming items are parked in pendingLink, pendingFile, pendingFolder and consumed by the target screen:

  • orixsecure://analyze?url=<link> opens the link analyser (ORIXSecureApp.handle checks the scheme orixsecure, the host analyze and the url query item; anything else is ignored);
  • a file URL (document type public.data, role Viewer, LSSupportsOpeningDocumentsInPlace false) opens the file scanner.

# 7. Local data architecture

graph LR
    subgraph Device["On the device"]
        subgraph Container["App container"]
            DB[("SwiftData store<br/>StoredReport, StoredAnswer, StoredWorkflow<br/>Application Support/ORIXSecure/Database")]
            UD[("UserDefaults<br/>5 preference keys")]
            CACHE[("Caches/ORIXSecure<br/>fingerprint cache: hashes, no images")]
            TMP[("tmp/ORIXSecureExports<br/>rendered export files")]
        end
        MEM["In memory only<br/>device snapshot, security signals,<br/>network change log (200 entries),<br/>probe results, cleanup analysis"]
        PHOTOS[("Photo library<br/>read through PhotoKit")]
        FILES[("Files the user picks<br/>security-scoped URLs")]
    end
    SHEET["System share sheet<br/>UIActivityViewController"]
    HOSTS["Hosts the user typed<br/>DNS, TCP, TLS, HEAD"]
    LAN["Local network<br/>Bonjour browse"]

    MEM -->|"Save as report"| DB
    PHOTOS -->|"thumbnails, never stored"| MEM
    PHOTOS -->|"fingerprints"| CACHE
    FILES -->|"bytes read, not copied"| MEM
    DB -->|"export, optionally redacted"| TMP
    TMP -->|"user action only"| SHEET
    MEM -.->|"probe packets, no user data"| HOSTS
    MEM -.->|"mDNS queries"| LAN
  • Stored: reports the user saved (or that a workflow, a file cleanup or the link history setting saved), checklist answers, workflows, preferences, photo fingerprints.
  • Never stored: photo pixels, file contents, the device name or serial number (ReportBuilder.deviceFacts writes the model identifier and system version only), the user's location.
  • Leaves the device only through the share sheet: an exported report file (ReportsView.export → ActivityView). There is no other upload path in the code.
  • Network traffic the app originates is limited to the probes described in network.md; they carry no user data beyond the host name being tested.

# 8. Verification status

  • This document was written from a reading of the sources listed above; the test suites were not re-run for it.
  • Package test targets exist for every package except ORIXDesign; UITests/ORIXSecureUITests.swift drives the app in the Simulator.
  • Data Protection, App Attest, battery readings, the Wi-Fi reading and the integrity checks return .unavailable(.simulator, …) or are skipped in the Simulator, so the corresponding paths have not been exercised on hardware. Photos, camera and Wi-Fi features were run in the Simulator or compiled only.
  • The French (Canada) catalog is complete by key count (section 3); its rendering in the running app was not checked here.
Files main
Menu

Theme