@tokamakdev/plugin-secure-storage 0.1.0-beta.47 → 0.1.0-beta.48

package/README.md

@@ -24,11 +24,19 @@ const value = await secureStorage.get("identity/encryption", {
 });
 
 await secureStorage.delete("identity/encryption");
+
+// string[], sorted
+const names = await secureStorage.keys();
+
+await secureStorage.clear();
 ```
 
 Values are strings; encode binary values before storing them. Only the app can
-read them, and they are never included in synced credential stores or restored
-to another device.
+read them, and they are never synced to other devices.
+
+By default a backup restores a value only to the device that stored it. Set
+`thisDeviceOnly: false` to let a backup restore it to a new device, where the
+platform supports that.
 
 `authentication` binds a value to the device's secure hardware, so it cannot be
 decrypted until the device owner authenticates:
@@ -57,13 +65,15 @@ the platform's default prompt is shown.
 
 ## Platforms
 
-- **iOS:** Keychain items with `ThisDeviceOnly` accessibility. They are included
-  in encrypted backups but restore only to the same device, and they survive
-  deleting and reinstalling the app.
+- **iOS:** Keychain items, which survive deleting and reinstalling the app.
+  They are included in encrypted backups; `thisDeviceOnly` values restore only
+  to the same device.
 - **macOS:** the data protection keychain, which requires a team-signed build
   (`macos-team-id`). Ad-hoc signed builds throw `NotSupportedError`.
 - **Android:** values are encrypted with a per-value Android Keystore key and
   stored in the app's no-backup directory. They are deleted on uninstall.
+  Keystore keys never leave the device, so `thisDeviceOnly: false` throws
+  `NotSupportedError`.
 - **Web and Windows:** no implementation; calls throw `NotSupportedError`.
 
 Removing the device passcode or screen lock makes values stored with

package/android/SecureStoragePlugin.kt

@@ -15,6 +15,9 @@ import android.util.AtomicFile
 import com.tokamak.runtime.TokamakPlugin
 import com.tokamak.runtime.TokamakPluginError
 import com.tokamak.runtime.TokamakPluginReply
+import java.io.ByteArrayOutputStream
+import java.io.DataInputStream
+import java.io.DataOutputStream
 import java.io.File
 import java.io.FileNotFoundException
 import java.security.KeyFactory
@@ -65,6 +68,11 @@ internal class TokamakSecureStoragePlugin(
                 delete(request(arguments).requireString("name"))
                 reply(Result.success(null))
             }
+            "keys" -> execute(reply) { reply(Result.success(keys())) }
+            "clear" -> execute(reply) {
+                clear()
+                reply(Result.success(null))
+            }
             else -> super.call(method, arguments, reply)
         }
     }
@@ -88,6 +96,9 @@ internal class TokamakSecureStoragePlugin(
                 "afterFirstUnlock" -> false
                 else -> throw typeError("readable must be \"whenUnlocked\" or \"afterFirstUnlock\"")
             }
+        if (!request.requireBoolean("thisDeviceOnly")) {
+            throw TokamakPluginError.notSupported("Android keeps secure storage values on this device")
+        }
         val keyId = ByteArray(KEY_ID_SIZE).also(random::nextBytes)
         val spec =
             KeyGenParameterSpec.Builder(alias(keyId), KeyProperties.PURPOSE_DECRYPT)
@@ -97,10 +108,10 @@ internal class TokamakSecureStoragePlugin(
                 .setUnlockedDeviceRequired(unlockedDeviceRequired)
         request.optionalString("authentication")?.let { requireAuthentication(spec, it) }
         val file = file(name)
-        val previousAlias = read(file)?.let(::storedAlias)
+        val previousAlias = read(file)?.let { alias(it.keyId) }
         val publicKey = generatePublicKey(spec)
         try {
-            write(file, keyId + seal(value, publicKey))
+            write(file, seal(name, keyId, value, publicKey).encode())
         } catch (error: Throwable) {
             keyStore.deleteEntry(alias(keyId))
             throw error
@@ -141,7 +152,7 @@ internal class TokamakSecureStoragePlugin(
             .generatePublic(X509EncodedKeySpec(keyPair.public.encoded))
     }
 
-    private fun seal(value: String, publicKey: PublicKey): ByteArray {
+    private fun seal(name: String, keyId: ByteArray, value: String, publicKey: PublicKey): StoredValue {
         val dataKey = KeyGenerator.getInstance("AES").apply { init(DATA_KEY_SIZE) }.generateKey()
         val iv = ByteArray(IV_SIZE).also(random::nextBytes)
         val sealed =
@@ -152,7 +163,7 @@ internal class TokamakSecureStoragePlugin(
             Cipher.getInstance(WRAP)
                 .apply { init(Cipher.ENCRYPT_MODE, publicKey, OAEP) }
                 .doFinal(dataKey.encoded)
-        return wrapped + iv + sealed
+        return StoredValue(name, keyId, wrapped, iv, sealed)
     }
 
     private fun get(request: JSONObject, reply: TokamakPluginReply) {
@@ -164,7 +175,7 @@ internal class TokamakSecureStoragePlugin(
             return
         }
         val privateKey =
-            keyStore.getKey(storedAlias(stored), null) as? PrivateKey
+            keyStore.getKey(alias(stored.keyId), null) as? PrivateKey
                 ?: throw notReadable()
         val unwrap = Cipher.getInstance(WRAP).apply { init(Cipher.DECRYPT_MODE, privateKey, OAEP) }
         val info =
@@ -186,7 +197,7 @@ internal class TokamakSecureStoragePlugin(
         authenticators: Int,
         prompt: String?,
         unwrap: Cipher,
-        stored: ByteArray,
+        stored: StoredValue,
         reply: TokamakPluginReply,
     ) {
         val callback = PromptCallback(reply) { execute(reply) { reply(Result.success(open(stored, unwrap))) } }
@@ -211,26 +222,38 @@ internal class TokamakSecureStoragePlugin(
         }
     }
 
-    /** Opens a stored value laid out as key ID, wrapped data key, IV, then sealed value. */
-    private fun open(stored: ByteArray, unwrap: Cipher): String {
-        val dataKey = SecretKeySpec(unwrap.doFinal(stored, KEY_ID_SIZE, WRAPPED_KEY_SIZE), "AES")
-        val iv = stored.copyOfRange(IV_START, SEALED_START)
+    private fun open(stored: StoredValue, unwrap: Cipher): String {
+        val dataKey = SecretKeySpec(unwrap.doFinal(stored.wrappedKey), "AES")
         return Cipher.getInstance(SEAL)
-            .apply { init(Cipher.DECRYPT_MODE, dataKey, GCMParameterSpec(TAG_SIZE, iv)) }
-            .doFinal(stored, SEALED_START, stored.size - SEALED_START)
+            .apply { init(Cipher.DECRYPT_MODE, dataKey, GCMParameterSpec(TAG_SIZE, stored.iv)) }
+            .doFinal(stored.sealed)
             .decodeToString()
     }
 
     private fun delete(name: String) {
         val file = file(name)
-        val alias = read(file)?.let(::storedAlias) ?: return
+        val stored = read(file) ?: return
         AtomicFile(file).delete()
-        keyStore.deleteEntry(alias)
+        keyStore.deleteEntry(alias(stored.keyId))
+    }
+
+    /** AtomicFile's in-progress and backup files carry a suffix; value files have none. */
+    private fun keys(): List<String> =
+        directory.listFiles { file -> '.' !in file.name }
+            .orEmpty()
+            .mapNotNull { read(it)?.name }
+            .sorted()
+
+    private fun clear() {
+        directory.deleteRecursively()
+        keyStore.aliases().toList()
+            .filter { it.startsWith(ALIAS_PREFIX) }
+            .forEach(keyStore::deleteEntry)
     }
 
-    private fun read(file: File): ByteArray? =
+    private fun read(file: File): StoredValue? =
         try {
-            AtomicFile(file).readFully()
+            StoredValue.decode(AtomicFile(file).readFully())
         } catch (_: FileNotFoundException) {
             null
         }
@@ -251,9 +274,7 @@ internal class TokamakSecureStoragePlugin(
     private fun file(name: String) =
         File(directory, MessageDigest.getInstance("SHA-256").digest(name.toByteArray()).toHex())
 
-    private fun alias(keyId: ByteArray) = "tokamak-secure-storage-${keyId.toHex()}"
-
-    private fun storedAlias(stored: ByteArray) = alias(stored.copyOf(KEY_ID_SIZE))
+    private fun alias(keyId: ByteArray) = ALIAS_PREFIX + keyId.toHex()
 
     private fun ByteArray.toHex() = joinToString("") { "%02x".format(it) }
 
@@ -263,6 +284,9 @@ internal class TokamakSecureStoragePlugin(
     private fun JSONObject.requireString(name: String): String =
         optionalString(name) ?: throw typeError("$name must be a string")
 
+    private fun JSONObject.requireBoolean(name: String): Boolean =
+        opt(name) as? Boolean ?: throw typeError("$name must be a boolean")
+
     private fun JSONObject.optionalString(name: String): String? =
         when (val value = opt(name)) {
             null, JSONObject.NULL -> null
@@ -298,13 +322,8 @@ internal class TokamakSecureStoragePlugin(
 
     private companion object {
         const val KEYSTORE = "AndroidKeyStore"
-        const val KEY_SIZE = 2048
-        const val KEY_ID_SIZE = 16
-        const val WRAPPED_KEY_SIZE = KEY_SIZE / 8
+        const val ALIAS_PREFIX = "tokamak-secure-storage-"
         const val DATA_KEY_SIZE = 256
-        const val IV_SIZE = 12
-        const val IV_START = KEY_ID_SIZE + WRAPPED_KEY_SIZE
-        const val SEALED_START = IV_START + IV_SIZE
         const val TAG_SIZE = 128
         const val WRAP = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
         const val SEAL = "AES/GCM/NoPadding"
@@ -340,6 +359,47 @@ internal class TokamakSecureStoragePlugin(
     }
 }
 
+private const val KEY_SIZE = 2048
+private const val KEY_ID_SIZE = 16
+private const val WRAPPED_KEY_SIZE = KEY_SIZE / 8
+private const val IV_SIZE = 12
+
+/** A value's file: its name, key ID, wrapped data key, IV, then sealed value. */
+private class StoredValue(
+    val name: String,
+    val keyId: ByteArray,
+    val wrappedKey: ByteArray,
+    val iv: ByteArray,
+    val sealed: ByteArray,
+) {
+    fun encode(): ByteArray {
+        val bytes = ByteArrayOutputStream()
+        DataOutputStream(bytes).run {
+            writeUTF(name)
+            write(keyId)
+            write(wrappedKey)
+            write(iv)
+            write(sealed)
+        }
+        return bytes.toByteArray()
+    }
+
+    companion object {
+        fun decode(bytes: ByteArray): StoredValue =
+            DataInputStream(bytes.inputStream()).run {
+                StoredValue(
+                    name = readUTF(),
+                    keyId = readExactly(KEY_ID_SIZE),
+                    wrappedKey = readExactly(WRAPPED_KEY_SIZE),
+                    iv = readExactly(IV_SIZE),
+                    sealed = readBytes(),
+                )
+            }
+
+        private fun DataInputStream.readExactly(size: Int) = ByteArray(size).also(::readFully)
+    }
+}
+
 private class PromptCallback(
     private val reply: TokamakPluginReply,
     private val succeeded: () -> Unit,

package/apple/SecureStoragePlugin.swift

@@ -47,7 +47,10 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
       try set(
         requiredString(arguments, "name"),
         value: requiredString(arguments, "value"),
-        readable: requiredString(arguments, "readable"),
+        accessibility: accessibility(
+          requiredString(arguments, "readable"),
+          thisDeviceOnly: requiredBool(arguments, "thisDeviceOnly")
+        ),
         authentication: optionalString(arguments, "authentication")
       )
       return nil
@@ -57,7 +60,12 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
         prompt: optionalString(arguments, "prompt")
       )
     case "delete":
-      try delete(requiredString(arguments, "name"))
+      try deleteItems(query(requiredString(arguments, "name")))
+      return nil
+    case "keys":
+      return try keys()
+    case "clear":
+      try deleteItems(serviceQuery())
       return nil
     default:
       throw .notSupported("\(id).\(method) is not supported")
@@ -69,12 +77,11 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
   private func set(
     _ name: String,
     value: String,
-    readable: String,
+    accessibility: CFString,
     authentication: String?
   ) throws(TokamakPluginError) {
     var item = query(name)
     item[kSecValueData] = Data(value.utf8)
-    let accessibility = try accessibility(readable)
     if let authentication {
       item[kSecAttrAccessControl] = try accessControl(accessibility, authentication)
     } else {
@@ -82,7 +89,7 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     }
     var status = SecItemAdd(item as CFDictionary, nil)
     if status == errSecDuplicateItem {
-      try delete(name)
+      try deleteItems(query(name))
       status = SecItemAdd(item as CFDictionary, nil)
     }
     try check(status)
@@ -112,8 +119,26 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     return String(decoding: data, as: UTF8.self)
   }
 
-  private func delete(_ name: String) throws(TokamakPluginError) {
-    let status = SecItemDelete(query(name) as CFDictionary)
+  /// Reads attributes only, which needs no authentication.
+  private func keys() throws(TokamakPluginError) -> [String] {
+    var items = serviceQuery()
+    items[kSecMatchLimit] = kSecMatchLimitAll
+    items[kSecReturnAttributes] = true
+    items[kSecUseAuthenticationContext] = nonInteractiveContext()
+    var attributes: CFTypeRef?
+    let status = SecItemCopyMatching(items as CFDictionary, &attributes)
+    if status == errSecItemNotFound {
+      return []
+    }
+    try check(status)
+    let names = (attributes as? [[String: Any]] ?? []).compactMap {
+      $0[kSecAttrAccount as String] as? String
+    }
+    return names.sorted()
+  }
+
+  private func deleteItems(_ query: [CFString: Any]) throws(TokamakPluginError) {
+    let status = SecItemDelete(query as CFDictionary)
     if status != errSecItemNotFound {
       try check(status)
     }
@@ -121,11 +146,9 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
 
   /// Reads attributes only, which needs no authentication.
   private func exists(_ name: String) throws(TokamakPluginError) -> Bool {
-    let context = LAContext()
-    context.interactionNotAllowed = true
     var item = query(name)
     item[kSecReturnAttributes] = true
-    item[kSecUseAuthenticationContext] = context
+    item[kSecUseAuthenticationContext] = nonInteractiveContext()
     let status = SecItemCopyMatching(item as CFDictionary, nil)
     if status == errSecItemNotFound {
       return false
@@ -134,21 +157,36 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     return true
   }
 
-  /// The data protection keychain is the only keychain on iOS; macOS needs a
-  /// team-signed build to use it.
-  private func query(_ name: String) -> [CFString: Any] {
+  private func nonInteractiveContext() -> LAContext {
+    let context = LAContext()
+    context.interactionNotAllowed = true
+    return context
+  }
+
+  /// All of the plugin's items. The data protection keychain is the only
+  /// keychain on iOS; macOS needs a team-signed build to use it.
+  private func serviceQuery() -> [CFString: Any] {
     [
       kSecClass: kSecClassGenericPassword,
       kSecAttrService: service,
-      kSecAttrAccount: name,
       kSecUseDataProtectionKeychain: true,
     ]
   }
 
-  private func accessibility(_ readable: String) throws(TokamakPluginError) -> CFString {
-    switch readable {
-    case "whenUnlocked": kSecAttrAccessibleWhenUnlockedThisDeviceOnly
-    case "afterFirstUnlock": kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+  private func query(_ name: String) -> [CFString: Any] {
+    serviceQuery().merging([kSecAttrAccount: name]) { _, name in name }
+  }
+
+  /// `ThisDeviceOnly` items restore only to the device they were stored on.
+  private func accessibility(
+    _ readable: String,
+    thisDeviceOnly: Bool
+  ) throws(TokamakPluginError) -> CFString {
+    switch (readable, thisDeviceOnly) {
+    case ("whenUnlocked", true): kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+    case ("whenUnlocked", false): kSecAttrAccessibleWhenUnlocked
+    case ("afterFirstUnlock", true): kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+    case ("afterFirstUnlock", false): kSecAttrAccessibleAfterFirstUnlock
     default: throw unsupportedArgument("readable", readable)
     }
   }
@@ -206,6 +244,16 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     return value
   }
 
+  private func requiredBool(
+    _ arguments: [String: Any],
+    _ key: String
+  ) throws(TokamakPluginError) -> Bool {
+    guard let value = arguments[key] as? Bool else {
+      throw TokamakPluginError(name: "TypeError", message: "\(key) must be a boolean")
+    }
+    return value
+  }
+
   /// Missing and null arguments are nil; other non-string values are rejected.
   private func optionalString(
     _ arguments: [String: Any],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin-secure-storage",
-  "version": "0.1.0-beta.47",
+  "version": "0.1.0-beta.48",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -11,7 +11,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.47"
+    "@tokamakdev/plugin": "0.1.0-beta.48"
   },
   "files": [
     "android",

package/src/index.ts

@@ -10,6 +10,11 @@ export interface SetOptions {
   readonly readable: Readable;
   /** Reads need no authentication when omitted. */
   readonly authentication?: Authentication;
+  /**
+   * Whether backups can restore the value only to this device. Defaults to true;
+   * false lets a backup restore it to a new device where the platform supports that.
+   */
+  readonly thisDeviceOnly?: boolean;
 }
 
 export interface GetOptions {
@@ -28,6 +33,7 @@ class SecureStorage extends FrontendPlugin {
       value,
       readable: options.readable,
       authentication: options.authentication ?? null,
+      thisDeviceOnly: options.thisDeviceOnly ?? true,
     });
   }
 
@@ -38,6 +44,16 @@ class SecureStorage extends FrontendPlugin {
   delete(name: string): Promise<void> {
     return this.call("delete", { name });
   }
+
+  /** The names of all stored values, sorted. */
+  keys(): Promise<string[]> {
+    return this.call("keys");
+  }
+
+  /** Deletes every stored value. */
+  clear(): Promise<void> {
+    return this.call("clear");
+  }
 }
 
 export const secureStorage = new SecureStorage();