@hed-hog/core 0.0.385 → 0.0.386

package/src/authorize/authorize.service.spec.ts

@@ -0,0 +1,307 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { BadRequestException } from '@nestjs/common';
+import { createHash, randomBytes } from 'crypto';
+
+// Mocka o MESMO módulo de onde o service importa (@hed-hog/api-prisma). Mockar
+// '@prisma/client' aqui deixaria o teste verde com um import que quebra em
+// runtime — foi exatamente o que aconteceu antes de o e2e pegar.
+jest.mock('@hed-hog/api-prisma', () => ({
+  PrismaService: class {},
+  Prisma: {
+    sql: (strings: TemplateStringsArray, ...values: unknown[]) => ({ strings: [...strings], values }),
+  },
+}));
+
+// eslint-disable-next-line import/first
+import { AuthorizeService } from './authorize.service';
+
+const CLIENT_ID = 'hedhog-extension';
+const REDIRECT_URI = 'https://gcjdclnalkkapoajodppjbcmifnadgok.chromiumapp.org/';
+
+/** base64url(sha256(v)) — o mesmo que SecurityService.hashSha256 produz. */
+const sha256b64url = (value: string) =>
+  createHash('sha256').update(value).digest('base64url');
+
+const makeVerifier = () => randomBytes(32).toString('base64url');
+
+const makeClient = (overrides: Record<string, unknown> = {}) => ({
+  client_id: CLIENT_ID,
+  name: 'HedHog Vaults Extension',
+  client_type: 'public',
+  redirect_uris: REDIRECT_URI,
+  scopes: 'vaults',
+  enabled: true,
+  ...overrides,
+});
+
+const makeDeps = () => {
+  const prisma = {
+    oauth_app_client: { findUnique: jest.fn() },
+    oauth_authorization_code: { create: jest.fn() },
+    $queryRaw: jest.fn(),
+  };
+  // Cripto real: é justamente o que estes testes precisam exercitar.
+  const security = {
+    randomOpaque: (size = 32) => randomBytes(size).toString('base64url'),
+    hashSha256: (value: string) => sha256b64url(value),
+  };
+  const auth = {
+    getAuthenticationPayload: jest.fn(async () => ({
+      accessToken: 'ACCESS',
+      refreshToken: 'REFRESH',
+      session: { id: 1 },
+    })),
+  };
+  return { prisma, security, auth };
+};
+
+const makeService = (deps: ReturnType<typeof makeDeps>) =>
+  new AuthorizeService(deps.prisma as never, deps.security as never, deps.auth as never);
+
+const validIssueParams = (challenge: string) => ({
+  userId: 7,
+  clientId: CLIENT_ID,
+  redirectUri: REDIRECT_URI,
+  scope: 'vaults',
+  codeChallenge: challenge,
+  codeChallengeMethod: 'S256',
+});
+
+const validExchangeParams = (code: string, verifier: string) => ({
+  code,
+  codeVerifier: verifier,
+  clientId: CLIENT_ID,
+  redirectUri: REDIRECT_URI,
+  locale: 'en',
+  ipAddress: '127.0.0.1',
+  userAgent: 'jest',
+});
+
+describe('AuthorizeService', () => {
+  let deps: ReturnType<typeof makeDeps>;
+  let service: AuthorizeService;
+
+  beforeEach(() => {
+    deps = makeDeps();
+    service = makeService(deps);
+    deps.prisma.oauth_app_client.findUnique.mockResolvedValue(makeClient() as never);
+  });
+
+  describe('issueCode', () => {
+    it('persiste apenas o hash do code, e devolve o code em claro', async () => {
+      const verifier = makeVerifier();
+      const code = await service.issueCode(validIssueParams(sha256b64url(verifier)));
+
+      const created = deps.prisma.oauth_authorization_code.create.mock.calls[0][0] as {
+        data: Record<string, unknown>;
+      };
+
+      expect(created.data.code_hash).toBe(sha256b64url(code));
+      expect(created.data.code_hash).not.toBe(code);
+      expect(created.data.user_id).toBe(7);
+      expect(created.data.code_challenge_method).toBe('S256');
+    });
+
+    it('dá ao code um TTL curto (60s)', async () => {
+      const before = Date.now();
+      await service.issueCode(validIssueParams(sha256b64url(makeVerifier())));
+
+      const created = deps.prisma.oauth_authorization_code.create.mock.calls[0][0] as {
+        data: { expires_at: Date };
+      };
+      const ttl = created.data.expires_at.getTime() - before;
+
+      expect(ttl).toBeGreaterThan(0);
+      expect(ttl).toBeLessThanOrEqual(60_000);
+    });
+
+    it('rejeita redirect_uri não registrado', async () => {
+      await expect(
+        service.issueCode({
+          ...validIssueParams(sha256b64url(makeVerifier())),
+          redirectUri: 'https://evil.example.com/',
+        }),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('rejeita redirect_uri que só difere por sufixo (sem match parcial)', async () => {
+      await expect(
+        service.issueCode({
+          ...validIssueParams(sha256b64url(makeVerifier())),
+          redirectUri: `${REDIRECT_URI}../evil`,
+        }),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('rejeita code_challenge_method plain', async () => {
+      await expect(
+        service.issueCode({
+          ...validIssueParams(sha256b64url(makeVerifier())),
+          codeChallengeMethod: 'plain',
+        }),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('rejeita code_challenge curto demais', async () => {
+      await expect(
+        service.issueCode({ ...validIssueParams('curto'), codeChallengeMethod: 'S256' }),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('rejeita scope fora do que o client tem', async () => {
+      await expect(
+        service.issueCode({
+          ...validIssueParams(sha256b64url(makeVerifier())),
+          scope: 'vaults admin',
+        }),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('rejeita client desabilitado', async () => {
+      deps.prisma.oauth_app_client.findUnique.mockResolvedValue(
+        makeClient({ enabled: false }) as never,
+      );
+      await expect(
+        service.issueCode(validIssueParams(sha256b64url(makeVerifier()))),
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it('rejeita client inexistente', async () => {
+      deps.prisma.oauth_app_client.findUnique.mockResolvedValue(null as never);
+      await expect(
+        service.issueCode(validIssueParams(sha256b64url(makeVerifier()))),
+      ).rejects.toThrow(BadRequestException);
+    });
+  });
+
+  describe('exchangeCode', () => {
+    it('troca o code por tokens quando o verifier confere', async () => {
+      const verifier = makeVerifier();
+      deps.prisma.$queryRaw.mockResolvedValue([
+        { user_id: 7, code_challenge: sha256b64url(verifier), scope: 'vaults' },
+      ] as never);
+
+      const result = await service.exchangeCode(validExchangeParams('CODE', verifier));
+
+      expect(result.accessToken).toBe('ACCESS');
+      expect(result.refreshToken).toBe('REFRESH');
+      expect(result.tokenType).toBe('Bearer');
+      expect(deps.auth.getAuthenticationPayload).toHaveBeenCalledWith(
+        'en',
+        7,
+        '127.0.0.1',
+        'jest',
+      );
+    });
+
+    it('rejeita verifier errado, e não emite token', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([
+        { user_id: 7, code_challenge: sha256b64url(makeVerifier()), scope: 'vaults' },
+      ] as never);
+
+      await expect(
+        service.exchangeCode(validExchangeParams('CODE', makeVerifier())),
+      ).rejects.toThrow(BadRequestException);
+      expect(deps.auth.getAuthenticationPayload).not.toHaveBeenCalled();
+    });
+
+    it('rejeita verifier curto demais (piso do RFC 7636)', async () => {
+      deps.prisma.$queryRaw.mockResolvedValue([
+        { user_id: 7, code_challenge: sha256b64url('curto'), scope: 'vaults' },
+      ] as never);
+
+      await expect(service.exchangeCode(validExchangeParams('CODE', 'curto'))).rejects.toThrow(
+        BadRequestException,
+      );
+    });
+
+    it('rejeita code já consumido, expirado ou inexistente', async () => {
+      // O UPDATE ... WHERE consumed_at IS NULL não devolve linha nesses casos.
+      deps.prisma.$queryRaw.mockResolvedValue([] as never);
+
+      await expect(
+        service.exchangeCode(validExchangeParams('CODE', makeVerifier())),
+      ).rejects.toThrow(BadRequestException);
+      expect(deps.auth.getAuthenticationPayload).not.toHaveBeenCalled();
+    });
+
+    it('consome o code no mesmo UPDATE que o lê (replay não tem segunda chance)', async () => {
+      const verifier = makeVerifier();
+      deps.prisma.$queryRaw.mockResolvedValue([
+        { user_id: 7, code_challenge: sha256b64url(verifier), scope: 'vaults' },
+      ] as never);
+
+      await service.exchangeCode(validExchangeParams('CODE', verifier));
+
+      const sql = JSON.stringify(deps.prisma.$queryRaw.mock.calls[0][0]);
+      expect(sql).toContain('consumed_at = NOW()');
+      expect(sql).toContain('consumed_at IS NULL');
+      expect(sql).toContain('expires_at > NOW()');
+    });
+
+    it('busca o code pelo hash, nunca pelo valor em claro', async () => {
+      const verifier = makeVerifier();
+      deps.prisma.$queryRaw.mockResolvedValue([
+        { user_id: 7, code_challenge: sha256b64url(verifier), scope: 'vaults' },
+      ] as never);
+
+      await service.exchangeCode(validExchangeParams('CODE-EM-CLARO', verifier));
+
+      const params = JSON.stringify(deps.prisma.$queryRaw.mock.calls[0][0]);
+      expect(params).toContain(sha256b64url('CODE-EM-CLARO'));
+      expect(params).not.toContain('CODE-EM-CLARO');
+    });
+
+    it('amarra o code ao redirect_uri usado no authorize', async () => {
+      const verifier = makeVerifier();
+      deps.prisma.$queryRaw.mockResolvedValue([] as never);
+
+      await expect(
+        service.exchangeCode({
+          ...validExchangeParams('CODE', verifier),
+          redirectUri: 'https://evil.example.com/',
+        }),
+      ).rejects.toThrow(BadRequestException);
+
+      const params = JSON.stringify(deps.prisma.$queryRaw.mock.calls[0][0]);
+      expect(params).toContain('https://evil.example.com/');
+    });
+
+    it('recusa client confidencial neste fluxo', async () => {
+      deps.prisma.oauth_app_client.findUnique.mockResolvedValue(
+        makeClient({ client_type: 'confidential' }) as never,
+      );
+
+      await expect(
+        service.exchangeCode(validExchangeParams('CODE', makeVerifier())),
+      ).rejects.toThrow(BadRequestException);
+      expect(deps.prisma.$queryRaw).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('getAuthorizationInfo', () => {
+    it('devolve o nome do app e os escopos para a tela de consent', async () => {
+      const info = await service.getAuthorizationInfo({
+        clientId: CLIENT_ID,
+        redirectUri: REDIRECT_URI,
+        scope: 'vaults',
+        codeChallenge: sha256b64url(makeVerifier()),
+        codeChallengeMethod: 'S256',
+      });
+
+      expect(info).toEqual({ clientName: 'HedHog Vaults Extension', scopes: ['vaults'] });
+    });
+
+    it('valida antes de a página redirecionar para qualquer lugar', async () => {
+      await expect(
+        service.getAuthorizationInfo({
+          clientId: CLIENT_ID,
+          redirectUri: 'https://evil.example.com/',
+          scope: 'vaults',
+          codeChallenge: sha256b64url(makeVerifier()),
+          codeChallengeMethod: 'S256',
+        }),
+      ).rejects.toThrow(BadRequestException);
+    });
+  });
+});

package/src/authorize/authorize.service.ts

@@ -0,0 +1,245 @@
+// `Prisma` vem de @hed-hog/api-prisma, não de '@prisma/client': o tsconfig do
+// monorepo mapeia '@prisma/client' para o client gerado (.prisma/client), que
+// não expõe o helper `Prisma.sql`. É a convenção do repo inteiro.
+import { Prisma, PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  Logger,
+  forwardRef,
+} from '@nestjs/common';
+import { timingSafeEqual } from 'crypto';
+import { AuthService } from '../auth/auth.service';
+import { SecurityService } from '../security/security.service';
+
+/**
+ * Authorization Code + PKCE — o HedHog como OAuth *provider* para apps
+ * first-party (a extensão de navegador; e o que vier depois).
+ *
+ * Modelado no padrão `web ref` do OAuthService: token opaco de que só o hash é
+ * persistido, TTL curto e consumo single-use atômico via UPDATE ... RETURNING.
+ *
+ * Por que existe, em vez de reusar GET /auth/desktop-token: aquele fluxo entrega
+ * accessToken e refreshToken na URL do redirect, e aceita `?scheme=` sem
+ * allowlist (open redirect). Para um gerenciador de senhas isso não serve.
+ */
+@Injectable()
+export class AuthorizeService {
+  private readonly logger = new Logger(AuthorizeService.name);
+
+  /** Curto de propósito: o code viaja na URL e só precisa sobreviver ao redirect. */
+  private readonly codeTtlMs = 60_000;
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => SecurityService))
+    private readonly security: SecurityService,
+    @Inject(forwardRef(() => AuthService))
+    private readonly auth: AuthService,
+  ) {}
+
+  private async getClient(clientId: string) {
+    const client = await this.prisma.oauth_app_client.findUnique({
+      where: { client_id: clientId },
+    });
+
+    if (!client || !client.enabled) {
+      throw new BadRequestException('Aplicativo desconhecido ou desabilitado.');
+    }
+
+    return client;
+  }
+
+  /**
+   * A allowlist é comparada por igualdade de string, não por parsing de URL:
+   * normalizar/parsear abriria espaço para bypass (barra final, case do host,
+   * userinfo, `origin` valendo "null" em esquemas não-http).
+   */
+  private assertRedirectUri(client: { redirect_uris: string }, redirectUri: string) {
+    const allowed = client.redirect_uris
+      .split('\n')
+      .map((uri) => uri.trim())
+      .filter(Boolean);
+
+    if (!allowed.includes(redirectUri)) {
+      throw new BadRequestException('redirect_uri não registrado para este aplicativo.');
+    }
+  }
+
+  private assertScope(client: { scopes: string }, scope: string) {
+    const granted = new Set(client.scopes.split(/[\s,]+/).filter(Boolean));
+    const requested = scope.split(/[\s,]+/).filter(Boolean);
+
+    if (requested.length === 0) {
+      throw new BadRequestException('scope é obrigatório.');
+    }
+    if (!requested.every((s) => granted.has(s))) {
+      throw new BadRequestException('scope não autorizado para este aplicativo.');
+    }
+  }
+
+  /** Metadados para a tela de consent. Também valida antes de qualquer redirect. */
+  async getAuthorizationInfo(params: {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+  }) {
+    const client = await this.getClient(params.clientId);
+    this.assertRedirectUri(client, params.redirectUri);
+    this.assertScope(client, params.scope);
+    this.assertPkce(params.codeChallenge, params.codeChallengeMethod);
+
+    return {
+      clientName: client.name,
+      scopes: params.scope.split(/[\s,]+/).filter(Boolean),
+    };
+  }
+
+  /**
+   * `plain` é rejeitado sem exceção: com ele o "verifier" viaja igual ao
+   * challenge e o PKCE não protege nada. O RFC 7636 permite; nós não.
+   */
+  private assertPkce(codeChallenge: string, method: string) {
+    if (method !== 'S256') {
+      throw new BadRequestException('code_challenge_method deve ser S256.');
+    }
+    if (
+      !codeChallenge ||
+      codeChallenge.length < 43 ||
+      codeChallenge.length > 128 ||
+      !/^[A-Za-z0-9\-._~]+$/.test(codeChallenge)
+    ) {
+      throw new BadRequestException('code_challenge inválido.');
+    }
+  }
+
+  /** Emite o code já vinculado ao usuário da sessão que aprovou o consent. */
+  async issueCode(params: {
+    userId: number;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    codeChallenge: string;
+    codeChallengeMethod: string;
+  }): Promise<string> {
+    const client = await this.getClient(params.clientId);
+    this.assertRedirectUri(client, params.redirectUri);
+    this.assertScope(client, params.scope);
+    this.assertPkce(params.codeChallenge, params.codeChallengeMethod);
+
+    const code = this.security.randomOpaque(32);
+    const codeHash = this.security.hashSha256(code);
+    const expiresAt = new Date(Date.now() + this.codeTtlMs);
+
+    await this.prisma.oauth_authorization_code.create({
+      data: {
+        code_hash: codeHash,
+        client_id: params.clientId,
+        user_id: params.userId,
+        redirect_uri: params.redirectUri,
+        scope: params.scope,
+        code_challenge: params.codeChallenge,
+        code_challenge_method: 'S256',
+        expires_at: expiresAt,
+      },
+    });
+
+    this.logger.debug(
+      `[AuthorizeService] code emitido client=${params.clientId} userId=${params.userId}`,
+    );
+
+    return code;
+  }
+
+  /**
+   * Troca o code por tokens. O consumo é atômico (UPDATE ... WHERE consumed_at
+   * IS NULL RETURNING): dois requests concorrentes com o mesmo code — o caso de
+   * replay — só podem ter um vencedor, decidido pelo banco.
+   */
+  async exchangeCode(params: {
+    code: string;
+    codeVerifier: string;
+    clientId: string;
+    redirectUri: string;
+    locale: string;
+    ipAddress: string;
+    userAgent: string;
+  }) {
+    const client = await this.getClient(params.clientId);
+
+    if (client.client_type !== 'public') {
+      throw new BadRequestException('Fluxo indisponível para este aplicativo.');
+    }
+
+    const codeHash = this.security.hashSha256(params.code);
+
+    const rows = await this.prisma.$queryRaw<
+      Array<{ user_id: number; code_challenge: string; scope: string }>
+    >(
+      Prisma.sql`
+        UPDATE oauth_authorization_code
+        SET consumed_at = NOW()
+        WHERE code_hash = ${codeHash}
+          AND client_id = ${params.clientId}
+          AND redirect_uri = ${params.redirectUri}
+          AND expires_at > NOW()
+          AND consumed_at IS NULL
+        RETURNING user_id, code_challenge, scope
+      `,
+    );
+
+    const row = rows[0];
+    if (!row) {
+      throw new BadRequestException(
+        'Código inválido, expirado ou já utilizado. Refaça a autorização.',
+      );
+    }
+
+    if (!this.verifyPkce(params.codeVerifier, row.code_challenge)) {
+      // O code já foi consumido acima — um verifier errado não dá segunda chance.
+      this.logger.warn(
+        `[AuthorizeService] PKCE falhou client=${params.clientId} userId=${row.user_id}`,
+      );
+      throw new BadRequestException('code_verifier inválido.');
+    }
+
+    const { accessToken, refreshToken } = await this.auth.getAuthenticationPayload(
+      params.locale,
+      row.user_id,
+      params.ipAddress,
+      params.userAgent,
+    );
+
+    return {
+      accessToken,
+      refreshToken,
+      tokenType: 'Bearer',
+      // Informativo para o cliente agendar refresh; a verdade é o exp do JWT.
+      expiresIn: 3600,
+      scope: row.scope,
+    };
+  }
+
+  /** base64url(sha256(verifier)) === challenge, em tempo constante. */
+  private verifyPkce(codeVerifier: string, codeChallenge: string): boolean {
+    if (!codeVerifier || codeVerifier.length < 43 || codeVerifier.length > 128) {
+      return false;
+    }
+
+    // hashSha256 já devolve base64url — o mesmo formato do S256.
+    const expected = Buffer.from(this.security.hashSha256(codeVerifier));
+    const provided = Buffer.from(codeChallenge);
+
+    if (expected.length !== provided.length) return false;
+
+    try {
+      return timingSafeEqual(expected, provided);
+    } catch {
+      return false;
+    }
+  }
+}

package/src/authorize/dto/authorize-info.dto.ts

@@ -0,0 +1,23 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+
+export class AuthorizeInfoDTO {
+  @IsString()
+  @IsNotEmpty()
+  client_id: string;
+
+  @IsString()
+  @IsNotEmpty()
+  redirect_uri: string;
+
+  @IsString()
+  @IsNotEmpty()
+  scope: string;
+
+  @IsString()
+  @IsNotEmpty()
+  code_challenge: string;
+
+  @IsString()
+  @IsNotEmpty()
+  code_challenge_method: string;
+}

package/src/authorize/dto/consent.dto.ts

@@ -0,0 +1,23 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+
+export class ConsentDTO {
+  @IsString()
+  @IsNotEmpty()
+  client_id: string;
+
+  @IsString()
+  @IsNotEmpty()
+  redirect_uri: string;
+
+  @IsString()
+  @IsNotEmpty()
+  scope: string;
+
+  @IsString()
+  @IsNotEmpty()
+  code_challenge: string;
+
+  @IsString()
+  @IsNotEmpty()
+  code_challenge_method: string;
+}

package/src/authorize/dto/token.dto.ts

@@ -0,0 +1,23 @@
+import { IsIn, IsNotEmpty, IsString } from 'class-validator';
+
+export class TokenDTO {
+  @IsString()
+  @IsIn(['authorization_code'])
+  grant_type: string;
+
+  @IsString()
+  @IsNotEmpty()
+  code: string;
+
+  @IsString()
+  @IsNotEmpty()
+  code_verifier: string;
+
+  @IsString()
+  @IsNotEmpty()
+  client_id: string;
+
+  @IsString()
+  @IsNotEmpty()
+  redirect_uri: string;
+}

package/src/challenge/challenge.service.ts

@@ -239,6 +239,34 @@ export class ChallengeService {
     return challenge;
   }
 
+  /**
+   * Cria um challenge de convite de criação de conta vinculado a um
+   * `user_identifier` de email já existente e retorna o token em base64
+   * (mesmo formato consumido pelo fluxo de reset de senha). A validade usa a
+   * setting `account-invite-expiration-minutes` (padrão 7 dias).
+   */
+  async createAccountInviteChallenge(userIdentifierId: number): Promise<string> {
+    const settings = await this.setting.getSettingValues([
+      'account-invite-expiration-minutes',
+    ]);
+
+    const token = await this.token.createOpaqueToken(16);
+    const hash = this.security.hashWithPepper(token);
+
+    await this.prisma.user_identifier_challenge.create({
+      data: {
+        hash,
+        expires_at: new Date(
+          Date.now() +
+            (settings['account-invite-expiration-minutes'] || 10080) * 60000,
+        ),
+        user_identifier_id: userIdentifierId,
+      },
+    });
+
+    return Buffer.from(token).toString('base64');
+  }
+
   private resolveAppUrl(settings: Record<string, any>, app?: string): string {
     const appUrls: string[] = Array.isArray(settings['app-urls']) ? settings['app-urls'] : [];
 

package/src/core.module.ts

@@ -42,6 +42,7 @@ import { IsPinCodeWithSettingConstraint } from './validators/is-pin-code-with-se
 import { IsStrongPasswordWithSettingsConstraint } from './validators/is-strong-password-with-settings.validator';
 import { ValidatorServiceLocator } from './validators/service-locator';
 import { AiInstructionModule } from './ai-instruction/ai-instruction.module';
+import { AuthorizeModule } from './authorize/authorize.module';
 import { IntegrationProfileModule } from './integration-profile/integration-profile.module';
 import { WebhookIntegrationModule } from './webhook-integration/webhook-integration.module';
 
@@ -53,6 +54,7 @@ import { WebhookIntegrationModule } from './webhook-integration/webhook-integrat
     forwardRef(() => AiModule),
     forwardRef(() => InstallModule),
     forwardRef(() => AuthModule),
+    forwardRef(() => AuthorizeModule),
     forwardRef(() => DashboardModule),
     forwardRef(() => MailSendModule),
     forwardRef(() => MenuModule),

package/src/file/file.service.ts

@@ -1041,6 +1041,25 @@ export class FileService implements OnModuleInit {
     return (await this.getProvider()).tempURL(filepath, expires);
   }
 
+  /**
+   * URL temporária a partir do id do arquivo.
+   * Prefira este método a `tempURL(file.path)`: quando `path` é apenas o
+   * basename, a chave real no provider inclui o prefixo `location`, e passar
+   * `path` cru gera uma URL que resolve para NoSuchKey.
+   */
+  async tempURLById(fileId: number, expires = 3600) {
+    const file = await this.prismaService.file.findFirst({
+      where: { id: fileId },
+      select: { location: true, path: true },
+    });
+
+    if (!file) {
+      throw new NotFoundException(`Not found: ${fileId}`);
+    }
+
+    return this.tempURL(this.resolveProviderPath(file), expires);
+  }
+
   async tempOpenURL(filepath: string, expires = 3600) {
     const url = await this.tempURL(filepath, expires);