[reklov]

Second of two branches from the kupferdraht comparison. The first, #8, hardened the client against values from the server; this one closes the weak form of kupferdraht's ADR-0042 gap: a build that meant to encrypt and silently did not.

The gap

With plain SQLite the server stores plaintext, as the README says. A build that meant to link SQLCipher and linked plain SQLite instead gets exactly that: PRAGMA key is an unknown pragma there and is ignored, and the VFS sends the pages as they are, without an error. Opening through encrypted_name() is safe from it, because multipleciphers-<name> exists only with SQLite3 Multiple Ciphers. Opening through name(), the SQLCipher path, is not.

What changes

• Config::refuse_plaintext, off by default. When set, the VFS refuses a read or a write of page 1 that carries an unencrypted SQLite header. SQLite gets SQLITE_PERM, a write transaction rolls back before anything reaches the server, and RemoteVfs::failure() reports the new Failure::Plaintext. The read side makes a database the server already holds in plaintext noticeable.
• Detection (vfs.rs): magic string at 0, the fixed bytes 64/32/32 at 21, and the 20 reserved zero bytes from 72. Checked against the SQLite3 Multiple Ciphers sources in vendor/: the default ciphers replace the magic with a salt, the others encrypt from byte 24 on at the latest (CIPHER_PAGE1_OFFSET), and SQLCipher's cipher_plaintext_header_size of 32 still leaves the reserved bytes encrypted. Only a plaintext header of 96 bytes or more would pass as plaintext.
• C interface: refuse_plaintext at the end of sqlite_remote_vfs_config. A program built against the 0.5.0 header passes the smaller struct_size and is accepted with the default. The registration now copies struct_size bytes into a zeroed struct instead of referencing the caller's struct as a whole, which would be undefined for the shorter one. The layout test in extension/ covers the field.
• Default stays off: the README documents plain SQLite as a mode, the extension workspace tests with it, and kupferdraht opens through encrypted_name() and needs no guard. Config gains a public field; constructors such as Config::new and Config::server set it, struct literals need the field.

Tests

• Unit: the detector on a plain page 1 (full page and the 100-byte header read), on salted, from-24-encrypted, 32-byte-plaintext-header and fully encrypted variants, on other pages and zero pages.
• Integration (need a server, run in CI): an encrypted database passes with the guard on; the first commit of an unencrypted one fails with SQLITE_PERM and a second VFS sees an empty database on the server; a database stored in plaintext fails on read; plain SQLite through the static C interface is refused; the 0.5.0 struct size is accepted.

Verified locally: cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, the same in extension/ and on wasm32-unknown-unknown in browser/, cargo test --workspace, the extension workspace's tests including the C layout test, cargo doc with -D warnings. The integration tests against a server ran only in CI, there is no Go toolchain on this machine.

🤖 Generated with Claude Code

[mtrossbach]

Thanks, the detection and the C ABI handling look solid. I pushed one documentation commit on top (a955f37):

Plaintext header limit. The check relies on the reserved bytes 72–91 of page 1 being encrypted. SQLite3 Multiple Ciphers allows plaintext_header_size up to 100 for its ciphers, the default ChaCha20 included (SQLCipher: multiples of 16). With more than 72 bytes, page 1 of an encrypted database can pass as plaintext by chance, from 92 bytes on it always does. Config::refuse_plaintext, the C header and the README now say so, and a unit test holds the limit (72 passes as encrypted, 92 is detected as plaintext).

Empty key. With SQLite3 Multiple Ciphers, PRAGMA key with an empty key attaches no cipher, so it writes plaintext without an error (sqlite3mcCodecAttach, nKey <= 0). For us, opening through encrypted_name(), that and a forgotten key are the cases the guard catches; the README names the empty key now.

For the release: Config gains a public field, so struct literals break. The next version should be 0.6.0.

🤖 Generated with Claude Code