@tokamakdev/plugin-secure-storage 0.1.0-beta.100 → 0.1.0-beta.102

package/README.md

@@ -11,14 +11,26 @@ npm install @tokamakdev/plugin-secure-storage
 ```ts
 import { secureStorage } from "@tokamakdev/plugin-secure-storage";
 
-await secureStorage.set("identity/encryption", base64Value, {
+const options = {
   // Required: "whenUnlocked" or "afterFirstUnlock".
   readable: "whenUnlocked",
   // Reads need no authentication when omitted.
   authentication: "biometricsOrPasscode",
+} as const;
+
+// Rejects with DuplicateItemError when the name has a value.
+await secureStorage.create("identity/encryption", base64Value, options);
+
+// Rejects with ItemNotFoundError when the name has no value.
+await secureStorage.replace("identity/encryption", base64Value, {
+  ...options,
+  prompt: "Confirm it's you to replace your key",
 });
 
-// string | null
+// Replaces the value, or creates it when the name has none.
+await secureStorage.set("identity/encryption", base64Value, options);
+
+// get, delete and clear reject with ItemNotFoundError when there is no value.
 const value = await secureStorage.get("identity/encryption", {
   prompt: "Confirm it's you to link a new device",
 });
@@ -51,17 +63,20 @@ enrolment change as failed authentication, so `get` rejects with
 `prompt` is the reason shown in the system authentication prompt. Without it,
 the platform's default prompt is shown.
 
-`set` replaces an existing value in place or adds a new one, so a failed `set`
+`replace` and `set` replace an existing value in place, so a failed write
 leaves the previous value. On Apple platforms the system asks for the
 authentication an existing value was saved with before replacing it, as it does
-for a read: `set` then shows its `prompt` and needs the app on screen. Android
-replaces values without asking.
+for a read: `replace` and `set` then show their `prompt` and need the app on
+screen. Android replaces values without asking.
 
 ## Errors
 
 | Name | When |
 |---|---|
 | `NotSupportedError` | The platform, build or device cannot enforce the options |
+| `DuplicateItemError` | `create` was given a name that has a value |
+| `ItemNotFoundError` | `replace`, `get` or `delete` was given a name that has no value, or `clear` found no values |
+| `MissingEntitlementError` | `keychainGroup` is not one of the app's keychain access groups |
 | `InvalidStateError` | The requested authentication is not set up on the device |
 | `NotAllowedError` | The user cancelled or failed authentication, or the device is locked |
 | `NeedsUIError` | Reading a value saved with `authentication` while the app is off screen on iOS or Android, or replacing one on iOS, where the system cannot show its prompt |
@@ -69,7 +84,24 @@ replaces values without asking.
 | `TypeError` | An argument is missing or has an unsupported value |
 | `OperationError` | The platform reported another failure |
 
-`get` resolves `null` when the name has no stored value.
+## Keychain access groups
+
+On Apple platforms an app can store values in each keychain access group its
+`keychain-access-groups` entitlement lists. `keychainGroup` selects one, as
+`kSecAttrAccessGroup` does in a native keychain query:
+
+- `create`, and `set` when the name has no value, store the value in
+  `keychainGroup`, or in the first listed group when it is omitted.
+- `get`, `replace`, `delete` and `clear`, and `set` when the name has a value,
+  act on `keychainGroup`, or on every group when it is omitted.
+
+A name can have a value in more than one group. Without `keychainGroup`, `get`
+resolves one of them, `delete` and `clear` delete all of them, and `replace`
+and `set` reject with `NotAllowedError`, which is how the keychain reports an
+update that matches more than one value (`errSecAuthFailed`).
+
+Other platforms have no equivalent and reject `keychainGroup` with
+`NotSupportedError`.
 
 ## Platforms
 
@@ -103,6 +135,8 @@ groups, the app's own first, in the app's entitlements file
 
 New values go into the app's own group; existing values stay in the shared
 group even when replaced, so keep `TEAMID.*` while users may still hold them.
+Pass `keychainGroup: "TEAMID.*"` to act on those values only, for example to
+delete one after creating it again in the app's own group.
 
 Removing the device passcode or screen lock makes values stored with
 `authentication` permanently unreadable on Android.

package/android/SecureStoragePlugin.kt

@@ -63,16 +63,25 @@ class TokamakSecureStoragePlugin(
 
     override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
         when (method) {
+            "create" -> execute(reply) {
+                store(request(arguments), Write.CREATE)
+                reply(Result.success(null))
+            }
+            "replace" -> execute(reply) {
+                store(request(arguments), Write.REPLACE)
+                reply(Result.success(null))
+            }
             "set" -> execute(reply) {
-                set(requireObject(arguments))
+                store(request(arguments), Write.SET)
                 reply(Result.success(null))
             }
-            "get" -> execute(reply) { get(requireObject(arguments), reply) }
+            "get" -> execute(reply) { get(request(arguments), reply) }
             "delete" -> execute(reply) {
-                delete(requireObject(arguments).requireString("name"))
+                delete(request(arguments).requireString("name"))
                 reply(Result.success(null))
             }
             "clear" -> execute(reply) {
+                request(arguments) // Rejects keychainGroup.
                 clear()
                 reply(Result.success(null))
             }
@@ -80,6 +89,15 @@ class TokamakSecureStoragePlugin(
         }
     }
 
+    /** The call's arguments, rejecting the Apple-only `keychainGroup`. */
+    private fun request(arguments: Any?): JSONObject {
+        val request = requireObject(arguments)
+        if (request.optionalString("keychainGroup") != null) {
+            throw TokamakPluginError.notSupported("keychainGroup is an Apple keychain feature")
+        }
+        return request
+    }
+
     private fun execute(reply: TokamakPluginReply, operation: () -> Unit) =
         worker.execute {
             runCatching(operation).onFailure { reply(Result.failure(pluginError(it))) }
@@ -90,7 +108,7 @@ class TokamakSecureStoragePlugin(
             runCatching(operation).onFailure { reply(Result.failure(pluginError(it))) }
         }
 
-    private fun set(request: JSONObject) {
+    private fun store(request: JSONObject, mode: Write) {
         val name = request.requireString("name")
         val value = request.requireString("value")
         val unlockedDeviceRequired =
@@ -111,7 +129,14 @@ class TokamakSecureStoragePlugin(
                 .setUnlockedDeviceRequired(unlockedDeviceRequired)
         request.optionalString("authentication")?.let { requireAuthentication(spec, it) }
         val file = file(name)
-        val previousAlias = read(file)?.let { alias(it.keyId) }
+        val previous = read(file)
+        if (previous != null && mode == Write.CREATE) {
+            throw TokamakPluginError("DuplicateItemError", "A value is already stored under this name")
+        }
+        if (previous == null && mode == Write.REPLACE) {
+            throw itemNotFound()
+        }
+        val previousAlias = previous?.let { alias(it.keyId) }
         val publicKey = generatePublicKey(spec)
         try {
             write(file, seal(keyId, value, publicKey).encode())
@@ -163,11 +188,7 @@ class TokamakSecureStoragePlugin(
     private fun get(request: JSONObject, reply: TokamakPluginReply) {
         val name = request.requireString("name")
         val prompt = request.optionalString("prompt")
-        val stored = read(file(name))
-        if (stored == null) {
-            reply(Result.success(null))
-            return
-        }
+        val stored = read(file(name)) ?: throw itemNotFound()
         val privateKey =
             keyStore.getKey(alias(stored.keyId), null) as? PrivateKey
                 ?: throw notReadable()
@@ -212,16 +233,22 @@ class TokamakSecureStoragePlugin(
 
     private fun delete(name: String) {
         val file = file(name)
-        val stored = read(file) ?: return
+        val stored = read(file) ?: throw itemNotFound()
         AtomicFile(file).delete()
         keyStore.deleteEntry(alias(stored.keyId))
     }
 
+    /** Deletes every value, and any key an interrupted write left behind. */
     private fun clear() {
+        // An interrupted first write leaves only a `.new` file, which [read] ignores.
+        val hadValues = directory.list().orEmpty().any { !it.endsWith(".new") }
         directory.deleteRecursively()
         keyStore.aliases().toList()
             .filter { it.startsWith(ALIAS_PREFIX) }
             .forEach(keyStore::deleteEntry)
+        if (!hadValues) {
+            throw TokamakPluginError("ItemNotFoundError", "No values are stored")
+        }
     }
 
     private fun read(file: File): StoredValue? =
@@ -251,6 +278,9 @@ class TokamakSecureStoragePlugin(
 
     private fun ByteArray.toHex() = joinToString("") { "%02x".format(it) }
 
+    /** Whether a write requires the name to have no value, a value, or either. */
+    private enum class Write { CREATE, REPLACE, SET }
+
     private enum class Authentication(
         val wireName: String,
         val keyTypes: Int,
@@ -296,6 +326,8 @@ class TokamakSecureStoragePlugin(
         fun notReadable() =
             TokamakPluginError("NotReadableError", "The stored value can no longer be decrypted")
 
+        fun itemNotFound() = TokamakPluginError("ItemNotFoundError", "No value is stored under this name")
+
         fun pluginError(error: Throwable): Throwable =
             when (error) {
                 is KeyPermanentlyInvalidatedException,

package/apple/SecureStoragePlugin.swift

@@ -18,10 +18,6 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     self.host = host
   }
 
-  private static let teamSigningRequired = TokamakPluginError.notSupported(
-    "Secure storage requires a team-signed build"
-  )
-
   #if os(macOS)
     /// macOS grants the data protection keychain only to apps whose provisioning
     /// profile provides an application identifier.
@@ -68,86 +64,107 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
   ) throws(TokamakPluginError) -> Any? {
     #if os(macOS)
       // Unentitled reads report errSecItemNotFound rather than a missing entitlement.
-      guard Self.hasApplicationIdentifier else { throw Self.teamSigningRequired }
+      guard Self.hasApplicationIdentifier else {
+        throw .notSupported("Secure storage requires a team-signed build")
+      }
     #endif
+    let group = try optionalString(arguments, "keychainGroup")
     switch method {
+    case "create":
+      try check(add(requiredString(arguments, "name"), group: group, stored(arguments)))
+      return nil
+    case "replace":
+      try check(
+        update(
+          requiredString(arguments, "name"),
+          group: group,
+          stored(arguments),
+          prompt: optionalString(arguments, "prompt"),
+          prompting: prompting
+        ))
+      return nil
     case "set":
-      try set(
-        requiredString(arguments, "name"),
-        value: requiredString(arguments, "value"),
-        readable: requiredString(arguments, "readable"),
-        thisDeviceOnly: requiredBool(arguments, "thisDeviceOnly"),
-        authentication: optionalString(arguments, "authentication"),
+      let name = try requiredString(arguments, "name")
+      let stored = try stored(arguments)
+      let status = try update(
+        name,
+        group: group,
+        stored,
         prompt: optionalString(arguments, "prompt"),
         prompting: prompting
       )
+      try check(status == errSecItemNotFound ? add(name, group: group, stored) : status)
       return nil
     case "get":
       return try get(
         requiredString(arguments, "name"),
+        group: group,
         prompt: optionalString(arguments, "prompt"),
         prompting: prompting
       )
     case "delete":
-      try deleteItems(query(requiredString(arguments, "name")))
+      let name = try requiredString(arguments, "name")
+      try check(SecItemDelete(query(name, group: group) as CFDictionary))
       return nil
     case "clear":
-      try deleteItems(serviceQuery())
+      try check(SecItemDelete(serviceQuery(group: group) as CFDictionary))
       return nil
     default:
       throw .notSupported("\(id).\(method) is not supported")
     }
   }
 
-  /// Updates an existing value in place or adds a new one, so a failure
-  /// leaves the previous value. Checks without UI first, so only replacing a
-  /// value saved with authentication needs the system prompt.
-  private func set(
+  /// The value and its protection, as keychain attributes. Access control even
+  /// without authentication, so an update removes any the existing value had.
+  private func stored(_ arguments: [String: Any]) throws(TokamakPluginError) -> [CFString: Any] {
+    let accessibility = try accessibility(
+      requiredString(arguments, "readable"),
+      thisDeviceOnly: requiredBool(arguments, "thisDeviceOnly")
+    )
+    return [
+      kSecValueData: Data(try requiredString(arguments, "value").utf8),
+      kSecAttrAccessControl: try accessControl(
+        accessibility, optionalString(arguments, "authentication")),
+    ]
+  }
+
+  /// Adds `name`'s value in one keychain call: errSecDuplicateItem when it has one.
+  private func add(_ name: String, group: String?, _ stored: [CFString: Any]) -> OSStatus {
+    SecItemAdd(query(name, group: group).merging(stored) { _, new in new } as CFDictionary, nil)
+  }
+
+  /// Updates `name`'s value in place, so a failure leaves the previous value:
+  /// errSecItemNotFound when it has none. Tries without UI
+  /// first, so only a value saved with authentication needs the system prompt.
+  private func update(
     _ name: String,
-    value: String,
-    readable: String,
-    thisDeviceOnly: Bool,
-    authentication: String?,
+    group: String?,
+    _ stored: [CFString: Any],
     prompt: String?,
     prompting: Result<Void, TokamakPluginError>?
-  ) throws(TokamakPluginError) {
-    let accessibility = try accessibility(readable, thisDeviceOnly: thisDeviceOnly)
-    // Access control even without authentication, so an update removes any the existing value had.
-    let stored: [CFString: Any] = [
-      kSecValueData: Data(value.utf8),
-      kSecAttrAccessControl: try accessControl(accessibility, authentication),
-    ]
-    var existing = query(name)
-    existing[kSecUseAuthenticationContext] = Self.contextWithoutUI()
-    let status = SecItemCopyMatching(existing as CFDictionary, nil)
-    if status == errSecItemNotFound {
-      try check(SecItemAdd(query(name).merging(stored) { _, new in new } as CFDictionary, nil))
-      return
-    }
-    if status == errSecInteractionNotAllowed, let prompting {
-      try prompting.get()
-      existing[kSecUseAuthenticationContext] = Self.context(prompt: prompt)
-    } else {
-      try check(status)
-    }
-    try check(SecItemUpdate(existing as CFDictionary, stored as CFDictionary))
+  ) throws(TokamakPluginError) -> OSStatus {
+    var item = query(name, group: group)
+    item[kSecUseAuthenticationContext] = Self.contextWithoutUI()
+    let status = SecItemUpdate(item as CFDictionary, stored as CFDictionary)
+    guard status == errSecInteractionNotAllowed, let prompting else { return status }
+    try prompting.get()
+    item[kSecUseAuthenticationContext] = Self.context(prompt: prompt)
+    return SecItemUpdate(item as CFDictionary, stored as CFDictionary)
   }
 
   /// Reads without UI first, so only a value saved with authentication needs
   /// the app able to show the system prompt.
   private func get(
     _ name: String,
+    group: String?,
     prompt: String?,
     prompting: Result<Void, TokamakPluginError>?
-  ) throws(TokamakPluginError) -> String? {
-    var item = query(name)
+  ) throws(TokamakPluginError) -> String {
+    var item = query(name, group: group)
     item[kSecReturnData] = true
     item[kSecUseAuthenticationContext] = Self.contextWithoutUI()
     var data: CFTypeRef?
     var status = SecItemCopyMatching(item as CFDictionary, &data)
-    if status == errSecItemNotFound {
-      return nil
-    }
     if status == errSecInteractionNotAllowed, let prompting {
       try prompting.get()
       item[kSecUseAuthenticationContext] = Self.context(prompt: prompt)
@@ -167,14 +184,7 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     return String(decoding: data, as: UTF8.self)
   }
 
-  private func deleteItems(_ query: [CFString: Any]) throws(TokamakPluginError) {
-    let status = SecItemDelete(query as CFDictionary)
-    if status != errSecItemNotFound {
-      try check(status)
-    }
-  }
-
-  /// A context in which reads that need authentication fail with
+  /// A context in which keychain calls that need authentication fail with
   /// `errSecInteractionNotAllowed` rather than show the system prompt.
   private static func contextWithoutUI() -> LAContext {
     let context = LAContext()
@@ -190,18 +200,22 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     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] {
-    [
+  /// The plugin's items in keychain access group `group`, or in every group
+  /// of the app when nil, where an add uses the app's first group. The data
+  /// protection keychain is the only keychain on iOS; macOS needs a
+  /// team-signed build to use it.
+  private func serviceQuery(group: String?) -> [CFString: Any] {
+    var query: [CFString: Any] = [
       kSecClass: kSecClassGenericPassword,
       kSecAttrService: service,
       kSecUseDataProtectionKeychain: true,
     ]
+    query[kSecAttrAccessGroup] = group
+    return query
   }
 
-  private func query(_ name: String) -> [CFString: Any] {
-    serviceQuery().merging([kSecAttrAccount: name]) { _, name in name }
+  private func query(_ name: String, group: String?) -> [CFString: Any] {
+    serviceQuery(group: group).merging([kSecAttrAccount: name]) { _, name in name }
   }
 
   /// `ThisDeviceOnly` items restore only to the device they were stored on.
@@ -255,8 +269,12 @@ final class TokamakSecureStoragePlugin: TokamakPlugin {
     guard status != errSecSuccess else { return }
     let message = SecCopyErrorMessageString(status, nil) as String? ?? "Keychain error \(status)"
     switch status {
+    case errSecDuplicateItem:
+      throw TokamakPluginError(name: "DuplicateItemError", message: message)
+    case errSecItemNotFound:
+      throw TokamakPluginError(name: "ItemNotFoundError", message: message)
     case errSecMissingEntitlement:
-      throw Self.teamSigningRequired
+      throw TokamakPluginError(name: "MissingEntitlementError", message: message)
     case errSecUserCanceled, errSecAuthFailed, errSecInteractionNotAllowed:
       throw TokamakPluginError(name: "NotAllowedError", message: message)
     default:

package/package.json

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

package/src/index.ts

@@ -6,7 +6,7 @@ export type Readable = "whenUnlocked" | "afterFirstUnlock";
 /** The authentication a read requires. */
 export type Authentication = "biometricsOrPasscode" | "biometrics" | "currentBiometrics";
 
-export interface SetOptions {
+export interface CreateOptions {
   readonly readable: Readable;
   /** Reads need no authentication when omitted. */
   readonly authentication?: Authentication;
@@ -15,6 +15,15 @@ export interface SetOptions {
    * false lets a backup restore it to a new device where the platform supports that.
    */
   readonly thisDeviceOnly?: boolean;
+  /**
+   * Apple platforms: the keychain access group, one of the app's `keychain-access-groups`.
+   * When omitted, new values go into the first of them and updates match every group.
+   */
+  readonly keychainGroup?: string;
+}
+
+/** Options for `set` and `replace`. */
+export interface SetOptions extends CreateOptions {
   /**
    * The reason shown in the system authentication prompt. Apple platforms ask for the
    * authentication an existing value was saved with before replacing it.
@@ -25,6 +34,14 @@ export interface SetOptions {
 export interface GetOptions {
   /** The reason shown in the system authentication prompt. */
   readonly prompt?: string;
+  /** Apple platforms: the keychain access group to read from. Defaults to all of the app's. */
+  readonly keychainGroup?: string;
+}
+
+/** Options for `delete` and `clear`. */
+export interface DeleteOptions {
+  /** Apple platforms: the keychain access group to delete from. Defaults to all of the app's. */
+  readonly keychainGroup?: string;
 }
 
 class SecureStorage extends Plugin {
@@ -32,29 +49,46 @@ class SecureStorage extends Plugin {
     super("secure-storage");
   }
 
+  /** Stores a new value; rejects with `DuplicateItemError` when `name` has one. */
+  create(name: string, value: string, options: CreateOptions): Promise<void> {
+    return this.call("create", stored(name, value, options));
+  }
+
+  /** Replaces the value in place; rejects with `ItemNotFoundError` when `name` has none. */
+  replace(name: string, value: string, options: SetOptions): Promise<void> {
+    return this.call("replace", { ...stored(name, value, options), prompt: options.prompt ?? null });
+  }
+
+  /** Replaces the value in place, or stores a new one when `name` has none. */
   set(name: string, value: string, options: SetOptions): Promise<void> {
-    return this.call("set", {
-      name,
-      value,
-      readable: options.readable,
-      authentication: options.authentication ?? null,
-      thisDeviceOnly: options.thisDeviceOnly ?? true,
-      prompt: options.prompt ?? null,
-    });
+    return this.call("set", { ...stored(name, value, options), prompt: options.prompt ?? null });
   }
 
-  get(name: string, options: GetOptions = {}): Promise<string | null> {
-    return this.call("get", { name, prompt: options.prompt ?? null });
+  /** Reads the value; rejects with `ItemNotFoundError` when `name` has none. */
+  get(name: string, options: GetOptions = {}): Promise<string> {
+    return this.call("get", { name, prompt: options.prompt ?? null, keychainGroup: options.keychainGroup ?? null });
   }
 
-  delete(name: string): Promise<void> {
-    return this.call("delete", { name });
+  /** Deletes the value; rejects with `ItemNotFoundError` when `name` has none. */
+  delete(name: string, options: DeleteOptions = {}): Promise<void> {
+    return this.call("delete", { name, keychainGroup: options.keychainGroup ?? null });
   }
 
-  /** Deletes every stored value. */
-  clear(): Promise<void> {
-    return this.call("clear");
+  /** Deletes every stored value; rejects with `ItemNotFoundError` when there are none. */
+  clear(options: DeleteOptions = {}): Promise<void> {
+    return this.call("clear", { keychainGroup: options.keychainGroup ?? null });
   }
 }
 
+function stored(name: string, value: string, options: CreateOptions) {
+  return {
+    name,
+    value,
+    readable: options.readable,
+    authentication: options.authentication ?? null,
+    thisDeviceOnly: options.thisDeviceOnly ?? true,
+    keychainGroup: options.keychainGroup ?? null,
+  };
+}
+
 export const secureStorage = new SecureStorage();