@hed-hog/core 0.0.387 → 0.0.393

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

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+import { of, throwError } from 'rxjs';
+import { SecurityService } from '../security/security.service';
+import {
+  OAuthTokenBrokerError,
+  OAuthTokenBrokerService,
+} from './oauth-token-broker.service';
+
+const ENCRYPTION_SECRET = 'test-encryption-secret-0123456789';
+
+const makeSecurity = () =>
+  new SecurityService({
+    get: (key: string) =>
+      key === 'ENCRYPTION_SECRET' ? ENCRYPTION_SECRET : undefined,
+  } as any);
+
+const makeDeps = () => {
+  const security = makeSecurity();
+  const http = { post: jest.fn() };
+  const prisma = {
+    integration_profile: { findUnique: jest.fn() },
+    user_account: { findFirst: jest.fn(), update: jest.fn() },
+  };
+  const setting = { getSettingValues: jest.fn() };
+  return { security, http, prisma, setting };
+};
+
+const makeService = (deps = makeDeps()) => ({
+  service: new OAuthTokenBrokerService(
+    deps.http as any,
+    deps.setting as any,
+    deps.prisma as any,
+    deps.security,
+  ),
+  deps,
+});
+
+const PROVIDER = 'microsoft-entra-id';
+
+const primeConfig = (deps: ReturnType<typeof makeDeps>) => {
+  deps.setting.getSettingValues.mockResolvedValue({
+    'oauth-microsoft-entra-id-profile-id': 'ms-profile',
+  } as any);
+  deps.prisma.integration_profile.findUnique.mockResolvedValue({
+    slug: 'ms-profile',
+    config: {
+      client_id: 'CID',
+      client_secret: 'SECRET',
+      tenant_id: 'TENANT',
+    },
+    integration_provider: { slug: 'microsoft-entra-id-oauth' },
+  } as any);
+};
+
+describe('OAuthTokenBrokerService', () => {
+  let deps: ReturnType<typeof makeDeps>;
+  let service: OAuthTokenBrokerService;
+
+  beforeEach(() => {
+    const built = makeService();
+    deps = built.deps;
+    service = built.service;
+    primeConfig(deps);
+  });
+
+  const storedRefreshTokenRow = (security: SecurityService, plain: string) => ({
+    id: 42,
+    refresh_token: Buffer.from(security.encrypt(plain)),
+    scopes: 'openid,offline_access,Calendars.Read',
+    token_expires_at: new Date('2020-01-01T00:00:00Z'),
+  });
+
+  it('decrypts the stored refresh token, exchanges it, and returns an access token', async () => {
+    deps.prisma.user_account.findFirst.mockResolvedValue(
+      storedRefreshTokenRow(deps.security, 'refresh-original') as any,
+    );
+    deps.http.post.mockReturnValue(
+      of({
+        data: {
+          access_token: 'ACCESS-1',
+          refresh_token: 'refresh-rotated',
+          expires_in: 3600,
+        },
+      }) as any,
+    );
+
+    const result = await service.getAccessToken(1, PROVIDER);
+
+    expect(result.accessToken).toBe('ACCESS-1');
+    expect(result.expiresAt.getTime()).toBeGreaterThan(Date.now());
+
+    // The token endpoint received the DECRYPTED refresh token, not the ciphertext.
+    const [, body] = deps.http.post.mock.calls[0] as [string, string, unknown];
+    expect(body).toContain('grant_type=refresh_token');
+    expect(body).toContain('refresh_token=refresh-original');
+  });
+
+  it('persists the rotated refresh token re-encrypted (never in plaintext)', async () => {
+    deps.prisma.user_account.findFirst.mockResolvedValue(
+      storedRefreshTokenRow(deps.security, 'refresh-original') as any,
+    );
+    deps.http.post.mockReturnValue(
+      of({
+        data: {
+          access_token: 'ACCESS-1',
+          refresh_token: 'refresh-rotated',
+          expires_in: 3600,
+        },
+      }) as any,
+    );
+
+    await service.getAccessToken(1, PROVIDER);
+
+    expect(deps.prisma.user_account.update).toHaveBeenCalledTimes(1);
+    const updateArg = deps.prisma.user_account.update.mock.calls[0][0] as any;
+    const storedBuffer = updateArg.data.refresh_token as Buffer;
+    // Round-trips back to the rotated token, and is not the plaintext itself.
+    expect(storedBuffer.toString()).not.toContain('refresh-rotated');
+    expect(deps.security.decrypt(storedBuffer.toString())).toBe('refresh-rotated');
+  });
+
+  it('serves a cached access token without a second token exchange', async () => {
+    deps.prisma.user_account.findFirst.mockResolvedValue(
+      storedRefreshTokenRow(deps.security, 'refresh-original') as any,
+    );
+    deps.http.post.mockReturnValue(
+      of({
+        data: { access_token: 'ACCESS-1', expires_in: 3600 },
+      }) as any,
+    );
+
+    await service.getAccessToken(1, PROVIDER);
+    await service.getAccessToken(1, PROVIDER);
+
+    expect(deps.http.post).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws not_connected when the user has no linked account', async () => {
+    deps.prisma.user_account.findFirst.mockResolvedValue(null as any);
+
+    await expect(service.getAccessToken(1, PROVIDER)).rejects.toMatchObject({
+      reason: 'not_connected',
+    });
+  });
+
+  it('throws refresh_revoked on invalid_grant from the provider', async () => {
+    deps.prisma.user_account.findFirst.mockResolvedValue(
+      storedRefreshTokenRow(deps.security, 'refresh-original') as any,
+    );
+    deps.http.post.mockReturnValue(
+      throwError(() => ({
+        response: { data: { error: 'invalid_grant' }, status: 400 },
+      })) as any,
+    );
+
+    await expect(service.getAccessToken(1, PROVIDER)).rejects.toBeInstanceOf(
+      OAuthTokenBrokerError,
+    );
+    await expect(service.getAccessToken(1, PROVIDER)).rejects.toMatchObject({
+      reason: 'refresh_revoked',
+    });
+  });
+
+  it('parses granted scopes from the stored account', async () => {
+    deps.prisma.user_account.findFirst.mockResolvedValue({
+      scopes: 'openid, Calendars.Read  offline_access',
+    } as any);
+
+    const scopes = await service.getGrantedScopes(1, PROVIDER);
+    expect(scopes).toEqual(['openid', 'Calendars.Read', 'offline_access']);
+  });
+});

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;