@xeplr/actions 2.2.2 → 2.2.4

package/README.md

@@ -138,6 +138,7 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `dbFetch` | `db-fetch` | Stream rows from a table (`mode: 'table'`) or SQL (`mode: 'query'`, `params`). Default `streaming_mode: true` → NDJSON file `{ filePath, format: 'jsonl', bytes, rows }`; `false` → `{ rows, rowCount }`. |
 | `dbPush` | `db-push` | Write `rows` or an NDJSON `filePath` into `targetTable` through the uploader. `primaryKeys` → upsert. |
 | `dbMove` | `db-move` | One window of rows from a source table, query or procedure into a target table in one streamed pass. See [db-move](#db-move). |
+| `dbDump` | `db-dump` | A whole database to one backup file with its own dump program: `pg_dump -Fc` (Postgres, `.dump`) or `mysqldump` (MySQL, `.sql.gz`). See [Backups](#backups-db-dump-folder-archive-and-s3-upload). |
 | `dbProcedure` | `db-procedure` | Call a stored procedure; returns `{ rows, rowCount, procedure, sql }`. See [db-procedure](#db-procedure). |
 | `dbListTables` | `db-list-tables` | `{ tables }` — base tables in a schema/database. |
 | `dbListViews` | `db-list-views` | `{ views }`. |
@@ -152,6 +153,8 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `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 [Where files are](#where-files-are-one-data-root-a-folder-per-tenant). |
+| `s3Upload` | `s3-upload` | One file to an S3 bucket (or an S3-compatible `endpoint`), in parts, with a SHA-256 checksum. Only writes. See [Backups](#backups-db-dump-folder-archive-and-s3-upload). |
+| `folderArchive` | `folder-archive` | A folder of the tenant's own data folder to one `.tar.gz` (`tar`, no shell); its `backups/` and `tmp/` always left out. See [Backups](#backups-db-dump-folder-archive-and-s3-upload). |
 | `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 }`. |
@@ -206,6 +209,74 @@ For `mode: 'table'` the source's declared column types (`getTableSchema`) are pa
 
 Message ids are IMAP UIDs **scoped to `folder`**, and a move changes the id — download and delete before moving.
 
+## Backups: `db-dump`, `folder-archive` and `s3-upload`
+
+A backup is two steps: make one file — a database's dump, or a folder's archive — then send the file away.
+
+```js
+var dumped = await runAction({ name: 'db-dump', input: {
+  dbType: 'postgres', connectionInfoId: 'main-server',   // the server's login, resolved by the host
+  database: 'shop'
+} })
+// → { filePath: '<tenant>/backups/shop-2026-11-13T02-00-05.dump', fileName, bytes, sha256, dbType, database, durationMs }
+
+await runAction({ name: 's3-upload', input: {
+  connectionInfoId: 'backup-bucket',                      // { bucket, region, accessKeyId, secretAccessKey, prefix? }
+  filePath: dumped.output.filePath, deleteAfter: true
+} })
+// → { bucket, key: 'backups/shop-2026-11-13T02-00-05.dump', bytes, etag, versionId, deleted: true }
+```
+
+**db-dump**
+
+| input | |
+|---|---|
+| `dbType` | `postgres` or `mysql`. `mssql` is refused: not supported yet. |
+| `connection` | The server's login `{ host, port, user, password }`. |
+| `database` | Required: which database on that server. |
+| `folder` | In the tenant's folder; default `backups`. |
+| `fileName` | Default `<database>-<UTC time>.dump` (Postgres) or `.sql.gz` (MySQL). A name, not a path. |
+
+- **Postgres:** `pg_dump -Fc --no-owner --no-acl` — the custom format, already compressed, restored with `pg_restore`. `pg_dump` must be **at least the server's version** (it refuses an older one, and the step says so).
+- **MySQL / MariaDB:** `mysqldump --single-transaction --quick --routines --triggers --events --databases <db>`, gzipped as it is written.
+- **No shell, ever.** The program is run with an argument list built here; the password goes in its environment (`PGPASSWORD`, `MYSQL_PWD`), never on the command line where `ps` shows it. A database, host or user starting with `-` is refused (it would be read as an option).
+- **Written under `<name>.partial`, renamed only when the program ends cleanly.** A failure removes it and fails the step with the end of what the program said, the password taken out. A program that is not installed is named ("pg_dump is not installed on this server").
+- `system.signal` stops it (the program is killed); `system.onProgress({ bytes })` every second.
+
+**folder-archive**
+
+| input | |
+|---|---|
+| `folder` | A folder in the tenant's own folder, checked like every file step's (outside, `../`, a link pointing out: refused). Blank or `.`: all of it. |
+| `exclude` | Patterns left out, comma separated (`node_modules, *.log`) — tar's `--exclude`. One starting with `-` is refused. |
+| `fileName` | Default `<folder>-<UTC time>.tar.gz` (`all-…` for the whole folder), in the tenant's `backups/`. A name, not a path. |
+
+→ `{ filePath, fileName, bytes, sha256, folder, warning }`
+
+- **An app backs up only its own files.** The folder is inside the tenant's folder like every file step's, so an app (or the monitor) embedding this can never archive anything else on the server.
+- **Never its own `backups/` and `tmp/`:** the whole folder is archived entry by entry without them, and naming either (or a folder in them) is refused — a backup must not hold the backups before it.
+- `tar -czf` with an argument list, no shell; written as `<name>.partial`, renamed when tar ends. Exit 1 — GNU tar's "a file changed while it was read", the archive still whole — succeeds with `warning`; anything else removes the file and fails with the end of what tar said. `system.signal` kills tar.
+
+**s3-upload**
+
+| input | |
+|---|---|
+| `connection` | `{ bucket, region, accessKeyId, secretAccessKey, prefix?, sessionToken?, endpoint?, forcePathStyle? }`. Without `accessKeyId` the SDK's own chain is used (an EC2 role). `endpoint` for an S3-compatible store. |
+| `filePath` | The file, in the tenant's folder. |
+| `key` | Default `<prefix>/<file name>`. |
+| `deleteAfter` | `true`: the local file is deleted once it is uploaded. |
+| `contentType` | Default `application/octet-stream`. |
+
+- **Streamed in 16 MB parts** (`@aws-sdk/lib-storage`), so any size needs little memory. Every part carries a **SHA-256 checksum** — required by a bucket with Object Lock, and checked by S3.
+- **It only writes.** No list, get or head of the bucket, so the key it uses needs `s3:PutObject` and `s3:AbortMultipartUpload` (a failed upload is aborted) on the prefix, and nothing else:
+
+  ```json
+  { "Effect": "Allow", "Action": ["s3:PutObject", "s3:AbortMultipartUpload"], "Resource": "arn:aws:s3:::<bucket>/backups/*" }
+  ```
+- Peers, optional: `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` (`^3`). Missing → the step says to install them.
+
+`test/backup/` checks all three: `folder-archive` with a real `tar` (patterns left out, `backups/` and `tmp/` never in it, outside paths and links refused); the dump programs with a stand-in on `PATH` (arguments, password only in the environment, a failure leaving no file), a real `pg_dump` restored with `pg_restore --list` when Postgres is here, and the upload against an S3 stand-in (one PUT, then parts, a SHA-256 checksum, never a read).
+
 ## Data operation
 
 The step between steps. A fetch returns everything a table holds; an email

package/lib/builtins/db/dump.js

@@ -0,0 +1,199 @@
+// db-dump action — a whole database to one backup file, by the database's own
+// dump program: pg_dump (Postgres) or mysqldump (MySQL / MariaDB).
+//
+//   postgres  pg_dump -Fc --no-owner --no-acl → <db>-<when>.dump (custom
+//             format: already compressed, restored with pg_restore)
+//   mysql     mysqldump --single-transaction --quick --routines --triggers
+//             --events, gzipped here → <db>-<when>.sql.gz
+//   mssql     refused: not supported yet
+//
+// THE PROGRAM IS RUN WITH AN ARGUMENT LIST, never a shell, and only these two
+// programs, with arguments built here — nothing from the input reaches the
+// command line except the host, port, user and database, each passed as its
+// own argument. The password goes in the program's environment (PGPASSWORD,
+// MYSQL_PWD), never on the command line, where `ps` would show it.
+//
+// THE FILE is written under a temporary name and renamed only once the
+// program has finished cleanly, so a half-written dump never looks like a
+// backup. A failure removes it and fails the step with the end of what the
+// program said (stderr), the password taken out. Inside the tenant's own
+// folder (lib/dataDir.js), `backups/` unless `folder` says otherwise.
+//
+// A stop (system.signal) kills the program. system.onProgress({ bytes })
+// reports how much is written, every second or so.
+
+var fs = require('fs');
+var path = require('path');
+var zlib = require('zlib');
+var crypto = require('crypto');
+var { spawn } = require('child_process');
+var dataDir = require('../../dataDir');
+
+var PROGRAMS = {
+  postgres: { bin: 'pg_dump', ext: '.dump', gzip: false, port: 5432 },
+  mysql:    { bin: 'mysqldump', ext: '.sql.gz', gzip: true, port: 3306 }
+};
+var DEFAULT_FOLDER = 'backups';
+var STDERR_KEEP = 2048;
+var PROGRESS_MS = 1000;
+
+/** "2026-11-13T02-00-05" — a file name's time, UTC. */
+function stamp(date) {
+  return date.toISOString().slice(0, 19).replace(/:/g, '-');
+}
+
+/** A database name made safe for a file name. */
+function fileSafe(name) {
+  return String(name).replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^\.+/, '') || 'database';
+}
+
+/** The program's arguments and environment — the password only in the environment. */
+function commandFor(dbType, conn, database) {
+  var p = PROGRAMS[dbType];
+  var host = String(conn.host || 'localhost');
+  var port = String(conn.port || p.port);
+  var user = conn.user ? String(conn.user) : null;
+  var env = Object.assign({}, process.env);
+  if (dbType === 'postgres') {
+    var args = ['-Fc', '--no-owner', '--no-acl', '-h', host, '-p', port];
+    if (user) args.push('-U', user);
+    args.push('-d', database);
+    delete env.PGPASSWORD;
+    if (conn.password) env.PGPASSWORD = String(conn.password);
+    return { bin: p.bin, args: args, env: env };
+  }
+  var margs = ['--single-transaction', '--quick', '--routines', '--triggers', '--events', '-h', host, '-P', port];
+  if (user) margs.push('-u', user);
+  margs.push('--databases', database);
+  delete env.MYSQL_PWD;
+  if (conn.password) env.MYSQL_PWD = String(conn.password);
+  return { bin: p.bin, args: margs, env: env };
+}
+
+function refuse(message, code) {
+  var err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+module.exports = {
+  name: 'db-dump',
+  // It writes a file, so it is never previewed.
+  example: { filePath: '/data/app/backups/shop-2026-11-13T02-00-05.dump', fileName: 'shop-2026-11-13T02-00-05.dump', bytes: 104857600,
+    sha256: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', dbType: 'postgres', database: 'shop', durationMs: 42000 },
+  description: 'Back up a whole database to one file with its own dump program — pg_dump (Postgres, custom format) or mysqldump (MySQL, gzipped). Returns { filePath, fileName, bytes, sha256, dbType, database, durationMs }.',
+  requires: [],   // the dump programs are checked when it runs
+
+  inputSchema: [
+    { name: 'dbType', type: 'string', required: true, order: 1,
+      description: 'postgres or mysql (SQL Server: not supported yet).' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: '{ host, port, user, password } — the server\'s login, a saved connection (connectionInfoId) resolved by the host.' },
+    { name: 'database', type: 'string', required: true, order: 3,
+      description: 'The database on that server to back up.' },
+    { name: 'folder', type: 'string', order: 4, group: 'File',
+      description: 'Where in this company\'s data folder the file goes. Default: backups.' },
+    { name: 'fileName', type: 'string', order: 5, group: 'File',
+      description: 'The file\'s name. Default: <database>-<UTC time>.dump (Postgres) or .sql.gz (MySQL).' }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'sha256', type: 'string' }, { name: 'dbType', type: 'string' }, { name: 'database', type: 'string' },
+    { name: 'durationMs', type: 'number' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+    var dbType = String(input.dbType || '').toLowerCase();
+    if (dbType === 'mssql') throw refuse('db-dump: SQL Server is not supported yet — postgres or mysql.', 'DB_TYPE_NOT_SUPPORTED');
+    if (!PROGRAMS[dbType]) throw refuse('db-dump: dbType must be postgres or mysql, not "' + input.dbType + '".', 'DB_TYPE_NOT_SUPPORTED');
+    var conn = input.connection || {};
+    var database = input.database;
+    if (!database) throw refuse('db-dump: say which database to back up.', 'NO_DATABASE');
+    // An argument starting with "-" would be read as an option, not a name.
+    [['database', database], ['host', conn.host], ['user', conn.user]].forEach(function(f) {
+      if (f[1] && /^-/.test(String(f[1]))) throw refuse('db-dump: the ' + f[0] + ' "' + f[1] + '" cannot start with "-".', 'BAD_ARGUMENT');
+    });
+
+    var started = Date.now();
+    var program = PROGRAMS[dbType];
+    var folder = dataDir.resolve(input.folder || DEFAULT_FOLDER, 'The backup folder');
+    fs.mkdirSync(folder, { recursive: true });
+    var name = input.fileName ? String(input.fileName) : fileSafe(database) + '-' + stamp(new Date()) + program.ext;
+    var filePath = dataDir.resolve(path.join(folder, name), 'The backup file');
+    if (path.dirname(filePath) !== fs.realpathSync(folder)) throw refuse('db-dump: fileName "' + name + '" must be a name, not a path.', 'PATH_NOT_ALLOWED');
+    var partial = filePath + '.partial';
+
+    var cmd = commandFor(dbType, conn, String(database));
+    var secret = conn.password ? String(conn.password) : null;
+    var out = fs.createWriteStream(partial);
+    var hash = crypto.createHash('sha256');
+    var bytes = 0;
+    var stderr = '';
+    var child;
+
+    var done = new Promise(function(resolve, reject) {
+      var settled = false;
+      function fail(err) { if (settled) return; settled = true; reject(err); }
+      function ok() { if (settled) return; settled = true; resolve(); }
+
+      try {
+        child = spawn(cmd.bin, cmd.args, { env: cmd.env, stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (e) {
+        fail(e);
+        return;
+      }
+      child.on('error', function(e) {
+        fail(e.code === 'ENOENT' ? refuse(cmd.bin + ' is not installed on this server (needed to back up ' + dbType + ').', 'PROGRAM_NOT_FOUND') : e);
+      });
+      child.stderr.on('data', function(d) { stderr = (stderr + d.toString()).slice(-STDERR_KEEP); });
+
+      var source = program.gzip ? child.stdout.pipe(zlib.createGzip()) : child.stdout;
+      source.on('data', function(chunk) { hash.update(chunk); bytes += chunk.length; });
+      source.on('error', fail);
+      out.on('error', fail);
+      source.pipe(out);
+
+      var exit = null;
+      var written = false;
+      function finish() {
+        if (exit === null || !written) return;
+        if (exit.code === 0) return ok();
+        var said = stderr.trim();
+        if (secret) said = said.split(secret).join('****');
+        var why = exit.signal ? 'was stopped (' + exit.signal + ')' : 'ended with code ' + exit.code;
+        fail(refuse(cmd.bin + ' ' + why + (said ? ': ' + said : ''), 'DUMP_FAILED'));
+      }
+      child.on('close', function(code, signal) { exit = { code: code, signal: signal }; finish(); });
+      out.on('finish', function() { written = true; finish(); });
+    });
+
+    var timer = system.onProgress ? setInterval(function() { system.onProgress({ bytes: bytes }); }, PROGRESS_MS) : null;
+    var onAbort = function() { if (child && child.exitCode === null) child.kill('SIGTERM'); };
+    if (system.signal) {
+      if (system.signal.aborted) onAbort();
+      else system.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    try {
+      await done;
+    } catch (err) {
+      out.destroy();
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw err;
+    } finally {
+      if (timer) clearInterval(timer);
+      if (system.signal) system.signal.removeEventListener('abort', onAbort);
+    }
+    fs.renameSync(partial, filePath);
+    if (system.onProgress) system.onProgress({ bytes: bytes });
+    return {
+      filePath: filePath, fileName: path.basename(filePath), bytes: bytes, sha256: hash.digest('hex'),
+      dbType: dbType, database: String(database), durationMs: Date.now() - started
+    };
+  },
+
+  // For tests: the command a dump runs, without running it.
+  _commandFor: commandFor
+};

package/lib/builtins/file/archive.js

@@ -0,0 +1,151 @@
+// folder-archive action — a folder of this company's data folder, packed into
+// one .tar.gz backup file (then s3-upload sends it away).
+//
+//   folder    inside the tenant's own folder (lib/dataDir.js), checked like
+//             every file step's: a path outside, ../ or a link pointing out is
+//             refused. '' or '.' is the whole tenant folder
+//   never     the tenant's own backups/ and tmp/ — a backup must not hold the
+//             backups before it, nor half-written spools. Archiving the whole
+//             folder names every other entry; naming backups/ or tmp/ (or a
+//             folder inside them) is refused
+//   exclude   patterns left out ("node_modules, *.log"), tar's --exclude; none
+//             may start with "-", which tar would read as an option
+//
+// `tar -czf` is RUN WITH AN ARGUMENT LIST, never a shell. The file is written
+// as <name>.partial and renamed only once tar ends: exit 0, or 1 — GNU tar's
+// "a file changed while it was read" (a log being written), where the archive
+// is whole — which comes back as `warning`. Anything else removes the file and
+// fails the step with the end of what tar said. A stop (system.signal) kills
+// tar. Written to the tenant's backups/: <slug>-<UTC time>.tar.gz.
+
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+var { spawn } = require('child_process');
+var dataDir = require('../../dataDir');
+
+var OUT_FOLDER = 'backups';
+var NEVER = ['backups', 'tmp'];
+var STDERR_KEEP = 2048;
+
+function refuse(message, code) {
+  var err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function stamp(date) {
+  return date.toISOString().slice(0, 19).replace(/:/g, '-');
+}
+
+/** "uploads/2026" → "uploads-2026"; the whole folder → "all". */
+function slugOf(rel) {
+  return String(rel).replace(/^[./]+|\/+$/g, '').replace(/[^A-Za-z0-9._-]+/g, '-') || 'all';
+}
+
+/** "node_modules, *.log" → the patterns; one starting with "-" is refused. */
+function excludesOf(text) {
+  var list = (Array.isArray(text) ? text : String(text || '').split(/[\n,]/)).map(function(p) { return String(p).trim(); }).filter(Boolean);
+  list.forEach(function(p) {
+    if (p[0] === '-') throw refuse('folder-archive: the pattern "' + p + '" cannot start with "-".', 'BAD_ARGUMENT');
+  });
+  return list;
+}
+
+/** What tar is asked to pack: from the tenant folder, its entries except backups/ and tmp/; else the folder itself. */
+function targetOf(input) {
+  var root = fs.realpathSync(dataDir.tenantFolder());
+  var asked = String(input.folder === undefined || input.folder === null ? '' : input.folder).trim();
+  var dir = asked === '' || asked === '.' ? root : dataDir.resolve(asked, 'The folder');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw refuse('"' + asked + '" is not a folder that exists.', 'NOT_A_FOLDER');
+  var rel = path.relative(root, dir);
+  var top = rel.split(path.sep)[0];
+  if (rel && NEVER.indexOf(top) >= 0) {
+    throw refuse('folder-archive: ' + top + '/ holds the backups and temporary files themselves — name a folder beside it.', 'PATH_NOT_ALLOWED');
+  }
+  if (!rel) {
+    var entries = fs.readdirSync(root).filter(function(n) { return NEVER.indexOf(n) < 0; }).sort();
+    if (!entries.length) throw refuse('folder-archive: there is nothing in this company\'s folder to back up.', 'NOTHING_TO_ARCHIVE');
+    return { dir: root, rel: '', cwd: root, members: entries };
+  }
+  return { dir: dir, rel: rel, cwd: path.dirname(dir), members: [path.basename(dir)] };
+}
+
+module.exports = {
+  name: 'folder-archive',
+  example: { filePath: '/data/app/backups/uploads-2026-11-13T02-00-05.tar.gz', fileName: 'uploads-2026-11-13T02-00-05.tar.gz', bytes: 10485760,
+    sha256: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', folder: 'uploads', warning: null },
+  description: 'Pack a folder of this company\'s data folder into one .tar.gz backup file (its backups/ and tmp/ always left out). Returns { filePath, fileName, bytes, sha256, folder, warning }.',
+  requires: [],   // tar is checked when it runs
+
+  inputSchema: [
+    { name: 'folder', type: 'string', order: 1,
+      description: 'A folder in this company\'s data folder, e.g. uploads. Blank or "." for all of it.' },
+    { name: 'exclude', type: 'string', order: 2,
+      description: 'Names or patterns to leave out, comma separated — e.g. node_modules, *.log.' },
+    { name: 'fileName', type: 'string', order: 3, group: 'File',
+      description: 'The archive\'s name. Default: <folder>-<time>.tar.gz.' }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'sha256', type: 'string' }, { name: 'folder', type: 'string' }, { name: 'warning', type: 'string' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+    var target = targetOf(input);
+    var excludes = excludesOf(input.exclude);
+    var outDir = dataDir.resolve(OUT_FOLDER, 'The backup folder');
+    fs.mkdirSync(outDir, { recursive: true });
+    var name = input.fileName ? String(input.fileName) : slugOf(target.rel) + '-' + stamp(new Date()) + '.tar.gz';
+    var filePath = dataDir.resolve(path.join(outDir, name), 'The backup file');
+    if (path.dirname(filePath) !== fs.realpathSync(outDir)) throw refuse('folder-archive: fileName "' + name + '" must be a name, not a path.', 'PATH_NOT_ALLOWED');
+    var partial = filePath + '.partial';
+
+    var args = ['-czf', partial].concat(excludes.map(function(p) { return '--exclude=' + p; }), ['-C', target.cwd, '--'], target.members);
+    var stderr = '';
+    var child;
+    var code = await new Promise(function(resolve, reject) {
+      try {
+        child = spawn('tar', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+      } catch (e) {
+        reject(e);
+        return;
+      }
+      child.on('error', function(e) { reject(e.code === 'ENOENT' ? refuse('tar is not installed on this server.', 'PROGRAM_NOT_FOUND') : e); });
+      child.stderr.on('data', function(d) { stderr = (stderr + d.toString()).slice(-STDERR_KEEP); });
+      var onAbort = function() { if (child.exitCode === null) child.kill('SIGTERM'); };
+      if (system.signal) {
+        if (system.signal.aborted) onAbort();
+        else system.signal.addEventListener('abort', onAbort, { once: true });
+      }
+      child.on('close', function(c, signal) {
+        if (system.signal) system.signal.removeEventListener('abort', onAbort);
+        if (signal) return reject(refuse('tar was stopped (' + signal + ').', 'ARCHIVE_FAILED'));
+        resolve(c);
+      });
+    }).catch(function(err) {
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw err;
+    });
+    var said = stderr.trim().split('\n').slice(-3).join(' ');
+    if (code !== 0 && code !== 1) {
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw refuse('tar ended with code ' + code + (said ? ': ' + said : ''), 'ARCHIVE_FAILED');
+    }
+    fs.renameSync(partial, filePath);
+    var hash = crypto.createHash('sha256');
+    await new Promise(function(resolve, reject) {
+      fs.createReadStream(filePath).on('data', function(d) { hash.update(d); }).on('end', resolve).on('error', reject);
+    });
+    return {
+      filePath: filePath, fileName: path.basename(filePath), bytes: fs.statSync(filePath).size, sha256: hash.digest('hex'),
+      folder: target.rel || '.', warning: code === 1 ? (said || 'some files changed while they were read') : null
+    };
+  },
+
+  // For tests.
+  _targetOf: targetOf,
+  _excludesOf: excludesOf
+};

package/lib/builtins/file/s3-upload.js

@@ -0,0 +1,131 @@
+// s3-upload action — one file from this company's data folder to an S3 bucket
+// (or an S3-compatible store: `endpoint`).
+//
+// Streamed in parts (@aws-sdk/lib-storage Upload), so a file of any size
+// needs no more memory than a few parts. Every part carries a SHA-256
+// checksum: a bucket with Object Lock refuses a PUT without one, and S3
+// checks the bytes it got against it.
+//
+// IT ONLY WRITES. No list, read or head of the bucket — a backup key should be
+// allowed s3:PutObject (and s3:AbortMultipartUpload, so a failed upload is
+// cleaned up) and nothing else, so a leaked key can add files and do no more.
+//
+// Peer deps, optional and lazy-required: @aws-sdk/client-s3 and
+// @aws-sdk/lib-storage.
+//
+// The connection: { bucket, region, accessKeyId, secretAccessKey, prefix?,
+// sessionToken?, endpoint?, forcePathStyle? } — a saved connection
+// (connectionInfoId) the host resolves; never typed into a step.
+
+var fs = require('fs');
+var path = require('path');
+var dataDir = require('../../dataDir');
+
+var PART_SIZE = 16 * 1024 * 1024;
+var QUEUE = 4;
+
+function refuse(message, code) {
+  var err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function aws() {
+  try {
+    return { s3: require('@aws-sdk/client-s3'), storage: require('@aws-sdk/lib-storage') };
+  } catch (_) {
+    throw refuse("s3-upload: '@aws-sdk/client-s3' and '@aws-sdk/lib-storage' are not installed. Run: npm install @aws-sdk/client-s3 @aws-sdk/lib-storage", 'MISSING_DEPENDENCY');
+  }
+}
+
+/** The object's key: `key` as given, else <prefix>/<file name>; never starting with "/". */
+function keyFor(input, conn, filePath) {
+  if (input.key) return String(input.key).replace(/^\/+/, '');
+  var prefix = String(conn.prefix || '').replace(/^\/+|\/+$/g, '');
+  return (prefix ? prefix + '/' : '') + path.basename(filePath);
+}
+
+module.exports = {
+  name: 's3-upload',
+  // It writes, so it is never previewed.
+  example: { bucket: 'acme-backups', key: 'backups/shop/shop-2026-11-13T02-00-05.dump', bytes: 104857600, etag: '"5d41402abc4b2a76b9719d911017c592-7"', versionId: '3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY', deleted: true },
+  description: 'Upload one file from this company\'s data folder to an S3 bucket, in parts, with a SHA-256 checksum. Only writes: the key needs s3:PutObject (and s3:AbortMultipartUpload), nothing else. Returns { bucket, key, bytes, etag, versionId, deleted }.',
+  requires: [],   // @aws-sdk/client-s3 and @aws-sdk/lib-storage checked at runtime
+
+  inputSchema: [
+    { name: 'connection', type: 'object', required: true, order: 1,
+      description: '{ bucket, region, accessKeyId, secretAccessKey, prefix? } — a saved connection (connectionInfoId), resolved by the host.' },
+    { name: 'filePath', type: 'string', required: true, order: 2,
+      description: 'The file, in this company\'s data folder, e.g. {steps.dump.filePath}.' },
+    { name: 'key', type: 'string', order: 3,
+      description: 'The object\'s key in the bucket. Default: <prefix>/<file name>.' },
+    { name: 'deleteAfter', type: 'boolean', default: false, order: 4,
+      description: 'Delete the local file once it is uploaded.' },
+    { name: 'contentType', type: 'string', order: 5, group: 'Upload options',
+      description: 'Default: application/octet-stream.' }
+  ],
+  outputSchema: [
+    { name: 'bucket', type: 'string' }, { name: 'key', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'etag', type: 'string' }, { name: 'versionId', type: 'string' }, { name: 'deleted', type: 'boolean' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+    var conn = input.connection || {};
+    if (!conn.bucket) throw refuse('s3-upload: the connection names no bucket.', 'NO_BUCKET');
+    if (!conn.region && !conn.endpoint) throw refuse('s3-upload: the connection names no region.', 'NO_REGION');
+    var file = dataDir.resolve(input.filePath, 'The file to upload');
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw refuse('s3-upload: "' + input.filePath + '" is not a file that exists.', 'FILE_NOT_FOUND');
+    var bytes = fs.statSync(file).size;
+    var key = keyFor(input, conn, file);
+
+    var lib = aws();
+    var clientConfig = { region: conn.region || 'us-east-1' };
+    if (conn.accessKeyId) {
+      clientConfig.credentials = { accessKeyId: String(conn.accessKeyId), secretAccessKey: String(conn.secretAccessKey || '') };
+      if (conn.sessionToken) clientConfig.credentials.sessionToken = String(conn.sessionToken);
+    }
+    if (conn.endpoint) clientConfig.endpoint = String(conn.endpoint);
+    if (conn.forcePathStyle) clientConfig.forcePathStyle = true;
+    var client = new lib.s3.S3Client(clientConfig);
+
+    var upload = new lib.storage.Upload({
+      client: client,
+      partSize: PART_SIZE,
+      queueSize: QUEUE,
+      leavePartsOnError: false,     // a failed upload is aborted (s3:AbortMultipartUpload)
+      params: {
+        Bucket: String(conn.bucket),
+        Key: key,
+        Body: fs.createReadStream(file),
+        ContentLength: bytes,
+        ContentType: input.contentType || 'application/octet-stream',
+        ChecksumAlgorithm: 'SHA256'
+      }
+    });
+    if (system.onProgress) upload.on('httpUploadProgress', function(p) { system.onProgress({ bytes: p.loaded || 0 }); });
+    var onAbort = function() { upload.abort().catch(function() {}); };
+    if (system.signal) {
+      if (system.signal.aborted) onAbort();
+      else system.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    var res;
+    try {
+      res = await upload.done();
+    } finally {
+      if (system.signal) system.signal.removeEventListener('abort', onAbort);
+      if (client.destroy) client.destroy();
+    }
+    var deleted = false;
+    if (input.deleteAfter === true) {
+      fs.unlinkSync(file);
+      deleted = true;
+    }
+    return { bucket: String(conn.bucket), key: key, bytes: bytes, etag: (res && res.ETag) || null, versionId: (res && res.VersionId) || null, deleted: deleted };
+  },
+
+  // For tests.
+  _keyFor: keyFor
+};

package/lib/builtins/index.js

@@ -40,6 +40,9 @@ module.exports = {
   // fetchStream piped straight into upload() rather than staged through an
   // NDJSON file the way dbFetch → dbPush does. See db/move.js.
   dbMove:       require('./db/move'),
+  // A whole database to one backup file, by its own dump program (pg_dump,
+  // mysqldump) — run with an argument list, never a shell. See db/dump.js.
+  dbDump:       require('./db/dump'),
 
   // DB introspection — list tables/views/procedures, or one table's columns.
   dbListTables:     require('./db/list-tables'),
@@ -53,6 +56,12 @@ module.exports = {
   fileDelete:   require('./file/delete'),
   fileList:     require('./file/list'),
   fileRead:     require('./file/read'),
+  // One file to an S3 bucket, in parts, write-only. Peers: @aws-sdk/client-s3
+  // and @aws-sdk/lib-storage — optional, lazy-required.
+  s3Upload:     require('./file/s3-upload'),
+  // A folder of the tenant's own data folder to one .tar.gz backup file (tar,
+  // no shell; its backups/ and tmp/ always left out).
+  folderArchive: require('./file/archive'),
 
   // Email actions. Inbound routes to getInboundProvider(input.emailType)
   // (imap today), outbound to getOutboundProvider (smtp) — see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {
@@ -39,6 +39,8 @@
     "@xeplr/schema-handler": "^1.0.0"
   },
   "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/lib-storage": "^3.0.0",
     "@duckdb/node-api": "1.5.5-r.3",
     "@xeplr/db": "^1.1.0",
     "@xeplr/email": "^1.0.0",
@@ -62,6 +64,12 @@
     "unzipper": "^0.12.5"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
     "@duckdb/node-api": {
       "optional": true
     },
@@ -124,6 +132,8 @@
     }
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1168.0",
+    "@aws-sdk/lib-storage": "^3.1168.0",
     "@duckdb/node-api": "^1.5.5-r.3",
     "@xeplr/db": "^1.1.0",
     "@xeplr/utils": "^1.0.0",