@xeplr/actions 1.5.0 → 2.0.0

package/README.md

@@ -125,7 +125,7 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `emailDelete` | `email-delete` | Flag `\Deleted` **and expunge** — permanent, not a move to Trash. |
 | `emailDownloadEmail` | `email-download-email` | Stream the raw message to an `.eml` file, named by `fileName`. `{ count, saved[], path, existing[] }`. |
 | `emailDownloadAttachments` | `email-download-attachments` | Save attachments, optionally filtered by `extension` / `filenameContains`, named by `fileName` (see [Saving files](#saving-files-names-and-a-name-already-taken)). `{ count, saved[], path, skipped, existing[] }`. |
-| `fileList` | `file-list` | The files in a folder, optionally matching `pattern` (`*.csv`, `Bank-2026-??.pdf`), sorted by name or date. `{ files[{ name, path, size, modifiedAt }], count }`. "Is it there?" is the exact name and `count`. See [File steps](#file-steps-and-the-folders-they-may-use). |
+| `fileList` | `file-list` | The files in a folder, optionally matching `pattern` (`*.csv`, `Bank-2026-??.pdf`), sorted by name or date. `{ files[{ name, path, size, modifiedAt }], count }`. "Is it there?" is the exact name and `count`. See [Where files are](#where-files-are-one-data-root-a-folder-per-tenant). |
 | `fileRead` | `file-read` | A CSV, text, Excel, JSON or NDJSON file as rows (format from the extension). `{ rows, count, columns, truncated }`, at most `maxRows` (50,000). |
 | `fileMove` | `file-move` | Move or copy a file into a folder (made if missing) or to a new name; `ifExists` as every saving step. `{ path, name, moved, skipped }`. |
 | `fileDelete` | `file-delete` | Delete one file, **permanently** (no trash; `file-move` to a "processed" folder is the reversible one). Never a folder. `ifMissing`: `fail` (default) or `skip`. `{ path, deleted, skipped }`. |
@@ -283,18 +283,28 @@ await runAction({ name: 'http-request', input: {
 - **Bodies:** JSON by default; `bodyType: 'form'` or `'text'`. The answer is parsed as JSON when it is JSON, else text.
 - **Not yet:** paging through many pages of results.
 
-## File steps, and the folders they may use
+## Where files are: one data root, a folder per tenant
 
-`file-list`, `file-read`, `file-move` and `file-delete` take a path from whoever wrote the workflow, so they work **only inside the folders the install names** (`lib/fileRoots.js`):
+**`XEPLR_DATA_DIR` is required** (`requiredEnv` — spread it into your `env.required.js`). Every file any step reads or writes is inside the folder of the tenant the work runs as, and nowhere else (`lib/dataDir.js`):
 
-| | |
-|---|---|
-| `XEPLR_FILE_ROOTS` | Absolute folders, comma-separated: `/data/bank,/data/erp`. |
-| always allowed | `XEPLR_ACTIONS_TMP_DIR` (where downloads and exports land by default), so the next step can read what the last one saved. |
+```
+<XEPLR_DATA_DIR>/<applicationId>/<mtId1>/<mtId2>/…
+```
+
+- **The application** is the one registered with `@xeplr/db`'s `registerApplication()`, which a host calls at boot. A company id is minted per app, so company 42 of BI and company 42 of ERP never share a folder. No application registered → refused.
+- **The tenant** comes from the context every query runs in: a request after the membership gate, a job, or a workflow run (`runWithMt`). **Never from a step's input.** An app with no tenancy registered is one tenant: `<root>/<app>`.
+- **A step names files inside its folder:** `bank/inbox/sept.csv`. A full path is accepted only when it is already inside, such as what an earlier step returned (`file-list`'s `path`). Anything else is refused (`PATH_NOT_ALLOWED`): a path elsewhere, `../`, a symbolic link pointing out, or an address (`http://…`, `file://…`). `../` and links are followed to the real path before the check; a path that does not exist yet is checked by its nearest existing folder.
+- **`*` at a level** (a job for every company) is a folder of its own, `_all`, which no company's step reaches. **No tenant at all is refused** (`NO_TENANT`) — never the root — as a query with no tenant finds nothing.
+- **Temporary files** (db-fetch and email-read spools, uploader batches, an export or email download nobody named) go in the tenant's `tmp/`.
+- **Not defaulted:** a missing or relative `XEPLR_DATA_DIR`, or one that does not exist, is refused by name (`DATA_DIR_UNSET`). A wrong root that boots would read as empty data rather than as an error.
+
+Which inputs are checked: `file-list` `folder`; `file-read` / `file-delete` `path`; `file-move` `from` and `to`; `file-upload`'s local source (`sourcePath`, and every local-source operation); `db-push` `filePath`; `export-table` `rowsFile` and `outputPath`; `export-pages` `outputPath`; the email download steps' folder; and `email-send` attachments.
+
+**`email-send` attachments** are `{ filename, path }` (inside the folder) or `{ filename, content }`. `href` and `raw` are refused, and so is a body that is not text: the mail library reads `path`, `href` and `html: { path }` from disk or from the network, so an unchecked one would mail the server's own settings or fetch an internal address.
+
+`dataDir` is exported (`resolve(name)`, `tenantFolder()`, `scratch()`, `nameOf(path)`) for a host's own code that keeps files per tenant.
 
-- **Paths are absolute.** A relative one is refused: it would mean different files depending on where the server was started.
-- **No way out:** `../` and symbolic links are followed to the real path before it is checked; a target that does not exist yet is checked by its nearest existing folder.
-- **Not defaulted:** with no `XEPLR_FILE_ROOTS`, a path outside the temp folder is refused (`PATH_NOT_ALLOWED`), naming the setting. Why: without it, a workflow could read any file the server can, its own settings included.
+**From 1.x:** `XEPLR_FILE_ROOTS` and `XEPLR_ACTIONS_TMP_DIR` are gone. Set `XEPLR_DATA_DIR`, call `registerApplication()`, and run actions inside a tenant context (jobs and the workflow engine already do). A saved path outside the tenant's folder is refused until its files are moved in.
 
 ## Saving files: names, and a name already taken
 
@@ -358,7 +368,7 @@ await runAction(builtins.exportTable, {
 
 - **Streaming.** CSV and Excel stream rows to disk, from `rows` or from `rowsFile` (NDJSON, one row per line, as `streaming.spool` writes it); 200,000 rows to xlsx take about 2 s in flat memory. Our own xlsx writer runs on `fflate`. `exceljs` was rejected: it pulls a `uuid` with a published advisory and has had no release since December 2024.
 - **Fonts.** pdfkit's built-in fonts cannot draw `₹` or non-Latin text; a missing glyph draws as nothing. The PDF embeds **DejaVu Sans Condensed** (the `dejavu-fonts-ttf` peer). Pass `document.font` / `boldFont` (TTF/OTF paths) for scripts it lacks. Only the glyphs used are embedded.
-- **Output** goes to `outputPath`, or to a new directory under `XEPLR_ACTIONS_TMP_DIR` with a file named after the title. A failed export leaves no half-written file.
+- **Output** goes to `outputPath` (a name inside the tenant's folder), or to a new directory in its `tmp/` with a file named after the title. A failed export leaves no half-written file.
 
 `export-pages` lays out `pages: [{ blocks }]`, each block positioned by **fractions** of the page's content box (A4 landscape by default):
 - `text` (`text`, `size`, `bold`, `color`, `align`)
@@ -511,8 +521,7 @@ await actions.runAction(actions.builtins.dbPush, input, { metaStore: xcfg.metaSt
 
 | name | required? | meaning |
 |---|---|---|
-| `XEPLR_ACTIONS_TMP_DIR` | no | Where `db-fetch` and `email-read` spool NDJSON, email downloads go (unless `outDir`), and the uploader spools batches. Default `<os.tmpdir()>/xeplr-actions`. Files are not cleaned up by `db-fetch` or `email-read`. |
-| `XEPLR_FILE_ROOTS` | for `file-list`, `file-read`, `file-move`, `file-delete` outside the temp folder | Absolute folders, comma-separated, that file steps may use. See [File steps](#file-steps-and-the-folders-they-may-use). |
+| `XEPLR_DATA_DIR` | **yes** (`requiredEnv`) | The root of all data: absolute, existing. Each tenant's files are in `<root>/<app>/<mtId1>/…`, temporary ones in its `tmp/`. See [Where files are](#where-files-are-one-data-root-a-folder-per-tenant). Files are not cleaned up by `db-fetch` or `email-read`. |
 | `XCFG_DB_NAME` | for `attachConfig` | The `xeplr_configs` database name. In `configRequiredEnv`. |
 | `XCFG_DB_CONNECTION_INFO_ENCRYPTED` | no | Encrypted server login for `attachConfig`; overrides `XEPLR_DB_CONNECTION`. |
 | `XEPLR_DB_CONNECTION` | for `attachConfig`, unless the above is set | Shared encrypted server login. |
@@ -599,6 +608,7 @@ node --test test/uploader/reconcile.test.js
 
 - **No `*_HOST`:** that database's tests are **skipped**, and each says which settings run it.
 - **`*_HOST` set:** they run, and a login the database refuses **fails** them. A configured run never passes by not connecting.
+- **A data root and an application per test process** (`--require ./test/setup-data-dir.cjs`, in `npm test`, CI, and the gate through `@flags` on `test/data-dir.test.js`), as an app has at boot. `test/data-dir.test.js` registers tenants: two companies with the same names, each refused the other's files by full path, `../`, a link and a move; `*` and no tenant; email attachments, db-push and a local upload.
 - **One file at a time** (`--test-concurrency=1`): the database suites share the `xeplr_actions_test` database and race to create it when run side by side.
 - **Why:** these files used to carry a fixed host, port and password each (Postgres on `:5435`). On any other machine they all failed, so the pre-commit gate and CI ran only `test/*.test.js` and never this package's sub-folders. That is how `data-operation` shipped returning no rows (fixed in 1.4.2).
 

package/index.js

@@ -56,5 +56,12 @@ module.exports = {
   // lib/uploader/attach.js. configRequiredEnv spreads into the app's own
   // env.required.js, same convention as @xeplr/auth's requiredEnv.
   attachConfig:      configDb.attachConfig,
-  configRequiredEnv: configDb.requiredEnv
+  configRequiredEnv: configDb.requiredEnv,
+
+  // WHERE FILES ARE: XEPLR_DATA_DIR, one folder per tenant under it
+  // (<root>/<app>/<mtId1>/…). requiredEnv spreads into the app's
+  // env.required.js — the root is never defaulted. dataDir.resolve(name)
+  // is the one check every file path goes through (lib/dataDir.js).
+  requiredEnv:       require('./lib/dataDir').requiredEnv,
+  dataDir:           require('./lib/dataDir')
 };

package/lib/builtins/db/fetch.js

@@ -14,13 +14,12 @@
 //   modes:
 //     'table'  → SELECT * FROM <table>            (input.table required)
 //     'query'  → raw input.sql (+ input.params)   (input.sql required)
-//   Temp file: XEPLR_ACTIONS_TMP_DIR (default os.tmpdir()/xeplr-actions),
+//   Temp file: the tenant's tmp/ under XEPLR_DATA_DIR (lib/dataDir.js),
 //   named <occurrenceId>_db-fetch_<seq>.jsonl. Cleanup: none in-action — rely
 //   on the sweep-temp-files action (or db-push after it consumes the file).
 
 var dbDrivers  = require('../../drivers/db');
 var { generateId } = require('@xeplr/utils/lib/helpers');
-var os = require('os');
 var path = require('path');
 var fs = require('fs');
 var fsp = require('fs/promises');
@@ -137,8 +136,8 @@ function buildFetchSql(driver, input) {
 
 
 async function resolveOutputPath(system) {
-  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
-  await fsp.mkdir(dir, { recursive: true });
+  // The tenant's own temporary folder (lib/dataDir.js).
+  var dir = require('../../dataDir').scratch();
   var base = (system.occurrenceId || generateId()) + '_db-fetch_' + generateId() + '.jsonl';
   return path.join(dir, base);
 }

package/lib/builtins/db/push.js

@@ -99,7 +99,7 @@ module.exports = {
 // Return an async iterable for whichever input shape the caller supplied.
 function resolveSource(input) {
   if (Array.isArray(input.rows) && input.rows.length > 0) return asyncFromArray(input.rows);
-  if (input.filePath)                                     return asyncFromNDJSONFile(input.filePath);
+  if (input.filePath)                                     return asyncFromNDJSONFile(require('../../dataDir').resolve(input.filePath, 'The rows file'));
   throw new Error('db-push: either input.rows (non-empty) or input.filePath is required');
 }
 

package/lib/builtins/email/download-attachments.js

@@ -34,7 +34,7 @@ module.exports = {
     { name: 'folder',           type: 'string', default: 'INBOX', order: 4,
       description: 'Folder the message is currently in — where its id is valid.' },
     { name: 'outDir',           type: 'string', order: 5,
-      description: 'Directory to write into. Defaults to XEPLR_ACTIONS_TMP_DIR.' },
+      description: 'A folder in this company\'s data folder, e.g. mail/attachments. Default: its tmp/ folder.' },
 
     { name: 'extension',        type: 'string', order: 6, group: 'Filters',
       description: 'Only attachments with this extension, e.g. "pdf" or ".pdf".' },

package/lib/builtins/email/download-email.js

@@ -32,7 +32,7 @@ module.exports = {
     { name: 'folder',     type: 'string', default: 'INBOX', order: 4,
       description: 'Folder the message is currently in — where its id is valid.' },
     { name: 'outDir',     type: 'string', order: 5,
-      description: 'Directory to write into. Defaults to XEPLR_ACTIONS_TMP_DIR.' }
+      description: 'A folder in this company\'s data folder, e.g. mail/attachments. Default: its tmp/ folder.' }
   ].concat(fileNames.nameInputs(6, '[subject], [id] (the message), [ext] (eml)')),
 
   execute: async function(ctx) {

package/lib/builtins/email/read.js

@@ -5,7 +5,7 @@
 // the normal case is a handful of messages a workflow branches on immediately.
 // Set streaming_mode:true when pulling bodies in bulk — HTML mail with inline
 // base64 images is large, and spooling keeps it off the heap and out of the
-// run record. Temp file: XEPLR_ACTIONS_TMP_DIR, same as db-fetch.
+// run record. Temp file: the tenant's tmp/ (lib/dataDir.js), same as db-fetch.
 //
 // COST CONTROL is `body`, not `limit`. body:'none' skips downloading message
 // sources entirely and fetches envelopes only — the right setting for a
@@ -14,7 +14,6 @@
 var emailDrivers = require('../../drivers/email');
 var emailConfig = require('../../drivers/email/config');
 var crypto = require('crypto');
-var os = require('os');
 var path = require('path');
 var fs = require('fs');
 var fsp = require('fs/promises');
@@ -92,8 +91,8 @@ module.exports = {
 // ─── helpers ────────────────────────────────────────────────────────────
 
 async function resolveOutputPath(system) {
-  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
-  await fsp.mkdir(dir, { recursive: true });
+  // The tenant's own temporary folder (lib/dataDir.js).
+  var dir = require('../../dataDir').scratch();
   var base = (system.occurrenceId || crypto.randomBytes(6).toString('hex'))
     + '_email-read_' + crypto.randomBytes(6).toString('hex') + '.jsonl';
   return path.join(dir, base);

package/lib/builtins/export/pages.js

@@ -11,7 +11,6 @@
 // of a raster type — no fetching, no markup.
 
 var fs = require('fs');
-var os = require('os');
 var path = require('path');
 var pdf = require('../../formats/writers/pdf');
 var { checkFormatRequires } = require('../../formats');
@@ -91,9 +90,11 @@ module.exports = {
     checkFormatRequires('export-pages', 'pdf', pdf);
     validate(input);
     var name = (String(input.title || 'dashboard').replace(/[\\/:*?"<>|\u0000-\u001F]+/g, ' ').trim().slice(0, 80) || 'dashboard') + '.pdf';
-    var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
-    fs.mkdirSync(dir, { recursive: true });
-    var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(dir, 'export-')), name);
+    // Inside the tenant's own folder (lib/dataDir.js): a name the step gives,
+    // or a new file in its tmp/.
+    var dataDir = require('../../dataDir');
+    var filePath = input.outputPath ? dataDir.resolve(input.outputPath, 'Where to save it')
+      : path.join(fs.mkdtempSync(path.join(dataDir.scratch(), 'export-')), name);
     var done = await pdf.renderPages(filePath, {
       pages: input.pages, title: input.title, footer: input.footer, landscape: input.landscape !== false,
       page: input.page || null

package/lib/builtins/export/table.js

@@ -17,18 +17,13 @@
 // default) because a page is laid out from them.
 
 var fs = require('fs');
-var os = require('os');
 var path = require('path');
 var readline = require('readline');
 var writers = require('../../formats/writers');
 var { checkFormatRequires } = require('../../formats');
 var fileNames = require('../../fileNames');
 
-function tmpDir() {
-  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
-}
+var dataDir = require('../../dataDir');
 
 /** A file name from a title: what a person would recognise in their downloads. */
 function fileNameFor(title, extension) {
@@ -50,7 +45,7 @@ function asRow(row, columns) {
 
 async function* rowsFrom(input, columns) {
   if (Array.isArray(input.rows)) { for (var i = 0; i < input.rows.length; i++) yield asRow(input.rows[i], columns); return; }
-  var lines = readline.createInterface({ input: fs.createReadStream(input.rowsFile), crlfDelay: Infinity });
+  var lines = readline.createInterface({ input: fs.createReadStream(dataDir.resolve(input.rowsFile, 'The rows file')), crlfDelay: Infinity });
   for await (var line of lines) if (line.trim()) yield asRow(JSON.parse(line), columns);
 }
 
@@ -80,7 +75,7 @@ module.exports = {
       description: 'An NDJSON file with one row per line, instead of rows.' },
     { name: 'outputPath', type: 'string', order: 5,
       description: 'Where to write, e.g. /data/recon/Recon-{trigger.window.from|date:YYYY-MM}.xlsx. ' +
-                   'Default: a new file in XEPLR_ACTIONS_TMP_DIR named after the title.' },
+                   'In this company\'s data folder, e.g. exports/sales.xlsx. Default: a new file in its tmp/ folder named after the title.' },
     { name: 'ifExists', type: 'string', order: 7, default: 'fail', options: fileNames.IF_EXISTS,
       description: 'When outputPath is already there. fail: the step fails and nothing is written. skip: left alone ' +
                    '(skipped: true). overwrite: replaced. addSuffix: "name (2).xlsx".' },
@@ -115,7 +110,9 @@ module.exports = {
 
     var info = writers.INFO[format];
     var fileName = fileNameFor(doc.title, info.extension);
-    var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(tmpDir(), 'export-')), fileName);
+    // A name the step gives is inside the tenant's folder; none, its tmp/.
+    var filePath = input.outputPath ? dataDir.resolve(input.outputPath, 'Where to save it')
+      : path.join(fs.mkdtempSync(path.join(dataDir.scratch(), 'export-')), fileName);
     if (input.outputPath) {
       // The same rule as every action that saves a file (lib/fileNames.js):
       // a name already taken is never silently replaced.

package/lib/builtins/file/delete.js

@@ -3,11 +3,11 @@
 // A file a workflow has finished with: the bank file read and posted, so the
 // next check of the folder does not find it again. PERMANENT — there is no
 // trash to take it back from; file-move into a "processed" folder is the one
-// that can be undone. Only inside the folders file steps may use
-// (lib/fileRoots.js), and only a file, never a folder.
+// that can be undone. Only inside the tenant's own folder (lib/dataDir.js),
+// and only a file, never a folder.
 
 var fs = require('fs');
-var fileRoots = require('../../fileRoots');
+var dataDir = require('../../dataDir');
 
 module.exports = {
   name: 'file-delete',
@@ -15,7 +15,7 @@ module.exports = {
   requires: [],
   inputSchema: [
     { name: 'path', type: 'string', required: true, order: 1,
-      description: 'The file, by absolute path, e.g. {item.path}.' },
+      description: 'The file, in this company\'s data folder, e.g. {item.path}.' },
     { name: 'ifMissing', type: 'string', default: 'fail', options: ['fail', 'skip'], order: 2,
       description: 'When there is no such file. fail: the step fails. skip: it goes on, deleted false.' }
   ],
@@ -25,7 +25,7 @@ module.exports = {
 
   execute: async function(ctx) {
     var input = ctx.input || {};
-    var file = fileRoots.allowed(input.path, 'The file to delete');
+    var file = dataDir.resolve(input.path, 'The file to delete');
     if (!fs.existsSync(file)) {
       if (input.ifMissing === 'skip') return { path: file, deleted: false, skipped: true };
       var missing = new Error('"' + input.path + '" is not a file that exists.');

package/lib/builtins/file/list.js

@@ -1,11 +1,11 @@
 // file-list action — the files in a folder, optionally matching a pattern.
 //
 // Also the way to ask "is it there yet?": list with the exact name and branch
-// on output.count. Only inside the folders file steps may use (lib/fileRoots.js).
+// on output.count. Only inside the tenant's own folder (lib/dataDir.js).
 
 var fs = require('fs');
 var path = require('path');
-var fileRoots = require('../../fileRoots');
+var dataDir = require('../../dataDir');
 
 /** `*.csv`, `Bank-2026-??.pdf` → a test on a name. Case-insensitive. */
 function matcher(pattern) {
@@ -25,7 +25,7 @@ module.exports = {
   requires: [],
   inputSchema: [
     { name: 'folder', type: 'string', required: true, order: 1,
-      description: 'An absolute folder inside XEPLR_FILE_ROOTS, e.g. /data/bank.' },
+      description: 'A folder in this company\'s data folder, e.g. bank/inbox.' },
     { name: 'pattern', type: 'string', order: 2,
       description: 'Only names matching this: * any characters, ? one. E.g. Bank-{trigger.window.from|date:YYYY-MM}*.csv' },
     { name: 'sort', type: 'string', default: 'name', options: ['name', 'newest', 'oldest'], order: 3,
@@ -38,7 +38,7 @@ module.exports = {
 
   execute: async function(ctx) {
     var input = ctx.input || {};
-    var dir = fileRoots.allowed(input.folder, 'The folder');
+    var dir = dataDir.resolve(input.folder, 'The folder');
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
       var missing = new Error('"' + input.folder + '" is not a folder that exists.');
       missing.code = 'NOT_A_FOLDER';

package/lib/builtins/file/move.js

@@ -1,13 +1,13 @@
 // file-move action — move or copy a file, into a folder or to a new name.
 //
 // "Processed" folders, an archive by month, a copy for another team. Only
-// inside the folders file steps may use (lib/fileRoots.js), at both ends. A
+// inside the tenant's own folder (lib/dataDir.js), at both ends. A
 // name already taken at the target follows the rule every file-writing step
 // follows (lib/fileNames.js): fail by default.
 
 var fs = require('fs');
 var path = require('path');
-var fileRoots = require('../../fileRoots');
+var dataDir = require('../../dataDir');
 var fileNames = require('../../fileNames');
 
 module.exports = {
@@ -16,9 +16,9 @@ module.exports = {
   requires: [],
   inputSchema: [
     { name: 'from', type: 'string', required: true, order: 1,
-      description: 'The file, by absolute path, e.g. {steps.save.output.path}.' },
+      description: 'The file, in this company\'s data folder, e.g. {item.path}.' },
     { name: 'to', type: 'string', required: true, order: 2,
-      description: 'A folder (it keeps its name), or a full path to rename it, e.g. /data/archive/{trigger.window.from|date:YYYY-MM}/' },
+      description: 'A folder (it keeps its name; end it with /), or a new name for it, e.g. archive/{trigger.window.from|date:YYYY-MM}/' },
     { name: 'operation', type: 'string', default: 'move', options: ['move', 'copy'], order: 3,
       description: 'move: it is no longer where it was. copy: it is in both places.' },
     { name: 'ifExists', type: 'string', default: 'fail', options: fileNames.IF_EXISTS, order: 4,
@@ -32,15 +32,16 @@ module.exports = {
 
   execute: async function(ctx) {
     var input = ctx.input || {};
-    var from = fileRoots.allowed(input.from, 'The file to move');
+    var from = dataDir.resolve(input.from, 'The file to move');
     if (!fs.existsSync(from) || !fs.statSync(from).isFile()) {
       var missing = new Error('"' + input.from + '" is not a file that exists.');
       missing.code = 'FILE_NOT_FOUND';
       throw missing;
     }
     // A folder: ends with a separator, or is one already.
-    var toIsFolder = /[\/\\]$/.test(input.to) || (fs.existsSync(input.to) && fs.statSync(input.to).isDirectory());
-    var dir = fileRoots.allowed(toIsFolder ? input.to : path.dirname(input.to), 'The target folder');
+    var target = dataDir.resolve(input.to, 'Where it goes');
+    var toIsFolder = /[\/\\]$/.test(input.to) || (fs.existsSync(target) && fs.statSync(target).isDirectory());
+    var dir = toIsFolder ? target : path.dirname(target);
     fs.mkdirSync(dir, { recursive: true });
     var wanted = toIsFolder ? path.basename(from) : fileNames.safeName(path.basename(input.to));
     var place = fileNames.plan(dir, [wanted], input.ifExists)[0];

package/lib/builtins/file/read.js

@@ -1,14 +1,14 @@
 // file-read action — a CSV, Excel, JSON or NDJSON file as rows.
 //
 // What the next step works with: the data step filters them, export-table
-// writes them, a matcher compares them. Only inside the folders file steps may
-// use (lib/fileRoots.js). Bounded by maxRows, because a step's output is
+// writes them, a matcher compares them. Only inside the tenant's own folder
+// (lib/dataDir.js). Bounded by maxRows, because a step's output is
 // stored with the run.
 
 var path = require('path');
 var fs = require('fs');
 var readline = require('readline');
-var fileRoots = require('../../fileRoots');
+var dataDir = require('../../dataDir');
 var formats = require('../../formats');
 
 var BY_EXTENSION = { csv: 'csv', txt: 'txt', tsv: 'txt', xlsx: 'excel', xls: 'excel', json: 'json', ndjson: 'ndjson', jsonl: 'ndjson' };
@@ -24,7 +24,7 @@ module.exports = {
   requires: [],
   inputSchema: [
     { name: 'path', type: 'string', required: true, order: 1,
-      description: 'An absolute file path inside XEPLR_FILE_ROOTS, e.g. {steps.save.output.path}.' },
+      description: 'A file in this company\'s data folder, e.g. bank/inbox/sept.csv or {item.path}.' },
     { name: 'format', type: 'string', order: 2, options: ['csv', 'txt', 'excel', 'json', 'ndjson'],
       description: 'Empty: from the file\'s extension.' },
     { name: 'sheet', type: 'string', order: 3, group: 'Excel',
@@ -40,7 +40,7 @@ module.exports = {
 
   execute: async function(ctx) {
     var input = ctx.input || {};
-    var file = fileRoots.allowed(input.path, 'The file');
+    var file = dataDir.resolve(input.path, 'The file');
     if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
       var missing = new Error('"' + input.path + '" is not a file that exists.');
       missing.code = 'FILE_NOT_FOUND';

package/lib/builtins/index.js

@@ -9,7 +9,7 @@
 //     in the output.
 //   - When false, data stays inline in output.rows / output.content.
 //   - Writes may accept EITHER `rows: []` OR a spooled `filePath`/`dirPath`.
-//   - Temp dir: XEPLR_ACTIONS_TMP_DIR env var, default os.tmpdir() + '/xeplr-actions/'.
+//   - Files: inside the tenant's own folder under XEPLR_DATA_DIR (lib/dataDir.js); temp in its tmp/.
 //
 // Uploader primitive (lib/uploader/) handles DDL, type inference, TZ, batch
 // bisection, and error-table routing. The DB actions here compose it with

package/lib/builtins/send-email.js

@@ -3,16 +3,47 @@
 // Peer dep: `nodemailer`, lazy-required inside the driver so a read-only
 // deployment never has to install it.
 //
-// ATTACHMENTS take nodemailer's own descriptors — { filename, path },
-// { filename, content }, { filename, href } — which is why the output of
-// email-download-attachments (`saved[]`, each with filename + path) can be
-// passed straight back in to forward what was just downloaded.
+// ATTACHMENTS are { filename, path } or { filename, content } — which is why
+// the output of email-download-attachments (`saved[]`, each with filename +
+// path) can be passed straight back in to forward what was just downloaded.
+//
+// A PATH IS A FILE IN THE TENANT'S OWN FOLDER (lib/dataDir.js), never anywhere
+// on the server and never an address: nodemailer reads whatever `path` names,
+// a file or a URL, so an unchecked one would mail the server's own settings to
+// anyone, or fetch an internal address. `href` is refused for the same reason,
+// and the body must be text — nodemailer reads `html: { path }` from disk too.
 //
 // `accepted` / `rejected` are both returned. SMTP accepts per-recipient, so a
 // send can succeed at the protocol level while dropping half its recipients;
 // reporting only success would hide that.
 
 var emailDrivers = require('../drivers/email');
+var dataDir = require('../dataDir');
+
+function bad(message) {
+  var err = new Error(message);
+  err.code = 'PATH_NOT_ALLOWED';
+  return err;
+}
+
+/** Each attachment, with its path checked; anything that would read elsewhere refused. */
+function safeAttachments(list) {
+  if (list === undefined || list === null) return list;
+  if (!Array.isArray(list)) throw bad('Attachments must be a list of { filename, path } or { filename, content }.');
+  return list.map(function(a, i) {
+    if (!a || typeof a !== 'object') throw bad('Attachment ' + (i + 1) + ' must be { filename, path } or { filename, content }.');
+    if (a.href !== undefined || a.raw !== undefined) throw bad('Attachment ' + (i + 1) + ' names an address; attach a file from this company\'s folder instead.');
+    var out = {};
+    ['filename', 'content', 'contentType', 'encoding', 'cid', 'contentDisposition'].forEach(function(k) { if (a[k] !== undefined) out[k] = a[k]; });
+    if (a.path !== undefined) out.path = dataDir.resolve(String(a.path), 'Attachment ' + (i + 1));
+    if (out.path === undefined && out.content === undefined) throw bad('Attachment ' + (i + 1) + ' has neither a path nor content.');
+    return out;
+  });
+}
+
+function textOnly(value, what) {
+  if (value !== undefined && value !== null && typeof value !== 'string') throw bad('The ' + what + ' must be text.');
+}
 var emailConfig = require('../drivers/email/config');
 
 module.exports = {
@@ -68,7 +99,7 @@ module.exports = {
       showWhen: { field: 'templateName', isSet: false },
       description: 'Plain-text body, as an alternative to html.' },
     { name: 'attachments', type: 'array',  order: 9, group: 'Message options',
-      description: 'Nodemailer attachment descriptors, e.g. [{ filename, path }].' },
+      description: 'Files to attach, e.g. [{ filename, path }] — path in this company\'s data folder, such as {steps.save.output.filePath}.' },
 
     { name: 'cc',          type: 'array',  order: 10, group: 'More addresses',
       description: 'CC addresses.' },
@@ -82,6 +113,11 @@ module.exports = {
 
   execute: async function(ctx) {
     var input = ctx.input || {};
+    // Before anything is opened or rendered: a body that is not text, or an
+    // attachment outside this company's folder, is refused here.
+    textOnly(input.html, 'body (html)');
+    textOnly(input.text, 'body (text)');
+    if (input.attachments !== undefined) input = Object.assign({}, input, { attachments: safeAttachments(input.attachments) });
 
     // A template supplies subject/html/text; anything typed on the step is
     // OVERRIDDEN rather than merged, so "which subject actually went out" has

package/lib/dataDir.js

@@ -0,0 +1,135 @@
+// WHERE A STEP'S FILES ARE — one data root, one folder per tenant.
+//
+//   XEPLR_DATA_DIR   the root of all data, absolute, required (requiredEnv)
+//
+// Every file a step reads or writes is inside the folder of the tenant the
+// work runs as, and nowhere else:
+//
+//   <XEPLR_DATA_DIR>/<applicationId>/<mtId1>/<mtId2>/…
+//
+// The application comes from @xeplr/db's registerApplication (a company id is
+// minted per app, so company 42 of BI and company 42 of ERP are two tenants);
+// the tenant from the context every query already runs in — a request after
+// the membership gate, a job or a workflow run (runWithMt). Never from a
+// step's input: a step names `bank/inbox/sept.csv`, and cannot name anything
+// outside its own folder.
+//
+//   a name           bank/inbox/sept.csv → inside the folder
+//   a full path      accepted only when it is inside the folder already (what
+//                    an earlier step returned: file-list's `path`)
+//   '*' at a level   `_all` — a job for every company has a folder of its own,
+//                    and no company's step can reach it
+//   no tenant        refused, as a query with no tenant finds nothing; never
+//                    the root
+//
+// `..` and symlinks are resolved before the check, so neither steps out.
+// NOT DEFAULTED: "Where data lives is never defaulted." A missing or relative
+// XEPLR_DATA_DIR is refused by name, and so is one that does not exist — a
+// wrong root that boots reads as empty data, not as an error.
+
+var fs = require('fs');
+var path = require('path');
+
+var VAR = 'XEPLR_DATA_DIR';
+var requiredEnv = [VAR];
+var ALL = '_all';
+var SCRATCH = 'tmp';
+
+function refused(message, code) {
+  var err = new Error(message);
+  err.code = code || 'PATH_NOT_ALLOWED';
+  err.status = 400;
+  return err;
+}
+
+function db() { return require('@xeplr/db'); }
+
+/** The data root, absolute and real. */
+function root() {
+  var dir = process.env[VAR];
+  if (!dir || !String(dir).trim()) {
+    throw refused(VAR + ' is not set: it is the folder all data lives under (absolute), e.g. /srv/xeplr-data.', 'DATA_DIR_UNSET');
+  }
+  if (!path.isAbsolute(dir)) throw refused(VAR + ' must be an absolute folder, and "' + dir + '" is not one.', 'DATA_DIR_UNSET');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    throw refused(VAR + ' is "' + dir + '", which is not a folder that exists. Create it, or point ' + VAR + ' at the one that holds the data.', 'DATA_DIR_UNSET');
+  }
+  return fs.realpathSync(dir);
+}
+
+// An id becomes a folder name as it is. One that could not be one — or could
+// climb out (`..`) — is refused rather than cleaned up into someone else's.
+function segment(value, what) {
+  if (value === '*') return ALL;
+  var s = value === null || value === undefined ? '' : String(value);
+  if (!/^[A-Za-z0-9_.-]{1,100}$/.test(s) || s === '.' || s === '..') {
+    throw refused('The ' + what + ' "' + s + '" cannot name a folder.', 'NO_TENANT');
+  }
+  return s;
+}
+
+/**
+ * The folder the current work may use: <root>/<app>/<mtId1>/…, made if it is
+ * not there yet. An app with no tenancy registered is one tenant: <root>/<app>.
+ */
+function tenantFolder() {
+  var x = db();
+  var app = x.getApplicationId();
+  if (!app) throw refused('No application is registered (registerApplication), so there is no folder for its files.', 'NO_TENANT');
+  var parts = [root(), segment(app, 'application')];
+  var levels = x.getMtConfig().levels || 0;
+  var ctx = x.getMtContext() || {};
+  for (var i = 1; i <= levels; i++) {
+    var v = ctx['mtId' + i];
+    if (v === undefined || v === null || v === '') {
+      throw refused('This work runs as no tenant, so it has no folder: files are only ever inside the folder of the company it runs for.', 'NO_TENANT');
+    }
+    parts.push(segment(v, 'tenant id'));
+  }
+  var dir = path.join.apply(path, parts);
+  fs.mkdirSync(dir, { recursive: true });
+  return fs.realpathSync(dir);
+}
+
+/** The tenant's own temporary folder: spools, downloads, exports nobody named. */
+function scratch() {
+  var dir = path.join(tenantFolder(), SCRATCH);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function inside(real, folder) {
+  return real === folder || real.indexOf(folder + path.sep) === 0;
+}
+
+/**
+ * A name (or a full path already inside the folder) → the real absolute path,
+ * inside the tenant's folder; refused otherwise. A path that does not exist
+ * yet (a move's target, an export) is checked by its nearest existing parent,
+ * so `../` and symlinks cannot step out.
+ */
+function resolve(p, what) {
+  if (!p || typeof p !== 'string' || !p.trim()) throw refused((what || 'A path') + ' is required.');
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(p)) throw refused((what || 'The path') + ' "' + p + '" is an address, not a file in this company\'s folder.');
+  var folder = tenantFolder();
+  var resolved = path.isAbsolute(p) ? path.resolve(p) : path.resolve(folder, p);
+  var probe = resolved;
+  var rest = '';
+  while (!fs.existsSync(probe) && path.dirname(probe) !== probe) {
+    rest = path.join(path.basename(probe), rest);
+    probe = path.dirname(probe);
+  }
+  var real = path.join(fs.realpathSync(probe), rest);
+  if (!inside(real, folder)) {
+    throw refused((what || 'The path') + ' "' + p + '" is outside this company\'s folder. Name it inside, e.g. bank/inbox/statement.csv.');
+  }
+  return real;
+}
+
+/** The name a path has inside the tenant's folder — what a screen shows. */
+function nameOf(real) {
+  var folder = tenantFolder();
+  return inside(real, folder) ? path.relative(folder, real) : null;
+}
+
+module.exports = { VAR: VAR, requiredEnv: requiredEnv, ALL: ALL, root: root, tenantFolder: tenantFolder, scratch: scratch, resolve: resolve, nameOf: nameOf };

package/lib/drivers/email/files.js

@@ -1,7 +1,7 @@
 // Shared on-disk helpers for the email actions that write files
 // (email-download-email, email-download-attachments).
 //
-// Output goes to XEPLR_ACTIONS_TMP_DIR — the SAME directory db-fetch spools
+// Output goes to the tenant's tmp/ (lib/dataDir.js) — the SAME directory db-fetch spools
 // NDJSON into — so every artifact an action leaves behind is swept by one
 // mechanism rather than one per action family. An explicit `outDir` input
 // still wins for the case where a later step (or another service) needs the
@@ -11,7 +11,6 @@ var crypto = require('crypto');
 var path   = require('path');
 var fs     = require('fs');
 var fsp    = require('fs/promises');
-var os     = require('os');
 var fileNames = require('../../fileNames');
 
 // Short random prefix. Attachment names collide constantly in mail —
@@ -34,10 +33,12 @@ function sanitizeFilename(name) {
   return out;
 }
 
-// Explicit outDir wins; otherwise the same temp root the rest of the actions
-// use. Created recursively — a first run has no directory yet.
+// A folder named by the step, inside the tenant's own folder; otherwise the
+// tenant's temporary folder (lib/dataDir.js). Created recursively — a first
+// run has no directory yet.
 async function resolveOutDir(outDir) {
-  var dir = outDir || process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+  var dataDir = require('../../dataDir');
+  var dir = outDir ? dataDir.resolve(outDir, 'The folder to save into') : dataDir.scratch();
   await fsp.mkdir(dir, { recursive: true });
   return dir;
 }

package/lib/drivers/file/local.js

@@ -7,18 +7,22 @@
 // deleteFile(config)                 → void
 //
 // `config.path` is the file/dir path — local source config is intentionally
-// minimal since fs handles most concerns natively.
+// minimal since fs handles most concerns natively. Every path is inside the
+// tenant's own folder (lib/dataDir.js): a name, or a full path already in it.
 
 var fs = require('fs');
 var fsp = require('fs/promises');
 var path = require('path');
+var dataDir = require('../../dataDir');
+
+function at(p, what) { return dataDir.resolve(p, what || 'The file'); }
 
 module.exports = {
   requires: [],
 
   async openStream(config) {
     if (!config || !config.path) throw new Error('local source: config.path is required');
-    return fs.createReadStream(config.path, config.encoding ? { encoding: config.encoding } : {});
+    return fs.createReadStream(at(config.path), config.encoding ? { encoding: config.encoding } : {});
   },
 
   // Formats that need random access (e.g. .xlsx via unzipper — the zip central
@@ -27,29 +31,31 @@ module.exports = {
   // must implement this by downloading to a caller-provided tmp path.
   async openPath(config) {
     if (!config || !config.path) throw new Error('local source: config.path is required');
-    return config.path;
+    return at(config.path);
   },
 
   async writeFile(config, opts) {
     if (!config.path) throw new Error('local source: config.path is required for writeFile');
     if (opts.filePath) {
-      await fsp.copyFile(opts.filePath, config.path);
-      return { bytes: (await fsp.stat(config.path)).size };
+      var to = at(config.path);
+      await fsp.copyFile(at(opts.filePath, 'The file to copy'), to);
+      return { bytes: (await fsp.stat(to)).size };
     }
     if (opts.content != null) {
-      await fsp.writeFile(config.path, opts.content);
+      await fsp.writeFile(at(config.path), opts.content);
       return { bytes: Buffer.byteLength(opts.content) };
     }
     throw new Error('local source: writeFile requires opts.content or opts.filePath');
   },
 
   async listFiles(config) {
-    var entries = await fsp.readdir(config.path, { withFileTypes: true });
+    var dir = at(config.path, 'The folder');
+    var entries = await fsp.readdir(dir, { withFileTypes: true });
     var out = [];
     for (var i = 0; i < entries.length; i++) {
       var e = entries[i];
       if (!e.isFile()) continue;
-      var full = path.join(config.path, e.name);
+      var full = path.join(dir, e.name);
       var stat = await fsp.stat(full);
       out.push({ name: e.name, path: full, size: stat.size, mtime: stat.mtime.toISOString() });
     }
@@ -58,11 +64,11 @@ module.exports = {
 
   async moveFile(_config, opts) {
     if (!opts || !opts.from || !opts.to) throw new Error('local source: moveFile requires from + to');
-    await fsp.rename(opts.from, opts.to);
+    await fsp.rename(at(opts.from, 'The file to move'), at(opts.to, 'Where it goes'));
   },
 
   async deleteFile(config) {
     if (!config.path) throw new Error('local source: config.path is required for deleteFile');
-    await fsp.unlink(config.path);
+    await fsp.unlink(at(config.path));
   }
 };

package/lib/uploader/index.js

@@ -26,7 +26,7 @@
 //                       // (filename, connectionId, who ran it, ...) the engine itself
 //                       // has no business knowing about
 //     errorTable,      // defaults to `<targetTable>_import_errors`
-//     batchDir,        // where NDJSON files spool to. Defaults to os.tmpdir()/xeplr-actions
+//     batchDir,        // where NDJSON files spool to. Defaults to the tenant's tmp/ (lib/dataDir.js)
 //     keepBatchFiles,  // default false — clean up NDJSON files after success
 //     replaceFrom,     // optional, staged only: { column } — the move deletes target
 //                       // rows from the earliest staged value on first (see mergeStaged)
@@ -59,7 +59,6 @@
 //
 // See project_xeplr_actions_streaming.md for the full contract.
 
-var os = require('os');
 var path = require('path');
 var fsp = require('fs/promises');
 
@@ -468,8 +467,8 @@ function normalizeOptions(opts) {
   opts.metaStore          = opts.metaStore          || require('./meta-store-noop');
   opts.errorTable         = opts.errorTable         || (opts.targetTable + '_import_errors');
   opts.connectionName     = opts.connectionName     || opts.targetTable;
-  opts.batchDir           = opts.batchDir           ||
-    (process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions'));
+  // The tenant's own temporary folder (lib/dataDir.js) unless the host names one.
+  opts.batchDir           = opts.batchDir           || require('../dataDir').scratch();
   opts.keepBatchFiles     = !!opts.keepBatchFiles;
   opts.staged             = !!opts.staged;
   // A driver that matches upsert keys only in a staged move (DuckDB: its

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {
-    "test": "node --test --test-concurrency=1 \"test/**/*.test.js\""
+    "test": "node --test --test-concurrency=1 --require ./test/setup-data-dir.cjs \"test/**/*.test.js\""
   },
   "files": [
     "index.js",

package/lib/fileRoots.js

@@ -1,71 +0,0 @@
-// WHERE A FILE STEP MAY LOOK.
-//
-// file-list, file-read and file-move take a path from whoever wrote the
-// workflow. Unbounded, that is every file the server can read: its own
-// settings, other installs' data. So they work only inside the folders the
-// install names:
-//
-//   XEPLR_FILE_ROOTS   absolute folders, comma-separated, e.g. /data/bank,/data/erp
-//
-// plus XEPLR_ACTIONS_TMP_DIR (or the system temp folder's xeplr-actions),
-// where downloads and exports land by default, so the file a step just saved
-// can be read by the next one.
-//
-// NOT DEFAULTED: no roots configured and a path outside the temp folder is
-// refused, naming the variable. "Where data lives is never defaulted."
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-function rootsError(message) {
-  var err = new Error(message);
-  err.code = 'PATH_NOT_ALLOWED';
-  err.status = 400;
-  return err;
-}
-
-function tmpRoot() {
-  return path.resolve(process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions'));
-}
-
-/** The folders a file step may use, resolved and real (symlinks followed). */
-function roots() {
-  var listed = String(process.env.XEPLR_FILE_ROOTS || '').split(',')
-    .map(function(r) { return r.trim(); })
-    .filter(Boolean);
-  listed.forEach(function(r) {
-    if (!path.isAbsolute(r)) throw rootsError('XEPLR_FILE_ROOTS must list absolute folders, and "' + r + '" is not one.');
-  });
-  return listed.concat([tmpRoot()]).map(function(r) {
-    try { return fs.realpathSync(r); } catch (e) { return path.resolve(r); }
-  });
-}
-
-/**
- * The path, absolute and real, when it is inside an allowed folder; refused
- * otherwise. A path that does not exist yet (a move's target) is checked by
- * its nearest existing parent, so "../" and symlinks cannot step outside.
- */
-function allowed(p, what) {
-  if (!p || typeof p !== 'string') throw rootsError((what || 'A path') + ' is required.');
-  if (!path.isAbsolute(p)) throw rootsError((what || 'The path') + ' "' + p + '" must be absolute, e.g. /data/bank/statement.csv.');
-  var resolved = path.resolve(p);
-  var probe = resolved;
-  var rest = '';
-  while (!fs.existsSync(probe) && path.dirname(probe) !== probe) {
-    rest = path.join(path.basename(probe), rest);
-    probe = path.dirname(probe);
-  }
-  var real = path.join(fs.realpathSync(probe), rest);
-  var ok = roots().some(function(r) { return real === r || real.indexOf(r + path.sep) === 0; });
-  if (!ok) {
-    throw rootsError((what || 'The path') + ' "' + p + '" is outside the folders file steps may use. ' +
-      (process.env.XEPLR_FILE_ROOTS
-        ? 'Allowed: ' + process.env.XEPLR_FILE_ROOTS + ' and the temp folder.'
-        : 'Set XEPLR_FILE_ROOTS to the folders they may use (absolute, comma-separated).'));
-  }
-  return real;
-}
-
-module.exports = { allowed: allowed, roots: roots, tmpRoot: tmpRoot };