@aztec/sqlite3mc-wasm 0.0.1-commit.e5a3663dd

package/README.md

@@ -0,0 +1,112 @@
+# @aztec/sqlite3mc-wasm
+
+SQLite3 Multiple Ciphers v2.2.4 (based on SQLite 3.50.4) packaged as a WASM
+module.
+
+Upstream: https://github.com/utelle/SQLite3MultipleCiphers
+
+Cipher schemes enabled: ChaCha20 (PRAGMA cipher = chacha20), SQLCipher v4,
+AES-256, and others. See sqlite3mc upstream docs.
+
+Usage: import sqlite3InitModule from @aztec/sqlite3mc-wasm. API is identical
+to @sqlite.org/sqlite-wasm; sqlite3mc is a strict superset.
+
+License: sqlite3mc is MIT-licensed.
+
+## How vendoring works
+
+Upstream WASM/JS artifacts under `vendor/jswasm/` are fetched at build time. The committed state of the directory is:
+
+| File                              | Why                                                                                                                                    |
+|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| `.gitignore`                      | Allowlist that keeps the rest of `vendor/jswasm/` out of git                                                                           |
+| `SHA256SUMS`                      | Per-file integrity manifest. Pinned at vendoring time; verified at every build                                                         |
+| `sqlite3-bundler-friendly.d.mts`  | Locally-authored TypeScript declaration companion for the upstream `.mjs`. Required by TS NodeNext module resolution.                  |
+
+Everything else in `vendor/jswasm/` (the actual `.wasm`, `.mjs`, `.js`) is populated by `scripts/vendor.sh`, which is
+invoked from `yarn-project/bootstrap.sh` before any package compiles. It downloads the upstream release zip, verifies
+its SHA256 against the pinned value, extracts the WASM/JS files, and regenerates `SHA256SUMS`. On CI cache hits the
+files come back via the build cache without re-fetching from upstream.
+
+The pinned upstream version lives in `scripts/vendor.pin`:
+
+```sh
+MC_VERSION=2.2.4
+SQLITE_VERSION=3.50.4
+SHA256=e73514200d76286d7d4a239589589b4f64d24ac4f4f7b2760e1f07b14ac5f6a5
+```
+
+## Verification (full chain)
+
+Run from this package's root, after `scripts/vendor.sh ensure` has populated `vendor/jswasm/`.
+
+### Step 1: zip matches the pinned SHA
+
+The build script verifies this automatically. To check by hand:
+
+```bash
+source scripts/vendor.pin
+curl -sL "https://github.com/utelle/SQLite3MultipleCiphers/releases/download/v${MC_VERSION}/sqlite3mc-${MC_VERSION}-sqlite-${SQLITE_VERSION}-wasm.zip" \
+  | sha256sum
+# Expected: matches $SHA256 from scripts/vendor.pin
+```
+
+If this fails: upstream re-released the asset, or the artifact was tampered with in transit. Investigate before
+trusting any subsequent check.
+
+### Step 2: vendored files match the manifest
+
+```bash
+cd vendor/jswasm && sha256sum -c SHA256SUMS
+```
+
+Expected output: every file reports `OK`.
+
+If any file reports `FAILED`: the file's bytes differ from what was recorded at vendoring time. Either the file was
+modified post-fetch (via pre-commit hooks, accidental edits, etc.), or `SHA256SUMS` itself was tampered with. Both
+cases need investigation, the build should not be trusted.
+
+### Step 3 (optional, stronger): independently re-derive SHA256SUMS from the zip
+
+A reviewer who wants to prove `SHA256SUMS` itself wasn't tampered with can regenerate it from the upstream zip:
+
+```bash
+source scripts/vendor.pin
+curl -sL "https://github.com/utelle/SQLite3MultipleCiphers/releases/download/v${MC_VERSION}/sqlite3mc-${MC_VERSION}-sqlite-${SQLITE_VERSION}-wasm.zip" -o /tmp/sqlite3mc.zip
+unzip -q /tmp/sqlite3mc.zip -d /tmp/sqlite3mc-check
+
+# Compute per-file hashes from the extracted jswasm/
+(cd /tmp/sqlite3mc-check/sqlite3mc-wasm-* && cd jswasm && sha256sum -- * | sort -k2) > /tmp/upstream-sums
+
+# Compare against repo's SHA256SUMS, excluding our locally-authored d.mts
+grep -v 'sqlite3-bundler-friendly\.d\.mts' vendor/jswasm/SHA256SUMS | sort -k2 > /tmp/repo-sums
+diff /tmp/upstream-sums /tmp/repo-sums
+```
+
+Expected: empty diff. Any output means either upstream files have been modified or `SHA256SUMS` claims different hashes
+than the zip.
+
+## Bumping the pinned version
+
+1. Edit `scripts/vendor.pin` with the new `MC_VERSION`, `SQLITE_VERSION`, and the SHA256 of the new release zip (find
+   it in the upstream release notes or compute it: `curl -sL <url> | sha256sum`).
+2. Run `scripts/vendor.sh` (no args). It fetches the new release, verifies the SHA, replaces `vendor/jswasm/`, and
+   regenerates `SHA256SUMS`.
+3. Re-run kv-store tests to confirm compatibility: `yarn workspace @aztec/kv-store test:browser`
+4. Commit `scripts/vendor.pin` and `vendor/jswasm/SHA256SUMS` together.
+
+To verify a candidate release before editing the pin file:
+
+```bash
+scripts/vendor.sh <mc-version> <sqlite-version> <expected-sha256>
+```
+
+The 3-argument form overrides the pin file but does not modify it.
+
+## Why `vendor/` is excluded from prettier
+
+The repo's `.prettierignore` includes `sqlite3mc-wasm/vendor/`. Without this, pre-commit hooks would silently reformat
+the upstream `.js` / `.mjs` files between fetch and the next commit (whitespace only, semantically identical, but
+cryptographically different bytes), breaking the verification chain above.
+
+If you see prettier formatting drift in this directory, the ignore entry is missing or misconfigured.

package/dest/index.js

@@ -0,0 +1,6 @@
+/**
+ * Re-exports sqlite3mc's bundler-friendly ES module default (sqlite3InitModule)
+ * and the TypeScript types expected by downstream consumers. Mirrors the
+ * `@sqlite.org/sqlite-wasm` package default export — sqlite3mc is a strict
+ * API-compatible superset, so upstream types apply unchanged.
+ */ export { default } from '../vendor/jswasm/sqlite3-bundler-friendly.mjs';

package/dest/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-exports sqlite3mc's bundler-friendly ES module default (sqlite3InitModule)
+ * and the TypeScript types expected by downstream consumers. Mirrors the
+ * `@sqlite.org/sqlite-wasm` package default export — sqlite3mc is a strict
+ * API-compatible superset, so upstream types apply unchanged.
+ */
+export { default } from '../vendor/jswasm/sqlite3-bundler-friendly.mjs';
+export type { Database, SAHPoolUtil, Sqlite3Static } from '@sqlite.org/sqlite-wasm';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7R0FLRztBQUNILE9BQU8sRUFBRSxPQUFPLEVBQUUsTUFBTSwrQ0FBK0MsQ0FBQztBQUN4RSxZQUFZLEVBQUUsUUFBUSxFQUFFLFdBQVcsRUFBRSxhQUFhLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQyJ9

package/dest/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,+CAA+C,CAAC;AACxE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@aztec/sqlite3mc-wasm",
+  "version": "0.0.1-commit.e5a3663dd",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dest/src/index.d.ts",
+      "import": "./dest/index.js"
+    },
+    "./vendor/jswasm/sqlite3.wasm": "./vendor/jswasm/sqlite3.wasm",
+    "./vendor/jswasm/sqlite3-opfs-async-proxy.js": "./vendor/jswasm/sqlite3-opfs-async-proxy.js"
+  },
+  "inherits": [
+    "../package.common.json",
+    "./package.local.json"
+  ],
+  "scripts": {
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}",
+    "build:dev": "../scripts/tsc.sh --watch"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.0.0",
+    "@sqlite.org/sqlite-wasm": "3.50.4-build1",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "jest": "^30.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "src",
+    "vendor",
+    "dest",
+    "!*.test.*"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "jest": {
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ],
+    "setupFilesAfterEnv": [
+      "../../foundation/src/jest/setupAfterEnv.mjs"
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exports sqlite3mc's bundler-friendly ES module default (sqlite3InitModule)
+ * and the TypeScript types expected by downstream consumers. Mirrors the
+ * `@sqlite.org/sqlite-wasm` package default export — sqlite3mc is a strict
+ * API-compatible superset, so upstream types apply unchanged.
+ */
+export { default } from '../vendor/jswasm/sqlite3-bundler-friendly.mjs';
+export type { Database, SAHPoolUtil, Sqlite3Static } from '@sqlite.org/sqlite-wasm';

package/vendor/jswasm/.gitignore

@@ -0,0 +1,9 @@
+# Upstream sqlite3mc-wasm release artifacts are fetched at build time by
+# scripts/vendor.sh (driven by scripts/vendor.pin). Don't commit them.
+#
+# Allowlist: keep this .gitignore, the integrity manifest, and our
+# locally-authored TypeScript declaration tracked in git.
+*
+!.gitignore
+!SHA256SUMS
+!sqlite3-bundler-friendly.d.mts

package/vendor/jswasm/SHA256SUMS

@@ -0,0 +1,11 @@
+812bca8052d0e43bd8668dbd99430ee76c1cbd1be2d42087590c5c29018083c7  sqlite3-bundler-friendly.d.mts
+85b8e8eb2b63ec08e106f82820a1942a07651c15a6204bc2c3510138a43b36bd  sqlite3-bundler-friendly.mjs
+f07714bd13b703c1917b02e73f4b3a8514c2b37e2b00afe1375d4a30faa2461d  sqlite3-node.mjs
+fc499c666c095929b5614dfa34d3f6e01cff77df2ea98abade30de97ac8db324  sqlite3-opfs-async-proxy.js
+9386ab42a3fe80fddf21e5651aa898eb1a674355b070f6d1338d93ebbc6779c6  sqlite3-worker1-bundler-friendly.mjs
+ff0581756d86ca1397ce3f53810c29af1d8db34c4814e77271f85d4d11df108f  sqlite3-worker1-promiser.js
+e1f0b46abdc61b45b9f64bc522324ccddfe385308ef772eef054e66ba3b013f8  sqlite3-worker1-promiser.mjs
+1bed25837f00f7b68943cfcabed62dfd202cae863a72af24a0d6487d7d7b0e61  sqlite3-worker1.js
+0c473584c02a07793b3c320e166c25aead8131880d5ae3e719f976ccc5081fa0  sqlite3.js
+4677d6c8e66fe99c29307fe2b782fce83272b760a3a617202fae8e3f3434dab5  sqlite3.mjs
+e0e94e4ac5221c19aefe7e59fe88ceab93bff56ec1d966c21c6cf39ac0f26735  sqlite3.wasm

package/vendor/jswasm/sqlite3-bundler-friendly.d.mts

@@ -0,0 +1,7 @@
+// Type declaration for the sqlite3mc bundler-friendly ES module.
+// sqlite3mc is API-compatible with @sqlite.org/sqlite-wasm, so we reuse its
+// Sqlite3Static type directly.
+import type { Sqlite3Static } from '@sqlite.org/sqlite-wasm';
+
+declare function sqlite3InitModule(opts?: Record<string, unknown>): Promise<Sqlite3Static>;
+export default sqlite3InitModule;