Implement OAuth 2.0 Dynamic Client Registration (RFC 7591) (#18608)

## Summary
This PR implements OAuth 2.0 Dynamic Client Registration (RFC 7591) and
OAuth 2.0 Protected Resource Metadata (RFC 9728) support, enabling
third-party applications to dynamically register as OAuth clients
without manual configuration.

## Key Changes

### OAuth Dynamic Client Registration
- **New Controller**: `OAuthRegistrationController` at `POST
/oauth/register` endpoint
  - Validates client metadata according to RFC 7591 specifications
  - Enforces PKCE-only public client model (no client secrets)
- Supports only `authorization_code` grant type and `code` response type
  - Rate limits registrations to 10 per hour per IP address
  - Returns `client_id` and registration metadata in response

- **Input Validation**: `OAuthRegisterInput` DTO with constraints on:
  - Client name (max 256 chars)
  - Redirect URIs (max 20, validated for security)
  - Grant types, response types, scopes, and auth methods
  - Logo and client URIs (max 2048 chars)

- **Discovery Endpoint Update**: Added `registration_endpoint` to OAuth
discovery metadata

### Stale Registration Cleanup
- **Cleanup Service**: Automatically removes OAuth-only registrations
older than 30 days that have no active installations
- **Cron Job**: Runs daily at 02:30 AM UTC with batch processing (100
records per batch)
- **CLI Command**: `cron:stale-registration-cleanup` to manually trigger
cleanup

### MCP (Model Context Protocol) Authentication
- **New Guard**: `McpAuthGuard` implements RFC 9728 compliance
  - Wraps JWT authentication with proper error responses
- Returns `WWW-Authenticate` header with protected resource metadata URL
on 401
  - Enables OAuth-protected MCP endpoints

### Protected Resource Metadata
- **New Endpoint**: `GET /.well-known/oauth-protected-resource` (RFC
9728)
  - Advertises MCP resource as OAuth-protected
  - Lists supported scopes and bearer token methods
  - Enables OAuth clients to discover authorization requirements

### Application Registration Updates
- **New Source Type**: `OAUTH_ONLY` enum value for OAuth-only
registrations
- **Install Service**: Skips artifact installation for OAuth-only apps
(no code artifacts)

### Frontend Updates
- **Authorization Page**: Support both snake_case (standard OAuth) and
camelCase (legacy) query parameters
  - `client_id` / `clientId`
  - `code_challenge` / `codeChallenge`
  - `redirect_uri` / `redirectUrl`

## Implementation Details

- **Rate Limiting**: Uses token bucket algorithm with 10 registrations
per 3,600,000ms window per IP
- **Scope Validation**: Requested scopes are capped to allowed OAuth
scopes; defaults to all scopes if not specified
- **Redirect URI Validation**: Uses existing `validateRedirectUri`
utility for security
- **Cache Headers**: Registration responses include `Cache-Control:
no-store` and `Pragma: no-cache`
- **Batch Processing**: Cleanup operations process 100 records at a time
to avoid memory issues
- **Grace Period**: 30-day grace period before cleanup to allow time for
client activation

https://claude.ai/code/session_01PxcuWFFRuXMASMaMGTLYk2

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: github-actions <github-actions@twenty.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

packages/twenty-server/src/engine/core-modules/application/application-install/application-install.service.ts

@@ -65,6 +65,17 @@ export class ApplicationInstallService {
       return true;
     }
 
+    if (
+      appRegistration.sourceType ===
+      ApplicationRegistrationSourceType.OAUTH_ONLY
+    ) {
+      this.logger.log(
+        `Skipping install for OAUTH_ONLY app ${appRegistration.universalIdentifier} (OAuth-only clients have no code artifacts)`,
+      );
+
+      return true;
+    }
+
     const lockKey = `app-install:${params.workspaceId}:${appRegistration.universalIdentifier}`;
 
     return this.cacheLockService.withLock(

packages/twenty-server/src/engine/core-modules/application/application-oauth/application-oauth.module.ts

@@ -3,14 +3,17 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { AppTokenEntity } from 'src/engine/core-modules/app-token/app-token.entity';
 import { ApplicationInstallModule } from 'src/engine/core-modules/application/application-install/application-install.module';
+import { ApplicationRegistrationEntity } from 'src/engine/core-modules/application/application-registration/application-registration.entity';
 import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
 import { ApplicationModule as ApplicationCoreModule } from 'src/engine/core-modules/application/application.module';
 import { ApplicationOAuthResolver } from 'src/engine/core-modules/application/application-oauth/application-oauth.resolver';
 import { OAuthDiscoveryController } from 'src/engine/core-modules/application/application-oauth/controllers/oauth-discovery.controller';
+import { OAuthRegistrationController } from 'src/engine/core-modules/application/application-oauth/controllers/oauth-registration.controller';
 import { OAuthTokenController } from 'src/engine/core-modules/application/application-oauth/controllers/oauth-token.controller';
 import { OAuthService } from 'src/engine/core-modules/application/application-oauth/oauth.service';
 import { ApplicationRegistrationModule } from 'src/engine/core-modules/application/application-registration/application-registration.module';
 import { TokenModule } from 'src/engine/core-modules/auth/token/token.module';
+import { DomainServerConfigModule } from 'src/engine/core-modules/domain/domain-server-config/domain-server-config.module';
 import { FeatureFlagModule } from 'src/engine/core-modules/feature-flag/feature-flag.module';
 import { ThrottlerModule } from 'src/engine/core-modules/throttler/throttler.module';
 import { TwentyConfigModule } from 'src/engine/core-modules/twenty-config/twenty-config.module';
@@ -23,19 +26,25 @@ import { WorkspaceCacheStorageModule } from 'src/engine/workspace-cache-storage/
     TypeOrmModule.forFeature([
       AppTokenEntity,
       ApplicationEntity,
+      ApplicationRegistrationEntity,
       UserWorkspaceEntity,
     ]),
     ApplicationRegistrationModule,
     ApplicationCoreModule,
     ApplicationInstallModule,
     TokenModule,
+    DomainServerConfigModule,
     FeatureFlagModule,
     PermissionsModule,
     ThrottlerModule,
     TwentyConfigModule,
     WorkspaceCacheStorageModule,
   ],
-  controllers: [OAuthTokenController, OAuthDiscoveryController],
+  controllers: [
+    OAuthTokenController,
+    OAuthDiscoveryController,
+    OAuthRegistrationController,
+  ],
   providers: [OAuthService, ApplicationOAuthResolver],
   exports: [OAuthService],
 })

packages/twenty-server/src/engine/core-modules/application/application-oauth/controllers/oauth-discovery.controller.ts

@@ -1,23 +1,29 @@
 import { Controller, Get, UseGuards } from '@nestjs/common';
 
 import { ALL_OAUTH_SCOPES } from 'src/engine/core-modules/application/application-oauth/constants/oauth-scopes';
+import { DomainServerConfigService } from 'src/engine/core-modules/domain/domain-server-config/services/domain-server-config.service';
 import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';
 import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';
 import { PublicEndpointGuard } from 'src/engine/guards/public-endpoint.guard';
 
 @Controller('.well-known')
 export class OAuthDiscoveryController {
-  constructor(private readonly twentyConfigService: TwentyConfigService) {}
+  constructor(
+    private readonly twentyConfigService: TwentyConfigService,
+    private readonly domainServerConfigService: DomainServerConfigService,
+  ) {}
 
   @Get('oauth-authorization-server')
   @UseGuards(PublicEndpointGuard, NoPermissionGuard)
   getAuthorizationServerMetadata() {
     const serverUrl = this.twentyConfigService.get('SERVER_URL');
+    const frontUrl = this.domainServerConfigService.getFrontUrl().toString();
 
     return {
       issuer: serverUrl,
-      authorization_endpoint: `${serverUrl}/authorize`,
+      authorization_endpoint: `${frontUrl.replace(/\/$/, '')}/authorize`,
       token_endpoint: `${serverUrl}/oauth/token`,
+      registration_endpoint: `${serverUrl}/oauth/register`,
       revocation_endpoint: `${serverUrl}/oauth/revoke`,
       introspection_endpoint: `${serverUrl}/oauth/introspect`,
       scopes_supported: ALL_OAUTH_SCOPES,
@@ -33,4 +39,18 @@ export class OAuthDiscoveryController {
       introspection_endpoint_auth_methods_supported: ['client_secret_post'],
     };
   }
+
+  // RFC 9728: OAuth 2.0 Protected Resource Metadata
+  @Get('oauth-protected-resource')
+  @UseGuards(PublicEndpointGuard, NoPermissionGuard)
+  getProtectedResourceMetadata() {
+    const serverUrl = this.twentyConfigService.get('SERVER_URL');
+
+    return {
+      resource: `${serverUrl}/mcp`,
+      authorization_servers: [serverUrl],
+      scopes_supported: ALL_OAUTH_SCOPES,
+      bearer_methods_supported: ['header'],
+    };
+  }
 }

packages/twenty-server/src/engine/core-modules/application/application-oauth/controllers/oauth-registration.controller.ts

@@ -0,0 +1,199 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  Post,
+  Req,
+  Res,
+  UseFilters,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
+
+import { type Request, type Response } from 'express';
+import { v4 } from 'uuid';
+
+import { InjectRepository } from '@nestjs/typeorm';
+import {
+  ALL_OAUTH_SCOPES,
+  type OAuthScope,
+} from 'src/engine/core-modules/application/application-oauth/constants/oauth-scopes';
+import { OAuthRegisterInput } from 'src/engine/core-modules/application/application-oauth/dtos/oauth-register.input';
+import { ApplicationRegistrationEntity } from 'src/engine/core-modules/application/application-registration/application-registration.entity';
+import { ApplicationRegistrationSourceType } from 'src/engine/core-modules/application/application-registration/enums/application-registration-source-type.enum';
+import { AuthRestApiExceptionFilter } from 'src/engine/core-modules/auth/filters/auth-rest-api-exception.filter';
+import { validateRedirectUri } from 'src/engine/core-modules/auth/utils/validate-redirect-uri.util';
+import { ThrottlerException } from 'src/engine/core-modules/throttler/throttler.exception';
+import { ThrottlerService } from 'src/engine/core-modules/throttler/throttler.service';
+import { NodeEnvironment } from 'src/engine/core-modules/twenty-config/interfaces/node-environment.interface';
+import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';
+import { PublicEndpointGuard } from 'src/engine/guards/public-endpoint.guard';
+import { Repository } from 'typeorm';
+
+// RFC 7591: 10 registrations per hour per IP
+const REGISTRATION_RATE_LIMIT_MAX =
+  process.env.NODE_ENV === NodeEnvironment.DEVELOPMENT ? 100 : 10;
+const REGISTRATION_RATE_LIMIT_WINDOW_MS = 3_600_000;
+
+const ALLOWED_GRANT_TYPES = ['authorization_code', 'refresh_token'];
+const ALLOWED_RESPONSE_TYPES = ['code'];
+
+@Controller('oauth')
+@UseFilters(AuthRestApiExceptionFilter)
+export class OAuthRegistrationController {
+  constructor(
+    @InjectRepository(ApplicationRegistrationEntity)
+    private readonly applicationRegistrationRepository: Repository<ApplicationRegistrationEntity>,
+    private readonly throttlerService: ThrottlerService,
+  ) {}
+
+  @Post('register')
+  @HttpCode(201)
+  @UseGuards(PublicEndpointGuard, NoPermissionGuard)
+  @UsePipes(new ValidationPipe())
+  async register(
+    @Body() body: OAuthRegisterInput,
+    @Req() req: Request,
+    @Res({ passthrough: true }) res: Response,
+  ) {
+    const rateLimitResult = await this.applyRateLimit(req);
+
+    if (rateLimitResult) {
+      res.status(429);
+
+      return rateLimitResult;
+    }
+
+    // Validate redirect URIs
+    for (const uri of body.redirect_uris) {
+      const result = validateRedirectUri(uri);
+
+      if (!result.valid) {
+        res.status(400);
+
+        return {
+          error: 'invalid_client_metadata',
+          error_description: result.reason,
+        };
+      }
+    }
+
+    if (body.redirect_uris.length === 0) {
+      res.status(400);
+
+      return {
+        error: 'invalid_client_metadata',
+        error_description: 'At least one redirect_uri is required',
+      };
+    }
+
+    // Validate grant_types — only authorization_code allowed for dynamic clients
+    const grantTypes = body.grant_types ?? ['authorization_code'];
+
+    for (const grantType of grantTypes) {
+      if (!ALLOWED_GRANT_TYPES.includes(grantType)) {
+        res.status(400);
+
+        return {
+          error: 'invalid_client_metadata',
+          error_description: `Unsupported grant_type: ${grantType}. Only authorization_code and refresh_token are allowed for dynamic registrations.`,
+        };
+      }
+    }
+
+    // Validate response_types
+    const responseTypes = body.response_types ?? ['code'];
+
+    for (const responseType of responseTypes) {
+      if (!ALLOWED_RESPONSE_TYPES.includes(responseType)) {
+        res.status(400);
+
+        return {
+          error: 'invalid_client_metadata',
+          error_description: `Unsupported response_type: ${responseType}`,
+        };
+      }
+    }
+
+    // Validate token_endpoint_auth_method — only 'none' for public clients
+    const tokenEndpointAuthMethod = body.token_endpoint_auth_method ?? 'none';
+
+    if (tokenEndpointAuthMethod !== 'none') {
+      res.status(400);
+
+      return {
+        error: 'invalid_client_metadata',
+        error_description:
+          'Only token_endpoint_auth_method "none" is supported for dynamic registrations (public clients with PKCE)',
+      };
+    }
+
+    // Parse and validate scopes — cap to allowed scopes
+    const validScopes: readonly string[] = ALL_OAUTH_SCOPES;
+    const requestedScopes = body.scope
+      ? body.scope.split(' ').filter((s) => validScopes.includes(s))
+      : [...ALL_OAUTH_SCOPES];
+
+    const clientId = v4();
+
+    const registration = this.applicationRegistrationRepository.create({
+      universalIdentifier: v4(),
+      name: body.client_name,
+      description: null,
+      logoUrl: body.logo_uri ?? null,
+      author: null,
+      oAuthClientId: clientId,
+      oAuthClientSecretHash: null,
+      oAuthRedirectUris: body.redirect_uris,
+      oAuthScopes: requestedScopes as OAuthScope[],
+      createdByUserId: null,
+      ownerWorkspaceId: null,
+      sourceType: ApplicationRegistrationSourceType.OAUTH_ONLY,
+      websiteUrl: body.client_uri ?? null,
+    });
+
+    await this.applicationRegistrationRepository.save(registration);
+
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('Pragma', 'no-cache');
+
+    return {
+      client_id: clientId,
+      client_name: body.client_name,
+      redirect_uris: body.redirect_uris,
+      grant_types: grantTypes,
+      response_types: responseTypes,
+      token_endpoint_auth_method: tokenEndpointAuthMethod,
+      scope: requestedScopes.join(' '),
+      client_id_issued_at: Math.floor(Date.now() / 1000),
+    };
+  }
+
+  private async applyRateLimit(
+    req: Request,
+  ): Promise<{ error: string; error_description: string } | null> {
+    const rateLimitKey = `oauth-register:${req.ip}`;
+
+    try {
+      await this.throttlerService.tokenBucketThrottleOrThrow(
+        rateLimitKey,
+        1,
+        REGISTRATION_RATE_LIMIT_MAX,
+        REGISTRATION_RATE_LIMIT_WINDOW_MS,
+      );
+
+      return null;
+    } catch (error) {
+      if (error instanceof ThrottlerException) {
+        return {
+          error: 'rate_limit_exceeded',
+          error_description:
+            'Too many registration requests, please try again later',
+        };
+      }
+
+      throw error;
+    }
+  }
+}

packages/twenty-server/src/engine/core-modules/application/application-oauth/dtos/oauth-register.input.ts

@@ -0,0 +1,52 @@
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsOptional,
+  IsString,
+  MaxLength,
+} from 'class-validator';
+
+// RFC 7591: OAuth 2.0 Dynamic Client Registration
+export class OAuthRegisterInput {
+  @IsString()
+  @MaxLength(256)
+  client_name: string;
+
+  @IsArray()
+  @IsString({ each: true })
+  @ArrayMaxSize(20)
+  @MaxLength(2048, { each: true })
+  redirect_uris: string[];
+
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  @ArrayMaxSize(5)
+  grant_types?: string[];
+
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  @ArrayMaxSize(5)
+  response_types?: string[];
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50)
+  token_endpoint_auth_method?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(256)
+  scope?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(2048)
+  client_uri?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(2048)
+  logo_uri?: string;
+}

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/commands/stale-registration-cleanup.cron.command.ts

@@ -0,0 +1,33 @@
+import { Command, CommandRunner } from 'nest-commander';
+
+import { InjectMessageQueue } from 'src/engine/core-modules/message-queue/decorators/message-queue.decorator';
+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
+import { MessageQueueService } from 'src/engine/core-modules/message-queue/services/message-queue.service';
+import { STALE_REGISTRATION_CLEANUP_CRON_PATTERN } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-cleanup-cron-pattern.constant';
+import { StaleRegistrationCleanupCronJob } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/crons/stale-registration-cleanup.cron.job';
+
+@Command({
+  name: 'cron:stale-registration-cleanup',
+  description:
+    'Starts a cron job to clean up stale OAuth-only application registrations',
+})
+export class StaleRegistrationCleanupCronCommand extends CommandRunner {
+  constructor(
+    @InjectMessageQueue(MessageQueue.cronQueue)
+    private readonly messageQueueService: MessageQueueService,
+  ) {
+    super();
+  }
+
+  async run(): Promise<void> {
+    await this.messageQueueService.addCron<undefined>({
+      jobName: StaleRegistrationCleanupCronJob.name,
+      data: undefined,
+      options: {
+        repeat: {
+          pattern: STALE_REGISTRATION_CLEANUP_CRON_PATTERN,
+        },
+      },
+    });
+  }
+}

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-cleanup-batch-size.constant.ts

@@ -0,0 +1 @@
+export const STALE_REGISTRATION_CLEANUP_BATCH_SIZE = 100;

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-cleanup-cron-pattern.constant.ts

@@ -0,0 +1,2 @@
+// Runs daily at 02:30 AM UTC
+export const STALE_REGISTRATION_CLEANUP_CRON_PATTERN = '30 2 * * *';

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-grace-period-days.constant.ts

@@ -0,0 +1 @@
+export const STALE_REGISTRATION_GRACE_PERIOD_DAYS = 30;

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/crons/stale-registration-cleanup.cron.job.ts

@@ -0,0 +1,41 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { SentryCronMonitor } from 'src/engine/core-modules/cron/sentry-cron-monitor.decorator';
+import { ExceptionHandlerService } from 'src/engine/core-modules/exception-handler/exception-handler.service';
+import { Process } from 'src/engine/core-modules/message-queue/decorators/process.decorator';
+import { Processor } from 'src/engine/core-modules/message-queue/decorators/processor.decorator';
+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
+import { STALE_REGISTRATION_CLEANUP_CRON_PATTERN } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-cleanup-cron-pattern.constant';
+import { StaleRegistrationCleanupService } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/services/stale-registration-cleanup.service';
+
+@Injectable()
+@Processor(MessageQueue.cronQueue)
+export class StaleRegistrationCleanupCronJob {
+  private readonly logger = new Logger(StaleRegistrationCleanupCronJob.name);
+
+  constructor(
+    private readonly staleRegistrationCleanupService: StaleRegistrationCleanupService,
+    private readonly exceptionHandlerService: ExceptionHandlerService,
+  ) {}
+
+  @Process(StaleRegistrationCleanupCronJob.name)
+  @SentryCronMonitor(
+    StaleRegistrationCleanupCronJob.name,
+    STALE_REGISTRATION_CLEANUP_CRON_PATTERN,
+  )
+  async handle(): Promise<void> {
+    this.logger.log('Starting stale OAuth registration cleanup');
+
+    try {
+      const deletedCount =
+        await this.staleRegistrationCleanupService.cleanupStaleRegistrations();
+
+      this.logger.log(
+        `Stale OAuth registration cleanup completed: ${deletedCount} registration(s) deleted`,
+      );
+    } catch (error) {
+      this.exceptionHandlerService.captureExceptions([error]);
+      throw error;
+    }
+  }
+}

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/services/stale-registration-cleanup.service.ts

@@ -0,0 +1,131 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+
+import { In, Repository } from 'typeorm';
+
+import { ApplicationRegistrationEntity } from 'src/engine/core-modules/application/application-registration/application-registration.entity';
+import { ApplicationRegistrationSourceType } from 'src/engine/core-modules/application/application-registration/enums/application-registration-source-type.enum';
+import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
+import { STALE_REGISTRATION_CLEANUP_BATCH_SIZE } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-cleanup-batch-size.constant';
+import { STALE_REGISTRATION_GRACE_PERIOD_DAYS } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/constants/stale-registration-grace-period-days.constant';
+
+@Injectable()
+export class StaleRegistrationCleanupService {
+  private readonly logger = new Logger(StaleRegistrationCleanupService.name);
+
+  constructor(
+    @InjectRepository(ApplicationRegistrationEntity)
+    private readonly applicationRegistrationRepository: Repository<ApplicationRegistrationEntity>,
+    @InjectRepository(ApplicationEntity)
+    private readonly applicationRepository: Repository<ApplicationEntity>,
+  ) {}
+
+  async cleanupStaleRegistrations(): Promise<number> {
+    const cutoffDate = this.calculateCutoffDate();
+    let totalDeleted = 0;
+    let lastCreatedAt: Date | undefined;
+
+    while (true) {
+      const staleRegistrations = await this.findStaleRegistrationBatch(
+        cutoffDate,
+        STALE_REGISTRATION_CLEANUP_BATCH_SIZE,
+        lastCreatedAt,
+      );
+
+      if (staleRegistrations.length === 0) {
+        break;
+      }
+
+      lastCreatedAt =
+        staleRegistrations[staleRegistrations.length - 1].createdAt;
+
+      const staleIds = staleRegistrations.map(
+        (registration) => registration.id,
+      );
+
+      // Filter out registrations that have active (non-deleted) installations
+      const registrationsWithInstallations = await this.applicationRepository
+        .createQueryBuilder('application')
+        .select('application.applicationRegistrationId')
+        .where(
+          'application.applicationRegistrationId IN (:...registrationIds)',
+          { registrationIds: staleIds },
+        )
+        .andWhere('application.deletedAt IS NULL')
+        .groupBy('application.applicationRegistrationId')
+        .getRawMany<{ application_applicationRegistrationId: string }>();
+
+      const registrationIdsWithInstallations = new Set(
+        registrationsWithInstallations.map(
+          (row) => row.application_applicationRegistrationId,
+        ),
+      );
+
+      const idsToDelete = staleIds.filter(
+        (id) => !registrationIdsWithInstallations.has(id),
+      );
+
+      if (idsToDelete.length > 0) {
+        await this.applicationRegistrationRepository.softDelete({
+          id: In(idsToDelete),
+        });
+
+        this.logger.log(
+          `Deleted ${idsToDelete.length} stale OAuth registration(s)`,
+        );
+
+        totalDeleted += idsToDelete.length;
+      }
+
+      if (staleRegistrations.length < STALE_REGISTRATION_CLEANUP_BATCH_SIZE) {
+        break;
+      }
+    }
+
+    return totalDeleted;
+  }
+
+  private async findStaleRegistrationBatch(
+    cutoffDate: Date,
+    batchSize: number,
+    afterCreatedAt?: Date,
+  ): Promise<Array<{ id: string; createdAt: Date }>> {
+    const queryBuilder = this.applicationRegistrationRepository
+      .createQueryBuilder('registration')
+      .select('registration.id', 'id')
+      .addSelect('registration.createdAt', 'createdAt')
+      .where('registration.sourceType = :sourceType', {
+        sourceType: ApplicationRegistrationSourceType.OAUTH_ONLY,
+      })
+      .andWhere('registration.createdAt < :cutoffDate', { cutoffDate })
+      .orderBy('registration.createdAt', 'ASC')
+      .take(batchSize);
+
+    if (afterCreatedAt) {
+      queryBuilder.andWhere('registration.createdAt > :afterCreatedAt', {
+        afterCreatedAt,
+      });
+    }
+
+    const rows = await queryBuilder.getRawMany<{
+      id: string;
+      createdAt: Date;
+    }>();
+
+    return rows.map((row) => ({
+      id: row.id,
+      createdAt: new Date(row.createdAt),
+    }));
+  }
+
+  private calculateCutoffDate(): Date {
+    const cutoffDate = new Date();
+
+    cutoffDate.setUTCHours(0, 0, 0, 0);
+    cutoffDate.setUTCDate(
+      cutoffDate.getUTCDate() - STALE_REGISTRATION_GRACE_PERIOD_DAYS,
+    );
+
+    return cutoffDate;
+  }
+}

packages/twenty-server/src/engine/core-modules/application/application-oauth/stale-registration-cleanup/stale-registration-cleanup.module.ts

@@ -0,0 +1,24 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { ApplicationRegistrationEntity } from 'src/engine/core-modules/application/application-registration/application-registration.entity';
+import { ApplicationEntity } from 'src/engine/core-modules/application/application.entity';
+import { StaleRegistrationCleanupCronCommand } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/commands/stale-registration-cleanup.cron.command';
+import { StaleRegistrationCleanupCronJob } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/crons/stale-registration-cleanup.cron.job';
+import { StaleRegistrationCleanupService } from 'src/engine/core-modules/application/application-oauth/stale-registration-cleanup/services/stale-registration-cleanup.service';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      ApplicationRegistrationEntity,
+      ApplicationEntity,
+    ]),
+  ],
+  providers: [
+    StaleRegistrationCleanupService,
+    StaleRegistrationCleanupCronJob,
+    StaleRegistrationCleanupCronCommand,
+  ],
+  exports: [StaleRegistrationCleanupCronCommand],
+})
+export class StaleRegistrationCleanupModule {}

packages/twenty-server/src/engine/core-modules/application/application-package/application-package-fetcher.service.ts

@@ -92,6 +92,7 @@ export class ApplicationPackageFetcherService implements OnModuleInit {
       case ApplicationRegistrationSourceType.TARBALL:
         return this.resolveFromTarball(appRegistration);
       case ApplicationRegistrationSourceType.LOCAL:
+      case ApplicationRegistrationSourceType.OAUTH_ONLY:
         return null;
     }
   }

packages/twenty-server/src/engine/core-modules/application/application-registration/enums/application-registration-source-type.enum.ts

@@ -4,6 +4,7 @@ export enum ApplicationRegistrationSourceType {
   NPM = 'npm',
   TARBALL = 'tarball',
   LOCAL = 'local',
+  OAUTH_ONLY = 'oauth-only',
 }
 
 registerEnumType(ApplicationRegistrationSourceType, {

packages/twenty-server/src/engine/core-modules/application/application-upgrade/application-upgrade.service.ts

@@ -101,10 +101,13 @@ export class ApplicationUpgradeService {
 
     if (
       appRegistration.sourceType === ApplicationRegistrationSourceType.LOCAL ||
-      appRegistration.sourceType === ApplicationRegistrationSourceType.TARBALL
+      appRegistration.sourceType ===
+        ApplicationRegistrationSourceType.TARBALL ||
+      appRegistration.sourceType ===
+        ApplicationRegistrationSourceType.OAUTH_ONLY
     ) {
       throw new ApplicationException(
-        'Cannot upgrade an app installed from a tarball or local source',
+        'Cannot upgrade an app installed from a tarball, local source, or OAuth-only registration',
         ApplicationExceptionCode.UPGRADE_FAILED,
       );
     }