strata-storage 2.4.2 → 2.5.0

package/android/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md — android/
+
+Last Updated: 2026-04-03
+
+> Agent instructions for Android native development.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `StrataStoragePlugin.java` | Capacitor plugin entry (com.stratastorage) |
+| `SharedPreferencesStorage.java` | General key-value storage (com.strata.storage) |
+| `EncryptedStorage.java` | Secure storage (com.strata.storage) |
+| `SQLiteStorage.java` | Database storage (com.strata.storage) |
+
+## Agent Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `EncryptedStorage`
+- NEVER store secrets in `SharedPreferencesStorage`
+
+### SQL Safety (IRON-SOLID)
+- ALWAYS use parameterized queries
+- NEVER concatenate user input into SQL strings
+
+### Plugin Architecture
+- Methods exposed through `StrataStoragePlugin.java`
+- Each storage backend is a separate Java class
+- Two package paths: `com.stratastorage` (plugin) and `com.strata.storage` (impl)
+
+### Before Modifying
+- Understand Capacitor plugin protocol for Android
+- Test on Android emulator after changes
+- Verify Gradle build succeeds

package/android/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md — android/
+
+Last Updated: 2026-04-03
+
+## Android Native Plugin
+
+Java implementation of native storage backends for Capacitor.
+
+### Files
+
+| File | Path | Purpose |
+|------|------|---------|
+| `StrataStoragePlugin.java` | `src/main/java/com/stratastorage/` | Main Capacitor plugin entry |
+| `SharedPreferencesStorage.java` | `src/main/java/com/strata/storage/` | SharedPreferences general storage |
+| `EncryptedStorage.java` | `src/main/java/com/strata/storage/` | EncryptedSharedPreferences secure storage |
+| `SQLiteStorage.java` | `src/main/java/com/strata/storage/` | SQLite database storage |
+
+### Configuration
+
+- Build: `build.gradle`
+- Proguard: `proguard-rules.pro`
+- Manifest: `src/main/AndroidManifest.xml`
+
+**Note**: There are two Java package paths — `com.stratastorage` (plugin) and `com.strata.storage` (implementations).
+
+## Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `EncryptedStorage` (EncryptedSharedPreferences)
+- NEVER store credentials, tokens, or secrets in `SharedPreferencesStorage`
+- Follow Android Keystore best practices
+
+### SQL Safety (IRON-SOLID)
+- ALWAYS use parameterized queries in `SQLiteStorage`
+- NEVER concatenate user input into SQL strings
+- Use `SQLiteDatabase.query()` or prepared statements
+
+### Plugin Architecture
+- All native methods exposed through `StrataStoragePlugin.java`
+- Plugin bridges Capacitor JS calls to Java implementations
+- Each storage backend is a separate Java class
+
+### Build
+- Gradle-based build system
+- Proguard rules configured for release builds
+- Test on Android emulator after changes
+
+### Before Modifying
+- Understand the Capacitor plugin protocol for Android
+- Test on Android emulator after changes
+- Verify Gradle build succeeds

package/android/src/main/java/com/strata/storage/SQLiteStorage.java

@@ -227,6 +227,41 @@ public class SQLiteStorage extends SQLiteOpenHelper {
             db.close();
         }
     }
+
+    /**
+     * Returns every row as a map of { key, value } where value is the decoded
+     * stored payload (UTF-8 string of the BLOB). The JS SqliteAdapter applies
+     * the real query condition by re-fetching/filtering each key, so this only
+     * needs to enumerate candidate rows.
+     */
+    public List<Map<String, Object>> query() {
+        List<Map<String, Object>> rows = new ArrayList<>();
+        SQLiteDatabase db = this.getReadableDatabase();
+        Cursor cursor = null;
+        try {
+            cursor = db.query(TABLE_NAME, new String[]{KEY_ID, KEY_VALUE},
+                    null, null, null, null, null);
+            if (cursor != null && cursor.moveToFirst()) {
+                do {
+                    Map<String, Object> row = new HashMap<>();
+                    row.put("key", cursor.getString(0));
+                    byte[] valueBytes = cursor.getBlob(1);
+                    if (valueBytes != null) {
+                        row.put("value", new String(valueBytes, StandardCharsets.UTF_8));
+                    } else {
+                        row.put("value", null);
+                    }
+                    rows.add(row);
+                } while (cursor.moveToNext());
+            }
+            return rows;
+        } finally {
+            if (cursor != null) {
+                cursor.close();
+            }
+            db.close();
+        }
+    }
     
     public SizeInfo size() {
         SQLiteDatabase db = this.getReadableDatabase();

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

@@ -1,6 +1,7 @@
 package com.stratastorage;
 
 import com.getcapacitor.JSObject;
+import com.getcapacitor.JSArray;
 import com.getcapacitor.Plugin;
 import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
@@ -12,10 +13,15 @@ import android.util.Log;
 import org.json.JSONArray;
 import org.json.JSONException;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Main Capacitor plugin for Strata Storage
- * Coordinates between different storage types on Android
+ * 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.
  */
 @CapacitorPlugin(name = "StrataStorage")
 public class StrataStoragePlugin extends Plugin {
@@ -27,30 +33,58 @@ public class StrataStoragePlugin extends Plugin {
     public void load() {
         try {
             sharedPrefsStorage = new SharedPreferencesStorage(getContext());
+        } catch (Exception e) {
+            Log.e("StrataStorage", "Failed to initialize preferences storage", e);
+        }
+        try {
             encryptedStorage = new EncryptedStorage(getContext());
+        } catch (Exception e) {
+            // Secure storage may be unavailable on some devices/keystores —
+            // keep the rest of the plugin functional.
+            Log.e("StrataStorage", "Failed to initialize encrypted storage", e);
+        }
+        try {
             sqliteStorage = new SQLiteStorage(getContext());
         } catch (Exception e) {
-            // Log error but don't crash - some storage types may not be available
-            Log.e("StrataStorage", "Failed to initialize storage", e);
+            Log.e("StrataStorage", "Failed to initialize SQLite 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."
+        );
+    }
+
     /**
-     * Check if storage is available
+     * Check if a specific storage type is available.
+     * Matches the JS contract: resolves { available: boolean }.
      */
     @PluginMethod
     public void isAvailable(PluginCall call) {
+        String storage = call.getString("storage", "preferences");
+        boolean available;
+        switch (storage) {
+            case "secure":
+                available = encryptedStorage != null;
+                break;
+            case "sqlite":
+                available = sqliteStorage != null;
+                break;
+            case "filesystem":
+                // No native filesystem backend.
+                available = false;
+                break;
+            case "preferences":
+            default:
+                available = sharedPrefsStorage != null;
+                break;
+        }
+
         JSObject result = new JSObject();
-        result.put("available", true);
-        result.put("platform", "android");
-        
-        JSObject adapters = new JSObject();
-        adapters.put("preferences", true);
-        adapters.put("secure", true);
-        adapters.put("sqlite", true);
-        adapters.put("filesystem", true);
-        result.put("adapters", adapters);
-        
+        result.put("available", available);
         call.resolve(result);
     }
 
@@ -66,7 +100,7 @@ public class StrataStoragePlugin extends Plugin {
         }
 
         String storage = call.getString("storage", "preferences");
-        
+
         try {
             Object value = null;
 
@@ -85,6 +119,9 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     value = sqliteStorage.get(key);
                     break;
+                case "filesystem":
+                    rejectUnsupportedFilesystem(call);
+                    return;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -116,33 +153,41 @@ public class StrataStoragePlugin extends Plugin {
 
         Object value = call.getData().opt("value");
         String storage = call.getString("storage", "preferences");
-        
+
         try {
+            boolean ok;
             switch (storage) {
                 case "secure":
                     if (encryptedStorage == null) {
                         call.reject("Encrypted storage not available");
                         return;
                     }
-                    encryptedStorage.set(key, value);
+                    ok = encryptedStorage.set(key, value);
                     break;
                 case "sqlite":
                     if (sqliteStorage == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    sqliteStorage.set(key, value);
+                    ok = sqliteStorage.set(key, value);
                     break;
+                case "filesystem":
+                    rejectUnsupportedFilesystem(call);
+                    return;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
                     }
-                    sharedPrefsStorage.set(key, value);
+                    ok = sharedPrefsStorage.set(key, value);
                     break;
             }
 
+            if (!ok) {
+                call.reject("Failed to persist value to " + storage + " storage");
+                return;
+            }
             call.resolve();
         } catch (Exception e) {
             call.reject("Failed to set value", e);
@@ -161,7 +206,7 @@ public class StrataStoragePlugin extends Plugin {
         }
 
         String storage = call.getString("storage", "preferences");
-        
+
         try {
             switch (storage) {
                 case "secure":
@@ -178,6 +223,9 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     sqliteStorage.remove(key);
                     break;
+                case "filesystem":
+                    rejectUnsupportedFilesystem(call);
+                    return;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -195,13 +243,17 @@ public class StrataStoragePlugin extends Plugin {
     }
 
     /**
-     * Clear storage
+     * Clear storage.
+     * Accepts the JS `pattern` (used as a key prefix) and a legacy `prefix`.
      */
     @PluginMethod
     public void clear(PluginCall call) {
         String storage = call.getString("storage", "preferences");
-        String prefix = call.getString("prefix");
-        
+        String prefix = call.getString("pattern");
+        if (prefix == null) {
+            prefix = call.getString("prefix");
+        }
+
         try {
             switch (storage) {
                 case "secure":
@@ -218,6 +270,9 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     sqliteStorage.clear(prefix);
                     break;
+                case "filesystem":
+                    rejectUnsupportedFilesystem(call);
+                    return;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -241,7 +296,7 @@ public class StrataStoragePlugin extends Plugin {
     public void keys(PluginCall call) {
         String storage = call.getString("storage", "preferences");
         String pattern = call.getString("pattern");
-        
+
         try {
             List<String> keys = null;
 
@@ -260,6 +315,9 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     keys = sqliteStorage.keys(pattern);
                     break;
+                case "filesystem":
+                    rejectUnsupportedFilesystem(call);
+                    return;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -284,7 +342,7 @@ public class StrataStoragePlugin extends Plugin {
     @PluginMethod
     public void size(PluginCall call) {
         String storage = call.getString("storage", "preferences");
-        
+
         try {
             JSObject result = new JSObject();
 
@@ -307,6 +365,9 @@ public class StrataStoragePlugin extends Plugin {
                     result.put("total", sqliteSizeInfo.total);
                     result.put("count", sqliteSizeInfo.count);
                     break;
+                case "filesystem":
+                    rejectUnsupportedFilesystem(call);
+                    return;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -324,5 +385,108 @@ public class StrataStoragePlugin extends Plugin {
             call.reject("Failed to get size", e);
         }
     }
-    
-}
+
+    /**
+     * 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.
+     */
+    @PluginMethod
+    public void query(PluginCall call) {
+        String storage = call.getString("storage", "sqlite");
+        if (!"sqlite".equals(storage)) {
+            call.reject("Query is only supported for the 'sqlite' storage type");
+            return;
+        }
+        if (sqliteStorage == null) {
+            call.reject("SQLite storage not available");
+            return;
+        }
+
+        try {
+            List<Map<String, Object>> rows = sqliteStorage.query();
+            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();
+            result.put("results", results);
+            call.resolve(result);
+        } catch (Exception e) {
+            call.reject("Failed to query SQLite", e);
+        }
+    }
+
+    /**
+     * Android-specific: read an encrypted preference.
+     * Resolves { value: unknown }. Honors an optional `fileName`.
+     */
+    @PluginMethod
+    public void getEncryptedPreference(PluginCall call) {
+        String key = call.getString("key");
+        if (key == null) {
+            call.reject("Key is required");
+            return;
+        }
+        String fileName = call.getString("fileName");
+
+        try {
+            EncryptedStorage store = resolveEncryptedStore(fileName);
+            if (store == null) {
+                call.reject("Encrypted storage not available");
+                return;
+            }
+            JSObject result = new JSObject();
+            result.put("value", store.get(key));
+            call.resolve(result);
+        } catch (Exception e) {
+            call.reject("Failed to read encrypted preference", e);
+        }
+    }
+
+    /**
+     * Android-specific: write an encrypted preference. Honors an optional
+     * `fileName`.
+     */
+    @PluginMethod
+    public void setEncryptedPreference(PluginCall call) {
+        String key = call.getString("key");
+        if (key == null) {
+            call.reject("Key is required");
+            return;
+        }
+        Object value = call.getData().opt("value");
+        String fileName = call.getString("fileName");
+
+        try {
+            EncryptedStorage store = resolveEncryptedStore(fileName);
+            if (store == null) {
+                call.reject("Encrypted storage not available");
+                return;
+            }
+            if (!store.set(key, value)) {
+                call.reject("Failed to persist encrypted preference");
+                return;
+            }
+            call.resolve();
+        } catch (Exception e) {
+            call.reject("Failed to write encrypted preference", e);
+        }
+    }
+
+    /**
+     * Returns the default encrypted store, or builds a file-specific one when a
+     * custom file name is supplied.
+     */
+    private EncryptedStorage resolveEncryptedStore(String fileName) throws Exception {
+        if (fileName == null || fileName.isEmpty()) {
+            return encryptedStorage;
+        }
+        return new EncryptedStorage(getContext(), fileName);
+    }
+}