Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Platform storage package
Browse files Browse the repository at this point in the history
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.
dnys1 committed Apr 2, 2024
1 parent 4034f52 commit e40b859
Showing 194 changed files with 38,329 additions and 0 deletions.
173 changes: 173 additions & 0 deletions .github/workflows/platform_storage.yaml
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
7 changes: 7 additions & 0 deletions packages/platform/storage/.gitignore
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
3 changes: 3 additions & 0 deletions packages/platform/storage/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
## 0.1.0

- Initial version.
19 changes: 19 additions & 0 deletions packages/platform/storage/LICENSE
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.
39 changes: 39 additions & 0 deletions packages/platform/storage/README.md
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>`.
1 change: 1 addition & 0 deletions packages/platform/storage/analysis_options.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include: package:lints/recommended.yaml
8 changes: 8 additions & 0 deletions packages/platform/storage/android/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
*.iml
.gradle
local.properties
.idea/
.DS_Store
build
captures
.cxx
62 changes: 62 additions & 0 deletions packages/platform/storage/android/build.gradle
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,)'
}
1 change: 1 addition & 0 deletions packages/platform/storage/android/consumer-rules.pro
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
-keep class dev.celest.platform_storage.** { *; }
6 changes: 6 additions & 0 deletions packages/platform/storage/android/settings.gradle
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
rootProject.name = 'platform_storage'
dependencyResolutionManagement {
repositories {
google()
}
}
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>
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)

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

}
Loading

0 comments on commit e40b859

Please sign in to comment.