# Vault

A lightweight Swift package for storing, reading, and deleting strings in the iOS and macOS keychain.

## Requirements

- Swift 6.0+
- iOS 13+ / macOS 10.15+

## Installation

Add Vault to your project via Swift Package Manager:

```swift
dependencies: [
    .package(url: "https://github.com/SparrowTek/Vault.git", from: "1.0.0")
]
```

## Usage

Vault is an actor, so all calls require `await`.

### Configure once, use everywhere

```swift
import Vault

let vault = Vault(configuration: KeychainConfiguration(
    serviceName: "com.myapp.service",
    accessGroup: nil,
    accountName: "userToken"
))

// Save
try await vault.save("my-secret-value")

// Read
let value = try await vault.read()

// Delete
try await vault.delete()
```

### Configure later

```swift
let vault = Vault()

let config = KeychainConfiguration(
    serviceName: "com.myapp.service",
    accessGroup: nil,
    accountName: "userToken"
)

await vault.configure(config)

try await vault.save("my-secret-value")
```

### Override configuration per call

You can pass a different configuration to any individual call, which takes precedence over the stored configuration:

```swift
let otherConfig = KeychainConfiguration(
    serviceName: "com.myapp.service",
    accessGroup: nil,
    accountName: "refreshToken"
)

try await vault.save("another-secret", configuration: otherConfig)
let token = try await vault.read(configuration: otherConfig)
```

## Error Handling

All errors are thrown as `VaultError`:

```swift
do {
    let value = try await vault.read()
} catch let error as VaultError {
    switch error {
    case .noConfiguration:
        // No KeychainConfiguration was provided
    case .itemNotFound:
        // No matching item exists in the keychain
    case .unexpectedData:
        // The keychain returned data in an unexpected format
    case .encodingFailed:
        // The value could not be encoded as UTF-8
    case .keychainFailure(let status):
        // A keychain operation failed with the given OSStatus
    }
}
```