strata-storage 2.4.3 → 2.6.0

package/ios/CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md — ios/
+
+Last Updated: 2026-05-27
+
+## iOS Native Plugin
+
+Swift implementation of native storage backends for Capacitor.
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `Plugin/StrataStoragePlugin.swift` | Main Capacitor plugin entry point |
+| `Plugin/UserDefaultsStorage.swift` | UserDefaults-based general storage |
+| `Plugin/KeychainStorage.swift` | Keychain-based secure storage |
+| `Plugin/SQLiteStorage.swift` | SQLite database storage (multi-store, v2.6.0) |
+| `Plugin/FilesystemStorage.swift` | File-per-key storage under `NSDocumentsDirectory/strata_storage/` (new in v2.6.0) |
+
+### Configuration
+
+- Pod spec: `StrataStorage.podspec` (root)
+- Minimum iOS version: defined in podspec
+- Language: Swift
+
+## v2.6.0 Changes
+
+### SQLite multi-store
+`SQLiteStorage.swift` now accepts `database` and `table` parameters from the
+Capacitor call options. Each unique `(database, table)` pair opens a separate
+`.db` file in the app's documents directory. Table identifiers are sanitised to
+`[A-Za-z0-9_]` before use in SQL. The full `StorageValue` wrapper is serialised
+to JSON and stored in a single `value` column; native `get` deserialises and
+returns the full wrapper so TTL, tags, and metadata survive the round-trip.
+Text/blob binds use `SQLITE_TRANSIENT` (removes a latent use-after-free for
+transient Swift buffers). `size(detailed: true)` returns per-column byte
+breakdown.
+
+### FilesystemStorage.swift (new)
+Stores each key as `NSDocumentsDirectory/strata_storage/<sanitised-key>.json`.
+Writes are atomic: the value is first written to
+`strata_storage/.staging/<key>.tmp`, then renamed into place. Temp files live in
+the staging subdirectory, so they are never exposed by `keys()` and are not
+deleted by a targeted `remove()`. `isAvailable()` returns `true` on device.
+`size(detailed: true)` supported.
+
+> **Pending on-device verification** — native code is complete and reviewed; see
+> `docs/guides/platforms/device-verification.md` for the test matrix.
+
+## Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `KeychainStorage`
+- NEVER store credentials, tokens, or secrets in `UserDefaultsStorage`
+- Keychain items should use appropriate access control flags
+
+### Plugin Architecture
+- All native methods are exposed through `StrataStoragePlugin.swift`
+- Plugin bridges Capacitor JS calls to native Swift implementations
+- Each storage backend is a separate Swift file
+- The `CAP_PLUGIN` macro must list every callable method; missing entries cause
+  silent `undefined` returns on the JS side
+
+### SQLite
+- `SQLiteStorage.swift` opens or creates the `.db` file identified by the
+  `database` call option (default `strata_storage.db`)
+- Handles table creation, migrations, and CRUD operations
+- Use parameterized queries — NEVER string-interpolate SQL
+- Use `SQLITE_TRANSIENT` for text/blob binds
+
+### Filesystem
+- Key strings are sanitised before use as filenames (`/` → `_`, etc.)
+- Staging renames ensure atomic writes; never read from `.staging/`
+- `keys()` lists `.json` files only, ignoring staging artifacts
+
+### Testing
+- Native code is tested through the Capacitor bridge
+- Test via the demo app on iOS simulator following
+  `docs/guides/platforms/device-verification.md`
+- Verify all adapter methods work end-to-end
+
+### Before Modifying
+- Understand the Capacitor plugin protocol
+- Test on iOS simulator after changes
+- Verify podspec still resolves

package/ios/Plugin/FilesystemStorage.swift

@@ -0,0 +1,218 @@
+import Foundation
+import os.log
+
+/**
+ * Filesystem-backed storage: one file per key under
+ * `<Documents>/strata_storage/`.
+ *
+ * Value-shape contract (matches src/plugin/definitions.ts, same as SQLite):
+ * - File contents are the JSON-serialized FULL `StorageValue` wrapper
+ *   `{ value, created, updated, expires?, tags?, metadata?, ... }`.
+ * - `get` parses the bytes back into the wrapper object; the plugin resolves
+ *   `{ value: wrapper }`. Missing file OR non-object bytes → miss (no crash).
+ *
+ * File naming: the storage key is percent-encoded with an allowed set that
+ * EXCLUDES `/` (and `%`), so the encoding is reversible and never escapes the
+ * storage directory. `decodeFileName` reverses it for `keys()`.
+ *
+ * Durability: writes go to a temp file in the same directory and are then
+ * atomically replaced into place, so a crash mid-write cannot leave a torn
+ * file at the real path.
+ */
+@objc public class FilesystemStorage: NSObject {
+    private let directory: URL
+    private let stagingDirectory: URL
+    private let logger = OSLog(subsystem: "com.strata.storage", category: "FilesystemStorage")
+
+    /// Reserved staging subdirectory name (inside the storage dir) holding
+    /// in-flight temp files for atomic writes. Enumeration skips it by name, so
+    /// a temp file can never collide with an encoded key file (e.g. a real key
+    /// literally named ".tmp-x").
+    private static let stagingDirName = ".strata-staging"
+
+    /// Characters allowed verbatim in an on-disk file name. Anything else
+    /// (notably `/` and `%`) is percent-escaped, keeping the name reversible
+    /// and confined to a single path component.
+    private static let fileNameAllowed: CharacterSet = {
+        var set = CharacterSet.alphanumerics
+        set.insert(charactersIn: "-_. ")
+        return set
+    }()
+
+    @objc public override init() {
+        let base = (try? FileManager.default.url(
+            for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: true
+        )) ?? URL(fileURLWithPath: NSTemporaryDirectory())
+        let storageDir = base.appendingPathComponent("strata_storage", isDirectory: true)
+        self.directory = storageDir
+        self.stagingDirectory = storageDir.appendingPathComponent(FilesystemStorage.stagingDirName, isDirectory: true)
+        super.init()
+        ensureDirectory()
+    }
+
+    private func ensureDirectory() {
+        for dir in [directory, stagingDirectory] {
+            if !FileManager.default.fileExists(atPath: dir.path) {
+                do {
+                    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+                } catch {
+                    os_log("Failed to create filesystem storage dir: %{public}@", log: logger, type: .error, error.localizedDescription)
+                }
+            }
+        }
+    }
+
+    /// Reversible encoding of a storage key → safe single-component file name.
+    private func encodeFileName(_ key: String) -> String {
+        // addingPercentEncoding only returns nil for invalid unichar sequences,
+        // which a Swift String key cannot contain; fall back defensively.
+        return key.addingPercentEncoding(withAllowedCharacters: FilesystemStorage.fileNameAllowed) ?? key
+    }
+
+    /// Reverses `encodeFileName`. Returns nil if the name cannot be decoded.
+    private func decodeFileName(_ name: String) -> String? {
+        return name.removingPercentEncoding
+    }
+
+    private func fileURL(forKey key: String) -> URL {
+        return directory.appendingPathComponent(encodeFileName(key), isDirectory: false)
+    }
+
+    /**
+     * Persist the full `StorageValue` wrapper for `key`. The wrapper is
+     * JSON-encoded and written atomically (temp file + replace).
+     */
+    @objc public func set(key: String, wrapper: [String: Any]) throws -> Bool {
+        ensureDirectory()
+        let data = try JSONSerialization.data(withJSONObject: wrapper, options: [])
+        let target = fileURL(forKey: key)
+
+        // Atomic write: stage to a unique temp file in the reserved staging
+        // subdir (same volume → atomic rename), then replace. The staging subdir
+        // keeps temp names out of the key namespace entirely.
+        let temp = stagingDirectory.appendingPathComponent(UUID().uuidString, isDirectory: false)
+        do {
+            try data.write(to: temp, options: .atomic)
+            if FileManager.default.fileExists(atPath: target.path) {
+                _ = try FileManager.default.replaceItemAt(target, withItemAt: temp)
+            } else {
+                try FileManager.default.moveItem(at: temp, to: target)
+            }
+        } catch {
+            // Clean up the temp file on any failure so we don't leak partials.
+            try? FileManager.default.removeItem(at: temp)
+            throw error
+        }
+        return true
+    }
+
+    /**
+     * Read the wrapper object for `key`. Missing file OR bytes that are not a
+     * JSON object → nil (treated as a miss; never throws on corrupt data).
+     */
+    @objc public func get(key: String) -> [String: Any]? {
+        let url = fileURL(forKey: key)
+        guard let data = try? Data(contentsOf: url) else {
+            return nil
+        }
+        guard let wrapper = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] else {
+            return nil
+        }
+        return wrapper
+    }
+
+    @objc public func remove(key: String) -> Bool {
+        let url = fileURL(forKey: key)
+        if !FileManager.default.fileExists(atPath: url.path) {
+            return true // already absent — treat as success/idempotent
+        }
+        do {
+            try FileManager.default.removeItem(at: url)
+            return true
+        } catch {
+            os_log("Failed to remove filesystem key: %{public}@", log: logger, type: .error, error.localizedDescription)
+            return false
+        }
+    }
+
+    /// Clears stored entries. When `prefix` is set, only keys starting with it
+    /// are removed; otherwise the whole storage directory contents are removed.
+    @objc public func clear(prefix: String? = nil) -> Bool {
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
+        var ok = true
+        for name in names {
+            // Skip the staging subdirectory (never a key).
+            if name == FilesystemStorage.stagingDirName { continue }
+            guard let key = decodeFileName(name) else { continue }
+            if let prefix = prefix, !key.hasPrefix(prefix) { continue }
+            do {
+                try FileManager.default.removeItem(at: directory.appendingPathComponent(name, isDirectory: false))
+            } catch {
+                ok = false
+            }
+        }
+        // On a full clear, also drop any orphaned in-flight temp files.
+        if prefix == nil, let temps = try? FileManager.default.contentsOfDirectory(atPath: stagingDirectory.path) {
+            for temp in temps {
+                try? FileManager.default.removeItem(at: stagingDirectory.appendingPathComponent(temp, isDirectory: false))
+            }
+        }
+        return ok
+    }
+
+    /// Lists stored keys, decoding file names back to their original keys.
+    /// When `pattern` is set, applies the same prefix/contains matching the
+    /// other backends use.
+    @objc public func keys(pattern: String? = nil) -> [String] {
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
+        var keys: [String] = []
+        for name in names {
+            if name == FilesystemStorage.stagingDirName { continue }
+            guard let key = decodeFileName(name) else { continue }
+            keys.append(key)
+        }
+        guard let pattern = pattern else { return keys }
+        return keys.filter { $0.hasPrefix(pattern) || $0.contains(pattern) }
+    }
+
+    /**
+     * Aggregate sizes over the storage directory.
+     *
+     * `count` = number of entry files; `values` = sum of file byte sizes;
+     * `keys` = sum of decoded-key UTF-8 byte lengths; `metadata` = sum of the
+     * serialized `metadata` segment per file (0 when absent or unparseable);
+     * `total` = `keys` + `values`.
+     */
+    @objc public func size() -> [String: Int] {
+        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
+        var count = 0
+        var keysSize = 0
+        var valuesSize = 0
+        var metadataSize = 0
+
+        for name in names {
+            if name == FilesystemStorage.stagingDirName { continue }
+            guard let key = decodeFileName(name) else { continue }
+            let url = directory.appendingPathComponent(name, isDirectory: false)
+            count += 1
+            keysSize += key.data(using: .utf8)?.count ?? 0
+
+            if let data = try? Data(contentsOf: url) {
+                valuesSize += data.count
+                if let wrapper = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
+                   let metadata = wrapper["metadata"],
+                   let metadataData = try? JSONSerialization.data(withJSONObject: metadata, options: []) {
+                    metadataSize += metadataData.count
+                }
+            }
+        }
+
+        return [
+            "count": count,
+            "keys": keysSize,
+            "values": valuesSize,
+            "metadata": metadataSize,
+            "total": keysSize + valuesSize
+        ]
+    }
+}

package/ios/Plugin/KeychainStorage.swift

@@ -1,19 +1,72 @@
 import Foundation
 import Security
 
+/**
+ * Keychain-backed secure storage.
+ *
+ * Security notes:
+ * - Items default to `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`,
+ *   which keeps data available to background tasks after the first unlock
+ *   while preventing it from leaving the device via encrypted backups.
+ *   `kSecAttrAccessibleAlways` / `kSecAttrAccessibleAlwaysThisDeviceOnly`
+ *   are deprecated and insecure and are intentionally NOT used.
+ * - Callers may pass a stricter accessibility class from JS via the
+ *   `accessible` option (see KeychainAccessible in definitions.ts).
+ * - Secret values are never logged.
+ */
 @objc public class KeychainStorage: NSObject {
     private let service: String
     private let accessGroup: String?
-    
+    private let defaultAccessible: CFString
+
     @objc public init(service: String? = nil, accessGroup: String? = nil) {
         self.service = service ?? Bundle.main.bundleIdentifier ?? "StrataStorage"
         self.accessGroup = accessGroup
+        // After-first-unlock + this-device-only is a safe, widely-recommended
+        // default for app secrets. It is more permissive than whenUnlocked
+        // (so background access works) but still excluded from backups.
+        self.defaultAccessible = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
         super.init()
     }
-    
-    @objc public func set(key: String, value: Any) throws -> Bool {
+
+    /// Maps a JS `KeychainAccessible` string to the matching Security framework
+    /// constant. Unknown / nil values fall back to the secure default.
+    private func accessibleConstant(for raw: String?) -> CFString {
+        switch raw {
+        case "whenUnlocked":
+            return kSecAttrAccessibleWhenUnlocked
+        case "afterFirstUnlock":
+            return kSecAttrAccessibleAfterFirstUnlock
+        case "whenUnlockedThisDeviceOnly":
+            return kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+        case "afterFirstUnlockThisDeviceOnly":
+            return kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        case "whenPasscodeSetThisDeviceOnly":
+            return kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
+        default:
+            return defaultAccessible
+        }
+    }
+
+    /// Builds an NSError that surfaces the OSStatus to the JS bridge without
+    /// leaking any stored secret value.
+    private func keychainError(_ status: OSStatus, operation: String) -> NSError {
+        let message: String
+        if #available(iOS 11.3, *), let str = SecCopyErrorMessageString(status, nil) as String? {
+            message = str
+        } else {
+            message = "OSStatus \(status)"
+        }
+        return NSError(
+            domain: "StrataStorage.KeychainStorage",
+            code: Int(status),
+            userInfo: [NSLocalizedDescriptionKey: "Keychain \(operation) failed: \(message)"]
+        )
+    }
+
+    @objc public func set(key: String, value: Any, accessible: String? = nil) throws -> Bool {
         let data: Data
-        
+
         if let dataValue = value as? Data {
             data = dataValue
         } else if let stringValue = value as? String {
@@ -23,28 +76,43 @@ import Security
             let jsonData = try JSONSerialization.data(withJSONObject: value, options: [])
             data = jsonData
         }
-        
-        let query = createQuery(key: key)
-        SecItemDelete(query as CFDictionary)
-        
-        var newItem = query
+
+        // Remove any existing item first so the accessibility class is applied
+        // cleanly (SecItemUpdate cannot change accessibility reliably).
+        let deleteQuery = createQuery(key: key)
+        SecItemDelete(deleteQuery as CFDictionary)
+
+        var newItem = createQuery(key: key, accessible: accessibleConstant(for: accessible))
         newItem[kSecValueData as String] = data
-        
+
         let status = SecItemAdd(newItem as CFDictionary, nil)
-        return status == errSecSuccess
+        guard status == errSecSuccess else {
+            throw keychainError(status, operation: "set")
+        }
+        return true
+    }
+
+    // Convenience overload kept for existing Objective-C callers.
+    @objc public func set(key: String, value: Any) throws -> Bool {
+        return try set(key: key, value: value, accessible: nil)
     }
-    
+
     @objc public func get(key: String) throws -> Any? {
         var query = createQuery(key: key)
         query[kSecReturnData as String] = true
         query[kSecMatchLimit as String] = kSecMatchLimitOne
-        
+
         var result: AnyObject?
         let status = SecItemCopyMatching(query as CFDictionary, &result)
-        
-        guard status == errSecSuccess else { return nil }
+
+        if status == errSecItemNotFound {
+            return nil
+        }
+        guard status == errSecSuccess else {
+            throw keychainError(status, operation: "get")
+        }
         guard let data = result as? Data else { return nil }
-        
+
         // Try to parse as JSON first, fallback to string
         if let jsonObject = try? JSONSerialization.jsonObject(with: data, options: []) {
             return jsonObject
@@ -52,35 +120,41 @@ import Security
             return String(data: data, encoding: .utf8)
         }
     }
-    
+
     @objc public func remove(key: String) throws -> Bool {
         let query = createQuery(key: key)
         let status = SecItemDelete(query as CFDictionary)
-        return status == errSecSuccess
+        guard status == errSecSuccess || status == errSecItemNotFound else {
+            throw keychainError(status, operation: "remove")
+        }
+        return true
     }
-    
+
     @objc public func clear(prefix: String? = nil) throws -> Bool {
         if let prefix = prefix {
             // Clear only keys with the given prefix
             let keysToRemove = try keys(pattern: prefix)
-            var allSuccess = true
             for key in keysToRemove {
-                if !(try remove(key: key)) {
-                    allSuccess = false
-                }
+                _ = try remove(key: key)
             }
-            return allSuccess
+            return true
         } else {
-            // Clear all keys
-            let query: [String: Any] = [
+            // Clear all keys for this service (and access group, if any).
+            var query: [String: Any] = [
                 kSecClass as String: kSecClassGenericPassword,
                 kSecAttrService as String: service
             ]
+            if let accessGroup = accessGroup {
+                query[kSecAttrAccessGroup as String] = accessGroup
+            }
             let status = SecItemDelete(query as CFDictionary)
-            return status == errSecSuccess || status == errSecItemNotFound
+            guard status == errSecSuccess || status == errSecItemNotFound else {
+                throw keychainError(status, operation: "clear")
+            }
+            return true
         }
     }
-    
+
     @objc public func keys(pattern: String? = nil) throws -> [String] {
         var query: [String: Any] = [
             kSecClass as String: kSecClassGenericPassword,
@@ -88,57 +162,72 @@ import Security
             kSecReturnAttributes as String: true,
             kSecMatchLimit as String: kSecMatchLimitAll
         ]
-        
+
         if let accessGroup = accessGroup {
             query[kSecAttrAccessGroup as String] = accessGroup
         }
-        
+
         var result: AnyObject?
         let status = SecItemCopyMatching(query as CFDictionary, &result)
-        
+
+        if status == errSecItemNotFound {
+            return []
+        }
         guard status == errSecSuccess,
-              let items = result as? [[String: Any]] else { return [] }
-        
+              let items = result as? [[String: Any]] else {
+            if status == errSecSuccess { return [] }
+            throw keychainError(status, operation: "keys")
+        }
+
         let allKeys = items.compactMap { $0[kSecAttrAccount as String] as? String }
-        
+
         guard let pattern = pattern else {
             return allKeys
         }
-        
-        // Filter keys by pattern (simple prefix matching)
+
+        // Filter keys by pattern (simple prefix / contains matching)
         return allKeys.filter { key in
             key.hasPrefix(pattern) || key.contains(pattern)
         }
     }
-    
-    private func createQuery(key: String) -> [String: Any] {
+
+    private func createQuery(key: String, accessible: CFString? = nil) -> [String: Any] {
         var query: [String: Any] = [
             kSecClass as String: kSecClassGenericPassword,
             kSecAttrService as String: service,
-            kSecAttrAccount as String: key,
-            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+            kSecAttrAccount as String: key
         ]
-        
+
+        // Accessibility only needs to be set when adding/writing an item.
+        // Including it on read/delete queries can over-constrain matching.
+        if let accessible = accessible {
+            query[kSecAttrAccessible as String] = accessible
+        }
+
         if let accessGroup = accessGroup {
             query[kSecAttrAccessGroup as String] = accessGroup
         }
-        
+
         return query
     }
-    
+
     @objc public func size() throws -> (total: Int, count: Int) {
         let allKeys = try keys()
         var totalSize = 0
-        
+
         for key in allKeys {
-            if let data = try get(key: key) as? Data {
-                totalSize += data.count
-            } else if let string = try get(key: key) as? String {
-                totalSize += string.data(using: .utf8)?.count ?? 0
+            if let value = try get(key: key) {
+                if let data = value as? Data {
+                    totalSize += data.count
+                } else if let string = value as? String {
+                    totalSize += string.data(using: .utf8)?.count ?? 0
+                } else if let jsonData = try? JSONSerialization.data(withJSONObject: value, options: []) {
+                    totalSize += jsonData.count
+                }
             }
             totalSize += key.data(using: .utf8)?.count ?? 0
         }
-        
+
         return (total: totalSize, count: allKeys.count)
     }
-}
+}