@tokamakdev/plugin-secure-storage 0.1.0-beta.45

package/README.md

@@ -0,0 +1,70 @@
+# @tokamakdev/plugin-secure-storage
+
+Secret storage that stays on the device, for Tokamak applications.
+
+Add it to your project's dependencies:
+
+```sh
+npm install @tokamakdev/plugin-secure-storage
+```
+
+```ts
+import { secureStorage } from "@tokamakdev/plugin-secure-storage";
+
+await secureStorage.set("identity/encryption", base64Value, {
+  // Required: "whenUnlocked" or "afterFirstUnlock".
+  readable: "whenUnlocked",
+  // Reads need no authentication when omitted.
+  authentication: "biometricsOrPasscode",
+});
+
+// string | null
+const value = await secureStorage.get("identity/encryption", {
+  prompt: "Confirm it's you to link a new device",
+});
+
+await secureStorage.delete("identity/encryption");
+```
+
+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.
+
+`authentication` binds a value to the device's secure hardware, so it cannot be
+decrypted until the device owner authenticates:
+
+| `authentication` | Reads accept | After a biometric enrolment change |
+|---|---|---|
+| `biometricsOrPasscode` | Face ID, Touch ID or fingerprint; passcode, PIN, pattern or password | Readable |
+| `biometrics` | Face ID, Touch ID or fingerprint | Readable |
+| `currentBiometrics` | Face ID, Touch ID or fingerprint enrolled when the value was stored | Permanently unreadable |
+
+`prompt` is the reason shown in the system authentication prompt. Without it,
+the platform's default prompt is shown.
+
+## Errors
+
+| Name | When |
+|---|---|
+| `NotSupportedError` | The platform, build or device cannot enforce the options |
+| `InvalidStateError` | The requested authentication is not set up on the device |
+| `NotAllowedError` | The user cancelled or failed authentication, or the device is locked |
+| `NotReadableError` | A stored value can no longer be decrypted |
+| `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.
+
+## 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.
+- **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.
+- **Web and Windows:** no implementation; calls throw `NotSupportedError`.
+
+Removing the device passcode or screen lock makes values stored with
+`authentication` permanently unreadable on Android.

package/android/SecureStoragePlugin.kt

@@ -0,0 +1,369 @@
+package com.tokamak.plugins.securestorage
+
+import android.app.Activity
+import android.hardware.biometrics.BiometricManager
+import android.hardware.biometrics.BiometricManager.Authenticators
+import android.hardware.biometrics.BiometricPrompt
+import android.os.CancellationSignal
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyInfo
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.security.keystore.StrongBoxUnavailableException
+import android.security.keystore.UserNotAuthenticatedException
+import android.util.AtomicFile
+import com.tokamak.runtime.TokamakPlugin
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakPluginReply
+import java.io.File
+import java.io.FileNotFoundException
+import java.security.KeyFactory
+import java.security.KeyPairGenerator
+import java.security.KeyStore
+import java.security.MessageDigest
+import java.security.PrivateKey
+import java.security.PublicKey
+import java.security.SecureRandom
+import java.security.spec.MGF1ParameterSpec
+import java.security.spec.X509EncodedKeySpec
+import java.util.concurrent.Executors
+import javax.crypto.BadPaddingException
+import javax.crypto.Cipher
+import javax.crypto.IllegalBlockSizeException
+import javax.crypto.KeyGenerator
+import javax.crypto.spec.GCMParameterSpec
+import javax.crypto.spec.OAEPParameterSpec
+import javax.crypto.spec.PSource
+import javax.crypto.spec.SecretKeySpec
+import org.json.JSONObject
+
+/**
+ * Stores each value sealed with a random AES-GCM key, wrapped by an RSA key pair in the
+ * Android Keystore. Writing uses only the public key, so it never prompts; the private key
+ * carries the value's unlock and authentication requirements. Every write uses a new key
+ * pair, identified in the value's file, so a failed write leaves the previous value readable.
+ */
+internal class TokamakSecureStoragePlugin(
+    private val activity: Activity,
+) : TokamakPlugin {
+    override val id = "secure-storage"
+
+    private val worker = Executors.newSingleThreadExecutor()
+    private val directory = File(activity.noBackupFilesDir, "tokamak-secure-storage")
+    private val keyStore = KeyStore.getInstance(KEYSTORE).apply { load(null) }
+    private val biometrics = activity.getSystemService(BiometricManager::class.java)
+    private val random = SecureRandom()
+
+    override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
+        when (method) {
+            "set" -> execute(reply) {
+                set(request(arguments))
+                reply(Result.success(null))
+            }
+            "get" -> execute(reply) { get(request(arguments), reply) }
+            "delete" -> execute(reply) {
+                delete(request(arguments).requireString("name"))
+                reply(Result.success(null))
+            }
+            else -> super.call(method, arguments, reply)
+        }
+    }
+
+    private fun execute(reply: TokamakPluginReply, operation: () -> Unit) =
+        worker.execute {
+            runCatching(operation).onFailure { reply(Result.failure(pluginError(it))) }
+        }
+
+    private fun onUiThread(reply: TokamakPluginReply, operation: () -> Unit) =
+        activity.runOnUiThread {
+            runCatching(operation).onFailure { reply(Result.failure(pluginError(it))) }
+        }
+
+    private fun set(request: JSONObject) {
+        val name = request.requireString("name")
+        val value = request.requireString("value")
+        val unlockedDeviceRequired =
+            when (request.requireString("readable")) {
+                "whenUnlocked" -> true
+                "afterFirstUnlock" -> false
+                else -> throw typeError("readable must be \"whenUnlocked\" or \"afterFirstUnlock\"")
+            }
+        val keyId = ByteArray(KEY_ID_SIZE).also(random::nextBytes)
+        val spec =
+            KeyGenParameterSpec.Builder(alias(keyId), KeyProperties.PURPOSE_DECRYPT)
+                .setKeySize(KEY_SIZE)
+                .setDigests(KeyProperties.DIGEST_SHA256)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_OAEP)
+                .setUnlockedDeviceRequired(unlockedDeviceRequired)
+        request.optionalString("authentication")?.let { requireAuthentication(spec, it) }
+        val file = file(name)
+        val previousAlias = read(file)?.let(::storedAlias)
+        val publicKey = generatePublicKey(spec)
+        try {
+            write(file, keyId + seal(value, publicKey))
+        } catch (error: Throwable) {
+            keyStore.deleteEntry(alias(keyId))
+            throw error
+        }
+        previousAlias?.let(keyStore::deleteEntry)
+    }
+
+    private fun requireAuthentication(spec: KeyGenParameterSpec.Builder, wireName: String) {
+        val authentication =
+            Authentication.entries.firstOrNull { it.wireName == wireName } ?: throw unknownAuthentication()
+        requireAvailable(authentication.authenticators)
+        spec.setUserAuthenticationRequired(true)
+            .setUserAuthenticationParameters(0, authentication.keyTypes)
+            .setInvalidatedByBiometricEnrollment(authentication.invalidatedByEnrollment)
+    }
+
+    private fun requireAvailable(authenticators: Int) {
+        when (biometrics.canAuthenticate(authenticators)) {
+            BiometricManager.BIOMETRIC_SUCCESS -> Unit
+            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE ->
+                throw TokamakPluginError.notSupported("This device cannot perform the requested authentication")
+            else -> throw notSetUp()
+        }
+    }
+
+    private fun generatePublicKey(spec: KeyGenParameterSpec.Builder): PublicKey {
+        val generator = KeyPairGenerator.getInstance(KeyProperties.KEY_ALGORITHM_RSA, KEYSTORE)
+        val keyPair =
+            try {
+                generator.initialize(spec.setIsStrongBoxBacked(true).build())
+                generator.generateKeyPair()
+            } catch (_: StrongBoxUnavailableException) {
+                generator.initialize(spec.setIsStrongBoxBacked(false).build())
+                generator.generateKeyPair()
+            }
+        // A software copy of the public key encrypts without Keystore restrictions.
+        return KeyFactory.getInstance(KeyProperties.KEY_ALGORITHM_RSA)
+            .generatePublic(X509EncodedKeySpec(keyPair.public.encoded))
+    }
+
+    private fun seal(value: String, publicKey: PublicKey): ByteArray {
+        val dataKey = KeyGenerator.getInstance("AES").apply { init(DATA_KEY_SIZE) }.generateKey()
+        val iv = ByteArray(IV_SIZE).also(random::nextBytes)
+        val sealed =
+            Cipher.getInstance(SEAL)
+                .apply { init(Cipher.ENCRYPT_MODE, dataKey, GCMParameterSpec(TAG_SIZE, iv)) }
+                .doFinal(value.toByteArray())
+        val wrapped =
+            Cipher.getInstance(WRAP)
+                .apply { init(Cipher.ENCRYPT_MODE, publicKey, OAEP) }
+                .doFinal(dataKey.encoded)
+        return wrapped + iv + sealed
+    }
+
+    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 privateKey =
+            keyStore.getKey(storedAlias(stored), null) as? PrivateKey
+                ?: throw notReadable()
+        val unwrap = Cipher.getInstance(WRAP).apply { init(Cipher.DECRYPT_MODE, privateKey, OAEP) }
+        val info =
+            KeyFactory.getInstance(privateKey.algorithm, KEYSTORE)
+                .getKeySpec(privateKey, KeyInfo::class.java)
+        if (!info.isUserAuthenticationRequired) {
+            reply(Result.success(open(stored, unwrap)))
+            return
+        }
+        val credential = (info.userAuthenticationType and KeyProperties.AUTH_DEVICE_CREDENTIAL) != 0
+        val authenticators =
+            if (credential) Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL
+            else Authenticators.BIOMETRIC_STRONG
+        authenticate(authenticators, prompt, unwrap, stored, reply)
+    }
+
+    /** Authorises [unwrap] with the device owner's authentication, then replies with the opened value. */
+    private fun authenticate(
+        authenticators: Int,
+        prompt: String?,
+        unwrap: Cipher,
+        stored: ByteArray,
+        reply: TokamakPluginReply,
+    ) {
+        val callback = PromptCallback(reply) { execute(reply) { reply(Result.success(open(stored, unwrap))) } }
+        val title = prompt?.takeIf { it.isNotEmpty() } ?: activity.applicationInfo.loadLabel(activity.packageManager)
+        val dialog =
+            BiometricPrompt.Builder(activity)
+                .setTitle(title)
+                .setAllowedAuthenticators(authenticators)
+        if ((authenticators and Authenticators.DEVICE_CREDENTIAL) == 0) {
+            dialog.setNegativeButton(
+                activity.getString(android.R.string.cancel),
+                activity.mainExecutor,
+            ) { _, _ -> reply(Result.failure(cancelled())) }
+        }
+        onUiThread(reply) {
+            dialog.build().authenticate(
+                BiometricPrompt.CryptoObject(unwrap),
+                CancellationSignal(),
+                activity.mainExecutor,
+                callback,
+            )
+        }
+    }
+
+    /** 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)
+        return Cipher.getInstance(SEAL)
+            .apply { init(Cipher.DECRYPT_MODE, dataKey, GCMParameterSpec(TAG_SIZE, iv)) }
+            .doFinal(stored, SEALED_START, stored.size - SEALED_START)
+            .decodeToString()
+    }
+
+    private fun delete(name: String) {
+        val file = file(name)
+        val alias = read(file)?.let(::storedAlias) ?: return
+        AtomicFile(file).delete()
+        keyStore.deleteEntry(alias)
+    }
+
+    private fun read(file: File): ByteArray? =
+        try {
+            AtomicFile(file).readFully()
+        } catch (_: FileNotFoundException) {
+            null
+        }
+
+    private fun write(file: File, bytes: ByteArray) {
+        directory.mkdirs()
+        val atomic = AtomicFile(file)
+        val output = atomic.startWrite()
+        try {
+            output.write(bytes)
+            atomic.finishWrite(output)
+        } catch (error: Throwable) {
+            atomic.failWrite(output)
+            throw error
+        }
+    }
+
+    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 ByteArray.toHex() = joinToString("") { "%02x".format(it) }
+
+    private fun request(arguments: Any?): JSONObject =
+        arguments as? JSONObject ?: throw typeError("$id arguments must be an object")
+
+    private fun JSONObject.requireString(name: String): String =
+        optionalString(name) ?: throw typeError("$name must be a string")
+
+    private fun JSONObject.optionalString(name: String): String? =
+        when (val value = opt(name)) {
+            null, JSONObject.NULL -> null
+            is String -> value
+            else -> throw typeError("$name must be a string")
+        }
+
+    private enum class Authentication(
+        val wireName: String,
+        val keyTypes: Int,
+        val authenticators: Int,
+        val invalidatedByEnrollment: Boolean,
+    ) {
+        BIOMETRICS_OR_PASSCODE(
+            "biometricsOrPasscode",
+            KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL,
+            Authenticators.BIOMETRIC_STRONG or Authenticators.DEVICE_CREDENTIAL,
+            invalidatedByEnrollment = false,
+        ),
+        BIOMETRICS(
+            "biometrics",
+            KeyProperties.AUTH_BIOMETRIC_STRONG,
+            Authenticators.BIOMETRIC_STRONG,
+            invalidatedByEnrollment = false,
+        ),
+        CURRENT_BIOMETRICS(
+            "currentBiometrics",
+            KeyProperties.AUTH_BIOMETRIC_STRONG,
+            Authenticators.BIOMETRIC_STRONG,
+            invalidatedByEnrollment = true,
+        ),
+    }
+
+    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 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"
+
+        // Keystore RSA keys default to SHA-1 for the OAEP MGF1 digest.
+        val OAEP = OAEPParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA1, PSource.PSpecified.DEFAULT)
+
+        fun typeError(message: String) = TokamakPluginError("TypeError", message)
+
+        fun unknownAuthentication() =
+            typeError("authentication must be \"biometricsOrPasscode\", \"biometrics\" or \"currentBiometrics\"")
+
+        fun locked() = TokamakPluginError("NotAllowedError", "The device must be unlocked to read this value")
+
+        fun notReadable() =
+            TokamakPluginError("NotReadableError", "The stored value can no longer be decrypted")
+
+        fun cancelled() = TokamakPluginError("NotAllowedError", "Authentication was cancelled")
+
+        fun notSetUp() =
+            TokamakPluginError("InvalidStateError", "The requested authentication is not set up on this device")
+
+        fun pluginError(error: Throwable): TokamakPluginError =
+            when (error) {
+                is TokamakPluginError -> error
+                is KeyPermanentlyInvalidatedException,
+                is BadPaddingException,
+                is IllegalBlockSizeException,
+                -> notReadable()
+                is UserNotAuthenticatedException -> locked()
+                else -> TokamakPluginError("OperationError", error.message ?: error.javaClass.name)
+            }
+    }
+}
+
+private class PromptCallback(
+    private val reply: TokamakPluginReply,
+    private val succeeded: () -> Unit,
+) : BiometricPrompt.AuthenticationCallback() {
+    override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) = succeeded()
+
+    override fun onAuthenticationError(code: Int, message: CharSequence) =
+        reply(Result.failure(authenticationError(code, message)))
+}
+
+private fun authenticationError(code: Int, message: CharSequence) =
+    TokamakPluginError(
+        when (code) {
+            BiometricPrompt.BIOMETRIC_ERROR_CANCELED,
+            BiometricPrompt.BIOMETRIC_ERROR_USER_CANCELED,
+            BiometricPrompt.BIOMETRIC_ERROR_TIMEOUT,
+            BiometricPrompt.BIOMETRIC_ERROR_LOCKOUT,
+            BiometricPrompt.BIOMETRIC_ERROR_LOCKOUT_PERMANENT,
+            -> "NotAllowedError"
+            BiometricPrompt.BIOMETRIC_ERROR_NO_BIOMETRICS,
+            BiometricPrompt.BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL,
+            -> "InvalidStateError"
+            BiometricPrompt.BIOMETRIC_ERROR_HW_NOT_PRESENT -> "NotSupportedError"
+            else -> "OperationError"
+        },
+        message.toString(),
+    )

package/apple/SecureStoragePlugin.swift

@@ -0,0 +1,221 @@
+import Foundation
+import LocalAuthentication
+import Security
+
+final class TokamakSecureStoragePlugin: TokamakPlugin {
+  let id = "secure-storage"
+
+  private let service = "tokamak.secure-storage"
+  /// Keychain calls block while the system authentication prompt is shown.
+  private let queue = DispatchQueue(label: "tokamak.secure-storage")
+
+  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.
+    private static let hasApplicationIdentifier: Bool = {
+      guard let task = SecTaskCreateFromSelf(nil) else { return false }
+      let entitlement = "com.apple.application-identifier" as CFString
+      return SecTaskCopyValueForEntitlement(task, entitlement, nil) != nil
+    }()
+  #endif
+
+  func call(
+    method: String,
+    arguments: Any,
+    reply: @escaping TokamakPluginReply
+  ) {
+    let arguments = arguments as? [String: Any] ?? [:]
+    queue.async {
+      reply(Result { () throws(TokamakPluginError) in try self.perform(method, arguments) })
+    }
+  }
+
+  private func perform(
+    _ method: String,
+    _ arguments: [String: Any]
+  ) throws(TokamakPluginError) -> Any? {
+    #if os(macOS)
+      // Unentitled reads report errSecItemNotFound rather than a missing entitlement.
+      guard Self.hasApplicationIdentifier else { throw Self.teamSigningRequired }
+    #endif
+    switch method {
+    case "set":
+      try set(
+        requiredString(arguments, "name"),
+        value: requiredString(arguments, "value"),
+        readable: requiredString(arguments, "readable"),
+        authentication: optionalString(arguments, "authentication")
+      )
+      return nil
+    case "get":
+      return try get(
+        requiredString(arguments, "name"),
+        prompt: optionalString(arguments, "prompt")
+      )
+    case "delete":
+      try delete(requiredString(arguments, "name"))
+      return nil
+    default:
+      throw .notSupported("\(id).\(method) is not supported")
+    }
+  }
+
+  /// Replaces an existing value only once the new item can be added, so a
+  /// failed write keeps the old value.
+  private func set(
+    _ name: String,
+    value: String,
+    readable: String,
+    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 {
+      item[kSecAttrAccessible] = accessibility
+    }
+    var status = SecItemAdd(item as CFDictionary, nil)
+    if status == errSecDuplicateItem {
+      try delete(name)
+      status = SecItemAdd(item as CFDictionary, nil)
+    }
+    try check(status)
+  }
+
+  private func get(_ name: String, prompt: String?) throws(TokamakPluginError) -> String? {
+    var item = query(name)
+    item[kSecReturnData] = true
+    if let prompt, !prompt.isEmpty {
+      let context = LAContext()
+      context.localizedReason = prompt
+      item[kSecUseAuthenticationContext] = context
+    }
+    var data: CFTypeRef?
+    let status = SecItemCopyMatching(item as CFDictionary, &data)
+    if status == errSecItemNotFound {
+      guard try exists(name) else { return nil }
+      throw TokamakPluginError(
+        name: "NotReadableError",
+        message: "The stored value can no longer be read"
+      )
+    }
+    try check(status)
+    guard let data = data as? Data else {
+      throw TokamakPluginError(name: "NotReadableError", message: "The stored value is not data")
+    }
+    return String(decoding: data, as: UTF8.self)
+  }
+
+  private func delete(_ name: String) throws(TokamakPluginError) {
+    let status = SecItemDelete(query(name) as CFDictionary)
+    if status != errSecItemNotFound {
+      try check(status)
+    }
+  }
+
+  /// 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
+    let status = SecItemCopyMatching(item as CFDictionary, nil)
+    if status == errSecItemNotFound {
+      return false
+    }
+    try check(status)
+    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] {
+    [
+      kSecClass: kSecClassGenericPassword,
+      kSecAttrService: service,
+      kSecAttrAccount: name,
+      kSecUseDataProtectionKeychain: true,
+    ]
+  }
+
+  private func accessibility(_ readable: String) throws(TokamakPluginError) -> CFString {
+    switch readable {
+    case "whenUnlocked": kSecAttrAccessibleWhenUnlockedThisDeviceOnly
+    case "afterFirstUnlock": kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+    default: throw unsupportedArgument("readable", readable)
+    }
+  }
+
+  private func accessControl(
+    _ accessibility: CFString,
+    _ authentication: String
+  ) throws(TokamakPluginError) -> SecAccessControl {
+    let (flags, policy): (SecAccessControlCreateFlags, LAPolicy) =
+      switch authentication {
+      case "biometricsOrPasscode": (.userPresence, .deviceOwnerAuthentication)
+      case "biometrics": (.biometryAny, .deviceOwnerAuthenticationWithBiometrics)
+      case "currentBiometrics": (.biometryCurrentSet, .deviceOwnerAuthenticationWithBiometrics)
+      default: throw unsupportedArgument("authentication", authentication)
+      }
+    try requireSetUp(policy)
+    guard let control = SecAccessControlCreateWithFlags(nil, accessibility, flags, nil) else {
+      throw TokamakPluginError(name: "OperationError", message: "Access control is unavailable")
+    }
+    return control
+  }
+
+  private func requireSetUp(_ policy: LAPolicy) throws(TokamakPluginError) {
+    var error: NSError?
+    if LAContext().canEvaluatePolicy(policy, error: &error) {
+      return
+    }
+    let message = error?.localizedDescription ?? "Authentication is unavailable"
+    if (error as? LAError)?.code == .biometryNotAvailable {
+      throw .notSupported(message)
+    }
+    throw TokamakPluginError(name: "InvalidStateError", message: message)
+  }
+
+  private func check(_ status: OSStatus) throws(TokamakPluginError) {
+    guard status != errSecSuccess else { return }
+    let message = SecCopyErrorMessageString(status, nil) as String? ?? "Keychain error \(status)"
+    switch status {
+    case errSecMissingEntitlement:
+      throw Self.teamSigningRequired
+    case errSecUserCanceled, errSecAuthFailed, errSecInteractionNotAllowed:
+      throw TokamakPluginError(name: "NotAllowedError", message: message)
+    default:
+      throw TokamakPluginError(name: "OperationError", message: message)
+    }
+  }
+
+  private func requiredString(
+    _ arguments: [String: Any],
+    _ key: String
+  ) throws(TokamakPluginError) -> String {
+    guard let value = arguments[key] as? String else {
+      throw TokamakPluginError(name: "TypeError", message: "\(key) must be a string")
+    }
+    return value
+  }
+
+  /// Missing and null arguments are nil; other non-string values are rejected.
+  private func optionalString(
+    _ arguments: [String: Any],
+    _ key: String
+  ) throws(TokamakPluginError) -> String? {
+    guard let value = arguments[key], !(value is NSNull) else { return nil }
+    return try requiredString(arguments, key)
+  }
+
+  private func unsupportedArgument(_ key: String, _ value: String) -> TokamakPluginError {
+    TokamakPluginError(name: "TypeError", message: "\(key) '\(value)' is not supported")
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@tokamakdev/plugin-secure-storage",
+  "version": "0.1.0-beta.45",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/secure-storage"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.45"
+  },
+  "files": [
+    "android",
+    "apple",
+    "src",
+    "tokamak-plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import { FrontendPlugin } from "@tokamakdev/plugin";
+
+/** When a stored value can be read. */
+export type Readable = "whenUnlocked" | "afterFirstUnlock";
+
+/** The authentication a read requires. */
+export type Authentication = "biometricsOrPasscode" | "biometrics" | "currentBiometrics";
+
+export interface SetOptions {
+  readonly readable: Readable;
+  /** Reads need no authentication when omitted. */
+  readonly authentication?: Authentication;
+}
+
+export interface GetOptions {
+  /** The reason shown in the system authentication prompt. */
+  readonly prompt?: string;
+}
+
+class SecureStorage extends FrontendPlugin {
+  constructor() {
+    super("secure-storage");
+  }
+
+  set(name: string, value: string, options: SetOptions): Promise<void> {
+    return this.call("set", {
+      name,
+      value,
+      readable: options.readable,
+      authentication: options.authentication ?? null,
+    });
+  }
+
+  get(name: string, options: GetOptions = {}): Promise<string | null> {
+    return this.call("get", { name, prompt: options.prompt ?? null });
+  }
+
+  delete(name: string): Promise<void> {
+    return this.call("delete", { name });
+  }
+}
+
+export const secureStorage = new SecureStorage();

package/tokamak-plugin.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "id": "secure-storage",
+  "kind": "frontend",
+  "platforms": {
+    "macos": {
+      "class": "TokamakSecureStoragePlugin",
+      "sources": ["apple/SecureStoragePlugin.swift"],
+      "frameworks": ["LocalAuthentication", "Security"]
+    },
+    "ios": {
+      "class": "TokamakSecureStoragePlugin",
+      "sources": ["apple/SecureStoragePlugin.swift"],
+      "frameworks": ["LocalAuthentication", "Security"],
+      "plist": {
+        "NSFaceIDUsageDescription": "This app uses Face ID to confirm your identity."
+      }
+    },
+    "ios-simulator": {
+      "class": "TokamakSecureStoragePlugin",
+      "sources": ["apple/SecureStoragePlugin.swift"],
+      "frameworks": ["LocalAuthentication", "Security"],
+      "plist": {
+        "NSFaceIDUsageDescription": "This app uses Face ID to confirm your identity."
+      }
+    },
+    "android": {
+      "class": "com.tokamak.plugins.securestorage.TokamakSecureStoragePlugin",
+      "sources": ["android/SecureStoragePlugin.kt"],
+      "permissions": ["android.permission.USE_BIOMETRIC"]
+    }
+  }
+}