akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/plugins/secure-storage/android/SecureStoragePlugin.kt

@@ -0,0 +1,184 @@
+package com.akanjs.plugins.securestorage
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import android.util.Log
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+import java.security.KeyStore
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import javax.crypto.AEADBadTagException
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * What androidx.security EncryptedSharedPreferences does, with framework APIs only (plugins.md §4.3):
+ * - One AES-256-GCM key in AndroidKeyStore (hardware-backed where the device has a TEE). It never
+ *   leaves the keystore and needs no user authentication, so background work can read values.
+ * - Values are stored as "1:" + Base64(IV ‖ ciphertext ‖ tag) in their own SharedPreferences file.
+ *   The keystore picks a fresh random IV per encryption (setRandomizedEncryptionRequired, default),
+ *   and the key name is authenticated data, so values swapped between keys fail to decrypt.
+ * - Key names are stored in plain text (EncryptedSharedPreferences also encrypts them); they are
+ *   identifiers, not secrets.
+ * - Keystore keys are not part of backups or device-to-device transfers. The shell sets
+ *   allowBackup="false", but Android 12+ still copies app data in a device-to-device transfer, so a
+ *   file can arrive without its key: without the key every entry is dropped, and an entry that fails
+ *   to decrypt reads as null and is removed (expo-secure-store behaves the same way).
+ * - Keystore calls are IPC to keystore2 and first-use key generation takes ~100 ms, so everything
+ *   runs on one worker thread, which also keeps set/get ordered. Writes use commit() on that thread
+ *   so a resolved set() is on disk.
+ * StrongBox (setIsStrongBoxBacked) is not requested: it is much slower and missing on many devices.
+ * Arguments arrive decoded and type-checked by the generated SecureStoragePluginSpec (PL-10).
+ */
+class SecureStoragePlugin(context: AkanNativePluginContext) : SecureStoragePluginSpec {
+    private val prefs = context.activity.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+    private val worker: ExecutorService = Executors.newSingleThreadExecutor { r -> Thread(r, "akan-native-secure-storage") }
+    private var key: SecretKey? = null // worker thread only
+
+    override fun get(args: SecureStorageGetArgs, reply: AkanNativeReply<SecureStorageGetResult>) {
+        if (!valid(args.key, reply)) return
+        val name = args.key
+        run(reply) { SecureStorageGetResult(value = read(name)) }
+    }
+
+    override fun set(args: SecureStorageSetArgs, reply: AkanNativeVoidReply) {
+        if (!valid(args.key, reply)) return
+        val name = args.key
+        run(reply) {
+            if (!prefs.edit().putString(name, encrypt(name, args.value)).commit()) throw IllegalStateException("could not write $PREFS")
+        }
+    }
+
+    override fun remove(args: SecureStorageRemoveArgs, reply: AkanNativeVoidReply) {
+        if (!valid(args.key, reply)) return
+        val name = args.key
+        run(reply) {
+            prefs.edit().remove(name).commit()
+        }
+    }
+
+    override fun keys(reply: AkanNativeReply<SecureStorageKeysResult>) = run(reply) { SecureStorageKeysResult(keys = readableKeys()) }
+
+    override fun clear(reply: AkanNativeVoidReply) = run(reply) {
+        prefs.edit().clear().commit()
+    }
+
+    override fun destroy() {
+        worker.shutdown()
+    }
+
+    private fun valid(key: String, reply: AkanNativeReply<*>): Boolean {
+        if (key.isNotEmpty()) return true
+        reply.reject(AkanNativeErrorCode.INVALID_ARGS, "key must be a non-empty string")
+        return false
+    }
+
+    private fun <T> run(reply: AkanNativeReply<T>, block: () -> T) {
+        worker.execute {
+            try {
+                reply.resolve(block())
+            } catch (e: Exception) { // GeneralSecurityException, KeyStoreException, ProviderException
+                Log.e("AkanNative", "secure-storage ${reply.call.method} failed", e)
+                reply.reject(AkanNativeErrorCode.INTERNAL, "secure-storage: $e")
+            }
+        }
+    }
+
+    /** The keystore key; with [create], generated when missing (and whatever was stored without it is dropped). */
+    private fun secretKey(create: Boolean): SecretKey? {
+        key?.let { return it }
+        val store = KeyStore.getInstance(KEYSTORE).apply { load(null) }
+        (store.getKey(ALIAS, null) as? SecretKey)?.let { return it.also { key = it } }
+        if (!create) return null
+        if (prefs.all.isNotEmpty()) {
+            Log.w("AkanNative", "secure-storage: the keystore key is gone (restore or device transfer), dropping ${prefs.all.size} entries")
+            prefs.edit().clear().commit()
+        }
+        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE)
+        generator.init(
+            KeyGenParameterSpec.Builder(ALIAS, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .setKeySize(256)
+                .build(),
+        )
+        return generator.generateKey().also { key = it }
+    }
+
+    private fun encrypt(name: String, value: String): String {
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.ENCRYPT_MODE, secretKey(create = true))
+        cipher.updateAAD(aad(name))
+        val iv = cipher.iv
+        return FORMAT + Base64.encodeToString(iv + cipher.doFinal(value.toByteArray(Charsets.UTF_8)), Base64.NO_WRAP)
+    }
+
+    /**
+     * null when the entry can never be read with the current key (another key, another name, or
+     * damaged: AEADBadTagException). Anything else the keystore throws may pass (a busy or
+     * restarting keystore daemon): it is thrown, the call fails, and the entry stays.
+     */
+    private fun decrypt(name: String, stored: String, key: SecretKey): String? {
+        val bytes = if (stored.startsWith(FORMAT)) runCatching { Base64.decode(stored.substring(FORMAT.length), Base64.NO_WRAP) }.getOrNull() else null
+        if (bytes == null || bytes.size < IV_BYTES + TAG_BITS / 8) return null
+        return try {
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(TAG_BITS, bytes, 0, IV_BYTES))
+            cipher.updateAAD(aad(name))
+            String(cipher.doFinal(bytes, IV_BYTES, bytes.size - IV_BYTES), Charsets.UTF_8)
+        } catch (e: AEADBadTagException) {
+            null
+        } catch (e: KeyPermanentlyInvalidatedException) {
+            // The key can never decrypt again: drop it with every entry, so the next set() starts over.
+            KeyStore.getInstance(KEYSTORE).apply { load(null) }.deleteEntry(ALIAS)
+            this.key = null
+            prefs.edit().clear().commit()
+            throw e
+        }
+    }
+
+    private fun read(name: String): String? {
+        val stored = prefs.getString(name, null) ?: return null
+        val key = secretKey(create = false) ?: return null
+        return decrypt(name, stored, key) ?: run {
+            Log.w("AkanNative", "secure-storage: $name cannot be decrypted, removing it")
+            prefs.edit().remove(name).commit()
+            null
+        }
+    }
+
+    /** Only keys get() can return; unreadable entries are removed on the way. */
+    private fun readableKeys(): List<String> {
+        val all = prefs.all
+        if (all.isEmpty()) return emptyList()
+        val key = secretKey(create = false) ?: return emptyList()
+        val readable = ArrayList<String>()
+        val editor = prefs.edit()
+        var dropped = false
+        for ((name, stored) in all) {
+            if (stored is String && decrypt(name, stored, key) != null) readable.add(name) else { editor.remove(name); dropped = true }
+        }
+        if (dropped) editor.commit()
+        return readable.sorted()
+    }
+
+    private fun aad(name: String): ByteArray = "akan-native.secure-storage\u0000$name".toByteArray(Charsets.UTF_8)
+
+    private companion object {
+        const val PREFS = "akan-native.secure-storage"
+        const val KEYSTORE = "AndroidKeyStore"
+        const val ALIAS = "akan-native.secure-storage"
+        const val TRANSFORMATION = "AES/GCM/NoPadding"
+        const val FORMAT = "1:"
+        const val IV_BYTES = 12
+        const val TAG_BITS = 128
+    }
+}

package/vendor/@akanjs/native/plugins/secure-storage/ios/SecureStoragePlugin.swift

@@ -0,0 +1,145 @@
+import Foundation
+import Security
+
+/// Keychain generic passwords: service "<bundle id>.akan-native.secure-storage", account = key, data = UTF-8.
+/// - kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly: readable in the background once the device
+///   was unlocked after boot, never synced to iCloud Keychain and never restored onto another
+///   device from a backup (expo-secure-store and capacitor secure storage default to WhenUnlocked,
+///   which breaks token refresh in background tasks).
+/// - Keychain items outlive the app: they are still there after an uninstall and reinstall. Wiping
+///   them on "first launch" (a UserDefaults flag) is a known trap, because a prewarmed launch before
+///   the first unlock reads UserDefaults as empty; apps that want it call clear() themselves.
+/// - SecItem calls block on securityd, so they run on a serial queue (also keeps set/get ordered).
+/// - Update first, add on errSecItemNotFound: SecItemAdd on an existing item fails with errSecDuplicateItem.
+/// Arguments arrive decoded and type-checked by the generated SecureStoragePluginSpec (PL-10).
+final class SecureStoragePlugin: SecureStoragePluginSpec {
+    static let id = "secure-storage"
+    private let service: String
+    private let queue = DispatchQueue(label: "com.akanjs.secure-storage")
+
+    init(context: AkanNativePluginContext) {
+        service = "\(Bundle.main.bundleIdentifier ?? "akan-native").akan-native.secure-storage"
+    }
+
+    func get(_ args: SecureStorageGetArgs, _ reply: AkanNativeReply<SecureStorageGetResult>) {
+        guard Self.valid(args.key, reply) else { return }
+        let key = args.key
+        let service = self.service
+        queue.async { Self.finish(reply) { try SecureStorageGetResult(value: Self.read(service, key)) } }
+    }
+
+    func set(_ args: SecureStorageSetArgs, _ reply: AkanNativeReply<Void>) {
+        guard Self.valid(args.key, reply) else { return }
+        let key = args.key
+        let service = self.service
+        let value = args.value
+        queue.async { Self.finish(reply) { try Self.write(service, key, Data(value.utf8)) } }
+    }
+
+    func remove(_ args: SecureStorageRemoveArgs, _ reply: AkanNativeReply<Void>) {
+        guard Self.valid(args.key, reply) else { return }
+        let key = args.key
+        let service = self.service
+        queue.async {
+            Self.finish(reply) {
+                try Self.check(SecItemDelete(Self.query(service, key) as CFDictionary), allowNotFound: true)
+            }
+        }
+    }
+
+    func keys(_ reply: AkanNativeReply<SecureStorageKeysResult>) {
+        let service = self.service
+        queue.async { Self.finish(reply) { try SecureStorageKeysResult(keys: Self.accounts(service)) } }
+    }
+
+    func clear(_ reply: AkanNativeReply<Void>) {
+        let service = self.service
+        // On iOS SecItemDelete removes every match (on macOS' file-based keychain only the first).
+        queue.async {
+            Self.finish(reply) {
+                try Self.check(SecItemDelete(Self.query(service, nil) as CFDictionary), allowNotFound: true)
+            }
+        }
+    }
+
+    private static func valid<T>(_ key: String, _ reply: AkanNativeReply<T>) -> Bool {
+        if !key.isEmpty { return true }
+        reply.reject(.invalidArgs, "key must be a non-empty string")
+        return false
+    }
+
+    // MARK: Keychain (off the main actor)
+
+    private struct KeychainError: Error {
+        let status: OSStatus
+    }
+
+    nonisolated private static func finish<T>(_ reply: AkanNativeReply<T>, _ body: () throws -> T) {
+        do {
+            reply.resolve(try body())
+        } catch let error as KeychainError {
+            let text = SecCopyErrorMessageString(error.status, nil) as String? ?? "OSStatus \(error.status)"
+            let hint =
+                switch error.status {
+                // Before the first unlock after a reboot (prewarmed launch).
+                case errSecInteractionNotAllowed: " (the device has not been unlocked since it started)"
+                // An ad-hoc signed simulator build without the application-identifier entitlement
+                // (Xcode embeds it as simulated entitlements, a __TEXT,__entitlements section).
+                case errSecMissingEntitlement: " (the app has no application-identifier entitlement)"
+                default: ""
+                }
+            reply.reject(.internalError, "keychain: \(text)\(hint)")
+        } catch {
+            reply.reject(.internalError, "\(error)")
+        }
+    }
+
+    nonisolated private static func query(_ service: String, _ account: String?) -> [String: Any] {
+        var query: [String: Any] = [kSecClass as String: kSecClassGenericPassword, kSecAttrService as String: service]
+        if let account { query[kSecAttrAccount as String] = account }
+        return query
+    }
+
+    nonisolated private static func check(_ status: OSStatus, allowNotFound: Bool = false) throws {
+        if status == errSecSuccess || (allowNotFound && status == errSecItemNotFound) { return }
+        throw KeychainError(status: status)
+    }
+
+    nonisolated private static func read(_ service: String, _ account: String) throws -> String? {
+        var query = query(service, account)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound { return nil }
+        try check(status)
+        guard let data = result as? Data else { return nil }
+        guard let text = String(data: data, encoding: .utf8) else {
+            throw NSError(domain: "akan-native", code: 1, userInfo: [NSLocalizedDescriptionKey: "\(account) does not hold UTF-8 text"])
+        }
+        return text
+    }
+
+    nonisolated private static func write(_ service: String, _ account: String, _ data: Data) throws {
+        let attributes: [String: Any] = [
+            kSecValueData as String: data,
+            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
+        ]
+        let status = SecItemUpdate(query(service, account) as CFDictionary, attributes as CFDictionary)
+        if status != errSecItemNotFound { return try check(status) }
+        let add = query(service, account).merging(attributes) { $1 }
+        try check(SecItemAdd(add as CFDictionary, nil))
+    }
+
+    nonisolated private static func accounts(_ service: String) throws -> [String] {
+        var query = query(service, nil)
+        query[kSecReturnAttributes as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitAll
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound { return [] }
+        try check(status)
+        let items = result as? [[String: Any]] ?? []
+        return items.compactMap { $0[kSecAttrAccount as String] as? String }.sorted()
+    }
+}

package/vendor/@akanjs/native/plugins/secure-storage/native-plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "secure-storage",
+  "apiVersion": 1,
+  "methods": ["get", "set", "remove", "keys", "clear"],
+  "events": [],
+  "codegen": true,
+  "web": null,
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "SecureStoragePlugin",
+    "frameworks": ["Security"]
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.securestorage.SecureStoragePlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/secure-storage/src/desktop.ts

@@ -0,0 +1,332 @@
+
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type { SecureStorageApi } from "./index.ts";
+
+const SECURITY = "/usr/bin/security"; 
+const ACCOUNT = "data-key";
+/** The in-process item's account (another item than the tool's, see above). */
+const APP_ACCOUNT = "data-key.app";
+const NOT_FOUND = 44; 
+const DUPLICATE = 45; 
+
+export interface DesktopSecureStorageOptions {
+  /** Keychain service of the data key. Default `<app id>.akan-native.secure-storage`. */
+  service?: (ctx: DesktopContext) => string;
+  /** The encrypted values. Default `<appDataDir>/secure-storage.json`. */
+  file?: (ctx: DesktopContext) => string;
+}
+
+interface Store {
+  /**
+   * Set on Windows and Linux, and on macOS when the app is signed with a Team ID: the key lives in
+   * an item the shell reads and writes (keychain.* ops), not through /usr/bin/security.
+   */
+  shell: DesktopContext["shell"] | null;
+  /** The account of the shell's item: APP_ACCOUNT on macOS (see above), ACCOUNT elsewhere. */
+  account: string;
+  service: string;
+  label: string;
+  file: string;
+  key: Buffer | null;
+  reading: Promise<Buffer | null> | null;
+  creating: Promise<Buffer> | null;
+  entries: Map<string, string> | null;
+}
+
+async function run(argv: string[], input?: string): Promise<{ code: number; out: string; err: string }> {
+  const proc = Bun.spawn(argv, {
+    stdin: input === undefined ? "ignore" : new Blob([input]),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, out, err };
+}
+
+/** A word for `security -i`, whose tokenizer takes "…" with \" and \\ escapes. Lines cannot hold control characters. */
+export function quoteForSecurity(text: string): string {
+  const printable = [...text].map((c) => (c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f ? " " : c)).join("");
+  return `"${printable.replace(/[\\"]/g, "\\$&")}"`;
+}
+
+const hexKey = (store: Store, hex: string) => {
+  if (!/^[0-9a-f]{64}$/.test(hex))
+    throw new AkanNativeError(
+      "INTERNAL",
+      `the stored item ${store.service} (${store.account}) is not an akan-native secure storage key`,
+    );
+  return Buffer.from(hex, "hex");
+};
+
+async function readKey(store: Store): Promise<Buffer | null> {
+  if (store.shell) {
+    const { value } = (await store.shell("keychain.get", { service: store.service, account: store.account })) as {
+      value: string | null;
+    };
+    if (value) return hexKey(store, value);
+    if (process.platform !== "darwin") return null;
+    const old = await readToolKey(store);
+    if (!old) return null;
+    await store.shell("keychain.set", {
+      service: store.service,
+      account: store.account,
+      value: old.toString("hex"),
+      label: store.label,
+    });
+    await run([SECURITY, "delete-generic-password", "-s", store.service, "-a", ACCOUNT]);
+    return old;
+  }
+  return readToolKey(store);
+}
+
+async function readToolKey(store: Store): Promise<Buffer | null> {
+  const { code, out, err } = await run([SECURITY, "find-generic-password", "-s", store.service, "-a", ACCOUNT, "-w"]);
+  if (code === NOT_FOUND) return null;
+  if (code !== 0)
+    throw new AkanNativeError(
+      "INTERNAL",
+      `reading the secure storage key from the Keychain failed (${code}): ${err.trim()}`,
+    );
+  const hex = out.trim();
+  if (!/^[0-9a-f]{64}$/.test(hex))
+    throw new AkanNativeError(
+      "INTERNAL",
+      `the Keychain item ${store.service} is not an akan-native secure storage key`,
+    );
+  return Buffer.from(hex, "hex");
+}
+
+async function createKey(store: Store): Promise<Buffer> {
+  const hex = randomBytes(32).toString("hex");
+  if (store.shell) {
+    const existing = await readKey(store); 
+    if (existing) return existing;
+    
+    await store.shell("keychain.set", {
+      service: store.service,
+      account: store.account,
+      value: hex,
+      label: store.label,
+    });
+    return Buffer.from(hex, "hex");
+  }
+  const command = [
+    "add-generic-password",
+    "-s",
+    quoteForSecurity(store.service),
+    "-a",
+    quoteForSecurity(ACCOUNT),
+    "-l",
+    quoteForSecurity(store.label),
+    "-j",
+    quoteForSecurity(
+      "akan-native: encrypts this app's secure-storage.json. Deleting it makes the stored values unreadable.",
+    ),
+    
+    "-X",
+    Buffer.from(hex, "latin1").toString("hex"),
+  ].join(" ");
+  const { code, err } = await run([SECURITY, "-i"], `${command}\n`);
+  if (code === DUPLICATE) {
+    const existing = await readKey(store); 
+    if (existing) return existing;
+  }
+  if (code !== 0)
+    throw new AkanNativeError(
+      "INTERNAL",
+      `storing the secure storage key in the Keychain failed (${code}): ${err.trim()}`,
+    );
+  return Buffer.from(hex, "hex");
+}
+
+function entries(store: Store): Map<string, string> {
+  if (store.entries) return store.entries;
+  const map = new Map<string, string>();
+  if (existsSync(store.file)) {
+    try {
+      const data = JSON.parse(readFileSync(store.file, "utf8")) as { v?: unknown; entries?: Record<string, unknown> };
+      if (data.v === 1 && data.entries && typeof data.entries === "object") {
+        for (const [key, value] of Object.entries(data.entries)) if (typeof value === "string") map.set(key, value);
+      }
+    } catch (error) {
+      console.error(`[akan-native] ${store.file} is unreadable, starting empty`, error);
+    }
+  }
+  store.entries = map;
+  return map;
+}
+
+function save(store: Store): void {
+  mkdirSync(dirname(store.file), { recursive: true });
+  
+  const tmp = `${store.file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ v: 1, entries: Object.fromEntries(entries(store)) }), { mode: 0o600 });
+  renameSync(tmp, store.file);
+}
+
+function dataKey(store: Store, create: true): Promise<Buffer>;
+function dataKey(store: Store, create: false): Promise<Buffer | null>;
+function dataKey(store: Store, create: boolean): Promise<Buffer | null> {
+  if (store.key) return Promise.resolve(store.key);
+  if (create) {
+    
+    store.creating ??= (async () => {
+      let key = await readKey(store);
+      if (!key) {
+        key = await createKey(store);
+
+        if (entries(store).size > 0) {
+          entries(store).clear();
+          save(store);
+        }
+      }
+      store.key = key;
+      return key;
+    })().finally(() => {
+      store.creating = null;
+    });
+    return store.creating;
+  }
+  store.reading ??= readKey(store)
+    .then((key) => {
+      if (key) store.key = key;
+      return key;
+    })
+    .finally(() => {
+      store.reading = null;
+    });
+  return store.reading;
+}
+
+/** AAD binds each value to its key: swapping entries in the file makes them unreadable. */
+const aad = (name: string) => Buffer.from(`akan-native.secure-storage\0${name}`, "utf8");
+
+export function encrypt(key: Buffer, name: string, value: string): string {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(aad(name));
+  const body = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+  return Buffer.concat([iv, body, cipher.getAuthTag()]).toString("base64");
+}
+
+/** null when the entry was written with another key, for another name, or is damaged. */
+export function decrypt(key: Buffer, name: string, blob: string): string | null {
+  try {
+    const bytes = Buffer.from(blob, "base64");
+    if (bytes.length < 12 + 16) return null;
+    const decipher = createDecipheriv("aes-256-gcm", key, bytes.subarray(0, 12));
+    decipher.setAAD(aad(name));
+    decipher.setAuthTag(bytes.subarray(bytes.length - 16));
+    return Buffer.concat([decipher.update(bytes.subarray(12, bytes.length - 16)), decipher.final()]).toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function checkKey(key: unknown): string {
+  if (typeof key !== "string" || key.length === 0)
+    throw new AkanNativeError("INVALID_ARGS", "key must be a non-empty string");
+  return key;
+}
+
+/** shell.json of the running .app says it is signed with a Team ID (see above). */
+function signedWithTeam(): boolean {
+  const macos = dirname(process.execPath);
+  const shell = join(dirname(macos), "Resources", "shell.json");
+  try {
+    return (JSON.parse(readFileSync(shell, "utf8")) as { signing?: string }).signing === "team";
+  } catch {
+    return false;
+  }
+}
+
+export function createDesktopSecureStorage(options: DesktopSecureStorageOptions = {}) {
+  const stores = new Map<string, Store>();
+  const storeFor = (ctx: DesktopContext): Store => {
+    const service = options.service?.(ctx) ?? `${ctx.app.id}.akan-native.secure-storage`;
+    const file = options.file?.(ctx) ?? join(ctx.appDataDir, "secure-storage.json");
+    const id = `${service}\0${file}`;
+    let store = stores.get(id);
+    if (!store) {
+      const mac = process.platform === "darwin";
+      const shell = !mac || signedWithTeam() ? ctx.shell : null;
+      store = {
+        shell,
+        account: mac ? APP_ACCOUNT : ACCOUNT,
+        service,
+        label: `${ctx.app.name} secure storage`,
+        file,
+        key: null,
+        reading: null,
+        creating: null,
+        entries: null,
+      };
+      stores.set(id, store);
+    }
+    return store;
+  };
+
+  return defineDesktopPlugin<SecureStorageApi>({
+    id: "secure-storage",
+    methods: {
+      async get(args, ctx) {
+        const name = checkKey(args?.key);
+        const store = storeFor(ctx);
+        const blob = entries(store).get(name);
+        if (blob === undefined) return { value: null };
+        const key = await dataKey(store, false);
+        const value = key ? decrypt(key, name, blob) : null;
+        if (value === null && key && entries(store).get(name) === blob) {
+          entries(store).delete(name); 
+          save(store);
+        }
+        return { value };
+      },
+      async set(args, ctx) {
+        const name = checkKey(args?.key);
+        if (typeof args.value !== "string") throw new AkanNativeError("INVALID_ARGS", "value must be a string");
+        const store = storeFor(ctx);
+        const key = await dataKey(store, true);
+        entries(store).set(name, encrypt(key, name, args.value));
+        save(store);
+      },
+      remove(args, ctx) {
+        const name = checkKey(args?.key);
+        const store = storeFor(ctx);
+        if (entries(store).delete(name)) save(store);
+      },
+      async keys(_args, ctx) {
+        const store = storeFor(ctx);
+        if (entries(store).size === 0) return { keys: [] };
+        const key = await dataKey(store, false);
+        if (!key) return { keys: [] }; 
+        
+        const readable = [...entries(store)].filter(([name, blob]) => decrypt(key, name, blob) !== null);
+        if (readable.length !== entries(store).size) {
+          store.entries = new Map(readable);
+          save(store);
+        }
+        return { keys: readable.map(([name]) => name).sort() };
+      },
+      clear(_args, ctx) {
+        const store = storeFor(ctx);
+        
+        if (entries(store).size > 0 || existsSync(store.file)) {
+          entries(store).clear();
+          save(store);
+        }
+      },
+    },
+  });
+}
+
+export default createDesktopSecureStorage();