feat: Native storage package (#96)

Introduces a `native_storage` package for Dart-native access to
platform-specific local and secure storage implementations.

The package provides synchronous and asynchronous wrappers over native
APIs like UserDefaults and Keychain on all platforms.

.github/workflows/native_storage.yaml

@@ -0,0 +1,168 @@
+name: native_storage
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/native_storage.yaml"
+      - "packages/native/storage/**"
+
+# Prevent duplicate runs due to Graphite
+# https://graphite.dev/docs/troubleshooting#why-are-my-actions-running-twice
+concurrency:
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || ''}}
+  cancel-in-progress: true
+
+jobs:
+  analyze_and_format:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # 4.1.2
+      - name: Setup Flutter
+        uses: subosito/flutter-action@1c5eb12d812966ca84680edc38353a0851c8fd56 # 2.14.0
+        with:
+          cache: true
+      - name: Get Packages
+        working-directory: packages/native/storage
+        run: dart pub get
+      - name: Analyze
+        working-directory: packages/native/storage
+        run: dart analyze
+      - name: Format
+        working-directory: packages/native/storage
+        run: dart format --set-exit-if-changed .
+  test_darwin:
+    runs-on: macos-latest-xlarge
+    timeout-minutes: 20
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # 4.1.2
+      - name: Setup Flutter
+        uses: subosito/flutter-action@1c5eb12d812966ca84680edc38353a0851c8fd56 # 2.14.0
+        with:
+          cache: true
+      - name: Get Packages
+        working-directory: packages/native/storage
+        run: dart pub get
+      - name: Test
+        working-directory: packages/native/storage
+        run: dart test
+      - name: Get Packages (Example)
+        working-directory: packages/native/storage/example
+        run: flutter pub get
+      - name: Setup iOS Simulator
+        run: |
+          RUNTIME=$(xcrun simctl list runtimes | grep 'iOS 17' | tail -n 1 | cut -d' ' -f 7)
+          echo "Using runtime: $RUNTIME"
+          xcrun simctl create ios 'iPhone 15 Pro Max' $RUNTIME
+          echo "Booting simulator"
+          xcrun simctl boot ios
+          echo "Booted simulator"
+      - name: Test (iOS)
+        working-directory: packages/native/storage/example
+        run: flutter test -d ios integration_test/storage_test.dart
+      - name: Test (macOS)
+        working-directory: packages/native/storage/example
+        run: flutter test -d macos integration_test/storage_test.dart
+  test_android:
+    runs-on:
+      group: public
+      labels: linux
+    timeout-minutes: 15
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # 4.1.2
+      - name: Setup Flutter
+        uses: subosito/flutter-action@1c5eb12d812966ca84680edc38353a0851c8fd56 # 2.14.0
+        with:
+          cache: true
+      - name: Get Packages (Example)
+        working-directory: packages/native/storage/example
+        run: flutter pub get
+      - name: Enable KVM
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+      - name: Test (Android)
+        uses: ReactiveCircus/android-emulator-runner@6b0df4b0efb23bb0ec63d881db79aefbc976e4b2 # 2.30.1
+        with:
+          # Matches `package:jni` compileSdkVersion
+          # https://github.com/dart-lang/native/blob/001910c9f40d637cb25c19bb500fb89cebdf7450/pkgs/jni/android/build.gradle#L57C23-L57C25
+          api-level: 31
+          arch: x86_64
+          script: cd packages/native/storage/example && flutter test -d emulator integration_test/storage_test.dart
+  test_linux:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # 4.1.2
+      - name: Setup Flutter
+        uses: subosito/flutter-action@1c5eb12d812966ca84680edc38353a0851c8fd56 # 2.14.0
+        with:
+          cache: true
+      - name: Install Build Dependencies
+        run: sudo apt-get update && sudo apt-get install -y clang cmake git ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-12-dev
+      - name: Setup Test Environment
+        working-directory: packages/native/storage
+        run: tool/setup-ci.sh
+      - name: Get Packages
+        working-directory: packages/native/storage
+        run: dart pub get
+      - name: Test
+        working-directory: packages/native/storage
+        run: dart test
+      - name: Get Packages (Example)
+        working-directory: packages/native/storage/example
+        run: flutter pub get
+      - name: Test (Linux)
+        working-directory: packages/native/storage/example
+        run: |
+          # Headless tests require virtual display for the linux tests to run.
+          export DISPLAY=:99
+          sudo Xvfb -ac :99 -screen 0 1280x1024x24 > /dev/null 2>&1 &
+          flutter test -d linux integration_test/storage_test.dart
+  # TODO: Re-enable
+  #       Need to fix this: Git error. Command: `git clone --mirror https://github.com/dart-lang/native /c/Users/runneradmin/.pub-cache\git\cache\native-647c69ed8027da6d6def6bc40efa87cf1a2f76aa`
+  test_windows:
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # 4.1.2
+      - name: Setup Flutter
+        uses: subosito/flutter-action@1c5eb12d812966ca84680edc38353a0851c8fd56 # 2.14.0
+        with:
+          cache: true
+      - name: Get Packages
+        working-directory: packages/native/storage
+        run: dart pub get --no-example
+      # - name: Test
+      #   working-directory: packages/native/storage
+      #   run: dart test
+      - name: Get Packages (Example)
+        working-directory: packages/native/storage/example
+        run: flutter pub get
+      - name: Test (Windows)
+        working-directory: packages/native/storage/example
+        run: flutter test -d windows integration_test/storage_test.dart
+  test_web:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # 4.1.2
+      - name: Setup Flutter
+        uses: subosito/flutter-action@1c5eb12d812966ca84680edc38353a0851c8fd56 # 2.14.0
+        with:
+          cache: true
+      - name: Get Packages
+        working-directory: packages/native/storage
+        run: dart pub get
+      - name: Test (Chrome, dart2js)
+        working-directory: packages/native/storage
+        run: dart test -p chrome
+      - name: Test (Chrome, dart2wasm)
+        working-directory: packages/native/storage
+        run: dart test -p chrome -c dart2wasm

packages/native/storage/.gitignore

@@ -0,0 +1,8 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/
+
+# Avoid committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock
+build/

packages/native/storage/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial version.

packages/native/storage/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 Teo, Inc. (Celest)
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
+
+(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
+
+Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/native/storage/README.md

@@ -0,0 +1,87 @@
+# native_storage
+
+Provides a unified API for accessing platform-native storage functionality, such as the iOS Keychain and Android SharedPreferences.
+Sync and async APIs are provided for all storage operations, where asynchronous APIs use an `Isolate` to perform the operation in 
+a background thread.
+
+> See [Web support](#Web) below for more info on how this package behaves in a browser environment.
+
+## Storage Types
+
+All implementations conform to the `NativeStorage` interface, which provides a simple API for reading and writing key-value pairs.
+There are three variations of `NativeStorage`: `NativeLocalStorage`, `NativeSecureStorage`, and `IsolatedNativeStorage`. 
+By default, a `NativeLocalStorage` instance is returned.
+
+### Local Storage
+
+Using a `NativeLocalStorage` instance, you can read/write values to your application's local data storage which are isolated to your
+application and persisted across app restarts.
+
+```dart
+final storage = NativeStorage();
+storage.write('key', 'value');
+print(storage.read('key')); // value
+```
+
+The local storage APIs are useful for storing non-sensitive data that should persist across app restarts and be deleted alongside the app.
+
+The platform implementations for local `NativeStorage` are:
+
+| Platform | Implementation |
+| -------- | -------------- |
+| iOS/macOS | [UserDefaults](https://developer.apple.com/documentation/foundation/userdefaults) |
+| Android | [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) |
+| Linux | JSON file |
+| Windows | [Registry](https://learn.microsoft.com/en-us/windows/win32/sysinfo/about-the-registry) |
+| Web | [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) |
+
+### Secure Storage
+
+Sometimes you may need to store sensitive data, such as API keys or user credentials, in a way that is more secure than local storage.
+In this case, use the `secure` getter on a `NativeStorage` instance to get a secure variation.
+
+```dart
+final secureStorage = storage.secure;
+secureStorage.write('key', 'value'); // value is encrypted before being stored
+print(secureStorage.read('key')); // value
+```
+
+The platform implementations for `NativeSecureStorage` are:
+
+| Platform | Implementation |
+| -------- | -------------- |
+| iOS/macOS | [Keychain](https://developer.apple.com/documentation/security/keychain_services) |
+| Android | [EncryptedSharedPreferences](https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences) |
+| Linux | [libsecret](https://wiki.gnome.org/Projects/Libsecret) |
+| Windows | [Security and Identity API](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/) |
+| Web | In-Memory (See [Web](#Web)) |
+
+### Isolated Storage
+
+The APIs shown above are all synchronous, which means they will block the main thread while reading/writing data. If you need to perform
+storage operations in the background, use the `isolated` getter on a `NativeStorage` instance to get an isolated variation.
+
+```dart
+final isolatedStorage = storage.isolated;
+await isolated.write('key', 'value'); // value is written in a background thread
+print(await isolated.read('key')); // value
+```
+
+These can be combined to create a secure, isolated storage for example:
+
+```dart
+final secureIsolatedStorage = storage.secure.isolated;
+await secureIsolatedStorage.write('key', 'value'); // value is encrypted and written in a background thread
+print(await secureIsolatedStorage.read); // value
+```
+
+The platform implementations for `IsolatedNativeStorage` are the same as the local/secure storage implementations, but the operations 
+are performed using an [Isolate](https://api.dart.dev/stable/dart-isolate/Isolate-class.html).
+
+### Web
+
+When running in a browser environment, there is [no way](https://auth0.com/blog/secure-browser-storage-the-facts/) to securely persist
+sensitive data. As a result, the `NativeSecureStorage` implementation for web is an in-memory store that does not persist data across
+page reloads. The `NativeLocalStorage` implementation for web, however, uses the browser's `localStorage` API for persistence.
+
+The `IsolatedNativeStorage` implementation for web uses the `NativeLocalStorage` implementation, but does not perform calls in a Web Worker.

packages/native/storage/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:lints/recommended.yaml

packages/native/storage/android/.gitignore

@@ -0,0 +1,8 @@
+*.iml
+.gradle
+local.properties
+.idea/
+.DS_Store
+build
+captures
+.cxx

packages/native/storage/android/build.gradle

@@ -0,0 +1,71 @@
+group 'dev.celest.native_storage'
+version '1.0-SNAPSHOT'
+
+buildscript {
+    ext.kotlin_version = '1.7.21'
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath 'com.android.tools.build:gradle:7.4.2'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+rootProject.allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    // Conditional for compatibility with AGP <4.2.
+    if (project.android.hasProperty("namespace")) {
+        namespace 'dev.celest.native_storage'
+    }
+
+    compileSdk 34
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    kotlinOptions {
+        jvmTarget = '1.8'
+    }
+
+    sourceSets {
+        main.java.srcDirs += 'src/main/kotlin'
+    }
+
+    defaultConfig {
+        minSdkVersion 23
+        consumerProguardFiles 'consumer-rules.pro'
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    testOptions {
+        unitTests {
+            includeAndroidResources = true
+        }
+    }
+}
+
+dependencies {
+    implementation 'androidx.security:security-crypto:[1.1.0-alpha04,)'
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation 'org.robolectric:robolectric:4.10.3'
+    testImplementation 'androidx.test:core-ktx:1.5.0'
+}

packages/native/storage/android/consumer-rules.pro

@@ -0,0 +1 @@
+-keep class dev.celest.native_storage.** { *; }

packages/native/storage/android/settings.gradle

@@ -0,0 +1,6 @@
+rootProject.name = 'native_storage'
+dependencyResolutionManagement {
+   repositories {
+       google()
+   }
+}