@nest-omni/core 4.1.3-11 → 4.1.3-13

package/dist/file-upload/services/file-signature-validator.service.js

@@ -0,0 +1,376 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var FileSignatureValidator_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSignatureValidator = void 0;
+const common_1 = require("@nestjs/common");
+const mime_registry_service_1 = require("./mime-registry.service");
+const fs = require("fs-extra");
+/**
+ * 文件签名验证服务
+ */
+let FileSignatureValidator = FileSignatureValidator_1 = class FileSignatureValidator {
+    constructor(mimeRegistry, customTypes) {
+        this.mimeRegistry = mimeRegistry;
+        this.logger = new common_1.Logger(FileSignatureValidator_1.name);
+        this.defaultSignatures = new Map();
+        this.initializeDefaultSignatures();
+        if (customTypes) {
+            this.registerCustomSignatures(customTypes);
+        }
+    }
+    /**
+     * 验证文件签名
+     */
+    validateFileSignature(filePath, expectedTypes, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const maxBytes = (options === null || options === void 0 ? void 0 : options.maxReadBytes) || 2048;
+            // 读取文件头
+            const buffer = yield this.readFileBuffer(filePath, maxBytes);
+            // 检测实际文件类型
+            const detectedTypes = yield this.detectFileTypes(buffer);
+            // 验证期望的类型
+            const isValid = expectedTypes.some((type) => this.matchesType(buffer, type));
+            // 检查文件完整性
+            const integrity = yield this.checkFileIntegrity(filePath, buffer);
+            // 获取文件大小
+            const stats = yield fs.stat(filePath);
+            return {
+                valid: isValid && integrity.valid,
+                detectedTypes,
+                expectedTypes,
+                errors: [
+                    ...(!isValid
+                        ? this.getValidationError(detectedTypes, expectedTypes)
+                        : []),
+                    ...(!integrity.valid ? integrity.errors : []),
+                ],
+                metadata: {
+                    fileSize: stats.size,
+                    confidence: this.calculateConfidence(buffer, detectedTypes),
+                    signatures: detectedTypes.map((t) => ({
+                        type: t.type,
+                        signature: t.signature,
+                    })),
+                },
+            };
+        });
+    }
+    /**
+     * 检测文件类型
+     */
+    detectFileTypes(buffer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const detected = [];
+            // 检查内置签名
+            for (const [mimeType, signatures] of this.defaultSignatures.entries()) {
+                for (const signature of signatures) {
+                    if (this.matchesSignature(buffer, signature)) {
+                        detected.push({
+                            type: mimeType,
+                            signature,
+                            confidence: this.calculateSignatureConfidence(signature),
+                        });
+                        break;
+                    }
+                }
+            }
+            // 检查自定义签名
+            const registeredTypes = this.mimeRegistry.getAllRegisteredTypes();
+            for (const typeName of registeredTypes) {
+                const config = this.mimeRegistry.getMimeConfig(typeName);
+                if (config === null || config === void 0 ? void 0 : config.signatures) {
+                    const signatures = Array.isArray(config.signatures)
+                        ? config.signatures
+                        : [config.signatures];
+                    for (const signature of signatures) {
+                        if (this.matchesSignature(buffer, signature)) {
+                            detected.push({
+                                type: typeName,
+                                signature,
+                                confidence: this.calculateSignatureConfidence(signature),
+                                isCustom: true,
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+            // 按置信度排序
+            return detected.sort((a, b) => b.confidence - a.confidence);
+        });
+    }
+    /**
+     * 注册自定义签名
+     */
+    registerCustomSignatures(customTypes) {
+        if (!customTypes || typeof customTypes !== 'object') {
+            this.logger.warn('Invalid custom types provided to registerCustomSignatures');
+            return;
+        }
+        Object.entries(customTypes).forEach(([typeName, config]) => {
+            if (config === null || config === void 0 ? void 0 : config.signature) {
+                const signatures = Array.isArray(config.signature)
+                    ? config.signature
+                    : [config.signature];
+                this.defaultSignatures.set(typeName, signatures);
+                this.logger.debug(`Registered custom signatures for: ${typeName}`);
+            }
+        });
+    }
+    /**
+     * 检查签名是否匹配
+     */
+    matchesSignature(buffer, signature) {
+        const offset = signature.offset || 0;
+        const bytes = this.normalizeSignatureBytes(signature.bytes);
+        const length = signature.length || bytes.length;
+        // 检查边界
+        if (offset + length > buffer.length) {
+            return false;
+        }
+        const bufferSlice = buffer.slice(offset, offset + length);
+        // 应用掩码
+        if (signature.mask) {
+            const mask = this.normalizeSignatureBytes(signature.mask);
+            for (let i = 0; i < length; i++) {
+                if ((bufferSlice[i] & mask[i]) !== (bytes[i] & mask[i])) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        // 字符串比较
+        if (typeof signature.bytes === 'string') {
+            const bufferStr = bufferSlice.toString('ascii');
+            if (signature.exact === false) {
+                return bufferStr.startsWith(signature.bytes);
+            }
+            return bufferStr === signature.bytes;
+        }
+        // 字节数组比较
+        return bufferSlice.equals(bytes);
+    }
+    /**
+     * 检查类型是否匹配
+     */
+    matchesType(buffer, type) {
+        const config = this.mimeRegistry.getMimeConfig(type);
+        if (!(config === null || config === void 0 ? void 0 : config.signatures)) {
+            return true; // 无签名配置，默认通过
+        }
+        const signatures = Array.isArray(config.signatures)
+            ? config.signatures
+            : [config.signatures];
+        return signatures.some((sig) => this.matchesSignature(buffer, sig));
+    }
+    /**
+     * 规范化签名字节
+     */
+    normalizeSignatureBytes(bytes) {
+        if (Buffer.isBuffer(bytes)) {
+            return bytes;
+        }
+        if (typeof bytes === 'string') {
+            return Buffer.from(bytes, 'ascii');
+        }
+        return Buffer.from(bytes);
+    }
+    /**
+     * 读取文件缓冲区
+     */
+    readFileBuffer(filePath, size) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let fileHandle;
+            try {
+                fileHandle = yield fs.open(filePath, 'r');
+                // 使用Buffer.alloc代替allocUnsafe以避免安全风险
+                const buffer = Buffer.alloc(size);
+                const { bytesRead } = yield fileHandle.read(buffer, 0, size, 0);
+                return buffer.slice(0, bytesRead);
+            }
+            finally {
+                if (fileHandle) {
+                    try {
+                        yield fileHandle.close();
+                    }
+                    catch (closeError) {
+                        this.logger.error(`Failed to close file handle: ${closeError.message}`);
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * 检查文件完整性
+     */
+    checkFileIntegrity(filePath, header) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const errors = [];
+            const stats = yield fs.stat(filePath);
+            // 检查文件是否为空
+            if (stats.size === 0) {
+                errors.push('File is empty');
+            }
+            // 检查常见损坏标记（大量null字节）
+            const nullBytes = header.filter((byte) => byte === 0x00).length;
+            if (nullBytes > header.length * 0.8) {
+                errors.push('File may be corrupted (excessive null bytes found)');
+            }
+            // 特定格式完整性检查
+            const detectedTypes = yield this.detectFileTypes(header);
+            for (const detection of detectedTypes) {
+                if (detection.type.includes('pdf')) {
+                    // 检查 PDF 结尾标记
+                    const tail = yield this.readFileTail(filePath, 1024);
+                    if (!tail.includes(Buffer.from('%%EOF'))) {
+                        errors.push('PDF file missing EOF marker');
+                    }
+                }
+            }
+            return {
+                valid: errors.length === 0,
+                errors,
+            };
+        });
+    }
+    /**
+     * 读取文件尾部
+     */
+    readFileTail(filePath, size) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stats = yield fs.stat(filePath);
+            const start = Math.max(0, stats.size - size);
+            const actualSize = Math.min(size, stats.size);
+            const buffer = Buffer.alloc(actualSize);
+            const fileHandle = yield fs.open(filePath, 'r');
+            try {
+                yield fileHandle.read(buffer, 0, actualSize, start);
+                return buffer;
+            }
+            finally {
+                yield fileHandle.close();
+            }
+        });
+    }
+    /**
+     * 计算签名置信度
+     */
+    calculateSignatureConfidence(signature) {
+        const bytes = typeof signature.bytes === 'string'
+            ? signature.bytes.length
+            : signature.bytes.length;
+        // 签名越长，置信度越高
+        let confidence = Math.min(bytes / 8, 1);
+        // 精确匹配提高置信度
+        if (signature.exact !== false) {
+            confidence *= 1.2;
+        }
+        // 有掩码降低置信度
+        if (signature.mask) {
+            confidence *= 0.9;
+        }
+        return Math.min(confidence, 1);
+    }
+    /**
+     * 计算总体置信度
+     */
+    calculateConfidence(buffer, detected) {
+        if (detected.length === 0) {
+            return 0;
+        }
+        // 取最高置信度
+        return detected[0].confidence;
+    }
+    /**
+     * 获取验证错误信息
+     */
+    getValidationError(detected, expected) {
+        if (detected.length === 0) {
+            return ['Unable to detect file type'];
+        }
+        const detectedTypes = detected.map((d) => d.type).join(', ');
+        return [
+            `File signature mismatch. Expected: ${expected.join(', ')}, Detected: ${detectedTypes}`,
+        ];
+    }
+    /**
+     * 初始化默认签名
+     */
+    initializeDefaultSignatures() {
+        // 图片格式
+        this.defaultSignatures.set('image/jpeg', [
+            { bytes: [0xff, 0xd8, 0xff], offset: 0 },
+        ]);
+        this.defaultSignatures.set('image/png', [
+            { bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], offset: 0 },
+        ]);
+        this.defaultSignatures.set('image/gif', [
+            { bytes: 'GIF87a', offset: 0 },
+            { bytes: 'GIF89a', offset: 0 },
+        ]);
+        this.defaultSignatures.set('image/webp', [{ bytes: 'RIFF', offset: 0 }]);
+        this.defaultSignatures.set('image/bmp', [
+            { bytes: [0x42, 0x4d], offset: 0 },
+        ]);
+        // PDF
+        this.defaultSignatures.set('application/pdf', [
+            { bytes: '%PDF-', exact: false, offset: 0 },
+        ]);
+        // ZIP 容器（DOCX, XLSX 等）
+        this.defaultSignatures.set('application/zip', [
+            { bytes: [0x50, 0x4b, 0x03, 0x04], offset: 0 },
+            { bytes: [0x50, 0x4b, 0x05, 0x06], offset: 0 },
+            { bytes: [0x50, 0x4b, 0x07, 0x08], offset: 0 },
+        ]);
+        // Office 文档 (旧格式)
+        this.defaultSignatures.set('application/msword', [
+            { bytes: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1], offset: 0 },
+        ]);
+        // 可执行文件 (用于检测)
+        this.defaultSignatures.set('application/x-executable', [
+            { bytes: [0x4d, 0x5a], offset: 0 }, // PE (Windows)
+            { bytes: [0x7f, 0x45, 0x4c, 0x46], offset: 0 }, // ELF (Linux)
+            { bytes: [0xfe, 0xed, 0xfa, 0xce], offset: 0 }, // Mach-O (macOS)
+            { bytes: [0xfe, 0xed, 0xfa, 0xcf], offset: 0 }, // Mach-O 64-bit
+        ]);
+        // 压缩格式
+        this.defaultSignatures.set('application/x-rar', [
+            { bytes: 'Rar!', offset: 0 },
+        ]);
+        this.defaultSignatures.set('application/x-7z-compressed', [
+            { bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c], offset: 0 },
+        ]);
+        this.defaultSignatures.set('application/gzip', [
+            { bytes: [0x1f, 0x8b], offset: 0 },
+        ]);
+        this.logger.log(`Initialized ${this.defaultSignatures.size} default file signatures`);
+    }
+};
+exports.FileSignatureValidator = FileSignatureValidator;
+exports.FileSignatureValidator = FileSignatureValidator = FileSignatureValidator_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)('CUSTOM_FILE_TYPES')),
+    __metadata("design:paramtypes", [mime_registry_service_1.MimeRegistryService, Object])
+], FileSignatureValidator);

package/dist/file-upload/services/file.service.d.ts

@@ -0,0 +1,193 @@
+import { Repository } from 'typeorm';
+import { FileEntity } from '../entities/file.entity';
+import { FileMetadataEntity } from '../entities/file-metadata.entity';
+import { CreateFileDto } from '../dto/create-file.dto';
+import { UpdateFileDto } from '../dto/update-file.dto';
+import { FindFilesDto } from '../dto/find-files.dto';
+import { PaginationDto } from '../dto/pagination.dto';
+import { IStorageProvider } from '../interfaces/storage-provider.interface';
+import { FileBuffer } from '../interfaces/file-buffer.interface';
+import { Readable } from 'stream';
+/**
+ * 存储统计信息
+ */
+export interface StorageStats {
+    totalFiles: number;
+    totalSize: number;
+    providers: Record<string, {
+        count: number;
+        size: number;
+    }>;
+}
+/**
+ * 文件查询结果
+ */
+export interface FileQueryResult {
+    files: FileEntity[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+/**
+ * 文件管理服务
+ */
+export declare class FileService {
+    private readonly fileRepository;
+    private readonly metadataRepository;
+    private readonly storageProvider?;
+    private readonly localStorageProvider?;
+    private readonly s3StorageProvider?;
+    private readonly logger;
+    private readonly ALLOWED_ORDER_FIELDS;
+    private readonly ALLOWED_ORDER_DIRECTIONS;
+    constructor(fileRepository: Repository<FileEntity>, metadataRepository: Repository<FileMetadataEntity>, storageProvider?: IStorageProvider, localStorageProvider?: IStorageProvider, s3StorageProvider?: IStorageProvider);
+    /**
+     * 创建文件记录
+     */
+    create(createFileDto: CreateFileDto): Promise<FileEntity>;
+    /**
+     * 根据ID查找文件
+     */
+    findById(id: string, includeDeleted?: boolean): Promise<FileEntity | null>;
+    /**
+     * 根据uploadId查找文件
+     */
+    findByUploadId(uploadId: string): Promise<FileEntity[]>;
+    /**
+     * 查找文件列表
+     */
+    findFiles(query: FindFilesDto, pagination: PaginationDto): Promise<FileQueryResult>;
+    /**
+     * 更新文件记录
+     */
+    update(id: string, updateFileDto: UpdateFileDto): Promise<FileEntity>;
+    /**
+     * 软删除文件
+     * @param id 文件ID
+     * @param deletePhysicalFile 是否同时删除物理文件，默认 false
+     */
+    softDelete(id: string, deletePhysicalFile?: boolean): Promise<void>;
+    /**
+     * 硬删除文件
+     * @param id 文件ID
+     * @param deletePhysicalFile 是否同时删除物理文件，默认 true
+     */
+    hardDelete(id: string, deletePhysicalFile?: boolean): Promise<void>;
+    /**
+     * 添加元数据
+     */
+    addMetadata(fileId: string, key: string, value: any, isPublic?: boolean): Promise<FileMetadataEntity>;
+    /**
+     * 获取元数据
+     */
+    getMetadata(fileId: string, keys?: string[]): Promise<Map<string, any>>;
+    /**
+     * 获取存储统计
+     */
+    getStorageStats(userId?: string): Promise<StorageStats>;
+    /**
+     * 更新处理状态
+     * 处理状态信息保存到 file_metadata 表
+     */
+    updateProcessingStatus(fileId: string, processor: string, status: 'pending' | 'completed' | 'failed', result?: any, error?: string): Promise<void>;
+    /**
+     * 清理临时文件（定时任务）
+     */
+    cleanupTempFiles(olderThanHours?: number): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * 获取文件内容（二进制）
+     * 适用于服务间调用，获取完整文件内容
+     *
+     * @param fileId 文件ID
+     * @returns 文件缓冲区对象
+     * @throws NotFoundException 文件不存在
+     * @throws BadRequestException 文件未完成上传
+     */
+    getFileContent(fileId: string): Promise<FileBuffer>;
+    /**
+     * 获取文件流（用于大文件）
+     * 适用于流式处理，避免一次性加载到内存
+     * 注意：仅支持本地存储，对象存储请使用 getSignedUrl
+     *
+     * @param fileId 文件ID
+     * @returns 可读流
+     * @throws NotFoundException 文件不存在或物理文件缺失
+     * @throws BadRequestException 文件未完成或存储类型不支持
+     */
+    getFileStream(fileId: string): Promise<Readable>;
+    /**
+     * 获取预签名 URL（对象存储）
+     * 适用于客户端直接下载，或临时授权访问
+     *
+     * @param fileId 文件ID
+     * @param expiresIn 过期时间（秒），默认 3600 秒（1小时）
+     * @returns 预签名 URL
+     * @throws NotFoundException 文件不存在
+     */
+    getSignedUrl(fileId: string, expiresIn?: number): Promise<string>;
+    /**
+     * 批量获取文件内容
+     * 适用于需要同时处理多个文件的场景
+     * 失败的文件会被跳过，不会中断整个流程
+     *
+     * @param fileIds 文件ID列表
+     * @returns Map<文件ID, 文件内容>
+     */
+    getFilesContent(fileIds: string[]): Promise<Map<string, FileBuffer>>;
+    /**
+     * 获取文件访问 URL
+     * 根据存储类型返回不同的 URL
+     *
+     * @param fileId 文件ID
+     * @param baseUrl 基础 URL（可选，用于本地存储）
+     * @returns 文件访问 URL
+     */
+    getFileUrl(fileId: string, baseUrl?: string): Promise<string>;
+    /**
+     * 批量删除文件
+     * @param fileIds 文件ID列表
+     * @param deletePhysicalFile 是否同时删除物理文件，默认 true
+     * @returns 删除结果统计
+     */
+    batchDelete(fileIds: string[], deletePhysicalFile?: boolean): Promise<{
+        success: string[];
+        failed: Array<{
+            id: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * 复制文件（创建新记录）
+     * @param sourceFileId 源文件ID
+     * @param userId 新文件的用户ID（可选）
+     * @returns 新的文件实体
+     */
+    copyFile(sourceFileId: string, userId?: string): Promise<FileEntity>;
+    /**
+     * 移动文件到新路径
+     * @param fileId 文件ID
+     * @param newPath 新路径
+     * @returns 更新后的文件实体
+     */
+    moveFile(fileId: string, newPath: string): Promise<FileEntity>;
+    /**
+     * 删除物理文件
+     * @private
+     */
+    private deletePhysicalFile;
+    /**
+     * 根据存储类型获取存储提供者
+     *
+     * @param storageType 存储类型
+     * @returns 存储提供者实例
+     * @throws Error 存储提供者未配置或不支持
+     */
+    private getStorageProvider;
+    /**
+     * 转义 LIKE 操作符中的特殊字符
+     */
+    private escapeLikeString;
+}