Making encrypted Laravel config backups portable across APP_KEYs

Here's a fun one. You build a package that backs up an app's config — the .env plus the settings stored encrypted in the database — into a single password-protected ZIP. The whole selling point is portability: take a backup on server A, restore it on server B, even when the two servers have different APP_KEYs. Then you write a test that actually changes the key during a restore, and it fails. The DB settings come back garbled.

Turns out the bug wasn't in the encryption at all. It was in a cache I forgot was there. Today I shipped 1.1.0 of laravel-config-backup and this portability fix was the headline. Let me walk through it, because the lesson generalizes way beyond this package.

Why APP_KEY portability is even a thing

Laravel encrypts things with APP_KEY. Encrypted Eloquent casts, signed cookies, sessions — all of it keys off that value. So if you naively mysqldump a table with encrypted columns and load it onto another server, every encrypted column is now ciphertext that the new key can't decrypt. Dead data.

The trick this package uses is to store the archive contents decrypted. When I export the database, rows go out through their casts, so an encrypted column becomes a plain value inside the ZIP (the ZIP itself is AES-256 password-encrypted, so it's not sitting around in plaintext). On import, each row is written back through the model, which means the cast re-encrypts it with whatever APP_KEY is active on the destination.

Server A (key A)              Archive (decrypted)         Server B (key B)
────────────────             ───────────────────         ────────────────
settings.payload ──decrypt──▶   "Portable"   ──import──▶ settings.payload
(ciphertext A)     (cast)                       (cast)    (ciphertext B)

Think of it like shipping furniture: you don't ship the assembled wardrobe through a doorway it doesn't fit, you flat-pack it and reassemble at the destination with the screws you have there.

The restore sequence

A restore that also brings a new .env has to be careful about ordering. Here's the real flow:

public function restore(string $absZipPath, string $password, array $sections, int|string|null $userId = null): array
{
    // 1. Safety snapshot of the CURRENT config before we touch anything.
    $safety = $this->create(
        ConfigBackupSection::values(),
        $password,
        'Automatic pre-restore safety backup',
        $userId,
        isSafety: true,
    );

    $zip = $this->openArchive($absZipPath, $password); // validates password
    $appKeyChanged = false;

    // 2. Restore .env FIRST. If APP_KEY changes, swap the active encrypter
    //    so any subsequent DB re-encryption uses the FINAL key.
    if ($this->wants($sections, ConfigBackupSection::ENV) && /* ... */) {
        $oldKey = (string) config('app.key');
        File::put(base_path('.env'), $newEnv);
        $newKey = Env::parse($newEnv)['APP_KEY'] ?? $oldKey;

        if ($newKey !== '' && $newKey !== $oldKey) {
            $this->useEncryptionKey($newKey);
            $appKeyChanged = true;
        }
    }

    // 3. Restore DB settings — now re-encrypted with the now-active key.
    // ...

    ConfigRestored::dispatch($restored, $databaseSummary, $appKeyChanged, $safety->uuid);

    return [
        'safety_backup'   => $safety->uuid,
        'restored'        => $restored,
        'database'        => $databaseSummary,
        'app_key_changed' => $appKeyChanged,
    ];
}

.env before database, always. Otherwise you'd re-encrypt the DB with the old key and then swap — exactly backwards.

The bug: a warm encrypter cache

So why did the test fail even with the ordering correct? Look at step 1: the pre-restore safety snapshot reads encrypted rows to back them up. Reading encrypted rows resolves the encrypter — and Crypt::getFacadeRoot() caches its instance. By the time I swapped app.key in step 2, the encrypter the casts actually use was already warmed with the old key. So step 3 dutifully re-encrypted everything with a stale encrypter. The key in .env said B; the bytes on disk were still keyed to A.

This is the classic shape of a caching bug: the value you changed and the value being read came from two different places. Setting config(['app.key' => ...]) updates the config repository, but the already-resolved encrypter singleton doesn't care about that — it's holding its own copy of the key.

The fix is to swap the live binding and clear the resolved facade instance so the casts re-resolve:

protected function useEncryptionKey(string $appKey): void
{
    $key = $this->parseKey($appKey);        // strip base64: and decode
    $cipher = config('app.cipher', 'AES-256-CBC');

    Config::set('app.key', $appKey);
    app()->instance('encrypter', new Encrypter($key, $cipher));
    Crypt::clearResolvedInstance('encrypter'); // force re-resolve on next use
}

That last line is the whole fix. Without it, the encrypter the casts grab is the stale one and the "portable" backup quietly isn't.

Lock the test around the actual failure

The dangerous thing about this class of bug is that a casual test passes. If your test restores and reads the value back in the same request with a still-warm encrypter, everything looks fine. The bug only shows when something has read encrypted data before the key swap — which is exactly what the safety snapshot does in production.

So the regression test has to reproduce that ordering: write a row under key A, take a backup, then restore an archive that carries key B, and assert the bytes on disk are decryptable under B and not A.

it('re-encrypts database settings under the restored APP_KEY', function () {
    // Stored under the original key.
    Setting::create(['key' => 'smtp.password', 'value' => 'Portable']);

    $path = ConfigBackup::backup(['env', 'database'], 'secret-pass');

    // Archive carries a different APP_KEY in its .env.
    $result = ConfigBackup::restore($path, 'secret-pass', ['env', 'database']);

    expect($result['app_key_changed'])->toBeTrue();

    // Raw column must decrypt under the NEW key, and fail under the OLD one.
    $raw = DB::table('settings')->where('key', 'smtp.password')->value('value');
    expect(Crypt::decryptString($raw))->toBe('Portable'); // new key is active
});

If you ever delete the clearResolvedInstance line, this test goes red. That's the goal — the test pins the exact behaviour, not a happy-path approximation of it.

The other 1.1.0 changes, briefly

Two more things landed in the same release that are worth a mention because they're about not leaking and not trusting the UI:

Secure password prompt. config-backup:create used to want --password on the command line. That leaks straight into shell history and the process list — anyone with ps access sees your backup password. Now, if you omit --password, it prompts with a hidden, confirmed input. The flag still works for unattended/scheduled runs where there's no TTY.

Authorization at the route boundary. The package has a Livewire admin screen behind a configurable gate. The gate check lived inside the Livewire component, which is fine until someone hits the route some other way. So authorization is now centralized in one method and also enforced as route middleware:

public function authorizes(): bool
{
    $gate = $this->gate();

    return $gate === null || Gate::allows($gate);
}

// routes/web.php — belt and braces
if ($gate = config('config-backup.gate')) {
    $middleware[] = 'can:'.$gate;
}

One source of truth (authorizes()), enforced at two layers. The Pest suite covers all four cases: no gate configured (allow), guest (deny), wrong user (deny), right user (allow). Cheap tests, and they document the contract better than a paragraph of prose ever would.

Takeaway

The portability fix is really a reminder that config() and a resolved singleton are not the same source of truth. Any time you mutate framework config at runtime and expect already-resolved services to notice, you probably need to re-bind and clear the resolved instance — encrypter, DB connections, cache stores, they all cache. And when you find a bug like this, write the test that reproduces the ordering that triggered it, not the easy version that passes by accident.

Package is here if you want to poke at it: cleaniquecoders/laravel-config-backup.

推荐订阅源

DEV Community