Encrypted Capacitor Service Log with SQLite SEE

This runnable Capacitor application demonstrates encrypted offline storage with the published @sqlite-encrypted/cordova package and the official SQLite Encryption Extension (SEE). It records customer service visits with create, search, update, and delete operations on Android and iOS.

This example uses SQLite SEE. It does not use SQLCipher.

What the application demonstrates

• Using the SQLite.Encrypted Cordova package from a Capacitor application.
• Validating SEE activation before opening application data.
• Opening with the keyed openDatabase API rather than a URI parameter.
• Reading sqlite_master before schema creation to reject a wrong passphrase.
• Running parameterized encrypted CRUD and search through the familiar Cordova API.
• Keeping the database passphrase in memory instead of persisting it in web storage.

Prerequisites

• Node.js 22 or newer.
• Android Studio for Android, or Xcode on macOS for iOS.
• A licensed SEE activation key.

Free fully-featured demo keys are available from sqlite.sourcegear.com.

Install

The checked-in .npmrc directs the @sqlite-encrypted scope to the SQLite.Encrypted package repository. Install the JavaScript dependencies:

npm install

Set the activation key before building. Supply the hexadecimal value without the see- prefix:

$env:SQLITE_ENCRYPTED_ACTIVATION_KEY = '<activation key>'

On macOS or Linux:

export SQLITE_ENCRYPTED_ACTIVATION_KEY='<activation key>'

The build script injects the key into the generated dist/js/config.js; the generated dist directory is ignored by Git. Like other client application configuration, the activation key is present in the compiled application. Choose an activation-key delivery and application-protection strategy suitable for your SEE license and production threat model.

Run on Android

Create the native project once:

npm run add:android

Then synchronize and open Android Studio:

npm run android

For later web-code changes, repeat npm run android. The script rebuilds the web assets and runs cap sync android before opening the project.

Run on iOS

On macOS, create the native project once and open Xcode:

npm run add:ios
npm run ios

Encryption flow

When Capacitor fires deviceready, the sample:

1. Rejects a missing or malformed activation-key configuration.
2. Calls sqlitePlugin.activateSEE.
3. Opens a temporary database and calls its explicit key() method. If key loading fails, the UI reports an activation-specific error and requires an application restart because SEE activation is process-global.
4. Opens encrypted-service-log.db with the keyed openDatabase overload.
5. Reads sqlite_master before creating or querying the application schema.

The database passphrase entered in the unlock screen is held only in memory. It is not written to localStorage, Capacitor Preferences, or the database.

Project layout

www/js/database.js   SEE activation, encrypted open, schema, and CRUD
www/js/app.js        Service-log workflow and DOM UI
scripts/build.mjs    Copies web assets and injects the activation key
capacitor.config.json

The android/ and ios/ directories are generated by Capacitor and intentionally ignored. Recreate them with npm run add:android or npm run add:ios.