strata-storage 2.6.0 → 2.7.0

package/AI-INTEGRATION-GUIDE.md

@@ -1,6 +1,6 @@
 # AI Integration Guide - strata-storage
 
-Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.5.0**.
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.7.0**.
 
 ## Installation
 
@@ -18,6 +18,36 @@ Zero runtime dependencies. React, Vue, Angular, and `@capacitor/core` are option
 - **One API, many backends** — `storage` types: `memory`, `localStorage`, `sessionStorage`, `indexedDB`, `cookies`, `cache`, `url`, plus native `preferences`, `secure`, `sqlite`, `filesystem` (Capacitor).
 - **Opt-in features** — encryption, compression, TTL, queries, cross-tab sync, integrity, durable writes, mirroring, snapshots. All off by default.
 
+## Entry points (import map)
+
+| Import | Use for |
+|--------|---------|
+| `strata-storage` | Core API + all web adapters (`memory`, `localStorage`, `sessionStorage`, `indexedDB`, `cookies`, `cache`, `url`). |
+| `strata-storage/capacitor` | Native mobile adapters: `PreferencesAdapter`, `SecureAdapter`, `SqliteAdapter`, `FilesystemAdapter`. |
+| `strata-storage/firebase` | `enableFirebaseSync`, `isFirebaseAvailable` — cross-device Firestore / Realtime DB sync. `firebase` is an optional peer dep. |
+| `strata-storage/react` | `createStrataHooks` (provider-free) + `<StrataProvider>`. |
+| `strata-storage/vue` | `createStrataComposables` + `StrataPlugin`. |
+| `strata-storage/angular` | `provideStrata` / `StrataService` (RxJS). |
+
+## Choosing a backend (decision guide)
+
+Pick the `storage` per the host project's needs:
+
+- **Web, small & persistent** → `localStorage` (sync-capable).
+- **Web, large / structured / queryable** → `indexedDB`.
+- **Web, offline assets / big blobs** → `cache`.
+- **Shareable UI state in the URL** → `url`.
+- **Server-readable small data** → `cookies`.
+- **Temporary / tests** → `memory`.
+- **Mobile (Capacitor), sensitive** → `secure` (Keychain/Keystore).
+- **Mobile, structured / multi-store** → `sqlite` (isolated `(database, table)`).
+- **Mobile, document-shaped values** → `filesystem`.
+- **Mobile, simple settings** → `preferences`.
+- **Cross-device / multi-user sync** → `firestore` or `realtime` (Firebase).
+
+Layer features on top regardless of backend: `encrypt`, `compress`, `ttl`,
+`tags`+`query`, cross-tab `sync`, `integrity`/`durable`/`mirror`.
+
 ## Quick Start
 
 ### Default instance (simplest)
@@ -160,15 +190,68 @@ const storage = defineStorage();
 
 ```typescript
 import { defineStorage } from 'strata-storage';
-import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
+import {
+  PreferencesAdapter,
+  SecureAdapter,
+  SqliteAdapter,
+  FilesystemAdapter,
+} from 'strata-storage/capacitor';
 
 const storage = defineStorage();
 storage.registerAdapter(new PreferencesAdapter());
-storage.registerAdapter(new SecureStorageAdapter());
+storage.registerAdapter(new SecureAdapter());
+storage.registerAdapter(new SqliteAdapter());       // 2.6.0 — multi-store (database + table)
+storage.registerAdapter(new FilesystemAdapter());   // 2.6.0 — file-per-key, atomic writes
 await storage.set('secret', token, { storage: 'secure' });
 ```
 
-Native adapters depend on the downstream Capacitor project setup; verify behavior on-device.
+**SQLite multi-store** (2.6.0): each `new SqliteAdapter({ database, table })` is an isolated store — distinct `(database, table)` pairs map to distinct physical `.db` files / tables natively and cannot collide. **Filesystem** (2.6.0): one JSON file per key under the app's documents/files directory; `isAvailable()` now returns `true` on iOS and Android.
+
+Native adapters depend on the downstream Capacitor project setup; follow the [device-verification guide](https://stratastorage-docs.aoneahsan.com/guides/platforms/device-verification) to verify on a real iOS + Android device.
+
+### Firebase cross-device sync (optional)
+
+`firebase` is an optional peer dependency, loaded dynamically only when used.
+
+```typescript
+import { enableFirebaseSync, isFirebaseAvailable } from 'strata-storage/firebase';
+
+await enableFirebaseSync(storage, {
+  apiKey: '…', authDomain: '…', projectId: '…', appId: '…',
+  firestore: true,          // registers the `firestore` adapter
+  realtimeDatabase: true,   // registers the `realtime` adapter
+  collectionName: 'strata-storage', // optional (default)
+});
+
+await storage.set('profile', data, { storage: 'firestore' });
+storage.subscribe((c) => { if (c.source === 'remote') apply(c); }, { storage: 'firestore' });
+```
+
+`firestore` is observable + queryable; `realtime` is observable. **Neither is
+encrypted at rest by Strata** — combine with `encrypt: true` and/or Firebase
+Security Rules for confidentiality. `firestore.size()` returns `{ total: 0, count: 0 }`.
+Note: `'firestore'`/`'realtime'` are runtime adapter names (not in the `StorageType`
+union), so strict TS may need a cast on the per-call options object.
+
+## Encryption & security (2.7.0)
+
+```typescript
+const storage = defineStorage({
+  encryption: {
+    enabled: true,
+    password: 'user-derived-password',
+    algorithm: 'AES-GCM',  // default; or 'AES-CBC' (authenticated via Encrypt-then-MAC)
+    iterations: 600000,    // PBKDF2 default (OWASP); stored per-record, used on decrypt
+  },
+});
+```
+
+- **`AES-GCM`** (default) is AEAD. **`AES-CBC`** is authenticated with
+  Encrypt-then-MAC (HMAC-SHA256 over `iv ‖ ciphertext`, verified before decrypt).
+- **Breaking:** legacy AES-CBC ciphertexts written before authentication have no
+  MAC and now fail closed with a "re-encrypt" error — re-encrypt them or use GCM.
+  GCM data is unaffected.
+- Encryption runs on the Web Crypto API on web, Capacitor webviews, and Node 20+ (SSR).
 
 ## Strata API (most-used methods)
 
@@ -200,9 +283,13 @@ Native adapters depend on the downstream Capacitor project setup; verify behavio
 
 ## Links
 
-- [README](./README.md)
-- [Changelog](./CHANGELOG.md)
-- [Core API](./docs/api/core/strata.md)
-- [URL Adapter](./docs/api/adapters/web/url.md)
-- [Recovery & Integrity](./docs/api/features/recovery.md)
-- [GitHub](https://github.com/aoneahsan/strata-storage)
+Full documentation lives at **https://stratastorage-docs.aoneahsan.com**:
+
+- [Documentation home](https://stratastorage-docs.aoneahsan.com/)
+- [For AI Agents (this guide, expanded)](https://stratastorage-docs.aoneahsan.com/ai)
+- [Core API](https://stratastorage-docs.aoneahsan.com/api/core/strata)
+- [Firebase sync](https://stratastorage-docs.aoneahsan.com/guides/platforms/firebase)
+- [URL Adapter](https://stratastorage-docs.aoneahsan.com/api/adapters/web/url)
+- [Recovery & Integrity](https://stratastorage-docs.aoneahsan.com/api/features/recovery)
+- [Changelog](https://stratastorage-docs.aoneahsan.com/reference/changelog)
+- Machine-readable: [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt) · [`/llms-full.txt`](https://stratastorage-docs.aoneahsan.com/llms-full.txt)

package/README.md

@@ -7,9 +7,9 @@
 [![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
-[![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://github.com/aoneahsan/strata-storage)
+[![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://stratastorage.aoneahsan.com)
 
-- **Version:** `2.5.0`
+- **Version:** `2.7.0`
 - **License:** Apache-2.0
 - **Node.js:** `>= 24.13.0`
 - **Module format:** ESM only
@@ -71,7 +71,7 @@ await storage.set('token', '...', { encrypt: true });
 
 ## Provider-Free Usage
 
-The recommended pattern across all frameworks: create one instance and bind to it. No Provider, plugin, or module is required. The Provider-based styles remain available and are documented in [docs/examples/frameworks](./docs/examples/frameworks).
+The recommended pattern across all frameworks: create one instance and bind to it. No Provider, plugin, or module is required. The Provider-based styles remain available and are documented in the [examples](https://stratastorage-docs.aoneahsan.com/examples).
 
 ### Vanilla JavaScript / TypeScript
 
@@ -390,15 +390,22 @@ const active = await storage.query({
 
 ### iOS and Android (via Capacitor)
 
-Register native adapters yourself when running under Capacitor:
+Register the native adapters you need when running under Capacitor. All four are zero-runtime-dependency: SQLite is hand-rolled (no plugin dependency) and filesystem uses the platform's native `FileManager` / `java.io.File`.
 
 ```typescript
 import { defineStorage } from 'strata-storage';
-import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
+import {
+  PreferencesAdapter,
+  SecureAdapter,
+  SqliteAdapter,
+  FilesystemAdapter,
+} from 'strata-storage/capacitor';
 
 const storage = defineStorage();
-storage.registerAdapter(new PreferencesAdapter());  // UserDefaults / SharedPreferences
-storage.registerAdapter(new SecureStorageAdapter()); // Keychain / EncryptedSharedPreferences
+storage.registerAdapter(new PreferencesAdapter());   // UserDefaults / SharedPreferences
+storage.registerAdapter(new SecureAdapter()); // Keychain / EncryptedSharedPreferences
+storage.registerAdapter(new SqliteAdapter());        // native SQLite
+storage.registerAdapter(new FilesystemAdapter());    // native files
 
 await storage.set('secret', token, { storage: 'secure' });
 ```
@@ -407,10 +414,25 @@ await storage.set('secret', token, { storage: 'secure' });
 |---------|-------------|-----------------|
 | `preferences` | UserDefaults | SharedPreferences |
 | `secure` | Keychain | EncryptedSharedPreferences |
-| `sqlite` | SQLite | SQLite |
-| `filesystem` | FileManager | Filesystem |
+| `sqlite` | SQLite (multi-store) | SQLite (multi-store) |
+| `filesystem` | FileManager | java.io.File |
 
-> **Honest note:** the native iOS/Android adapters depend on your downstream Capacitor project setup and platform configuration. Behavior on a real device should be verified on-device — native storage cannot be exercised by the web/Node test suite.
+**SQLite multi-store** (2.6.0+): each `SqliteAdapter` instance binds to a `(database, table)` pair, so distinct logical stores map to distinct physical SQLite files / tables and cannot collide.
+
+```typescript
+import { SqliteAdapter } from 'strata-storage/capacitor';
+
+const analytics = defineStorage();
+analytics.registerAdapter(new SqliteAdapter({ database: 'analytics', table: 'events' }));
+
+const audit = defineStorage();
+audit.registerAdapter(new SqliteAdapter({ database: 'audit', table: 'rows' }));
+// → separate physical .db files; writes to `analytics` can never bleed into `audit`.
+```
+
+`await storage.size(true)` aggregates `{ total, count, byStorage, ... }`; native SQLite and filesystem additionally report a per-column byte breakdown (keys / values / metadata) when called on those adapters directly.
+
+> **Honest note:** the native iOS/Android adapters depend on your downstream Capacitor project setup and platform configuration, and native behavior cannot be exercised in a web/Node environment. Follow the [device-verification guide](https://stratastorage-docs.aoneahsan.com/guides/platforms/device-verification) to verify on a real iOS and Android device after integrating.
 
 ### Firebase (optional cloud sync)
 
@@ -419,7 +441,12 @@ import { defineStorage } from 'strata-storage';
 import { enableFirebaseSync } from 'strata-storage/firebase';
 
 const storage = defineStorage();
-await enableFirebaseSync(storage, { apiKey: '…', projectId: '…', firestore: true });
+await enableFirebaseSync(storage, {
+  apiKey: '…', authDomain: '…', projectId: '…', appId: '…',
+  firestore: true,
+});
+// 'firestore' / 'realtime' are runtime adapter names (not in the StorageType
+// union, so strict TS may need a cast on the options object).
 await storage.set('data', value, { storage: 'firestore' });
 ```
 
@@ -436,8 +463,8 @@ await storage.set('data', value, { storage: 'firestore' });
 | `url` | Web | ✅ | async only | Shareable UI state, length-limited |
 | `preferences` | Mobile | ❌ | async only | UserDefaults / SharedPreferences |
 | `secure` | Mobile | ❌ | async only | Keychain / EncryptedSharedPreferences |
-| `sqlite` | Mobile | ❌ | async only | Native SQLite |
-| `filesystem` | Mobile | ❌ | async only | Native files |
+| `sqlite` | Mobile | ❌ | async only | Native SQLite — multi-store via `(database, table)` (2.6.0+) |
+| `filesystem` | Mobile | ❌ | async only | Native files — file-per-key with atomic writes (2.6.0+) |
 
 "async only" means encryption and compression require the `await storage.set(...)` path — the synchronous API cannot encrypt or compress.
 
@@ -451,59 +478,24 @@ Optional peer dependencies (install only the ones you use): `react >= 19.2.3`, `
 
 ## Documentation
 
+📚 **Full documentation: [stratastorage-docs.aoneahsan.com](https://stratastorage-docs.aoneahsan.com)**
+🤖 **For AI agents: [stratastorage-docs.aoneahsan.com/ai](https://stratastorage-docs.aoneahsan.com/ai)** (plus [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt) and [`/llms-full.txt`](https://stratastorage-docs.aoneahsan.com/llms-full.txt))
+
 ### Getting Started
-- [Installation](./docs/getting-started/installation.md) — install and set up
-- [Quick Start](./docs/getting-started/quick-start.md) — running in minutes
-- [Configuration](./docs/getting-started/configuration.md) — configuration options
-
-### Core
-- [API Reference](./docs/api/README.md) — complete API
-- [Core API (`Strata`)](./docs/api/core/strata.md) — the main class
-- [Type Definitions](./docs/api/core/types.md) — TypeScript types
-- [Error Handling](./docs/api/core/errors.md) — error classes
-
-### Storage Adapters
-- [Web Adapters](./docs/api/adapters/README.md#web-adapters)
-  - [localStorage](./docs/api/adapters/web/localstorage.md)
-  - [sessionStorage](./docs/api/adapters/web/sessionstorage.md)
-  - [IndexedDB](./docs/api/adapters/web/indexeddb.md)
-  - [Cookies](./docs/api/adapters/web/cookies.md)
-  - [Cache API](./docs/api/adapters/web/cache.md)
-  - [Memory](./docs/api/adapters/web/memory.md)
-  - [URL](./docs/api/adapters/web/url.md)
-- [Capacitor Adapters](./docs/api/adapters/README.md#capacitor-adapters)
-  - [Preferences](./docs/api/adapters/capacitor/preferences.md)
-  - [Secure Storage](./docs/api/adapters/capacitor/secure.md)
-  - [SQLite](./docs/api/adapters/capacitor/sqlite.md)
-  - [Filesystem](./docs/api/adapters/capacitor/filesystem.md)
+- [Installation](https://stratastorage-docs.aoneahsan.com/installation) · [Quick Start](https://stratastorage-docs.aoneahsan.com/quick-start) · [Configuration](https://stratastorage-docs.aoneahsan.com/configuration)
+
+### API
+- [API Reference](https://stratastorage-docs.aoneahsan.com/api) · [Core (`Strata`)](https://stratastorage-docs.aoneahsan.com/api/core/strata) · [Types](https://stratastorage-docs.aoneahsan.com/api/core/types) · [Errors](https://stratastorage-docs.aoneahsan.com/api/core/errors)
+- [All adapters](https://stratastorage-docs.aoneahsan.com/api/adapters) — web (localStorage, IndexedDB, cookies, Cache, URL, …) + Capacitor (Preferences, Secure, SQLite, Filesystem) + remote (Firebase)
 
 ### Features
-- [Encryption](./docs/guides/features/encryption.md)
-- [Compression](./docs/guides/features/compression.md)
-- [TTL Management](./docs/api/features/ttl.md)
-- [Cross-Tab Sync](./docs/guides/features/sync.md)
-- [Query Engine](./docs/guides/features/queries.md)
-- [Migrations](./docs/guides/features/migrations.md)
-- [Recovery & Integrity](./docs/api/features/recovery.md)
-
-### Platform Guides
-- [Web](./docs/guides/platforms/web.md)
-- [iOS](./docs/guides/platforms/ios.md)
-- [Android](./docs/guides/platforms/android.md)
-- [Capacitor](./docs/guides/platforms/capacitor.md)
-
-### Examples
-- [Basic Usage](./docs/examples/basic-usage.md)
-- [React Integration](./docs/examples/frameworks/react.md)
-- [Vue Integration](./docs/examples/frameworks/vue.md)
-- [Angular Integration](./docs/examples/frameworks/angular.md)
-- [All Examples](./docs/examples/README.md)
-
-### Reference
-- [Changelog](./docs/reference/changelog.md)
-- [FAQ](./docs/reference/faq.md)
-- [Troubleshooting](./docs/reference/troubleshooting.md)
-- [Migration Guide](./docs/MIGRATION.md)
+- [Encryption](https://stratastorage-docs.aoneahsan.com/guides/features/encryption) · [Compression](https://stratastorage-docs.aoneahsan.com/guides/features/compression) · [TTL](https://stratastorage-docs.aoneahsan.com/api/features/ttl) · [Sync](https://stratastorage-docs.aoneahsan.com/guides/features/sync) · [Queries](https://stratastorage-docs.aoneahsan.com/guides/features/queries) · [Migrations](https://stratastorage-docs.aoneahsan.com/guides/features/migrations) · [Recovery & Integrity](https://stratastorage-docs.aoneahsan.com/api/features/recovery)
+
+### Platforms
+- [Web](https://stratastorage-docs.aoneahsan.com/guides/platforms/web) · [iOS](https://stratastorage-docs.aoneahsan.com/guides/platforms/ios) · [Android](https://stratastorage-docs.aoneahsan.com/guides/platforms/android) · [Capacitor](https://stratastorage-docs.aoneahsan.com/guides/platforms/capacitor) · [Firebase](https://stratastorage-docs.aoneahsan.com/guides/platforms/firebase)
+
+### Examples & Reference
+- [Examples](https://stratastorage-docs.aoneahsan.com/examples) · [Changelog](https://stratastorage-docs.aoneahsan.com/reference/changelog) · [FAQ](https://stratastorage-docs.aoneahsan.com/reference/faq) · [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troubleshooting) · [Migration](https://stratastorage-docs.aoneahsan.com/migration)
 
 ## Contributing
 
@@ -525,17 +517,25 @@ Apache License 2.0 — see [LICENSE](LICENSE). Free for commercial use, modifica
 
 ## Links
 
-- **NPM Package:** [npmjs.com/package/strata-storage](https://www.npmjs.com/package/strata-storage)
-- **GitHub Repository:** [github.com/aoneahsan/strata-storage](https://github.com/aoneahsan/strata-storage)
-- **Issue Tracker:** [github.com/aoneahsan/strata-storage/issues](https://github.com/aoneahsan/strata-storage/issues)
-- **Documentation:** [github.com/aoneahsan/strata-storage/tree/main/docs](https://github.com/aoneahsan/strata-storage/tree/main/docs)
+- **NPM Package:** https://www.npmjs.com/package/strata-storage
+- **Documentation:** https://stratastorage-docs.aoneahsan.com
+- **Website:** https://stratastorage.aoneahsan.com
 
 ## Support
 
-1. Check the [FAQ](./docs/reference/faq.md)
-2. Search [existing issues](https://github.com/aoneahsan/strata-storage/issues)
-3. Open a [new issue](https://github.com/aoneahsan/strata-storage/issues/new)
+1. Check the [FAQ](https://stratastorage-docs.aoneahsan.com/reference/faq) and [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troubleshooting)
+2. Browse the [documentation](https://stratastorage-docs.aoneahsan.com)
+3. [Contact us / report an issue](https://stratastorage.aoneahsan.com/contact)
 
 ---
 
 Made by [Ahsan Mahmood](https://aoneahsan.com). **One API. Every Storage. Everywhere.**
+
+<!-- project-links:start -->
+## Links
+
+- Live: https://www.npmjs.com/package/strata-storage
+- NPM: https://www.npmjs.com/package/strata-storage
+
+_URL source of truth: `01-code/projects/project-live-urls.json` (auto-generated — do not hand-edit between these markers)._
+<!-- project-links:end -->

package/android/AGENTS.md

@@ -1,9 +1,24 @@
 # AGENTS.md — android/
 
-Last Updated: 2026-05-27
+Last Updated: 2026-06-24
 
 > Agent instructions for Android native development.
 
+> **v2.7.0:** Secure storage THROWS on API < 23 (no plaintext fallback) and
+> `minSdkVersion` is raised to **23**. `FilesystemStorage` writes atomically
+> (`Files.move` ATOMIC_MOVE on API 26+, backup-swap fallback below) — never
+> deletes the old value before the new one commits. Preferences/secure `get()`
+> parses the JSON wrapper back to an object so `StorageValue` (TTL/tags/metadata)
+> round-trips. `EncryptedStorage.objectToJsonString()` serialises arrays via
+> `java.lang.reflect.Array` so primitive arrays (`int[]`, `long[]`, …) round-trip
+> (no lossy `toString()` fallback). **SQLite:** identifiers (`table`/`database`)
+> are now REJECTED (throw → `call.reject`) when not strict SQL identifiers
+> (`^[A-Za-z_][A-Za-z0-9_]*$`) instead of being silently stripped (`#5`);
+> `keys()`/`query()` filter expired rows in SQL and `query()` returns the full
+> `{key, value}` wrapper in one round-trip, plus a new `cleanupExpired`
+> single-`DELETE` on the TTL tick (`#6` — no more per-key `get()` N+1).
+> Device-verify pending.
+
 ## Files
 
 | File | Purpose |
@@ -19,7 +34,7 @@ Last Updated: 2026-05-27
 - **`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 }`.
+- **FilesystemStorage.java:** new class. Writes are atomic (staging temp → `renameTo`). `keys()` excludes `.strata-staging/` artifacts. `size(detailed)` → `{ keys, values, metadata }`.
 - **Pending on-device verification** — see `docs/guides/platforms/device-verification.md`.
 
 ## Agent Rules
@@ -34,7 +49,7 @@ Last Updated: 2026-05-27
 - NEVER concatenate user input into SQL strings
 
 ### Filesystem Safety
-- NEVER read from `strata_storage/.staging/` — staging files are transient
+- NEVER read from `strata_storage/.strata-staging/` — staging files are transient
 - Key sanitisation must be consistent between `set`, `get`, `remove`, and `keys`
 
 ### Plugin Architecture

package/android/CLAUDE.md

@@ -1,6 +1,39 @@
 # CLAUDE.md — android/
 
-Last Updated: 2026-05-27
+Last Updated: 2026-06-24
+
+## v2.7.0 Changes
+
+- **Secure storage no longer degrades to plaintext.** `EncryptedStorage` now
+  THROWS `GeneralSecurityException` on API < 23 instead of silently falling back
+  to unencrypted `SharedPreferences`, and `minSdkVersion` is raised to **23**
+  (EncryptedSharedPreferences requires API 23+). 23 is the floor for the secure
+  guarantees this plugin advertises.
+- **Filesystem writes are atomic.** `FilesystemStorage.set()` commits via
+  `Files.move(ATOMIC_MOVE, REPLACE_EXISTING)` on API 26+, falling back to a
+  backup-swap on API 23–25 — the old value is never deleted before the new one
+  is committed (the prior delete-then-rename could lose data on a failed rename).
+- **Preferences/secure `StorageValue` round-trip fixed.** `StrataStoragePlugin`
+  parses the stored JSON wrapper string back into a `JSObject` on `get()`, so
+  TTL/tags/metadata survive a write→read cycle (matching sqlite/filesystem).
+- **Secure primitive-array serialization fixed.** `EncryptedStorage.objectToJsonString()`
+  now serialises arrays via `java.lang.reflect.Array` (`getLength`/`get`) instead
+  of the `(Object[]) obj` cast, so primitive arrays (`int[]`, `long[]`, …)
+  round-trip instead of falling back to lossy `value.toString()` (`[I@…`).
+- **SQLite identifiers are rejected, not stripped (`#5`).** `SQLiteStorage.sanitizeTable`
+  and `StrataStoragePlugin.sanitizeDatabase` now throw `IllegalArgumentException`
+  on a non-empty name that is not a strict SQL identifier
+  (`^[A-Za-z_][A-Za-z0-9_]*$`) instead of silently removing illegal characters.
+  The throw propagates to the plugin's `try/catch` → `call.reject` (and
+  `getSqliteStore` maps an invalid database to `null` → reject). The TS adapter
+  applies the same allow-list and rejects first; this is defense-in-depth.
+  Values stay bound parameters — identifiers are the only interpolated input.
+- **SQLite `keys()`/`query()` N+1 eliminated (`#6`).** `keys()` now excludes
+  expired rows in SQL (`expires IS NULL OR expires > ?`); `query()` returns the
+  full `StorageValue` wrapper `{key, value}` for each non-expired row in one
+  round-trip; new `cleanupExpired(table)` does a single `DELETE` of expired rows
+  (the TS adapter calls it on its TTL tick). The per-key `get()` loop is gone.
+- All native changes remain pending on-device verification.
 
 ## Android Native Plugin
 
@@ -45,7 +78,7 @@ 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
+are atomic: value is written to `strata_storage/.strata-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.
@@ -67,7 +100,7 @@ app-private). `isAvailable()` returns `true`. `size(detailed)` supported.
 - Use `SQLiteDatabase.query()` or prepared statements
 
 ### Filesystem Safety
-- NEVER read from `strata_storage/.staging/` — staging files are transient
+- NEVER read from `strata_storage/.strata-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
 

package/android/build.gradle

@@ -21,7 +21,11 @@ android {
     namespace "com.stratastorage"
     compileSdkVersion project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
     defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
+        // minSdk 23 (Marshmallow): EncryptedSharedPreferences-backed secure
+        // storage requires API 23+. Below it, "secure" storage would degrade to
+        // plaintext, so 23 is the floor for the security guarantees this plugin
+        // advertises.
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
         targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
         versionCode 1
         versionName "1.0"

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

@@ -8,6 +8,7 @@ import androidx.security.crypto.EncryptedSharedPreferences;
 import androidx.security.crypto.MasterKey;
 import java.security.GeneralSecurityException;
 import java.io.IOException;
+import java.lang.reflect.Array;
 import java.util.Set;
 import java.util.HashSet;
 import java.util.Map;
@@ -18,7 +19,6 @@ 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 {
@@ -42,20 +42,24 @@ public class EncryptedStorage {
                     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();
+            // SECURITY: EncryptedSharedPreferences requires API 23+. Refuse to
+            // silently fall back to UNENCRYPTED SharedPreferences for "secure"
+            // storage — that would persist sensitive data in plaintext while the
+            // caller believes it is encrypted. Reject so the caller can decide.
+            // (minSdkVersion is also raised to 23, so this is defense in depth.)
+            Log.e("StrataStorage", "Secure storage unavailable on API " + Build.VERSION.SDK_INT + " (< 23)");
+            throw new GeneralSecurityException(
+                "Secure storage requires Android API 23 (Marshmallow) or higher; refusing to "
+                    + "fall back to unencrypted storage on API " + Build.VERSION.SDK_INT);
         }
     }
     
-    public boolean set(String key, Object value) {
+    public synchronized boolean set(String key, Object value) {
         try {
             String stringValue;
             if (value instanceof String) {
@@ -74,6 +78,7 @@ public class EncryptedStorage {
                     }
                 }
             }
+            SharedPreferences.Editor editor = encryptedPrefs.edit();
             editor.putString(key, stringValue);
             return editor.commit();
         } catch (Exception e) {
@@ -82,11 +87,12 @@ public class EncryptedStorage {
         }
     }
     
-    public String get(String key) {
+    public synchronized String get(String key) {
         return encryptedPrefs.getString(key, null);
     }
-    
-    public boolean remove(String key) {
+
+    public synchronized boolean remove(String key) {
+        SharedPreferences.Editor editor = encryptedPrefs.edit();
         editor.remove(key);
         return editor.commit();
     }
@@ -95,7 +101,8 @@ public class EncryptedStorage {
         return clear(null);
     }
     
-    public boolean clear(String prefix) {
+    public synchronized boolean clear(String prefix) {
+        SharedPreferences.Editor editor = encryptedPrefs.edit();
         if (prefix != null) {
             // Clear only keys with the given prefix
             Set<String> keysToRemove = new HashSet<>();
@@ -118,7 +125,7 @@ public class EncryptedStorage {
         return keys(null);
     }
     
-    public List<String> keys(String pattern) {
+    public synchronized List<String> keys(String pattern) {
         Set<String> allKeys = encryptedPrefs.getAll().keySet();
         
         if (pattern == null) {
@@ -135,11 +142,11 @@ public class EncryptedStorage {
         return filteredKeys;
     }
     
-    public boolean has(String key) {
+    public synchronized boolean has(String key) {
         return encryptedPrefs.contains(key);
     }
-    
-    public SizeInfo size() {
+
+    public synchronized SizeInfo size() {
         Map<String, ?> all = encryptedPrefs.getAll();
         long totalSize = 0;
         int count = all.size();
@@ -188,9 +195,15 @@ public class EncryptedStorage {
                     jsonArray.put(item);
                 }
             } else {
-                Object[] array = (Object[]) obj;
-                for (Object item : array) {
-                    jsonArray.put(item);
+                // Use java.lang.reflect.Array so EVERY array type round-trips,
+                // including primitive arrays (int[], long[], double[], boolean[],
+                // ...). A direct `(Object[]) obj` cast throws ClassCastException for
+                // primitive arrays, which the caller would swallow and replace with
+                // the lossy `value.toString()` (e.g. "[I@1a2b3c"). Array.get boxes
+                // each primitive element so JSONArray.put stores a real value.
+                int len = Array.getLength(obj);
+                for (int i = 0; i < len; i++) {
+                    jsonArray.put(Array.get(obj, i));
                 }
             }
             return jsonArray.toString();