strata-storage 2.6.0 → 2.7.0

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;
-        }
-    }
-}

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

@@ -1,287 +0,0 @@
-package com.strata.storage;
-
-import android.content.Context;
-import android.util.Log;
-import com.getcapacitor.JSObject;
-import java.io.File;
-import java.io.FileOutputStream;
-import java.io.IOException;
-import java.nio.charset.StandardCharsets;
-import java.net.URLDecoder;
-import java.net.URLEncoder;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.UUID;
-import org.json.JSONException;
-
-/**
- * Filesystem-backed storage. One file per key lives under
- * {@code <filesDir>/strata_storage}. The file name is a reversible
- * URL-encoding of the key (no path separators survive encoding) and the file
- * contents are the JSON-serialized FULL wrapper object ({@code value, created,
- * updated, expires?, tags?, metadata?}), mirroring the SQLite value-shape
- * contract.
- *
- * <p>Writes are atomic: a temp file is written then renamed over the target.
- * All access is synchronized on the instance so overlapping bridge calls are
- * safe.
- */
-public class FilesystemStorage {
-    private static final String DIR_NAME = "strata_storage";
-    private static final String ENCODING = "UTF-8";
-    /**
-     * Reserved subdirectory (inside the storage dir) that holds in-flight temp
-     * files for atomic writes. Because it is a directory, the file-only
-     * enumeration in keys()/size()/clear() skips it automatically, and temp
-     * names therefore can never collide with an encoded key file in the storage
-     * dir (e.g. a real key {@code "backup.tmp"}).
-     */
-    private static final String STAGING_DIR_NAME = ".strata-staging";
-
-    private final File baseDir;
-    private final File stagingDir;
-
-    public FilesystemStorage(Context context) {
-        this.baseDir = new File(context.getFilesDir(), DIR_NAME);
-        this.stagingDir = new File(baseDir, STAGING_DIR_NAME);
-        ensureDir();
-    }
-
-    private synchronized void ensureDir() {
-        if (!baseDir.exists()) {
-            // mkdirs() returns false if it already exists due to a race; the
-            // subsequent exists() check below is the real guard.
-            baseDir.mkdirs();
-        }
-        if (!stagingDir.exists()) {
-            stagingDir.mkdirs();
-        }
-    }
-
-    /** Reversibly encode a key into a path-separator-free file name. */
-    private static String encodeKey(String key) {
-        try {
-            return URLEncoder.encode(key, ENCODING);
-        } catch (Exception e) {
-            // UTF-8 is always supported; fall back defensively.
-            return key.replaceAll("[^A-Za-z0-9_-]", "_");
-        }
-    }
-
-    /** Inverse of {@link #encodeKey(String)}. */
-    private static String decodeKey(String fileName) {
-        try {
-            return URLDecoder.decode(fileName, ENCODING);
-        } catch (Exception e) {
-            return fileName;
-        }
-    }
-
-    private File fileForKey(String key) {
-        return new File(baseDir, encodeKey(key));
-    }
-
-    /**
-     * Read + parse the full wrapper for {@code key}. Missing file → {@code null}.
-     * Unparseable contents → {@code null} (treated as a miss; never throws).
-     */
-    public synchronized JSObject get(String key) {
-        File file = fileForKey(key);
-        if (!file.exists() || !file.isFile()) {
-            return null;
-        }
-        try {
-            String json = readFile(file);
-            return new JSObject(json);
-        } catch (JSONException parseError) {
-            Log.w("StrataStorage", "Unparseable filesystem value for key " + key);
-            return null;
-        } catch (IOException ioError) {
-            Log.e("StrataStorage", "Failed to read filesystem value for key " + key, ioError);
-            return null;
-        }
-    }
-
-    /**
-     * Atomically persist the full wrapper for {@code key}: write a temp file
-     * then rename it over the destination.
-     */
-    public synchronized boolean set(String key, JSObject wrapper) {
-        if (wrapper == null) {
-            return false;
-        }
-        ensureDir();
-        File target = fileForKey(key);
-        // Temp file lives in the staging subdir (same filesystem → atomic
-        // rename) with a UUID name, so it can never collide with a key file.
-        File tmp = new File(stagingDir, UUID.randomUUID().toString() + ".tmp");
-        FileOutputStream fos = null;
-        try {
-            fos = new FileOutputStream(tmp);
-            fos.write(wrapper.toString().getBytes(StandardCharsets.UTF_8));
-            fos.flush();
-            fos.getFD().sync();
-            fos.close();
-            fos = null;
-
-            // Rename is atomic on the same filesystem. Remove a stale target
-            // first since File.renameTo can fail when the destination exists.
-            if (target.exists() && !target.delete()) {
-                Log.w("StrataStorage", "Could not delete existing file before rename: " + key);
-            }
-            if (!tmp.renameTo(target)) {
-                tmp.delete();
-                return false;
-            }
-            return true;
-        } catch (IOException e) {
-            Log.e("StrataStorage", "Failed to set filesystem value for key " + key, e);
-            if (tmp.exists()) {
-                tmp.delete();
-            }
-            return false;
-        } finally {
-            if (fos != null) {
-                try {
-                    fos.close();
-                } catch (IOException ignored) {
-                    // best-effort close
-                }
-            }
-        }
-    }
-
-    public synchronized boolean remove(String key) {
-        File file = fileForKey(key);
-        if (!file.exists()) {
-            return false;
-        }
-        return file.delete();
-    }
-
-    /**
-     * Delete all stored entries. {@code prefix}, when non-null, restricts the
-     * delete to keys whose (decoded) name starts with the prefix.
-     */
-    public synchronized boolean clear(String prefix) {
-        File[] files = baseDir.listFiles();
-        if (files == null) {
-            return true;
-        }
-        boolean ok = true;
-        for (File file : files) {
-            // Skips the staging subdirectory (and any other non-file entry).
-            if (!file.isFile()) {
-                continue;
-            }
-            if (prefix == null || decodeKey(file.getName()).startsWith(prefix)) {
-                if (!file.delete()) {
-                    ok = false;
-                }
-            }
-        }
-        // On a full clear, also drop any orphaned in-flight temp files.
-        if (prefix == null) {
-            File[] temps = stagingDir.listFiles();
-            if (temps != null) {
-                for (File t : temps) {
-                    t.delete();
-                }
-            }
-        }
-        return ok;
-    }
-
-    public synchronized List<String> keys(String pattern) {
-        List<String> keys = new ArrayList<>();
-        File[] files = baseDir.listFiles();
-        if (files == null) {
-            return keys;
-        }
-        for (File file : files) {
-            // Skips the staging subdirectory (and any other non-file entry).
-            if (!file.isFile()) {
-                continue;
-            }
-            String key = decodeKey(file.getName());
-            if (pattern == null || key.contains(pattern)) {
-                keys.add(key);
-            }
-        }
-        return keys;
-    }
-
-    public synchronized boolean has(String key) {
-        File file = fileForKey(key);
-        return file.exists() && file.isFile();
-    }
-
-    /**
-     * Size information. {@code total} = {@code keys} + {@code values} (matching
-     * the web adapters' convention), {@code values} = Σ file byte sizes,
-     * {@code keys} = Σ decoded-key byte lengths, {@code metadata} = Σ length of
-     * the parsed {@code metadata} field (0 when absent or unparseable),
-     * {@code count} = number of stored files. The detailed breakdown is only
-     * surfaced to JS when {@code detailed} is true.
-     */
-    public synchronized SQLiteStorage.SizeInfo size(boolean detailed) {
-        File[] files = baseDir.listFiles();
-        long valuesBytes = 0;
-        long keysBytes = 0;
-        long metadataBytes = 0;
-        int count = 0;
-
-        if (files != null) {
-            for (File file : files) {
-                // Skips the staging subdirectory (and any other non-file entry).
-                if (!file.isFile()) {
-                    continue;
-                }
-                count++;
-                valuesBytes += file.length();
-                keysBytes += decodeKey(file.getName()).getBytes(StandardCharsets.UTF_8).length;
-                if (detailed) {
-                    metadataBytes += metadataByteLength(file);
-                }
-            }
-        }
-
-        if (!detailed) {
-            return new SQLiteStorage.SizeInfo(keysBytes + valuesBytes, count);
-        }
-        return new SQLiteStorage.SizeInfo(keysBytes + valuesBytes, count, keysBytes, valuesBytes, metadataBytes);
-    }
-
-    /** Parse the file and return the byte length of its {@code metadata} field. */
-    private long metadataByteLength(File file) {
-        try {
-            JSObject wrapper = new JSObject(readFile(file));
-            Object metadata = wrapper.opt("metadata");
-            if (metadata != null && metadata != org.json.JSONObject.NULL) {
-                return metadata.toString().getBytes(StandardCharsets.UTF_8).length;
-            }
-        } catch (Exception ignored) {
-            // Unparseable → contributes 0 metadata bytes.
-        }
-        return 0;
-    }
-
-    private String readFile(File file) throws IOException {
-        byte[] data = new byte[(int) file.length()];
-        java.io.FileInputStream fis = null;
-        try {
-            fis = new java.io.FileInputStream(file);
-            int offset = 0;
-            int read;
-            while (offset < data.length
-                    && (read = fis.read(data, offset, data.length - offset)) != -1) {
-                offset += read;
-            }
-        } finally {
-            if (fis != null) {
-                fis.close();
-            }
-        }
-        return new String(data, StandardCharsets.UTF_8);
-    }
-}