inillucent 1.0.32 → 2.0.1

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/bin/inillucent-mcp.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent-mcp` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent-mcp');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent-mcp` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-mcp');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent-migrate.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent-migrate` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent-migrate');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent-migrate` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-migrate');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent-shell.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent-shell` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent-shell');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent-shell` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-shell');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-// The `inillucent` shim: resolve the platform binary and become it.
-//
-// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
-// execve and this has to work on Windows. The child's exit code and its signal
-// are both passed back up: a wrapper that always exited 0 would break every
-// script that branches on the exit code, and inillucent's exit codes carry
-// meaning - 3 is "the engine has not built that".
-import { spawn } from 'node:child_process';
-import { resolveBinary } from '../resolve.mjs';
-
-let binary;
-try {
-  binary = resolveBinary('inillucent');
-} catch (why) {
-  process.stderr.write(String(why.message ?? why) + '\n');
-  process.exit(1);
-}
-
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
-child.on('error', (why) => {
-  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
-  process.exit(1);
-});
-child.on('exit', (code, signal) => {
-  if (signal) {
-    // Re-raise it on ourselves so a shell sees the same thing it would have
-    // seen from the real program, rather than a plain exit.
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// The `inillucent` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

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.32",
+  "version": "2.0.1",
   "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.32",
-    "@blackrainbowlabs/cli-darwin-arm64": "1.0.32",
-    "@blackrainbowlabs/cli-darwin-x64": "1.0.32",
-    "@blackrainbowlabs/cli-linux-x64": "1.0.32",
-    "@blackrainbowlabs/cli-linux-arm64": "1.0.32"
+    "@blackrainbowlabs/cli-win32-x64": "2.0.1",
+    "@blackrainbowlabs/cli-darwin-arm64": "2.0.1",
+    "@blackrainbowlabs/cli-darwin-x64": "2.0.1",
+    "@blackrainbowlabs/cli-linux-x64": "2.0.1",
+    "@blackrainbowlabs/cli-linux-arm64": "2.0.1"
   }
 }