strata-storage 2.5.0 → 2.6.0

package/dist/android/src/main/java/com/stratastorage/StrataStoragePlugin.java

@@ -8,10 +8,11 @@ import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import com.strata.storage.SharedPreferencesStorage;
 import com.strata.storage.EncryptedStorage;
+import com.strata.storage.FilesystemStorage;
 import com.strata.storage.SQLiteStorage;
 import android.util.Log;
 import org.json.JSONArray;
-import org.json.JSONException;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
@@ -19,15 +20,24 @@ import java.util.Map;
  * Main Capacitor plugin for Strata Storage
  * Coordinates between different storage types on Android.
  *
- * Storage types with a real native backend: preferences, secure, sqlite.
- * `filesystem` is NOT implemented natively and is rejected explicitly rather
- * than silently falling through to SharedPreferences.
+ * Storage types with a real native backend: preferences, secure, sqlite,
+ * filesystem.
+ *
+ * SQLite supports multi-store: the `database` option selects the DB file and
+ * `table` selects the table within it. SQLite helper instances are cached per
+ * database name so the connection is not reopened per call.
  */
 @CapacitorPlugin(name = "StrataStorage")
 public class StrataStoragePlugin extends Plugin {
+    private static final String DEFAULT_DATABASE = "strata_storage";
+    private static final String DEFAULT_TABLE = "storage";
+
     private SharedPreferencesStorage sharedPrefsStorage;
     private EncryptedStorage encryptedStorage;
-    private SQLiteStorage sqliteStorage;
+    private FilesystemStorage filesystemStorage;
+
+    /** SQLite helper cache keyed by resolved database name (without ".db"). */
+    private final Map<String, SQLiteStorage> sqliteStores = new HashMap<>();
 
     @Override
     public void load() {
@@ -44,18 +54,43 @@ public class StrataStoragePlugin extends Plugin {
             Log.e("StrataStorage", "Failed to initialize encrypted storage", e);
         }
         try {
-            sqliteStorage = new SQLiteStorage(getContext());
+            filesystemStorage = new FilesystemStorage(getContext());
         } catch (Exception e) {
-            Log.e("StrataStorage", "Failed to initialize SQLite storage", e);
+            Log.e("StrataStorage", "Failed to initialize filesystem storage", e);
         }
     }
 
-    private void rejectUnsupportedFilesystem(PluginCall call) {
-        call.reject(
-            "Filesystem storage is not implemented in the native Android plugin. " +
-            "Use the 'preferences', 'secure', or 'sqlite' storage types, or a " +
-            "web/Capacitor Filesystem-backed adapter."
-        );
+    /**
+     * Sanitize a database name to a safe file stem ({@code ^[A-Za-z0-9_]+$})
+     * and return the resolved stem. The ".db" suffix is appended when opening.
+     */
+    private static String sanitizeDatabase(String database) {
+        if (database == null || database.isEmpty()) {
+            return DEFAULT_DATABASE;
+        }
+        String cleaned = database.replaceAll("[^A-Za-z0-9_]", "");
+        return cleaned.isEmpty() ? DEFAULT_DATABASE : cleaned;
+    }
+
+    /**
+     * Return (creating + caching on first use) the SQLite helper for the given
+     * database name. The cache is keyed by the sanitized DB stem so the
+     * connection is reused across bridge calls. May return {@code null} if the
+     * helper cannot be constructed.
+     */
+    private synchronized SQLiteStorage getSqliteStore(String database) {
+        String dbStem = sanitizeDatabase(database);
+        SQLiteStorage store = sqliteStores.get(dbStem);
+        if (store == null) {
+            try {
+                store = new SQLiteStorage(getContext(), dbStem + ".db");
+                sqliteStores.put(dbStem, store);
+            } catch (Exception e) {
+                Log.e("StrataStorage", "Failed to open SQLite database " + dbStem, e);
+                return null;
+            }
+        }
+        return store;
     }
 
     /**
@@ -71,11 +106,10 @@ public class StrataStoragePlugin extends Plugin {
                 available = encryptedStorage != null;
                 break;
             case "sqlite":
-                available = sqliteStorage != null;
+                available = getSqliteStore(call.getString("database", DEFAULT_DATABASE)) != null;
                 break;
             case "filesystem":
-                // No native filesystem backend.
-                available = false;
+                available = filesystemStorage != null;
                 break;
             case "preferences":
             default:
@@ -89,7 +123,10 @@ public class StrataStoragePlugin extends Plugin {
     }
 
     /**
-     * Get value from storage
+     * Get value from storage.
+     *
+     * For sqlite/filesystem the resolved `value` is the full wrapper object
+     * (parsed back from JSON). A miss resolves `value` = null.
      */
     @PluginMethod
     public void get(PluginCall call) {
@@ -102,46 +139,70 @@ public class StrataStoragePlugin extends Plugin {
         String storage = call.getString("storage", "preferences");
 
         try {
-            Object value = null;
-
             switch (storage) {
-                case "secure":
+                case "secure": {
                     if (encryptedStorage == null) {
                         call.reject("Encrypted storage not available");
                         return;
                     }
-                    value = encryptedStorage.get(key);
-                    break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                    resolveValue(call, encryptedStorage.get(key));
+                    return;
+                }
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    value = sqliteStorage.get(key);
-                    break;
-                case "filesystem":
-                    rejectUnsupportedFilesystem(call);
+                    String table = call.getString("table", DEFAULT_TABLE);
+                    resolveValue(call, store.get(table, key));
                     return;
+                }
+                case "filesystem": {
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    resolveValue(call, filesystemStorage.get(key));
+                    return;
+                }
                 case "preferences":
-                default:
+                default: {
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
                     }
-                    value = sharedPrefsStorage.get(key);
-                    break;
+                    resolveValue(call, sharedPrefsStorage.get(key));
+                    return;
+                }
             }
-
-            JSObject result = new JSObject();
-            result.put("value", value);
-            call.resolve(result);
         } catch (Exception e) {
             call.reject("Failed to get value", e);
         }
     }
 
     /**
-     * Set value in storage
+     * Resolve a get() call, mapping a Java {@code null} to a JS {@code null}
+     * value so the TS adapters treat it as a miss.
+     */
+    private void resolveValue(PluginCall call, Object value) {
+        JSObject result = new JSObject();
+        if (value == null) {
+            result.put("value", JSObject.NULL);
+        } else {
+            result.put("value", value);
+        }
+        call.resolve(result);
+    }
+
+    /**
+     * Set value in storage.
+     *
+     * For sqlite/filesystem the `value` is the FULL wrapper object
+     * ({ value, created, updated, expires?, tags?, metadata? }); it is read via
+     * call.getObject("value") and stored verbatim (with TTL/query columns
+     * extracted for sqlite). For preferences/secure the raw value is forwarded
+     * unchanged.
      */
     @PluginMethod
     public void set(PluginCall call) {
@@ -151,7 +212,6 @@ public class StrataStoragePlugin extends Plugin {
             return;
         }
 
-        Object value = call.getData().opt("value");
         String storage = call.getString("storage", "preferences");
 
         try {
@@ -162,25 +222,42 @@ public class StrataStoragePlugin extends Plugin {
                         call.reject("Encrypted storage not available");
                         return;
                     }
-                    ok = encryptedStorage.set(key, value);
+                    ok = encryptedStorage.set(key, call.getData().opt("value"));
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    ok = sqliteStorage.set(key, value);
+                    JSObject wrapper = call.getObject("value");
+                    if (wrapper == null) {
+                        call.reject("A wrapper object 'value' is required for sqlite storage");
+                        return;
+                    }
+                    ok = store.set(call.getString("table", DEFAULT_TABLE), key, wrapper);
                     break;
-                case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                }
+                case "filesystem": {
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    JSObject wrapper = call.getObject("value");
+                    if (wrapper == null) {
+                        call.reject("A wrapper object 'value' is required for filesystem storage");
+                        return;
+                    }
+                    ok = filesystemStorage.set(key, wrapper);
+                    break;
+                }
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
                     }
-                    ok = sharedPrefsStorage.set(key, value);
+                    ok = sharedPrefsStorage.set(key, call.getData().opt("value"));
                     break;
             }
 
@@ -216,16 +293,22 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     encryptedStorage.remove(key);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    sqliteStorage.remove(key);
+                    store.remove(call.getString("table", DEFAULT_TABLE), key);
                     break;
+                }
                 case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    filesystemStorage.remove(key);
+                    break;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -263,16 +346,22 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     encryptedStorage.clear(prefix);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    sqliteStorage.clear(prefix);
+                    store.clear(call.getString("table", DEFAULT_TABLE), prefix);
                     break;
+                }
                 case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    filesystemStorage.clear(prefix);
+                    break;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -298,7 +387,7 @@ public class StrataStoragePlugin extends Plugin {
         String pattern = call.getString("pattern");
 
         try {
-            List<String> keys = null;
+            List<String> keys;
 
             switch (storage) {
                 case "secure":
@@ -308,16 +397,22 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     keys = encryptedStorage.keys(pattern);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    keys = sqliteStorage.keys(pattern);
+                    keys = store.keys(call.getString("table", DEFAULT_TABLE), pattern);
                     break;
+                }
                 case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    keys = filesystemStorage.keys(pattern);
+                    break;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -337,17 +432,21 @@ public class StrataStoragePlugin extends Plugin {
     }
 
     /**
-     * Get storage size information
+     * Get storage size information.
+     *
+     * When `detailed` is true the result also carries a byte breakdown
+     * { detailed: { keys, values, metadata } }.
      */
     @PluginMethod
     public void size(PluginCall call) {
         String storage = call.getString("storage", "preferences");
+        boolean detailed = Boolean.TRUE.equals(call.getBoolean("detailed", false));
 
         try {
             JSObject result = new JSObject();
 
             switch (storage) {
-                case "secure":
+                case "secure": {
                     if (encryptedStorage == null) {
                         call.reject("Encrypted storage not available");
                         return;
@@ -356,20 +455,29 @@ public class StrataStoragePlugin extends Plugin {
                     result.put("total", encryptedSizeInfo.total);
                     result.put("count", encryptedSizeInfo.count);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                }
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    SQLiteStorage.SizeInfo sqliteSizeInfo = sqliteStorage.size();
-                    result.put("total", sqliteSizeInfo.total);
-                    result.put("count", sqliteSizeInfo.count);
+                    SQLiteStorage.SizeInfo sqliteSizeInfo =
+                            store.size(call.getString("table", DEFAULT_TABLE), detailed);
+                    putSizeInfo(result, sqliteSizeInfo);
                     break;
-                case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                }
+                case "filesystem": {
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    SQLiteStorage.SizeInfo fsSizeInfo = filesystemStorage.size(detailed);
+                    putSizeInfo(result, fsSizeInfo);
+                    break;
+                }
                 case "preferences":
-                default:
+                default: {
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
@@ -378,6 +486,7 @@ public class StrataStoragePlugin extends Plugin {
                     result.put("total", prefsSizeInfo.total);
                     result.put("count", prefsSizeInfo.count);
                     break;
+                }
             }
 
             call.resolve(result);
@@ -386,12 +495,27 @@ public class StrataStoragePlugin extends Plugin {
         }
     }
 
+    /**
+     * Populate a size result, including the detailed byte breakdown when the
+     * {@link SQLiteStorage.SizeInfo} carries one.
+     */
+    private void putSizeInfo(JSObject result, SQLiteStorage.SizeInfo info) {
+        result.put("total", info.total);
+        result.put("count", info.count);
+        if (info.detailed) {
+            JSObject breakdown = new JSObject();
+            breakdown.put("keys", info.keysBytes);
+            breakdown.put("values", info.valuesBytes);
+            breakdown.put("metadata", info.metadataBytes);
+            result.put("detailed", breakdown);
+        }
+    }
+
     /**
      * Query SQLite-backed storage.
      * Matches the optional `query` method in the JS contract:
-     * resolves { results: [{ key, value }] }. The JS SqliteAdapter applies the
-     * real condition by re-fetching/filtering, so this enumerates candidate
-     * rows.
+     * resolves { results: [{ key }] }. The JS SqliteAdapter applies the real
+     * condition by re-fetching/filtering, so this enumerates candidate keys.
      */
     @PluginMethod
     public void query(PluginCall call) {
@@ -400,18 +524,18 @@ public class StrataStoragePlugin extends Plugin {
             call.reject("Query is only supported for the 'sqlite' storage type");
             return;
         }
-        if (sqliteStorage == null) {
+        SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+        if (store == null) {
             call.reject("SQLite storage not available");
             return;
         }
 
         try {
-            List<Map<String, Object>> rows = sqliteStorage.query();
+            List<Map<String, Object>> rows = store.query(call.getString("table", DEFAULT_TABLE));
             JSArray results = new JSArray();
             for (Map<String, Object> row : rows) {
                 JSObject obj = new JSObject();
                 obj.put("key", row.get("key"));
-                obj.put("value", row.get("value"));
                 results.put(obj);
             }
             JSObject result = new JSObject();

package/dist/ios/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — ios/
 
-Last Updated: 2026-04-03
+Last Updated: 2026-05-27
 
 > Agent instructions for iOS native development.
 
@@ -11,7 +11,16 @@ Last Updated: 2026-04-03
 | `Plugin/StrataStoragePlugin.swift` | Capacitor plugin entry |
 | `Plugin/UserDefaultsStorage.swift` | General key-value storage |
 | `Plugin/KeychainStorage.swift` | Secure storage |
-| `Plugin/SQLiteStorage.swift` | Database storage (~11KB) |
+| `Plugin/SQLiteStorage.swift` | SQLite database storage — multi-store (v2.6.0), `database`/`table` options honoured, full `StorageValue` wrapper round-trip, `size(detailed)` supported |
+| `Plugin/FilesystemStorage.swift` | File-per-key native storage under `NSDocumentsDirectory/strata_storage/` (new in v2.6.0); atomic writes via staging rename; `isAvailable()` returns `true` |
+
+## v2.6.0 Notes
+
+- **SQLite multi-store:** `database` option → distinct `.db` file. `table` option → sanitised table identifier `[A-Za-z0-9_]`. Previously both were ignored and all adapters shared one table.
+- **SQLite value shape:** `get` now returns the full `StorageValue` wrapper (`value`, `created`, `updated`, `expires`, `tags`, `metadata`). Corrupt rows are treated as a miss.
+- **SQLite bind safety:** text/blob binds use `SQLITE_TRANSIENT` — removes a latent use-after-free for transient Swift buffers.
+- **FilesystemStorage.swift:** new file. Writes are atomic (staging temp → rename). `keys()` excludes `.staging/` artifacts. `size(detailed: true)` returns `{ keys, values, metadata }`.
+- **Pending on-device verification** — see `docs/guides/platforms/device-verification.md`.
 
 ## Agent Rules
 
@@ -20,14 +29,20 @@ Last Updated: 2026-04-03
 - NEVER store secrets in `UserDefaultsStorage`
 
 ### SQL Safety
-- ALWAYS use parameterized queries in SQLiteStorage
+- ALWAYS use parameterized queries in `SQLiteStorage`
 - NEVER string-interpolate SQL values
+- Use `SQLITE_TRANSIENT` for text/blob binds
+
+### Filesystem Safety
+- NEVER read from `strata_storage/.staging/` — staging files are transient
+- Key sanitisation must be consistent between `set`, `get`, `remove`, and `keys`
 
 ### Plugin Architecture
 - Methods exposed through `StrataStoragePlugin.swift`
 - Each storage backend is a separate Swift file
 - Bridges Capacitor JS calls to native Swift
+- The `CAP_PLUGIN` macro must include every callable method name
 
 ### Before Modifying
 - Understand Capacitor plugin protocol
-- Test on iOS simulator after changes
+- Test on iOS simulator after changes; follow device-verification guide

package/dist/ios/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — ios/
 
-Last Updated: 2026-04-03
+Last Updated: 2026-05-27
 
 ## iOS Native Plugin
 
@@ -13,7 +13,8 @@ Swift implementation of native storage backends for Capacitor.
 | `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 (~11KB) |
+| `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
 
@@ -21,6 +22,30 @@ Swift implementation of native storage backends for Capacitor.
 - 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)
@@ -32,15 +57,25 @@ Swift implementation of native storage backends for Capacitor.
 - 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` is the largest file (~11KB)
+- `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
+- 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