@xeplr/actions 1.1.11 → 1.1.12

package/README.md

@@ -255,6 +255,24 @@ None published. The package has no HTTP routes (a host serves `list()`, e.g. `@x
 
 The repository has `scripts/upload-file.js` (not in the npm package) — a CLI that loads a CSV or Excel file into Postgres with `file-upload`; its header documents the flags (`--file`, `--table`, `--conn-name`, `--conn`, `--host`/`--port`/`--db`/`--user`/`--password`, `--encrypt-conn`).
 
+## Read-only connections — for SQL you did not write
+
+A report preview, a user's query, anything whose SQL text came from outside your own code: connect with `readOnly: true`.
+
+```js
+const pool = await driver.connect({ ...connection, readOnly: true })
+await driver.query(pool, userSql, params)          // reads only
+```
+
+| Driver | What `readOnly` does |
+|---|---|
+| postgres | every `query` and `fetchStream` runs inside `BEGIN TRANSACTION READ ONLY`, always rolled back, over the **extended protocol** — one statement only, so `…; COMMIT; DROP TABLE t` is refused, and nothing inside can switch the transaction back to read-write |
+| mysql | every connection the pool opens is set to `TRANSACTION READ ONLY`; `multipleStatements` stays off, so one statement per query |
+| mssql | `readOnlyIntent` (routes to a readable secondary where one exists) — **not enforcement**: SQL Server runs whole batches and has no session read-only mode. Give such SQL a login with only `db_datareader` |
+| duckdb | read-only unless `access: 'rw'` |
+
+**Values are bound, never written into SQL.** On MySQL, `stringifyObjects` is always on, so an object or array passed as a value is compared as text instead of being expanded into `key = value` pairs. **Procedure parameter names** are written into the call (`@region = @p0`, `region => $1`) and must be plain names — letters, digits and `_`.
+
 ## Rules the code enforces, and why
 
 | rule | why |

package/lib/drivers/db/mssql.js

@@ -87,6 +87,11 @@ async function connect(config) {
     pool:     { max: config.maxConnections || 10 },
     options:  Object.assign(
       { encrypt: true, trustServerCertificate: true },
+      // readOnly: ApplicationIntent=ReadOnly — routed to a readable secondary
+      // where there is one. It is NOT enforcement: SQL Server runs a whole
+      // batch and has no session-level read-only mode, so SQL the caller did
+      // not write needs a login that can only read (db_datareader). See README.
+      config.readOnly ? { readOnlyIntent: true } : {},
       config.options || {}
     )
   });

package/lib/drivers/db/mysql.js

@@ -89,8 +89,21 @@ async function connect(config) {
     timezone:          'Z',
     dateStrings:       true,
     supportBigNumbers: true,
-    bigNumberStrings:  true
+    bigNumberStrings:  true,
+    // A VALUE IS A VALUE. Without this mysql2 expands an object bound to `?`
+    // into `key` = value pairs and nested arrays into lists — so a filter value
+    // of {"a":1} rewrites the predicate instead of being compared to it.
+    stringifyObjects:  true
+    // multipleStatements stays at its default (off): one statement per query.
   });
+  // READ-ONLY CONNECTIONS — `connect({ ..., readOnly: true })` for SQL the
+  // caller did not write itself. Every connection the pool opens is put into
+  // read-only transaction mode before it is used, so a write fails.
+  if (config.readOnly) {
+    pool.pool.on('connection', function(conn) {
+      conn.query('SET SESSION TRANSACTION READ ONLY');
+    });
+  }
   return pool;
 }
 

package/lib/drivers/db/postgres.js

@@ -41,6 +41,17 @@ var TYPE_MAP = {
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
 
+// READ-ONLY CONNECTIONS — for SQL the caller did not write itself (a report
+// preview, a user's query). `connect({ ..., readOnly: true })` makes every
+// query and fetchStream on that pool:
+//
+//   • run inside BEGIN TRANSACTION READ ONLY, always rolled back — a write
+//     fails with "cannot execute … in a read-only transaction", and nothing
+//     inside the transaction can switch it back to read-write
+//   • go over the EXTENDED protocol, which carries exactly one statement — so
+//     `…; COMMIT; DROP TABLE t` is refused rather than run after the SELECT
+//     (the simple protocol, which pg uses when there are no parameters, runs
+//     every statement in the string)
 async function connect(config) {
   var pg = require('pg');
   var pool = new pg.Pool({
@@ -51,6 +62,7 @@ async function connect(config) {
     database: config.database,
     max:      config.maxConnections || 10
   });
+  if (config.readOnly) pool.__xeplrReadOnly = true;
   return pool;
 }
 
@@ -67,7 +79,19 @@ async function close(pool) {
 // this as the canonical shape the other drivers normalize TO, so replacing
 // the object risks dropping a property something else reads.
 async function query(pool, sql, params) {
-  var result = await pool.query(sql, params || []);
+  var result;
+  if (pool.__xeplrReadOnly) {
+    var client = await pool.connect();
+    try {
+      await client.query('BEGIN TRANSACTION READ ONLY');
+      result = await client.query({ text: sql, values: params || [], queryMode: 'extended' });
+    } finally {
+      try { await client.query('ROLLBACK'); } catch (_) { /* the connection is released either way */ }
+      client.release();
+    }
+  } else {
+    result = await pool.query(sql, params || []);
+  }
   result.columns = (result.fields || []).map(function(f) { return f.name; });
   return result;
 }
@@ -323,8 +347,13 @@ async function* fetchStream(pool, opts) {
   var client = await pool.connect();
   var declared = false;
   try {
-    await client.query('BEGIN');
-    await client.query('DECLARE __xeplr_fetch_cur NO SCROLL CURSOR FOR ' + opts.sql, opts.params || []);
+    var readOnly = Boolean(pool.__xeplrReadOnly);
+    await client.query(readOnly ? 'BEGIN TRANSACTION READ ONLY' : 'BEGIN');
+    // Extended protocol when read-only: one statement, so the caller's SQL
+    // cannot close the cursor declaration and carry on with its own.
+    await client.query(readOnly
+      ? { text: 'DECLARE __xeplr_fetch_cur NO SCROLL CURSOR FOR ' + opts.sql, values: opts.params || [], queryMode: 'extended' }
+      : 'DECLARE __xeplr_fetch_cur NO SCROLL CURSOR FOR ' + opts.sql, readOnly ? undefined : (opts.params || []));
     declared = true;
     while (true) {
       var res = await client.query('FETCH FORWARD ' + batchSize + ' FROM __xeplr_fetch_cur');
@@ -333,7 +362,7 @@ async function* fetchStream(pool, opts) {
     }
   } finally {
     try { if (declared) await client.query('CLOSE __xeplr_fetch_cur'); } catch (_) {}
-    try { await client.query('COMMIT'); } catch (_) {}
+    try { await client.query(pool.__xeplrReadOnly ? 'ROLLBACK' : 'COMMIT'); } catch (_) {}
     client.release();
   }
 }

package/lib/drivers/db/procedure.js

@@ -183,6 +183,12 @@ function buildProcedureCall(opts) {
   var marks = entries.map(function(p, i) {
     var mark = ph(i);
     if (!p.name || !supportsNames) return mark;
+    // Written into the call as text (`@region = @p0`, `region => $1`), so a
+    // plain name only — a saved or requested parameter name must not be able
+    // to close the call and start another statement.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(p.name))) {
+      throw new Error('procedure parameter name "' + String(p.name).slice(0, 40) + '" — use letters, digits and _ only');
+    }
     if (dbType === 'mssql') return '@' + p.name + ' = ' + mark;
     return p.name + ' => ' + mark;              // postgres named-argument call
   }).join(', ');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "files": [