Architecture Diagram
How the system fits together
This visual is meant to show the operating shape of the project at a glance: where input begins, where decisions happen, and what the useful output surface actually is.
Diagram of SpectreFS showing an encrypted vault, mounted plaintext view, trusted-app access control, and native desktop tooling.
Snapshot
What matters most in this project
Challenge
The hard part was making security and usability coexist: random-access encrypted IO, Finder-compatible metadata, trusted-app enforcement, recovery flows, and macOS distribution constraints all had to work together without hand-waving the tradeoffs.
Result
SpectreFS now operates as a multi-surface security product: encrypted mounted vaults for direct distribution, a native desktop experience for day-to-day use, and an in-place protection path that moves the codebase closer to sandbox-compatible packaging.
Approach
- Designed the vault runtime around transparent encryption at rest, authenticated chunk records, encrypted metadata sidecars, and filename protection so normal file workflows still behave predictably.
- Built `spectrefsctl` maintenance and in-place flows for vault creation, password rotation, health checks, repair, snapshots, and interrupted-work recovery.
- Expanded the project into a native macOS desktop wrapper and release path with signed direct distribution, notarization support, and a separate no-FUSE mode for sandbox-oriented packaging.
Architecture
- Encrypted vault data lives on disk while a mounted or in-place workflow exposes plaintext only at the interaction boundary needed by trusted apps.
- Crypto and key-management layers use Argon2id-derived credentials, wrapped master keys, and authenticated chunk records to protect both contents and metadata sidecars.
- Operational tooling spans `spectrefs`, `spectrefsctl`, native SwiftUI screens, local audit/history data, and release scripts for packaging, signing, notarization, and regression checks.
Impact
Turned a local encryption tool into a product-shaped system with chunk-authenticated storage, process-based access control, native app flows, and packaging automation instead of stopping at a command-line prototype.
- Encrypts file contents, filenames, extended attributes, and Finder-style metadata instead of leaking filesystem context in plaintext.
- Restricts plaintext reads through Process-Based Access Control so trusted macOS apps can be allowed while blocked access attempts are audited.
- Includes vault health, repair, snapshot, native QA, and release-gate workflows that make the product easier to operate and safer to ship.
Tradeoffs and Decisions
- Accepted the complexity of a split architecture because a usable desktop security product needed mount logic, repair tooling, UI flows, and distribution automation, not just encryption primitives.
- Kept direct signed-and-notarized distribution as the primary shipping path while building a separate no-FUSE mode for App Store-oriented constraints instead of pretending the FUSE workflow was sandbox-friendly.
- Used trusted-app rules and audit logging to reduce plaintext exposure, knowing that app identity handling on macOS needs careful fallbacks and explicit operator review.
Stack