@ix-xs/node-comfort 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,158 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [2.2.0] - 2026-11-03
+
+A security release. Three audits went through every module looking for what an attacker could do with the
+values a program receives: a request body, a header, a file name, a `.env` in a cloned repository, a log
+line. More than fifty problems came out of them, a few serious ones. They are all fixed, each with a test
+that failed before. Most fixes change nothing for code that works today, and the ones you could notice are
+listed under "Changed". The package also makes use of what Node.js 26 brings.
+
+### Security
+
+- **JWT**: a public key could be used as an HMAC secret when it was read from a file with a BOM, had text
+  before its PEM header, or was in DER form, so anyone could sign `HS256` tokens with it. Anything that looks
+  like an asymmetric key is now refused as a secret, and `HS*` secrets need at least 32 bytes (RFC 7518).
+  An invalid `clockTolerance` or `now` no longer turns the expiry check off, signatures must be written in
+  canonical Base64URL, and a `crit` header is refused unless you list it in `options.crit`.
+- **sys**: on Windows, an argument passed to an npm command (`npm.cmd`, global shims) could run another
+  command (the "BatBadBut" problem). Arguments are now escaped twice for every `.cmd` or `.bat` that passes
+  them on, and a line break, which can't be escaped, is refused.
+- **SQLite**: `update()`, `delete()` and `increment()` with a filter whose values were all `undefined`
+  (`{ id: undefined }`, `{ $or: [{}] }`, `{ id: { notIn: [] } }`) changed or deleted the whole table. They
+  now throw. A filter value taken from a JSON body could also become an operator (`{ "ne": "x" }` matched
+  every row): the new `operators: "tagged"` option and `SQLite.op` close that door, see "Added".
+- **http**: with a `baseURL`, a path like `"https://evil.example"`, `"\\evil.example"` or `"../../admin"`
+  left the base and took the client's `auth` header with it. Paths now stay under the base. Responses are
+  limited to 100 MB once decompressed (a 500 KB gzip bomb used to fill 512 MB), redirects to another origin
+  drop `x-api-key` and the other secret headers, the temporary file of `download()` has an unguessable name,
+  and an `HttpError` no longer shows query-string secrets or cookies in its message and `toJSON()`.
+- **env**: the `.env` loaded automatically at startup set `NODE_OPTIONS` (code run in every child process),
+  `NODE_TLS_REJECT_UNAUTHORIZED` and other dangerous variables. They are now left out, with one warning on
+  stderr. `env.parse()` no longer reads `process.env` for `${VAR}`, and a value that expands to more than
+  64 KB is refused.
+- **Denial of service**: a few hundred bytes could block the process for seconds or minutes in
+  `isMimeType()`, the duration parser (`"5m"`, behind every `timeout`, `ttl` and `expiresIn`), `time.add()`,
+  the case converters of `str`, the paths of `obj`, a recursive `schema.union()`, `.env` comments and
+  expansion, `time.parse()`, `obj.set()` with a key like `"a.4000000000"`, `arr.unzip()`, `num.parseBytes()`
+  and `fs.sanitizeFilename()`. All of them are now linear.
+- **logger and cli**: a logged value could send escape sequences to the terminal (write to the clipboard,
+  change the title, clear the screen), forge a log line with `\r` or `\n`, or be read as markup. They are now
+  shown as text, and the colors and links you add with `nc.color` still work. `redact` also covers `Map`,
+  `Set` and the causes of errors, and log files are created readable by their owner only.
+- **id**: a program started from a startup snapshot (`node --build-snapshot`, single executable
+  applications) printed the same ids at each start. They are now drawn again in each process.
+- **memoize**: `func.memoize()`, `func.dedupe()` and `cache.wrap()` could give one call the cached result of
+  another, for example `{ role: "admin" }` and `{ role: "guest" }` held in a `Set`.
+- **fs**: copying or moving a file onto itself, or a folder into itself, deleted it. `copy()` followed
+  junctions out of the folder on Windows, `emptyFolder()` emptied the folder a junction pointed to, and
+  `sanitizeFilename()` let `COM¹`, `CONIN$` and right-to-left characters through.
+- **Smaller fixes**: TOTP secrets need 10 bytes (16 for new ones from `totpSecret()`) and the window is
+  capped at 10, `verifyPassword()` refuses hashes that would take minutes, `safeEqual("", "")` is `false`, `str.mask()` no longer shows a short
+  secret in full, `isURL()` and `schema.string().url()` refuse text that only parses once cleaned
+  (`https://a.com/"><script>`), `sys.open()` only opens web and mail links, and `obj.set()` converts each
+  key once, so a key object can't pass the `__proto__` check and then change.
+
+### Added
+
+- **crypto**: Argon2id passwords, with `hashPassword(password, { algorithm: "argon2id" })` (Node.js 24.7 or
+  later). The hashes use the standard PHC format, so other libraries can read them. `verifyPassword()` reads
+  both kinds, and `needsRehash()` says when a hash should move to the algorithm you ask for.
+- **crypto**: `totpStep()` gives the time step of a valid code, and `verifyTOTP({ after })` refuses a code
+  that was already used. `verifyJWT()` takes `typ` and `crit`, and `clockTolerance` takes text like `"30s"`.
+- **SQLite**: `SQLite.op` builds operators (`SQLite.op.gte(18)`, `SQLite.op.in([1, 2])`) that a value from
+  JSON can't imitate, and `new SQLite(path, { operators: "tagged" })` only accepts those. In that mode, a read
+  throws on an `undefined` filter value too, so a missing field can't drop its condition.
+- **http**: `maxResponseSize`, `allowAbsoluteUrls` and `sensitiveHeaders` options, and the client follows
+  redirects itself (`redirect: "follow" | "manual" | "error"`).
+- **sys**: `open(target, { protocols, allowUNC })` and `which(command, { cwd })`.
+- **schema**: `parse()`, `safeParse()` and `is()` take `{ maxDepth }` (1000 by default), and a value nested
+  deeper gets a `"too_deep"` issue instead of a stack overflow.
+- **str**: `levenshtein(a, b, { maxDistance })` and `closest(..., { maxDistance })` stop counting early.
+- **checker**: `isDataURL(value, { types })` limits the accepted media types.
+- **logger**: the `mode` of log files (`0o600` by default).
+- **`using`**: watchers, schedules (`every()`, `cron()`), spinners, progress bars, `when()` tasks,
+  `dontCrash()`, and the functions returned by `emitter.on()`, `onAny()` and `sys.onShutdown()` work with
+  `using` (Node.js 24 and later): they stop at the end of the block.
+- **time**: dates can be `Temporal` objects (`Temporal.Instant`, `Temporal.ZonedDateTime`).
+
+### Changed
+
+- **Node.js 22.23.4, 24.22.1, 26.12.1 or a later version of these lines is required** (`engines`). Older
+  versions can be crashed by a single malicious HTTP response, which no package can prevent (2.1.1 only
+  warned about it). Node.js 25 is not supported.
+- **Faster on Node.js 26**: time zones go through `Temporal`, and `time.add()` or `time.startOf()` with a
+  zone are more than twice as fast.
+- JWT `HS*` secrets shorter than 32 bytes throw a `TypeError`, when signing and when verifying.
+- TOTP secrets shorter than 10 bytes throw, `totpSecret()` needs at least 16 bytes, and `window` must be an
+  integer from 0 to 10.
+- `update()`, `delete()`, `increment()` and `set()` of SQLite throw on an `undefined` filter value, an empty
+  `$and` or `$or`, or a filter that matches every row (use `clearTable()` to empty a table).
+- `http`: with a `baseURL`, a URL outside it throws a `TypeError` unless you pass `allowAbsoluteUrls: true`,
+  and then the client's `auth`, `headers` and `query` stay home. A `params` value of `.` or `..` throws.
+  Bodies over 100 MB throw `ERR_RESPONSE_TOO_LARGE`, and `redirect: "error"` throws `ERR_REDIRECT`, which
+  is not retried.
+- `sys.run()` on Windows rejects a line break in an argument to a `.cmd` or `.bat`. A relative command is
+  looked up from `options.cwd`, and `extendEnv: false` without `env` gives an empty environment.
+- `sys.open()` throws for a scheme other than `http:`, `https:` and `mailto:`, for a path that doesn't
+  exist, for a control character and, on Windows, for a network path or a double quote.
+- `env.parse()` only expands `${VAR}` from the text itself and the `env` option: pass `{ env: process.env }`
+  for the old behaviour. `env.load()` is unchanged.
+- The logger shows control characters as text, indents the lines of a message after the first one even
+  without a timestamp (but not for `log()` with no scope and no timestamp, which prints like `console.log`),
+  and reads markup in the first argument only. Without colors (and in files), colors
+  are removed from logged strings. In JSON, a logged object can't replace `time`, `level`, `scope` or `msg`.
+- `color.strip()` also removes `\r`, `\b` and every other control character but tabs and new lines.
+- `str.mask()` hides everything when `start` and `end` would show the whole text, `arr.pluck()` and the
+  other string iteratees ignore what an item inherits from `Object.prototype`, and `obj.get({}, "toString")`
+  is `undefined`.
+- `obj.set()` and `obj.unflatten()` make an object, not an array, for a number key above 10000.
+- `isURL()` and `schema.string().url()` refuse spaces, double quotes, `<`, `>`, backticks and backslashes, and
+  `isEmail()`, `isHostname()`, `isMimeType()` and `isCron()` are stricter on look-alike characters, label
+  lengths, line breaks and trailing garbage. `time.cron()` refuses `"*/5/x"` too.
+- `memoize`, `dedupe` and `cache.wrap()` compare `Set`, `Map` and class instances given as arguments by
+  identity.
+- `fs.copyFile()`, `moveFile()`, `copy()`, `move()` and the folder helpers return `false` (or `0`) instead
+  of losing data when the destination is the source or inside it.
+- `schema.union()` stops checking an option at its first issue, and `is()` stops at the first issue: the
+  refinements after it no longer run.
+- `crypto.verifyPassword()` throws a `RangeError` for a hash that asks for more work than allowed (scrypt
+  with `p` over 16, Argon2 with more than 1 GiB of memory), without doing that work: the password may be
+  right, the hash has to be replaced.
+
+### Fixed
+
+- `fs.move()` keeps the destination when the move fails, `findUp({ stopAt })` honors a path with a trailing
+  separator or another letter case, and `color.link()` can't be cut short by its own text.
+- `fs.moveFilesIn()` deleted every selected file, even one whose copy failed. Now a file that can't be
+  copied stays where it is, and `moveFile()` can change only the letter case of a name on Windows and macOS.
+- A response body is cancelled when `onDownloadProgress` throws, so the connection doesn't stay open.
+- `s.literal(5n)` and enums of bigints report a failure instead of throwing.
+
+### Repository
+
+- Every GitHub Action is pinned to a commit, the jobs keep no git credentials, and CodeQL scans the code and
+  the workflows on each pull request. Dependabot keeps the tools up to date.
+- `scripts/bench.js` measures 63 hot paths and compares two runs.
+
+## [2.1.1] - 2026-10-30
+
+### Security
+
+- **Update Node.js if your program calls servers you don't control.** Versions of Node.js before 22.23.4,
+  24.22.1 and 26.12.1 can be crashed by a single malicious HTTP response (GHSA-xjj6-f33q-929c,
+  CVE-2026-109869), in the copy of undici behind their `fetch()`. `nc.http` uses that `fetch()`, so it is
+  exposed like any other client: the error can be caught, but the process stops right after, and no code in
+  a package can prevent it. The package still accepts older versions of Node.js. Node.js 25 has no fix.
+
+### Documentation
+
+- The reference is now in French too, like the rest of the website, and the landing page and the page for
+  an address that does not exist no longer have English left in them.
+- A dozen sentences of the JSDoc were wrong or unclear, among them the parameter of `func.throttle()` and
+  the options of `fs.move()`, `fs.hashFile()` and `fs.sanitizeFilename()`. Your editor now shows the right ones.
+
 ## [2.1.0] - 2026-10-12
 
 Every module was read again, line by line. The result: about sixty new functions and options, a hot path
@@ -335,6 +487,7 @@ Each item explains what to change. Most projects only need the SQLite and Node.j
 
 - SQLite: the folder of the database was created in one place and the file opened in another.
 
+[2.1.1]: https://github.com/ix-xs/node-comfort/compare/v2.1.0...v2.1.1
 [2.1.0]: https://github.com/ix-xs/node-comfort/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/ix-xs/node-comfort/compare/v1.2.0...v2.0.0
 [1.2.0]: https://github.com/ix-xs/node-comfort/releases/tag/v1.2.0

package/README.md

@@ -51,7 +51,7 @@ nc.sys.onShutdown(() => db.close());
 npm install @ix-xs/node-comfort
 ```
 
-Node.js 22.13 or newer. That's the first version where `node:sqlite` works without a flag.
+Node.js 22.23.4, 24.22.1, 26.12.1 or a later version of these lines. Older versions [can be crashed by a malicious HTTP response](https://ix-xs.github.io/node-comfort/system/http/#servers-you-dont-control), and no package can prevent it. On Node.js 26, time zones go through `Temporal` and are more than twice as fast.
 
 ## Why node-comfort
 
@@ -60,7 +60,7 @@ Node.js 22.13 or newer. That's the first version where `node:sqlite` works witho
 - **Fast to load.** Namespaces load the first time you use them. Requiring the package takes about 4 ms, and a script that only logs never loads the database or the HTTP client.
 - **Safe by default.** Prototype-pollution-proof objects, scrypt passwords, AES-256-GCM, constant-time comparisons, parameterized SQL, atomic file writes.
 - **One way of doing things.** Durations are always `"5m"` or milliseconds, options always come last, and every error has a stable `code`.
-- **Tested everywhere.** Linux, macOS and Windows, Node.js 22 and 24, TypeScript 5.9, 6 and 7.
+- **Tested everywhere.** Linux, macOS and Windows, Node.js 22, 24 and 26, TypeScript 5.9, 6 and 7.
 
 ## What's inside
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ix-xs/node-comfort",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The zero-dependency standard library for Node.js: logger, filesystem, SQLite, schema validation, HTTP client, CLI toolkit, cache, env, async pools, colors, events, i18n dates, ids, crypto and hundreds of fully typed helpers.",
   "keywords": [
     "utils",
@@ -178,7 +178,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.13.0"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "publishConfig": {
     "access": "public"

package/src/Arr.js

@@ -65,6 +65,9 @@ const { intl, preciseSum } = require("./internal/shared.js");
 const _fn = (iteratee) => {
   if (typeof iteratee === "function") return /** @type {(item: any, index: number) => any} */ (iteratee);
   if (typeof iteratee === "string" || typeof iteratee === "number" || typeof iteratee === "symbol") {
+    // Members of Object.prototype (`__proto__`, `constructor`...) are not data, unless the item has its own.
+    // Getters of a class still work.
+    if (iteratee in Object.prototype) return (item) => (item == null || !Object.hasOwn(item, iteratee) ? undefined : item[iteratee]);
     return (item) => (item == null ? undefined : item[iteratee]);
   }
   return (item) => item;
@@ -384,6 +387,7 @@ function partition(array, predicate) {
  * @returns {Array<T[K]>}
  */
 function pluck(array, key) {
+  if (key in Object.prototype) return array.map(_fn(key));
   return array.map((item) => (item == null ? /** @type {T[K]} */ (/** @type {unknown} */ (undefined)) : item[key]));
 }
 
@@ -729,7 +733,8 @@ function flatten(array, depth) {
 }
 
 /**
- * Pairs items by position. Shorter arrays leave `undefined` holes.
+ * Pairs items by position. Shorter arrays leave `undefined` holes, and
+ * values that are not arrays count as empty ones.
  *
  * @example
  * arr.zip(["a", "b"], [1, 2]); // [["a", 1], ["b", 2]]
@@ -743,7 +748,8 @@ function zip(...arrays) {
 }
 
 /**
- * The opposite of `zip()`: rows become columns.
+ * The opposite of `zip()`: rows become columns. Rows that are not arrays
+ * count as empty ones.
  *
  * @example
  * arr.unzip([["a", 1], ["b", 2]]); // [["a", "b"], [1, 2]]
@@ -753,15 +759,17 @@ function zip(...arrays) {
  * @returns {Array<Array<T | undefined>>}
  */
 function unzip(tuples) {
-  return _zip(tuples);
+  return Array.isArray(tuples) ? _zip(tuples) : [];
 }
 
 /**
  * @template T
- * @param {ReadonlyArray<ReadonlyArray<T>>} arrays
+ * @param {ReadonlyArray<ReadonlyArray<T>>} input
  * @returns {Array<Array<T | undefined>>}
  */
-const _zip = (arrays) => {
+const _zip = (input) => {
+  // Only real arrays: a parsed `{ "length": 1e9 }` would allocate a billion rows.
+  const arrays = input.map((array) => (Array.isArray(array) ? array : []));
   let size = 0;
   for (const array of arrays) if (array.length > size) size = array.length;
   /** @type {Array<Array<T | undefined>>} */

package/src/Checker.js

@@ -15,13 +15,24 @@ const shared = require("./internal/shared.js");
 
 /** @type {typeof import("node:net") | undefined} */
 let _net;
+/** @type {typeof import("node:url") | undefined} */
+let _url;
 
-const EMAIL = /^(?!\.)(?!.*\.\.)[\p{L}\p{N}.!#$%&'*+/=?^_`{|}~-]{1,64}(?<!\.)@(?:[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?\.)+(?:\p{L}{2,}|xn--[a-z0-9-]{2,})$/iu;
+// No "i" flag: with "u", it would let the Kelvin sign match "k" and the long s match "s".
+const EMAIL = /^(?!\.)(?!.*\.\.)[\p{L}\p{N}.!#$%&'*+/=?^_`{|}~-]{1,64}(?<!\.)@(?:[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?\.)+(?:\p{L}{2,}|[xX][nN]--[A-Za-z0-9-]{2,})$/u;
+// The same rules for ASCII addresses, the common case, which need no further check.
+const EMAIL_ASCII = /^(?!\.)(?!.*\.\.)[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]{1,64}(?<!\.)@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+(?:[A-Za-z]{2,}|[xX][nN]--[A-Za-z0-9-]{2,})$/;
 const TLD = /\.(?:[a-z]{2,}|xn--[a-z0-9-]{2,})\.?$/i;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-([1-8])[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const UUID_NIL_OR_MAX = /^(?:0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$/i;
 const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(?:Z|([+-])(\d{2}):?(\d{2}))?)?$/;
 const HOST_LABEL = /^[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?$/u;
+// Characters a URL parser silently drops, encodes or rewrites.
+// The apostrophe is legal, as in /wiki/Ender's_Game.
+const URL_UNSAFE = /[\x00-\x20\x7f<>"`\\]/;
+// Quoted and bare parameter values can't overlap, so there is nothing to backtrack into.
+const MIME_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(?:\s*;\s*[a-z0-9-]+=(?:"[^"\r\n]*"|[^;\s"]+))*$/i;
+const DATA_URL = /^data:(?:[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+)?(?:;[a-z0-9-]+=[^;,]*)*(?:;base64)?,/i;
 const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 
 /**
@@ -59,6 +70,12 @@ const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
  * @property {boolean} [urlSafe] Expect the URL-safe alphabet (`-` and `_`), padding optional.
  */
 
+/**
+ * Options for `isDataURL()`.
+ * @typedef {object} IsDataURLOptions
+ * @property {string[]} [types] Accepted media types, like `["image/png", "image/jpeg"]`, case ignored. A URL without a type, like `data:,Hello`, counts as `text/plain`. Without this option, any type passes.
+ */
+
 /**
  * Is it an array?
  *
@@ -580,7 +597,10 @@ function isOneOf(value, allowed) {
 /**
  * Does it look like an email address? The rules are practical rather than
  * the full RFC: one `@`, no stray dots, a real top-level domain.
- * International addresses are accepted.
+ * International addresses are accepted, but not look-alike characters such
+ * as the Kelvin sign in the domain. A valid address can still contain
+ * quotes, `&`, `|` or backticks: it is not safe to put unescaped into HTML
+ * or a shell command.
  *
  * @example
  * nc.isEmail("jose@exemple.fr");     // true
@@ -591,11 +611,19 @@ function isOneOf(value, allowed) {
  * @returns {value is string}
  */
 function isEmail(value) {
-  return typeof value === "string" && value.length <= 254 && EMAIL.test(value);
+  if (typeof value !== "string" || value.length > 254) return false;
+  if (EMAIL_ASCII.test(value)) return true;
+  if (shared.ASCII.test(value) || !EMAIL.test(value)) return false;
+  // Compatibility characters (Kelvin sign, fullwidth letters...) become other letters in DNS.
+  const domain = value.slice(value.lastIndexOf("@") + 1);
+  return domain === domain.normalize("NFKC");
 }
 
 /**
  * Is it an absolute URL with an allowed protocol (http and https by default)?
+ * The text must already be clean: spaces, control characters, double
+ * quotes, backticks, `<`, `>` and backslashes are refused, even where the URL
+ * parser would quietly fix them. An apostrophe is fine.
  *
  * @example
  * nc.isURL("https://example.com/a?b=1");                 // true
@@ -607,7 +635,7 @@ function isEmail(value) {
  * @returns {value is string}
  */
 function isURL(value, options = {}) {
-  if (typeof value !== "string") return false;
+  if (typeof value !== "string" || URL_UNSAFE.test(value)) return false;
   const url = URL.parse(value);
   if (!url) return false;
   const protocols = options.protocols;
@@ -891,6 +919,8 @@ function isJWT(value) {
 /**
  * Is it a host name, like `example.com`, `api.internal` or `localhost`?
  * International names are accepted. IP addresses aren't: see `isIP`.
+ * Lengths are counted the way DNS sees them, once converted to ASCII
+ * (`xn--`): 63 bytes per label, 253 in all.
  *
  * @example
  * nc.isHostname("api.example.com");                    // true
@@ -907,6 +937,11 @@ function isHostname(value, options = {}) {
   const labels = value.split(".");
   if (!labels.every((label) => HOST_LABEL.test(label))) return false;
   if (/^\d+$/.test(labels[labels.length - 1])) return false;
+  if (!shared.ASCII.test(value)) {
+    // An international label takes more room once encoded: "é" x 63 is 67 bytes long.
+    const ascii = (_url ??= require("node:url")).domainToASCII(value);
+    if (ascii === "" || ascii.length > 253 || ascii.split(".").some((label) => label.length > 63)) return false;
+  }
   return !options.requireTld || (labels.length > 1 && TLD.test(value));
 }
 
@@ -991,17 +1026,25 @@ function isULID(value) {
 }
 
 /**
- * Is it a `data:` URL, like an inline image?
+ * Is it a `data:` URL, like an inline image? Only the header is checked,
+ * not the data. Without `types`, any media type passes, `text/html` and
+ * `image/svg+xml` included, and both can run scripts.
  *
  * @example
  * nc.isDataURL("data:image/png;base64,iVBORw0KGgo="); // true
  * nc.isDataURL("data:,Hello");                         // true
+ * nc.isDataURL("data:text/html,<p>Hi</p>", { types: ["image/png"] }); // false
  *
  * @param {unknown} value
+ * @param {IsDataURLOptions} [options]
  * @returns {value is string}
  */
-function isDataURL(value) {
-  return typeof value === "string" && /^data:(?:[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+)?(?:;[a-z0-9-]+=[^;,]*)*(?:;base64)?,/i.test(value);
+function isDataURL(value, options = {}) {
+  if (typeof value !== "string" || !DATA_URL.test(value)) return false;
+  const types = options.types;
+  if (!types) return true;
+  const type = value.slice(5, value.search(/[;,]/)).toLowerCase() || "text/plain";
+  return types.some((allowed) => allowed.toLowerCase() === type);
 }
 
 /**
@@ -1016,7 +1059,7 @@ function isDataURL(value) {
  * @returns {value is string}
  */
 function isMimeType(value) {
-  return typeof value === "string" && /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(?:\s*;\s*[a-z0-9-]+=(?:"[^"]*"|[^;\s]+))*$/i.test(value);
+  return typeof value === "string" && MIME_TYPE.test(value);
 }
 
 /**
@@ -1071,6 +1114,11 @@ function isLocale(value) {
  */
 function isCron(value) {
   if (typeof value !== "string") return false;
+  // "*/5/x" is not a step and "1-5-x" is not a range, even though the parser stops reading early.
+  for (const part of value.trim().split(/[\s,]+/)) {
+    const step = part.split("/");
+    if (step.length > 2 || step[0].split("-").length > 2) return false;
+  }
   try {
     shared.parseCron(value);
     return true;

package/src/Cli.js

@@ -6,6 +6,10 @@
  * boxes. When nobody's at the keyboard (CI, pipes), prompts read plain lines
  * and animations print only their final state.
  *
+ * Tables, boxes, trees and menus show what a terminal could act on as text
+ * (`\x1b`, `\r`), so a value can't move the cursor or break the layout.
+ * Colors and links in them still work.
+ *
  * @example
  * const { flags } = cli.args({
  *   port: { type: "number", short: "p", default: 3000, description: "Port to listen on" },
@@ -66,8 +70,12 @@ const { AbortError } = require("./errors.js");
  */
 
 /**
- * A spinner. Every method returns it.
- * @typedef {object} Spinner
+ * A spinner. Every method returns it. With `using`, it stops at the end of the block.
+ * @typedef {_SpinnerMethods & Disposable} Spinner
+ */
+
+/**
+ * @typedef {object} _SpinnerMethods
  * @property {(text?: string) => Spinner} start Starts spinning, optionally with new text.
  * @property {() => Spinner} stop Stops and clears the line.
  * @property {(text?: string) => Spinner} succeed Stops with a green `✔`.
@@ -91,8 +99,12 @@ const { AbortError } = require("./errors.js");
  */
 
 /**
- * A progress bar.
- * @typedef {object} ProgressBar
+ * A progress bar. With `using`, it stops at the end of the block.
+ * @typedef {_ProgressBarMethods & Disposable} ProgressBar
+ */
+
+/**
+ * @typedef {object} _ProgressBarMethods
  * @property {(amount?: number, label?: string) => ProgressBar} tick Adds to the value, 1 by default.
  * @property {(value: number, label?: string) => ProgressBar} update Sets the value.
  * @property {() => ProgressBar} stop Draws the final state and frees the line.
@@ -257,18 +269,28 @@ const _align = (text, width, align) => {
   return text + " ".repeat(gap);
 };
 
+const { safe: _safe } = require("./internal/terminal.js");
+
+/**
+ * Text a terminal can't act on: control characters and escape sequences are
+ * shown as text (`\x1b`, `\r`). Colors and links stay, a cell may be colored
+ * on purpose.
+ * @param {string} text
+ */
+const _text = (text) => _safe(text, true);
+
 /** @param {unknown} value */
 const _cell = (value) => {
   if (value === null || value === undefined) return "";
   if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
   if (typeof value === "object") {
     try {
-      return JSON.stringify(value);
+      return _text(JSON.stringify(value) ?? String(value));
     } catch {
-      return String(value);
+      return _text(String(value));
     }
   }
-  return String(value);
+  return _text(String(value));
 };
 
 /** @param {NodeJS.WriteStream | undefined} stream */
@@ -328,7 +350,7 @@ function table(rows, options = {}) {
   const columns = keys.map((column) => (typeof column === "object" ? column : { key: column }));
   if (!columns.length) return "";
   const showHeader = options.header ?? !isArrayRows;
-  const headers = columns.map((column) => column.header ?? String(column.key));
+  const headers = columns.map((column) => _text(column.header ?? String(column.key)));
   const widths = headers.map((header) => Math.max(markdown ? 3 : 1, showHeader ? color.width(header) : 0));
   const numeric = columns.map(() => rows.length > 0);
 
@@ -409,8 +431,8 @@ function box(text, options = {}) {
   const palette = _palette(options.colors);
   const b = BORDERS[options.border ?? "rounded"];
   const pad = typeof options.padding === "number" ? { x: options.padding, y: Math.floor(options.padding / 2) } : { x: 2, y: 0, ...options.padding };
-  const lines = String(text).split(_LINE_BREAK);
-  const title = options.title ? ` ${options.title} ` : "";
+  const lines = _text(String(text)).split(_LINE_BREAK);
+  const title = options.title ? ` ${_text(options.title)} ` : "";
   let longest = Math.max(options.width ?? 0, color.width(title) + 2 - pad.x * 2);
   for (const line of lines) longest = Math.max(longest, color.width(line));
   const inner = longest + pad.x * 2;
@@ -487,7 +509,8 @@ function tree(data, options = {}) {
     entries.forEach(([label, value], i) => {
       const isLast = i === entries.length - 1;
       const nested = isBranch(value);
-      const text = nested || value === null || value === undefined || value === true ? label : `${label}: ${_cell(value)}`;
+      const name = _text(label);
+      const text = nested || value === null || value === undefined || value === true ? name : `${name}: ${_cell(value)}`;
       const [first, ...rest] = text.split(_LINE_BREAK);
       out.push(indent + (isLast ? last : branch) + first);
       for (const line of rest) out.push(indent + (isLast ? blank : pipe) + line);
@@ -562,6 +585,10 @@ function spinner(text = "", options = {}) {
       return self;
     },
     stop: () => finish("", undefined),
+    [Symbol.dispose]: () => {
+      // Leaving the block early, by an error or a return, stops the spinner: one that already finished stays as it is.
+      if (spinning) finish("", undefined);
+    },
     succeed: (finalText) => finish(_paint(palette, "green", "✔"), finalText),
     fail: (finalText) => finish(_paint(palette, "red", "✖"), finalText),
     warn: (finalText) => finish(_paint(palette, "yellow", "⚠"), finalText),
@@ -698,6 +725,9 @@ function progress(options) {
       stream.write(interactive ? `\n${SHOW_CURSOR}` : `${line()}\n`);
       return self;
     },
+    [Symbol.dispose]() {
+      self.stop();
+    },
     get value() {
       return value;
     },
@@ -908,17 +938,29 @@ async function confirm(question, options = {}) {
 const _normalizeChoices = (choices) =>
   choices.map((c) => (typeof c === "string" ? { label: c, value: /** @type {V} */ (/** @type {unknown} */ (c)) } : c));
 
+/**
+ * The question and its numbered choices, for when nobody can use the arrow keys.
+ * @param {string} question
+ * @param {Array<{ label: string, disabled?: boolean }>} items
+ */
+const _numbered = (question, items) =>
+  `? ${_text(String(question))}\n${items.map((it, i) => `  ${i + 1}. ${_text(String(it.label))}${it.disabled ? " (disabled)" : ""}`).join("\n")}\n`;
+
 /**
  * The arrow-key list behind `select()` and `multiselect()`.
  * @template V
- * @param {string} question
+ * @param {string} rawQuestion
  * @param {Array<{ label: string, value: V, hint?: string, disabled?: boolean }>} items
  * @param {SelectOptions} options
  * @param {boolean} multiple
  * @returns {Promise<number[]>}
  */
-const _interactiveList = (question, items, options, multiple) =>
+const _interactiveList = (rawQuestion, items, options, multiple) =>
   new Promise((resolve, reject) => {
+    // Choices often come from data: shown as text, they can't drive the terminal.
+    const question = _text(String(rawQuestion));
+    const labels = items.map((item) => _text(String(item.label)));
+    const hints = items.map((item) => (item.hint ? _text(String(item.hint)) : ""));
     const input = options.input ?? process.stdin;
     const output = options.output ?? process.stdout;
     const palette = color.create(color.detect(output));
@@ -942,8 +984,8 @@ const _interactiveList = (question, items, options, multiple) =>
         const item = items[i];
         const active = i === cursor;
         const mark = multiple ? (selected.has(i) ? palette.green("◉ ") : "◯ ") : "";
-        const text = item.disabled ? palette.gray(`${item.label} (disabled)`) : active ? palette.cyan(item.label) : item.label;
-        lines.push(`${active ? palette.cyan("❯") : " "} ${mark}${text}${item.hint ? ` ${palette.gray(item.hint)}` : ""}`);
+        const text = item.disabled ? palette.gray(`${labels[i]} (disabled)`) : active ? palette.cyan(labels[i]) : labels[i];
+        lines.push(`${active ? palette.cyan("❯") : " "} ${mark}${text}${hints[i] ? ` ${palette.gray(hints[i])}` : ""}`);
       }
       if (error) lines.push(palette.red(`✖ ${error}`));
       // Going back up assumes one row per line, so nothing may wrap.
@@ -994,7 +1036,7 @@ const _interactiveList = (question, items, options, multiple) =>
         } else {
           const picked = multiple ? [...selected].sort((a, b) => a - b) : [cursor];
           // Fold the list into one line that says what was chosen.
-          output.write(`${_up(drawn)}${CLEAR_BELOW}${_oneRow(`${palette.green("✔")} ${question} ${palette.cyan(picked.map((i) => items[i].label).join(", "))}`, output)}\n`);
+          output.write(`${_up(drawn)}${CLEAR_BELOW}${_oneRow(`${palette.green("✔")} ${question} ${palette.cyan(picked.map((i) => labels[i]).join(", "))}`, output)}\n`);
           cleanup();
           resolve(picked);
           return;
@@ -1038,7 +1080,7 @@ async function select(question, choices, options = {}) {
     return items[index].value;
   }
   const output = options.output ?? process.stdout;
-  output.write(`? ${question}\n${items.map((it, i) => `  ${i + 1}. ${it.label}${it.disabled ? " (disabled)" : ""}`).join("\n")}\n`);
+  output.write(_numbered(question, items));
   for (;;) {
     const answer = (await _ask(`Choose 1-${items.length}${options.default !== undefined ? ` (${options.default + 1})` : ""}: `, input, output)).trim();
     const index = answer === "" && options.default !== undefined ? options.default : Number(answer) - 1;
@@ -1068,7 +1110,7 @@ async function multiselect(question, choices, options = {}) {
     return indexes.map((i) => items[i].value);
   }
   const output = options.output ?? process.stdout;
-  output.write(`? ${question}\n${items.map((it, i) => `  ${i + 1}. ${it.label}${it.disabled ? " (disabled)" : ""}`).join("\n")}\n`);
+  output.write(_numbered(question, items));
   for (;;) {
     const answer = (await _ask("Choose (comma-separated numbers): ", input, output)).trim();
     const indexes = answer === "" ? [] : answer.split(/[\s,]+/).filter(Boolean).map((n) => Number(n) - 1);