-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Loading status checks…
feat: Platform storage package
Introduces a `platform_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.
Showing
194 changed files
with
38,329 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,173 @@ | ||
name: platform_storage | ||
on: | ||
pull_request: | ||
paths: | ||
- ".github/workflows/platform_storage.yaml" | ||
- "packages/platform/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/platform/storage | ||
run: dart pub get | ||
- name: Analyze | ||
working-directory: packages/platform/storage | ||
run: dart analyze | ||
- name: Format | ||
working-directory: packages/platform/storage | ||
run: dart format --set-exit-if-changed . | ||
test_darwin: | ||
needs: analyze_and_format | ||
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/platform/storage | ||
run: dart pub get | ||
- name: Test | ||
working-directory: packages/platform/storage | ||
run: dart test | ||
- name: Get Packages (Example) | ||
working-directory: packages/platform/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/platform/storage/example | ||
run: flutter test -d ios integration_test/storage_test.dart | ||
- name: Test (macOS) | ||
working-directory: packages/platform/storage/example | ||
run: flutter test -d macos integration_test/storage_test.dart | ||
test_android: | ||
needs: analyze_and_format | ||
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/platform/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/platform/storage/example && flutter test -d emulator integration_test/storage_test.dart | ||
test_linux: | ||
needs: analyze_and_format | ||
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/platform/storage | ||
run: tool/setup-ci.sh | ||
- name: Get Packages | ||
working-directory: packages/platform/storage | ||
run: dart pub get | ||
- name: Test | ||
working-directory: packages/platform/storage | ||
run: dart test | ||
- name: Get Packages (Example) | ||
working-directory: packages/platform/storage/example | ||
run: flutter pub get | ||
- name: Test (Linux) | ||
working-directory: packages/platform/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: | ||
needs: analyze_and_format | ||
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/platform/storage | ||
run: dart pub get --no-example | ||
- name: Test | ||
working-directory: packages/platform/storage | ||
run: dart test | ||
- name: Get Packages (Example) | ||
working-directory: packages/platform/storage/example | ||
run: flutter pub get | ||
- name: Test (Windows) | ||
working-directory: packages/platform/storage/example | ||
run: flutter test -d windows integration_test/storage_test.dart | ||
test_web: | ||
needs: analyze_and_format | ||
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/platform/storage | ||
run: dart pub get | ||
- name: Test (Chrome, dart2js) | ||
working-directory: packages/platform/storage | ||
run: dart test -p chrome | ||
- name: Test (Chrome, dart2wasm) | ||
working-directory: packages/platform/storage | ||
run: dart test -p chrome -c dart2wasm |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
## 0.1.0 | ||
|
||
- Initial version. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
# platform_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. | ||
## `PlatformStorage` | ||
|
||
All implementations conform to the `PlatformStorage` interface, which provides a simple API for reading and writing key-value pairs. | ||
|
||
There are two flavors of `PlatformStorage` currently: `PlatformLocalStorage` and `PlatformSecureStorage`. Both are constructed with | ||
a required `namespace` parameter and optional `scope`. The `namespace` represents the isolation boundary of the storage values, while | ||
the `scope` is used to separate storage data between different parts of the app, | ||
|
||
It is recommended to use your application or bundle identifier as the `namespace`. | ||
|
||
### `PlatformLocalStorage` | ||
|
||
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 `PlatformLocalStorage` are: | ||
- **iOS/macOS**: The `UserDefaults` API with a [suite name](https://developer.apple.com/documentation/foundation/nsuserdefaults/1409957-initwithsuitename#discussion) of `namespace<.scope>`. | ||
- **Android**: The `SharedPreferences` API with a [name](https://developer.android.com/reference/android/content/Context.html#getSharedPreferences(java.lang.String,%20int)) of `namespace<.scope>`. | ||
- **Linux**: The `gsettings` API with a schema path of `namespace<.scope>`. | ||
- **Windows**: The `Windows.Storage.ApplicationData.Current.LocalSettings` API with a container name of `namespace<.scope>`. | ||
- **Web**: The `localStorage` API with a key prefix of `namespace<.scope>`. | ||
|
||
### `PlatformSecureStorage` | ||
|
||
The secure storage APIs are useful for storing sensitive data that should persist across app restarts and be deleted alongside the app. | ||
|
||
The platform implementations for `PlatformSecureStorage` are: | ||
- **iOS**: The iOS Keychain with a service name of `namespace<.scope>`. | ||
- **Android**: The Android KeyStore with an alias of `namespace<.scope>`. | ||
- **Linux**: The `libsecret` API with a schema path of `namespace<.scope>`. | ||
- **Windows**: The Windows Credential Locker with a resource name of `namespace<.scope>`. | ||
- **Web**: The `localStorage` API with a key prefix of `namespace<.scope>`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
include: package:lints/recommended.yaml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
*.iml | ||
.gradle | ||
local.properties | ||
.idea/ | ||
.DS_Store | ||
build | ||
captures | ||
.cxx |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
group 'dev.celest.platform_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.platform_storage' | ||
} | ||
|
||
compileSdk 31 | ||
|
||
compileOptions { | ||
sourceCompatibility JavaVersion.VERSION_1_8 | ||
targetCompatibility JavaVersion.VERSION_1_8 | ||
} | ||
|
||
kotlinOptions { | ||
jvmTarget = '1.8' | ||
} | ||
|
||
sourceSets { | ||
main.java.srcDirs += 'src/main/kotlin' | ||
} | ||
|
||
defaultConfig { | ||
minSdkVersion 21 | ||
consumerProguardFiles 'consumer-rules.pro' | ||
} | ||
|
||
buildTypes { | ||
release { | ||
minifyEnabled false | ||
} | ||
} | ||
} | ||
|
||
dependencies { | ||
implementation 'androidx.security:security-crypto:[1.1.0-alpha04,)' | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
-keep class dev.celest.platform_storage.** { *; } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
rootProject.name = 'platform_storage' | ||
dependencyResolutionManagement { | ||
repositories { | ||
google() | ||
} | ||
} |
3 changes: 3 additions & 0 deletions
3
packages/platform/storage/android/src/main/AndroidManifest.xml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
<manifest xmlns:android="http://schemas.android.com/apk/res/android" | ||
package="dev.celest.platform_storage"> | ||
</manifest> |
18 changes: 18 additions & 0 deletions
18
...tform/storage/android/src/main/kotlin/dev/celest/platform_storage/PlatformLocalStorage.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
package dev.celest.platform_storage | ||
|
||
import android.app.Activity | ||
import android.content.Context | ||
import android.content.SharedPreferences | ||
import androidx.annotation.Keep | ||
|
||
@Keep | ||
class PlatformLocalStorage( | ||
mainActivity: Activity, | ||
namespace: String, | ||
scope: String?, | ||
) : PlatformStorage(mainActivity, namespace, scope) { | ||
|
||
override val sharedPreferences: SharedPreferences = | ||
mainActivity.getSharedPreferences(namespace, Context.MODE_PRIVATE) | ||
|
||
} |
33 changes: 33 additions & 0 deletions
33
...form/storage/android/src/main/kotlin/dev/celest/platform_storage/PlatformSecureStorage.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
package dev.celest.platform_storage | ||
|
||
import android.app.Activity | ||
import android.content.SharedPreferences | ||
import androidx.annotation.Keep | ||
import androidx.security.crypto.EncryptedSharedPreferences | ||
import androidx.security.crypto.MasterKey | ||
|
||
// TODO(dnys1): Exclude from backup: | ||
// - https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences | ||
// - https://developer.android.com/guide/topics/data/autobackup#IncludingFiles | ||
@Keep | ||
class PlatformSecureStorage( | ||
mainActivity: Activity, | ||
namespace: String, | ||
scope: String?, | ||
) : PlatformStorage(mainActivity, namespace, scope) { | ||
|
||
override val sharedPreferences: SharedPreferences by lazy { | ||
val masterKey = MasterKey.Builder(mainActivity) | ||
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM) | ||
.build() | ||
val sharedPreferences = EncryptedSharedPreferences.create( | ||
mainActivity, | ||
namespace, | ||
masterKey, | ||
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV, | ||
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM, | ||
) | ||
sharedPreferences | ||
} | ||
|
||
} |
Oops, something went wrong.