{"id":46634888,"url":"https://github.com/7mind/sqlcipher-wasm","last_synced_at":"2026-03-08T01:02:38.755Z","repository":{"id":332015275,"uuid":"1087881321","full_name":"7mind/sqlcipher-wasm","owner":"7mind","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-03T20:58:48.000Z","size":21127,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T06:22:53.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7mind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T20:47:55.000Z","updated_at":"2025-12-03T20:58:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/7mind/sqlcipher-wasm","commit_stats":null,"previous_names":["7mind/sqlcipher-wasm"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/7mind/sqlcipher-wasm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mind%2Fsqlcipher-wasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mind%2Fsqlcipher-wasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mind%2Fsqlcipher-wasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mind%2Fsqlcipher-wasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7mind","download_url":"https://codeload.github.com/7mind/sqlcipher-wasm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7mind%2Fsqlcipher-wasm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30240269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"ssl_error","status_checked_at":"2026-03-08T00:55:48.608Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-08T01:01:13.521Z","updated_at":"2026-03-08T01:02:38.670Z","avatar_url":"https://github.com/7mind.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SQLCipher WebAssembly\n\n[![npm version](https://badge.fury.io/js/%407mind.io%2Fsqlcipher-wasm.svg)](https://www.npmjs.com/package/@7mind.io/sqlcipher-wasm)\n[![CI/CD](https://github.com/7mind/sqlcipher-wasm/workflows/CI%2FCD/badge.svg)](https://github.com/7mind/sqlcipher-wasm/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA production-ready WebAssembly build of [SQLCipher](https://www.zetetic.net/sqlcipher/) with **real OpenSSL-based encryption**, high-level JavaScript API, and comprehensive test coverage.\n\n## Features\n\n- **Real Encryption**: Full SQLCipher encryption using OpenSSL 3.3.2 compiled to WebAssembly\n- **High-Level API**: Easy-to-use JavaScript wrapper with automatic memory management\n- **Cross-Platform**: Works in Node.js and browsers, compatible with native SQLCipher databases\n- **Comprehensive Tests**: 5 test suites covering all functionality including cross-platform compatibility\n- **Nix Flake Environment**: Reproducible development environment\n- **Type Definitions**: TypeScript definitions included\n- **Benchmarked**: Performance benchmarks for critical operations\n\n## Security\n\nThis build uses **real cryptographic primitives** from OpenSSL 3.3.2, providing:\n\n- **AES-256-CBC** encryption\n- **PBKDF2-HMAC-SHA1** key derivation (64,000 iterations by default)\n- **HMAC-SHA1** for authentication\n- **Cryptographically secure** random number generation\n\nDatabases created with this library are **fully compatible** with native SQLCipher (C++ version).\n\n## Prerequisites\n\n- [Nix](https://nixos.org/download.html) with flakes enabled\n- [direnv](https://direnv.net/) (optional but recommended)\n\n### Enable Nix Flakes\n\nAdd to your `~/.config/nix/nix.conf` (or `/etc/nix/nix.conf`):\n\n```\nexperimental-features = nix-command flakes\n```\n\n## Quick Start\n\n1. **Clone the repository**\n\n2. **Enter the Nix environment**:\n\n   ```bash\n   nix develop\n   ```\n\n   Or with direnv:\n   ```bash\n   direnv allow\n   ```\n\n3. **Build OpenSSL for WebAssembly** (first time only):\n\n   ```bash\n   ./build-openssl.sh\n   ```\n\n4. **Build SQLCipher WASM**:\n\n   ```bash\n   ./build.sh\n   ```\n\n5. **Run all tests**:\n\n   ```bash\n   npm test\n   ```\n\n6. **Run benchmarks**:\n\n   ```bash\n   npm run bench\n   ```\n\n## Project Structure\n\n```\n.\n├── flake.nix                       # Nix flake configuration\n├── .envrc                          # direnv configuration\n├── build-openssl.sh                # OpenSSL build script\n├── build.sh                        # SQLCipher WASM build script\n├── package.json                    # NPM package configuration\n├── dist/                           # Output directory\n│   ├── sqlcipher.js                # JavaScript loader\n│   └── sqlcipher.wasm              # WebAssembly binary\n├── lib/\n│   └── sqlite-api.cjs              # High-level JavaScript API\n├── test/\n│   ├── run-all-tests.cjs           # Test suite runner\n│   ├── test.cjs                    # Core functionality tests\n│   ├── e2e-test.cjs                # End-to-end tests\n│   ├── file-db-test.cjs            # File persistence tests\n│   ├── encryption-test.cjs         # Encryption tests\n│   └── cross-platform-db-test.cjs  # C++ ↔ WASM compatibility (generated)\n├── bench/\n│   └── benchmark.cjs               # Performance benchmarks\n├── examples/\n│   └── example.cjs                 # Usage examples\n├── tools/\n│   └── prepare-cross-platform-test.sh  # Generate cross-platform test\n└── docs/\n    └── archive/                    # Historical documentation\n```\n\n## Build Process\n\n### 1. OpenSSL Build (`build-openssl.sh`)\n\nDownloads and compiles OpenSSL 3.3.2 to WebAssembly:\n\n- Configured for WASM target (`linux-generic32`)\n- Optimized build (`-O3`)\n- Disabled features: ASM, threads, engines, hardware acceleration\n- Static library output\n\n### 2. SQLCipher Build (`build.sh`)\n\nCompiles SQLCipher with OpenSSL:\n\n1. Copies SQLCipher source from Nix store\n2. Configures and creates amalgamation (`sqlite3.c`)\n3. Compiles with OpenSSL crypto provider\n4. Links with OpenSSL static libraries\n5. Outputs `sqlcipher.js` and `sqlcipher.wasm`\n\n**Key Compilation Flags**:\n\nSQLCipher flags:\n- `SQLITE_HAS_CODEC` - Enable encryption\n- `SQLCIPHER_CRYPTO_OPENSSL` - Use OpenSSL crypto provider\n- `SQLITE_TEMP_STORE=2` - Use memory for temporary storage\n- `SQLITE_THREADSAFE=0` - Disable threading (not needed in WASM)\n- `SQLITE_ENABLE_FTS5` - Full-text search\n- `SQLITE_ENABLE_RTREE` - Spatial indexing\n- `SQLITE_ENABLE_JSON1` - JSON support\n\nEmscripten flags:\n- `INITIAL_MEMORY=16MB` - Starting memory\n- `MAXIMUM_MEMORY=2GB` - Maximum allowed memory\n- `ALLOW_MEMORY_GROWTH=1` - Dynamic memory growth\n- `ENVIRONMENT=node,web` - Node.js and browser support\n\n## Usage\n\n### Basic Example\n\n```javascript\nconst { SQLiteAPI } = require('./lib/sqlite-api.cjs');\nconst initSqlcipher = require('./dist/sqlcipher.js');\n\nasync function main() {\n    // Initialize the WASM module\n    const Module = await initSqlcipher();\n    const sqlite = new SQLiteAPI(Module);\n\n    // Create an encrypted database\n    const db = sqlite.open('/mydb.db', 'my-secret-password');\n\n    // Create a table\n    db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');\n\n    // Insert data\n    db.exec(\n        'INSERT INTO users (name, email) VALUES (?, ?)',\n        ['Alice', 'alice@example.com']\n    );\n\n    // Query data\n    const users = db.query('SELECT * FROM users WHERE name = ?', ['Alice']);\n    console.log(users);\n    // =\u003e [{ id: 1, name: 'Alice', email: 'alice@example.com' }]\n\n    // Close database\n    db.close();\n}\n\nmain();\n```\n\n### Encryption Examples\n\n```javascript\n// Open with password\nconst db = sqlite.open('/encrypted.db', 'password123');\n\n// Change password (re-key)\ndb.exec(\"PRAGMA rekey = 'new-password'\");\n\n// Multiple databases with different passwords\nconst db1 = sqlite.open('/db1.db', 'password1');\nconst db2 = sqlite.open('/db2.db', 'password2');\n\n// Check encryption worked\ndb1.exec('SELECT count(*) FROM sqlite_master'); // OK\ndb2.exec('SELECT count(*) FROM sqlite_master'); // OK\n```\n\n### Browser Usage\n\n```html\n\u003cscript type=\"module\"\u003e\n  import initSqlcipher from './dist/sqlcipher.js';\n  import { SQLiteAPI } from './lib/sqlite-api.js';\n\n  const Module = await initSqlcipher();\n  const sqlite = new SQLiteAPI(Module);\n\n  const db = sqlite.open('/mydb.db', 'secret');\n  console.log('SQLCipher ready!');\n\u003c/script\u003e\n```\n\n## API Reference\n\n### `SQLiteAPI`\n\nHigh-level JavaScript API for SQLCipher.\n\n#### `open(path, password?)`\n\nOpen or create a database.\n\n- `path` - Database file path (e.g., `/mydb.db`)\n- `password` - Encryption password (optional for unencrypted databases)\n- Returns: `Database` instance\n\n#### `Database` Methods\n\n##### `exec(sql, params?)`\n\nExecute SQL statement.\n\n- `sql` - SQL statement\n- `params` - Optional array of parameters for `?` placeholders\n- Returns: `void`\n\n##### `query(sql, params?)`\n\nExecute query and return results.\n\n- `sql` - SQL query\n- `params` - Optional array of parameters\n- Returns: Array of result objects\n\n##### `close()`\n\nClose the database connection.\n\n##### `getChanges()`\n\nGet number of rows changed by last statement.\n\n- Returns: `number`\n\n## Test Suite\n\nThe test suite includes 5 comprehensive test suites:\n\n### 1. Unit Tests (`test/test.cjs`)\n- Module loading and initialization\n- Basic SQL operations\n- Memory management\n- API correctness\n\n### 2. End-to-End Tests (`test/e2e-test.cjs`)\n- Complete workflows\n- Multi-step operations\n- Error handling\n- Edge cases\n\n### 3. File Database Tests (`test/file-db-test.cjs`)\n- File persistence\n- VFS (Virtual File System)\n- Database reopening\n- File operations\n\n### 4. Encryption Tests (`test/encryption-test.cjs`)\n- PRAGMA key interface\n- Password verification\n- Multiple databases with different passwords\n- Database re-keying\n- Wrong password handling\n- API key vs PRAGMA key equivalence\n\n### 5. Cross-Platform Tests (`test/cross-platform-db-test.cjs`)\n- C++ (native SQLCipher) → WASM compatibility\n- Database created with native SQLCipher, read by WASM\n- Binary compatibility verification\n- Real-world migration scenarios\n\nRun all tests:\n```bash\nnpm test\n```\n\nRun tests in watch mode:\n```bash\nnpm run test:watch\n```\n\n### Test Output\n\n```\n╔════════════════════════════════════════════════════════════╗\n║          SQLCipher WASM Test Suite                         ║\n╚════════════════════════════════════════════════════════════╝\n\nRunning 5 test suites...\n\n▶ Running Unit Tests...\n  Core SQLCipher functionality tests\n\n✓ Unit Tests completed in 542ms\n\n▶ Running End-to-End Tests...\n  Complete workflow tests\n\n✓ End-to-End Tests completed in 498ms\n\n...\n\n╔════════════════════════════════════════════════════════════╗\n║                    Test Summary                            ║\n╚════════════════════════════════════════════════════════════╝\n\n  ✓ PASS  Unit Tests               542ms\n  ✓ PASS  End-to-End Tests         498ms\n  ✓ PASS  File Database Tests      523ms\n  ✓ PASS  Encryption Tests         445ms\n  ✓ PASS  Cross-Platform Tests     389ms\n\n─────────────────────────────────────────────────────────────\n  ALL TESTS PASSED\n  Total: 5  Passed: 5  Failed: 0\n  Time: 2.40s\n```\n\n## Benchmarks\n\nRun performance benchmarks:\n\n```bash\nnpm run bench\n```\n\nBenchmarks measure:\n- Module initialization time\n- Memory allocation performance\n- Database operations (INSERT, SELECT, UPDATE, DELETE)\n- Query performance\n- Encryption overhead\n- Memory usage patterns\n\n## Cross-Platform Compatibility\n\nDatabases created with this WASM build are **100% compatible** with native SQLCipher.\n\n### Testing Cross-Platform Compatibility\n\nGenerate and run the cross-platform test:\n\n```bash\n./tools/prepare-cross-platform-test.sh\nnode test/cross-platform-db-test.cjs\n```\n\nThis creates a database with native SQLCipher (C++), encodes it, and verifies WASM can read it.\n\n### Migrating from Native SQLCipher\n\nJust copy your `.db` file and open it with the same password:\n\n```javascript\nconst db = sqlite.open('/path/to/existing.db', 'same-password');\nconst data = db.query('SELECT * FROM your_table');\n```\n\n### Using WASM Databases in Native Apps\n\nThe reverse also works - databases created in WASM can be used in native applications.\n\n## Development\n\n### Rebuilding\n\nAfter changing build scripts:\n\n```bash\n./build.sh\n```\n\nClean rebuild:\n\n```bash\nrm -rf build/ dist/\n./build.sh\n```\n\nRebuild OpenSSL (rarely needed):\n\n```bash\nrm -rf openssl-wasm/ openssl-3.3.2/\n./build-openssl.sh\n```\n\n### Adding Tests\n\nAdd to appropriate test file in `test/`:\n\n```javascript\ntest('Your test name', () =\u003e {\n    const db = sqlite.open('/test.db', 'password');\n    db.exec('CREATE TABLE test (id INTEGER)');\n    const result = db.query('SELECT * FROM test');\n    assert.strictEqual(result.length, 0);\n    db.close();\n});\n```\n\nTests are automatically picked up by `npm test`.\n\n## CI/CD\n\nGitHub Actions workflows:\n\n- **CI/CD** (`.github/workflows/ci.yml`) - Build, test, and publish on releases\n- **PR Checks** (`.github/workflows/pr-check.yml`) - Quick validation on pull requests\n\nBoth workflows:\n1. Cache OpenSSL and Emscripten for faster builds\n2. Build OpenSSL if not cached\n3. Build SQLCipher WASM\n4. Generate cross-platform test\n5. Run all test suites\n6. Run benchmarks (CI only)\n\n## Troubleshooting\n\n### Build fails with \"SQLCIPHER_SRC not set\"\n\nEnter the Nix environment:\n```bash\nnix develop\n```\n\n### Build fails with OpenSSL errors\n\nRebuild OpenSSL:\n```bash\nrm -rf openssl-wasm/ openssl-3.3.2/\n./build-openssl.sh\n```\n\n### Tests fail with \"Cannot find module\"\n\nBuild first:\n```bash\n./build.sh\n```\n\n### \"file is encrypted or is not a database\"\n\nWrong password or corrupted database. Verify password:\n```javascript\ntry {\n    const db = sqlite.open('/test.db', 'password');\n    db.query('SELECT * FROM sqlite_master'); // Will fail if wrong password\n} catch (err) {\n    console.log('Wrong password or corrupted database');\n}\n```\n\n### Out of memory during build\n\nIncrease Node.js memory:\n```bash\nexport NODE_OPTIONS=\"--max-old-space-size=4096\"\n./build.sh\n```\n\n### Cross-platform test fails\n\nMake sure native SQLCipher is available (provided by Nix environment):\n```bash\nnix develop --command bash -c \"which sqlcipher\"\n```\n\n## Performance Tips\n\n1. **Batch operations** - Use transactions for multiple inserts\n2. **Prepare statements** - Reuse prepared statements for repeated queries\n3. **Appropriate memory settings** - Adjust `PRAGMA cache_size`\n4. **Index wisely** - Create indexes for frequently queried columns\n5. **Use the benchmarks** - Profile before optimizing\n\nExample batch insert:\n\n```javascript\ndb.exec('BEGIN TRANSACTION');\nfor (let i = 0; i \u003c 1000; i++) {\n    db.exec('INSERT INTO users (name) VALUES (?)', [`User ${i}`]);\n}\ndb.exec('COMMIT');\n```\n\n## Contributing\n\nContributions welcome! Areas for improvement:\n\n- [ ] Browser-based test runner\n- [ ] More comprehensive benchmarks\n- [ ] IndexedDB persistence examples\n- [ ] Worker thread examples\n- [ ] React/Vue/Svelte integration examples\n- [ ] Performance optimization guides\n\n## Publishing\n\nThe package is configured for NPM publishing:\n\n```bash\nnpm version patch  # or minor, major\ngit push --tags\n```\n\nCreate a GitHub release to trigger automatic publishing to:\n- NPM registry\n- GitHub Packages\n\n## Environment Variables\n\nIn the Nix environment:\n\n- `SQLCIPHER_SRC` - Path to SQLCipher source\n- `EM_CACHE` - Emscripten cache directory\n- `NODE_PATH` - Node.js module search path\n\n## Resources\n\n- [SQLCipher Documentation](https://www.zetetic.net/sqlcipher/documentation/)\n- [OpenSSL Documentation](https://www.openssl.org/docs/)\n- [Emscripten Documentation](https://emscripten.org/docs/)\n- [SQLite Documentation](https://www.sqlite.org/docs.html)\n- [WebAssembly MDN](https://developer.mozilla.org/en-US/docs/WebAssembly)\n\n## License\n\nMIT License - See LICENSE file for details\n\nDependencies:\n- SQLCipher - BSD-style license\n- SQLite - Public domain\n- OpenSSL - Apache License 2.0\n- Emscripten - MIT/NCSA License\n\n## Acknowledgments\n\n- [SQLCipher team](https://www.zetetic.net/) for the encrypted SQLite fork\n- [OpenSSL team](https://www.openssl.org/) for the cryptographic library\n- [Emscripten team](https://emscripten.org/) for the WASM toolchain\n- [SQLite team](https://www.sqlite.org/) for the amazing database engine\n- [Nix community](https://nixos.org/) for reproducible builds\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7mind%2Fsqlcipher-wasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7mind%2Fsqlcipher-wasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7mind%2Fsqlcipher-wasm/lists"}