@hed-hog/core 0.0.390 → 0.0.394

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;

package/src/impersonation/impersonation.controller.ts

@@ -0,0 +1,109 @@
+import { Impersonation, ImpersonationContext, NoRole, Public, Role, User } from '@hed-hog/api';
+import { Locale } from '@hed-hog/api-locale';
+import { Pagination } from '@hed-hog/api-pagination';
+import {
+  Body,
+  Controller,
+  Get,
+  Headers,
+  Inject,
+  Ip,
+  Post,
+  Query,
+  UseGuards,
+  forwardRef,
+} from '@nestjs/common';
+import { Throttle, ThrottlerGuard } from '@nestjs/throttler';
+import { RedeemImpersonationDTO } from './dto/redeem-impersonation.dto';
+import { StartImpersonationDTO } from './dto/start-impersonation.dto';
+import { ImpersonationService } from './impersonation.service';
+
+/**
+ * Quem chama o quê:
+ * - `start` e `history`: a aba do OPERADOR, com papel administrativo;
+ * - `redeem`: a aba NOVA, que ainda nao tem sessao nenhuma — por isso @Public();
+ * - `stop` e `session`: a propria sessao SIMULADA, cujos papeis sao os do alvo
+ *   (um aluno, por exemplo) — por isso @NoRole(), e nao @Role().
+ */
+@Role()
+@Controller('impersonation')
+export class ImpersonationController {
+  constructor(
+    @Inject(forwardRef(() => ImpersonationService))
+    private readonly service: ImpersonationService,
+  ) {}
+
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  @Post('start')
+  async start(
+    @Locale() locale: string,
+    @User() operator,
+    @Impersonation() impersonation: ImpersonationContext,
+    @Body() body: StartImpersonationDTO & { targetUserId: number },
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.start({
+      locale,
+      operatorUserId: operator.id,
+      targetUserId: Number(body.targetUserId),
+      app: body.app,
+      reason: body.reason,
+      isImpersonating: impersonation.active,
+      ipAddress,
+      userAgent,
+    });
+  }
+
+  @Public()
+  @UseGuards(ThrottlerGuard)
+  @Throttle({ default: { limit: 20, ttl: 60_000 } })
+  @Post('redeem')
+  async redeem(
+    @Locale() locale: string,
+    @Body() { code }: RedeemImpersonationDTO,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+  ) {
+    return this.service.redeem({ locale, code, ipAddress, userAgent });
+  }
+
+  @NoRole()
+  @Post('stop')
+  async stop(
+    @User() target,
+    @Impersonation() impersonation: ImpersonationContext,
+    @Ip() ipAddress: string,
+  ) {
+    return this.service.stop({
+      sessionId: impersonation.sessionId,
+      targetUserId: target.id,
+      operatorUserId: impersonation.operatorUserId,
+      ipAddress,
+    });
+  }
+
+  @NoRole()
+  @Get('session')
+  async session(@Impersonation() impersonation: ImpersonationContext) {
+    return this.service.currentSession(
+      impersonation.active ? impersonation.sessionId : null,
+    );
+  }
+
+  @Get('apps')
+  async apps() {
+    return { apps: await this.service.listRedeemableApps() };
+  }
+
+  @Get('history')
+  async history(
+    @Pagination() paginationParams,
+    @Query('targetUserId') targetUserId?: string,
+  ) {
+    return this.service.history(paginationParams, {
+      targetUserId: targetUserId ? Number(targetUserId) : undefined,
+    });
+  }
+}

package/src/impersonation/impersonation.module.ts

@@ -0,0 +1,31 @@
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Module, forwardRef } from '@nestjs/common';
+import { SecurityModule } from '../security/security.module';
+import { SessionModule } from '../session/session.module';
+import { SettingModule } from '../setting/setting.module';
+import { TokenModule } from '../token/token.module';
+import { UserModule } from '../user/user.module';
+import { ImpersonationController } from './impersonation.controller';
+import { ImpersonationService } from './impersonation.service';
+
+/**
+ * Modulo proprio, e nao mais um endpoint no AuthModule, porque a simulacao tem
+ * um ciclo de vida completo (emitir → resgatar → encerrar → auditar) e uma
+ * denylist de rotas que o RoleGuard consulta.
+ */
+@Module({
+  imports: [
+    forwardRef(() => PrismaModule),
+    forwardRef(() => SecurityModule),
+    forwardRef(() => SettingModule),
+    forwardRef(() => TokenModule),
+    forwardRef(() => SessionModule),
+    forwardRef(() => UserModule),
+    forwardRef(() => PaginationModule),
+  ],
+  controllers: [ImpersonationController],
+  providers: [ImpersonationService],
+  exports: [ImpersonationService],
+})
+export class ImpersonationModule {}