🔐 Secure Property Storage

Helps you define secure storages for your properties using Swift property wrappers.

All keys are hashed using SHA512 and all values are encrypted using AES-GCM to keep user information safe, automagically. Symmetric key is stored in Keychain in a totally secure way.

🐒 Basic usage

@UserDefault

This property wrapper will store your property in UserDefaults using StoreKey (any String but i recommend you a String typed enum). Optionally, you can assign a default value to the property that will be secure stored at initialization.

@UserDefault(<#StoreKey#>)
var yourProperty: YourType? = yourDefaultValueIfNeeded

UserDefaultsStorage is also available, a subclass of UserDefaults with all the security provided by this library, where you can customize suite name.

@Keychain

This property wrapper will store your property in Keychain using StoreKey.

@Keychain(<#StoreKey#>)
var yourProperty: YourType? = yourDefaultValueIfNeeded

As UserDefaultsStorage, KeychainStorage is also available, where you can customize access, group and synchronize it with iCloud.

@Singleton

This property wrapper will store your property in a memory singleton, every property with the same wrapper and key can access or modify the value from wherever it is.

@Singleton(<#StoreKey#>)
var yourProperty: YourType? = yourDefaultValueIfNeeded

As KeychainStorage, SingletonStorage is also available.

@Inject

This property wrapper is similar to @Singleton but, together with @Register, will inject your dependencies. More details in Dependency Injection usage guide.

@Inject
var yourDependency: YourProtocol?

As SingletonStorage, InjectStorage is also available.

@Store

This is a custom wrapper, you can define your own Storage protocol implementation.

@Store(<#YourStorage#>, <#StoreKey#>)
var yourProperty: YourType? = yourDefaultValueIfNeeded

As InjectStorage, DelegatedStorage is also available with all the magic of this library.

🧙‍♂️ Codable usage

If your property conforms Codable protocol, just add Codable keyword as prefix of your property wrapper.

• @CodableUserDefault
• @CodableKeychain
• @CodableSingleton
• @CodableStore

🥡 Unwrapped usage

To avoid continually unwrapping your property, just add Unwrapped keyword as prefix of your property wrapper, assign a default value (mandatory except for @UnwrappedInject), and it will return stored value or default value, but your property will always be there for you.

• @UnwrappedUserDefault
• @UnwrappedKeychain
• @UnwrappedSingleton
• @UnwrappedInject
• @UnwrappedStore

🥡 + 🧙‍♂️ Combo usage

You can also combine previous cases in case you need it, unwrapped first please.

• @UnwrappedCodableUserDefault
• @UnwrappedCodableKeychain
• @UnwrappedCodableSingleton
• @UnwrappedCodableStore

💉 Dependency Injection usage

@Register
var yourDependency: YourProtocol = YourImplementation()
@Register
var yourDependency = YourImplementation()

@Register
var yourDependency = {
    YourImplementation() as YourProtocol
}
@Register
var yourDependency = {
    YourImplementation()
}

InjectStorage.standard.errorClosure = { error in
    if case InjectError.notFound = error {
        YourImplementation.register()
    }
}

static func register(@Register yourDependency: YourProtocol = YourImplementation()) {}

@Inject
var yourDependency: YourProtocol?
@Inject
var yourDependency: YourImplementation?
@UnwrappedInject
var yourUnwrappedDependency: YourProtocol
@UnwrappedInject
var yourUnwrappedDependency: YourImplementation

@Inject(.instance)
var yourDependency: YourProtocol?
@UnwrappedInject(.instance)
var yourUnwrappedDependency: YourProtocol

@Register
var yourDependency = { parameters in
    YourImplementation(parameters) as YourProtocol
}
@Inject(YourParameters())
var yourDependency: YourProtocol?
@UnwrappedInject(YourParameters())
var yourUnwrappedDependency: YourProtocol

protocol Animal {
  func sound()
}
@objc protocol Dog {}
@objc protocol Cat {}

class DogImplementation: Animal, Dog {
    func sound() { print("Woof!") }
}
class CatImplementation: Animal, Cat {
    func sound() { print("Meow!") }
}

@Register
var registerDog: Animal = DogImplementation()
@Register
var registerCat: Animal = CatImplementation()

@UnwrappedInject(Dog.self)
var dog: Animal
@UnwrappedInject(Cat.self)
var cat: Animal
dog.sound() // prints Woof!
cat.sound() // prints Meow!

// App target
class YourImplementation: YourProtocol {}
@Register
var yourDependency: YourProtocol = YourImplementation()
@Inject
var yourDependency: YourProtocol?

// Test target
class YourMock: YourProtocol, Mock {}
@Register
var yourDependency: YourProtocol = YourMock()

@Register(group: <#DependencyGroupKey#>)
var yourDependency: YourProtocol = YourImplementation()

@Inject(group: <#DependencyGroupKey#>)
var yourDependency: YourProtocol?

🔒 Concurrency and Sendable

This library is designed with Swift's modern concurrency features in mind. Access to the underlying storage mechanisms (UserDefaults, Keychain, etc.) is serialized through a global actor (StorageActor), preventing data races during read and write operations performed by the library itself.

However, for your application to be fully concurrency-safe when using this library, it is crucial that the types you store and retrieve are Sendable.

• Generic Types: When using generic property wrappers or methods like @Store var item: MyType?, storage.value(forKey: "key") as? MyType, or storage.decodable(forKey: "key") as? MyDecodableType, ensure that MyType and MyDecodableType conform to the Sendable protocol.
• Object Archiving: If you use methods that rely on NSKeyedArchiver (such as storage.set(object: myNSObject, forKey: "key")), the class myNSObject should conform to NSSecureCoding for security and also be Sendable for concurrency safety.
• Why is Sendable important?: While the library ensures that the act of storing or retrieving data is safe, if the data itself (e.g., a class instance) is not Sendable, then passing it across different concurrent tasks or actors after retrieval can lead to data races if the data is mutable. Conforming to Sendable helps Swift enforce that such types can be safely shared.

👀 Examples

Talk is cheap. Show me the code.

// Securely stored in UserDefaults.
    @UserDefault("username")
    var username: String?
// Securely stored in Keychain.
    @Keychain("password")
    var password: String?
// Securely stored in a Singleton storage.
    @Singleton("sessionToken")
    var sessionToken: String?
// Securely stored in a Singleton storage.
    // Always has a value, the stored or the default.
    @UnwrappedSingleton("refreshToken")
    var refreshToken: String = "B0610306-A33F"
struct User: Codable {
        let username: String
        let password: String?
        let sessionToken: String?
    }
// Codable model securely stored in UserDefaults.
    @CodableUserDefault("user")
    var user: User?

🛠 Compatibility

| Platform | Minimum deployment target | |---|---| | iOS / iPadOS | 15.0 | | macOS | 12.0 | | tvOS | 15.0 | | watchOS | 9.0 | | visionOS | 1.0 |

• Developed and tested with Xcode 27.1 and Swift 6.4 (swift-tools-version:6.0, Swift 6 language mode).
• Mac Catalyst builds are supported as well.
• Continuous integration (see .github/workflows/ci.yml) runs the full test suite on an iPhone 17 Simulator (iOS 27.0) and on macOS (swift test),

• tvOS, watchOS and visionOS are compile-verified only: the test suite is not executed on those platforms.
• If you need to support older OS versions, use the previous releases (0.8.2 supports iOS 13, macOS 11.5, tvOS 13 and watchOS 6).

⚙️ Installation

You can use the Swift Package Manager by declaring SecurePropertyStorage as a dependency in your Package.swift file:

.package(url: "https://github.com/alexruperez/SecurePropertyStorage", from: "0.8.2")

By default, all property wrappers are installed and you can import them, but if you want, you can install only some of them:

• UserDefault: @*UserDefault property wrappers.
• Keychain: @*Keychain property wrappers.
• Singleton: @*Singleton property wrappers.
• Storage: @*Store property wrappers.
• Inject: @*Inject property wrappers.

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "SecurePropertyStorage", package: "SecurePropertyStorage")
        // or only some of them: "UserDefault", "Keychain", "Singleton", "Inject", "Storage"
    ]
)

In Xcode: File ▸ Add Package Dependencies… and enter https://github.com/alexruperez/SecurePropertyStorage.

For more information, see the Swift Package Manager documentation.

Or you can use Carthage:

github "alexruperez/SecurePropertyStorage"

🧪 Development

swift build                      # Build all targets
swift test                       # Run the test suite on macOS
Run the test suite on the iPhone 17 Simulator (iOS 27.0), as the CI does
xcodebuild test \
  -project SecurePropertyStorage.xcodeproj \
  -scheme SecurePropertyStorage-Package \
  -destination 'platform=iOS Simulator,name=iPhone 17,OS=27.0'
Compile-check another platform
xcodebuild build \
  -project SecurePropertyStorage.xcodeproj \
  -scheme SecurePropertyStorage-Package \
  -destination 'generic/platform=watchOS Simulator'

Notes for contributors:

• Test classes are isolated to @StorageActor and their test methods are async, so XCTest runs them on that actor.
• The Keychain needs entitlements that are not available to swift test on macOS; the Keychain tests therefore assert the error path there.

• Please keep the public API source compatible and add a CHANGELOG entry for every user-facing change.

🍻 Etc.

• Featured in Dave Verwer's iOS Dev Weekly - Issue 450, thanks Dave!
• Contributions are very welcome. Thanks Alberto Garcia, Manu and Chen!
• Attribution is appreciated (let's spread the word!), but not mandatory.

👨‍💻 Author

Alex Rupérez – @alexruperez

👮‍♂️ License

SecurePropertyStorage is available under the MIT license. See the LICENSE file for more info.