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

package/README.md

@@ -0,0 +1,108 @@
+# @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");
+
+await secureStorage.clear();
+```
+
+Values are strings; encode binary values before storing them. Only the app can
+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:
+
+| `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 |
+
+On iOS, the system reports a read of a `currentBiometrics` value after an
+enrolment change as failed authentication, so `get` rejects with
+`NotAllowedError` rather than `NotReadableError`.
+
+`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`
+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.
+
+## 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 |
+| `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 |
+| `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, 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`.
+
+### Values stored by builds from tok 0.1.1-beta.87 or earlier
+
+Team-signed iOS and macOS builds made with tok 0.1.1-beta.87 or earlier kept
+values in a keychain access group literally named `TEAMID.*`, which all of a
+team's apps built that way share. Later builds use the app's own group,
+`TEAMID.<bundle id>`, and cannot see those values. To keep them, declare both
+groups, the app's own first, in the app's entitlements file
+(`ios.entitlements`, `macos.entitlements`):
+
+```xml
+<key>keychain-access-groups</key>
+<array>
+  <string>TEAMID.com.example.app</string>
+  <string>TEAMID.*</string>
+</array>
+```
+
+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.
+
+Removing the device passcode or screen lock makes values stored with
+`authentication` permanently unreadable on Android.

package/android/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+</manifest>

package/android/SecureStoragePlugin.kt

@@ -0,0 +1,349 @@
+package com.tokamak.plugins.securestorage
+
+import android.hardware.biometrics.BiometricManager.Authenticators
+import android.hardware.biometrics.BiometricPrompt
+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.TokamakHost
+import com.tokamak.runtime.TokamakPlugin
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakPluginReply
+import com.tokamak.runtime.authenticateOwner
+import com.tokamak.runtime.optionalString
+import com.tokamak.runtime.requireBoolean
+import com.tokamak.runtime.requireObject
+import com.tokamak.runtime.requireOwnerAuthentication
+import com.tokamak.runtime.requireString
+import java.io.ByteArrayOutputStream
+import java.io.DataInputStream
+import java.io.DataOutputStream
+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.
+ */
+class TokamakSecureStoragePlugin(
+    private val host: TokamakHost,
+) : TokamakPlugin {
+    override val id = "secure-storage"
+
+    private val context = host.context
+    private val worker = Executors.newSingleThreadExecutor()
+    private val directory = File(context.noBackupFilesDir, "tokamak-secure-storage")
+    private val keyStore = KeyStore.getInstance(KEYSTORE).apply { load(null) }
+    private val random = SecureRandom()
+
+    override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
+        when (method) {
+            "set" -> execute(reply) {
+                set(requireObject(arguments))
+                reply(Result.success(null))
+            }
+            "get" -> execute(reply) { get(requireObject(arguments), reply) }
+            "delete" -> execute(reply) {
+                delete(requireObject(arguments).requireString("name"))
+                reply(Result.success(null))
+            }
+            "clear" -> execute(reply) {
+                clear()
+                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) =
+        context.mainExecutor.execute {
+            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 TokamakPluginError.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)
+                .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 { alias(it.keyId) }
+        val publicKey = generatePublicKey(spec)
+        try {
+            write(file, seal(keyId, value, publicKey).encode())
+        } 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()
+        host.requireOwnerAuthentication(authentication.authenticators)
+        spec.setUserAuthenticationRequired(true)
+            .setUserAuthenticationParameters(0, authentication.keyTypes)
+            .setInvalidatedByBiometricEnrollment(authentication.invalidatedByEnrollment)
+    }
+
+    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(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 =
+            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 StoredValue(keyId, 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(alias(stored.keyId), 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: StoredValue,
+        reply: TokamakPluginReply,
+    ) {
+        val title = prompt?.takeIf { it.isNotEmpty() } ?: context.applicationInfo.loadLabel(context.packageManager)
+        onUiThread(reply) {
+            host.authenticateOwner(title, authenticators, BiometricPrompt.CryptoObject(unwrap), reply) {
+                execute(reply) { reply(Result.success(open(stored, unwrap))) }
+            }
+        }
+    }
+
+    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, stored.iv)) }
+            .doFinal(stored.sealed)
+            .decodeToString()
+    }
+
+    private fun delete(name: String) {
+        val file = file(name)
+        val stored = read(file) ?: return
+        AtomicFile(file).delete()
+        keyStore.deleteEntry(alias(stored.keyId))
+    }
+
+    private fun clear() {
+        directory.deleteRecursively()
+        keyStore.aliases().toList()
+            .filter { it.startsWith(ALIAS_PREFIX) }
+            .forEach(keyStore::deleteEntry)
+    }
+
+    private fun read(file: File): StoredValue? =
+        try {
+            StoredValue.decode(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) = ALIAS_PREFIX + keyId.toHex()
+
+    private fun ByteArray.toHex() = joinToString("") { "%02x".format(it) }
+
+    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 ALIAS_PREFIX = "tokamak-secure-storage-"
+        const val DATA_KEY_SIZE = 256
+        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 unknownAuthentication() =
+            TokamakPluginError.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 pluginError(error: Throwable): Throwable =
+            when (error) {
+                is KeyPermanentlyInvalidatedException,
+                is BadPaddingException,
+                is IllegalBlockSizeException,
+                -> notReadable()
+                is UserNotAuthenticatedException -> locked()
+                else -> error
+            }
+    }
+}
+
+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: an unused string, then the key ID, wrapped data key, IV and sealed value. */
+private class StoredValue(
+    val keyId: ByteArray,
+    val wrappedKey: ByteArray,
+    val iv: ByteArray,
+    val sealed: ByteArray,
+) {
+    fun encode(): ByteArray {
+        val bytes = ByteArrayOutputStream()
+        DataOutputStream(bytes).run {
+            writeUTF("")
+            write(keyId)
+            write(wrappedKey)
+            write(iv)
+            write(sealed)
+        }
+        return bytes.toByteArray()
+    }
+
+    companion object {
+        fun decode(bytes: ByteArray): StoredValue =
+            DataInputStream(bytes.inputStream()).run {
+                readUTF()
+                StoredValue(
+                    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)
+    }
+}

package/apple/Info.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>NSFaceIDUsageDescription</key>
+	<string>This app uses Face ID to confirm your identity.</string>
+</dict>
+</plist>

package/apple/SecureStoragePlugin.swift

@@ -0,0 +1,299 @@
+import Foundation
+import LocalAuthentication
+import Security
+
+#if os(iOS)
+  import UIKit
+#endif
+
+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 let host: TokamakHost
+
+  init(host: TokamakHost) {
+    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.
+    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] ?? [:]
+    let prompting =
+      isUnlocked ? Result { () throws(TokamakPluginError) in try host.requireUI() } : nil
+    queue.async {
+      reply(
+        Result { () throws(TokamakPluginError) in
+          try self.perform(method, arguments, prompting: prompting)
+        })
+    }
+  }
+
+  /// Whether the device's protected data is available, which it is not while
+  /// an iPhone is locked. Read it on the main thread.
+  private var isUnlocked: Bool {
+    #if os(iOS)
+      UIApplication.shared.isProtectedDataAvailable
+    #else
+      true
+    #endif
+  }
+
+  /// `prompting` is whether a read or update that needs authentication may
+  /// show the system prompt, decided on the main thread as the call arrives:
+  /// nil while the device is locked, where either fails without UI anyway.
+  private func perform(
+    _ method: String,
+    _ arguments: [String: Any],
+    prompting: Result<Void, TokamakPluginError>?
+  ) 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"),
+        thisDeviceOnly: requiredBool(arguments, "thisDeviceOnly"),
+        authentication: optionalString(arguments, "authentication"),
+        prompt: optionalString(arguments, "prompt"),
+        prompting: prompting
+      )
+      return nil
+    case "get":
+      return try get(
+        requiredString(arguments, "name"),
+        prompt: optionalString(arguments, "prompt"),
+        prompting: prompting
+      )
+    case "delete":
+      try deleteItems(query(requiredString(arguments, "name")))
+      return nil
+    case "clear":
+      try deleteItems(serviceQuery())
+      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(
+    _ name: String,
+    value: String,
+    readable: String,
+    thisDeviceOnly: Bool,
+    authentication: String?,
+    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))
+  }
+
+  /// 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,
+    prompt: String?,
+    prompting: Result<Void, TokamakPluginError>?
+  ) throws(TokamakPluginError) -> String? {
+    var item = query(name)
+    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)
+      status = SecItemCopyMatching(item as CFDictionary, &data)
+      // The first read found the value, so it exists but the system can no longer decrypt it.
+      if status == errSecItemNotFound {
+        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 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
+  /// `errSecInteractionNotAllowed` rather than show the system prompt.
+  private static func contextWithoutUI() -> LAContext {
+    let context = LAContext()
+    context.interactionNotAllowed = true
+    return context
+  }
+
+  /// A context whose system prompt shows `prompt`, or nil for the default prompt.
+  private static func context(prompt: String?) -> LAContext? {
+    guard let prompt, !prompt.isEmpty else { return nil }
+    let context = LAContext()
+    context.localizedReason = prompt
+    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,
+      kSecUseDataProtectionKeychain: true,
+    ]
+  }
+
+  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)
+    }
+  }
+
+  private func accessControl(
+    _ accessibility: CFString,
+    _ authentication: String?
+  ) throws(TokamakPluginError) -> SecAccessControl {
+    let (flags, policy): (SecAccessControlCreateFlags, LAPolicy?) =
+      switch authentication {
+      case nil: ([], nil)
+      case "biometricsOrPasscode": (.userPresence, .deviceOwnerAuthentication)
+      case "biometrics": (.biometryAny, .deviceOwnerAuthenticationWithBiometrics)
+      case "currentBiometrics": (.biometryCurrentSet, .deviceOwnerAuthenticationWithBiometrics)
+      case let authentication?: throw unsupportedArgument("authentication", authentication)
+      }
+    if let policy {
+      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
+  }
+
+  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],
+    _ 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.100",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mantty/tokamak.git",
+    "directory": "plugins/secure-storage"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.100"
+  },
+  "files": [
+    "android",
+    "apple",
+    "src",
+    "tokamak-plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+import { Plugin } 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;
+  /**
+   * 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;
+  /**
+   * The reason shown in the system authentication prompt. Apple platforms ask for the
+   * authentication an existing value was saved with before replacing it.
+   */
+  readonly prompt?: string;
+}
+
+export interface GetOptions {
+  /** The reason shown in the system authentication prompt. */
+  readonly prompt?: string;
+}
+
+class SecureStorage extends Plugin {
+  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,
+      thisDeviceOnly: options.thisDeviceOnly ?? true,
+      prompt: options.prompt ?? 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 });
+  }
+
+  /** Deletes every stored value. */
+  clear(): Promise<void> {
+    return this.call("clear");
+  }
+}
+
+export const secureStorage = new SecureStorage();

package/tokamak-plugin.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "id": "secure-storage",
+  "platforms": {
+    "macos": {
+      "class": "TokamakSecureStoragePlugin",
+      "sources": ["apple/SecureStoragePlugin.swift"]
+    },
+    "ios": {
+      "class": "TokamakSecureStoragePlugin",
+      "sources": ["apple/SecureStoragePlugin.swift"],
+      "plist": "apple/Info.plist"
+    },
+    "android": {
+      "class": "com.tokamak.plugins.securestorage.TokamakSecureStoragePlugin",
+      "sources": ["android/SecureStoragePlugin.kt"],
+      "manifest": "android/AndroidManifest.xml"
+    }
+  }
+}