@hed-hog/core 0.0.385 → 0.0.386

package/src/integration-profile/integration-profile.secrets.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from '@jest/globals';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { INTEGRATION_SECRET_KEYS, getSensitiveConfigKeys } from './integration-profile.secrets';
+
+/**
+ * TRAVA DE SEGURANÇA: PROVIDER_FIELDS (admin) e INTEGRATION_SECRET_KEYS (aqui)
+ * são dois mapas hardcoded que precisam ficar em sincronia manual. Se um campo
+ * sensível do form não estiver no allowlist, ele é gravado NO BANCO EM TEXTO
+ * CLARO — sem erro, sem aviso.
+ *
+ * Esse sync já derrapou antes (o docblock do .secrets.ts apontava para um
+ * arquivo onde PROVIDER_FIELDS não existe mais). Este teste transforma o
+ * combinado em falha de CI.
+ *
+ * Lê o fonte do admin em vez de importá-lo: o arquivo é um componente React/TSX
+ * com imports de UI que não carregam sob o jest de backend.
+ */
+const SHEET_PATH = join(
+  __dirname,
+  '../../../../apps/admin/src/components/integration-profile/integration-profile-sheet.tsx',
+);
+
+/** Extrai { providerSlug: [chaves sensíveis] } do PROVIDER_FIELDS do admin. */
+function parseSensitiveFieldsFromAdmin(): Record<string, string[]> {
+  const source = readFileSync(SHEET_PATH, 'utf8');
+
+  const start = source.indexOf('const PROVIDER_FIELDS');
+  expect(start).toBeGreaterThan(-1);
+
+  // Vai até o fecho do objeto no nível zero: `\n};`
+  const end = source.indexOf('\n};', start);
+  expect(end).toBeGreaterThan(start);
+
+  const block = source.slice(start, end);
+  const result: Record<string, string[]> = {};
+
+  // Cada provider começa com `  slug: [` ou `  'slug': [` na indentação de 2.
+  const providerRegex = /\n {2}'?([a-z0-9_-]+)'?: \[/g;
+  const providers: Array<{ slug: string; from: number }> = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = providerRegex.exec(block)) !== null) {
+    providers.push({ slug: match[1], from: match.index });
+  }
+
+  providers.forEach((provider, index) => {
+    const chunk = block.slice(
+      provider.from,
+      index + 1 < providers.length ? providers[index + 1].from : block.length,
+    );
+
+    const fields: string[] = [];
+    // Cada field é um objeto com key e type; casa os dois em qualquer ordem.
+    const fieldRegex = /key:\s*'([^']+)'[\s\S]*?type:\s*'([^']+)'/g;
+    let fieldMatch: RegExpExecArray | null;
+
+    while ((fieldMatch = fieldRegex.exec(chunk)) !== null) {
+      const [, key, type] = fieldMatch;
+      if (type === 'password' || type === 'file') {
+        fields.push(key);
+      }
+    }
+
+    result[provider.slug] = fields;
+  });
+
+  return result;
+}
+
+describe('INTEGRATION_SECRET_KEYS is in sync with the admin form', () => {
+  const adminSensitive = parseSensitiveFieldsFromAdmin();
+
+  it('parses the admin PROVIDER_FIELDS map', () => {
+    // Se o parser quebrar, o resto passaria vacuamente. Fixa um piso conhecido.
+    expect(Object.keys(adminSensitive).length).toBeGreaterThan(5);
+    expect(adminSensitive.smtp).toContain('password');
+  });
+
+  it.each(Object.entries(adminSensitive).filter(([, fields]) => fields.length))(
+    'provider "%s" has every password/file field in the allowlist',
+    (providerSlug, fields) => {
+      const allowlisted = getSensitiveConfigKeys(providerSlug);
+      const missing = (fields as string[]).filter((key) => !allowlisted.includes(key));
+
+      // Uma chave listada aqui seria gravada em texto claro no banco.
+      expect(missing).toEqual([]);
+    },
+  );
+
+  it('keeps the A1 certificate and its password encrypted', () => {
+    // O caso que mais dói: quem tem o PFX + a senha emite nota como a empresa.
+    expect(getSensitiveConfigKeys('nfse-national')).toEqual(
+      expect.arrayContaining(['certificate_pfx_base64', 'certificate_password']),
+    );
+  });
+
+  it('does not treat public keys as secrets', () => {
+    // site_key/public_key/access_key_id contêm "key" mas são públicos. Cifrá-los
+    // por heurística de nome quebraria integrações silenciosamente.
+    expect(getSensitiveConfigKeys('recaptcha')).not.toContain('site_key');
+    expect(getSensitiveConfigKeys('s3')).not.toContain('access_key_id');
+  });
+
+  it('returns an empty list for an unknown provider', () => {
+    expect(getSensitiveConfigKeys('does-not-exist')).toEqual([]);
+  });
+
+  it('has no duplicate keys per provider', () => {
+    for (const [slug, keys] of Object.entries(INTEGRATION_SECRET_KEYS)) {
+      expect(new Set(keys).size).toBe(keys.length);
+    }
+  });
+});

package/src/integration-profile/integration-profile.secrets.ts

@@ -4,8 +4,12 @@
  * SEGURANÇA-CRÍTICO: este mapa é a fonte única de verdade do que é cifrado em repouso
  * (integration-credential-crypto.service) e mascarado na exportação/UI. Qualquer chave
  * esquecida aqui NÃO será cifrada. Deve ser mantido em sincronia com os campos
- * `type: 'password'` do form do admin (PROVIDER_FIELDS em
- * apps/admin/src/app/(app)/(libraries)/core/integration/profiles/page.tsx).
+ * `type: 'password'` e `type: 'file'` do form do admin (PROVIDER_FIELDS em
+ * apps/admin/src/components/integration-profile/integration-profile-sheet.tsx).
+ *
+ * O sync é manual e já derrapou uma vez (este comentário apontava para um arquivo
+ * onde PROVIDER_FIELDS não existe mais). Por isso existe um teste que falha se um
+ * campo sensível do form não tiver entrada aqui: integration-profile.secrets.spec.ts.
  *
  * Não usar heurística por nome de chave: campos públicos como `site_key`, `public_key` e
  * `access_key_id` contêm "key" mas NÃO são segredos.
@@ -15,6 +19,7 @@ export const INTEGRATION_SECRET_KEYS: Record<string, string[]> = {
   smtp: ['password'],
   gmail: ['client_secret', 'refresh_token'],
   ses: ['secret_access_key'],
+  resend: ['api_token', 'webhook_secret'],
   // Mensageria
   'evolution-api': ['token'],
   'whatsapp-official': ['access_token'],
@@ -47,6 +52,10 @@ export const INTEGRATION_SECRET_KEYS: Record<string, string[]> = {
   // Infraestrutura (autoscaling)
   digitalocean: ['api_token'],
   kubernetes: ['token', 'ca_cert'],
+  // Fiscal
+  // O certificado A1 é a chave privada da empresa: quem tem o PFX + a senha
+  // emite nota em nome dela. Os dois DEVEM estar aqui.
+  'nfse-national': ['certificate_pfx_base64', 'certificate_password'],
 };
 
 /** Chaves sensíveis de um provider (vazio se desconhecido). */

package/src/integration-profile/integration-profile.service.ts

@@ -472,6 +472,25 @@ export class IntegrationProfileService {
       ) as Record<string, unknown>;
     }
 
+    // Resend não usa SMTP/from_email: valida credenciais/domínio próprios.
+    if (provider.slug === 'resend') {
+      const resendCfg = (effectiveConfig as Record<string, unknown> | null) ?? {};
+      const apiToken = String(resendCfg.api_token ?? '').trim();
+      const domain = String(resendCfg.domain ?? '').trim();
+
+      if (!apiToken) {
+        throw new BadRequestException('Resend API token is required.');
+      }
+      if (!domain) {
+        throw new BadRequestException('Resend sending domain is required.');
+      }
+
+      return {
+        success: true,
+        destination: domain,
+      };
+    }
+
     buildMailConfigFromIntegration(provider.slug, effectiveConfig);
 
     const destination = String(

package/src/integration-profile/integration-profile.utils.ts

@@ -38,11 +38,51 @@ export function buildMailConfigFromIntegration(
         secretAccessKey: String(cfg.secret_access_key ?? ''),
         from: String(cfg.from_email ?? ''),
       };
+    case 'resend':
+      // Resend usa a API HTTP própria (não nodemailer). Retornamos um marcador
+      // tipado para os consumidores ramificarem; o inbox usa
+      // `buildResendConfigFromIntegration` diretamente.
+      return {
+        global: true,
+        type: 'RESEND' as const,
+        apiToken: String(cfg.api_token ?? ''),
+        domain: String(cfg.domain ?? ''),
+        region: String(cfg.region ?? ''),
+        from: String(cfg.from_email ?? ''),
+      };
     default:
       throw new BadRequestException(`Unsupported mail provider: ${providerSlug}`);
   }
 }
 
+export type ResendIntegrationConfig = {
+  apiToken: string;
+  domain: string;
+  region?: string;
+  webhookSecret?: string;
+  providerDomainId?: string;
+  fromName?: string;
+};
+
+/** Maps an integration_profile config JSON to the Resend credentials/domain. */
+export function buildResendConfigFromIntegration(
+  config: unknown,
+): ResendIntegrationConfig {
+  const cfg = (config as Cfg) ?? {};
+  return {
+    apiToken: String(cfg.api_token ?? '').trim(),
+    domain: String(cfg.domain ?? '').trim(),
+    ...(cfg.region ? { region: String(cfg.region).trim() } : {}),
+    ...(cfg.webhook_secret
+      ? { webhookSecret: String(cfg.webhook_secret).trim() }
+      : {}),
+    ...(cfg.provider_domain_id
+      ? { providerDomainId: String(cfg.provider_domain_id).trim() }
+      : {}),
+    ...(cfg.from_name ? { fromName: String(cfg.from_name).trim() } : {}),
+  };
+}
+
 export function getFromAddress(config: unknown): string {
   const cfg = (config as Cfg) ?? {};
   const fromEmail = String(cfg.from_email ?? '');

package/src/oauth/interfaces/OAuthProvider.ts

@@ -1,5 +1,9 @@
 export interface OAuthProvider {
-  getAuthUrl(callbackPath: string): Promise<string>;
+  getAuthUrl(
+    callbackPath: string,
+    flow?: 'login' | 'register' | 'connect',
+    app?: string,
+  ): Promise<string>;
   getProfile(code: string, type?: string, redirectUri?: string): Promise<any>;
   getProviderType(): string;
 }

package/src/oauth/oauth.controller.ts

@@ -97,6 +97,95 @@ export class OAuthController {
     return res.redirect(redirectURL);
   }
 
+  /**
+   * Server-side bounce for Microsoft Entra ID. Entra's authorization `code` is ~2KB
+   * (forced `offline_access`), which trips front-end ingress buffers when forwarded
+   * in an app URL. So Entra's web `redirect_uri` points here: we exchange the code
+   * server-side and redirect the browser to the initiating app with only a short
+   * single-use `ref` (never the giant code).
+   */
+  @Public()
+  @Get('microsoft-entra-id/callback')
+  async microsoftEntraIdCallback(
+    @Query('code') code: string,
+    @Query('state') state: string,
+    @Headers('user-agent') userAgent: string,
+    @Ip() ipAddress: string,
+    @Res() res,
+  ) {
+    this.logOAuthRequest('callback-web-ref', 'microsoft-entra-id', {
+      ipAddress,
+      userAgent,
+      code,
+    });
+
+    const forward = await this.service.resolveWebForward(state);
+    const flow = (forward?.flow ?? 'login') as 'login' | 'register' | 'connect';
+    const { url: frontendURL = '' } = await this.settingService.getSettingValues(['url']);
+    const base = forward?.origin || frontendURL;
+
+    const ref = await this.service.beginWebRefCallback({
+      provider: 'microsoft-entra-id' as user_account_provider_52222e2ecb_enum,
+      code,
+      state,
+      flow,
+      appOrigin: forward?.origin ?? null,
+    });
+
+    return res.redirect(
+      `${base}/callback/microsoft-entra-id/${flow}?ref=${encodeURIComponent(ref)}`,
+    );
+  }
+
+  /** Redeems a login/register `ref` from the Entra server-side bounce (public). */
+  @Public()
+  @Get('microsoft-entra-id/redeem')
+  async microsoftEntraIdRedeem(
+    @Locale() locale: string,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+    @Headers('origin') origin: string,
+    @Headers('referer') referer: string,
+    @Query('ref') ref: string,
+    @Res({ passthrough: true }) res,
+  ) {
+    return this.service.redeemWebRef({
+      res,
+      ref,
+      provider: 'microsoft-entra-id' as user_account_provider_52222e2ecb_enum,
+      locale,
+      ipAddress,
+      userAgent,
+      requestOrigin: origin,
+      requestReferer: referer,
+    });
+  }
+
+  /** Redeems a connect `ref` (authenticated: connect binds to the current user). */
+  @Get('microsoft-entra-id/redeem/connect')
+  async microsoftEntraIdRedeemConnect(
+    @Locale() locale: string,
+    @Ip() ipAddress: string,
+    @Headers('user-agent') userAgent: string,
+    @Headers('origin') origin: string,
+    @Headers('referer') referer: string,
+    @User() { id },
+    @Query('ref') ref: string,
+    @Res({ passthrough: true }) res,
+  ) {
+    return this.service.redeemWebRef({
+      res,
+      ref,
+      provider: 'microsoft-entra-id' as user_account_provider_52222e2ecb_enum,
+      locale,
+      ipAddress,
+      userAgent,
+      userId: id,
+      requestOrigin: origin,
+      requestReferer: referer,
+    });
+  }
+
   @Public()
   @Get(':provider/login')
   async login(

package/src/oauth/oauth.service.ts

@@ -89,12 +89,17 @@ export class OAuthService {
     this.providers.set(linkedin.getProviderType(), linkedin);
   }
 
-  async getAuthUrl(provider: user_account_provider_52222e2ecb_enum, callbackPath: string) {
+  async getAuthUrl(
+    provider: user_account_provider_52222e2ecb_enum,
+    callbackPath: string,
+    flow?: 'login' | 'register' | 'connect',
+    app?: string,
+  ) {
     const enabled = await this.isProviderEnabled(provider);
     if (!enabled) {
       throw new BadRequestException(`OAuth provider ${provider} is not enabled.`);
     }
-    return this.getProvider(provider).getAuthUrl(callbackPath);
+    return this.getProvider(provider).getAuthUrl(callbackPath, flow, app);
   }
 
   async getMobileAuthUrl(
@@ -137,15 +142,16 @@ export class OAuthService {
     flow: 'login' | 'register' | 'connect',
     redirectApp?: string,
   ) {
+    // `self` means "the hub handles it locally"; a resolvable app key means the hub
+    // forwards the callback back to that app (origin-bound).
+    const app = this.sanitizeAppKey(redirectApp) ?? OAuthService.WEB_STATE_SELF_APP;
+
     // Single, flow-less callback per provider: the flow (and the initiating app)
     // travel in the signed state, so only ONE redirect URI needs to be registered
-    // per provider in its OAuth console.
+    // per provider in its OAuth console. `flow`/`app` are forwarded so providers that
+    // need them (e.g. Microsoft Entra ID's backend bounce + `prompt=consent`) can adapt.
     const callbackPath = `/callback/${String(provider)}`;
-    const authUrl = await this.getAuthUrl(provider, callbackPath);
-
-    // Always carry the flow. `self` means "the hub handles it locally"; a resolvable
-    // app key means the hub forwards the callback back to that app (origin-bound).
-    const app = this.sanitizeAppKey(redirectApp) ?? OAuthService.WEB_STATE_SELF_APP;
+    const authUrl = await this.getAuthUrl(provider, callbackPath, flow, app);
 
     const url = new URL(authUrl);
     url.searchParams.set('state', this.buildWebState(app, flow));
@@ -549,6 +555,182 @@ export class OAuthService {
     return record?.redirect_uri ?? null;
   }
 
+  /** TTL for the short web-ref bounce token (Entra). Short: it briefly holds an encrypted profile. */
+  private readonly webRefTokenTtlMs = 2 * 60 * 1000;
+
+  /**
+   * Server-side bounce for providers whose authorization `code` is too large to
+   * safely ride a front-end app URL (Microsoft Entra ID). Exchanges the code here
+   * (once, under the callback lock), stores the resulting profile encrypted under
+   * an opaque single-use `ref`, and returns that `ref`. The app later redeems it via
+   * `redeemWebRef`, so the giant code never reaches a front-end ingress.
+   */
+  async beginWebRefCallback({
+    provider,
+    code,
+    state,
+    flow,
+    appOrigin,
+  }: {
+    provider: user_account_provider_52222e2ecb_enum;
+    code: string;
+    state?: string;
+    flow: 'login' | 'register' | 'connect';
+    appOrigin: string | null;
+  }): Promise<string> {
+    if (!code) {
+      throw new BadRequestException('Authorization code is required.');
+    }
+
+    // Match the redirect_uri used at authorize time (the API callback).
+    const settings = await this.setting.getSettingValues(['api-url']);
+    const apiRedirectUri = new URL(
+      '/oauth/microsoft-entra-id/callback',
+      String(settings['api-url'] ?? ''),
+    ).toString();
+
+    const callbackKey = this.buildCallbackKey(provider, flow, code);
+    const profile = await this.callbackCoordinator.execute(callbackKey, async () =>
+      this.getProvider(provider).getProfile(code, flow, apiRedirectUri),
+    );
+
+    const token = this.security.randomOpaque(24);
+    const signature = this.security.signHmacSha256(`oauth-web-ref:${token}`);
+    const tokenHash = this.security.hashSha256(token);
+    const expiresAt = new Date(Date.now() + this.webRefTokenTtlMs);
+    const profileEnc = this.security.encrypt(JSON.stringify(profile));
+
+    await this.prisma.$executeRaw(
+      Prisma.sql`
+        INSERT INTO oauth_web_ref_token (
+          token_hash, provider, flow_type, app_origin, profile_enc, expires_at, created_at
+        ) VALUES (
+          ${tokenHash},
+          ${String(provider).toLowerCase()},
+          ${flow},
+          ${appOrigin},
+          ${profileEnc},
+          ${expiresAt},
+          NOW()
+        )
+      `,
+    );
+
+    return `${token}.${signature}`;
+  }
+
+  /**
+   * Redeems a `ref` issued by `beginWebRefCallback`: single-use consume, origin-bind
+   * to the initiating app, then finalize the flow (sets the refresh cookie via `res`
+   * and returns `{ accessToken }`) — byte-for-byte the same response as `callback/login`.
+   */
+  async redeemWebRef({
+    res,
+    ref,
+    provider,
+    locale,
+    ipAddress,
+    userAgent,
+    userId,
+    requestOrigin,
+    requestReferer,
+  }: {
+    res: Response;
+    ref: string;
+    provider: user_account_provider_52222e2ecb_enum;
+    locale: string;
+    ipAddress: string;
+    userAgent: string;
+    userId?: number;
+    requestOrigin?: string;
+    requestReferer?: string;
+  }) {
+    const parts = String(ref ?? '').split('.');
+    const token = parts[0];
+    const signature = parts[1];
+
+    if (!token || !signature) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    if (!this.security.verifyHmacSha256(`oauth-web-ref:${token}`, signature)) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    const tokenHash = this.security.hashSha256(token);
+    const rows = await this.prisma.$queryRaw<
+      Array<{ profile_enc: string; flow_type: string; app_origin: string | null }>
+    >(
+      Prisma.sql`
+        UPDATE oauth_web_ref_token
+        SET consumed_at = NOW()
+        WHERE token_hash = ${tokenHash}
+          AND provider = ${String(provider).toLowerCase()}
+          AND expires_at > NOW()
+          AND consumed_at IS NULL
+        RETURNING profile_enc, flow_type, app_origin
+      `,
+    );
+
+    const row = rows[0];
+    if (!row) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.alreadyProcessed', locale, 'This OAuth callback was already processed. Start the sign-in flow again.'),
+      );
+    }
+
+    const flow = row.flow_type as 'login' | 'register' | 'connect';
+
+    // Origin-bind at redeem (the backend callback's Origin was Microsoft, so the
+    // usual handleCallback binding can't run there). Skip only when no app origin
+    // was recorded (the hub's own "self" flow).
+    if (row.app_origin) {
+      const expectedOrigin = this.normalizeOrigin(row.app_origin);
+      const boundOrigin =
+        this.normalizeOrigin(requestOrigin) ?? this.normalizeOrigin(requestReferer);
+      if (!boundOrigin || expectedOrigin !== boundOrigin) {
+        throw new BadRequestException(
+          getLocaleText('oauth.callback.invalidState', locale, 'OAuth callback origin is invalid. Start the sign-in flow again.'),
+        );
+      }
+    }
+
+    if (flow === 'connect' && !userId) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    let profile: any;
+    try {
+      profile = JSON.parse(this.security.decrypt(row.profile_enc));
+    } catch {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    try {
+      return await this.finalizeCallback({
+        res,
+        locale,
+        ipAddress,
+        userAgent,
+        provider,
+        type: flow,
+        profile,
+        userId,
+        includeRefreshTokenInBody: false,
+      });
+    } catch (error) {
+      throw this.mapCallbackError(locale, provider, flow, error);
+    }
+  }
+
   private async finalizeCallback({
     res,
     locale,

package/src/oauth/providers/microsoft-entra-id.provider.ts

@@ -35,10 +35,22 @@ export class MicrosoftEntraIdProvider extends BaseOAuthProvider {
     return 'MICROSOFT-ENTRA-ID';
   }
 
+  // Fixed API callback used by the web flow so the ~2KB Entra `code` is received
+  // and exchanged server-side (never forwarded into a front-end app URL).
+  private static readonly API_CALLBACK_PATH = '/oauth/microsoft-entra-id/callback';
+
+  // Apps whose front-end callback pages know how to redeem the server-side bounce
+  // `ref`. Only these use the API bounce; every other web app (and mobile) keeps the
+  // legacy front-end redirect, so this change is additive and non-regressing. Add an
+  // app here once its callback pages handle `?ref=`. `self` is the hub (admin), which
+  // initiates Entra without a `redirectApp` and thus resolves to the sentinel `self`.
+  private static readonly API_BOUNCE_APPS = new Set(['class', 'self', 'training', 'partners']);
+
   private async loadConfig() {
     const settings = await this.setting.getSettingValues([
       'oauth-microsoft-entra-id-profile-id',
       'url',
+      'api-url',
     ]);
     const profileSlug = String(settings['oauth-microsoft-entra-id-profile-id'] ?? '').trim();
     if (!profileSlug) throw new BadRequestException('Microsoft Entra ID OAuth profile not configured.');
@@ -56,19 +68,47 @@ export class MicrosoftEntraIdProvider extends BaseOAuthProvider {
     if (!tenantId) {
       throw new BadRequestException('Microsoft Entra ID OAuth profile is missing tenant_id.');
     }
-    return { clientId, clientSecret, tenantId, baseUrl: String(settings['url'] ?? '') };
+    return {
+      clientId,
+      clientSecret,
+      tenantId,
+      baseUrl: String(settings['url'] ?? ''),
+      apiUrl: String(settings['api-url'] ?? ''),
+    };
   }
 
-  async getAuthUrl(callbackPath: string) {
-    const { clientId, tenantId, baseUrl } = await this.loadConfig();
+  /** Absolute redirect URI the web flow registers/exchanges against (the API). */
+  private buildApiRedirectUri(apiUrl: string) {
+    if (!String(apiUrl).trim()) {
+      throw new BadRequestException(
+        'Microsoft Entra ID OAuth requires the `api-url` setting for the web callback.',
+      );
+    }
+    return this.buildRedirectUri(apiUrl, MicrosoftEntraIdProvider.API_CALLBACK_PATH);
+  }
+
+  async getAuthUrl(
+    callbackPath: string,
+    flow?: 'login' | 'register' | 'connect',
+    app?: string,
+  ) {
+    const { clientId, tenantId, baseUrl, apiUrl } = await this.loadConfig();
     const settings = await this.setting.getSettingValues(['oauth-microsoft-entra-id-scopes']);
     const baseScopes: string[] = settings['oauth-microsoft-entra-id-scopes'] ?? ['openid', 'profile', 'email'];
     const scopes = baseScopes.includes('offline_access')
       ? baseScopes
       : [...baseScopes, 'offline_access'];
 
-    const redirectURI = this.buildRedirectUri(baseUrl, callbackPath);
-    const isConnectFlow = callbackPath.includes('/connect');
+    // Only apps that can redeem a `ref` bounce through the API (where the ~2KB code
+    // is exchanged server-side); every other web app and mobile keep the front-end
+    // callback, so this stays additive and non-regressing.
+    const useApiBounce = !!app && MicrosoftEntraIdProvider.API_BOUNCE_APPS.has(app);
+    const redirectURI = useApiBounce
+      ? this.buildApiRedirectUri(apiUrl)
+      : this.buildRedirectUri(baseUrl, callbackPath);
+    const isConnectFlow = useApiBounce
+      ? flow === 'connect'
+      : callbackPath.includes('/connect');
     const params = new URLSearchParams({
       client_id: clientId,
       redirect_uri: redirectURI,