Refuse to open a journal on a build without SQLCipher

[Jberma23]

What this does

Adds the runtime guard half of #130: the app now refuses to open the journal on a build that has no SQLCipher, instead of silently writing a plaintext one.

PRAGMA key cannot tell you whether SQLCipher is present. SQLite ignores pragmas it does not recognise rather than erroring, so on a stock build the key statement is accepted and does nothing, the schema read after it succeeds against a plaintext file, and the app writes an unencrypted medical journal with no error, no warning, and nothing observable that distinguishes it from the encrypted case. Verified against stock SQLite:

PRAGMA key on plain SQLite: ACCEPTED SILENTLY (no error)
sqlite_master probe still works: {"c":0}
PRAGMA cipher_version -> null

That build is easy to be running. useSQLCipher is applied by a config plugin at prebuild, so Expo Go has never had it, and neither has a stale ios/ or android/ directory generated before the flag was set — and until #129 lands the README still tells contributors to use Expo Go.

PRAGMA cipher_version returns a version string on a SQLCipher build and no row on stock SQLite, which makes it the one cheap way to tell them apart. It asks the library rather than the database, so it is safe ahead of the key — and asking first means a build that cannot encrypt fails against an empty file rather than filling one with plaintext. The error names the remedy (npx expo prebuild + a development build), since whoever hits it is the person who most needs to read it.

0017 refuses an unencrypted fallback on web for exactly this reason: a silent downgrade makes the privacy promise untrue in the way nobody notices until it matters. This applies the same rule to a build that lost SQLCipher, and reports it as SQLCipherUnavailableError rather than a generic open failure — the problem is the binary, not the database, and "could not open the journal database" would send someone looking in the wrong place.

Issue

Addresses #130

Not closing it. #130 has two halves and this is only one: whether a SQLCipher build can read an unkeyed plaintext catalog.db still needs a device, and is untouched here.

Testing

• Covered by tests

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

Five new tests, mutation-checked: commenting out the assertSQLCipher call fails all five and nothing else, so they are genuinely load-bearing rather than passing by coincidence. They cover the refusal itself, that the check happens before PRAGMA key so nothing is written to the file, that the message names the remedy, that the handle is closed, and that it is not reported as a generic DatabaseUnavailableError.

Two existing ordering assertions became index-based casualties of inserting a statement — they now locate PRAGMA key rather than assuming position 0, which is what they actually meant.

Cannot be tested here: that a real SQLCipher build returns a version string. That is the device half of #130.

Notes for review

• Stacked on Address #128 review: unopenable journals, repository binding, and the node:sqlite guard #138, not on feature/encrypted-storage-unlock-foundation directly, and targeted at Address #128 review: unopenable journals, repository binding, and the node:sqlite guard #138's branch. Both PRs edit the same region of open(), so basing this on Paul's branch would have guaranteed a conflict. Merge Address #128 review: unopenable journals, repository binding, and the node:sqlite guard #138 first and this retargets cleanly; the diff here shows only its own commit.
• Ordering choice worth a look. getOrCreateDatabaseKey() still runs before openDatabaseAsync, so on a broken build a key is minted and stored before the guard fires. That is harmless — we throw before anything writes, so the file stays zero-length and a later correct build keys it normally — but the alternative was reordering, which breaks the existing "does not open the database if the key cannot be read" test. Happy to swap if reviewers prefer.

[PaulgSmith]

Looked at rebasing this onto main now that #128 has merged, and I don't think it should be — the fix landed with #128 already, in 37161a2 ("Detect a build with no SQLCipher, and stop destroy racing close"). Rebasing would mean reverting that to reinstate an earlier version of the same idea.

main's open() does the same thing this PR does, by the same mechanism:

async function assertEncrypted(db: SQLiteDatabase): Promise<void> {
  const row = await db.getFirstAsync<{ cipher_version?: string }>('PRAGMA cipher_version');
  if (!row?.cipher_version) {
    throw new DatabaseUnavailableError(
      'This build has no SQLCipher, so the journal would be stored unencrypted. Rebuild with `useSQLCipher` ...'
    );
  }
}

Same discriminator, same absence-is-the-signal reasoning, same remedy named in the message.

The test coverage on main is a superset of the five tests here. It has the refusal, the remedy in the message, the ordering guarantee, and the connection being closed — plus two this PR does not have: that a stored key is neither blamed nor deleted over a build misconfiguration, and an integration test that runs the real open path against real stock SQLite via node:sqlite, so PRAGMA key is accepted-and-ignored for real rather than because a mock was told to say so. That last one is the strongest evidence available off-device for exactly the build #130 describes.

Two differences are real but, I think, not worth reverting main for:

1. Ordering. This PR checks before PRAGMA key; main checks after. The stated rationale here was that a broken build should fail against an empty file rather than one filled with plaintext — but on stock SQLite PRAGMA key is an unrecognised pragma that writes nothing, and openDatabaseAsync has already created the (empty) file by then either way. So the outcomes are identical, and main's order preserves the "key is the first statement to touch the database" invariant, which is the more conservative choice on a build that does have SQLCipher.

2. Error type. This PR raises a distinct SQLCipherUnavailableError on the argument that the problem is the binary, not the database. main raises DatabaseUnavailableError with a message that names the binary and the remedy. That's a genuine design question and the argument here is decent — but nothing branches on the type today, so it's a refactor rather than a fix. If it's still wanted it's a small standalone PR, and easier to review as one.

So my suggestion is to close this as superseded rather than rebase it. #130 should stay open regardless: this only ever addressed half of it, and the other half — whether a SQLCipher build can read an unkeyed plaintext catalog.db — still needs a device and is untouched by anything on main.

Not closing it myself since it's your PR — say the word, or close it whenever suits.

[PaulgSmith]

Closing as superseded: the fix landed with #128 as commit 37161a2, and main's version is a superset of this one (see the analysis above).

Leaving #130 open — this only ever addressed half of it, and the other half (whether a SQLCipher build can read an unkeyed plaintext catalog.db) still needs a device.

The branch is not deleted, so nothing here is lost if the SQLCipherUnavailableError idea is worth picking up as its own PR later.