Simplify Interface

Author: davidmuggleton

.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 jobs:
   publish:
@@ -27,7 +28,7 @@ jobs:
 
       - run: pnpm run build
 
-      - run: pnpm publish --no-git-checks
+      - run: pnpm publish --no-git-checks --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

README.md

@@ -4,16 +4,24 @@
 [![CI](https://github.com/davidmuggleton/pglite-encrypted-fs/actions/workflows/ci.yml/badge.svg)](https://github.com/davidmuggleton/pglite-encrypted-fs/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
-Transparent AES-256-GCM page-level encryption for PGlite PostgreSQL databases.
+An encrypted virtual filesystem for [PGlite](https://pglite.dev/). Provides transparent AES-256-GCM page-level encryption so your PGlite database files are encrypted at rest.
+
+> **Status:** Alpha. The on-disk format is not yet versioned and may change before 1.0.
+
+## Why this exists
+
+[PGlite](https://pglite.dev/) gives you a full embedded PostgreSQL in Node.js -- SQL, indexes, transactions, extensions like pgvector, all without a server. But out of the box, database files sit **plaintext on disk**.
+
+This package is an encrypted VFS that plugs into PGlite's filesystem layer, encrypting every page as it's written and decrypting as it's read. Your PGlite code stays the same -- you just pass an `EncryptedFS` instance at creation.
 
 ## Features
 
 - **AES-256-GCM authenticated encryption** -- page-level encryption with integrity verification on every read
-- **PBKDF2-SHA512 key derivation** -- 256K iterations, compliant with OWASP recommendations
+- **PBKDF2-SHA512 key derivation** -- 256K iterations, aligned with [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) guidance
 - **Near-zero read overhead** -- decrypted pages are cached in PostgreSQL's buffer pool; subsequent reads hit the cache
 - **AAD binding prevents page swapping/replay attacks** -- each page is bound to its file identity and position
 - **Passphrase verification on reopen** -- a wrong key is detected immediately, before any data is served
-- **Works with PGlite extensions** -- pgvector, and any other extension supported by PGlite
+- **Transparent to PGlite extensions** -- pgvector and other extensions work normally on top of the encrypted VFS
 
 ## Install
 
@@ -34,59 +42,71 @@ yarn add pglite-encrypted-fs @electric-sql/pglite
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite'
-import { EncryptedFS, deriveKeys, randomSalt } from 'pglite-encrypted-fs'
+import { EncryptedFS } from 'pglite-encrypted-fs'
 
 const dataDir = './my-encrypted-db'
-const passphrase = 'my-secret-passphrase'
-
-// First time: generate a new salt and derive keys
-const salt = randomSalt()
-const keys = deriveKeys(passphrase, salt)
-
-// Create the encrypted filesystem and pass it to PGlite
-const fs = new EncryptedFS(dataDir, keys, salt)
+const fs = new EncryptedFS(dataDir, 'my-secret-passphrase')
 const db = await PGlite.create({ dataDir, fs })
 
-// Use it like a normal PGlite database
 await db.exec('CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)')
 await db.exec("INSERT INTO users (name) VALUES ('Alice')")
 const result = await db.query('SELECT * FROM users')
 console.log(result.rows) // [{ id: 1, name: 'Alice' }]
 
 await db.close()
-
-// IMPORTANT: Store the salt alongside your database path.
-// You'll need it to reopen the database later.
 ```
 
 ## Reopening an Existing Database
 
-The salt is required to reopen a database. Store it alongside your database path -- for example, in a config file or as a hex-encoded string in your application's settings.
+Use the same passphrase -- the salt is stored automatically.
 
 ```typescript
-// To reopen, use the same salt and passphrase
-const keys = deriveKeys(passphrase, savedSalt)
-const fs = new EncryptedFS(dataDir, keys, savedSalt)
+const fs = new EncryptedFS(dataDir, 'my-secret-passphrase')
 const db = await PGlite.create({ dataDir, fs })
 // Your data is still there, decrypted transparently
 ```
 
-If the passphrase is wrong, the `EncryptedFS` constructor throws immediately with `"Invalid passphrase or corrupted encryption keys"`.
+If the passphrase is wrong, the constructor throws immediately with `"Invalid passphrase or corrupted encryption keys"`.
+
+## pgvector Example
+
+PGlite extensions work normally on top of the encrypted VFS. Here's pgvector:
+
+```typescript
+import { PGlite } from '@electric-sql/pglite'
+import { vector } from '@electric-sql/pglite/vector'
+import { EncryptedFS } from 'pglite-encrypted-fs'
+
+const dataDir = './my-encrypted-vectors'
+const fs = new EncryptedFS(dataDir, process.env.DB_PASSPHRASE!)
+const db = await PGlite.create({ dataDir, fs, extensions: { vector } })
+
+await db.exec('CREATE EXTENSION IF NOT EXISTS vector')
+await db.exec('CREATE TABLE docs (id serial PRIMARY KEY, embedding vector(3))')
+await db.exec("INSERT INTO docs (embedding) VALUES ('[0.1, 0.2, 0.3]')")
+
+const { rows } = await db.query(
+  "SELECT * FROM docs ORDER BY embedding <-> '[0.1, 0.2, 0.3]' LIMIT 5"
+)
+console.log(rows)
+
+await db.close()
+fs.destroy()
+```
 
 ## API Reference
 
-### `EncryptedFS(dataDir, keys, salt, options?)`
+### `new EncryptedFS(dataDir, passphrase, options?)`
 
 Creates an encrypted filesystem instance.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `dataDir` | `string` | Path to the database directory on disk |
-| `keys` | `DerivedKeys` | Encryption keys returned by `deriveKeys()` |
-| `salt` | `Buffer` | The 16-byte salt used during key derivation |
+| `passphrase` | `string` | Your encryption passphrase |
 | `options` | `{ debug?: boolean }` | Optional. Enable debug logging with `{ debug: true }` |
 
-The constructor creates the data directory if it does not exist, and verifies the passphrase against an existing database (or creates the verification token for a new one).
+The constructor creates the data directory if it does not exist. On first use, it generates a random salt and creates a verification token. On subsequent opens, it reads the salt from the existing verification token and verifies the passphrase is correct.
 
 ### `deriveKeys(passphrase, salt)`
 
@@ -158,7 +178,7 @@ Each file receives a random 32-byte identifier stored in its header. Because fil
 
 ### Passphrase Verification
 
-On first initialization, a `.encryption-verify` file is created containing a known magic value encrypted with the derived key. On every subsequent open, this file is decrypted and checked. A wrong passphrase fails immediately rather than silently serving corrupted data.
+On first initialization, a `.encryption-verify` file is created containing the 16-byte salt followed by a known magic value encrypted with the derived key. On every subsequent open, the salt is read from this file, the key is re-derived, and the magic value is decrypted and checked. A wrong passphrase fails immediately rather than silently serving corrupted data.
 
 ### Unencrypted Files
 
@@ -172,6 +192,17 @@ The following PostgreSQL metadata files are left unencrypted because they contai
 - `.lock` files
 - `replorigin_checkpoint`
 
+## Threat Model
+
+This provides **at-rest encryption** of PGlite/PostgreSQL database files on disk. It protects against offline theft or unauthorized access to the stored files.
+
+**Non-goals:**
+
+- Does not protect against an attacker who can run code in your process
+- Data is decrypted in memory during query execution (like any database encryption-at-rest)
+- JavaScript runtimes cannot guarantee secure key erasure (`destroy()` is best-effort)
+- This package has not been independently audited. If you find a vulnerability, please report it privately via GitHub.
+
 ## Performance
 
 Benchmarks measured on Node.js (see `pnpm run bench` for your own results):
@@ -190,7 +221,7 @@ Benchmarks measured on Node.js (see `pnpm run bench` for your own results):
 | Single page decrypt | -- | 3.9us | -- |
 | Key derivation (PBKDF2) | -- | 48ms | -- |
 
-Read operations have near-zero overhead because data is decrypted when pages are loaded into PostgreSQL's buffer pool. Subsequent reads hit the cache. Write overhead comes from per-page encryption. Run benchmarks yourself with `pnpm run bench`.
+Read operations have near-zero overhead because data is decrypted when pages are loaded into PostgreSQL's buffer pool. Subsequent reads hit the cache, so reads are only slow the first time a page is loaded. Write overhead comes from per-page encryption. Run benchmarks yourself with `pnpm run bench`.
 
 ## Platform Support
 
@@ -205,6 +236,20 @@ Read operations have near-zero overhead because data is decrypted when pages are
 
 This package uses Node.js `crypto` and `fs` modules and is not compatible with browser environments.
 
+## FAQ
+
+**Can I rotate the passphrase?**
+
+Not in-place. Export your data with `pg_dump` (or application-level export), create a new encrypted database with the new passphrase, and re-import.
+
+**Can I migrate an existing plaintext PGlite database?**
+
+Same approach -- dump and re-import into a new encrypted database.
+
+**Why not SQLCipher?**
+
+SQLCipher encrypts **SQLite** databases. This package encrypts **PGlite/PostgreSQL** databases. If you're already using PGlite for its PostgreSQL features (extensions, SQL semantics, pgvector), this adds at-rest encryption without changing databases.
+
 ## Contributing
 
 ```bash

bench/helpers/bench-utils.ts

@@ -12,7 +12,6 @@ export interface BenchPair {
   encDb: PGlite
   plainDir: string
   encDir: string
-  encSalt: Buffer
   cleanup: () => Promise<void>
 }
 
@@ -32,7 +31,7 @@ export async function createBenchPair(
     ...(extensions ? { extensions } : {}),
   })
 
-  const { db: encDb, salt: encSalt } = await createEncryptedPGlite(
+  const { db: encDb } = await createEncryptedPGlite(
     encDir,
     'bench-passphrase',
     extensions,
@@ -50,7 +49,7 @@ export async function createBenchPair(
     cleanupTestDir(encDir)
   }
 
-  return { plainDb, encDb, plainDir, encDir, encSalt, cleanup }
+  return { plainDb, encDb, plainDir, encDir, cleanup }
 }
 
 /**

bench/startup.bench.ts

@@ -1,7 +1,7 @@
 import { describe, bench } from 'vitest'
 import { PGlite } from '@electric-sql/pglite'
+import { EncryptedFS } from '../src/index.js'
 import { createTestDir, createEncryptedPGlite } from './helpers/bench-utils.js'
-import { reopenEncryptedPGlite } from '../test/helpers/test-utils.js'
 
 describe('fresh init', () => {
   bench(
@@ -28,7 +28,6 @@ describe('fresh init', () => {
 describe('reopen', () => {
   let plainDir: string
   let encDir: string
-  let encSalt: Buffer
 
   bench(
     'plain - reopen',
@@ -49,20 +48,11 @@ describe('reopen', () => {
     async () => {
       if (!encDir) {
         encDir = createTestDir()
-        const { salt } = await createEncryptedPGlite(encDir, 'bench-passphrase')
-        encSalt = salt
-        const { db } = await reopenEncryptedPGlite(
-          encDir,
-          encSalt,
-          'bench-passphrase',
-        )
+        const { db } = await createEncryptedPGlite(encDir, 'bench-passphrase')
         await db.close()
       }
-      const { db } = await reopenEncryptedPGlite(
-        encDir,
-        encSalt,
-        'bench-passphrase',
-      )
+      const encFs = new EncryptedFS(encDir, 'bench-passphrase')
+      const db = await PGlite.create({ dataDir: encDir, fs: encFs })
       await db.close()
     },
     { iterations: 3, warmupIterations: 1, time: 0 },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pglite-encrypted-fs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Encrypted filesystem for PGlite — AES-256-GCM page-level encryption for PostgreSQL databases",
   "type": "module",
   "main": "./dist/index.js",

src/encrypted-fs.ts

@@ -18,6 +18,8 @@ import {
   type DerivedKeys,
   encryptPage,
   decryptPage,
+  deriveKeys,
+  randomSalt,
   VERIFICATION_MAGIC,
   VERIFICATION_FILE_ID,
 } from './crypto.js'
@@ -156,30 +158,43 @@ interface OpenFile {
   fileId: Buffer
 }
 
+export interface EncryptedFSOptions {
+  debug?: boolean
+}
+
 export class EncryptedFS extends BaseFilesystem {
-  private readonly keys: DerivedKeys
-  private readonly salt: Buffer
+  private readonly keys!: DerivedKeys
+  private readonly salt!: Buffer
   private openFiles: Map<number, OpenFile> = new Map()
   private cwd: string = '/'
   private nextFd: number = 100
 
   private destroyed = false
 
-  constructor(
-    dataDir: string,
-    keys: DerivedKeys,
-    salt: Buffer,
-    options?: { debug?: boolean },
-  ) {
+  constructor(dataDir: string, passphrase: string, options?: EncryptedFSOptions) {
     super(dataDir, options)
-    this.keys = keys
-    this.salt = salt
 
     const baseDir = this.dataDir ?? dataDir
     if (!fs.existsSync(baseDir)) {
       fs.mkdirSync(baseDir, { recursive: true })
     }
 
+    const tokenPath = path.join(baseDir, '.encryption-verify')
+    if (fs.existsSync(tokenPath)) {
+      const header = Buffer.alloc(SALT_SIZE)
+      const fd = fs.openSync(tokenPath, 'r')
+      try {
+        fs.readSync(fd, header, 0, SALT_SIZE, 0)
+      } finally {
+        fs.closeSync(fd)
+      }
+      this.salt = header
+    } else {
+      this.salt = randomSalt()
+    }
+
+    this.keys = deriveKeys(passphrase, this.salt)
+
     this.verifyOrCreateToken(baseDir)
 
     if (this.debug) {
@@ -211,17 +226,24 @@ export class EncryptedFS extends BaseFilesystem {
       const magic = Buffer.alloc(PAGE_SIZE)
       VERIFICATION_MAGIC.copy(magic)
       const encrypted = encryptPage(magic, 0, this.keys, VERIFICATION_FILE_ID)
-      fs.writeFileSync(tokenPath, encrypted)
+      fs.writeFileSync(tokenPath, Buffer.concat([this.salt, encrypted]))
       return
     }
 
     const data = fs.readFileSync(tokenPath)
-    if (data.length !== ENCRYPTED_PAGE_SIZE) {
+    if (data.length !== SALT_SIZE + ENCRYPTED_PAGE_SIZE) {
       throw new Error('Invalid passphrase or corrupted encryption keys')
     }
 
+    const encryptedPage = data.subarray(SALT_SIZE)
+
     try {
-      const decrypted = decryptPage(data, 0, this.keys, VERIFICATION_FILE_ID)
+      const decrypted = decryptPage(
+        encryptedPage,
+        0,
+        this.keys,
+        VERIFICATION_FILE_ID,
+      )
       if (
         !decrypted
           .subarray(0, VERIFICATION_MAGIC.length)

src/index.ts

@@ -1,4 +1,4 @@
-export { EncryptedFS } from './encrypted-fs.js'
+export { EncryptedFS, type EncryptedFSOptions } from './encrypted-fs.js'
 
 export {
   PAGE_SIZE,