@hed-hog/core 0.0.387 → 0.0.393

package/src/file/image-optimization.service.spec.ts

@@ -7,6 +7,7 @@ jest.mock('sharp', () => {
     webp: jest.fn(),
     jpeg: jest.fn(),
     png: jest.fn(),
+    avif: jest.fn(),
     toBuffer: jest.fn(),
   };
   const fn: any = jest.fn(() => instance);
@@ -46,6 +47,7 @@ describe('ImageOptimizationService', () => {
     inst.webp.mockReset().mockReturnValue(inst);
     inst.jpeg.mockReset().mockReturnValue(inst);
     inst.png.mockReset().mockReturnValue(inst);
+    inst.avif.mockReset().mockReturnValue(inst);
     inst.toBuffer.mockReset();
   });
 
@@ -280,4 +282,94 @@ describe('ImageOptimizationService', () => {
       expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 80 });
     });
   });
+
+  describe('resizeBuffer', () => {
+    it('redimensiona sem ampliar e converte para o formato pedido', async () => {
+      const { service } = makeService();
+      mockSharp.__instance.webp.mockReturnValue(mockSharp.__instance);
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
+
+      const result = await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+        width: 640,
+        format: 'webp',
+        quality: 82,
+      });
+
+      expect(mockSharp.__instance.resize).toHaveBeenCalledWith({
+        width: 640,
+        fit: 'inside',
+        withoutEnlargement: true,
+      });
+      expect(mockSharp.__instance.webp).toHaveBeenCalledWith({ quality: 82 });
+      expect(result).toEqual({
+        buffer: Buffer.from('out'),
+        mimetype: 'image/webp',
+        originalname: 'image.webp',
+      });
+    });
+
+    it('mantém o formato de origem quando nenhum é pedido', async () => {
+      const { service } = makeService();
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
+
+      const result = await service.resizeBuffer(Buffer.from('img'), 'image/png', {
+        width: 320,
+      });
+
+      expect(mockSharp.__instance.png).toHaveBeenCalled();
+      expect(result?.mimetype).toBe('image/png');
+    });
+
+    it('não redimensiona SVG nem GIF animado', async () => {
+      const { service } = makeService();
+
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/svg+xml', { width: 640 }),
+      ).toBeNull();
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/gif', { width: 640 }),
+      ).toBeNull();
+      expect(mockSharp).not.toHaveBeenCalled();
+    });
+
+    it('retorna null para largura inválida', async () => {
+      const { service } = makeService();
+
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/jpeg', { width: 0 }),
+      ).toBeNull();
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/jpeg', {
+          width: -10,
+        }),
+      ).toBeNull();
+    });
+
+    it('retorna null quando o sharp lança, para o caller servir o original', async () => {
+      const { service } = makeService();
+      const warnSpy = jest
+        .spyOn((service as any).logger, 'warn')
+        .mockImplementation(() => undefined);
+      mockSharp.__instance.toBuffer.mockRejectedValue(new Error('sharp boom'));
+
+      const result = await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+        width: 640,
+      });
+
+      expect(result).toBeNull();
+      expect(warnSpy).toHaveBeenCalled();
+    });
+
+    it('faz clamp da quality fora da faixa', async () => {
+      const { service } = makeService();
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
+
+      await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+        width: 640,
+        quality: 0,
+      });
+
+      expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 80 });
+    });
+  });
 });

package/src/file/image-optimization.service.ts

@@ -15,6 +15,25 @@ export interface OptimizeOptions {
   maxHeight?: number;
 }
 
+export type ImageVariantFormat = 'webp' | 'jpeg' | 'png' | 'avif';
+
+export interface ResizeVariantOptions {
+  /** Target width in px. The height follows the aspect ratio. */
+  width: number;
+  /** Output encoding. Defaults to keeping the source format. */
+  format?: ImageVariantFormat;
+  quality?: number;
+}
+
+export interface ShareCardOptions {
+  /** Defaults to the 1200x630 expected by Open Graph consumers. */
+  width?: number;
+  height?: number;
+  /** Canvas color behind the composition (hex, e.g. `#ff760c`). */
+  background?: string | null;
+  quality?: number;
+}
+
 @Injectable()
 export class ImageOptimizationService {
   private readonly logger = new Logger(ImageOptimizationService.name);
@@ -185,4 +204,187 @@ export class ImageOptimizationService {
       return { buffer, mimetype, originalname };
     }
   }
+
+  /** Keeps the source encoding when the caller did not pick one explicitly. */
+  private defaultVariantFormat(mimetype: string): ImageVariantFormat {
+    if (mimetype === 'image/png') return 'png';
+    if (mimetype === 'image/webp') return 'webp';
+    if (mimetype === 'image/avif') return 'avif';
+    return 'jpeg';
+  }
+
+  /**
+   * Renders a resized variant of an already stored image, for serving a specific
+   * `?w=`/`?f=` URL. Unlike `optimizeBuffer`, every parameter is explicit and no
+   * setting is consulted: a given variant URL must always return the same bytes,
+   * otherwise the immutable cache headers would be a lie.
+   *
+   * Returns `null` whenever the variant cannot (or should not) be produced, so
+   * the caller falls back to streaming the original file.
+   */
+  async resizeBuffer(
+    buffer: Buffer,
+    mimetype: string,
+    options: ResizeVariantOptions,
+  ): Promise<OptimizedImage | null> {
+    const width = Math.round(Number(options.width) || 0);
+    if (width <= 0) return null;
+
+    // Vectors scale on their own, and resizing an animated GIF would flatten it
+    // to a single frame — both are better served as-is.
+    if (mimetype === 'image/svg+xml' || mimetype === 'image/gif') return null;
+
+    const quality = Math.min(100, Math.max(1, Number(options.quality) || 80));
+    const format = options.format ?? this.defaultVariantFormat(mimetype);
+
+    try {
+      const instance = sharp(buffer).resize({
+        width,
+        fit: 'inside',
+        withoutEnlargement: true,
+      });
+
+      if (format === 'png') {
+        return {
+          buffer: await instance
+            .png({ compressionLevel: this.pngCompressionLevel(quality) })
+            .toBuffer(),
+          mimetype: 'image/png',
+          originalname: 'image.png',
+        };
+      }
+
+      const encoded =
+        format === 'webp'
+          ? await instance.webp({ quality }).toBuffer()
+          : format === 'avif'
+            ? await instance.avif({ quality }).toBuffer()
+            : await instance.jpeg({ quality }).toBuffer();
+
+      return {
+        buffer: encoded,
+        mimetype: `image/${format}`,
+        originalname: `image.${format === 'jpeg' ? 'jpg' : format}`,
+      };
+    } catch (err) {
+      this.logger.warn(
+        `Image resize failed (${mimetype}, w=${width}, f=${format}): ${err instanceof Error ? err.message : String(err)}. Serving the original.`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Monta um cartão de compartilhamento (Open Graph) a partir das imagens já
+   * cadastradas: fundo desfocado e escurecido, com a arte principal centralizada.
+   *
+   * A saída é sempre JPEG, e é esse o ponto do método: as imagens do acervo são
+   * convertidas para WebP no upload (ver `image-webp-conversion-enabled`), e o
+   * robô do WhatsApp não renderiza WebP de forma confiável — apontar `og:image`
+   * para o arquivo original deixaria o preview sem imagem.
+   *
+   * Sem texto de propósito: o título vem na tag `og:title`, que as redes já
+   * desenham ao lado do cartão, e assim não é preciso embutir fonte nem tratar
+   * transbordo de título longo no bitmap.
+   */
+  async composeShareCard(
+    background: Buffer | null | undefined,
+    overlay: Buffer | null | undefined,
+    options: ShareCardOptions = {},
+  ): Promise<Buffer | null> {
+    const width = options.width ?? 1200;
+    const height = options.height ?? 630;
+    const quality = Math.min(100, Math.max(1, options.quality ?? 82));
+    const canvasColor = this.parseHexColor(options.background) ?? {
+      r: 11,
+      g: 11,
+      b: 15,
+    };
+
+    const backdropSource = background ?? overlay;
+    const foregroundSource = overlay ?? background;
+
+    if (!backdropSource && !foregroundSource) {
+      return null;
+    }
+
+    try {
+      const layers: sharp.OverlayOptions[] = [];
+
+      if (backdropSource) {
+        const backdrop = await sharp(backdropSource)
+          .resize(width, height, { fit: 'cover', position: 'centre' })
+          .blur(32)
+          .modulate({ brightness: 0.45 })
+          .toBuffer()
+          .catch(() => null);
+
+        if (backdrop) {
+          layers.push({ input: backdrop, top: 0, left: 0 });
+        }
+      }
+
+      if (foregroundSource) {
+        const foreground = await sharp(foregroundSource)
+          .resize(Math.round(width * 0.64), Math.round(height * 0.64), {
+            fit: 'inside',
+            withoutEnlargement: false,
+          })
+          .toBuffer()
+          .catch(() => null);
+
+        if (foreground) {
+          layers.push({ input: foreground, gravity: 'centre' });
+        }
+      }
+
+      if (layers.length === 0) {
+        return null;
+      }
+
+      return await sharp({
+        create: {
+          width,
+          height,
+          channels: 3,
+          background: canvasColor,
+        },
+      })
+        .composite(layers)
+        .jpeg({ quality, mozjpeg: true })
+        .toBuffer();
+    } catch (err) {
+      this.logger.warn(
+        `Share card composition failed: ${err instanceof Error ? err.message : String(err)}.`,
+      );
+      return null;
+    }
+  }
+
+  private parseHexColor(
+    raw: string | null | undefined,
+  ): { r: number; g: number; b: number } | null {
+    if (!raw) {
+      return null;
+    }
+
+    const hex = raw.trim().replace(/^#/, '');
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((char) => char + char)
+            .join('')
+        : hex;
+
+    if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+      return null;
+    }
+
+    return {
+      r: parseInt(full.slice(0, 2), 16),
+      g: parseInt(full.slice(2, 4), 16),
+      b: parseInt(full.slice(4, 6), 16),
+    };
+  }
 }

package/src/file/provider/abstract.provider.ts

@@ -24,6 +24,22 @@ interface IProvider {
   initValidation(): Promise<any>;
 }
 
+/**
+ * Copies an object that is already stored, without moving the bytes through the app.
+ *
+ * Optional on purpose: `FileService.duplicate` falls back to streaming the file through a temp
+ * file when the active provider does not implement it, so no provider is ever left broken.
+ */
+export interface ProviderServerSideCopy {
+  copy(sourcePath: string, destination: string, filename: string): Promise<string>;
+}
+
+export function supportsServerSideCopy(
+  provider: AbstractProvider,
+): provider is AbstractProvider & ProviderServerSideCopy {
+  return typeof (provider as Partial<ProviderServerSideCopy>).copy === 'function';
+}
+
 export abstract class AbstractProvider implements IProvider {
   abstract uploadFromString(
     destination: string,
@@ -44,6 +60,13 @@ export abstract class AbstractProvider implements IProvider {
   abstract tempURL(filepath: string, expires?: number): Promise<any>;
   abstract initValidation(): Promise<any>;
 
+  /**
+   * Server-side copy of an already-stored object into `destination`, returning the new stored
+   * filename (same contract as `upload*`). Implemented by providers whose SDK supports it; see
+   * `supportsServerSideCopy`.
+   */
+  copy?(sourcePath: string, destination: string, filename: string): Promise<string>;
+
   getExtension(filename: string) {
     return filename.split('.').pop();
   }

package/src/file/provider/gcs.provider.ts

@@ -96,6 +96,23 @@ export class GCSProvider extends AbstractProvider {
     if (options?.end !== undefined) rangeOpts.end = options.end;
     return file.createReadStream(Object.keys(rangeOpts).length > 0 ? rangeOpts : undefined);
   }
+  /** Server-side copy — the bytes never leave GCS. */
+  async copy(
+    sourcePath: string,
+    destination: string,
+    filename: string,
+  ): Promise<string> {
+    const storage = await this.getClient();
+    const bucket = storage.bucket(this.setting['storage-gcs-bucket']);
+    const storedFilename = this.getFilename(filename);
+
+    await bucket
+      .file(sourcePath)
+      .copy(bucket.file([destination.replace(/\/$/, ''), storedFilename].join('/')));
+
+    return storedFilename;
+  }
+
   async delete(filepath: string): Promise<any> {
     const storage = await this.getClient();
     const bucket = storage.bucket(this.setting['storage-gcs-bucket']);

package/src/file/provider/local.provider.ts

@@ -117,6 +117,27 @@ export class LocalProvider extends AbstractProvider {
     return targetFilename;
   }
 
+  async copy(
+    sourcePath: string,
+    destination: string,
+    filename: string,
+  ): Promise<string> {
+    const fullSourcePath = this.resolveFilepath(sourcePath);
+
+    if (!existsSync(fullSourcePath)) {
+      throw new BadRequestException(`File not found: ${fullSourcePath}`);
+    }
+
+    const storagePath = join(this.setting['storage-local-path'], destination);
+    if (!existsSync(storagePath)) {
+      await this.createFolderRecursive(storagePath);
+    }
+
+    const storedFilename = this.getFilename(filename);
+    await copyFile(fullSourcePath, join(storagePath, storedFilename));
+    return storedFilename;
+  }
+
   async delete(filepath: string): Promise<any> {
     const fullPath = this.resolveFilepath(filepath);
 

package/src/file/provider/s3.provider.ts

@@ -1,4 +1,5 @@
 import {
+    CopyObjectCommand,
     DeleteObjectCommand,
     GetObjectCommand,
     HeadBucketCommand,
@@ -181,6 +182,30 @@ export class S3Provider extends AbstractProvider {
     return storedFilename;
   }
 
+  /**
+   * Server-side copy — the bytes never leave S3. Capped at 5GB per object by CopyObject;
+   * FileService catches the failure and falls back to streaming through a temp file.
+   */
+  async copy(
+    sourcePath: string,
+    destination: string,
+    filename: string,
+  ): Promise<string> {
+    const s3 = await this.getClient();
+    const bucket = this.setting['storage-s3-bucket'];
+    const storedFilename = this.getFilename(filename);
+
+    await s3.send(
+      new CopyObjectCommand({
+        Bucket: bucket,
+        Key: [destination, storedFilename].join('/'),
+        CopySource: encodeURI(`${bucket}/${this.resolveS3Key(sourcePath)}`),
+      }),
+    );
+
+    return storedFilename;
+  }
+
   async delete(filepath: string): Promise<any> {
     const s3 = await this.getClient();
     const key = this.resolveS3Key(filepath);

package/src/file/provider/spaces.provider.ts

@@ -1,4 +1,5 @@
 import {
+    CopyObjectCommand,
     DeleteObjectCommand,
     GetObjectCommand,
     HeadBucketCommand,
@@ -207,6 +208,31 @@ export class SpacesProvider extends AbstractProvider {
     return storedFilename;
   }
 
+  /**
+   * Server-side copy — the bytes never leave Spaces. Capped at 5GB per object by CopyObject;
+   * FileService catches the failure and falls back to streaming through a temp file.
+   */
+  async copy(
+    sourcePath: string,
+    destination: string,
+    filename: string,
+  ): Promise<string> {
+    const s3 = await this.getClient();
+    const bucket = this.setting['storage-spaces-bucket'];
+    const storedFilename = this.getFilename(filename);
+
+    await s3.send(
+      new CopyObjectCommand({
+        Bucket: bucket,
+        Key: [destination, storedFilename].join('/'),
+        CopySource: encodeURI(`${bucket}/${this.resolveKey(sourcePath)}`),
+        ACL: 'public-read',
+      }),
+    );
+
+    return storedFilename;
+  }
+
   async delete(filepath: string): Promise<any> {
     const s3 = await this.getClient();
     const key = this.resolveKey(filepath);

package/src/impersonation/dto/redeem-impersonation.dto.ts

@@ -0,0 +1,8 @@
+import { IsString, MaxLength, MinLength } from 'class-validator';
+
+export class RedeemImpersonationDTO {
+  @IsString()
+  @MinLength(16)
+  @MaxLength(255)
+  code: string;
+}

package/src/impersonation/dto/start-impersonation.dto.ts

@@ -0,0 +1,13 @@
+import { IsIn, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class StartImpersonationDTO {
+  /** Chave do app de destino em `app-urls`. */
+  @IsIn(['admin', 'class', 'partners'])
+  app: string;
+
+  /** Justificativa livre do operador; vai para a trilha de auditoria. */
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  reason?: string;
+}

package/src/impersonation/impersonation-restrictions.ts

@@ -0,0 +1,84 @@
+/**
+ * Rotas bloqueadas enquanto uma sessao simulada esta ativa.
+ *
+ * POR QUE ISTO EXISTE
+ *
+ * Numa simulacao o JWT tem `sub` = ALVO, entao para todo o resto do sistema o
+ * request E o alvo. Isso e o desejado (o RoleGuard resolve os papeis do alvo),
+ * mas abre buracos em qualquer endpoint que transforme "quem eu sou" em algo
+ * duravel. O caso mais grave e `GET /auth/desktop-token`: ele e `@NoRole()` e
+ * chama `getAuthenticationPayload` para `@User().id`, ou seja, o operador
+ * cunharia para o alvo uma sessao completa, RENOVAVEL e de 30 dias — furando o
+ * teto de 30 minutos e saindo da trilha de auditoria.
+ *
+ * `POST /auth/logout` e igualmente perigoso pelo motivo oposto: ele le
+ * `req.cookies['rt']`, que na mesma origem e o cookie do OPERADOR, e revogaria
+ * a sessao real dele.
+ *
+ * Por isso a checagem roda ANTES dos atalhos de `@Public()` e `@NoRole()` no
+ * RoleGuard — sao justamente esses dois decorators que protegem as rotas
+ * perigosas.
+ */
+
+/** `METHOD /path` exatos, no formato que o RoleGuard monta a partir do Nest. */
+const RESTRICTED_EXACT = new Set([
+  // Emissao de credencial duravel para o alvo.
+  'GET /auth/desktop-token',
+  'POST /auth/token',
+  // Mexe no cookie `rt`, que e do operador.
+  'POST /auth/logout',
+  // Encerrar sessao alheia a partir de uma simulacao.
+  'DELETE /sessions/:sessionId/revoke',
+  'DELETE /sessions/revoke-all',
+  'DELETE /sessions/revoke-all-other',
+  // Tomada de conta.
+  'PUT /profile/change-password',
+  'PUT /profile/change-email',
+  'DELETE /profile/account',
+  'PATCH /user/:userId/reset-password',
+  // Simulacao aninhada.
+  'POST /impersonation/start',
+]);
+
+/** Familias inteiras: pareamento, OAuth e todo o material de segunda etapa. */
+const RESTRICTED_PREFIXES = [
+  '/auth/pairing',
+  '/auth/authorize',
+  '/profile/mfa',
+  '/profile/totp',
+  '/profile/webauthn',
+  '/profile/recovery-codes',
+  '/profile/email',
+];
+
+/**
+ * Precisam funcionar justamente porque a sessao e simulada — sem elas o
+ * operador nao conseguiria sair.
+ */
+const ALWAYS_ALLOWED = new Set([
+  'POST /impersonation/stop',
+  'GET /impersonation/session',
+]);
+
+export function isRestrictedDuringImpersonation(
+  httpMethod: string,
+  fullPath: string,
+): boolean {
+  const key = `${httpMethod} ${fullPath}`;
+
+  if (ALWAYS_ALLOWED.has(key)) {
+    return false;
+  }
+
+  if (RESTRICTED_EXACT.has(key)) {
+    return true;
+  }
+
+  return RESTRICTED_PREFIXES.some(
+    (prefix) => fullPath === prefix || fullPath.startsWith(`${prefix}/`),
+  );
+}
+
+export const IMPERSONATION_RESTRICTED_EXACT = RESTRICTED_EXACT;
+export const IMPERSONATION_RESTRICTED_PREFIXES = RESTRICTED_PREFIXES;
+export const IMPERSONATION_ALWAYS_ALLOWED = ALWAYS_ALLOWED;