@hed-hog/core 0.0.373 → 0.0.374

package/src/oauth/oauth.service.ts

@@ -25,9 +25,11 @@ import {
     OAuthCallbackInProgressError,
     OAuthProviderException,
 } from './oauth.errors';
+import { AppleProvider } from './providers/apple.provider';
 import { FacebookProvider } from './providers/facebook.provider';
 import { GithubProvider } from './providers/github.provider';
 import { GoogleProvider } from './providers/google.provider';
+import { LinkedinProvider } from './providers/linkedin.provider';
 import { MicrosoftEntraIdProvider } from './providers/microsoft-entra-id.provider';
 import { MicrosoftProvider } from './providers/microsoft.provider';
 
@@ -44,6 +46,10 @@ type HandleCallbackProps = {
   redirectUri?: string;
   state?: string;
   includeRefreshTokenInBody?: boolean;
+  /** Origin header of the request that hit the callback (used to bind web hub flows). */
+  requestOrigin?: string;
+  /** Referer header, used as a fallback when the Origin header is absent. */
+  requestReferer?: string;
 };
 
 @Injectable()
@@ -51,6 +57,8 @@ export class OAuthService {
   private readonly logger = new Logger(OAuthService.name);
   private providers: Map<string, OAuthProvider> = new Map();
   private readonly mobileOAuthStateTtlMs = 10 * 60 * 1000;
+  /** Sentinel app in the web state meaning "the OAuth hub handles this locally". */
+  private static readonly WEB_STATE_SELF_APP = 'self';
 
   constructor(
     google: GoogleProvider,
@@ -58,6 +66,8 @@ export class OAuthService {
     microsoft: MicrosoftProvider,
     github: GithubProvider,
     microsoftEntraId: MicrosoftEntraIdProvider,
+    apple: AppleProvider,
+    linkedin: LinkedinProvider,
     private readonly callbackCoordinator: OAuthCallbackCoordinatorService,
     @Inject(forwardRef(() => AuthService))
     private readonly auth: AuthService,
@@ -75,6 +85,8 @@ export class OAuthService {
     this.providers.set(microsoft.getProviderType(), microsoft);
     this.providers.set(github.getProviderType(), github);
     this.providers.set(microsoftEntraId.getProviderType(), microsoftEntraId);
+    this.providers.set(apple.getProviderType(), apple);
+    this.providers.set(linkedin.getProviderType(), linkedin);
   }
 
   async getAuthUrl(provider: user_account_provider_52222e2ecb_enum, callbackPath: string) {
@@ -94,7 +106,9 @@ export class OAuthService {
       throw new BadRequestException('Invalid mobile redirect URI.');
     }
 
-    const callbackPath = `/callback/${String(provider)}/login`;
+    // Flow-less callback to match the single registered redirect URI and the
+    // flow-less token exchange in each provider's getProfile.
+    const callbackPath = `/callback/${String(provider)}`;
     const authUrl = await this.getAuthUrl(provider, callbackPath);
     const flow = 'login';
     const { token, signature } = await this.issueMobileState(
@@ -108,6 +122,114 @@ export class OAuthService {
     return url.toString();
   }
 
+  /**
+   * Builds a provider auth URL for a browser (web) flow that may be initiated by an
+   * app other than the OAuth hub (the app configured in the `url` setting).
+   *
+   * When `redirectApp` resolves to a known origin (via the `app-urls` setting), a
+   * signed `state` (`hhweb.<app>.<flow>.<sig>`) is attached so the hub can forward
+   * the callback back to the initiating app and the backend can bind the code
+   * exchange to that origin. Without a resolvable `redirectApp`, the URL is returned
+   * unchanged — identical to the legacy hub-only behavior.
+   */
+  async getWebAuthUrl(
+    provider: user_account_provider_52222e2ecb_enum,
+    flow: 'login' | 'register' | 'connect',
+    redirectApp?: string,
+  ) {
+    // 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.
+    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 url = new URL(authUrl);
+    url.searchParams.set('state', this.buildWebState(app, flow));
+    return url.toString();
+  }
+
+  /**
+   * Resolves how the GitHub backend bounce should forward the browser. GitHub only
+   * supports a single registered callback URL (the API), so the provider always
+   * lands on the backend; this maps the signed web state to the initiating app's
+   * origin. Returns null for legacy hub-only flows (state carries just the flow).
+   */
+  async resolveWebForward(
+    state?: string,
+  ): Promise<{ origin: string | null; flow: 'login' | 'register' | 'connect' } | null> {
+    const web = this.parseWebState(state);
+    if (!web) {
+      return null;
+    }
+    return { origin: await this.resolveAppOrigin(web.app), flow: web.flow };
+  }
+
+  private sanitizeAppKey(app?: string): string | null {
+    const value = String(app ?? '').trim().toLowerCase();
+    return /^[a-z0-9][a-z0-9_-]{0,63}$/.test(value) ? value : null;
+  }
+
+  private buildWebState(app: string, flow: 'login' | 'register' | 'connect') {
+    const signature = this.security.signHmacSha256(`oauth-web-state:${app}:${flow}`);
+    return `hhweb.${app}.${flow}.${signature}`;
+  }
+
+  /** Parses and verifies a signed web-hub state. Returns null when invalid. */
+  private parseWebState(
+    state?: string,
+  ): { app: string; flow: 'login' | 'register' | 'connect' } | null {
+    if (!state || !state.startsWith('hhweb.')) {
+      return null;
+    }
+
+    const parts = state.split('.');
+    if (parts.length !== 4) {
+      return null;
+    }
+
+    const [, app, flow, signature] = parts;
+    if (!app || !flow || !signature) {
+      return null;
+    }
+
+    if (flow !== 'login' && flow !== 'register' && flow !== 'connect') {
+      return null;
+    }
+
+    if (!this.security.verifyHmacSha256(`oauth-web-state:${app}:${flow}`, signature)) {
+      return null;
+    }
+
+    return { app, flow };
+  }
+
+  /** Resolves an app key to its configured base origin via the `app-urls` setting. */
+  private async resolveAppOrigin(app: string): Promise<string | null> {
+    const settings = await this.setting.getSettingValues(['app-urls']);
+    const appUrls: string[] = Array.isArray(settings['app-urls']) ? settings['app-urls'] : [];
+    const entry = appUrls.find((item) => item.split('=')[0]?.trim() === app);
+    if (!entry) {
+      return null;
+    }
+    const value = entry.slice(entry.indexOf('=') + 1).trim();
+    return value || null;
+  }
+
+  private normalizeOrigin(value?: string): string | null {
+    if (!value) {
+      return null;
+    }
+    try {
+      return new URL(value).origin.toLowerCase();
+    } catch {
+      return null;
+    }
+  }
+
   async handleCallback({
     res,
     locale,
@@ -121,6 +243,8 @@ export class OAuthService {
     redirectUri,
     state,
     includeRefreshTokenInBody,
+    requestOrigin,
+    requestReferer,
   }: HandleCallbackProps) {
     try {
       this.logger.log(
@@ -141,6 +265,33 @@ export class OAuthService {
         );
       }
 
+      // Web hub flow: an app other than the OAuth hub started the flow and the hub
+      // forwarded the code here. Bind the code exchange to the initiating app's
+      // origin so a leaked/forwarded code cannot be redeemed from another origin.
+      const webState = this.parseWebState(state);
+      if (webState && (type === 'login' || type === 'register')) {
+        const expectedOrigin = this.normalizeOrigin(
+          await this.resolveAppOrigin(webState.app),
+        );
+        // Only bind cross-app forwards (the app resolves to a configured origin).
+        // The hub's own flow (app "self") resolves to nothing and runs locally.
+        if (expectedOrigin) {
+          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 (
         redirectUri &&
         !(await this.consumeMobileState(state, provider, redirectUri))
@@ -238,6 +389,8 @@ export class OAuthService {
     microsoft: 'oauth-microsoft-scopes',
     'microsoft-entra-id': 'oauth-microsoft-entra-id-scopes',
     microsoft_entra_id: 'oauth-microsoft-entra-id-scopes',
+    apple: 'oauth-apple-scopes',
+    linkedin: 'oauth-linkedin-scopes',
   };
 
   private static readonly PROVIDER_ENABLED_SLUGS: Record<string, string> = {
@@ -247,6 +400,8 @@ export class OAuthService {
     microsoft: 'oauth-microsoft-enabled',
     'microsoft-entra-id': 'oauth-microsoft-entra-id-enabled',
     microsoft_entra_id: 'oauth-microsoft-entra-id-enabled',
+    apple: 'oauth-apple-enabled',
+    linkedin: 'oauth-linkedin-enabled',
   };
 
   async isProviderEnabled(provider: user_account_provider_52222e2ecb_enum): Promise<boolean> {

package/src/oauth/providers/apple.provider.ts

@@ -0,0 +1,175 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { HttpService } from '@nestjs/axios';
+import { BadRequestException, forwardRef, Inject, Injectable } from '@nestjs/common';
+import * as jwt from 'jsonwebtoken';
+import { buildOAuthConfigFromIntegration } from '../../integration-profile/integration-profile.utils';
+import { SettingService } from '../../setting/setting.service';
+import { BaseOAuthProvider } from './abstract.provider';
+
+const APPLE_TOKEN_AUDIENCE = 'https://appleid.apple.com';
+// Apple accepts client_secret JWTs valid for up to 6 months; a short TTL is enough
+// since a fresh one is signed on every token exchange (no caching/rotation needed).
+const CLIENT_SECRET_TTL_SECONDS = 5 * 60;
+
+@Injectable()
+export class AppleProvider extends BaseOAuthProvider {
+
+  constructor(
+    http: HttpService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly setting: SettingService,
+    private readonly prisma: PrismaService,
+  ) {
+    super(http);
+  }
+
+  getProviderType() {
+    return 'APPLE';
+  }
+
+  private async loadConfig() {
+    const settings = await this.setting.getSettingValues([
+      'oauth-apple-profile-id',
+      'api-url',
+    ]);
+    const profileSlug = String(settings['oauth-apple-profile-id'] ?? '').trim();
+    if (!profileSlug) throw new BadRequestException('Apple OAuth profile not configured.');
+
+    const profile = await this.prisma.integration_profile.findUnique({
+      where: { slug: profileSlug },
+      include: { integration_provider: { select: { slug: true } } },
+    });
+    if (!profile) throw new BadRequestException('Apple OAuth profile not found.');
+
+    const { clientId, teamId, keyId, privateKey } = buildOAuthConfigFromIntegration(
+      profile.integration_provider.slug,
+      profile.config,
+    );
+    if (!teamId || !keyId || !privateKey) {
+      throw new BadRequestException(
+        'Apple OAuth profile is missing team_id, key_id or private_key.',
+      );
+    }
+
+    return {
+      clientId,
+      teamId,
+      keyId,
+      privateKey: this.normalizePrivateKey(privateKey),
+      apiUrl: String(settings['api-url'] ?? ''),
+    };
+  }
+
+  /** Accepts keys pasted with literal "\n" escapes, in addition to real line breaks. */
+  private normalizePrivateKey(raw: string): string {
+    const trimmed = raw.trim();
+    return trimmed.includes('\\n') ? trimmed.replace(/\\n/g, '\n') : trimmed;
+  }
+
+  /**
+   * Apple has no static client_secret: it must be a short-lived ES256 JWT signed
+   * with the private key tied to keyId, issued by teamId, for clientId (the
+   * Services ID). Built fresh per token exchange.
+   */
+  private buildClientSecret(
+    clientId: string,
+    teamId: string,
+    keyId: string,
+    privateKey: string,
+  ): string {
+    const now = Math.floor(Date.now() / 1000);
+    return jwt.sign(
+      {
+        iss: teamId,
+        iat: now,
+        exp: now + CLIENT_SECRET_TTL_SECONDS,
+        aud: APPLE_TOKEN_AUDIENCE,
+        sub: clientId,
+      },
+      privateKey,
+      { algorithm: 'ES256', keyid: keyId },
+    );
+  }
+
+  async getAuthUrl(_callbackPath: string) {
+    const { clientId, apiUrl } = await this.loadConfig();
+    const settings = await this.setting.getSettingValues(['oauth-apple-scopes']);
+    const scopes: string[] = settings['oauth-apple-scopes'] ?? ['name', 'email'];
+
+    // Apple only supports a single registered "Return URL" per app, at the backend
+    // (mirrors GitHub): the flow (login/register/connect) and initiating app travel
+    // in the signed OAuth state, never the path (see OAuthService.getWebAuthUrl).
+    const redirectURI = new URL('/oauth/apple/callback', apiUrl).toString();
+
+    const params = new URLSearchParams({
+      client_id: clientId,
+      redirect_uri: redirectURI,
+      response_type: 'code',
+      scope: scopes.join(' '),
+    });
+
+    // Apple mandates response_mode=form_post whenever `scope` is requested: the
+    // browser POSTs code/state to redirect_uri instead of a GET redirect. The
+    // dedicated POST /oauth/apple/callback route bounces it back to a GET so the
+    // rest of the pipeline (hub forwarding, code exchange) is identical to every
+    // other provider.
+    if (scopes.length > 0) {
+      params.set('response_mode', 'form_post');
+    }
+
+    return `https://appleid.apple.com/auth/authorize?${params}`;
+  }
+
+  async getProfile(code: string, _type?: string, redirectUri?: string) {
+    const { clientId, teamId, keyId, privateKey, apiUrl } = await this.loadConfig();
+
+    const resolvedRedirectUri =
+      redirectUri?.trim() || new URL('/oauth/apple/callback', apiUrl).toString();
+
+    const clientSecret = this.buildClientSecret(clientId, teamId, keyId, privateKey);
+
+    const token = await this.fetchToken({
+      code,
+      url: 'https://appleid.apple.com/auth/token',
+      clientId,
+      clientSecret,
+      redirectUri: resolvedRedirectUri,
+    });
+
+    // Apple has no profile REST endpoint: identity comes from the id_token JWT,
+    // delivered directly by Apple over this authenticated server-to-server call
+    // (never client-supplied), so decoding the payload without re-verifying the
+    // signature carries the same trust level as the TLS channel itself.
+    const claims = this.decodeIdTokenPayload(token.id_token);
+    const email = claims.email ? String(claims.email) : null;
+
+    return {
+      id: String(claims.sub ?? ''),
+      email,
+      // Apple only sends the user's name once, in the initial form_post body —
+      // not reachable from this GET-based hub bounce. Fall back to the email
+      // local-part so account creation (user.name is required) still works.
+      name: email ? email.split('@')[0] : 'Apple User',
+      picture: null,
+      oauth_tokens: {
+        access_token: token.access_token,
+        refresh_token: token.refresh_token,
+        expires_in: token.expires_in,
+        token_type: token.token_type,
+      },
+    };
+  }
+
+  private decodeIdTokenPayload(idToken: string): Record<string, unknown> {
+    const segments = String(idToken ?? '').split('.');
+    if (segments.length < 2) {
+      throw new BadRequestException('Apple OAuth response is missing a valid identity token.');
+    }
+    try {
+      const payload = Buffer.from(segments[1], 'base64url').toString('utf8');
+      return JSON.parse(payload);
+    } catch {
+      throw new BadRequestException('Unable to decode Apple identity token.');
+    }
+  }
+}

package/src/oauth/providers/facebook.provider.ts

@@ -59,11 +59,12 @@ export class FacebookProvider extends BaseOAuthProvider {
     return `https://www.facebook.com/v17.0/dialog/oauth?${params}`;
   }
 
-  async getProfile(code: string, type: string, redirectUri?: string): Promise<any> {
+  async getProfile(code: string, _type?: string, redirectUri?: string): Promise<any> {
     const { clientId, clientSecret, baseUrl } = await this.loadConfig();
 
+    // Single, flow-less callback per provider (the flow travels in the OAuth state).
     const resolvedRedirectUri =
-      redirectUri?.trim() || `${baseUrl}/oauth/facebook/callback/${type}`;
+      redirectUri?.trim() || `${baseUrl}/callback/facebook`;
 
     const token = await this.fetchToken({
       code,

package/src/oauth/providers/google.provider.ts

@@ -60,11 +60,12 @@ export class GoogleProvider extends BaseOAuthProvider {
     return `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
   }
 
-  async getProfile(code: string, type: string, redirectUri?: string) {
+  async getProfile(code: string, _type?: string, redirectUri?: string) {
     const { clientId, clientSecret, baseUrl } = await this.loadConfig();
 
+    // Single, flow-less callback per provider (the flow travels in the OAuth state).
     const resolvedRedirectUri =
-      redirectUri?.trim() || `${baseUrl}/callback/google/${type}`;
+      redirectUri?.trim() || `${baseUrl}/callback/google`;
 
     const token = await this.fetchToken({
       code,

package/src/oauth/providers/linkedin.provider.ts

@@ -0,0 +1,96 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { HttpService } from '@nestjs/axios';
+import { BadRequestException, forwardRef, Inject, Injectable } from '@nestjs/common';
+import { buildOAuthConfigFromIntegration } from '../../integration-profile/integration-profile.utils';
+import { SettingService } from '../../setting/setting.service';
+import { BaseOAuthProvider } from './abstract.provider';
+
+@Injectable()
+export class LinkedinProvider extends BaseOAuthProvider {
+
+  constructor(
+    http: HttpService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly setting: SettingService,
+    private readonly prisma: PrismaService,
+  ) {
+    super(http);
+  }
+
+  getProviderType() {
+    return 'LINKEDIN';
+  }
+
+  private async loadConfig() {
+    const settings = await this.setting.getSettingValues([
+      'oauth-linkedin-profile-id',
+      'url',
+    ]);
+    const profileSlug = String(settings['oauth-linkedin-profile-id'] ?? '').trim();
+    if (!profileSlug) throw new BadRequestException('LinkedIn OAuth profile not configured.');
+
+    const profile = await this.prisma.integration_profile.findUnique({
+      where: { slug: profileSlug },
+      include: { integration_provider: { select: { slug: true } } },
+    });
+    if (!profile) throw new BadRequestException('LinkedIn OAuth profile not found.');
+
+    const { clientId, clientSecret } = buildOAuthConfigFromIntegration(
+      profile.integration_provider.slug,
+      profile.config,
+    );
+    return { clientId, clientSecret, baseUrl: String(settings['url'] ?? '') };
+  }
+
+  async getAuthUrl(callbackPath: string) {
+    const { clientId, baseUrl } = await this.loadConfig();
+    const settings = await this.setting.getSettingValues(['oauth-linkedin-scopes']);
+    const scopes: string[] = settings['oauth-linkedin-scopes'] ?? ['openid', 'profile', 'email'];
+    const redirectURI = new URL(callbackPath, baseUrl).toString();
+
+    const params = new URLSearchParams({
+      client_id: clientId,
+      redirect_uri: redirectURI,
+      response_type: 'code',
+      scope: scopes.join(' '),
+    });
+
+    return `https://www.linkedin.com/oauth/v2/authorization?${params}`;
+  }
+
+  async getProfile(code: string, _type?: string, redirectUri?: string) {
+    const { clientId, clientSecret, baseUrl } = await this.loadConfig();
+
+    // Single, flow-less callback per provider (the flow travels in the OAuth state).
+    const resolvedRedirectUri =
+      redirectUri?.trim() || `${baseUrl}/callback/linkedin`;
+
+    const token = await this.fetchToken({
+      code,
+      url: 'https://www.linkedin.com/oauth/v2/accessToken',
+      clientId,
+      clientSecret,
+      redirectUri: resolvedRedirectUri,
+    });
+
+    // "Sign In with LinkedIn using OpenID Connect": a single OIDC userinfo call
+    // replaces the legacy /v2/me + /v2/emailAddress two-request dance.
+    const profile = await this.fetchProfile(
+      token.access_token,
+      'https://api.linkedin.com/v2/userinfo',
+    );
+
+    return {
+      id: profile.sub,
+      email: profile.email,
+      name: profile.name,
+      picture: profile.picture,
+      oauth_tokens: {
+        access_token: token.access_token,
+        refresh_token: token.refresh_token,
+        expires_in: token.expires_in,
+        token_type: token.token_type,
+      },
+    };
+  }
+}

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

@@ -96,7 +96,7 @@ export class MicrosoftEntraIdProvider extends BaseOAuthProvider {
       const settings = await this.setting.getSettingValues(['oauth-microsoft-entra-id-scopes']);
       const scopes: string[] = settings['oauth-microsoft-entra-id-scopes'] ?? [];
       resolvedRedirectUri =
-        redirectUri?.trim() || this.buildRedirectUri(baseUrl, `/callback/microsoft-entra-id/${type}`);
+        redirectUri?.trim() || this.buildRedirectUri(baseUrl, '/callback/microsoft-entra-id');
 
       this.logger.log(
         `OAuth token exchange started: provider=MICROSOFT-ENTRA-ID type=${type} redirectUri=${resolvedRedirectUri} hasCode=${code ? 'yes' : 'no'} codeLength=${code?.length ?? 0}`,

package/src/oauth/providers/microsoft.provider.ts

@@ -60,11 +60,12 @@ export class MicrosoftProvider extends BaseOAuthProvider {
     return `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?${params}`;
   }
 
-  async getProfile(code: string, type: string, redirectUri?: string): Promise<any> {
+  async getProfile(code: string, _type?: string, redirectUri?: string): Promise<any> {
     const { clientId, clientSecret, baseUrl } = await this.loadConfig();
 
+    // Single, flow-less callback per provider (the flow travels in the OAuth state).
     const resolvedRedirectUri =
-      redirectUri?.trim() || `${baseUrl}/callback/microsoft/${type}`;
+      redirectUri?.trim() || `${baseUrl}/callback/microsoft`;
 
     const token = await this.fetchToken({
       code,

package/src/pdf/pdf.service.ts

@@ -21,6 +21,17 @@ export interface PdfGenerateOptions {
   height?: string;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Parses a CSS pixel size string (e.g. '1600px') into a number, falling back when absent/unparsable. */
+function parsePxSize(value: string | undefined, fallback: number): number {
+  if (!value) return fallback;
+  const match = /^([\d.]+)px$/.exec(value.trim());
+  return match ? Math.round(Number(match[1])) : fallback;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Service
 // ─────────────────────────────────────────────────────────────────────────────
@@ -161,8 +172,15 @@ export class PdfService {
 
       const page = await browser.newPage();
 
-      // A4 viewport for proper page layout
-      await page.setViewportSize({ width: 794, height: 1123 });
+      // Viewport must match the requested PDF page size (`width`/`height`),
+      // otherwise CSS vw/vh units in the HTML are computed against the wrong
+      // box and everything laid out with them (e.g. certificate fields) ends
+      // up misaligned once Chromium scales the page to the paper size. Falls
+      // back to the A4 default (96dpi 210x297mm) when no explicit size is given.
+      await page.setViewportSize({
+        width: parsePxSize(options.width, 794),
+        height: parsePxSize(options.height, 1123),
+      });
       await page.setContent(html, { waitUntil: 'networkidle' });
 
       const pdfBuffer = await page.pdf(