@capnative/capacitor-secure-storage 0.0.0-stage → 8.0.0

package/CapacitorSecureStorage.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapacitorSecureStorage'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://github.com/marioshtika/capacitor-secure-storage'
+  s.author = package['author']
+  s.source = { :git => 'https://github.com/marioshtika/capacitor-secure-storage.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marioshtika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorSecureStorage",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapacitorSecureStorage",
+            targets: ["SecureStoragePlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "SecureStoragePlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/SecureStoragePlugin"),
+        .testTarget(
+            name: "SecureStoragePluginTests",
+            dependencies: ["SecureStoragePlugin"],
+            path: "ios/Tests/SecureStoragePluginTests")
+    ]
+)

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# Capacitor Secure Storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Capacitor plugin for storing string key-value data securely using the **iOS Keychain** and the **Android Keystore** (AES-256-GCM).
+
+## Compatibility
+
+| Plugin version | Capacitor compatibility | Maintained |
+| -------------- | ----------------------- | ---------- |
+| v8.\*.\*       | v8.\*.\*                | ✅         |
+
+## Supported platforms
+
+| Platform | Support | Minimum version            |
+| -------- | ------- | -------------------------- |
+| iOS      | ✅      | iOS 15                     |
+| Android  | ✅      | API level 24 (Android 7.0) |
+| Web      | ❌      | —                          |
+
+## Install
+
+```bash
+npm install @capnative/capacitor-secure-storage
+npx cap sync
+```
+
+## Basic usage
+
+```typescript
+import { SecureStorage } from '@capnative/capacitor-secure-storage';
+
+await SecureStorage.set({ 
+    key: 'access_token', 
+    value: 'my-secret-token'
+});
+
+const { value } = await SecureStorage.get({ 
+    key: 'access_token'
+});
+```
+
+## API
+
+<docgen-index>
+
+* [`set(...)`](#set)
+* [`get(...)`](#get)
+* [`has(...)`](#has)
+* [`remove(...)`](#remove)
+* [`clear()`](#clear)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### set(...)
+
+```typescript
+set(options: { key: string; value: string; }) => Promise<void>
+```
+
+Stores a string value securely. If the key already exists, its value is overwritten. Empty string values are allowed.
+
+**Options:**
+
+| Param | Type |
+| --- | --- |
+| **`options`** | <code>{ key: string; value: string; }</code> |
+
+--------------------
+
+
+### get(...)
+
+```typescript
+get(options: { key: string; }) => Promise<{ value: string | null; }>
+```
+
+Retrieves a stored value. The value is `null` if the key does not exist.
+
+**Options:**
+
+| Param | Type |
+| --- | --- |
+| **`options`** | <code>{ key: string; }</code> |
+
+**Returns:** <code>Promise&lt;{ value: string | null; }&gt;</code>
+
+--------------------
+
+
+### has(...)
+
+```typescript
+has(options: { key: string; }) => Promise<{ value: boolean; }>
+```
+
+Checks whether a key exists.
+
+**Options:**
+
+| Param | Type |
+| --- | --- |
+| **`options`** | <code>{ key: string; }</code> |
+
+**Returns:** <code>Promise&lt;{ value: boolean; }&gt;</code>
+
+--------------------
+
+
+### remove(...)
+
+```typescript
+remove(options: { key: string; }) => Promise<void>
+```
+
+Deletes a key. Succeeds even if the key does not exist.
+
+**Options:**
+
+| Param | Type |
+| --- | --- |
+| **`options`** | <code>{ key: string; }</code> |
+
+--------------------
+
+
+### clear()
+
+```typescript
+clear() => Promise<void>
+```
+
+Deletes every value stored by this plugin and nothing else.
+
+--------------------
+
+</docgen-api>
+
+Keys must be non-empty and at most 256 UTF-8 bytes. Values must be strings.
+
+## Errors
+
+If an operation fails, its promise rejects with a stable `code` and a safe message. Handle errors using `code`, not the message text.
+
+| Code | Platform | Meaning |
+| ---- | -------- | ------- |
+| `INVALID_KEY` | iOS, Android | The key is empty or exceeds 256 UTF-8 bytes. |
+| `INVALID_VALUE` | iOS, Android | The value passed to `set` is not a string. |
+| `STORAGE_ERROR` | iOS, Android | An unexpected storage operation failed, or Android could not persist a change. |
+| `KEYCHAIN_ERROR` | iOS | The iOS Keychain operation failed. |
+| `KEYSTORE_ERROR` | Android | The Android Keystore could not be accessed or updated. |
+| `ENCRYPTION_ERROR` | Android | The value could not be encrypted. |
+| `DECRYPTION_ERROR` | Android | The stored value is corrupt, tampered with, or cannot be decrypted with the available Keystore key. |
+| `UNAVAILABLE` | Web | Secure storage is not supported on the web; there is no insecure storage fallback. |

package/android/build.gradle

@@ -0,0 +1,60 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxTestRunnerVersion = project.hasProperty('androidxTestRunnerVersion') ? rootProject.ext.androidxTestRunnerVersion : '1.6.2'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty('kotlin_version') ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace = "io.github.marioshtika.securestorage"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdk = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdk = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    kotlinOptions {
+        jvmTarget = '21'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test:runner:$androidxTestRunnerVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/io/github/marioshtika/securestorage/EncryptedPayload.kt

@@ -0,0 +1,35 @@
+package io.github.marioshtika.securestorage
+
+import android.util.Base64
+
+/**
+ * Persistent representation of an encrypted value: `version:base64(iv):base64(ciphertext+tag)`.
+ * The GCM authentication tag is appended to the ciphertext by the JCA provider.
+ */
+class EncryptedPayload(val iv: ByteArray, val cipherText: ByteArray) {
+
+    fun encode(): String =
+        listOf(VERSION, b64(iv), b64(cipherText)).joinToString(SEPARATOR)
+
+    companion object {
+        const val VERSION = "v1"
+        private const val SEPARATOR = ":"
+        const val IV_LENGTH_BYTES = 12
+        const val TAG_LENGTH_BYTES = 16
+
+        private fun b64(bytes: ByteArray) = Base64.encodeToString(bytes, Base64.NO_WRAP)
+
+        /** Parses a stored string; returns null if it is malformed. */
+        fun decode(encoded: String): EncryptedPayload? {
+            val parts = encoded.split(SEPARATOR)
+            if (parts.size != 3 || parts[0] != VERSION) return null
+            return try {
+                val iv = Base64.decode(parts[1], Base64.NO_WRAP)
+                val ct = Base64.decode(parts[2], Base64.NO_WRAP)
+                if (iv.size != IV_LENGTH_BYTES || ct.size < TAG_LENGTH_BYTES) null else EncryptedPayload(iv, ct)
+            } catch (e: IllegalArgumentException) {
+                null
+            }
+        }
+    }
+}

package/android/src/main/java/io/github/marioshtika/securestorage/KeystoreCipher.kt

@@ -0,0 +1,107 @@
+package io.github.marioshtika.securestorage
+
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import java.security.GeneralSecurityException
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * AES-256-GCM encryption using a non-exportable key held in the Android Keystore.
+ * The raw key is never available to this process or persisted anywhere else.
+ * No custom cryptography: only the platform JCA/Keystore primitives are used.
+ */
+class KeystoreCipher(private val alias: String = DEFAULT_ALIAS) {
+
+    private val keyLock = Any()
+
+    /** Encrypts [plainText]. A fresh random IV is generated by the Keystore for every call. */
+    fun encrypt(plainText: ByteArray, associatedData: ByteArray): EncryptedPayload {
+        try {
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.ENCRYPT_MODE, getOrCreateKey())
+            cipher.updateAAD(associatedData)
+            val cipherText = cipher.doFinal(plainText)
+            return EncryptedPayload(cipher.iv, cipherText)
+        } catch (e: GeneralSecurityException) {
+            throw SecureStorageException(SecureStorageException.ENCRYPTION_ERROR, "Failed to encrypt value", e)
+        }
+    }
+
+    /** Decrypts and authenticates [payload]; throws if the data was tampered with or the key is gone. */
+    fun decrypt(payload: EncryptedPayload, associatedData: ByteArray): ByteArray {
+        val key = try {
+            getExistingKey()
+        } catch (e: GeneralSecurityException) {
+            throw SecureStorageException(SecureStorageException.KEYSTORE_ERROR, "Failed to access Android Keystore", e)
+        } ?: throw SecureStorageException(
+            SecureStorageException.DECRYPTION_ERROR,
+            "Encryption key is unavailable; the stored value cannot be decrypted",
+        )
+        try {
+            val cipher = Cipher.getInstance(TRANSFORMATION)
+            cipher.init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(EncryptedPayload.TAG_LENGTH_BYTES * 8, payload.iv))
+            cipher.updateAAD(associatedData)
+            return cipher.doFinal(payload.cipherText)
+        } catch (e: GeneralSecurityException) {
+            throw SecureStorageException(SecureStorageException.DECRYPTION_ERROR, "Failed to decrypt value", e)
+        }
+    }
+
+    /** Whether the Keystore currently holds the key (used by tests). */
+    fun hasKey(): Boolean = try {
+        getExistingKey() != null
+    } catch (e: GeneralSecurityException) {
+        false
+    }
+
+    /** Deletes the Keystore key. All previously encrypted values become undecryptable. */
+    fun deleteKey() {
+        synchronized(keyLock) {
+            try {
+                keyStore().deleteEntry(alias)
+            } catch (e: Exception) {
+                throw SecureStorageException(SecureStorageException.KEYSTORE_ERROR, "Failed to delete key", e)
+            }
+        }
+    }
+
+    private fun keyStore(): KeyStore = KeyStore.getInstance(ANDROID_KEYSTORE).apply { load(null) }
+
+    private fun getExistingKey(): SecretKey? = keyStore().getKey(alias, null) as? SecretKey
+
+    private fun getOrCreateKey(): SecretKey {
+        try {
+            getExistingKey()?.let { return it }
+            // Only key creation is serialized; encrypt/decrypt calls run concurrently.
+            synchronized(keyLock) {
+                getExistingKey()?.let { return it }
+                val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_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)
+                        // Required (default true): the Keystore generates a unique IV per encryption.
+                        .setRandomizedEncryptionRequired(true)
+                        .build(),
+                )
+                return generator.generateKey()
+            }
+        } catch (e: GeneralSecurityException) {
+            throw SecureStorageException(SecureStorageException.KEYSTORE_ERROR, "Failed to access Android Keystore", e)
+        }
+    }
+
+    companion object {
+        const val DEFAULT_ALIAS = "capacitor-secure-storage-key"
+        private const val ANDROID_KEYSTORE = "AndroidKeyStore"
+        private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    }
+}

package/android/src/main/java/io/github/marioshtika/securestorage/SecureStorage.kt

@@ -0,0 +1,80 @@
+package io.github.marioshtika.securestorage
+
+import android.content.Context
+import android.content.SharedPreferences
+import java.security.MessageDigest
+
+/**
+ * Persists values encrypted by [KeystoreCipher] in a dedicated SharedPreferences file.
+ * The file is only a persistence layer: it contains hashed key names and ciphertext, never plaintext values.
+ * The key name is bound to the ciphertext as GCM associated data, so entries cannot be swapped between keys.
+ */
+class SecureStorage(
+    private val prefs: SharedPreferences,
+    private val cipher: KeystoreCipher = KeystoreCipher(),
+) {
+
+    constructor(context: Context, prefsName: String = PREFS_NAME, alias: String = KeystoreCipher.DEFAULT_ALIAS) :
+        this(
+            context.applicationContext.getSharedPreferences(prefsName, Context.MODE_PRIVATE),
+            KeystoreCipher(alias),
+        )
+
+    fun set(key: String, value: String) {
+        val storageKey = storageKey(key)
+        val payload = cipher.encrypt(value.toByteArray(Charsets.UTF_8), storageKey.toByteArray(Charsets.UTF_8))
+        // commit() is synchronous so failures are reported; we are never on the UI thread here.
+        if (!prefs.edit().putString(storageKey, payload.encode()).commit()) {
+            throw SecureStorageException(SecureStorageException.STORAGE_ERROR, "Failed to persist value")
+        }
+    }
+
+    /** Returns the decrypted value, or null if the key doesn't exist. Throws if decryption fails. */
+    fun get(key: String): String? {
+        val storageKey = storageKey(key)
+        val encoded = prefs.getString(storageKey, null) ?: return null
+        val payload = EncryptedPayload.decode(encoded)
+            ?: throw SecureStorageException(SecureStorageException.DECRYPTION_ERROR, "Stored value is corrupted")
+        val bytes = cipher.decrypt(payload, storageKey.toByteArray(Charsets.UTF_8))
+        return String(bytes, Charsets.UTF_8)
+    }
+
+    fun has(key: String): Boolean = prefs.contains(storageKey(key))
+
+    fun remove(key: String) {
+        if (!prefs.edit().remove(storageKey(key)).commit()) {
+            throw SecureStorageException(SecureStorageException.STORAGE_ERROR, "Failed to remove value")
+        }
+    }
+
+    /** Removes only entries of this plugin's dedicated preferences file. The Keystore key is kept. */
+    fun clear() {
+        if (!prefs.edit().clear().commit()) {
+            throw SecureStorageException(SecureStorageException.STORAGE_ERROR, "Failed to clear values")
+        }
+    }
+
+    companion object {
+        const val PREFS_NAME = "capacitor_secure_storage"
+        const val MAX_KEY_BYTES = 256
+
+        /** Throws INVALID_KEY unless [key] is a non-empty string of at most [MAX_KEY_BYTES] UTF-8 bytes. */
+        fun validateKey(key: String?): String {
+            if (key.isNullOrEmpty()) {
+                throw SecureStorageException(SecureStorageException.INVALID_KEY, "Key must be a non-empty string")
+            }
+            if (key.toByteArray(Charsets.UTF_8).size > MAX_KEY_BYTES) {
+                throw SecureStorageException(
+                    SecureStorageException.INVALID_KEY,
+                    "Key must be at most $MAX_KEY_BYTES bytes",
+                )
+            }
+            return key
+        }
+
+        /** Key names are hashed so that they are not stored in plaintext either. */
+        fun storageKey(key: String): String =
+            MessageDigest.getInstance("SHA-256").digest(key.toByteArray(Charsets.UTF_8))
+                .joinToString("") { "%02x".format(it) }
+    }
+}

package/android/src/main/java/io/github/marioshtika/securestorage/SecureStorageException.kt

@@ -0,0 +1,21 @@
+package io.github.marioshtika.securestorage
+
+/**
+ * A storage failure with a stable error code and a safe message.
+ * Messages must never contain secrets, key material, ciphertext or decrypted data,
+ * and the underlying cause is intentionally never forwarded to JavaScript.
+ */
+class SecureStorageException(
+    val code: String,
+    message: String,
+    cause: Throwable? = null,
+) : Exception(message, cause) {
+    companion object {
+        const val INVALID_KEY = "INVALID_KEY"
+        const val INVALID_VALUE = "INVALID_VALUE"
+        const val STORAGE_ERROR = "STORAGE_ERROR"
+        const val KEYSTORE_ERROR = "KEYSTORE_ERROR"
+        const val ENCRYPTION_ERROR = "ENCRYPTION_ERROR"
+        const val DECRYPTION_ERROR = "DECRYPTION_ERROR"
+    }
+}

package/android/src/main/java/io/github/marioshtika/securestorage/SecureStoragePlugin.kt

@@ -0,0 +1,64 @@
+package io.github.marioshtika.securestorage
+
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+@CapacitorPlugin(name = "SecureStorage")
+class SecureStoragePlugin : Plugin() {
+
+    private val storage: SecureStorage by lazy { SecureStorage(context) }
+
+    // Plugin methods run on Capacitor's background plugin thread (not the UI thread).
+    // SharedPreferences is thread-safe and only key creation is locked, so calls run concurrently.
+
+    @PluginMethod
+    fun set(call: PluginCall) = handle(call) {
+        val key = SecureStorage.validateKey(call.getString("key"))
+        val value = call.getString("value")
+            ?: throw SecureStorageException(SecureStorageException.INVALID_VALUE, "Value must be a string")
+        storage.set(key, value)
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun get(call: PluginCall) = handle(call) {
+        val key = SecureStorage.validateKey(call.getString("key"))
+        val result = JSObject()
+        result.put("value", storage.get(key) ?: JSObject.NULL)
+        call.resolve(result)
+    }
+
+    @PluginMethod
+    fun has(call: PluginCall) = handle(call) {
+        val key = SecureStorage.validateKey(call.getString("key"))
+        val result = JSObject()
+        result.put("value", storage.has(key))
+        call.resolve(result)
+    }
+
+    @PluginMethod
+    fun remove(call: PluginCall) = handle(call) {
+        storage.remove(SecureStorage.validateKey(call.getString("key")))
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun clear(call: PluginCall) = handle(call) {
+        storage.clear()
+        call.resolve()
+    }
+
+    private fun handle(call: PluginCall, block: () -> Unit) {
+        try {
+            block()
+        } catch (e: SecureStorageException) {
+            // Only the safe message and code are exposed; the cause is never forwarded.
+            call.reject(e.message, e.code)
+        } catch (e: Exception) {
+            call.reject("Unexpected storage error", SecureStorageException.STORAGE_ERROR)
+        }
+    }
+}

package/dist/esm/definitions.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Error codes reported by the native implementations (as `error.code`).
+ */
+export type SecureStorageErrorCode = 'INVALID_KEY' | 'INVALID_VALUE' | 'STORAGE_ERROR' | 'KEYCHAIN_ERROR' | 'KEYSTORE_ERROR' | 'ENCRYPTION_ERROR' | 'DECRYPTION_ERROR' | 'UNAVAILABLE';
+/** Maximum key length (in UTF-8 bytes) accepted on every platform. */
+export declare const MAX_KEY_LENGTH = 256;
+export interface SecureStoragePlugin {
+    /**
+     * Store a string value securely.
+     * If the key already exists, overwrite its value.
+     */
+    set(options: {
+        key: string;
+        value: string;
+    }): Promise<void>;
+    /**
+     * Retrieve a previously stored value.
+     *
+     * Returns null if the key does not exist.
+     */
+    get(options: {
+        key: string;
+    }): Promise<{
+        value: string | null;
+    }>;
+    /**
+     * Check whether a key exists.
+     */
+    has(options: {
+        key: string;
+    }): Promise<{
+        value: boolean;
+    }>;
+    /**
+     * Delete a key.
+     *
+     * Succeeds even if the key does not exist.
+     */
+    remove(options: {
+        key: string;
+    }): Promise<void>;
+    /**
+     * Remove all values stored by this plugin.
+     */
+    clear(): Promise<void>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,3 @@
+/** Maximum key length (in UTF-8 bytes) accepted on every platform. */
+export const MAX_KEY_LENGTH = 256;
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAaA,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { SecureStoragePlugin } from './definitions';
+declare const SecureStorage: SecureStoragePlugin;
+export * from './definitions';
+export { SecureStorage };

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const SecureStorage = registerPlugin('SecureStorage', {
+    web: () => import('./web').then((m) => new m.SecureStorageWeb()),
+});
+export * from './definitions';
+export { SecureStorage };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,aAAa,GAAG,cAAc,CAAsB,eAAe,EAAE;IACzE,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAC;CACjE,CAAC,CAAC;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/esm/web.d.ts

@@ -0,0 +1,27 @@
+import { WebPlugin } from '@capacitor/core';
+import type { SecureStoragePlugin } from './definitions';
+/**
+ * The web has no secure storage facility. Rather than silently falling back to
+ * localStorage (which would be a security vulnerability), every method rejects
+ * with an `UNAVAILABLE` error.
+ */
+export declare class SecureStorageWeb extends WebPlugin implements SecureStoragePlugin {
+    set(_options: {
+        key: string;
+        value: string;
+    }): Promise<void>;
+    get(_options: {
+        key: string;
+    }): Promise<{
+        value: string | null;
+    }>;
+    has(_options: {
+        key: string;
+    }): Promise<{
+        value: boolean;
+    }>;
+    remove(_options: {
+        key: string;
+    }): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/esm/web.js

@@ -0,0 +1,24 @@
+import { WebPlugin } from '@capacitor/core';
+/**
+ * The web has no secure storage facility. Rather than silently falling back to
+ * localStorage (which would be a security vulnerability), every method rejects
+ * with an `UNAVAILABLE` error.
+ */
+export class SecureStorageWeb extends WebPlugin {
+    async set(_options) {
+        throw this.unavailable('SecureStorage is not supported on the web');
+    }
+    async get(_options) {
+        throw this.unavailable('SecureStorage is not supported on the web');
+    }
+    async has(_options) {
+        throw this.unavailable('SecureStorage is not supported on the web');
+    }
+    async remove(_options) {
+        throw this.unavailable('SecureStorage is not supported on the web');
+    }
+    async clear() {
+        throw this.unavailable('SecureStorage is not supported on the web');
+    }
+}
+//# sourceMappingURL=web.js.map

package/dist/esm/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC7C,KAAK,CAAC,GAAG,CAAC,QAAwC;QAChD,MAAM,IAAI,CAAC,WAAW,CAAC,2CAA2C,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAyB;QACjC,MAAM,IAAI,CAAC,WAAW,CAAC,2CAA2C,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAyB;QACjC,MAAM,IAAI,CAAC,WAAW,CAAC,2CAA2C,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAyB;QACpC,MAAM,IAAI,CAAC,WAAW,CAAC,2CAA2C,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,WAAW,CAAC,2CAA2C,CAAC,CAAC;IACtE,CAAC;CACF"}

package/ios/Sources/SecureStoragePlugin/KeychainStore.swift

@@ -0,0 +1,120 @@
+import Foundation
+import Security
+
+/// Thin wrapper around Keychain Services (generic password items).
+///
+/// Every item is scoped to a dedicated `kSecAttrService`, so `clear()` can never touch
+/// unrelated Keychain entries. Items use `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
+/// and are never synchronized through iCloud Keychain. Values are never logged.
+final class KeychainStore {
+    static let defaultService = "capacitor-secure-storage"
+    static let maxKeyBytes = 256
+
+    private let service: String
+
+    init(service: String = KeychainStore.defaultService) {
+        self.service = service
+    }
+
+    static func validate(key: String?) throws -> String {
+        guard let key = key, !key.isEmpty else {
+            throw SecureStorageError.invalidKey("Key must be a non-empty string")
+        }
+        guard key.utf8.count <= maxKeyBytes else {
+            throw SecureStorageError.invalidKey("Key must be at most \(maxKeyBytes) bytes")
+        }
+        return key
+    }
+
+    /// Base query identifying this plugin's items (optionally a single account).
+    private func baseQuery(account: String? = nil) -> [String: Any] {
+        var query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            // Match any sync state so remove()/clear() also catch items synced by older versions.
+            kSecAttrSynchronizable as String: kSecAttrSynchronizableAny
+        ]
+        if let account = account {
+            query[kSecAttrAccount as String] = account
+        }
+        return query
+    }
+
+    func set(_ value: String, for key: String) throws {
+        let data = Data(value.utf8)
+        let updateStatus = SecItemUpdate(
+            baseQuery(account: key) as CFDictionary,
+            [kSecValueData as String: data] as CFDictionary
+        )
+        switch updateStatus {
+        case errSecSuccess:
+            return
+        case errSecItemNotFound:
+            var attributes = baseQuery(account: key)
+            attributes[kSecValueData as String] = data
+            attributes[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+            // Replace the "any" match with an explicit non-synchronizable attribute.
+            attributes[kSecAttrSynchronizable as String] = kCFBooleanFalse
+            let addStatus = SecItemAdd(attributes as CFDictionary, nil)
+            if addStatus == errSecDuplicateItem {
+                // Lost a race with a concurrent set(); the item now exists, so update it.
+                let retry = SecItemUpdate(
+                    baseQuery(account: key) as CFDictionary,
+                    [kSecValueData as String: data] as CFDictionary
+                )
+                guard retry == errSecSuccess else { throw SecureStorageError.keychain(retry) }
+            } else if addStatus != errSecSuccess {
+                throw SecureStorageError.keychain(addStatus)
+            }
+        default:
+            throw SecureStorageError.keychain(updateStatus)
+        }
+    }
+
+    /// Returns nil if the key does not exist.
+    func get(_ key: String) throws -> String? {
+        var query = baseQuery(account: key)
+        query[kSecReturnData as String] = kCFBooleanTrue
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        switch status {
+        case errSecSuccess:
+            guard let data = result as? Data, let string = String(data: data, encoding: .utf8) else {
+                throw SecureStorageError.invalidValue("Stored value is not valid UTF-8")
+            }
+            return string
+        case errSecItemNotFound:
+            return nil
+        default:
+            throw SecureStorageError.keychain(status)
+        }
+    }
+
+    func has(_ key: String) throws -> Bool {
+        var query = baseQuery(account: key)
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        let status = SecItemCopyMatching(query as CFDictionary, nil)
+        switch status {
+        case errSecSuccess: return true
+        case errSecItemNotFound: return false
+        default: throw SecureStorageError.keychain(status)
+        }
+    }
+
+    /// A missing key is not an error.
+    func remove(_ key: String) throws {
+        let status = SecItemDelete(baseQuery(account: key) as CFDictionary)
+        guard status == errSecSuccess || status == errSecItemNotFound else {
+            throw SecureStorageError.keychain(status)
+        }
+    }
+
+    /// Deletes only items belonging to this store's service.
+    func clear() throws {
+        let status = SecItemDelete(baseQuery() as CFDictionary)
+        guard status == errSecSuccess || status == errSecItemNotFound else {
+            throw SecureStorageError.keychain(status)
+        }
+    }
+}

package/ios/Sources/SecureStoragePlugin/SecureStorageError.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+/// Plugin errors with stable codes and safe messages.
+/// Messages never contain secret values, keys' contents or Keychain item data.
+enum SecureStorageError: Error, Equatable {
+    case invalidKey(String)
+    case invalidValue(String)
+    case keychain(OSStatus)
+
+    var code: String {
+        switch self {
+        case .invalidKey: return "INVALID_KEY"
+        case .invalidValue: return "INVALID_VALUE"
+        case .keychain: return "KEYCHAIN_ERROR"
+        }
+    }
+
+    var message: String {
+        switch self {
+        case .invalidKey(let reason), .invalidValue(let reason):
+            return reason
+        case .keychain(let status):
+            // Only the numeric OSStatus is exposed; it carries no sensitive data.
+            return "Keychain operation failed (OSStatus \(status))"
+        }
+    }
+}

package/ios/Sources/SecureStoragePlugin/SecureStoragePlugin.swift

@@ -0,0 +1,73 @@
+import Capacitor
+import Foundation
+
+@objc(SecureStoragePlugin)
+public class SecureStoragePlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "SecureStoragePlugin"
+    public let jsName = "SecureStorage"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "set", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "get", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "has", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "remove", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise)
+    ]
+
+    private let store = KeychainStore()
+    // Keychain calls are thread-safe; a concurrent queue keeps them off the main thread
+    // without serializing unrelated operations.
+    private let queue = DispatchQueue(label: "capacitor-secure-storage", qos: .userInitiated, attributes: .concurrent)
+
+    @objc func set(_ call: CAPPluginCall) {
+        run(call) { [store] in
+            let key = try KeychainStore.validate(key: call.getString("key"))
+            guard let value = call.getString("value") else {
+                throw SecureStorageError.invalidValue("Value must be a string")
+            }
+            try store.set(value, for: key)
+            call.resolve()
+        }
+    }
+
+    @objc func get(_ call: CAPPluginCall) {
+        run(call) { [store] in
+            let key = try KeychainStore.validate(key: call.getString("key"))
+            let value = try store.get(key)
+            call.resolve(["value": value ?? NSNull()])
+        }
+    }
+
+    @objc func has(_ call: CAPPluginCall) {
+        run(call) { [store] in
+            let key = try KeychainStore.validate(key: call.getString("key"))
+            call.resolve(["value": try store.has(key)])
+        }
+    }
+
+    @objc func remove(_ call: CAPPluginCall) {
+        run(call) { [store] in
+            let key = try KeychainStore.validate(key: call.getString("key"))
+            try store.remove(key)
+            call.resolve()
+        }
+    }
+
+    @objc func clear(_ call: CAPPluginCall) {
+        run(call) { [store] in
+            try store.clear()
+            call.resolve()
+        }
+    }
+
+    private func run(_ call: CAPPluginCall, _ work: @escaping () throws -> Void) {
+        queue.async {
+            do {
+                try work()
+            } catch let error as SecureStorageError {
+                call.reject(error.message, error.code)
+            } catch {
+                call.reject("Unexpected storage error", "STORAGE_ERROR")
+            }
+        }
+    }
+}

package/ios/Tests/SecureStoragePluginTests/KeychainStoreTests.swift

@@ -0,0 +1,99 @@
+import Security
+import XCTest
+@testable import SecureStoragePlugin
+
+final class KeychainStoreTests: XCTestCase {
+    private let service = "capacitor-secure-storage-tests"
+    private var store: KeychainStore!
+
+    override func setUpWithError() throws {
+        store = KeychainStore(service: service)
+        try store.clear()
+    }
+
+    override func tearDownWithError() throws {
+        try store.clear()
+    }
+
+    func testSetGetHasRemove() throws {
+        try store.set("secret-value", for: "access_token")
+        XCTAssertEqual(try store.get("access_token"), "secret-value")
+        XCTAssertTrue(try store.has("access_token"))
+        try store.remove("access_token")
+        XCTAssertNil(try store.get("access_token"))
+        XCTAssertFalse(try store.has("access_token"))
+        XCTAssertNoThrow(try store.remove("access_token"))
+    }
+
+    func testOverwrite() throws {
+        try store.set("one", for: "k")
+        try store.set("two", for: "k")
+        XCTAssertEqual(try store.get("k"), "two")
+    }
+
+    func testMissingKey() throws {
+        XCTAssertNil(try store.get("missing"))
+    }
+
+    func testUnicodeEmojiEmptyAndNullBytes() throws {
+        try store.set("значение 🙂 日本語", for: "ключ-🔑")
+        XCTAssertEqual(try store.get("ключ-🔑"), "значение 🙂 日本語")
+        try store.set("", for: "empty")
+        XCTAssertEqual(try store.get("empty"), "")
+        try store.set("a\u{0}b", for: "nul")
+        XCTAssertEqual(try store.get("nul"), "a\u{0}b")
+    }
+
+    func testPersistsAcrossInstances() throws {
+        try store.set("v", for: "k")
+        XCTAssertEqual(try KeychainStore(service: service).get("k"), "v")
+    }
+
+    func testClearOnlyAffectsOwnService() throws {
+        let other = KeychainStore(service: service + ".other")
+        try other.clear()
+        try store.set("1", for: "a")
+        try other.set("2", for: "a")
+        try store.clear()
+        XCTAssertNil(try store.get("a"))
+        XCTAssertEqual(try other.get("a"), "2")
+        try other.clear()
+    }
+
+    func testStoredInKeychainWithDeviceOnlyAccessibility() throws {
+        try store.set("v", for: "k")
+        let query: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: "k",
+            kSecReturnAttributes as String: true,
+            kSecMatchLimit as String: kSecMatchLimitOne
+        ]
+        var result: CFTypeRef?
+        XCTAssertEqual(SecItemCopyMatching(query as CFDictionary, &result), errSecSuccess)
+        let attributes = result as? [String: Any]
+        XCTAssertEqual(attributes?[kSecAttrAccessible as String] as? String,
+                       kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly as String)
+    }
+
+    func testDoesNotUseUserDefaults() throws {
+        try store.set("plain-secret-check", for: "ud")
+        let dump = UserDefaults.standard.dictionaryRepresentation().description
+        XCTAssertFalse(dump.contains("plain-secret-check"))
+    }
+
+    func testKeyValidation() {
+        XCTAssertThrowsError(try KeychainStore.validate(key: "")) {
+            XCTAssertEqual(($0 as? SecureStorageError)?.code, "INVALID_KEY")
+        }
+        XCTAssertThrowsError(try KeychainStore.validate(key: nil))
+        XCTAssertThrowsError(try KeychainStore.validate(key: String(repeating: "a", count: 257)))
+        XCTAssertNoThrow(try KeychainStore.validate(key: "ключ-🔑"))
+    }
+
+    func testKeychainErrorMessageIsSafe() {
+        let error = SecureStorageError.keychain(errSecAuthFailed)
+        XCTAssertEqual(error.code, "KEYCHAIN_ERROR")
+        XCTAssertFalse(error.message.isEmpty)
+    }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@capnative/capacitor-secure-storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "8.0.0",
+  "description": "Secure key-value storage for Capacitor using iOS Keychain and Android Keystore (AES-GCM).",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "ios/Sources",
+    "ios/Tests",
+    "Package.swift",
+    "CapacitorSecureStorage.podspec"
+  ],
+  "author": "marioshtika",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marioshtika/capacitor-secure-storage.git"
+  },
+  "keywords": [
+    "capacitor",
+    "plugin",
+    "native",
+    "secure-storage",
+    "keychain",
+    "keystore"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "verify:ios": "swift build && swift test",
+    "verify:android": "cd android && gradle clean build test",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@capacitor/android": "^8.0.0",
+    "@capacitor/core": "^8.0.0",
+    "@capacitor/ios": "^8.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": ">=8.0.0"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  }
+}