strata-storage 2.6.1 → 2.7.1

package/dist/android/AGENTS.md

@@ -1,51 +0,0 @@
-# AGENTS.md — android/
-
-Last Updated: 2026-05-27
-
-> 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 via EncryptedSharedPreferences (`com.strata.storage`); requires `androidx.security:security-crypto 1.1.0` (stable, upgraded in v2.6.0) |
-| `SQLiteStorage.java` | SQLite database storage — multi-store (v2.6.0): `database`/`table` options honoured, full `StorageValue` wrapper round-trip, `size(detailed)` supported (`com.strata.storage`) |
-| `FilesystemStorage.java` | File-per-key native storage under `getFilesDir()/strata_storage/` (new in v2.6.0); atomic writes via staging rename; `isAvailable()` returns `true`; no external permissions needed (`com.strata.storage`) |
-
-## v2.6.0 Notes
-
-- **`androidx.security 1.1.0`:** upgraded from `1.1.0-alpha06`. Requires `compileSdkVersion 34`. If Gradle sync fails, bump `compileSdkVersion` and `targetSdkVersion` to 34 in `android/app/build.gradle`.
-- **SQLite multi-store:** `call.getString("database")` and `call.getString("table")` are now read and used. Each `(database, table)` pair → distinct `.db` file. Previously ignored.
-- **SQLite value shape:** native `get` returns full `StorageValue` wrapper. Corrupt rows → treated as miss (no throw).
-- **FilesystemStorage.java:** new class. Writes are atomic (staging temp → `renameTo`). `keys()` excludes `.staging/` artifacts. `size(detailed)` → `{ keys, values, metadata }`.
-- **Pending on-device verification** — see `docs/guides/platforms/device-verification.md`.
-
-## Agent Rules
-
-### Security (IRON-SOLID)
-- Sensitive data MUST use `EncryptedStorage`
-- NEVER store secrets in `SharedPreferencesStorage`
-- `androidx.security:security-crypto` version MUST be `1.1.0` (stable) — not alpha
-
-### SQL Safety (IRON-SOLID)
-- ALWAYS use parameterized queries
-- NEVER concatenate user input into SQL strings
-
-### 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.java`
-- Each storage backend is a separate Java class
-- Two package paths: `com.stratastorage` (plugin) and `com.strata.storage` (impl)
-
-### Build
-- `compileSdkVersion 34` required for `androidx.security 1.1.0`
-- Verify Gradle build succeeds after any change
-
-### Before Modifying
-- Understand Capacitor plugin protocol for Android
-- Test on Android emulator after changes; follow device-verification guide

package/dist/android/CLAUDE.md

@@ -1,89 +0,0 @@
-# CLAUDE.md — android/
-
-Last Updated: 2026-05-27
-
-## 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 (`androidx.security 1.1.0`) |
-| `SQLiteStorage.java` | `src/main/java/com/strata/storage/` | SQLite database storage — multi-store (v2.6.0) |
-| `FilesystemStorage.java` | `src/main/java/com/strata/storage/` | File-per-key storage under `Context.getFilesDir()/strata_storage/` (new in v2.6.0) |
-
-### 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).
-
-## v2.6.0 Changes
-
-### `androidx.security:security-crypto` 1.1.0 (stable)
-`EncryptedStorage.java` depends on `androidx.security:security-crypto`. The
-dependency was upgraded from `1.1.0-alpha06` to `1.1.0` (stable) in v2.6.0.
-The `EncryptedSharedPreferences` / `MasterKey` API is unchanged. The stable
-version requires `compileSdkVersion 34` — if Gradle sync fails after this
-change, bump `compileSdkVersion` and `targetSdkVersion` in
-`android/app/build.gradle` to 34.
-
-### SQLite multi-store
-`SQLiteStorage.java` now accepts `database` and `table` parameters from
-`call.getString("database")` / `call.getString("table")`. Each unique pair
-opens a distinct `.db` file in the app's internal storage. Table identifiers
-are sanitised to `[A-Za-z0-9_]`. The full `StorageValue` wrapper is serialised
-to JSON and stored in a single `value` column; native `get` returns the full
-wrapper so TTL, tags, and metadata survive the round-trip. `size(detailed)`
-returns per-column byte breakdown.
-
-### FilesystemStorage.java (new)
-Stores each key as `getFilesDir()/strata_storage/<sanitised-key>.json`. Writes
-are atomic: value is written to `strata_storage/.staging/<key>.tmp`, then
-renamed into place using `renameTo()`. Staging artifacts are excluded from
-`keys()`. No external filesystem permissions are needed (`getFilesDir()` is
-app-private). `isAvailable()` returns `true`. `size(detailed)` 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 `EncryptedStorage` (EncryptedSharedPreferences)
-- NEVER store credentials, tokens, or secrets in `SharedPreferencesStorage`
-- Follow Android Keystore best practices
-- `androidx.security:security-crypto 1.1.0` (stable) is the required version
-
-### SQL Safety (IRON-SOLID)
-- ALWAYS use parameterized queries in `SQLiteStorage`
-- NEVER concatenate user input into SQL strings
-- Use `SQLiteDatabase.query()` or prepared statements
-
-### Filesystem Safety
-- NEVER read from `strata_storage/.staging/` — staging files are transient
-- Key sanitisation must be consistent between `set`, `get`, `remove`, and `keys`
-- `getFilesDir()` is app-private; no external storage permissions required
-
-### 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
-- Two package paths: `com.stratastorage` (plugin) and `com.strata.storage` (impl)
-
-### Build
-- Gradle-based build system
-- `compileSdkVersion 34` required for `androidx.security 1.1.0`
-- Proguard rules configured for release builds
-- Test on Android emulator after changes; follow device-verification guide
-
-### Before Modifying
-- Understand the Capacitor plugin protocol for Android
-- Test on Android emulator after changes
-- Verify Gradle build succeeds

package/dist/android/build.gradle

@@ -1,58 +0,0 @@
-ext {
-    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
-    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
-    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
-    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
-}
-
-buildscript {
-    repositories {
-        google()
-        mavenCentral()
-    }
-    dependencies {
-        classpath 'com.android.tools.build:gradle:8.2.1'
-    }
-}
-
-apply plugin: 'com.android.library'
-
-android {
-    namespace "com.stratastorage"
-    compileSdkVersion project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
-    defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
-        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
-        versionCode 1
-        versionName "1.0"
-        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
-    }
-    buildTypes {
-        release {
-            minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
-        }
-    }
-    lintOptions {
-        abortOnError false
-    }
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_17
-        targetCompatibility JavaVersion.VERSION_17
-    }
-}
-
-repositories {
-    google()
-    mavenCentral()
-}
-
-dependencies {
-    implementation fileTree(dir: 'libs', include: ['*.jar'])
-    implementation project(':capacitor-android')
-    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
-    implementation 'androidx.security:security-crypto:1.1.0'
-    testImplementation "junit:junit:$junitVersion"
-    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
-    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
-}

package/dist/android/proguard-rules.pro

@@ -1,11 +0,0 @@
-# Add project specific ProGuard rules here.
-
-# Keep StrataStorage plugin classes
--keep class com.stratastorage.** { *; }
--keep class com.strata.storage.** { *; }
-
-# Keep Capacitor classes
--keep class com.getcapacitor.** { *; }
-
-# Keep security crypto classes for encrypted storage
--keep class androidx.security.crypto.** { *; }

package/dist/android/settings.gradle

@@ -1,2 +0,0 @@
-include ':strata-storage'
-project(':strata-storage').projectDir = new File(rootProject.projectDir, '.')

package/dist/android/src/main/AndroidManifest.xml

@@ -1,2 +0,0 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-</manifest>

package/dist/android/src/main/java/com/strata/storage/EncryptedStorage.java

@@ -1,218 +0,0 @@
-package com.strata.storage;
-
-import android.content.Context;
-import android.content.SharedPreferences;
-import android.os.Build;
-import android.util.Log;
-import androidx.security.crypto.EncryptedSharedPreferences;
-import androidx.security.crypto.MasterKey;
-import java.security.GeneralSecurityException;
-import java.io.IOException;
-import java.util.Set;
-import java.util.HashSet;
-import java.util.Map;
-import java.util.List;
-import java.util.ArrayList;
-import org.json.JSONObject;
-import org.json.JSONArray;
-
-public class EncryptedStorage {
-    private SharedPreferences encryptedPrefs;
-    private SharedPreferences.Editor editor;
-    private static final String DEFAULT_NAME = "StrataSecureStorage";
-    
-    public EncryptedStorage(Context context) throws GeneralSecurityException, IOException {
-        this(context, DEFAULT_NAME);
-    }
-
-    public EncryptedStorage(Context context, String name) throws GeneralSecurityException, IOException {
-        String fileName = name != null ? name : DEFAULT_NAME;
-
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-            try {
-                MasterKey masterKey = new MasterKey.Builder(context)
-                    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
-                    .build();
-
-                encryptedPrefs = EncryptedSharedPreferences.create(
-                    context,
-                    fileName,
-                    masterKey,
-                    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
-                    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
-                );
-
-                editor = encryptedPrefs.edit();
-            } catch (GeneralSecurityException | IOException e) {
-                Log.e("StrataStorage", "Failed to initialize encrypted storage", e);
-                throw e;
-            }
-        } else {
-            Log.w("StrataStorage", "API < 23, using unencrypted SharedPreferences");
-            // Fallback to regular SharedPreferences for older devices
-            encryptedPrefs = context.getSharedPreferences(fileName, Context.MODE_PRIVATE);
-            editor = encryptedPrefs.edit();
-        }
-    }
-    
-    public boolean set(String key, Object value) {
-        try {
-            String stringValue;
-            if (value instanceof String) {
-                stringValue = (String) value;
-            } else {
-                // Convert complex objects to JSON
-                if (value instanceof JSONObject) {
-                    stringValue = ((JSONObject) value).toString();
-                } else {
-                    // Use helper method to convert object to JSON string
-                    try {
-                        stringValue = objectToJsonString(value);
-                    } catch (Exception e) {
-                        // Fallback to string representation
-                        stringValue = value.toString();
-                    }
-                }
-            }
-            editor.putString(key, stringValue);
-            return editor.commit();
-        } catch (Exception e) {
-            Log.e("StrataStorage", "Failed to set value in encrypted storage", e);
-            return false;
-        }
-    }
-    
-    public String get(String key) {
-        return encryptedPrefs.getString(key, null);
-    }
-    
-    public boolean remove(String key) {
-        editor.remove(key);
-        return editor.commit();
-    }
-    
-    public boolean clear() {
-        return clear(null);
-    }
-    
-    public boolean clear(String prefix) {
-        if (prefix != null) {
-            // Clear only keys with the given prefix
-            Set<String> keysToRemove = new HashSet<>();
-            for (String key : encryptedPrefs.getAll().keySet()) {
-                if (key.startsWith(prefix) || key.contains(prefix)) {
-                    keysToRemove.add(key);
-                }
-            }
-            for (String key : keysToRemove) {
-                editor.remove(key);
-            }
-        } else {
-            // Clear all keys
-            editor.clear();
-        }
-        return editor.commit();
-    }
-    
-    public List<String> keys() {
-        return keys(null);
-    }
-    
-    public List<String> keys(String pattern) {
-        Set<String> allKeys = encryptedPrefs.getAll().keySet();
-        
-        if (pattern == null) {
-            return new ArrayList<>(allKeys);
-        }
-        
-        // Filter keys by pattern
-        List<String> filteredKeys = new ArrayList<>();
-        for (String key : allKeys) {
-            if (key.startsWith(pattern) || key.contains(pattern)) {
-                filteredKeys.add(key);
-            }
-        }
-        return filteredKeys;
-    }
-    
-    public boolean has(String key) {
-        return encryptedPrefs.contains(key);
-    }
-    
-    public SizeInfo size() {
-        Map<String, ?> all = encryptedPrefs.getAll();
-        long totalSize = 0;
-        int count = all.size();
-        
-        for (Map.Entry<String, ?> entry : all.entrySet()) {
-            String key = entry.getKey();
-            Object value = entry.getValue();
-            
-            // Estimate size (key + value in bytes)
-            totalSize += key.getBytes().length;
-            if (value != null) {
-                totalSize += value.toString().getBytes().length;
-            }
-        }
-        
-        return new SizeInfo(totalSize, count);
-    }
-    
-    /**
-     * Convert an object to JSON string using reflection
-     */
-    private String objectToJsonString(Object obj) throws Exception {
-        if (obj == null) {
-            return "null";
-        }
-        
-        if (obj instanceof String || obj instanceof Number || obj instanceof Boolean) {
-            return obj.toString();
-        }
-        
-        if (obj instanceof Map) {
-            JSONObject jsonObj = new JSONObject();
-            Map<?, ?> map = (Map<?, ?>) obj;
-            for (Map.Entry<?, ?> entry : map.entrySet()) {
-                String key = entry.getKey().toString();
-                jsonObj.put(key, entry.getValue());
-            }
-            return jsonObj.toString();
-        }
-        
-        if (obj instanceof List || obj.getClass().isArray()) {
-            JSONArray jsonArray = new JSONArray();
-            if (obj instanceof List) {
-                List<?> list = (List<?>) obj;
-                for (Object item : list) {
-                    jsonArray.put(item);
-                }
-            } else {
-                Object[] array = (Object[]) obj;
-                for (Object item : array) {
-                    jsonArray.put(item);
-                }
-            }
-            return jsonArray.toString();
-        }
-        
-        // For other objects, create a simple JSON object with their string representation
-        JSONObject jsonObj = new JSONObject();
-        jsonObj.put("value", obj.toString());
-        jsonObj.put("type", obj.getClass().getSimpleName());
-        return jsonObj.toString();
-    }
-    
-    /**
-     * Size information class
-     */
-    public static class SizeInfo {
-        public final long total;
-        public final int count;
-        
-        public SizeInfo(long total, int count) {
-            this.total = total;
-            this.count = count;
-        }
-    }
-}