projectmata/mobile-secure-storage

Custom secure storage plugin for NativePHP Mobile

v1.0.0 2026-04-25 04:10 UTC

Requires

• php: ^8.1

MIT

README

Encrypted key-value storage plugin for NativePHP Mobile. Backed by Android Keystore AES-GCM encryption and iOS Keychain.

Use it for API tokens, refresh tokens, small credentials, or any small string you don't want sitting in plain SharedPreferences / UserDefaults.

Requirements

• PHP ^8.1
• Laravel ^11.0 or ^12.0 / ^13.0
• nativephp/mobile
• Android: min_version 33
• iOS: min_version 18.2

Installation

composer require projectmata/mobile-secure-storage

Laravel auto-discovery registers the service provider and facade automatically.

Rebuild the mobile app so the native plugin is bundled:

php artisan native:run android
# or
php artisan native:run ios

Usage

PHP (Laravel)

use Projectmata\MobileSecureStorage\Facades\SecureStorage;

SecureStorage::setItem('auth_token', $token);

$token = SecureStorage::getItem('auth_token');
// ['success' => true, 'value' => '...'] or ['success' => true, 'value' => null] if missing

SecureStorage::removeItem('auth_token');

SecureStorage::clear(); // wipe every key this app has stored

JavaScript (in-app)

The plugin registers itself on window.NativePHP.SecureStorage:

await window.NativePHP.SecureStorage.SetItem({ key: 'auth_token', value: token });

const { value } = await window.NativePHP.SecureStorage.GetItem({ key: 'auth_token' });

await window.NativePHP.SecureStorage.RemoveItem({ key: 'auth_token' });

await window.NativePHP.SecureStorage.Clear();

Or as a bundled import:

import SecureStorage, { setItem, getItem } from 'projectmata-mobile-secure-storage';

Bridge methods

Method	Params	Returns
SecureStorage.SetItem	{ key, value }	{ success }
SecureStorage.GetItem	{ key }	{ success, value | null }
SecureStorage.RemoveItem	{ key }	{ success }
SecureStorage.Clear	—	{ success }

Platform notes

• Android — Values are AES-256-GCM encrypted with a key stored in the Android Keystore. Values persist across app launches but are cleared if the app is uninstalled.
• iOS — Values are stored in the Keychain with kSecAttrAccessibleAfterFirstUnlock. They survive app reinstalls unless you explicitly clear them (Keychain is not tied to the app sandbox in the same way as Android).
• clear() only removes keys set by this plugin; it will not touch other Keychain / SharedPreferences entries.

Security caveats

Secure storage protects at rest on a non-rooted / non-jailbroken device. It is not a substitute for:

• Short-lived / rotating tokens on the server side.
• TLS for data in transit.
• App-level auth gating (see projectmata/mobile-biometrics) for high-value actions.

License

MIT