@vulkano/core 1.22.1 → 1.23.1

package/README.md

@@ -334,6 +334,7 @@ All files in `app/services/` are auto-loaded as globals. The framework also expo
 | `Crontab`   | Schedule recurring jobs with cron expressions                   |
 | `ApiClient` | HTTP client for calling external APIs (native fetch + undici)   |
 | `Download`  | File download helper                                            |
+| `Upload`    | Validate, save and return the local path of an uploaded file    |
 | `i18n`      | Internationalization via i18next                                |
 | `mongoose`  | Mongoose instance                                               |
 
@@ -341,20 +342,106 @@ All files in `app/services/` are auto-loaded as globals. The framework also expo
 
 ## File Uploads
 
-Vulkano uses [Multer](https://github.com/expressjs/multer) v2. Files are available on `req.files` after a `multipart/form-data` POST:
+Vulkano uses [Multer](https://github.com/expressjs/multer) v2. Files are available on `req.files` after a `multipart/form-data` POST — Multer writes them straight into `PUBLIC_PATH/files` under a temporary name.
+
+### The `Upload` lib
+
+`Upload.file(files, opts)` validates a single uploaded file (mimetype, extension, size, write
+permission) and renames it to its final, safe filename inside `PUBLIC_PATH/files`. It only ever
+touches the local disk — it never uploads anywhere. If your app needs to push the result to a
+cloud provider, chain your own service off the returned `path`:
+
+```js
+// app/controllers/UploadController.js
+module.exports = {
+
+  'post upload': (req, res) => {
+
+    const props = {
+      allowed: ['jpg', 'jpeg', 'png', 'webp'],
+      // For custom mimetypes or mime-to-extension mapping
+      // mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+      maxSize: 10 * 1024 * 1024,
+      lang: req.query.lang   // 'en' (default) or 'es' — controls the error language
+    };
+
+    res.vsr(
+      Upload
+        .file(req.files || [], props)
+        .then((file) => Cloud.upload(file.path).then((url) => ({ ...file, url })))
+    );
+
+  }
+
+};
+```
+
+`Upload.file()` resolves with `{ name, path }` — `name` is the destination filename, `path` the
+absolute local path. SVGs get their content sanitized regardless of the rename strategy —
+`<script>` tags, inline event handler attributes (`onload`, `onclick`, ...) and `javascript:` URIs
+are stripped before the file is saved, since an SVG is just XML that can otherwise carry
+executable code.
+
+**`opts`:**
+
+| Option    | Description                                                              |
+|-----------|---------------------------------------------------------------------------|
+| `allowed` | Array of allowed extensions (e.g. `['jpg', 'png']`). Skipped if omitted   |
+| `maxSize` | Max size in bytes. Defaults to 10MB                                       |
+| `name`    | Restrict to a specific form fieldname. Defaults to the first file sent    |
+| `lang`    | Language for validation error messages. Defaults to `en`                  |
+| `rename`  | Naming strategy for the saved file — see below. Defaults to none          |
+
+**`rename`** controls the destination filename:
 
 ```js
-'post upload': function (req, res) {
-  const files = (req.files || []).map((f) => ({
-    fieldname:    f.fieldname,
-    originalname: f.originalname,
-    mimetype:     f.mimetype,
-    size:         f.size
-  }));
-  res.vsr(Promise.resolve({ uploaded: files.length, files }));
-}
+Upload.file(req.files, { rename: true });                       // uuid, e.g. "3fa2...c9.png"
+Upload.file(req.files, {});                                     // sanitized original name
+Upload.file(req.files, { rename: (file) => `user-${req.auth._id}` }); // custom base name
 ```
 
+- `rename: true` → a random uuid (collision-free, extension kept)
+- omitted / `false` → the sanitized original filename, unchanged
+- a function `(file) => string` → its return value becomes the base name (still sanitized —
+  never trusted as-is, since it could carry `../`)
+
+In every case except the uuid one, if the resulting filename already exists in `PUBLIC_PATH/files`
+a short random suffix is appended so the new upload doesn't silently overwrite it — a plain
+upload with no collision keeps a clean name.
+
+Any of the 5 `opts` keys above (`allowed`, `maxSize`, `name`, `lang`, `rename`) can also be set once
+as project-wide defaults in `app/config/upload.js` — it's a plain JS module merged under the
+`opts` passed on each call, so per-call values win:
+
+```js
+// app/config/upload.js
+module.exports = {
+  allowed: ['jpg', 'jpeg', 'png', 'webp'],
+  maxSize: 10 * 1024 * 1024
+  // name, lang and rename are usually left per-call since they tend to
+  // depend on the request, but they're valid here too
+};
+```
+
+Validation errors are `VSError`s translated through the `i18n` keys `upload.notUploaded`,
+`upload.noPermission`, `upload.invalidMimeType`, `upload.extensionNotAllowed` and
+`upload.maxSizeExceeded` — see [i18n](#i18n) below to override their text per locale.
+
+### Multiple files — `Upload.files()`
+
+Same options as `Upload.file()`, but validates and saves every file sent (optionally restricted to
+one fieldname via `opts.name`) and resolves with an array:
+
+```js
+res.vsr(
+  Upload.files(req.files || [], { allowed: ['jpg', 'png'], name: 'gallery' })
+);
+// → [{ name, path }, { name, path }, ...]
+```
+
+If any file fails validation, the whole call rejects (same as `Promise.all`) — no files are
+partially saved.
+
 ---
 
 ## JWT Authentication
@@ -467,6 +554,10 @@ module.exports = {
 Default language is `en`, with `en` as the fallback if a key or locale is missing. To switch the
 active language at runtime, call `i18n.changeLanguage('es')`.
 
+The core also ships its own default `en`/`es` locale files (currently the `upload.*` keys used by
+the `Upload` lib). They're deep-merged under your project's `app/config/locales/`, so any key you
+declare there wins over the core default — you only need to override the keys you want to change.
+
 ---
 
 ## Socket.io

package/config/locales/en.js

@@ -0,0 +1,18 @@
+/**
+ * Locale — English (core defaults)
+ *
+ * Overridden by matching keys in the project's app/config/locales/en.js
+ *
+ */
+
+module.exports = {
+
+  upload: {
+    notUploaded: 'The file could not be uploaded',
+    noPermission: 'The folder doesn\'t have permission to save the file',
+    invalidMimeType: 'The MIME type of the selected file is not allowed: {{mimetype}}',
+    extensionNotAllowed: 'The extension file is not allowed: {{ext}}',
+    maxSizeExceeded: 'The file exceeds the maximum allowed size of {{size}}MB'
+  }
+
+};

package/config/locales/es.js

@@ -0,0 +1,18 @@
+/**
+ * Locale — Español (defaults del core)
+ *
+ * Sobreescrito por las mismas claves en app/config/locales/es.js del proyecto
+ *
+ */
+
+module.exports = {
+
+  upload: {
+    notUploaded: 'No se pudo subir el archivo',
+    noPermission: 'La carpeta no tiene permisos para guardar el archivo',
+    invalidMimeType: 'El tipo MIME del archivo seleccionado no está permitido: {{mimetype}}',
+    extensionNotAllowed: 'La extensión del archivo no está permitida: {{ext}}',
+    maxSizeExceeded: 'El archivo excede el tamaño máximo permitido de {{size}}MB'
+  }
+
+};

package/libs/Upload.js

@@ -0,0 +1,366 @@
+/* global VSError, i18n */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+
+const { rename, readFile, writeFile, unlink } = fs.promises;
+
+// Strips executable content from an SVG (a text/XML format) before it's
+// served as an "image" — <script>, inline event handlers and javascript:
+// URIs would otherwise run in the browser of anyone who opens the file.
+function sanitizeSvg(content) {
+
+  return content
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/\son\w+\s*=\s*"[^"]*"/gi, '')
+    .replace(/\son\w+\s*=\s*'[^']*'/gi, '')
+    .replace(/((?:xlink:)?href)\s*=\s*"\s*javascript:[^"]*"/gi, '$1=""')
+    .replace(/((?:xlink:)?href)\s*=\s*'\s*javascript:[^']*'/gi, '$1=\'\'');
+
+}
+
+const IMAGE_MIME_TYPES = ['image/jpeg', 'image/jpg', 'image/pjpeg', 'image/gif', 'image/png', 'image/webp', 'image/svg+xml', 'image/heic', 'image/heif'];
+const DOCUMENT_MIME_TYPES = ['application/pdf', 'application/x-pdf', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/vnd.ms-excel', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.ms-powerpoint', 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'text/csv', 'application/vnd.ms-excel.sheet.binary.macroenabled.12'];
+const ARCHIVE_MIME_TYPES = ['application/zip', 'application/x-rar', 'application/gzip', 'text/plain', 'application/x-zip-compressed'];
+const VIDEO_MIME_TYPES = ['video/quicktime', 'video/ogg', 'video/webm', 'video/mp4', 'video/x-mp4', 'video/3gp', 'video/x-3gp', 'video/mov', 'video/x-mov', 'video/m4v', 'video/x-m4v', 'video/avi', 'video/x-avi', 'video/mpg', 'video/x-mpg'];
+
+const VALID_MIME_TYPES = [...IMAGE_MIME_TYPES, ...DOCUMENT_MIME_TYPES, ...ARCHIVE_MIME_TYPES, ...VIDEO_MIME_TYPES];
+
+// Fallback when originalname has no usable extension (e.g. a blob)
+const MIME_EXTENSION_MAP = {
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/pjpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/png': 'png',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+  'image/heic': 'heic',
+  'image/heif': 'heif',
+  'application/pdf': 'pdf',
+  'application/x-pdf': 'pdf',
+  'application/msword': 'doc',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx',
+  'application/vnd.ms-excel': 'xls',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',
+  'application/vnd.ms-powerpoint': 'ppt',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'pptx',
+  'text/csv': 'csv',
+  'application/vnd.ms-excel.sheet.binary.macroenabled.12': 'xlsb',
+  'application/zip': 'zip',
+  'application/x-zip-compressed': 'zip',
+  'application/x-rar': 'rar',
+  'application/gzip': 'gz',
+  'text/plain': 'txt',
+  'video/quicktime': 'mov',
+  'video/mov': 'mov',
+  'video/x-mov': 'mov',
+  'video/ogg': 'ogv',
+  'video/webm': 'webm',
+  'video/mp4': 'mp4',
+  'video/x-mp4': 'mp4',
+  'video/3gp': '3gp',
+  'video/x-3gp': '3gp',
+  'video/m4v': 'm4v',
+  'video/x-m4v': 'm4v',
+  'video/avi': 'avi',
+  'video/x-avi': 'avi',
+  'video/mpg': 'mpg',
+  'video/x-mpg': 'mpg'
+};
+
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024;
+
+module.exports = {
+
+  /**
+   * Validate a single multer file object and move it into its final public
+   * location. Internal helper shared by Upload.file() and Upload.files().
+   *
+   * @param {Object} file
+   * @param {Object} props - { allowed, maxSize, lang, rename }
+   * @returns {Promise<{name: string, path: string}>}
+   */
+  _saveFile(file, props) {
+
+    const {
+      allowed,
+      mimeTypes,
+      extensionMap,
+      maxSize,
+      lang
+    } = props;
+
+    const t = (key, vars) => i18n.t(key, { lng: lang || 'en', ...vars });
+
+    return Promise
+      .resolve()
+      .then(() => {
+
+        const publicDir = path.join(PUBLIC_PATH, 'files');
+        if (!Upload.isWritable(publicDir)) {
+          throw new VSError(t('upload.noPermission'), 500);
+        }
+
+        if (!Upload.isValidMimeType(file, mimeTypes)) {
+          throw new VSError(t('upload.invalidMimeType', { mimetype: file.mimetype }), 400);
+        }
+
+        const ext = Upload.getExtension(file, extensionMap);
+
+        if (allowed && Array.isArray(allowed) && !allowed.includes(ext)) {
+          throw new VSError(t('upload.extensionNotAllowed', { ext }), 400);
+        }
+
+        const limit = maxSize || DEFAULT_MAX_SIZE;
+        if (file.size > limit) {
+          throw new VSError(t('upload.maxSizeExceeded', { size: Math.floor(limit / (1024 * 1024)) }), 400);
+        }
+
+        return { ext, publicDir };
+
+      })
+      .then(({ ext, publicDir }) => {
+
+        const safeName = Upload.buildSafeName(file, ext, props, publicDir);
+
+        file.originalname = safeName;
+
+        const filePath = path.normalize(file.path);
+        const filePublic = path.join(publicDir, safeName);
+
+        const save = ext === 'svg'
+          ? readFile(filePath, 'utf8')
+            .then((content) => writeFile(filePublic, sanitizeSvg(content)))
+            .then(() => unlink(filePath))
+          : rename(filePath, filePublic);
+
+        return save.then(() => ({
+          name: file.originalname,
+          path: filePublic
+        }));
+
+      });
+
+  },
+
+  /**
+   * Validate a single uploaded file and move it from multer's temp path to
+   * its final public location. Never uploads to any cloud provider -
+   * callers needing that should chain a separate service off the returned
+   * path.
+   *
+   * @param {Array} files - req.files array from multer
+   * @param {Object} opts - { allowed, maxSize, name, lang, rename }
+   * @returns {Promise<{name: string, path: string}>}
+   */
+  file(files, opts) {
+
+    const uploadConfig = app.config && app.config.upload;
+    const props = { ...uploadConfig, ...opts };
+
+    const file = Upload.isUploaded(files, props.name);
+    const t = (key, vars) => i18n.t(key, { lng: props.lang || 'en', ...vars });
+
+    if (!file) {
+      return Promise.reject(new VSError(t('upload.notUploaded'), 400));
+    }
+
+    return Upload._saveFile(file, props);
+
+  },
+
+  /**
+   * Same as Upload.file() but validates and saves every matching file.
+   * Rejects on the first invalid file (same as Promise.all).
+   *
+   * @param {Array} files - req.files array from multer
+   * @param {Object} opts - { allowed, maxSize, name, lang, rename }
+   * @returns {Promise<Array<{name: string, path: string}>>}
+   */
+  files(files, opts) {
+
+    const uploadConfig = app.config && app.config.upload;
+    const props = { ...uploadConfig, ...opts };
+
+    const matched = Upload.isUploadedMany(files, props.name);
+    const t = (key, vars) => i18n.t(key, { lng: props.lang || 'en', ...vars });
+
+    if (!matched.length) {
+      return Promise.reject(new VSError(t('upload.notUploaded'), 400));
+    }
+
+    return Promise.all(matched.map((file) => Upload._saveFile(file, props)));
+
+  },
+
+  /**
+   * Check if a file was uploaded for the expected field.
+   *
+   * @param {Array} file - req.files array from multer
+   * @param {string} fieldname
+   * @returns {Object|false}
+   */
+  isUploaded(file, fieldname) {
+
+    const tmp = (file && file[0]) || null;
+    if (!tmp) {
+      return false;
+    }
+    return (!fieldname || tmp.fieldname === fieldname) ? tmp : false;
+
+  },
+
+  /**
+   * Same as isUploaded() but returns every matching file instead of just
+   * the first one.
+   *
+   * @param {Array} files - req.files array from multer
+   * @param {string} fieldname
+   * @returns {Array}
+   */
+  isUploadedMany(files, fieldname) {
+
+    if (!Array.isArray(files)) {
+      return [];
+    }
+    return fieldname ? files.filter((f) => f.fieldname === fieldname) : files;
+
+  },
+
+  /**
+   * Check if a directory is writable.
+   *
+   * @param {string} dir
+   * @returns {boolean}
+   */
+  isWritable(dir) {
+
+    try {
+      fs.accessSync(dir, fs.constants.W_OK);
+      return true;
+    } catch (err) {
+      return false;
+    }
+
+  },
+
+  /**
+   * Get the lowercased file extension, falling back to mimetype lookup.
+   *
+   * `extensionMap` (from `props.extensionMap`) lets a caller extend the
+   * built-in mimetype→extension fallback with types the core doesn't know
+   * about yet - needed for a nameless upload (e.g. a blob) whose extension
+   * can only be derived from its mimetype, such as
+   * `extensionMap: { 'image/heic': 'heic' }`.
+   *
+   * @param {Object} file
+   * @param {Object} [extensionMap] - extra mimetype→extension entries, checked before the built-in map
+   * @returns {string}
+   */
+  getExtension(file, extensionMap) {
+
+    let ext = (file.originalname || '').split('.').pop();
+
+    if (!ext || ext === 'blob' || ext === file.originalname) {
+      ext = (extensionMap && extensionMap[file.mimetype]) || MIME_EXTENSION_MAP[file.mimetype] || '';
+    }
+
+    return ext.toLowerCase();
+
+  },
+
+  /**
+   * Check if the file's mimetype is in the allowed list.
+   *
+   * `mimeTypes` (from `props.mimeTypes`) lets a caller extend the built-in
+   * whitelist with mimetypes the core doesn't know about yet, without
+   * having to fork this file - e.g. `mimeTypes: ['image/heic']`.
+   *
+   * @param {Object} file
+   * @param {Array} [mimeTypes] - extra mimetypes to accept, in addition to VALID_MIME_TYPES
+   * @returns {boolean}
+   */
+  isValidMimeType(file, mimeTypes) {
+
+    const extra = Array.isArray(mimeTypes) ? mimeTypes : [];
+    return VALID_MIME_TYPES.includes(file.mimetype) || extra.includes(file.mimetype);
+
+  },
+
+  /**
+   * Build the destination filename.
+   *
+   * - `props.rename === true`      → random uuid (extension kept)
+   * - `props.rename` is a function → `props.rename(file)` picks the base
+   *   name (still sanitized here - never trust it as-is, it can carry `../`)
+   * - otherwise                    → sanitized original name, unchanged
+   *
+   * In every case except the uuid one, a short suffix is appended only if
+   * the resulting name already exists in `publicDir`, so a normal upload
+   * keeps a clean name and only collisions get disambiguated.
+   *
+   * @param {Object} file
+   * @param {string} ext
+   * @param {Object} props - { rename }
+   * @param {string} publicDir
+   * @returns {string}
+   */
+  buildSafeName(file, ext, props, publicDir) {
+
+    const { rename: renameOpt } = props || {};
+
+    if (renameOpt === true) {
+      return `${crypto.randomUUID()}.${ext}`;
+    }
+
+    const source = typeof renameOpt === 'function'
+      ? renameOpt(file)
+      : path.basename(file.originalname || 'file', path.extname(file.originalname || ''));
+
+    const base = Upload.sanitizeBaseName(source);
+
+    return Upload.ensureUniqueName(publicDir, base, ext);
+
+  },
+
+  /**
+   * Strip anything that isn't alphanumeric/underscore/dash - originalname
+   * (and any custom name from `rename`) must never be trusted directly,
+   * it can carry `../` path segments.
+   *
+   * @param {string} name
+   * @returns {string}
+   */
+  sanitizeBaseName(name) {
+
+    return String(name || '')
+      .replace(/[^a-zA-Z0-9_-]/g, '_')
+      .slice(0, 100) || 'file';
+
+  },
+
+  /**
+   * Append a short random suffix only if `base.ext` already exists in dir,
+   * so an upload without a rename strategy doesn't silently overwrite an
+   * existing file.
+   *
+   * @param {string} dir
+   * @param {string} base
+   * @param {string} ext
+   * @returns {string}
+   */
+  ensureUniqueName(dir, base, ext) {
+
+    let candidate = `${base}.${ext}`;
+
+    while (fs.existsSync(path.join(dir, candidate))) {
+      candidate = `${base}_${crypto.randomBytes(3).toString('hex')}.${ext}`;
+    }
+
+    return candidate;
+
+  }
+
+};

package/libs/i18n.js

@@ -1,4 +1,10 @@
 const i18next = require('i18next');
+const merge = require('./Merge');
+
+const coreLocales = {
+  en: require('../config/locales/en'),
+  es: require('../config/locales/es')
+};
 
 module.exports = (() => {
 
@@ -6,15 +12,11 @@ module.exports = (() => {
     config
   } = app || {};
 
-  let {
-    locales: configLocales
+  const {
+    locales: projectLocales
   } = config || {};
 
-  if (!configLocales) {
-    configLocales = {
-      en: {}
-    };
-  }
+  const configLocales = merge.all([coreLocales, projectLocales || {}]);
 
   const locales = Object.keys(configLocales);
   const resources = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vulkano/core",
-  "version": "1.22.1",
+  "version": "1.23.1",
   "description": "A MVC framework using Express 4",
   "license": "MIT",
   "author": "Vulkano Team",