Unify Android and iOS config formats

This commit is contained in:
James Babcock committed 2026-10-31 15:43:55 -07:00
1 parent 35a4ae7064
commit 210b111e27
18 files changed
+1116 -427

No files matched your search

@@ -25,13 +25,23 @@ class FaceclawSettings private constructor(context: Context) {
private val prefs: SharedPreferences = context.applicationContext
.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
private val hub = SettingsChangeHub(object : SettingsStorage {
override fun getString(key: String?, defaultValue: String?): String? = prefs.getString(key, defaultValue)
// An imported or hand-edited config can store a setting as a different type than the
// app reads it as (iOS is lenient about this); read it as text rather than crash.
override fun getString(key: String?, defaultValue: String?): String? = try {
prefs.getString(key, defaultValue)
} catch (_: ClassCastException) {
prefs.all[key]?.toString() ?: defaultValue
}
override fun putString(key: String?, value: String?) {
prefs.edit().putString(key, value).apply()
}
override fun getBoolean(key: String?, defaultValue: Boolean): Boolean = prefs.getBoolean(key, defaultValue)
override fun getBoolean(key: String?, defaultValue: Boolean): Boolean = try {
prefs.getBoolean(key, defaultValue)
} catch (_: ClassCastException) {
prefs.all[key]?.toString()?.toBooleanStrictOrNull() ?: defaultValue
}
override fun putBoolean(key: String?, value: Boolean) {
prefs.edit().putBoolean(key, value).apply()
@@ -3,52 +3,68 @@ package com.faceclaw.app
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.content.SharedPreferences
import android.os.Handler
import android.os.Looper
import android.util.AtomicFile
import android.util.Log
import android.util.Xml
import org.xmlpull.v1.XmlPullParser
import java.io.File
import java.io.FileInputStream
import java.io.FileOutputStream
import java.io.IOException
import java.io.InputStream
import java.io.OutputStream
/**
* adb-triggered export/import of the faceclaw_settings SharedPreferences
* file, so configuration (API keys, device addresses, ...) can be moved off a
* release build, where run-as is unavailable. See scripts/pull_config.sh and
* scripts/push_config.sh, which use run-as on debuggable builds and fall back
* to this receiver otherwise.
* adb-triggered export/import of Faceclaw's settings as the JSON document shared with iOS
* (SettingsTransfer; see scripts/config-transfer.md). scripts/pull_config.sh and
* scripts/push_config.sh drive it; it works on release builds, where run-as is unavailable.
*
* adb shell am broadcast -n com.faceclaw.app/.FaceclawSettingsPortReceiver \
* -a com.faceclaw.app.SETTINGS_EXPORT
* adb pull /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-export.xml
* adb shell am broadcast --include-stopped-packages \
* -n com.faceclaw.app/.FaceclawSettingsPortReceiver -a com.faceclaw.app.SETTINGS_EXPORT
* adb pull /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-export.json
*
* adb push settings.xml /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-import.xml
* adb shell am broadcast -n com.faceclaw.app/.FaceclawSettingsPortReceiver \
* -a com.faceclaw.app.SETTINGS_IMPORT
* adb push settings.json /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-import.json
* adb shell am broadcast --include-stopped-packages \
* -n com.faceclaw.app/.FaceclawSettingsPortReceiver -a com.faceclaw.app.SETTINGS_IMPORT
*
* Security: the settings file contains API tokens, so the manifest guards
* this receiver with android.permission.DUMP — a development permission the
* adb shell holds but ordinary apps cannot obtain without adb's help, keeping
* the trigger reachable from adb only. The transfer file lives in
* getExternalFilesDir(), which other apps cannot read on Android 11+ (and
* which the scripts delete as soon as the transfer completes); on the
* Android 7-10 devices minSdk still admits, apps holding READ_EXTERNAL_STORAGE
* could read it during that window.
* Settings live in two SharedPreferences files: FaceclawSettings' own, and NativeScript's
* ApplicationSettings file (prefs.db), which still holds the pairing, onboarding and EvenHub
* localStorage keys. Both are exported, and each imported key is written to the file the app
* reads it from. An import merges: settings missing from the document are left alone.
* It writes through the process's live SharedPreferences, so a running app cannot flush stale
* values over it, then exits so the next launch starts from the imported settings.
*
* Security: the settings contain API tokens, so the manifest guards this receiver with
* android.permission.DUMP — a development permission the adb shell holds but ordinary apps
* cannot obtain without adb's help, keeping the trigger reachable from adb only. The transfer
* file lives in getExternalFilesDir(), which other apps cannot read on Android 11+ (and which
* the scripts delete as soon as the transfer completes); on the Android 7-10 devices minSdk
* still admits, apps holding READ_EXTERNAL_STORAGE could read it during that window.
*/
class FaceclawSettingsPortReceiver : BroadcastReceiver() {
companion object {
private const val TAG = "FaceclawSettingsPort"
const val ACTION_EXPORT = "com.faceclaw.app.SETTINGS_EXPORT"
const val ACTION_IMPORT = "com.faceclaw.app.SETTINGS_IMPORT"
private const val PREFS_FILE = "faceclaw_settings.xml"
private const val EXPORT_NAME = "faceclaw-settings-export.xml"
private const val IMPORT_NAME = "faceclaw-settings-import.xml"
private const val PLATFORM = "android"
private const val SETTINGS_PREFS = "faceclaw_settings" // FaceclawSettings
private const val NATIVESCRIPT_PREFS = "prefs.db" // NativeScript ApplicationSettings
private const val EXPORT_NAME = "faceclaw-settings-export.json"
private const val IMPORT_NAME = "faceclaw-settings-import.json"
private const val BACKUP_NAME = "faceclaw-settings-previous.json"
private enum class StoredAs { STRING, BOOLEAN, NUMBER }
/**
* Keys the app reads through NativeScript's ApplicationSettings rather than FaceclawSettings,
* and the getter it uses (device-addresses.ts, onboarding-state.ts, evenhub/session.ts;
* tests/settings-transfer.test.cjs keeps this list in step with them). prefs.db also holds
* settings abandoned when FaceclawSettings took over, so nothing else is read from it.
*/
private fun nativeScriptKey(key: String): StoredAs? = when {
key == "onboarding.complete" || key == "onboarding.previewOnly" -> StoredAs.BOOLEAN
key == "deviceIdentity.pairedAtMs" -> StoredAs.NUMBER
key.startsWith("deviceAddress.") || key.startsWith("deviceIdentity.") || key.startsWith("evenhub:") -> StoredAs.STRING
else -> null
}
}
override fun onReceive(context: Context, intent: Intent?) {
@@ -57,11 +73,10 @@ class FaceclawSettingsPortReceiver : BroadcastReceiver() {
if (ACTION_EXPORT == action) {
resultData = exportSettings(context)
} else if (ACTION_IMPORT == action) {
resultData = importSettings(context)
// Exit once the broadcast result has been delivered: this
// process may hold stale in-memory SharedPreferences that a
// later apply() would flush over the imported file, and the
// next launch must re-read from disk.
val result = importSettings(context)
resultData = result
if (!result.startsWith("imported:")) return
// Restart cleanly: running code may hold settings it read before the import.
Handler(Looper.getMainLooper()).postDelayed({
Log.i(TAG, "Exiting after settings import")
System.exit(0)
@@ -69,13 +84,15 @@ class FaceclawSettingsPortReceiver : BroadcastReceiver() {
}
} catch (e: Exception) {
Log.e(TAG, "Settings $action failed", e)
resultData = "error: $e"
resultData = "error: ${e.message ?: e}"
}
}
private fun prefsFile(context: Context): File {
return File(context.applicationInfo.dataDir, "shared_prefs/$PREFS_FILE")
}
private fun settingsPrefs(context: Context): SharedPreferences =
context.getSharedPreferences(SETTINGS_PREFS, Context.MODE_PRIVATE)
private fun nativeScriptPrefs(context: Context): SharedPreferences =
context.getSharedPreferences(NATIVESCRIPT_PREFS, Context.MODE_PRIVATE)
@Throws(IOException::class)
private fun externalFile(context: Context, name: String): File {
@@ -84,63 +101,111 @@ class FaceclawSettingsPortReceiver : BroadcastReceiver() {
return File(dir, name)
}
@Throws(IOException::class)
private fun exportSettings(context: Context): String {
val prefs = prefsFile(context)
if (!prefs.exists()) {
return "error: no settings file yet ($prefs)"
private fun appVersion(context: Context): String? =
runCatching { context.packageManager.getPackageInfo(context.packageName, 0).versionName }.getOrNull()
/** Every setting, from the file the app reads it from, as SettingsTransfer values. */
private fun currentSettings(context: Context): Map<String, Any?> {
val values = linkedMapOf<String, Any?>()
for ((key, value) in settingsPrefs(context).all) {
if (key == null || nativeScriptKey(key) != null) continue
val exported = exportable(value)
if (exported != null) values[key] = exported else Log.w(TAG, "Not exporting $key: unsupported type")
}
for ((key, value) in nativeScriptPrefs(context).all) {
val storedAs = nativeScriptKey(key ?: continue) ?: continue
// NativeScript stores numbers as the raw bits of a double in a long.
val exported = if (storedAs == StoredAs.NUMBER && value is Long) {
Double.fromBits(value).takeIf { it.isFinite() }?.let { JsonNumber.of(it) }
} else {
exportable(value)
}
if (exported != null) values[key] = exported else Log.w(TAG, "Not exporting $key: unsupported value")
}
return values
}
private fun exportable(value: Any?): Any? = when (value) {
is String, is Boolean -> value
is Int, is Long -> JsonNumber(value.toString())
is Float -> value.toDouble().takeIf { it.isFinite() }?.let { JsonNumber.of(it) }
else -> null // string sets are unused
}
private fun exportSettings(context: Context): String {
val document = SettingsTransfer.export(currentSettings(context), PLATFORM, appVersion(context))
val out = externalFile(context, EXPORT_NAME)
copy(prefs, out)
writeAtomically(out, document)
return "exported: $out"
}
@Throws(Exception::class)
private fun importSettings(context: Context): String {
val staged = externalFile(context, IMPORT_NAME)
if (!staged.exists()) {
return "error: nothing staged at $staged"
}
validatePrefsXml(staged)
val prefs = prefsFile(context)
prefs.parentFile?.mkdirs()
if (prefs.exists()) {
copy(prefs, File(prefs.path + ".bak"))
val plan = try {
SettingsTransfer.planImport(staged.readText(), PLATFORM)
} finally {
staged.delete() // holds API tokens
}
copy(staged, prefs)
staged.delete()
return "imported: $prefs (previous settings in $PREFS_FILE.bak)"
}
/** Reject files that are not a SharedPreferences <map> document. */
@Throws(Exception::class)
private fun validatePrefsXml(file: File) {
FileInputStream(file).use { input ->
val parser = Xml.newPullParser()
parser.setInput(input, null)
var event = parser.next()
while (event != XmlPullParser.START_TAG && event != XmlPullParser.END_DOCUMENT) {
event = parser.next()
}
if (event != XmlPullParser.START_TAG || "map" != parser.name) {
throw IOException("not a SharedPreferences <map> document")
}
// Walk the rest so malformed XML is caught before it replaces
// the live settings file.
while (parser.next() != XmlPullParser.END_DOCUMENT) { }
}
}
@Throws(IOException::class)
private fun copy(from: File, to: File) {
FileInputStream(from).use { input: InputStream ->
FileOutputStream(to).use { out: OutputStream ->
val buffer = ByteArray(8192)
var n: Int
while (input.read(buffer).also { n = it } > 0) {
out.write(buffer, 0, n)
// Convert everything before writing anything, so a bad value leaves settings untouched.
val settingsWrites = ArrayList<(SharedPreferences.Editor) -> Unit>()
val nativeScriptWrites = ArrayList<(SharedPreferences.Editor) -> Unit>()
for ((key, value) in plan.values) {
when (nativeScriptKey(key)) {
// FaceclawSettings only has string and boolean getters.
null -> if (value is Boolean) {
settingsWrites.add { e -> e.putBoolean(key, value) }
} else {
settingsWrites.add { e -> e.putString(key, text(value)) }
}
StoredAs.STRING -> nativeScriptWrites.add { e -> e.putString(key, text(value)) }
StoredAs.BOOLEAN -> {
val flag = value as? Boolean ?: (value as? String)?.toBooleanStrictOrNull()
?: throw IllegalArgumentException("Setting $key must be a boolean")
nativeScriptWrites.add { e -> e.putBoolean(key, flag) }
}
StoredAs.NUMBER -> {
val number = text(value).toDoubleOrNull()?.takeIf { it.isFinite() }
?: throw IllegalArgumentException("Setting $key must be a number")
nativeScriptWrites.add { e -> e.putLong(key, number.toRawBits()) }
}
}
}
val backup = File(context.filesDir, BACKUP_NAME)
writeAtomically(backup, SettingsTransfer.export(currentSettings(context), PLATFORM, appVersion(context)))
commit(settingsPrefs(context), settingsWrites)
commit(nativeScriptPrefs(context), nativeScriptWrites)
val skipped = if (plan.skipped.isEmpty()) "" else
" (left out ${plan.skipped.size} ${plan.sourcePlatform ?: "other-platform"}-only settings)"
return "imported: ${plan.values.size} settings$skipped; previous settings saved in $backup"
}
private fun text(value: Any): String = when (value) {
is JsonNumber -> value.text
else -> value.toString()
}
private fun commit(prefs: SharedPreferences, writes: List<(SharedPreferences.Editor) -> Unit>) {
if (writes.isEmpty()) return
val editor = prefs.edit()
for (write in writes) write(editor)
if (!editor.commit()) throw IOException("Could not save settings")
}
private fun writeAtomically(file: File, text: String) {
val atomic = AtomicFile(file)
val stream = atomic.startWrite()
try {
stream.write(text.toByteArray(Charsets.UTF_8))
atomic.finishWrite(stream)
} catch (e: IOException) {
atomic.failWrite(stream)
throw e
}
}
}
+13 -2
View File
@@ -1,6 +1,17 @@
#import <Foundation/Foundation.h>
/** Developer config transfer through the app container, before workers start. */
NS_ASSUME_NONNULL_BEGIN
/** Converts between this phone's settings and the transfer document (Kotlin SettingsTransfer). */
@protocol FaceclawConfigCodec <NSObject>
/** valuesJson is a JSON object of the settings; nil when they cannot be exported. */
- (nullable NSString *)exportValuesJson:(NSString *)valuesJson platform:(NSString *)platform appVersion:(nullable NSString *)appVersion;
/** A JSON object: {"ok":true,"settings":{...},"skipped":[...],"sourcePlatform":...} or {"ok":false,"message":...}. */
- (NSString *)importPlanDocument:(NSString *)document platform:(NSString *)platform;
@end
/** Developer config transfer through the app container, before workers start (scripts/config-transfer.md). */
@interface FaceclawConfigPort : NSObject
+ (void)processPendingRequest;
+ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain;
+ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain
codec:(id<FaceclawConfigCodec>)codec appVersion:(nullable NSString *)appVersion;
@end
NS_ASSUME_NONNULL_END
+85 -30
View File
@@ -1,57 +1,112 @@
#import "FaceclawConfigPort.h"
#include <math.h>
// The app links FaceclawKit; tests/ios-config-native.cjs builds this file for macOS without it
// and supplies its own codec.
#if __has_include(<FaceclawKit/FaceclawKit.h>)
#import <FaceclawKit/FaceclawKit.h>
@interface FaceclawKitConfigCodec : NSObject <FaceclawConfigCodec>
@end
@implementation FaceclawKitConfigCodec
- (NSString *)exportValuesJson:(NSString *)valuesJson platform:(NSString *)platform appVersion:(NSString *)appVersion {
return [FaceclawKitSettingsTransfer.shared exportValuesJson:valuesJson platform:platform appVersion:appVersion];
}
- (NSString *)importPlanDocument:(NSString *)document platform:(NSString *)platform {
return [FaceclawKitSettingsTransfer.shared importPlanDocument:document platform:platform];
}
@end
#define FACECLAW_CONFIG_CODEC [FaceclawKitConfigCodec new]
#endif
static NSString *const kPlatform = @"ios";
static NSString *const kChangeToken = @"ios.settings.changeToken";
@implementation FaceclawConfigPort
+ (void)processPendingRequest {
#ifdef FACECLAW_CONFIG_CODEC
NSString *library = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES).firstObject;
[self processDirectory:[library stringByAppendingPathComponent:@"FaceclawConfigPort"]
defaults:NSUserDefaults.standardUserDefaults domain:NSBundle.mainBundle.bundleIdentifier];
defaults:NSUserDefaults.standardUserDefaults domain:NSBundle.mainBundle.bundleIdentifier
codec:FACECLAW_CONFIG_CODEC
appVersion:NSBundle.mainBundle.infoDictionary[@"CFBundleShortVersionString"]];
#endif
}
+ (BOOL)validSettings:(id)settings {
if (![settings isKindOfClass:NSDictionary.class] || [settings count] > 4096) return NO;
for (id key in settings) {
// Typed locals, not messages to id: FaceclawKit declares other `count`/`length` properties.
+ (BOOL)validSettings:(id)candidate {
if (![candidate isKindOfClass:NSDictionary.class]) return NO;
NSDictionary *settings = candidate;
if (settings.count > 4096) return NO;
for (id candidateKey in settings) {
if (![candidateKey isKindOfClass:NSString.class]) return NO;
NSString *key = candidateKey;
id value = settings[key];
if (![key isKindOfClass:NSString.class] || ![key length] || [key length] > 512 ||
if (!key.length || key.length > 512 ||
!([value isKindOfClass:NSString.class] || [value isKindOfClass:NSNumber.class])) return NO;
}
return YES;
}
+ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain {
/** The app's settings: strings and finite numbers (booleans included) in its persistent domain. */
+ (NSDictionary *)exportableSettings:(NSDictionary *)domain {
NSMutableDictionary *settings = [NSMutableDictionary new];
for (NSString *key in domain) {
id value = domain[key];
if ([value isKindOfClass:NSString.class] ||
([value isKindOfClass:NSNumber.class] && isfinite([value doubleValue]))) settings[key] = value;
}
[settings removeObjectForKey:kChangeToken];
return settings;
}
+ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain
codec:(id<FaceclawConfigCodec>)codec appVersion:(NSString *)appVersion {
NSString *requestPath = [directory stringByAppendingPathComponent:@"request.json"];
NSData *data = [NSData dataWithContentsOfFile:requestPath];
if (!data) return;
NSFileManager *fm = NSFileManager.defaultManager;
// Consume once. A failed import must never be replayed at a later launch.
[fm removeItemAtPath:requestPath error:nil];
id request = data.length <= 2 * 1024 * 1024 ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil;
// A push embeds a document of up to 2 MiB as a JSON string, which escaping can enlarge.
id request = data.length <= 8 * 1024 * 1024 ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil;
BOOL valid = [request isKindOfClass:NSDictionary.class];
NSString *identifier = valid && [request[@"id"] isKindOfClass:NSString.class] ? request[@"id"] : @"";
NSMutableDictionary *reply = [@{@"id":identifier, @"ok":@NO, @"message":@"Invalid config request"} mutableCopy];
[defaults synchronize];
NSDictionary *before = [defaults persistentDomainForName:domain] ?: @{};
if (valid && [request[@"operation"] isEqual:@"pull"]) {
NSMutableDictionary *settings = [NSMutableDictionary new];
for (NSString *key in before) {
id value = before[key];
if ([value isKindOfClass:NSString.class] || [value isKindOfClass:NSNumber.class]) settings[key] = value;
NSDictionary *settings = [self exportableSettings:before];
NSData *values = [NSJSONSerialization dataWithJSONObject:settings options:0 error:nil];
NSString *document = values ? [codec exportValuesJson:[[NSString alloc] initWithData:values encoding:NSUTF8StringEncoding]
platform:kPlatform appVersion:appVersion] : nil;
if (document) {
reply[@"ok"] = @YES; reply[@"message"] = @"Config exported";
reply[@"document"] = document; reply[@"count"] = @(settings.count);
} else reply[@"message"] = @"Could not encode settings";
} else if (valid && [request[@"operation"] isEqual:@"push"] && [request[@"document"] isKindOfClass:NSString.class]) {
NSData *planData = [[codec importPlanDocument:request[@"document"] platform:kPlatform] dataUsingEncoding:NSUTF8StringEncoding];
id plan = planData ? [NSJSONSerialization JSONObjectWithData:planData options:0 error:nil] : nil;
NSDictionary *settings = [plan isKindOfClass:NSDictionary.class] ? plan[@"settings"] : nil;
if (![plan isKindOfClass:NSDictionary.class] || ![plan[@"ok"] isEqual:@YES]) {
id message = [plan isKindOfClass:NSDictionary.class] ? plan[@"message"] : nil;
reply[@"message"] = [message isKindOfClass:NSString.class] ? message : @"Invalid config";
} else if (![self validSettings:settings]) {
reply[@"message"] = @"Invalid config";
} else {
NSError *error = nil;
NSData *backup = [NSPropertyListSerialization dataWithPropertyList:before format:NSPropertyListBinaryFormat_v1_0 options:0 error:&error];
if (backup && [backup writeToFile:[directory stringByAppendingPathComponent:@"previous.plist"] options:NSDataWritingAtomic error:&error]) {
NSMutableDictionary *next = [before mutableCopy];
[next addEntriesFromDictionary:settings];
next[kChangeToken] = NSUUID.UUID.UUIDString;
[defaults setPersistentDomain:next forName:domain];
if ([defaults synchronize]) {
reply[@"ok"] = @YES; reply[@"message"] = @"Config imported";
reply[@"count"] = @(settings.count);
if ([plan[@"skipped"] isKindOfClass:NSArray.class]) reply[@"skipped"] = plan[@"skipped"];
if ([plan[@"sourcePlatform"] isKindOfClass:NSString.class]) reply[@"sourcePlatform"] = plan[@"sourcePlatform"];
} else {
[defaults setPersistentDomain:before forName:domain]; [defaults synchronize];
reply[@"message"] = @"Could not persist config; restored previous settings";
}
} else reply[@"message"] = @"Could not back up existing settings; import skipped";
}
[settings removeObjectForKey:@"ios.settings.changeToken"];
reply[@"config"] = @{@"schema":@1, @"settings":settings}; reply[@"ok"] = @YES;
reply[@"message"] = @"Config exported";
} else if (valid && [request[@"operation"] isEqual:@"push"] && [self validSettings:request[@"settings"]]) {
NSError *error = nil;
NSData *backup = [NSPropertyListSerialization dataWithPropertyList:before format:NSPropertyListBinaryFormat_v1_0 options:0 error:&error];
if (backup && [backup writeToFile:[directory stringByAppendingPathComponent:@"previous.plist"] options:NSDataWritingAtomic error:&error]) {
NSMutableDictionary *next = [before mutableCopy];
[next addEntriesFromDictionary:request[@"settings"]];
next[@"ios.settings.changeToken"] = NSUUID.UUID.UUIDString;
[defaults setPersistentDomain:next forName:domain];
if ([defaults synchronize]) {
reply[@"ok"] = @YES; reply[@"message"] = @"Config imported";
reply[@"count"] = @([request[@"settings"] count]);
} else {
[defaults setPersistentDomain:before forName:domain]; [defaults synchronize];
reply[@"message"] = @"Could not persist config; restored previous settings";
}
} else reply[@"message"] = @"Could not back up existing settings; import skipped";
}
NSData *response = [NSJSONSerialization dataWithJSONObject:reply options:NSJSONWritingPrettyPrinted error:nil];
[response writeToFile:[directory stringByAppendingPathComponent:@"response.json"] options:NSDataWritingAtomic error:nil];