@appweaver/core 1.1.2 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/core",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Appweaver - the backend framework for AI-first development (@core)",
   "author": "Luka Matosevic",
   "license": "MIT",

package/resource/resource-loader.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadResources = loadResources;
 const typebox_1 = require("@sinclair/typebox");
 const common_1 = require("@appweaver/common");
+const utils_1 = require("../utils");
 /**
  * Loads application resources including models, services, policies, and routes.
  *
@@ -50,6 +51,9 @@ async function loadModels(baseDir, modelPattern) {
             }
         }
     }
+    // Reject file name patterns writing into a reserved storage path before any
+    // upload can reach the storage layer.
+    (0, utils_1.validateFileNamePatterns)(models);
     // Map model variants to schemas using their corresponding suffixes
     const resourceModels = {};
     for (const model of Object.values(models)) {

package/security/jwt/jwt-keys.js

@@ -10,6 +10,12 @@ const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_util_1 = require("node:util");
 const node_crypto_1 = require("node:crypto");
+/** Permissions of the directory holding the security keys (owner only). */
+const KEYS_DIR_MODE = 0o700;
+/** Permissions of the generated private key file (owner read/write only). */
+const PRIVATE_KEY_MODE = 0o600;
+/** Permissions of the generated public key file (owner read/write, others read). */
+const PUBLIC_KEY_MODE = 0o644;
 async function ensureSecurityKeys(publicKeyPath, privateKeyPath, generateIfNotExists) {
     try {
         await promises_1.default.access(publicKeyPath, promises_1.default.constants.F_OK);
@@ -30,10 +36,22 @@ async function generateSecurityKeys(publicKeyPath, privateKeyPath) {
         publicKeyEncoding: { type: 'spki', format: 'pem' },
         privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
     });
-    await promises_1.default.mkdir(node_path_1.default.dirname(publicKeyPath), { recursive: true });
-    await promises_1.default.writeFile(publicKeyPath, publicKey, 'utf8');
-    await promises_1.default.mkdir(node_path_1.default.dirname(privateKeyPath), { recursive: true });
-    await promises_1.default.writeFile(privateKeyPath, privateKey, 'utf8');
+    await promises_1.default.mkdir(node_path_1.default.dirname(publicKeyPath), {
+        recursive: true,
+        mode: KEYS_DIR_MODE
+    });
+    await promises_1.default.writeFile(publicKeyPath, publicKey, {
+        encoding: 'utf8',
+        mode: PUBLIC_KEY_MODE
+    });
+    await promises_1.default.mkdir(node_path_1.default.dirname(privateKeyPath), {
+        recursive: true,
+        mode: KEYS_DIR_MODE
+    });
+    await promises_1.default.writeFile(privateKeyPath, privateKey, {
+        encoding: 'utf8',
+        mode: PRIVATE_KEY_MODE
+    });
 }
 async function loadSecurityKeys(publicKeyPath, privateKeyPath, generateIfNotExists) {
     const keysExisted = await ensureSecurityKeys(publicKeyPath, privateKeyPath, generateIfNotExists);

package/storage/file-service.d.ts

@@ -14,7 +14,8 @@ export declare class FileService {
      *
      * @param {string} fileName - The name of the file to search for.
      * @return {Promise<File>} A promise that resolves to the file object if found.
-     * @throws {HttpError} Throws an error if a database error occurs or if the file is not found.
+     * @throws {HttpError} Throws an error if the file name is placed under a reserved storage path, if a database error
+     * occurs, or if the file is not found.
      */
     findByName(fileName: string): Promise<File>;
     /**

package/storage/file-service.js

@@ -20,9 +20,11 @@ class FileService {
      *
      * @param {string} fileName - The name of the file to search for.
      * @return {Promise<File>} A promise that resolves to the file object if found.
-     * @throws {HttpError} Throws an error if a database error occurs or if the file is not found.
+     * @throws {HttpError} Throws an error if the file name is placed under a reserved storage path, if a database error
+     * occurs, or if the file is not found.
      */
     async findByName(fileName) {
+        this.assertPathNotReserved(fileName);
         let file;
         try {
             file = (await this._db.client().file.findFirst({
@@ -135,6 +137,9 @@ class FileService {
             userId: identity?.id,
             userEmail: identity?.email
         });
+        // The generated name may come from a name pattern configured as a function,
+        // which cannot be validated on startup, so it is checked here as well.
+        this.assertPathNotReserved(generatedName);
         let nameRegenCount = 0;
         while (await this._storage.exists(generatedName)) {
             nameRegenCount++;
@@ -400,6 +405,13 @@ class FileService {
         return deletedFiles;
     }
     /** @internal */
+    assertPathNotReserved(fileName) {
+        const reservedPath = (0, common_1.findReservedStoragePath)(fileName, common_1.config.STORAGE_RESERVED_PATHS);
+        if (reservedPath !== null) {
+            throw new errors_1.HttpError(`File path '${fileName}' is not allowed`, 400);
+        }
+    }
+    /** @internal */
     async deleteSafe(fileName) {
         let success = true;
         try {

package/storage/filesystem-storage.js

@@ -11,16 +11,19 @@ const promises_2 = require("node:stream/promises");
 const common_1 = require("@appweaver/common");
 class FilesystemStorage extends common_1.Storage {
     /** @internal */
-    _dirPath = common_1.config.STORAGE_PATH;
+    _dirPath = node_path_1.default.resolve(common_1.config.STORAGE_PATH);
     async onInit() {
-        const directoryExists = await this.exists('');
+        const directoryExists = await this.pathExists(this._dirPath);
         if (!directoryExists) {
             await promises_1.default.mkdir(this._dirPath, { recursive: true });
             common_1.logger.info(`Storage directory initialized: ${this._dirPath}`);
         }
     }
     async stream(fileName, start = 0, end) {
-        const filePath = `${this._dirPath}/${fileName}`;
+        const filePath = this.resolveFilePath(fileName, 'stream');
+        if (!filePath) {
+            return null;
+        }
         try {
             const { size } = await promises_1.default.stat(filePath);
             const endIndex = start >= 0 && !end && end !== 0
@@ -38,10 +41,16 @@ class FilesystemStorage extends common_1.Storage {
         }
     }
     async store(fileName, data) {
-        const filePath = await this.getFilePath(fileName, true);
+        const filePath = this.resolveFilePath(fileName, 'store');
+        if (!filePath) {
+            // The stream must still be consumed to prevent request from hanging.
+            data.resume();
+            return null;
+        }
         try {
+            await this.ensureDirectoryExists(filePath);
             await (0, promises_2.pipeline)(data, node_fs_1.default.createWriteStream(filePath));
-            return fileName;
+            return (0, common_1.normalizeStoragePath)(fileName) ?? fileName;
         }
         catch (e) {
             common_1.logger.error(e, `Error storing file: ${filePath}`);
@@ -49,7 +58,10 @@ class FilesystemStorage extends common_1.Storage {
         }
     }
     async delete(fileName) {
-        const filePath = await this.getFilePath(fileName);
+        const filePath = this.resolveFilePath(fileName, 'delete');
+        if (!filePath) {
+            return false;
+        }
         try {
             await promises_1.default.unlink(filePath);
             await this.removeEmptyDirectories(node_path_1.default.dirname(filePath));
@@ -61,14 +73,11 @@ class FilesystemStorage extends common_1.Storage {
         }
     }
     async exists(fileName) {
-        const filePath = await this.getFilePath(fileName);
-        try {
-            await promises_1.default.access(filePath, node_fs_1.default.constants.F_OK);
-            return true;
-        }
-        catch (e) {
+        const filePath = this.resolveFilePath(fileName, 'exists');
+        if (!filePath) {
             return false;
         }
+        return this.pathExists(filePath);
     }
     async checkHealth() {
         try {
@@ -80,14 +89,30 @@ class FilesystemStorage extends common_1.Storage {
         }
     }
     /** @internal */
-    async getFilePath(fileName, mkdir = false) {
-        const filePath = `${this._dirPath}/${fileName}`;
-        if (mkdir) {
-            await this.ensureDirectoryExists(filePath);
+    resolveFilePath(fileName, action) {
+        const filePath = (0, common_1.resolveStoragePath)(this._dirPath, fileName);
+        if (!filePath) {
+            common_1.logger.error({ fileName, action }, 'Rejected invalid storage file path');
+            return null;
+        }
+        const reservedPath = (0, common_1.findReservedStoragePath)(fileName, common_1.config.STORAGE_RESERVED_PATHS);
+        if (reservedPath !== null) {
+            common_1.logger.error({ fileName, action, reservedPath }, 'Rejected reserved storage file path');
+            return null;
         }
         return filePath;
     }
     /** @internal */
+    async pathExists(filePath) {
+        try {
+            await promises_1.default.access(filePath, node_fs_1.default.constants.F_OK);
+            return true;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    /** @internal */
     async removeEmptyDirectories(filePath) {
         const normalizedDirPath = node_path_1.default.normalize(filePath);
         if (!normalizedDirPath ||
@@ -117,10 +142,7 @@ class FilesystemStorage extends common_1.Storage {
     /** @internal */
     async ensureDirectoryExists(filePath) {
         const dirname = node_path_1.default.dirname(filePath);
-        try {
-            await promises_1.default.access(dirname, node_fs_1.default.constants.F_OK);
-        }
-        catch (e) {
+        if (!(await this.pathExists(dirname))) {
             await promises_1.default.mkdir(dirname, { recursive: true });
         }
     }

package/utils/file-util.d.ts

@@ -1,4 +1,4 @@
-import { FilesConfig } from '@appweaver/common';
+import { FilesConfig, ResourceModel } from '@appweaver/common';
 import { File } from '../types';
 /**
  * Builds the access URL for a stored file. The `public` or `protected` path prefix is resolved from the access type
@@ -55,12 +55,31 @@ export declare function isValidMimeType(mimeType: string, mimeTypeExp?: string |
  */
 export declare function generateFileName(name: string, pattern?: string, variables?: Record<string, any>): string;
 /**
- * Sanitizes a given filename by removing invalid characters that are not allowed in file systems.
+ * Validates that no configured file name pattern writes into a path reserved by `STORAGE_RESERVED_PATHS`. Both the
+ * global `STORAGE_NAME_PATTERN` and the `namePattern` of every file field of the provided models are checked. Patterns
+ * defined as a factory function cannot be resolved before an upload, so they are validated at runtime instead.
+ *
+ * @param {Record<string, ResourceModel>} models - The loaded resource models, keyed by model name.
+ * @throws {Error} Throws an error naming the model, the field, and the reserved path when a pattern is reserved.
+ */
+export declare function validateFileNamePatterns(models: Record<string, ResourceModel>): void;
+/**
+ * Sanitizes a given filename by removing invalid characters that are not allowed in file systems. Path separators are
+ * preserved, since a file name may be a path relative to the storage root.
  *
  * @param fileName The original filename to sanitize.
  * @return A sanitized filename with invalid characters removed.
  */
 export declare function sanitizeFilename(fileName: string): string;
+/**
+ * Sanitizes an untrusted value into a single file path segment. In addition to the characters removed by
+ * {@link sanitizeFilename}, all path separators are stripped and leading dots are removed, so that the value can never
+ * introduce a subdirectory, a `..` traversal or a hidden file.
+ *
+ * @param value The untrusted value to sanitize.
+ * @return A sanitized single path segment, or an empty string when nothing usable remains.
+ */
+export declare function sanitizeFileSegment(value?: string | null): string;
 /**
  * Aggregates the provided files into a structured object based on the given configuration.
  *

package/utils/file-util.js

@@ -6,7 +6,9 @@ exports.maxFileSize = maxFileSize;
 exports.sizeInBytes = sizeInBytes;
 exports.isValidMimeType = isValidMimeType;
 exports.generateFileName = generateFileName;
+exports.validateFileNamePatterns = validateFileNamePatterns;
 exports.sanitizeFilename = sanitizeFilename;
+exports.sanitizeFileSegment = sanitizeFileSegment;
 exports.aggregateFiles = aggregateFiles;
 const common_1 = require("@appweaver/common");
 const context_1 = require("../context");
@@ -106,25 +108,100 @@ function generateFileName(name, pattern, variables = {}) {
         nameWithoutExtension = nameParts.join('.');
     }
     const defaultPattern = common_1.config.STORAGE_NAME_PATTERN ?? '{name}-{hash}.{extension}';
+    // Only the pattern itself is trusted to contain directory separators, every substituted value is reduced to a
+    // single path segment so that an uploaded file name cannot introduce a sub-path or a traversal.
     let fileName = (0, common_1.replacePatternVariables)(pattern ?? defaultPattern, {
-        name: nameWithoutExtension,
-        extension,
-        ...variables
+        ...sanitizeVariables(variables),
+        name: sanitizeFileSegment(nameWithoutExtension),
+        extension: sanitizeFileSegment(extension)
     });
     fileName = sanitizeFilename(fileName);
     fileName = fileName.endsWith('.')
         ? fileName.substring(0, fileName.length - 1)
         : fileName;
-    return fileName || name;
+    return ((0, common_1.normalizeStoragePath)(fileName) ||
+        sanitizeFileSegment(name) ||
+        (0, common_1.generateToken)('bytes', 32));
 }
 /**
- * Sanitizes a given filename by removing invalid characters that are not allowed in file systems.
+ * Validates that no configured file name pattern writes into a path reserved by `STORAGE_RESERVED_PATHS`. Both the
+ * global `STORAGE_NAME_PATTERN` and the `namePattern` of every file field of the provided models are checked. Patterns
+ * defined as a factory function cannot be resolved before an upload, so they are validated at runtime instead.
+ *
+ * @param {Record<string, ResourceModel>} models - The loaded resource models, keyed by model name.
+ * @throws {Error} Throws an error naming the model, the field, and the reserved path when a pattern is reserved.
+ */
+function validateFileNamePatterns(models) {
+    const reservedPaths = common_1.config.STORAGE_RESERVED_PATHS;
+    const globalReservedPath = (0, common_1.findReservedStoragePath)(common_1.config.STORAGE_NAME_PATTERN, reservedPaths);
+    if (globalReservedPath !== null) {
+        throw new Error(`Configured STORAGE_NAME_PATTERN '${common_1.config.STORAGE_NAME_PATTERN}' is placed under the reserved ` +
+            `storage path '${globalReservedPath}'`);
+    }
+    for (const model of Object.values(models)) {
+        for (const [field, fileConfig] of Object.entries(model.config.files ?? {})) {
+            if (!(0, common_1.isString)(fileConfig.namePattern)) {
+                continue;
+            }
+            const reservedPath = (0, common_1.findReservedStoragePath)(fileConfig.namePattern, reservedPaths);
+            if (reservedPath !== null) {
+                throw new Error(`File name pattern '${fileConfig.namePattern}' of the '${model.name}.${field}' field is placed ` +
+                    `under the reserved storage path '${reservedPath}'`);
+            }
+        }
+    }
+}
+/**
+ * Sanitizes a given filename by removing invalid characters that are not allowed in file systems. Path separators are
+ * preserved, since a file name may be a path relative to the storage root.
  *
  * @param fileName The original filename to sanitize.
  * @return A sanitized filename with invalid characters removed.
  */
 function sanitizeFilename(fileName) {
-    return fileName.replace(/[\\:*?"<>|]/g, '');
+    const invalidFilenameChars = new Set([
+        '\\',
+        ':',
+        '*',
+        '?',
+        '"',
+        '<',
+        '>',
+        '|'
+    ]);
+    return [...fileName]
+        .filter((char) => {
+        const code = char.charCodeAt(0);
+        // Strip control characters (including NUL) and characters invalid in file names.
+        return code > 31 && code !== 127 && !invalidFilenameChars.has(char);
+    })
+        .join('');
+}
+/**
+ * Sanitizes an untrusted value into a single file path segment. In addition to the characters removed by
+ * {@link sanitizeFilename}, all path separators are stripped and leading dots are removed, so that the value can never
+ * introduce a subdirectory, a `..` traversal or a hidden file.
+ *
+ * @param value The untrusted value to sanitize.
+ * @return A sanitized single path segment, or an empty string when nothing usable remains.
+ */
+function sanitizeFileSegment(value) {
+    if (!(0, common_1.isString)(value)) {
+        return '';
+    }
+    // Trimming must precede the leading dot removal, otherwise a padded value such as '  ..  ' keeps its dots.
+    return sanitizeFilename(value)
+        .replace(/[/\\]+/g, '')
+        .trim()
+        .replace(/^\.+/, '')
+        .trim();
+}
+/** @internal */
+function sanitizeVariables(variables) {
+    return Object.fromEntries(Object.entries(variables).map(([key, value]) => [
+        key,
+        (0, common_1.isString)(value) ? sanitizeFileSegment(value) : value
+    ]));
 }
 /**
  * Aggregates the provided files into a structured object based on the given configuration.