Back to Blog
NativePHP Mobile 4.6: Your APP_KEY Moves Into the Android Keystore
NativePHP Mobile 4.6 encrypts the per-device APP_KEY with the Android Keystore, rotates the old plain-text key on first launch, and always strips APP_KEY from the bundled .env. Here is what changes and what to check before you ship.
Back
Engineering
Table of contents
NativePHP Mobile 4.6.0 (2 October 2026) moved the Android APP_KEY into the Keystore and stopped bundling the developer's key with the app. The release notes also shipped device rotation events and language support, but that keystore change is the line I keep coming back to.
The current version is 4.8.0 (14 November 2026). It adds more hardening on top of the 4.6 work, including a signed native-callback cache and a scoped Android web view bridge. If you are still on 4.6.x, upgrade to the latest rather than stopping at the minimum version that fixes the keystore.
That sounds like plumbing. It is plumbing. It is also the kind of plumbing that decides whether Crypt::encryptString() on a phone actually protects anything.
Quick Answer
Before 4.6, the Android shell wrote each device's APP_KEY as plain text to persisted_data/appkey.txt. iOS already used the Keychain. In 4.6, Android encrypts the key with an AES-GCM key held in the Android Keystore, migrates existing installs on first launch, and rotates the old key into APP_PREVIOUS_KEYS so old data still decrypts.
Separately, APP_KEY and APP_PREVIOUS_KEYS are now always removed from the .env that ships inside your app, on both platforms, whatever your cleanup_env_keys config says.
Upgrade, and if any of your older builds went out with your server's real APP_KEY in the bundled .env, treat that key as public.
Why the plain-text file mattered
NativePHP's own Security docs say the quiet part out loud: your Laravel app is bundled into the APK or IPA and extracted on the device, so anyone who unpacks the package can read it. The recommended defence is to treat the bundle as public and use per-device keys for anything you encrypt on the phone.
The point of on-device encryption, in the docs' words, is that if someone gets hold of your app's files or database, the sensitive values are unreadable without the key, "and the key is not stored alongside them."
A plain-text appkey.txt in the app's storage directory is, well, stored alongside them. My read: in most cases, whoever can copy the SQLite file can copy the key file sitting next to it. 4.6 closes that gap on Android so it matches what iOS was already doing.
What 4.6 actually does on Android
From the PR description and the code:
- A new
AppKeyStoreclass encrypts the key (and any previous keys) with an AES-256-GCM key that lives in the Android Keystore under the aliasnativephp_app_key. - The encrypted blob is saved in
noBackupFilesDir, so it is excluded from Auto Backup and device transfer. - On first launch after the upgrade, the old key is read from
appkey.txt, a fresh key is generated, the old one is passed to Laravel asAPP_PREVIOUS_KEYS, and the text file is deleted. - Any
bootstrap/cache/config.phpbuilt before the migration is deleted, because it would hold the old key in plain text. - After
config:cacheruns on the device, NativePHP stripsapp.keyandapp.previous_keysfrom the cached config and puts them back from the environment at runtime.
The rotation step is the clever part. Laravel's APP_PREVIOUS_KEYS (documented under "Gracefully Rotating Encryption Keys") makes the encrypter use the current key for new values and fall back to previous keys when decrypting. So existing encrypted data keeps working, and anything encrypted from now on uses a key that was never sitting on disk unprotected.
The bundled .env change applies to iOS too
This one is easy to miss. Up to 4.5.2, the .env cleanup only removed keys listed in cleanup_env_keys. The default list covers AWS_*, GITHUB_*, DO_SPACES_*, *_SECRET, DB_PASSWORD, and DB_USERNAME. It does not include APP_KEY.
In 4.6, APP_KEY and APP_PREVIOUS_KEYS are hard-coded into the cleanup step. The PR explains why they did not just add them to the default config: apps that already published config/nativephp.php would never pick up a new default.
The cleanup also got stricter about matching. It now catches export APP_KEY= lines and lines with leading spaces. That stricter matching applies to every key in cleanup_env_keys, not just the two new ones.
One behaviour change on iOS: with no key in the bundled .env, a Keychain failure now gives you a missing key error instead of quietly falling back to the developer's key. I would rather get the loud error.
Things to watch for
These are straight from the PR's "Things to watch for" section, and they are worth reading before you push an update to real users.
- Laravel 10 apps do not rotate.
APP_PREVIOUS_KEYSarrived in Laravel 11, so on Laravel 10 the old key is moved into the Keystore as it is. If you later move that app to Laravel 11, nothing goes back and rotates it. - Encrypted data does not survive a new phone. The store is excluded from backup and device transfer. That matches iOS and what the docs already promised, but if you were (accidentally) relying on Android backups carrying the key, that stops now.
- A missing or corrupted Keystore key means a new key. If the Keystore key is gone or the store fails authentication, NativePHP generates a fresh key and old encrypted data is lost. Any other Keystore error stops the boot instead of replacing the key.
- Test coverage has gaps. The PR was tested on an Android emulator with a Laravel 13 app and a debug build. The author lists release builds, real devices, the Laravel 10 path on a device, and a WorkManager cold start as not tested.
That last point is not a criticism. It is an honest PR, and it tells you exactly what to test yourself.
My Take
This is the right fix, and the rotation-on-migration design is better than I expected from a point release. Most frameworks would have just moved the key and called it done.
But the part I would act on today is not the Keystore. It is the .env.
If you built your NativePHP app by starting from an existing Laravel web project (the natural thing to try), there is a real chance your mobile .env had the same APP_KEY as your server. Before 4.6, unless you had added APP_KEY to cleanup_env_keys, that key could ship inside every APK and IPA you released.
That is my inference from the 4.5.2 cleanup code and the default config, not something the release notes claim. But the docs are clear that anything in the bundle should be treated as public. So:
- Unpack one of your released builds and look at the bundled
.env. Check forAPP_KEY. - If it matches a key your server uses, rotate the server key. Laravel's
APP_PREVIOUS_KEYSlets you do that gracefully: new values use the new key, and old values still decrypt with the previous one. - Give your mobile project its own
.envwith nothing in it you would not post publicly.
And keep following the docs' advice on what to encrypt on the device at all: short-lived tokens and data you can fetch again. Anything users expect to keep across phones belongs on your server.
Also in 4.6
OrientationChangedevent andSystem::orientation()for reacting to rotation from PHP- A new
supported_localesconfig key to declare which languages your app supports - Device thermal state and extra telemetry in device info
- Build a simulator app without a simulator running
- Plugin hook failures now surface instead of producing a broken app
- Android keystore passwords with special characters are no longer mangled
- WebP output for generated Android icons and splash screens
- iOS 26 fixes for toolbar hit-testing and top-bar backgrounds
One upgrade note from the official guide: if your iOS app relies on translated permission strings, add those locales to supported_locales. From 4.6, translated permission strings are only written for locales your app supports (plus config('app.locale')), and a config published before 4.6 will not have the key yet.
Upgrade
bash
composer update nativephp/mobile
php artisan native:install
php artisan native:runnative:install has to run after the composer update and before native:run so the native shell picks up the new package.
Target 4.8.0 or newer when you run composer update nativephp/mobile so you pick up the later security fixes, not only the 4.6 keystore behaviour this post focuses on.
Sources
Facts checked on 20 November 2026.
- NativePHP Mobile 4.6.0 release announcement (October 5, 2026)
- NativePHP mobile-air 4.6.0 GitHub release (October 2, 2026)
- NativePHP mobile-air 4.8.0 GitHub release (November 14, 2026)
- AppKeyStore.kt at 4.6.0
- PR #519: Store the Android APP_KEY in the Keystore and stop bundling the developer's key
- CleansEnvFile.php at 4.5.2 (pre-4.6 cleanup behaviour)
- config/nativephp.php at 4.6.0 (default
cleanup_env_keys) - NativePHP Mobile v4 Security docs
- NativePHP Mobile v4 Upgrade Guide
- Laravel 13.x Encryption docs: Gracefully Rotating Encryption Keys
Comments
No comments yet
Loading comments...