@hed-hog/core 0.0.387 → 0.0.390

package/src/oauth/oauth-token-broker.service.ts

@@ -0,0 +1,363 @@
+import {
+  PrismaService,
+  user_account_provider_52222e2ecb_enum,
+} from '@hed-hog/api-prisma';
+import { HttpService } from '@nestjs/axios';
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { lastValueFrom } from 'rxjs';
+import { buildOAuthConfigFromIntegration } from '../integration-profile/integration-profile.utils';
+import { SecurityService } from '../security/security.service';
+import { SettingService } from '../setting/setting.service';
+
+/**
+ * Reasons a brokered access token could not be produced. Consumers (e.g. the
+ * `microsoft` library) map these to HTTP responses so the UI can react — most
+ * importantly, `not_connected`/`refresh_revoked` should prompt the user to
+ * (re)connect their account, and `missing_scope` to re-consent.
+ */
+export type OAuthTokenBrokerReason =
+  | 'not_connected'
+  | 'refresh_revoked'
+  | 'missing_scope'
+  | 'provider_not_configured'
+  | 'upstream_failure';
+
+export class OAuthTokenBrokerError extends Error {
+  constructor(
+    readonly reason: OAuthTokenBrokerReason,
+    message: string,
+    readonly provider: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'OAuthTokenBrokerError';
+  }
+}
+
+export interface BrokeredAccessToken {
+  accessToken: string;
+  /** Absolute expiry of the access token. */
+  expiresAt: Date;
+  /** Scopes granted to the stored refresh token (best-effort, from `user_account.scopes`). */
+  scopes: string[];
+}
+
+interface ProviderTokenConfig {
+  tokenUrl: string;
+  clientId: string;
+  clientSecret: string;
+}
+
+interface CacheEntry {
+  accessToken: string;
+  expiresAt: Date;
+  scopes: string[];
+}
+
+/**
+ * Exchanges a user's stored (encrypted) OAuth **refresh token** for a fresh
+ * **access token**, so the backend can call provider APIs (Microsoft Graph,
+ * Google, ...) on that user's behalf — the "delegated" access mode.
+ *
+ * The refresh token is written by {@link OAuthService} during login/connect
+ * (encrypted with {@link SecurityService.encrypt} and stored as bytes in
+ * `user_account.refresh_token`); this service reads it back, decrypts it, runs
+ * a `grant_type=refresh_token` exchange, persists the rotated refresh token,
+ * and caches the access token in memory until shortly before it expires.
+ *
+ * It intentionally reuses the SAME `integration_profile` credentials already
+ * configured for OAuth login — no new provider, table, or setting is introduced.
+ */
+@Injectable()
+export class OAuthTokenBrokerService {
+  private readonly logger = new Logger(OAuthTokenBrokerService.name);
+
+  /** access-token cache keyed by `${provider}:${userId}`. */
+  private readonly cache = new Map<string, CacheEntry>();
+
+  /** Refresh a bit early so an in-flight request never rides an about-to-expire token. */
+  private static readonly EXPIRY_SKEW_MS = 60 * 1000;
+
+  constructor(
+    private readonly http: HttpService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly setting: SettingService,
+    private readonly prisma: PrismaService,
+    private readonly security: SecurityService,
+  ) {}
+
+  /** Normalizes a provider to the enum form stored in `user_account.provider`. */
+  private toAccountProvider(
+    provider: string,
+  ): user_account_provider_52222e2ecb_enum {
+    return String(provider)
+      .toLowerCase()
+      .replace(/-/g, '_') as user_account_provider_52222e2ecb_enum;
+  }
+
+  /** Setting slug that points at the integration profile for this provider. */
+  private profileSettingSlug(provider: string): string | null {
+    switch (String(provider).toLowerCase().replace(/_/g, '-')) {
+      case 'microsoft-entra-id':
+        return 'oauth-microsoft-entra-id-profile-id';
+      case 'microsoft':
+        return 'oauth-microsoft-profile-id';
+      case 'google':
+        return 'oauth-google-profile-id';
+      default:
+        return null;
+    }
+  }
+
+  private async resolveProviderConfig(
+    provider: string,
+  ): Promise<ProviderTokenConfig> {
+    const settingSlug = this.profileSettingSlug(provider);
+    if (!settingSlug) {
+      throw new OAuthTokenBrokerError(
+        'provider_not_configured',
+        `Token broker does not support provider "${provider}".`,
+        provider,
+      );
+    }
+
+    const settings = await this.setting.getSettingValues([settingSlug]);
+    const profileSlug = String(settings[settingSlug] ?? '').trim();
+    if (!profileSlug) {
+      throw new OAuthTokenBrokerError(
+        'provider_not_configured',
+        `OAuth profile for "${provider}" is not configured.`,
+        provider,
+      );
+    }
+
+    const profile = await this.prisma.integration_profile.findUnique({
+      where: { slug: profileSlug },
+      include: { integration_provider: { select: { slug: true } } },
+    });
+    if (!profile) {
+      throw new OAuthTokenBrokerError(
+        'provider_not_configured',
+        `OAuth profile "${profileSlug}" for "${provider}" was not found.`,
+        provider,
+      );
+    }
+
+    const { clientId, clientSecret, tenantId } = buildOAuthConfigFromIntegration(
+      profile.integration_provider.slug,
+      profile.config,
+    );
+
+    const normalized = String(provider).toLowerCase().replace(/_/g, '-');
+    let tokenUrl: string;
+    if (normalized === 'microsoft-entra-id') {
+      if (!tenantId) {
+        throw new OAuthTokenBrokerError(
+          'provider_not_configured',
+          'Microsoft Entra ID OAuth profile is missing tenant_id.',
+          provider,
+        );
+      }
+      tokenUrl = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;
+    } else if (normalized === 'microsoft') {
+      tokenUrl = 'https://login.microsoftonline.com/common/oauth2/v2.0/token';
+    } else {
+      // google
+      tokenUrl = 'https://oauth2.googleapis.com/token';
+    }
+
+    return { tokenUrl, clientId, clientSecret };
+  }
+
+  private async loadUserAccount(userId: number, provider: string) {
+    const account = await this.prisma.user_account.findFirst({
+      where: {
+        user_id: userId,
+        provider: this.toAccountProvider(provider),
+      },
+      select: {
+        id: true,
+        refresh_token: true,
+        scopes: true,
+        token_expires_at: true,
+      },
+    });
+
+    if (!account || !account.refresh_token) {
+      throw new OAuthTokenBrokerError(
+        'not_connected',
+        `User ${userId} has no connected "${provider}" account.`,
+        provider,
+      );
+    }
+
+    return account;
+  }
+
+  private parseScopes(scopes?: string | null): string[] {
+    return String(scopes ?? '')
+      .split(/[\s,]+/)
+      .map((scope) => scope.trim())
+      .filter(Boolean);
+  }
+
+  /** Scopes granted to the stored refresh token, from `user_account.scopes`. */
+  async getGrantedScopes(userId: number, provider: string): Promise<string[]> {
+    const account = await this.prisma.user_account.findFirst({
+      where: { user_id: userId, provider: this.toAccountProvider(provider) },
+      select: { scopes: true },
+    });
+    return this.parseScopes(account?.scopes);
+  }
+
+  /** Whether the user has this provider connected with a usable refresh token. */
+  async isConnected(userId: number, provider: string): Promise<boolean> {
+    const account = await this.prisma.user_account.findFirst({
+      where: { user_id: userId, provider: this.toAccountProvider(provider) },
+      select: { refresh_token: true },
+    });
+    return Boolean(account?.refresh_token);
+  }
+
+  private cacheKey(userId: number, provider: string): string {
+    return `${String(provider).toLowerCase()}:${userId}`;
+  }
+
+  /**
+   * Returns a fresh access token for the user, refreshing (and rotating the
+   * stored refresh token) when the cache is cold or about to expire.
+   *
+   * @throws {OAuthTokenBrokerError} with a typed `reason` on any failure.
+   */
+  async getAccessToken(
+    userId: number,
+    provider: string,
+  ): Promise<BrokeredAccessToken> {
+    const key = this.cacheKey(userId, provider);
+    const cached = this.cache.get(key);
+    if (
+      cached &&
+      cached.expiresAt.getTime() - Date.now() > OAuthTokenBrokerService.EXPIRY_SKEW_MS
+    ) {
+      return { ...cached };
+    }
+
+    const [config, account] = await Promise.all([
+      this.resolveProviderConfig(provider),
+      this.loadUserAccount(userId, provider),
+    ]);
+
+    let decryptedRefreshToken: string;
+    try {
+      decryptedRefreshToken = this.security.decrypt(account.refresh_token.toString());
+    } catch (error) {
+      throw new OAuthTokenBrokerError(
+        'refresh_revoked',
+        `Failed to decrypt stored refresh token for "${provider}".`,
+        provider,
+        error,
+      );
+    }
+
+    const grantedScopes = this.parseScopes(account.scopes);
+    const scopeParam = grantedScopes.includes('offline_access')
+      ? grantedScopes
+      : [...grantedScopes, 'offline_access'];
+
+    const body = new URLSearchParams({
+      client_id: config.clientId,
+      client_secret: config.clientSecret,
+      grant_type: 'refresh_token',
+      refresh_token: decryptedRefreshToken,
+    });
+    if (scopeParam.length > 1) {
+      body.set('scope', scopeParam.join(' '));
+    }
+
+    let token: {
+      access_token: string;
+      refresh_token?: string;
+      expires_in?: number;
+      scope?: string;
+    };
+    try {
+      const response = await lastValueFrom(
+        this.http.post(config.tokenUrl, body.toString(), {
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        }),
+      );
+      token = response.data;
+    } catch (error: any) {
+      const providerError = error?.response?.data?.error;
+      if (providerError === 'invalid_grant') {
+        // Refresh token revoked/expired — the user must reconnect.
+        this.cache.delete(key);
+        throw new OAuthTokenBrokerError(
+          'refresh_revoked',
+          `Refresh token for "${provider}" is no longer valid. Reconnect the account.`,
+          provider,
+          error,
+        );
+      }
+      this.logger.warn(
+        `Token refresh failed: provider=${provider} userId=${userId} error=${providerError ?? error?.message ?? 'unknown'}`,
+      );
+      throw new OAuthTokenBrokerError(
+        'upstream_failure',
+        `Unable to refresh "${provider}" access token.`,
+        provider,
+        error,
+      );
+    }
+
+    if (!token?.access_token) {
+      throw new OAuthTokenBrokerError(
+        'upstream_failure',
+        `Provider "${provider}" returned no access token.`,
+        provider,
+      );
+    }
+
+    const expiresAt = new Date(
+      Date.now() + (token.expires_in ? token.expires_in * 1000 : 3600 * 1000),
+    );
+    const resolvedScopes = token.scope
+      ? this.parseScopes(token.scope)
+      : grantedScopes;
+
+    // Persist the rotated refresh token so the next call starts from the newest
+    // one (Microsoft rotates refresh tokens on every exchange).
+    if (token.refresh_token && token.refresh_token !== decryptedRefreshToken) {
+      try {
+        const encrypted = this.security.encrypt(token.refresh_token);
+        await this.prisma.user_account.update({
+          where: { id: account.id },
+          data: {
+            refresh_token: Buffer.from(encrypted),
+            token_expires_at: expiresAt,
+            ...(token.scope ? { scopes: resolvedScopes.join(',') } : {}),
+          },
+        });
+      } catch (error) {
+        // A persistence failure must not fail the request — the access token is
+        // already valid; log and continue (next refresh reuses the old token).
+        this.logger.warn(
+          `Failed to persist rotated refresh token: provider=${provider} userId=${userId} error=${error instanceof Error ? error.message : 'unknown'}`,
+        );
+      }
+    }
+
+    const entry: CacheEntry = {
+      accessToken: token.access_token,
+      expiresAt,
+      scopes: resolvedScopes,
+    };
+    this.cache.set(key, entry);
+    return { ...entry };
+  }
+
+  /** Drops any cached access token for a user/provider (e.g. after disconnect). */
+  invalidate(userId: number, provider: string): void {
+    this.cache.delete(this.cacheKey(userId, provider));
+  }
+}

package/src/oauth/oauth.module.ts

@@ -10,6 +10,7 @@ import { SecurityModule } from '../security/security.module';
 import { TokenModule } from '../token/token.module';
 import { UserModule } from '../user/user.module';
 import { OAuthCallbackCoordinatorService } from './oauth-callback-coordinator.service';
+import { OAuthTokenBrokerService } from './oauth-token-broker.service';
 import { OAuthController } from './oauth.controller';
 import { OAuthService } from './oauth.service';
 import { AppleProvider } from './providers/apple.provider';
@@ -36,6 +37,7 @@ import { MicrosoftProvider } from './providers/microsoft.provider';
   controllers: [OAuthController],
   providers: [
     OAuthCallbackCoordinatorService,
+    OAuthTokenBrokerService,
     OAuthService,
     GoogleProvider,
     FacebookProvider,
@@ -45,6 +47,6 @@ import { MicrosoftProvider } from './providers/microsoft.provider';
     AppleProvider,
     LinkedinProvider,
   ],
-  exports: [OAuthService],
+  exports: [OAuthService, OAuthTokenBrokerService],
 })
 export class OAuthModule {}

package/src/oauth/oauth.service.ts

@@ -50,6 +50,8 @@ type HandleCallbackProps = {
   requestOrigin?: string;
   /** Referer header, used as a fallback when the Origin header is absent. */
   requestReferer?: string;
+  /** App key that initiated the flow (decoded from the signed web state), used for per-app email branding. */
+  app?: string;
 };
 
 @Injectable()
@@ -338,6 +340,7 @@ export class OAuthService {
             profile,
             userId,
             includeRefreshTokenInBody: true,
+            app: webState?.app,
           });
         })) as { accessToken: string; refreshToken?: string };
 
@@ -365,6 +368,7 @@ export class OAuthService {
           profile,
           userId,
           includeRefreshTokenInBody,
+          app: webState?.app,
         });
 
         this.logger.log(
@@ -741,12 +745,13 @@ export class OAuthService {
     profile,
     userId,
     includeRefreshTokenInBody,
+    app,
   }: Omit<HandleCallbackProps, 'code' | 'email' | 'redirectUri' | 'state'> & { profile: any }) {
     switch (type) {
       case 'login':
         return this.handleLogin(res, locale, ipAddress, userAgent, provider, profile, includeRefreshTokenInBody);
       case 'register':
-        return this.handleRegister(res, locale, ipAddress, userAgent, provider, profile, includeRefreshTokenInBody);
+        return this.handleRegister(res, locale, ipAddress, userAgent, provider, profile, includeRefreshTokenInBody, app);
       case 'connect':
         return this.handleConnect(res, locale, ipAddress, userAgent, provider, profile, userId, includeRefreshTokenInBody);
       default:
@@ -896,7 +901,7 @@ export class OAuthService {
     }
   }
 
-  private async handleRegister(res: Response, locale: string, ipAddress: string, userAgent: string, provider: user_account_provider_52222e2ecb_enum, profile: any, includeRefreshTokenInBody?: boolean) {
+  private async handleRegister(res: Response, locale: string, ipAddress: string, userAgent: string, provider: user_account_provider_52222e2ecb_enum, profile: any, includeRefreshTokenInBody?: boolean, app?: string) {
     const existingUser = await this.prisma.user_identifier.findFirst({
       where: {
         type: 'email',
@@ -959,6 +964,7 @@ export class OAuthService {
       email: profile.email,
       slug: 'auth-sign-up',
       variables: { name: profile.name },
+      app,
     });
 
     const pictureURL = profile.picture?.data?.url || profile.picture;

package/src/pdf/pdf.service.ts

@@ -229,6 +229,81 @@ export class PdfService {
     }
   }
 
+  // ── HTML → PNG image ──────────────────────────────────────────────────────
+
+  /**
+   * Renders an HTML string to a PNG image buffer via a Playwright/Chromium
+   * screenshot. Shares the same layout contract as {@link generatePdfFromHtml}
+   * (the viewport matches `width`/`height`), so the image is a pixel-faithful
+   * preview of what the PDF would produce for the same HTML — used for
+   * certificate thumbnails on the web/app.
+   */
+  async generateImageFromHtml(html: string, options: PdfGenerateOptions = {}): Promise<Buffer> {
+    const executablePath = this.configService.get<string>('CHROMIUM_EXECUTABLE_PATH');
+    const noSandbox = this.configService.get<string>('CHROMIUM_NO_SANDBOX') === 'true';
+
+    const launchArgs = noSandbox
+      ? ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
+      : [];
+
+    const width = parsePxSize(options.width, 794);
+    const height = parsePxSize(options.height, 1123);
+
+    let browser: any = null;
+
+    try {
+      const importPlaywright = new Function(
+        'moduleName',
+        'return import(moduleName);',
+      ) as (moduleName: string) => Promise<any>;
+
+      const playwright = await importPlaywright('playwright');
+
+      browser = await playwright.chromium.launch({
+        headless: true,
+        ...(executablePath ? { executablePath } : {}),
+        args: launchArgs,
+      });
+
+      const page = await browser.newPage();
+      await page.setViewportSize({ width, height });
+      await page.setContent(html, { waitUntil: 'networkidle' });
+
+      const imageBuffer = await page.screenshot({
+        type: 'png',
+        clip: { x: 0, y: 0, width, height },
+      });
+
+      return Buffer.from(imageBuffer);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? (error.stack ?? errorMessage) : String(error);
+
+      const missingRuntime =
+        /Cannot find package ['"]playwright['"]|Cannot find module ['"]playwright['"]|Executable doesn't exist|browserType\.launch|Failed to launch|Please run the following command/i.test(
+          errorMessage,
+        );
+
+      this.logger.error(`Image generation failed. ${errorMessage}`, errorStack);
+
+      if (missingRuntime) {
+        throw new InternalServerErrorException(
+          'Playwright runtime is not available. Run `pnpm --filter api run playwright:install` in the API environment.',
+        );
+      }
+
+      throw new InternalServerErrorException(`Image generation failed: ${errorMessage}`);
+    } finally {
+      if (browser) {
+        try {
+          await browser.close();
+        } catch {
+          // Ignore close errors
+        }
+      }
+    }
+  }
+
   // ── Template engine ───────────────────────────────────────────────────────
 
   /**

package/src/presence/presence.controller.ts

@@ -0,0 +1,29 @@
+import { User } from '@hed-hog/api';
+import { Controller, Get, Post, Query } from '@nestjs/common';
+import { PresenceService } from './presence.service';
+
+/**
+ * Presence endpoints — authenticated (no @Role): any signed-in user may send
+ * their own heartbeat and read presence for a set of users.
+ */
+@Controller('presence')
+export class PresenceController {
+  constructor(private readonly presence: PresenceService) {}
+
+  /** Browser heartbeat: marks the signed-in user as online in the app. */
+  @Post('heartbeat')
+  async heartbeat(@User() user: any) {
+    await this.presence.heartbeat(Number(user?.id) || 0);
+    return { ok: true };
+  }
+
+  /** Combined presence for `userIds` (comma-separated). */
+  @Get()
+  async getStatuses(@Query('userIds') userIds?: string) {
+    const ids = String(userIds ?? '')
+      .split(',')
+      .map((s) => Number(s.trim()))
+      .filter((n) => Number.isInteger(n) && n > 0);
+    return this.presence.getStatuses(ids);
+  }
+}

package/src/presence/presence.listener.ts

@@ -0,0 +1,53 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Cron } from '@nestjs/schedule';
+import { RealtimeService } from '../realtime/realtime.service';
+import { REALTIME_EVENTS } from '../realtime/realtime.gateway';
+import { PresenceService } from './presence.service';
+
+/**
+ * Bridges the generic realtime layer to presence: a live socket IS the app
+ * heartbeat. On (first) connect the user goes online and the change is pushed;
+ * while connected, a cron keeps the heartbeat fresh (so it never lapses under
+ * the 60s window); on disconnect the new status is pushed.
+ */
+@Injectable()
+export class PresenceListener {
+  private readonly logger = new Logger(PresenceListener.name);
+
+  constructor(
+    private readonly presence: PresenceService,
+    private readonly realtime: RealtimeService,
+  ) {}
+
+  @OnEvent(REALTIME_EVENTS.userConnected)
+  async onConnected(payload: { userId: number; firstConnection: boolean }) {
+    await this.presence.heartbeat(payload.userId);
+    // Only push when the user actually transitioned to online (first socket).
+    if (payload.firstConnection) {
+      await this.presence.pushStatus(payload.userId).catch(() => undefined);
+    }
+  }
+
+  @OnEvent(REALTIME_EVENTS.userDisconnected)
+  async onDisconnected(payload: { userId: number; remainingLocalSockets: number }) {
+    // Recompute/push; if the user still has sockets elsewhere the heartbeat keeps
+    // them online, otherwise they go offline once the heartbeat window elapses.
+    if (payload.remainingLocalSockets === 0) {
+      await this.presence.pushStatus(payload.userId).catch(() => undefined);
+    }
+  }
+
+  /**
+   * Keeps the app heartbeat fresh for every locally-connected user. A connected
+   * socket must stay "online" past the 60s heartbeat window, so refresh every
+   * 30s. Silent (no push) — nothing changed.
+   */
+  @Cron('*/30 * * * * *')
+  async refreshHeartbeats() {
+    const userIds = this.realtime.getLocallyConnectedUserIds();
+    for (const userId of userIds) {
+      await this.presence.heartbeat(userId).catch(() => undefined);
+    }
+  }
+}

package/src/presence/presence.module.ts

@@ -0,0 +1,19 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { forwardRef, Module } from '@nestjs/common';
+import { RealtimeModule } from '../realtime/realtime.module';
+import { SettingModule } from '../setting/setting.module';
+import { PresenceController } from './presence.controller';
+import { PresenceListener } from './presence.listener';
+import { PresenceService } from './presence.service';
+
+@Module({
+  imports: [
+    forwardRef(() => PrismaModule),
+    forwardRef(() => SettingModule),
+    forwardRef(() => RealtimeModule),
+  ],
+  controllers: [PresenceController],
+  providers: [PresenceService, PresenceListener],
+  exports: [PresenceService],
+})
+export class PresenceModule {}