@hed-hog/core 0.0.398 → 0.0.400

package/dist/file/file.service.js

@@ -18,11 +18,25 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
     function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
     function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
 };
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
 var _a;
 var FileService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileService = void 0;
 const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
 const client_lambda_1 = require("@aws-sdk/client-lambda");
 const client_sts_1 = require("@aws-sdk/client-sts");
 const api_locale_1 = require("@hed-hog/api-locale");
@@ -30,6 +44,7 @@ const api_pagination_1 = require("@hed-hog/api-pagination");
 const api_prisma_1 = require("@hed-hog/api-prisma");
 const common_1 = require("@nestjs/common");
 const jwt_1 = require("@nestjs/jwt");
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -37,6 +52,8 @@ const promises_1 = require("stream/promises");
 const uuid_1 = require("uuid");
 const integration_profile_utils_1 = require("../integration-profile/integration-profile.utils");
 const setting_service_1 = require("../setting/setting.service");
+const filename_encoding_util_1 = require("./filename-encoding.util");
+const mimetype_sniff_util_1 = require("./mimetype-sniff.util");
 const image_optimization_service_1 = require("./image-optimization.service");
 const abstract_provider_1 = require("./provider/abstract.provider");
 const provider_factory_1 = require("./provider/provider.factory");
@@ -56,18 +73,13 @@ let FileService = FileService_1 = class FileService {
         }
         return `${file.location}/${file.path}`;
     }
-    hasMojibake(value) {
-        return /Ã.|Â.|â[\u0080-\u00BF]/.test(value);
-    }
+    /**
+     * Nome que chegou com o encoding trocado (busboy entrega `originalname` em
+     * latin1, e a base ainda recebe nome importado com o mesmo defeito). A lógica
+     * mora no util porque a migration de backfill a reproduz em plpgsql.
+     */
     normalizeUploadedFilename(filename) {
-        if (!filename) {
-            return filename;
-        }
-        if (!this.hasMojibake(filename)) {
-            return filename;
-        }
-        const decoded = Buffer.from(filename, 'latin1').toString('utf8');
-        return this.hasMojibake(decoded) ? filename : decoded;
+        return filename ? (0, filename_encoding_util_1.fixMojibake)(filename) : filename;
     }
     constructor(prismaService, paginationService, settingService, jwtService, imageOptimizationService) {
         this.prismaService = prismaService;
@@ -79,6 +91,8 @@ let FileService = FileService_1 = class FileService {
         this.mimetypes = {};
         this.cachedProvider = null;
         this.providerResolution = null;
+        /** Cache curto de papéis, no mesmo espírito do McpPermissionService. */
+        this.fileAdminCache = new Map();
     }
     async onModuleInit() {
         try {
@@ -397,7 +411,7 @@ let FileService = FileService_1 = class FileService {
     // repassa este argumento, então não há como acioná-lo por HTTP.
     // `isPrivate` tira o arquivo das rotas que servem por id sem autenticação.
     options) {
-        var _a;
+        var _a, _b;
         if (!fileBuffer) {
             throw new common_1.BadRequestException(`No file provided`);
         }
@@ -426,12 +440,13 @@ let FileService = FileService_1 = class FileService {
                 mimetype_id: await this.getMimeType(optimized.mimetype),
                 size: optimized.buffer.length,
                 is_private: (_a = options === null || options === void 0 ? void 0 : options.isPrivate) !== null && _a !== void 0 ? _a : false,
+                created_by_user_id: (_b = options === null || options === void 0 ? void 0 : options.createdByUserId) !== null && _b !== void 0 ? _b : null,
             },
         });
         return file;
     }
     async uploadFromPath(destination, filePath, metadata) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         if (!filePath) {
             throw new common_1.BadRequestException(`No file path provided`);
         }
@@ -446,7 +461,14 @@ let FileService = FileService_1 = class FileService {
         const originalname = this.normalizeUploadedFilename((_c = (_b = metadata === null || metadata === void 0 ? void 0 : metadata.originalname) !== null && _b !== void 0 ? _b : metadata === null || metadata === void 0 ? void 0 : metadata.filename) !== null && _c !== void 0 ? _c : (0, path_1.basename)(filePath));
         // Recupera o tipo real quando o caller não informou o mimetype (default antigo era
         // application/octet-stream, que fazia imagens caírem fora da otimização e do serve).
-        const mimetype = await this.resolveEffectiveMimetype(metadata === null || metadata === void 0 ? void 0 : metadata.mimetype, originalname);
+        // Diferente de `upload`, aqui só existe um caminho no disco — e ler o arquivo inteiro
+        // é justamente o que o branch de streaming abaixo evita para SCORM/vídeo de vários GB.
+        // Por isso o sniffing recebe só o cabeçalho, e apenas quando o caller não declarou um
+        // tipo concreto: sem isso, uma imagem enviada como application/octet-stream sem
+        // extensão no nome escapava da otimização e era gravada byte a byte.
+        const declaredMimetype = metadata === null || metadata === void 0 ? void 0 : metadata.mimetype;
+        const isGenericMimetype = !declaredMimetype || declaredMimetype === 'application/octet-stream';
+        const mimetype = await this.resolveEffectiveMimetype(declaredMimetype, originalname, isGenericMimetype ? await this.readFileHeader(filePath) : undefined);
         if (!(metadata === null || metadata === void 0 ? void 0 : metadata.skipMimeValidation) && !(await this.acceptMimetypes(mimetype))) {
             throw new common_1.BadRequestException(`Invalid file type: ${mimetype}`);
         }
@@ -473,19 +495,20 @@ let FileService = FileService_1 = class FileService {
                     mimetype_id: await this.getMimeType(mimetype),
                     size,
                     is_private: (_d = metadata === null || metadata === void 0 ? void 0 : metadata.isPrivate) !== null && _d !== void 0 ? _d : false,
+                    created_by_user_id: (_e = metadata === null || metadata === void 0 ? void 0 : metadata.createdByUserId) !== null && _e !== void 0 ? _e : null,
                 },
             });
         }
         // Read buffer to allow image optimization regardless of provider support
         const rawBuffer = await fs_1.promises.readFile(filePath);
         const optimized = await this.imageOptimizationService.optimizeBuffer(rawBuffer, mimetype, originalname, {
-            maxWidth: (_e = metadata === null || metadata === void 0 ? void 0 : metadata.resize) === null || _e === void 0 ? void 0 : _e.maxWidth,
-            maxHeight: (_f = metadata === null || metadata === void 0 ? void 0 : metadata.resize) === null || _f === void 0 ? void 0 : _f.maxHeight,
+            maxWidth: (_f = metadata === null || metadata === void 0 ? void 0 : metadata.resize) === null || _f === void 0 ? void 0 : _f.maxWidth,
+            maxHeight: (_g = metadata === null || metadata === void 0 ? void 0 : metadata.resize) === null || _g === void 0 ? void 0 : _g.maxHeight,
         });
         const url = await provider.upload(destination, {
             fieldname: 'file',
             originalname: optimized.originalname,
-            encoding: (_g = metadata === null || metadata === void 0 ? void 0 : metadata.encoding) !== null && _g !== void 0 ? _g : '7bit',
+            encoding: (_h = metadata === null || metadata === void 0 ? void 0 : metadata.encoding) !== null && _h !== void 0 ? _h : '7bit',
             mimetype: optimized.mimetype,
             size: optimized.buffer.length,
             destination: '',
@@ -501,19 +524,68 @@ let FileService = FileService_1 = class FileService {
                 location: destination,
                 mimetype_id: await this.getMimeType(optimized.mimetype),
                 size: optimized.buffer.length,
-                is_private: (_h = metadata === null || metadata === void 0 ? void 0 : metadata.isPrivate) !== null && _h !== void 0 ? _h : false,
+                is_private: (_j = metadata === null || metadata === void 0 ? void 0 : metadata.isPrivate) !== null && _j !== void 0 ? _j : false,
+                created_by_user_id: (_k = metadata === null || metadata === void 0 ? void 0 : metadata.createdByUserId) !== null && _k !== void 0 ? _k : null,
             },
         });
         return file;
     }
+    /**
+     * Lista as imagens armazenadas que valem uma passada por `reoptimizeFile`, para a
+     * operação em massa de reprocessamento do acervo.
+     *
+     * Devolve junto o total e a soma de bytes do filtro inteiro (não só da página), que é
+     * o que permite mostrar uma prévia antes de enfileirar dezenas de milhares de jobs.
+     * O core não conhece a fila — quem enfileira é a library `queue`, que depende deste
+     * pacote e não o contrário.
+     */
+    async findOptimizableImages(params) {
+        var _a, _b, _c;
+        const minSize = Math.max(0, Math.trunc(Number(params === null || params === void 0 ? void 0 : params.minSize) || 0));
+        const locations = ((_a = params === null || params === void 0 ? void 0 : params.locations) !== null && _a !== void 0 ? _a : [])
+            .map((location) => String(location).trim())
+            .filter(Boolean);
+        const where = {
+            size: { gte: minSize },
+            file_mimetype: {
+                name: {
+                    startsWith: 'image/',
+                    notIn: FileService_1.NON_OPTIMIZABLE_IMAGE_MIMETYPES,
+                },
+            },
+        };
+        if (locations.length) {
+            where.location = { in: locations };
+        }
+        const [aggregate, rows] = await Promise.all([
+            this.prismaService.file.aggregate({
+                where,
+                _count: { _all: true },
+                _sum: { size: true },
+            }),
+            this.prismaService.file.findMany({
+                where,
+                select: { id: true },
+                // Ordem estável para que o enfileiramento paginado não pule nem repita linhas.
+                orderBy: { id: 'asc' },
+                skip: Math.max(0, Math.trunc(Number(params === null || params === void 0 ? void 0 : params.offset) || 0)),
+                take: Math.min(5000, Math.max(1, Math.trunc(Number(params === null || params === void 0 ? void 0 : params.limit) || 1000))),
+            }),
+        ]);
+        return {
+            ids: rows.map((row) => row.id),
+            total: (_b = aggregate._count._all) !== null && _b !== void 0 ? _b : 0,
+            totalBytes: Number((_c = aggregate._sum.size) !== null && _c !== void 0 ? _c : 0),
+        };
+    }
     /**
      * Re-applies the current image-optimization settings to an already-stored file,
      * rewriting it in place: the `file` record keeps the same id, so every row that
      * references it (course_image, course_lesson_video_frame, ...) stays valid without
-     * any FK juggling. Only replaces the stored object when the optimized result is
-     * strictly smaller or the mimetype changed (e.g. PNG → WebP) — this keeps the
-     * operation idempotent and avoids repeated lossy recompression. Non-image files are
-     * left untouched.
+     * any FK juggling. Only replaces the stored object when the mimetype changed
+     * (e.g. PNG → WebP) or the result is smaller by a margin that justifies the rewrite —
+     * that margin is what actually makes the operation idempotent and avoids repeated
+     * lossy recompression. Non-image files are left untouched.
      */
     async reoptimizeFile(fileId) {
         var _a;
@@ -525,8 +597,13 @@ let FileService = FileService_1 = class FileService {
         }
         const optimized = await this.imageOptimizationService.optimizeBuffer(buffer, currentMimetype, file.filename);
         const mimetypeChanged = optimized.mimetype !== currentMimetype;
-        const smaller = optimized.buffer.length < oldSize;
-        if (!mimetypeChanged && !smaller) {
+        // Mudança de formato é o ganho principal (PNG → WebP) e vale por si; sem ela, só
+        // regrava quando a economia passa do limiar. `optimizeBuffer` já garante que o
+        // resultado nunca é maior que a entrada neste caminho (sem crop de alvo exato).
+        const worthRewriting = oldSize > 0 &&
+            (oldSize - optimized.buffer.length) / oldSize >=
+                FileService_1.REOPTIMIZE_MIN_GAIN_RATIO;
+        if (!mimetypeChanged && !worthRewriting) {
             return {
                 changed: false,
                 oldSize,
@@ -602,14 +679,181 @@ let FileService = FileService_1 = class FileService {
         }
         return files.map((file) => file.id);
     }
-    async getFiles(paginationParams) {
+    /**
+     * `ownerUserId` restringe a listagem aos arquivos enviados por aquele usuário.
+     *
+     * Existe para as tools MCP: sem ele, `core.files.list` é um índice de tudo o que
+     * qualquer empresa já subiu, incluindo o que está gravado como `is_private`. O
+     * controller REST continua chamando sem o parâmetro, porque ali a rota já é `admin`
+     * e a tela de arquivos é justamente a visão global.
+     */
+    /**
+     * Grava um stream em disco medindo, hasheando e guardando o cabeçalho de uma vez só.
+     *
+     * O upload assinado recebe o binário cru no corpo do PUT, e nada garante que venha com
+     * `Content-Length` — sem o contador abaixo, um corpo aberto encheria o disco do pod. O
+     * corte é feito em pleno voo, antes de o excedente chegar ao arquivo.
+     *
+     * Passa o cabeçalho adiante porque conferir o tipo real é obrigatório nesse caminho, e
+     * reler o arquivo depois seria uma segunda passada por nada.
+     */
+    async writeStreamToPath(source, targetPath, maxBytes) {
+        const hash = (0, crypto_1.createHash)('sha256');
+        const headerChunks = [];
+        let headerLength = 0;
+        let bytes = 0;
+        const target = (0, fs_1.createWriteStream)(targetPath);
+        await (0, promises_1.pipeline)(source, function (chunks) {
+            return __asyncGenerator(this, arguments, function* () {
+                var _a, e_1, _b, _c;
+                try {
+                    for (var _d = true, chunks_1 = __asyncValues(chunks), chunks_1_1; chunks_1_1 = yield __await(chunks_1.next()), _a = chunks_1_1.done, !_a; _d = true) {
+                        _c = chunks_1_1.value;
+                        _d = false;
+                        const chunk = _c;
+                        const buffer = Buffer.from(chunk);
+                        bytes += buffer.length;
+                        if (bytes > maxBytes) {
+                            throw new common_1.BadRequestException(`Upload exceeds the declared size of ${maxBytes} bytes`);
+                        }
+                        hash.update(buffer);
+                        if (headerLength < mimetype_sniff_util_1.MIMETYPE_SNIFF_BYTES) {
+                            const slice = buffer.subarray(0, mimetype_sniff_util_1.MIMETYPE_SNIFF_BYTES - headerLength);
+                            headerChunks.push(slice);
+                            headerLength += slice.length;
+                        }
+                        yield yield __await(buffer);
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = chunks_1.return)) yield __await(_b.call(chunks_1));
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+            });
+        }, target);
+        return {
+            bytes,
+            sha256: hash.digest('hex'),
+            header: Buffer.concat(headerChunks),
+        };
+    }
+    /**
+     * Conteúdo de um arquivo já armazenado, em memória.
+     *
+     * Existe para as tools que consomem os bytes sem persistir nada (importar extrato,
+     * extrair dados de uma nota com IA): elas recebem um `fileId` e precisam do arquivo,
+     * não de um stream. O teto evita que um `fileId` apontando para um SCORM de vários GB
+     * derrube o pod — quem serve arquivo grande usa `openReadStream` e não passa por aqui.
+     */
+    async bufferById(fileId, maxBytes) {
+        var _a, e_2, _b, _c;
+        var _d, _e;
+        const { stream } = await this.openReadStreamById(fileId);
+        const chunks = [];
+        let total = 0;
+        try {
+            for (var _f = true, _g = __asyncValues(stream), _h; _h = await _g.next(), _a = _h.done, !_a; _f = true) {
+                _c = _h.value;
+                _f = false;
+                const chunk = _c;
+                total += chunk.length;
+                if (total > maxBytes) {
+                    (_e = (_d = stream).destroy) === null || _e === void 0 ? void 0 : _e.call(_d);
+                    throw new common_1.BadRequestException(`File ${fileId} is larger than the ${maxBytes} bytes this operation can load`);
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (!_f && !_a && (_b = _g.return)) await _b.call(_g);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        return Buffer.concat(chunks);
+    }
+    /**
+     * Nome do mimetype de um arquivo.
+     *
+     * `get()` e `upload()` devolvem a linha crua, sem a relação, e cada chamador que
+     * precisava do tipo vinha refazendo o `include` por conta. Como o cache de
+     * `getMimeType` é id-por-nome, este é o inverso dele e sai do mesmo mapa quando já
+     * tiver sido consultado.
+     */
+    async mimetypeNameById(mimetypeId) {
+        const cached = Object.entries(this.mimetypes).find(([, id]) => id === mimetypeId);
+        if (cached) {
+            return cached[0];
+        }
+        const row = await this.prismaService.file_mimetype.findUnique({
+            where: { id: mimetypeId },
+            select: { name: true },
+        });
+        if (row === null || row === void 0 ? void 0 : row.name) {
+            this.mimetypes[row.name] = mimetypeId;
+            return row.name;
+        }
+        return 'application/octet-stream';
+    }
+    async getFiles(paginationParams, ownerUserId) {
         const fields = ['filename', 'path'];
         const OR = this.prismaService.createInsensitiveSearch(fields, paginationParams);
         return this.paginationService.paginate(this.prismaService.file, paginationParams, {
+            where: Object.assign({ OR }, (ownerUserId ? { created_by_user_id: ownerUserId } : {})),
+        });
+    }
+    async isFileAdmin(userId) {
+        const cached = this.fileAdminCache.get(userId);
+        if (cached && Date.now() - cached.at < FileService_1.FILE_ADMIN_CACHE_TTL_MS) {
+            return cached.value;
+        }
+        const found = await this.prismaService.role_user.findFirst({
             where: {
-                OR,
+                user_id: userId,
+                role: { slug: { in: FileService_1.FILE_ADMIN_ROLES } },
             },
+            select: { role_id: true },
         });
+        const value = Boolean(found);
+        this.fileAdminCache.set(userId, { value, at: Date.now() });
+        return value;
+    }
+    /**
+     * Porteiro do `fileId` vindo de fora: só o dono usa um arquivo, e quem administra o
+     * acervo usa qualquer um.
+     *
+     * Sem isto, apontar um `fileId` numa tool seria enumerar — id de arquivo é sequencial,
+     * exatamente o motivo pelo qual `is_private` existe. Arquivo anterior a esta coluna
+     * (ou gravado por cron/seed/webhook) fica com dono nulo e só o admin alcança: não dá
+     * para provar de quem ele é, e adivinhar a favor do chamador seria abrir a porta que
+     * este método fecha.
+     */
+    async assertFileUsable(fileId, userId) {
+        if (!Number.isInteger(fileId) || fileId <= 0) {
+            throw new common_1.BadRequestException(`Invalid file id: ${fileId}`);
+        }
+        const file = await this.prismaService.file.findUnique({
+            where: { id: fileId },
+            include: { file_mimetype: true },
+        });
+        // Mesma resposta para inexistente e para alheio seria o ideal contra enumeração, mas
+        // `get()` já responde 404 com o id, e divergir aqui só confundiria quem integra.
+        if (!file) {
+            throw new common_1.NotFoundException(`File not found: ${fileId}`);
+        }
+        if (file.created_by_user_id === userId) {
+            return file;
+        }
+        if (await this.isFileAdmin(userId)) {
+            return file;
+        }
+        throw new common_1.ForbiddenException(file.created_by_user_id === null
+            ? `File ${fileId} has no recorded owner and can only be used by an administrator`
+            : `File ${fileId} belongs to another user`);
     }
     async get(fileId) {
         const file = await this.prismaService.file.findUnique({
@@ -743,19 +987,44 @@ let FileService = FileService_1 = class FileService {
         }
         return undefined;
     }
+    /**
+     * Resolve o `file` cujo `resolveProviderPath` (location + path, ou path já combinado) bate com
+     * o `filepath` embutido no token de download — é o inverso de `resolveProviderPath`.
+     *
+     * Bug corrigido (relatado como "Token de download inválido ou expirado" no storage local):
+     * `tempURLById` assina o token com `resolveProviderPath(file)` (ex.:
+     * "class-assignment-tasks/abc123.pdf", já com o prefixo de `location`), mas o upload local/S3
+     * grava só o basename em `file.path` ("abc123.pdf") e o `location` separado em outra coluna.
+     * Um `findFirst({ where: { path: filepath } })` direto nunca batia para esses arquivos — sempre
+     * caía no `catch` abaixo e mostrava a mensagem genérica de token inválido, mesmo com o token
+     * (e o arquivo) perfeitamente válidos. S3 mascarava isso porque `S3Provider.tempURL` devolve uma
+     * URL assinada direto do bucket, sem passar por este método.
+     */
+    async findFileByResolvedPath(filepath) {
+        const bySameValue = await this.prismaService.file.findFirst({
+            where: { path: filepath },
+            include: { file_mimetype: true },
+        });
+        if (bySameValue)
+            return bySameValue;
+        const slashIndex = filepath.lastIndexOf('/');
+        if (slashIndex === -1)
+            return null;
+        return this.prismaService.file.findFirst({
+            where: {
+                location: filepath.slice(0, slashIndex),
+                path: filepath.slice(slashIndex + 1),
+            },
+            include: { file_mimetype: true },
+        });
+    }
     async download(locale, token) {
         var _a;
         try {
             const { filepath } = this.jwtService.verify(token, {
                 secret: process.env.JWT_SECRET,
             });
-            // Buscar o arquivo no banco para pegar nome original e mimetype
-            const file = await this.prismaService.file.findFirst({
-                where: { path: filepath },
-                include: {
-                    file_mimetype: true,
-                },
-            });
+            const file = await this.findFileByResolvedPath(filepath);
             if (!file) {
                 throw new common_1.NotFoundException((0, api_locale_1.getLocaleText)('file.download.not_found', locale, `Not found: ${filepath}`));
             }
@@ -879,6 +1148,28 @@ let FileService = FileService_1 = class FileService {
         };
         return (_a = map[ext]) !== null && _a !== void 0 ? _a : null;
     }
+    /**
+     * Lê só o começo do arquivo, o bastante para o sharp reconhecer o formato pelo
+     * cabeçalho. Existe para o sniffing de `uploadFromPath`, que não pode chamar
+     * `fs.readFile`: o mesmo caminho recebe pacotes SCORM e vídeos de vários GB, e
+     * carregá-los inteiros estoura o limite de Buffer. Devolve `undefined` em qualquer
+     * falha de leitura — quem chama já trata a ausência do buffer.
+     */
+    async readFileHeader(filePath, bytes = 64 * 1024) {
+        let handle;
+        try {
+            handle = await fs_1.promises.open(filePath, 'r');
+            const buffer = Buffer.alloc(bytes);
+            const { bytesRead } = await handle.read(buffer, 0, bytes, 0);
+            return bytesRead > 0 ? buffer.subarray(0, bytesRead) : undefined;
+        }
+        catch (_a) {
+            return undefined;
+        }
+        finally {
+            await (handle === null || handle === void 0 ? void 0 : handle.close().catch(() => undefined));
+        }
+    }
     /**
      * Resolves the MIME type to persist for an upload. When the incoming mimetype is
      * generic (application/octet-stream or empty), recovers the real image type from
@@ -1000,7 +1291,7 @@ let FileService = FileService_1 = class FileService {
      * which the storage layer does not normally do — cannot serve stale bytes.
      */
     async renderImageVariant(provider, providerPath, contentType, id, size, variant) {
-        var _a, e_1, _b, _c;
+        var _a, e_3, _b, _c;
         var _d;
         const format = (_d = variant.format) !== null && _d !== void 0 ? _d : (contentType === 'image/png'
             ? 'png'
@@ -1028,12 +1319,12 @@ let FileService = FileService_1 = class FileService {
                     chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
                 }
             }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
             finally {
                 try {
                     if (!_f && !_a && (_b = stream_1.return)) await _b.call(stream_1);
                 }
-                finally { if (e_1) throw e_1.error; }
+                finally { if (e_3) throw e_3.error; }
             }
             const original = Buffer.concat(chunks);
             const rendered = await this.imageOptimizationService.resizeBuffer(original, contentType, { width: variant.width, format: variant.format, quality: variant.quality });
@@ -1096,6 +1387,14 @@ let FileService = FileService_1 = class FileService {
         }
         return url;
     }
+    /** Par de `tempURLById`, pela mesma razão: `path` cru resolve para NoSuchKey no S3. */
+    async tempOpenURLById(fileId, expires = 3600) {
+        const url = await this.tempURLById(fileId, expires);
+        if (typeof url === 'string') {
+            return url.replace('/file/download/', '/file/open/');
+        }
+        return url;
+    }
     async getTemporaryCredentials(params) {
         const stsClient = new client_sts_1.STSClient({
             region: params.region,
@@ -1131,6 +1430,30 @@ let FileService = FileService_1 = class FileService {
             ETag: result.ETag,
         };
     }
+    /**
+     * URL assinada de um objeto em bucket avulso.
+     *
+     * O `getFileUrl` do provider resolve arquivos do acervo, que vivem no destino
+     * ativo do core. Este metodo serve para os buckets que outras libraries
+     * configuram por conta propria — o Studio grava no perfil de armazenamento
+     * dele, que pode nao ser o mesmo — e por isso recebe as credenciais e o bucket
+     * de fora, como o `headS3Object` ao lado.
+     */
+    async signS3Object(params) {
+        var _a;
+        const s3 = new client_s3_1.S3Client({
+            region: params.region,
+            credentials: Object.assign({ accessKeyId: params.accessKeyId, secretAccessKey: params.secretAccessKey }, (params.sessionToken ? { sessionToken: params.sessionToken } : {})),
+        });
+        const command = new client_s3_1.GetObjectCommand(Object.assign({ Bucket: params.bucket, Key: params.key }, (params.downloadFileName
+            ? {
+                ResponseContentDisposition: `attachment; filename="${params.downloadFileName.replace(/"/g, '')}"`,
+            }
+            : {})));
+        return (0, s3_request_presigner_1.getSignedUrl)(s3, command, {
+            expiresIn: (_a = params.expiresInSeconds) !== null && _a !== void 0 ? _a : 900,
+        });
+    }
     async headS3Bucket(params) {
         const s3 = new client_s3_1.S3Client({
             region: params.region,
@@ -1382,6 +1705,32 @@ let FileService = FileService_1 = class FileService {
     }
 };
 exports.FileService = FileService;
+/**
+ * Mimetypes de imagem que `optimizeBuffer` devolve intactos por decisão de projeto
+ * (vetor não vira bitmap, GIF animado não vira quadro único). Enfileirá-los para
+ * reotimização seria custo de download e reprocessamento com resultado garantidamente
+ * nulo, então ficam fora da varredura.
+ */
+FileService.NON_OPTIMIZABLE_IMAGE_MIMETYPES = [
+    'image/svg+xml',
+    'image/gif',
+];
+/**
+ * Ganho mínimo para valer a regravação de um arquivo que já está no formato final.
+ *
+ * Recomprimir WebP sobre WebP sempre devolve alguns bytes a menos, então um limiar de
+ * "estritamente menor" nunca converge: cada passada da varredura trocaria o arquivo
+ * por um ganho irrisório e mais uma geração de perda de qualidade. Medido aqui, três
+ * passadas seguidas rendiam 10926 → 10664 → 10662 bytes — a última custou uma
+ * recompressão inteira para economizar 2 bytes.
+ */
+FileService.REOPTIMIZE_MIN_GAIN_RATIO = 0.1;
+/**
+ * Papéis que enxergam qualquer arquivo. Os mesmos que já governam as rotas de arquivo
+ * em `route.yaml` — quem administra o acervo pela tela também o administra pelo MCP.
+ */
+FileService.FILE_ADMIN_ROLES = ['admin', 'admin-access'];
+FileService.FILE_ADMIN_CACHE_TTL_MS = 30000;
 exports.FileService = FileService = FileService_1 = __decorate([
     (0, common_1.Injectable)(),
     __param(0, (0, common_1.Inject)((0, common_1.forwardRef)(() => api_prisma_1.PrismaService))),