@aiao/rxdb-adapter-encrypted

Local field-level AES-GCM-256 envelope encryption for @aiao/rxdb. Plugs into the SQLite-core / PGlite / wa-sqlite / sqliteai adapters with zero-plaintext-at-rest guarantees on the structural database files, change log, query cache and history snapshots.

Install

pnpm add @aiao/rxdb-adapter-encrypted

Peer of any local SQLite-family adapter (@aiao/rxdb-adapter-wa-sqlite, @aiao/rxdb-adapter-pglite, @aiao/rxdb-adapter-sqlite-wasm, @aiao/rxdb-adapter-sqliteai). Not needed for Supabase or remote-only adapters.

Quickstart

import { Entity, Property, PropertyType } from '@aiao/rxdb';
import { WaSqliteAdapter } from '@aiao/rxdb-adapter-wa-sqlite';
import { RxDB } from '@aiao/rxdb';

@Entity({ tableName: 'users' })
class User {
  @Property({ primaryKey: true }) id!: string;
  @Property({ propertyType: PropertyType.STRING }) displayName!: string;

  @Property({ propertyType: PropertyType.STRING, encrypted: true })
  email!: string;
}

const adapter = await WaSqliteAdapter.create({ name: 'app.db' });
const db = await RxDB.create({ adapter, entities: [User] });

await adapter.encryption.unlock({
  passphrase: 'correct horse battery staple'
  // idleTimeoutMs: 10 * 60_000  // override default 5-minute auto-lock
  // idleTimeoutMs: 0            // disable auto-lock
});

await db.repository(User).create({
  id: 'u1',
  displayName: 'Ada',
  email: '[email protected]' // encrypted at rest
});

Public API

import {
  // Keyring lifecycle
  Keyring,
  createKeyring,
  type UnlockOptions,
  type PassphraseUnlockOptions,
  type KeyBytesUnlockOptions,
  type CryptoKeyUnlockOptions,
  type KeyProviderUnlockOptions,

  // Envelope codec
  encodeEnvelope,
  decodeEnvelope,
  isEnvelope,
  buildAAD,
  ENVELOPE_VERSION,
  ENVELOPE_ALG,
  type CryptoEnvelope,
  type EnvelopeVersion,

  // Schema + query validators
  validateEncryptedPropertyMetadata,
  validateFTSRegistrationAgainstEncryptedColumns,
  validateQueryAgainstEncryptedColumns,
  type EncryptedAwareEntity,

  // Typed errors
  EncryptedError,
  EncryptedConfigurationError,
  EncryptedDecryptError,
  EncryptedLockedError,
  EncryptedQueryError,
  EncryptedUnlockError,
  type EncryptedErrorCode,
  type EncryptedErrorInit,

  // Keyring persistence binding
  type KeyringRow,
  type KeyringStorageBinding,

  // Verifier sentinel constant
  VERIFIER_SENTINEL
} from '@aiao/rxdb-adapter-encrypted';

import { scanForPlaintext, type ScanHit } from '@aiao/rxdb-adapter-encrypted/testing';

Refer to the TSDoc on each export for its security and lifecycle contract.

Guarantees

| Spec | Guarantee | | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | | FR-001 | Schema validation rejects encrypted PK / FK / index / unique / sortable / FTS / computed columns | | FR-002 | Envelope text form v\|alg\|kid\|iv\|ct\|tag (6 base64url segments) | | FR-003 | AES-GCM-256, unique 96-bit IV per write, AAD joins namespace, tableName, columnName, primaryKey, and kid with byte 0x1F | | FR-004 | unlock() accepts exactly one of passphrase / keyBytes / key / keyProvider | | FR-005 | All encrypted columns are emitted as TEXT regardless of logical type | | FR-006 | Zero plaintext in DB files, rxdb_change patches, query cache, history snapshots | | FR-007 | Filter / order / group / FTS over encrypted column throws EncryptedQueryError before SQL gen | | FR-008 | Locked-state reads throw EncryptedLockedError; idle auto-lock after 5 min (configurable, 0 disables) | | FR-009 | unlock() verifies passphrase against persisted verifier probe; wrong passphrase never retains key |

What this package does NOT do (MVP)

• No full-database encryption — only declared columns are sealed.
• No native keychain / passkey / WebAuthn — bring your own passphrase or key bytes.
• No searchable encryption — where / order / group / FTS on encrypted columns is rejected.
• No key rotation — single kid per database for the MVP.
• No audit log — decrypt failures throw, not persisted.
• No automatic relock on tab visibility — subscribe to document.visibilitychange yourself.

License

MIT