UmbraCore is built to extend the foundation of Restic, a remarkable open-source backup programme that has set the standard for secure, efficient, and reliable backups. In particular, we have focussed extensively on enabling Restic to work more fully within Swift sandboxed environments as well as using native macOS security features coupled with Restic for those of us who struggle to remember passwords.
We are deeply grateful to the Restic team for their years of dedication in creating and maintaining such an exceptional tool, without whom UmbraCore would not exist. This bears noting as UmbraCore is not designed in any way to replace Restic but, rather, further extend its capabilities to ever more users who will undoubtedly come to use, admire, and love Restic as much as we do.
Our mission with UmbraCore is to:
- Extend Restic's capabilities specifically for macOS application development
- Provide a type-safe, Swift-native interface
- Maintain complete compatibility with Restic's core functionality
- Provide a solid development platform for novel Restic apps for devs and users alike
If you find UmbraCore useful, please consider:
- Complete developer documentation is update frequently and available at UmbraCore Dot Dev
- macOS 14.0+
- Swift 5.9.2+
- Bazel 8.1.0+
- Add UmbraCore to your dependencies in
MODULE.bazel:
swift_deps = use_extension("@rules_swift_package_manager//:extensions.bzl", "swift_deps")
swift_deps.from_json(
deps_json = "//:.deps.json",
)- Add the dependency to your
.deps.json:
{
"umbracore": {
"url": "https://github.com/UmbraDevelopment/UmbraCore.git",
"version": "0.2.0"
}
}UmbraCore powers several macOS backup management tools:
- ResticBar (macOS menu bar app for developers)
- Rbx (VS Code extension)
- Rbum (user-friendly GUI)
- Secure keychain operations with XPC service
- Repository password handling
- Comprehensive error handling and logging
- Thread-safe operations
- SwiftyBeaver logging integration
- Modular architecture
- Extensive test coverage
- SSH key management
- Cloud provider credentials
UmbraCore is organised into several key components:
- UmbraErrors: Core error handling and error types
- CoreDTOs: Data transfer objects for module interoperability
- SecurityInterfaces: Security provider interfaces and adapters
- SecurityTypes: Core security type definitions
- FileSystemTypes: File system abstractions and utilities
- Scheduling: Task scheduling and background processing
- UserDefaults: User preferences management
- ResticCLIHelper: Command-line interface integration
- Repositories: Repository management and operations
- Snapshots: Snapshot creation and management
- Config: Configuration and settings management
- Logging: Privacy-aware structured logging
We are currently migrating to the new Alpha Dot Five architecture, which brings better module organisation, improved dependency management, and enhanced concurrency support. As part of this migration:
- Successfully migrated modules are moved to the
MigratedArchivedirectory - New modules follow the standardised Alpha Dot Five structure
- Migration status is tracked in
migration_status.json
For detailed information about the migration process and archive structure, see the MigratedArchive documentation.
- SecurityTypes: Base security primitives and protocols
- CryptoTypes: Cryptographic operations and types
- UmbraLogging: Centralised logging infrastructure
- UmbraKeychainService: Secure keychain operations
- UmbraCryptoService: Cryptographic operations service
- UmbraBookmarkService: File system bookmark management
- UmbraXPC: XPC communication infrastructure
- ResticCLIHelper: Command-line interface integration
- Repositories: Repository management and operations
- Snapshots: Snapshot creation and management
- Config: Configuration and settings management
- Logging: Privacy-aware structured logging
- ErrorHandling: Comprehensive error management
- Autocomplete: Context-aware command completion
The /Examples directory contains sample implementations demonstrating correct usage of UmbraCore APIs and patterns. These examples are kept separate from the main codebase to prevent build/test interference while still providing reference implementations.
UmbraCore implements a dual-library cryptographic approach to support both native macOS security features and cross-process operations:
- Native macOS security features for ResticBar
- Hardware-backed security operations
- Secure key storage with Secure Enclave
- Optimised for sandboxed environments
- Cross-process operations for Rbum and Rbx
- Platform-independent implementation
- Flexible XPC service support
- Consistent cross-application behaviour
The KeyManager orchestrates cryptographic operations across both implementations:
- Intelligent routing between CryptoKit and CryptoSwift
- Unified key lifecycle management
- Secure key storage and rotation
- Context-aware security boundaries
- Cross-process synchronisation
This dual-library strategy enables UmbraCore to provide:
- Native security features in ResticBar
- Cross-functional operation in Rbum and Rbx
- Consistent security model across all implementations
- Flexible deployment options
# Generate/update BUILD files
bazelisk run //:update_build_files
# Build all targets
bazelisk build //...
# Run tests
bazelisk test //...UmbraCore uses a clean Git repository approach with:
- Development scripts and utilities kept locally but excluded from Git
- Production code focused on the main branch
- Clear separation between build outputs and source code
If you're contributing, please note that certain file types are excluded from Git tracking:
- Python scripts (.py)
- Shell scripts (.sh)
- Dot files (.dot)
- Most .md files (except README.md files)
- .txt files (except test_targets.txt and production_targets.txt)
- Various analyser and utility files
This approach keeps the repository clean while maintaining the necessary tools for development locally.
The complete documentation is available at UmbraCore Dot Dev.
UmbraCore prioritises security through:
- Secure keychain integration
- XPC service isolation
- Regular dependency scanning
- Comprehensive security testing
- Fork the repository
- Create your feature branch
- Write tests for new functionality
- Ensure all tests pass
- Submit a pull request
Please follow our contribution guidelines and code of conduct.
See our detailed Development Roadmap for upcoming features and milestones.
UmbraCore builds upon the work of several outstanding open-source projects:
A truly unique backup programme that sets the standard for secure, efficient, and reliable backups. The dedication of the Restic team in creating and maintaining this exceptional tool has been instrumental in making UmbraCore possible.
An outstanding cryptography framework created and maintained by Marcin Krzyżanowski. We are grateful for the years of work that have gone into making this comprehensive, pure-Swift implementation of popular cryptographic algorithms. CryptoSwift's excellent design and thorough testing have been crucial for UmbraCore's security features.
A sophisticated logging system developed by Sebastian Kreutzberger and contributors. SwiftyBeaver's elegant API design and robust feature set have significantly enhanced UmbraCore's logging capabilities. We deeply appreciate the maintainers' commitment to providing such a reliable and well-documented logging solution.
This project is licensed under the GNU General Public License v3.0
Copyright 2024-2025 Umbra Development Ltd. All rights reserved.
UmbraCore is a trademark of Umbra Development Ltd.
This software includes components from other projects, each under its own licence.