Address #128 review: unopenable journals, repository binding, and the node:sqlite guard

[Jberma23]

What this does

Follow-ups to #128 from reviewing it, targeted at that branch rather than main so the foundation lands with these already in it. Three commits, one concern each.

1. Handle a journal no key can open, and close it when locking — two gaps between what 0015 decided and what the code does.

0015 keeps the key WHEN_UNLOCKED_THIS_DEVICE_ONLY precisely so it does not travel in an iCloud backup — but journal.db lives in Documents and does. Restoring a backup onto a new phone brings the file back without the key. Nothing handled that: SecureStore returns null both for "nothing stored yet" and for "the entry was invalidated", key.ts read null as a first run and minted a fresh key, and database.ts asked for the key before opening the file so it could not know better. The result was a generic Could not open the journal database on that launch and every launch after, with no explanation and nowhere to go — from the ordinary act of replacing a handset.

getOrCreateDatabaseKey now reports whether it minted the key. A key we just created cannot fail to read a file we just created, so a failed decrypt on a fresh key means the file predates it. That is now UnrecoverableJournalError, and the useless key is deleted so the next launch reaches the same branch instead of degrading to something undiagnosable. The journal really is gone — 0007 commits to saying so during onboarding — but "made on a different phone" is true and leaves the user somewhere to go. The UI for starting over isn't built; this is the mechanism it needs.

Separately, the unlock gate locked the view and nothing else: database.ts held a decrypted handle and the key stayed in memory for the life of the process, which made WHEN_UNLOCKED_THIS_DEVICE_ONLY a property of the first launch and nothing after it, since the keychain was never asked again. The gate now closes the database on the same background event that re-locks.

Also corrects two comments in key.ts that were wrong rather than thin: keychainAccessible is iOS-only, so the Google-backup half of that claim comes from the config plugin's backup rules (which makes the bare plugin entry in app.json load-bearing); and WHEN_PASSCODE_SET_THIS_DEVICE_ONLY is recorded as considered-and-rejected, because it looks like a free upgrade but cannot store a key at all on the devices 0018 is about.

2. Fix repository update() binding and create() return value — update reached find through this, so const { update } = repo and onPress={repo.update} both threw TypeError at runtime, uncaught by TypeScript. And create() built its return from the caller's input, so an omitted field was stored as NULL but returned absent, and keys that were never columns were echoed back looking saved.

3. Make the node:sqlite guard actually run — the static import resolved before the try/catch could, so the guard never evaluated and the two SQLite suites errored instead of skipping on Node < 22.5.

Issue

Closes #134
Closes #133

Not closing #130 — the PRAGMA cipher_version guard is still outstanding; this only corrects the comment in database.ts that overstated what the sqlite_master probe catches.

Testing

• Covered by tests

cd mobile && npm test → 11 suites, 109 tests, all pass (95 before). npx tsc --noEmit and npm run lint both clean, on Node 22.20.0.

14 new tests. Five cover the orphaned-journal paths, including the two that must not fire: a decrypt failure against a stored key stays a generic error and does not delete the key, and a genuine first run is left alone. Three prove the repository defects, all of which I reproduced against the in-memory SQLite harness before fixing. Three more are a new suite for the jest helper itself — making the require throw is the only way to exercise the old-Node path from a new Node, and without it nothing in CI would notice #133 regressing, which is how it got here.

Still not tested anywhere: that the file is actually encrypted. That needs hardware — #101, and #130 for the build-flag half.

Notes for review

• getOrCreateDatabaseKey now returns { key, created } instead of a string. Breaking change to a public export, one consumer today. The alternative was splitting it into readDatabaseKey + createDatabaseKey; I preferred one atomic call that reports what it did.
• deleteDatabaseKey was mocked as a bare jest.fn() in database.test.ts, which returns undefined rather than a promise. Chaining .catch() onto it threw a TypeError that swallowed the real error and made three tests fail for a completely misleading reason. Given mockResolvedValue(undefined) with a comment — worth knowing about as a harness sharp edge, not just here.
• Deliberately left out: destroyJournalDatabase() can report success when the journal file was not deleted #135 (its feature doesn't exist yet and belongs with [FEATURE] "Delete all my data" in-app control #116) and Journal contents appear in the iOS app-switcher snapshot; unlock gate only re-locks on background #136 (needs a device). The incoherent file-before-key comment at database.ts:96-99 is untouched, since rewording it is tangled up with how destroyJournalDatabase() can report success when the journal file was not deleted #135 resolves the ordering.