inillucent 1.0.33 → 2.0.2

package/README.md

@@ -39,9 +39,9 @@ package by name, for example `npm install @blackrainbowlabs/cli-linux-x64`.
 
 | Program | What it is |
 |---|---|
-| `inillucent` | the command line: 30 commands, such as `query`, `exec`, `describe`, `import`, `export` and `search` |
+| `inillucent` | the command line: 34 commands, such as `query`, `exec`, `describe`, `import`, `export` and `search` |
 | `inillucent-shell` | an interactive shell that works like `sqlite3`, with 63 of its 65 dot commands |
-| `inillucent-mcp` | an MCP server: 28 of the same commands served to an AI agent |
+| `inillucent-mcp` | an MCP server: 29 of the same commands served to an AI agent |
 | `inillucent-migrate` | builds a database from a legacy retrieval index. `inillucent migrate` copies a SQLite file or a PostgreSQL or MySQL database |
 
 ## From a shell
@@ -106,6 +106,24 @@ spans two calls. To run several statements as one transaction, use the `batch` c
 `query()` returns a BLOB column as a `Uint8Array`, so bytes read by one query can be bound into the
 next.
 
+## Encrypted databases
+
+Pass `key` beside `db`:
+
+```js
+const key = `x'${'5a'.repeat(32)}'`;
+await inillucent('exec', { db: 'app.rdb', key, sql: 'CREATE TABLE note (body TEXT)' });
+const rows = await query('SELECT body FROM note', { db: 'app.rdb', key });
+```
+
+The key travels to the program in the `INILLUCENT_KEY` environment variable. It is never put on the command line, because a command line is visible in the process list. When you pass no key, the environment the program inherits is left alone.
+
+A key written `x'` followed by 64 hexadecimal digits and `'` is a raw 32 byte key. Any other text is a passphrase, which is stretched with 600,000 rounds of PBKDF2 on every open, so a raw key opens faster.
+
+A database created with a key is encrypted. Opening it without the key, or with a wrong key, fails with status `corrupt`. Opening a plaintext database with a key fails the same way.
+
+A call without `key` on an encrypted database returns `{ ok: false, status: 'corrupt' }`.
+
 ## Errors
 
 ```js
@@ -146,7 +164,7 @@ client's configuration:
 }
 ```
 
-`inillucent-mcp` serves 28 of the command line's commands as MCP tools. The tools are generated from
+`inillucent-mcp` serves 29 of the command line's commands as MCP tools. The tools are generated from
 the same command table as the command line. `--readonly` refuses every statement that changes data.
 `--root DIR` refuses every path outside `DIR`.
 

package/index.mjs

@@ -77,14 +77,15 @@ export { resolveBinary, PROGRAMS, platformPackage };
  * @param binary - the program to run
  * @param args - its command line
  * @param stdin - what to write to its standard input, or null
+ * @param env - the environment the program runs with
  */
-async function spawnWith(binary, args, stdin) {
+async function spawnWith(binary, args, stdin, env) {
   if (stdin === null) {
-    return run(binary, args, { maxBuffer: 256 * 1024 * 1024 });
+    return run(binary, args, { maxBuffer: 256 * 1024 * 1024, env });
   }
   const { spawn } = await import('node:child_process');
   return new Promise((resolve, reject) => {
-    const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'], env });
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', (chunk) => {
@@ -110,6 +111,22 @@ async function spawnWith(binary, args, stdin) {
   });
 }
 
+/**
+ * Builds the environment a child program runs with.
+ *
+ * The key of an encrypted database travels in `INILLUCENT_KEY` and never on the
+ * command line, because a command line is visible in the process list. With no
+ * key the inherited environment is passed on untouched.
+ *
+ * @param key - the key text of an encrypted database, or undefined
+ */
+function childEnvironment(key) {
+  if (key === undefined || key === null) {
+    return process.env;
+  }
+  return { ...process.env, INILLUCENT_KEY: String(key) };
+}
+
 /**
  * Runs one inillucent command and returns its result object.
  *
@@ -124,10 +141,11 @@ async function spawnWith(binary, args, stdin) {
  * broken invocation throws.
  *
  * @param command - the verb, such as "query" or "describe"
- * @param options - the named arguments the verb takes, plus `db`
+ * @param options - the named arguments the verb takes, plus `db` and `key`
+ *   (the key of an encrypted database, sent in `INILLUCENT_KEY`)
  */
 export async function inillucent(command, options = {}) {
-  const { db, ...rest } = options;
+  const { db, key, ...rest } = options;
   const args = [command, '--output', 'json'];
   let stdin = null;
   if (db) {
@@ -160,7 +178,7 @@ export async function inillucent(command, options = {}) {
   }
   const binary = resolveBinary('inillucent');
   try {
-    const { stdout } = await spawnWith(binary, args, stdin);
+    const { stdout } = await spawnWith(binary, args, stdin, childEnvironment(key));
     return JSON.parse(stdout);
   } catch (why) {
     // A non-zero exit still prints the result object on standard output when
@@ -182,7 +200,7 @@ export async function inillucent(command, options = {}) {
  * that need the counts, the timing or the failure class.
  *
  * @param sql - the statement
- * @param options - `db`, `params`, `limit`
+ * @param options - `db`, `key`, `params`, `limit`
  */
 export async function query(sql, options = {}) {
   const result = await inillucent('query', { sql, ...options });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inillucent",
-  "version": "1.0.33",
+  "version": "2.0.2",
   "description": "Embedded SQL database with full-text and vector search, an MCP server, and a sqlite3-shaped shell. No native build step: the binaries ship as platform packages.",
   "keywords": [
     "database",
@@ -43,10 +43,10 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "@blackrainbowlabs/cli-win32-x64": "1.0.33",
-    "@blackrainbowlabs/cli-darwin-arm64": "1.0.33",
-    "@blackrainbowlabs/cli-darwin-x64": "1.0.33",
-    "@blackrainbowlabs/cli-linux-x64": "1.0.33",
-    "@blackrainbowlabs/cli-linux-arm64": "1.0.33"
+    "@blackrainbowlabs/cli-win32-x64": "2.0.2",
+    "@blackrainbowlabs/cli-darwin-arm64": "2.0.2",
+    "@blackrainbowlabs/cli-darwin-x64": "2.0.2",
+    "@blackrainbowlabs/cli-linux-x64": "2.0.2",
+    "@blackrainbowlabs/cli-linux-arm64": "2.0.2"
   }
 }