feat(integrations): add integration framework with link unfurling

apps/server/src/core/integration/constants.ts

@@ -0,0 +1,9 @@
+export enum IntegrationType {
+  SLACK = 'slack',
+  GITHUB = 'github',
+  GITLAB = 'gitlab',
+  JIRA = 'jira',
+  LINEAR = 'linear',
+  GOOGLE_DOCS = 'google_docs',
+  FIGMA = 'figma',
+}

apps/server/src/core/integration/dto/integration.dto.ts

@@ -0,0 +1,57 @@
+import {
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  Matches,
+  MaxLength,
+} from 'class-validator';
+
+export class InstallIntegrationDto {
+  @IsNotEmpty()
+  @IsString()
+  type: string;
+}
+
+export class UninstallIntegrationDto {
+  @IsNotEmpty()
+  @IsString()
+  integrationId: string;
+}
+
+export class IntegrationIdDto {
+  @IsNotEmpty()
+  @IsString()
+  integrationId: string;
+}
+
+export class UnfurlDto {
+  @IsNotEmpty()
+  @IsString()
+  url: string;
+}
+
+export class OAuthAuthorizeDto {
+  @IsNotEmpty()
+  @IsString()
+  integrationId: string;
+
+  // In-app path to land on after OAuth; single leading slash keeps the
+  // redirect on the workspace origin.
+  @IsOptional()
+  @IsString()
+  @MaxLength(512)
+  @Matches(/^\/(?!\/)[^\s\\]*$/)
+  returnPath?: string;
+}
+
+export class OAuthDisconnectDto {
+  @IsNotEmpty()
+  @IsString()
+  integrationId: string;
+}
+
+export class OAuthInstallDto {
+  @IsNotEmpty()
+  @IsString()
+  type: string;
+}

apps/server/src/core/integration/integration-connection.service.ts

@@ -0,0 +1,89 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { IntegrationConnectionRepo } from './repos/integration-connection.repo';
+import { IntegrationRepo } from './repos/integration.repo';
+import { IntegrationConnection } from '@docmost/db/types/entity.types';
+import { UnfurlService } from './unfurl/unfurl.service';
+
+@Injectable()
+export class IntegrationConnectionService {
+  constructor(
+    private readonly connectionRepo: IntegrationConnectionRepo,
+    private readonly integrationRepo: IntegrationRepo,
+    private readonly unfurlService: UnfurlService,
+  ) {}
+
+  async getConnectionStatus(
+    integrationId: string,
+    userId: string,
+    workspaceId: string,
+  ): Promise<{ connected: boolean; providerUserId?: string }> {
+    const integration = await this.integrationRepo.findById(integrationId);
+    if (!integration || integration.workspaceId !== workspaceId) {
+      throw new NotFoundException('Integration not found');
+    }
+
+    const connection = await this.connectionRepo.findByIntegrationAndUser(
+      integrationId,
+      userId,
+    );
+
+    return {
+      connected: !!connection && !connection.invalidatedAt,
+      providerUserId: connection?.providerUserId ?? undefined,
+    };
+  }
+
+  async findByIntegrationAndUser(
+    integrationId: string,
+    userId: string,
+  ): Promise<IntegrationConnection | undefined> {
+    return this.connectionRepo.findByIntegrationAndUser(integrationId, userId);
+  }
+
+  async findByWorkspaceTypeAndUser(
+    workspaceId: string,
+    integrationType: string,
+    userId: string,
+  ): Promise<IntegrationConnection | undefined> {
+    return this.connectionRepo.findByWorkspaceTypeAndUser(
+      workspaceId,
+      integrationType,
+      userId,
+    );
+  }
+
+  async getUserConnections(userId: string, workspaceId: string) {
+    const rows = await this.connectionRepo.findByUserAndWorkspace(
+      userId,
+      workspaceId,
+    );
+
+    return rows.map((row) => ({
+      integrationId: row.integrationId,
+      type: row.type,
+      providerUserId: row.providerUserId ?? null,
+      providerDisplayName:
+        (row.metadata as { displayName?: string } | null)?.displayName ?? null,
+      connectedAt: row.createdAt,
+      invalidatedAt: row.invalidatedAt ?? null,
+    }));
+  }
+
+  async disconnect(
+    integrationId: string,
+    userId: string,
+    workspaceId: string,
+  ): Promise<void> {
+    const integration = await this.integrationRepo.findById(integrationId);
+    if (!integration || integration.workspaceId !== workspaceId) {
+      throw new NotFoundException('Integration not found');
+    }
+
+    await this.connectionRepo.deleteByIntegrationAndUser(
+      integrationId,
+      userId,
+    );
+
+    await this.unfurlService.purgeUserCache(workspaceId, userId);
+  }
+}

apps/server/src/core/integration/integration.controller.ts

@@ -0,0 +1,138 @@
+import {
+  Body,
+  Controller,
+  ForbiddenException,
+  HttpCode,
+  HttpStatus,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { AuthUser } from '../../common/decorators/auth-user.decorator';
+import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import { IntegrationService } from './integration.service';
+import { IntegrationConnectionService } from './integration-connection.service';
+import {
+  InstallIntegrationDto,
+  UninstallIntegrationDto,
+  IntegrationIdDto,
+} from './dto/integration.dto';
+import { IntegrationRegistry } from './registry/integration-registry';
+import WorkspaceAbilityFactory from '../casl/abilities/workspace-ability.factory';
+import {
+  WorkspaceCaslAction,
+  WorkspaceCaslSubject,
+} from '../casl/interfaces/workspace-ability.type';
+import { LicenseCheckService } from '../../integrations/environment/license-check.service';
+import { Feature } from '../../common/features';
+
+@Controller('integrations')
+export class IntegrationController {
+  constructor(
+    private readonly integrationService: IntegrationService,
+    private readonly connectionService: IntegrationConnectionService,
+    private readonly workspaceAbility: WorkspaceAbilityFactory,
+    private readonly licenseCheckService: LicenseCheckService,
+    private readonly registry: IntegrationRegistry,
+  ) {}
+
+  private assertIntegrationsLicensed(workspace: Workspace) {
+    if (
+      !this.licenseCheckService.hasFeature(
+        workspace.licenseKey,
+        Feature.INTEGRATIONS,
+        workspace.plan,
+      )
+    ) {
+      throw new ForbiddenException('This feature requires a valid license');
+    }
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('available')
+  async getAvailableIntegrations() {
+    return this.integrationService.getAvailableIntegrations();
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('list')
+  async getInstalledIntegrations(
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.integrationService.getInstalledIntegrations(workspace.id);
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('install')
+  async install(
+    @Body() dto: InstallIntegrationDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const ability = this.workspaceAbility.createForUser(user, workspace);
+    if (
+      ability.cannot(
+        WorkspaceCaslAction.Manage,
+        WorkspaceCaslSubject.Settings,
+      )
+    ) {
+      throw new ForbiddenException();
+    }
+
+    if (this.registry.getProvider(dto.type)?.definition.requiresLicense) {
+      this.assertIntegrationsLicensed(workspace);
+    }
+    return this.integrationService.install(dto.type, workspace.id, user.id);
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('uninstall')
+  async uninstall(
+    @Body() dto: UninstallIntegrationDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const ability = this.workspaceAbility.createForUser(user, workspace);
+    if (
+      ability.cannot(
+        WorkspaceCaslAction.Manage,
+        WorkspaceCaslSubject.Settings,
+      )
+    ) {
+      throw new ForbiddenException();
+    }
+
+    await this.integrationService.uninstall(dto.integrationId, workspace.id);
+    return { success: true };
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('connections/mine')
+  async getMyConnections(
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.connectionService.getUserConnections(user.id, workspace.id);
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('connection/status')
+  async getConnectionStatus(
+    @Body() dto: IntegrationIdDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.connectionService.getConnectionStatus(
+      dto.integrationId,
+      user.id,
+      workspace.id,
+    );
+  }
+}

apps/server/src/core/integration/integration.listener.ts

@@ -0,0 +1,55 @@
+import { Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+import { QueueJob, QueueName } from '../../integrations/queue/constants';
+import { EventName } from '../../common/events/event.contants';
+
+const TOKEN_REFRESH_SCHEDULER_ID = 'integration-token-refresh-scheduler';
+const TOKEN_REFRESH_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes
+
+@Injectable()
+export class IntegrationListener implements OnApplicationBootstrap {
+  private readonly logger = new Logger(IntegrationListener.name);
+
+  constructor(
+    @InjectQueue(QueueName.INTEGRATION_QUEUE)
+    private readonly integrationQueue: Queue,
+  ) {}
+
+  async onApplicationBootstrap() {
+    await this.integrationQueue.upsertJobScheduler(
+      TOKEN_REFRESH_SCHEDULER_ID,
+      { every: TOKEN_REFRESH_INTERVAL_MS },
+      {
+        name: QueueJob.INTEGRATION_TOKEN_REFRESH,
+        data: {},
+      },
+    );
+    this.logger.debug('Integration token refresh scheduler created');
+  }
+
+  @OnEvent(EventName.PAGE_CREATED)
+  async onPageCreated(payload: any) {
+    await this.integrationQueue.add(QueueJob.INTEGRATION_EVENT, {
+      eventName: EventName.PAGE_CREATED,
+      ...payload,
+    });
+  }
+
+  @OnEvent(EventName.PAGE_UPDATED)
+  async onPageUpdated(payload: any) {
+    await this.integrationQueue.add(QueueJob.INTEGRATION_EVENT, {
+      eventName: EventName.PAGE_UPDATED,
+      ...payload,
+    });
+  }
+
+  @OnEvent(EventName.PAGE_DELETED)
+  async onPageDeleted(payload: any) {
+    await this.integrationQueue.add(QueueJob.INTEGRATION_EVENT, {
+      eventName: EventName.PAGE_DELETED,
+      ...payload,
+    });
+  }
+}

apps/server/src/core/integration/integration.module.ts

@@ -0,0 +1,37 @@
+import { Module } from '@nestjs/common';
+import { IntegrationRegistry } from './registry/integration-registry';
+import { IntegrationService } from './integration.service';
+import { IntegrationConnectionService } from './integration-connection.service';
+import { IntegrationController } from './integration.controller';
+import { OAuthController } from './oauth/oauth.controller';
+import { OAuthService } from './oauth/oauth.service';
+import { UnfurlController } from './unfurl/unfurl.controller';
+import { UnfurlService } from './unfurl/unfurl.service';
+import { IntegrationRepo } from './repos/integration.repo';
+import { IntegrationConnectionRepo } from './repos/integration-connection.repo';
+import { IntegrationListener } from './integration.listener';
+import { IntegrationProcessor } from './integration.processor';
+
+@Module({
+  controllers: [IntegrationController, OAuthController, UnfurlController],
+  providers: [
+    IntegrationRegistry,
+    IntegrationService,
+    IntegrationConnectionService,
+    OAuthService,
+    UnfurlService,
+    IntegrationRepo,
+    IntegrationConnectionRepo,
+    IntegrationListener,
+    IntegrationProcessor,
+  ],
+  exports: [
+    IntegrationRegistry,
+    IntegrationService,
+    IntegrationConnectionService,
+    OAuthService,
+    IntegrationRepo,
+    IntegrationConnectionRepo,
+  ],
+})
+export class IntegrationModule {}

apps/server/src/core/integration/integration.processor.ts

@@ -0,0 +1,133 @@
+import { OnWorkerEvent, Processor, WorkerHost } from '@nestjs/bullmq';
+import { Logger, NotFoundException } from '@nestjs/common';
+import { IntegrationConnection } from '@docmost/db/types/entity.types';
+import { TokenInvalidError } from './registry/integration-provider.interface';
+import { Job } from 'bullmq';
+import { QueueJob, QueueName } from '../../integrations/queue/constants/queue.constants';
+import { IntegrationRegistry } from './registry/integration-registry';
+import { IntegrationRepo } from './repos/integration.repo';
+import { IntegrationConnectionRepo } from './repos/integration-connection.repo';
+import { OAuthService } from './oauth/oauth.service';
+
+const TOKEN_REFRESH_WINDOW_MS = 15 * 60 * 1000; // 15 minutes
+
+@Processor(QueueName.INTEGRATION_QUEUE)
+export class IntegrationProcessor extends WorkerHost {
+  private readonly logger = new Logger(IntegrationProcessor.name);
+
+  constructor(
+    private readonly registry: IntegrationRegistry,
+    private readonly integrationRepo: IntegrationRepo,
+    private readonly connectionRepo: IntegrationConnectionRepo,
+    private readonly oauthService: OAuthService,
+  ) {
+    super();
+  }
+
+  async process(job: Job): Promise<void> {
+    switch (job.name) {
+      case QueueJob.INTEGRATION_EVENT:
+        await this.handleIntegrationEvent(job);
+        break;
+      case QueueJob.INTEGRATION_TOKEN_REFRESH:
+        await this.handleTokenRefresh();
+        break;
+      default:
+        this.logger.warn(`Unknown job: ${job.name}`);
+    }
+  }
+
+  // Route worker-level errors (e.g. lock renewal after laptop sleep) through
+  // the logger instead of bullmq's raw console.error fallback.
+  @OnWorkerEvent('error')
+  onError(err: Error): void {
+    this.logger.error(`Worker error: ${err.message}`);
+  }
+
+  private async handleTokenRefresh(): Promise<void> {
+    const connections = await this.connectionRepo.findExpiringTokens(
+      TOKEN_REFRESH_WINDOW_MS,
+    );
+
+    if (connections.length === 0) {
+      return;
+    }
+
+    this.logger.log(
+      `Refreshing tokens for ${connections.length} connection(s)`,
+    );
+
+    for (const connection of connections) {
+      try {
+        await this.oauthService.getValidAccessToken(connection);
+      } catch (err) {
+        this.logger.error(
+          `Token refresh failed for connection ${connection.id}: ${(err as Error).message}`,
+        );
+        // Dead credential or orphaned row: retire it so findExpiringTokens stops selecting it.
+        if (
+          err instanceof NotFoundException ||
+          err instanceof TokenInvalidError
+        ) {
+          await this.connectionRepo
+            .invalidate(connection.id)
+            .catch(() => undefined);
+        }
+      }
+    }
+  }
+
+  private async handleIntegrationEvent(job: Job): Promise<void> {
+    const { eventName, workspaceId, ...payload } = job.data;
+
+    if (!workspaceId) {
+      return;
+    }
+
+    const integrations =
+      await this.integrationRepo.findAllByWorkspace(workspaceId);
+
+    for (const integration of integrations) {
+      const provider = this.registry.getProvider(integration.type);
+      if (!provider?.handleEvent) {
+        continue;
+      }
+
+      let connection: IntegrationConnection | undefined;
+      try {
+        const connections = await this.connectionRepo.findByIntegration(
+          integration.id,
+        );
+
+        connection = connections[0];
+        let accessToken: string | undefined;
+
+        if (connection) {
+          accessToken = await this.oauthService.getValidAccessToken(connection);
+        }
+
+        await provider.handleEvent({
+          eventName,
+          payload,
+          integration: {
+            id: integration.id,
+            type: integration.type,
+            settings: integration.settings as Record<string, any> | null,
+          },
+          connection: connection
+            ? { accessToken, userId: connection.userId }
+            : undefined,
+        });
+      } catch (err) {
+        this.logger.error(
+          `Integration event handler failed for ${integration.type}: ${(err as Error).message}`,
+        );
+        if (err instanceof TokenInvalidError && connection) {
+          await this.connectionRepo
+            .invalidate(connection.id)
+            .catch(() => undefined);
+        }
+      }
+    }
+  }
+}

apps/server/src/core/integration/integration.service.ts

@@ -0,0 +1,80 @@
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';
+import { IntegrationRepo } from './repos/integration.repo';
+import { IntegrationConnectionRepo } from './repos/integration-connection.repo';
+import { IntegrationRegistry } from './registry/integration-registry';
+import { Integration } from '@docmost/db/types/entity.types';
+
+@Injectable()
+export class IntegrationService {
+  constructor(
+    @InjectKysely() private readonly db: KyselyDB,
+    private readonly integrationRepo: IntegrationRepo,
+    private readonly connectionRepo: IntegrationConnectionRepo,
+    private readonly registry: IntegrationRegistry,
+  ) {}
+
+  async getAvailableIntegrations() {
+    return this.registry.getAvailableIntegrations();
+  }
+
+  async getInstalledIntegrations(workspaceId: string): Promise<Integration[]> {
+    return this.integrationRepo.findAllByWorkspace(workspaceId);
+  }
+
+  async findById(integrationId: string): Promise<Integration | undefined> {
+    return this.integrationRepo.findById(integrationId);
+  }
+
+  async install(
+    type: string,
+    workspaceId: string,
+    userId: string,
+  ): Promise<Integration> {
+    const provider = this.registry.getProvider(type);
+    if (!provider || provider.definition.hidden) {
+      throw new BadRequestException(`Unknown integration type: ${type}`);
+    }
+
+    // OAuth providers install via install-and-authorize (see OAuthService).
+    if (provider.definition.oauth) {
+      throw new BadRequestException(
+        'This integration is installed by completing its OAuth flow',
+      );
+    }
+
+    const existing = await this.integrationRepo.findByWorkspaceAndType(
+      workspaceId,
+      type,
+    );
+    if (existing) {
+      throw new BadRequestException(
+        `Integration "${type}" is already installed`,
+      );
+    }
+
+    return this.integrationRepo.insertOrRestore({
+      type,
+      workspaceId,
+      installedById: userId,
+    });
+  }
+
+  async uninstall(integrationId: string, workspaceId: string): Promise<void> {
+    const integration = await this.integrationRepo.findById(integrationId);
+    if (!integration || integration.workspaceId !== workspaceId) {
+      throw new NotFoundException('Integration not found');
+    }
+    // Delete child rows first so no orphan connections keep feeding the token refresh scheduler.
+    await executeTx(this.db, async (trx) => {
+      await this.connectionRepo.deleteByIntegration(integrationId, trx);
+      await this.integrationRepo.softDelete(integrationId, trx);
+    });
+  }
+}

apps/server/src/core/integration/oauth/oauth.controller.ts

@@ -0,0 +1,159 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Logger,
+  Param,
+  Post,
+  Query,
+  Res,
+  UseGuards,
+} from '@nestjs/common';
+import { FastifyReply } from 'fastify';
+import { JwtAuthGuard } from '../../../common/guards/jwt-auth.guard';
+import { AuthUser } from '../../../common/decorators/auth-user.decorator';
+import { AuthWorkspace } from '../../../common/decorators/auth-workspace.decorator';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import { OAuthService } from './oauth.service';
+import {
+  OAuthAuthorizeDto,
+  OAuthDisconnectDto,
+  OAuthInstallDto,
+} from '../dto/integration.dto';
+import { IntegrationConnectionService } from '../integration-connection.service';
+import { IntegrationRegistry } from '../registry/integration-registry';
+import { LicenseCheckService } from '../../../integrations/environment/license-check.service';
+import { Feature } from '../../../common/features';
+import { ForbiddenException } from '@nestjs/common';
+
+@Controller('integrations/oauth')
+export class OAuthController {
+  private readonly logger = new Logger(OAuthController.name);
+
+  constructor(
+    private readonly oauthService: OAuthService,
+    private readonly connectionService: IntegrationConnectionService,
+    private readonly licenseCheckService: LicenseCheckService,
+    private readonly registry: IntegrationRegistry,
+  ) {}
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('authorize')
+  async authorize(
+    @Body() dto: OAuthAuthorizeDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const { authorizationUrl } = await this.oauthService.getAuthorizationUrl(
+      dto.integrationId,
+      workspace.id,
+      user.id,
+      dto.returnPath,
+    );
+
+    return { authorizationUrl };
+  }
+
+  /**
+   * Install-and-authorize: the install flow for every OAuth provider. The
+   * integration row is only created on callback after a successful token
+   * exchange; a cancelled or failed flow persists nothing.
+   */
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('install')
+  async installAndAuthorize(
+    @Body() dto: OAuthInstallDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    // This flow creates the integration row on callback success; gate it
+    // like a plain install.
+    if (
+      this.registry.getProvider(dto.type)?.definition.requiresLicense &&
+      !this.licenseCheckService.hasFeature(
+        workspace.licenseKey,
+        Feature.INTEGRATIONS,
+        workspace.plan,
+      )
+    ) {
+      throw new ForbiddenException('This feature requires a valid license');
+    }
+
+    const { authorizationUrl } = await this.oauthService.getInstallAuthorizationUrl(
+      dto.type,
+      workspace.id,
+      user.id,
+    );
+
+    return { authorizationUrl };
+  }
+
+  @Get(':type/callback')
+  async callback(
+    @Param('type') type: string,
+    @Query('code') code: string,
+    @Query('state') state: string,
+    @Res() res: FastifyReply,
+  ) {
+    if (!state) {
+      throw new BadRequestException('Missing state parameter');
+    }
+
+    const statePayload = this.oauthService.verifySignedState(state);
+    if (!statePayload) {
+      throw new BadRequestException('Invalid or expired OAuth state');
+    }
+
+    // returnUrl is derived server-side at authorize time from the workspace's
+    // own hostname/customDomain (canonical DB truth, not user input), then
+    // signed into the state JWT. Tampering would invalidate the signature.
+    const returnUrl = statePayload.returnUrl;
+    // States signed before returnPath existed fall back to the admin page.
+    const returnPath = statePayload.returnPath ?? '/settings/integrations';
+
+    // Consent denied or cancelled at the provider: no code comes back.
+    if (!code) {
+      return res
+        .redirect(`${returnUrl}${returnPath}?error=oauth_failed`, 302)
+        .send();
+    }
+
+    try {
+      await this.oauthService.exchangeCodeForTokens(
+        type,
+        code,
+        statePayload.integrationId,
+        statePayload.userId,
+        statePayload.workspaceId,
+      );
+
+      return res.redirect(`${returnUrl}${returnPath}`, 302).send();
+    } catch (err) {
+      this.logger.error(`OAuth callback error for ${type}: ${(err as Error).message}`);
+      return res
+        .redirect(`${returnUrl}${returnPath}?error=oauth_failed`, 302)
+        .send();
+    }
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('disconnect')
+  async disconnect(
+    @Body() dto: OAuthDisconnectDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    await this.connectionService.disconnect(
+      dto.integrationId,
+      user.id,
+      workspace.id,
+    );
+    return { success: true };
+  }
+}

apps/server/src/core/integration/oauth/oauth.service.ts

@@ -0,0 +1,473 @@
+import {
+  BadRequestException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { EnvironmentService } from '../../../integrations/environment/environment.service';
+import { DomainService } from '../../../integrations/environment/domain.service';
+import { IntegrationRegistry } from '../registry/integration-registry';
+import { IntegrationRepo } from '../repos/integration.repo';
+import { IntegrationConnectionRepo } from '../repos/integration-connection.repo';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { EncryptionService } from '../../../integrations/encryption/encryption.service';
+import { IntegrationConnection } from '@docmost/db/types/entity.types';
+import {
+  OAuthConfig,
+  TokenInvalidError,
+} from '../registry/integration-provider.interface';
+import { proxyFetch } from '../../../common/proxy-fetch';
+import * as crypto from 'crypto';
+
+const OAUTH_HTTP_TIMEOUT_MS = 10_000;
+
+type OAuthTokenResponse = {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  token_type?: string;
+  scope?: string;
+};
+
+export type OAuthStatePayload = {
+  // For "authorize-only" flows (per-user OAuth on an already-installed
+  // integration) integrationId is set; for "install-and-authorize" flows
+  // (workspace-scoped providers like Slack) it's null until the callback
+  // resolves-or-creates the row atomically with token exchange success.
+  integrationId: string | null;
+  type: string;
+  userId: string;
+  workspaceId: string;
+  // Workspace's canonical URL at authorize time. Cloud workspaces are routed
+  // through a single central OAuth callback (the only redirect_uri Slack/etc.
+  // accept), and this lets the callback redirect the user back to their own
+  // workspace host (subdomain or custom domain) after token exchange.
+  returnUrl: string;
+  // Settings page (relative to returnUrl) to land on after the callback.
+  // Derived server-side from the flow that started it, never from user input.
+  returnPath?: string;
+  exp: number;
+};
+
+@Injectable()
+export class OAuthService {
+  private readonly logger = new Logger(OAuthService.name);
+
+  constructor(
+    private readonly environmentService: EnvironmentService,
+    private readonly domainService: DomainService,
+    private readonly registry: IntegrationRegistry,
+    private readonly integrationRepo: IntegrationRepo,
+    private readonly connectionRepo: IntegrationConnectionRepo,
+    private readonly workspaceRepo: WorkspaceRepo,
+    private readonly encryptionService: EncryptionService,
+  ) {}
+
+  async getAuthorizationUrl(
+    integrationId: string,
+    workspaceId: string,
+    userId: string,
+    returnPathOverride?: string,
+  ): Promise<{ authorizationUrl: string }> {
+    const integration = await this.integrationRepo.findById(integrationId);
+    if (!integration || integration.workspaceId !== workspaceId) {
+      throw new NotFoundException('Integration not found');
+    }
+
+    const provider = this.registry.getProvider(integration.type);
+    if (!provider || !provider.definition.oauth) {
+      throw new BadRequestException('Integration does not support OAuth');
+    }
+
+    const oauthConfig = provider.getOAuthConfig
+      ? provider.getOAuthConfig((integration.settings as Record<string, any>) ?? {})
+      : provider.definition.oauth;
+
+    const callbackUrl = this.buildCallbackUrl(integration.type);
+
+    const workspace = await this.workspaceRepo.findById(workspaceId);
+    const returnUrl = this.domainService.getWorkspaceUrl(
+      workspace ?? { hostname: null, customDomain: null },
+    );
+
+    // Per-user connects are initiated from the account connections page;
+    // workspace-scoped authorizes from the admin integrations page. A connect
+    // started elsewhere (e.g. an editor connect card) passes its own path.
+    const returnPath =
+      returnPathOverride ??
+      ((provider.definition.oauth.connectionScope ?? 'user') === 'workspace'
+        ? '/settings/integrations'
+        : '/settings/account/connections');
+
+    const state = this.createSignedState({
+      integrationId,
+      type: integration.type,
+      userId,
+      workspaceId,
+      returnUrl,
+      returnPath,
+      exp: Date.now() + 10 * 60 * 1000,
+    });
+
+    const params = new URLSearchParams({
+      client_id: this.getClientId(integration.type),
+      redirect_uri: callbackUrl,
+      response_type: 'code',
+      state,
+    });
+
+    const scope = oauthConfig.scopes
+      .map((s) => encodeURIComponent(s))
+      .join('%20');
+
+    return {
+      authorizationUrl: `${oauthConfig.authUrl}?${params.toString()}&scope=${scope}`,
+    };
+  }
+
+  /**
+   * Install-and-authorize: the install flow for every OAuth provider.
+   *
+   * Skips creating the integration row up front. The callback persists it
+   * only after a successful token exchange, so a cancelled consent screen or
+   * misconfigured client credentials leave nothing half-installed. Refusing
+   * the already-installed case here keeps the install button idempotent.
+   */
+  async getInstallAuthorizationUrl(
+    type: string,
+    workspaceId: string,
+    userId: string,
+  ): Promise<{ authorizationUrl: string }> {
+    const provider = this.registry.getProvider(type);
+    if (!provider || !provider.definition.oauth) {
+      throw new BadRequestException('Integration does not support OAuth');
+    }
+
+    const existing = await this.integrationRepo.findByWorkspaceAndType(
+      workspaceId,
+      type,
+    );
+    if (existing) {
+      throw new BadRequestException(
+        `Integration "${type}" is already installed`,
+      );
+    }
+
+    const oauthConfig = provider.getOAuthConfig
+      ? provider.getOAuthConfig({})
+      : provider.definition.oauth;
+
+    const callbackUrl = this.buildCallbackUrl(type);
+
+    const workspace = await this.workspaceRepo.findById(workspaceId);
+    const returnUrl = this.domainService.getWorkspaceUrl(
+      workspace ?? { hostname: null, customDomain: null },
+    );
+
+    const state = this.createSignedState({
+      integrationId: null,
+      type,
+      userId,
+      workspaceId,
+      returnUrl,
+      returnPath: '/settings/integrations',
+      exp: Date.now() + 10 * 60 * 1000,
+    });
+
+    const params = new URLSearchParams({
+      client_id: this.getClientId(type),
+      redirect_uri: callbackUrl,
+      response_type: 'code',
+      state,
+    });
+
+    const scope = oauthConfig.scopes
+      .map((s) => encodeURIComponent(s))
+      .join('%20');
+
+    return {
+      authorizationUrl: `${oauthConfig.authUrl}?${params.toString()}&scope=${scope}`,
+    };
+  }
+
+  verifySignedState(state: string): OAuthStatePayload | null {
+    const dotIndex = state.lastIndexOf('.');
+    if (dotIndex === -1) return null;
+
+    const data = state.substring(0, dotIndex);
+    const signature = state.substring(dotIndex + 1);
+
+    const secret = this.environmentService.getAppSecret();
+    const expected = crypto
+      .createHmac('sha256', secret)
+      .update(data)
+      .digest('base64url');
+
+    if (signature !== expected) return null;
+
+    try {
+      const payload: OAuthStatePayload = JSON.parse(
+        Buffer.from(data, 'base64url').toString(),
+      );
+
+      if (payload.exp < Date.now()) return null;
+
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+
+  async exchangeCodeForTokens(
+    type: string,
+    code: string,
+    integrationId: string | null,
+    userId: string,
+    workspaceId: string,
+  ): Promise<IntegrationConnection> {
+    const provider = this.registry.getProvider(type);
+    if (!provider || !provider.definition.oauth) {
+      throw new BadRequestException('Integration does not support OAuth');
+    }
+
+    // Install flow: no row yet; persisted only after the token exchange succeeds.
+    let integration = integrationId
+      ? await this.integrationRepo.findById(integrationId)
+      : null;
+
+    const settings = (integration?.settings as Record<string, any>) ?? {};
+
+    const oauthConfig = provider.getOAuthConfig
+      ? provider.getOAuthConfig(settings)
+      : provider.definition.oauth;
+
+    const tokenResponse = await this.requestTokens(
+      oauthConfig,
+      type,
+      code,
+    );
+
+    if (!integration) {
+      integration = await this.integrationRepo.insertOrRestore({
+        type,
+        workspaceId,
+        installedById: userId,
+      });
+      integrationId = integration.id;
+    }
+
+    const encryptedAccessToken = this.encryptionService.encrypt(
+      tokenResponse.access_token,
+    );
+    const encryptedRefreshToken = tokenResponse.refresh_token
+      ? this.encryptionService.encrypt(tokenResponse.refresh_token)
+      : null;
+
+    const tokenExpiresAt = tokenResponse.expires_in
+      ? new Date(Date.now() + tokenResponse.expires_in * 1000)
+      : null;
+
+    const connectionScope =
+      provider.definition.oauth?.connectionScope ?? 'user';
+
+    const connection =
+      connectionScope === 'workspace'
+        ? await this.connectionRepo.upsertWorkspaceConnection({
+            integrationId,
+            userId,
+            workspaceId,
+            accessToken: encryptedAccessToken,
+            refreshToken: encryptedRefreshToken,
+            tokenExpiresAt,
+            scopes: tokenResponse.scope ?? null,
+          })
+        : await this.connectionRepo.upsert({
+            integrationId,
+            userId,
+            workspaceId,
+            accessToken: encryptedAccessToken,
+            refreshToken: encryptedRefreshToken,
+            tokenExpiresAt,
+            scopes: tokenResponse.scope ?? null,
+          });
+
+    if (provider.onConnected) {
+      await provider.onConnected({
+        integrationId,
+        workspaceId,
+        accessToken: tokenResponse.access_token,
+        refreshToken: tokenResponse.refresh_token,
+        userId,
+        metadata: tokenResponse,
+      });
+    }
+
+    return connection;
+  }
+
+  async getValidAccessToken(
+    connection: IntegrationConnection,
+  ): Promise<string> {
+    if (connection.invalidatedAt) {
+      throw new TokenInvalidError();
+    }
+    const accessToken = this.encryptionService.decrypt(connection.accessToken);
+
+    const needsRefresh =
+      connection.tokenExpiresAt &&
+      connection.refreshToken &&
+      new Date(connection.tokenExpiresAt).getTime() - Date.now() < 5 * 60 * 1000;
+
+    if (!needsRefresh) {
+      return accessToken;
+    }
+
+    return this.refreshAccessToken(connection);
+  }
+
+  private async refreshAccessToken(
+    connection: IntegrationConnection,
+  ): Promise<string> {
+    const refreshToken = this.encryptionService.decrypt(
+      connection.refreshToken,
+    );
+
+    const integration = await this.integrationRepo.findById(
+      connection.integrationId,
+    );
+    if (!integration) {
+      throw new NotFoundException('Integration not found');
+    }
+
+    const provider = this.registry.getProvider(integration.type);
+    if (!provider || !provider.definition.oauth) {
+      throw new BadRequestException('Integration does not support OAuth');
+    }
+
+    const oauthConfig = provider.getOAuthConfig
+      ? provider.getOAuthConfig((integration.settings as Record<string, any>) ?? {})
+      : provider.definition.oauth;
+
+    const params = new URLSearchParams({
+      grant_type: 'refresh_token',
+      client_id: this.getClientId(integration.type),
+      client_secret: this.getClientSecret(integration.type),
+      refresh_token: refreshToken,
+    });
+
+    try {
+      const response = await proxyFetch(oauthConfig.tokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: params.toString(),
+        signal: AbortSignal.timeout(OAUTH_HTTP_TIMEOUT_MS),
+      });
+
+      if (!response.ok) {
+        this.logger.error(
+          `Token refresh failed for ${integration.type}: ${response.status}`,
+        );
+        // 400/401 from the token endpoint means invalid_grant/invalid_client:
+        // the refresh token is dead, not a transient failure.
+        if (response.status === 400 || response.status === 401) {
+          throw new TokenInvalidError(
+            `Refresh token rejected for ${integration.type}`,
+          );
+        }
+        throw new BadRequestException('Token refresh failed');
+      }
+
+      const data: OAuthTokenResponse = await response.json();
+      const encryptedAccessToken = this.encryptionService.encrypt(
+        data.access_token,
+      );
+      const encryptedRefreshToken = data.refresh_token
+        ? this.encryptionService.encrypt(data.refresh_token)
+        : connection.refreshToken;
+      const tokenExpiresAt = data.expires_in
+        ? new Date(Date.now() + data.expires_in * 1000)
+        : null;
+
+      await this.connectionRepo.update(connection.id, {
+        accessToken: encryptedAccessToken,
+        refreshToken: encryptedRefreshToken,
+        tokenExpiresAt,
+        invalidatedAt: null,
+      });
+
+      return data.access_token;
+    } catch (err) {
+      if (err instanceof TokenInvalidError) {
+        throw err;
+      }
+      this.logger.error(`Token refresh error: ${(err as Error).message}`);
+      throw new BadRequestException('Failed to refresh token');
+    }
+  }
+
+  private async requestTokens(
+    oauthConfig: OAuthConfig,
+    type: string,
+    code: string,
+  ): Promise<OAuthTokenResponse> {
+    const params = new URLSearchParams({
+      grant_type: 'authorization_code',
+      client_id: this.getClientId(type),
+      client_secret: this.getClientSecret(type),
+      code,
+      redirect_uri: this.buildCallbackUrl(type),
+    });
+
+    const response = await proxyFetch(oauthConfig.tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+      body: params.toString(),
+      signal: AbortSignal.timeout(OAUTH_HTTP_TIMEOUT_MS),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`Token exchange failed for ${type}: ${response.status} ${body}`);
+      throw new BadRequestException('OAuth token exchange failed');
+    }
+
+    return response.json();
+  }
+
+  buildCallbackUrl(type: string): string {
+    const appUrl = this.environmentService.getAppUrl();
+    return `${appUrl}/api/integrations/oauth/${type}/callback`;
+  }
+
+  private createSignedState(payload: OAuthStatePayload): string {
+    const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const secret = this.environmentService.getAppSecret();
+    const signature = crypto
+      .createHmac('sha256', secret)
+      .update(data)
+      .digest('base64url');
+    return `${data}.${signature}`;
+  }
+
+  private getClientId(type: string): string {
+    const envKey = `INTEGRATION_${type.toUpperCase()}_CLIENT_ID`;
+    const value = process.env[envKey];
+    if (!value) {
+      throw new BadRequestException(
+        `Missing environment variable: ${envKey}`,
+      );
+    }
+    return value;
+  }
+
+  private getClientSecret(type: string): string {
+    const envKey = `INTEGRATION_${type.toUpperCase()}_CLIENT_SECRET`;
+    const value = process.env[envKey];
+    if (!value) {
+      throw new BadRequestException(
+        `Missing environment variable: ${envKey}`,
+      );
+    }
+    return value;
+  }
+}

apps/server/src/core/integration/providers/github/github-patterns.ts

@@ -0,0 +1,72 @@
+import { UnfurlPattern } from '../../registry/integration-provider.interface';
+
+function escapeForRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function buildGitHubPatterns(baseUrl: string): UnfurlPattern[] {
+  const escaped = escapeForRegex(baseUrl);
+  return [
+    // Commit within a PR: /:owner/:repo/pull/:num/commits/:sha
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/pull\\/(\\d+)\\/commits\\/([a-f0-9]+)`,
+      ),
+      type: 'github-pr-commit',
+    },
+    // PR sub-pages: /:owner/:repo/pull/:num(/checks|/commits|/files)?
+    {
+      regex: new RegExp(`^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/pull\\/(\\d+)`),
+      type: 'github-pr',
+    },
+    // Single issue: /:owner/:repo/issues/:num
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/issues\\/(\\d+)`,
+      ),
+      type: 'github-issue',
+    },
+    // Commit: /:owner/:repo/commit(s)/:sha
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/commits?\\/([a-f0-9]+)`,
+      ),
+      type: 'github-commit',
+    },
+    // File/blob: /:owner/:repo/blob/:ref/:path(#L:start(-L:end))?
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/blob\\/([^\\/]+)\\/(.+?)(?:#L(\\d+)(?:-L(\\d+))?)?$`,
+      ),
+      type: 'github-file',
+    },
+    // Pulls list: /:owner/:repo/pulls
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/pulls(?:\\/.*)?(?:\\?.*)?$`,
+      ),
+      type: 'github-pulls-list',
+    },
+    // Issues list: /:owner/:repo/issues(/created_by/...|/assigned/...)?
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/issues(?:\\/(?:created_by|assigned)\\/[\\w.\\/-]+)?\\/?(?:\\?.*)?$`,
+      ),
+      type: 'github-issues-list',
+    },
+    // Releases: /:owner/:repo/releases
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([^\\/]+)\\/([^\\/]+)\\/releases(?:\\/.*)?(?:\\?.*)?$`,
+      ),
+      type: 'github-releases-list',
+    },
+    // Repo: /:owner/:repo
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([a-zA-Z0-9\\-_.]+)\\/([a-zA-Z0-9\\-_.]+)\\/?$`,
+      ),
+      type: 'github-repo',
+    },
+  ];
+}

apps/server/src/core/integration/providers/github/github.module.ts

@@ -0,0 +1,21 @@
+import { Module, OnModuleInit } from '@nestjs/common';
+import { GitHubProvider } from './github.provider';
+import { GitHubService } from './github.service';
+import { IntegrationRegistry } from '../../registry/integration-registry';
+import { IntegrationModule } from '../../integration.module';
+
+@Module({
+  imports: [IntegrationModule],
+  providers: [GitHubProvider, GitHubService],
+  exports: [GitHubProvider],
+})
+export class GitHubModule implements OnModuleInit {
+  constructor(
+    private readonly registry: IntegrationRegistry,
+    private readonly githubProvider: GitHubProvider,
+  ) {}
+
+  onModuleInit() {
+    this.registry.register(this.githubProvider);
+  }
+}

apps/server/src/core/integration/providers/github/github.provider.ts

@@ -0,0 +1,154 @@
+import { Injectable } from '@nestjs/common';
+import {
+  IntegrationProvider,
+  IntegrationDefinition,
+  LinkDescription,
+  OAuthConfig,
+  UnfurlPattern,
+  UnfurlOpts,
+  UnfurlResult,
+} from '../../registry/integration-provider.interface';
+import { GitHubService } from './github.service';
+import { buildGitHubPatterns } from './github-patterns';
+
+const DEFAULT_BASE_URL = 'https://github.com';
+
+@Injectable()
+export class GitHubProvider extends IntegrationProvider {
+  definition: IntegrationDefinition = {
+    type: 'github',
+    name: 'GitHub',
+    description: 'Link previews for repos, pull requests, issues, commits, and files',
+    icon: 'github',
+    capabilities: ['oauth', 'unfurl'],
+    oauth: {
+      authUrl: 'https://github.com/login/oauth/authorize',
+      tokenUrl: 'https://github.com/login/oauth/access_token',
+      scopes: ['repo', 'read:user'],
+    },
+    unfurlPatterns: buildGitHubPatterns('https://github.com'),
+  };
+
+  constructor(private readonly githubService: GitHubService) {
+    super();
+  }
+
+  getOAuthConfig(settings: Record<string, any>): OAuthConfig {
+    const baseUrl = this.resolveBaseUrl();
+    return {
+      authUrl: `${baseUrl}/login/oauth/authorize`,
+      tokenUrl: `${baseUrl}/login/oauth/access_token`,
+      scopes: ['repo', 'read:user'],
+    };
+  }
+
+  getUnfurlPatterns(settings: Record<string, any>): UnfurlPattern[] {
+    const baseUrl = this.resolveBaseUrl();
+    if (baseUrl === DEFAULT_BASE_URL) return [];
+    return buildGitHubPatterns(baseUrl);
+  }
+
+  async unfurl(opts: UnfurlOpts): Promise<UnfurlResult> {
+    const { match, patternType, accessToken, url } = opts;
+    const apiBaseUrl = this.resolveApiBaseUrl(url);
+    const owner = match[1];
+    const repo = match[2];
+
+    switch (patternType) {
+      case 'github-pr': {
+        const number = parseInt(match[3], 10);
+        return this.githubService.unfurlPullRequest(
+          accessToken, apiBaseUrl, owner, repo, number, url,
+        );
+      }
+
+      case 'github-issue': {
+        const number = parseInt(match[3], 10);
+        return this.githubService.unfurlIssue(
+          accessToken, apiBaseUrl, owner, repo, number, url,
+        );
+      }
+
+      case 'github-repo':
+        return this.githubService.unfurlRepo(
+          accessToken, apiBaseUrl, owner, repo, url,
+        );
+
+      case 'github-commit': {
+        const sha = match[3];
+        return this.githubService.unfurlCommit(
+          accessToken, apiBaseUrl, owner, repo, sha, url,
+        );
+      }
+
+      case 'github-pr-commit': {
+        const sha = match[4];
+        return this.githubService.unfurlCommit(
+          accessToken, apiBaseUrl, owner, repo, sha, url,
+        );
+      }
+
+      case 'github-file': {
+        const ref = match[3];
+        const path = match[4];
+        const startLine = match[5] ? parseInt(match[5], 10) : undefined;
+        const endLine = match[6] ? parseInt(match[6], 10) : undefined;
+        return this.githubService.unfurlFile(
+          owner, repo, ref, path, startLine, endLine, url,
+        );
+      }
+
+      case 'github-pulls-list':
+      case 'github-issues-list':
+      case 'github-releases-list':
+        return this.githubService.unfurlCollectionPage(
+          accessToken, apiBaseUrl, owner, repo, patternType.replace('github-', ''), url,
+        );
+
+      default:
+        throw new Error(`Unknown GitHub pattern type: ${patternType}`);
+    }
+  }
+
+  describeLink(
+    patternType: string,
+    match: RegExpMatchArray,
+  ): LinkDescription | null {
+    const repo = `${match[1]}/${match[2]}`;
+    switch (patternType) {
+      case 'github-pr':
+        return { title: `Pull Request #${match[3]}`, description: repo };
+      case 'github-pr-commit':
+        return { title: `Commit ${match[4].slice(0, 7)}`, description: repo };
+      case 'github-issue':
+        return { title: `Issue #${match[3]}`, description: repo };
+      case 'github-commit':
+        return { title: `Commit ${match[3].slice(0, 7)}`, description: repo };
+      case 'github-file':
+        return { title: match[4], description: repo };
+      case 'github-pulls-list':
+        return { title: 'Pull Requests', description: repo };
+      case 'github-issues-list':
+        return { title: 'Issues', description: repo };
+      case 'github-releases-list':
+        return { title: 'Releases', description: repo };
+      case 'github-repo':
+        return { title: repo };
+      default:
+        return null;
+    }
+  }
+
+  private resolveBaseUrl(): string {
+    const baseUrl = process.env.INTEGRATION_GITHUB_BASE_URL;
+    return baseUrl ? baseUrl.replace(/\/+$/, '') : DEFAULT_BASE_URL;
+  }
+
+  private resolveApiBaseUrl(url: string): string {
+    const parsed = new URL(url);
+    if (parsed.hostname === 'github.com') {
+      return 'https://api.github.com';
+    }
+    return `${parsed.origin}/api/v3`;
+  }
+}

apps/server/src/core/integration/providers/github/github.service.ts

@@ -0,0 +1,267 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { UnfurlResult } from '../../registry/integration-provider.interface';
+import { relativeTime } from '../../utils/relative-time';
+import { providerApiFetch } from '../../utils/provider-fetch';
+
+@Injectable()
+export class GitHubService {
+  private readonly logger = new Logger(GitHubService.name);
+
+  async unfurlPullRequest(
+    accessToken: string,
+    apiBaseUrl: string,
+    owner: string,
+    repo: string,
+    number: number,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/repos/${owner}/${repo}/pulls/${number}`,
+    );
+
+    const prAuthor = data.user?.login;
+    const prDesc = [
+      `#${data.number}`,
+      relativeTime(data.updated_at ?? data.created_at),
+      prAuthor,
+    ].filter(Boolean).join(' · ');
+
+    return {
+      title: data.title,
+      description: prDesc,
+      url,
+      provider: 'github',
+      providerIcon: 'github',
+      status: this.formatPrStatus(data),
+      statusColor: this.getPrStatusColor(data),
+      author: prAuthor,
+      authorAvatarUrl: data.user?.avatar_url,
+      metadata: {
+        type: 'pr',
+        number: data.number,
+        repo: `${owner}/${repo}`,
+        labels: data.labels?.map((l: any) => l.name) ?? [],
+        draft: data.draft,
+        additions: data.additions,
+        deletions: data.deletions,
+      },
+    };
+  }
+
+  async unfurlIssue(
+    accessToken: string,
+    apiBaseUrl: string,
+    owner: string,
+    repo: string,
+    number: number,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/repos/${owner}/${repo}/issues/${number}`,
+    );
+
+    const issueAuthor = data.user?.login;
+    const issueDesc = [
+      `#${data.number}`,
+      relativeTime(data.updated_at ?? data.created_at),
+      issueAuthor,
+    ].filter(Boolean).join(' · ');
+
+    return {
+      title: data.title,
+      description: issueDesc,
+      url,
+      provider: 'github',
+      providerIcon: 'github',
+      status: data.state,
+      statusColor: data.state === 'open' ? 'green' : 'purple',
+      author: issueAuthor,
+      authorAvatarUrl: data.user?.avatar_url,
+      metadata: {
+        type: 'issue',
+        number: data.number,
+        repo: `${owner}/${repo}`,
+        labels: data.labels?.map((l: any) => l.name) ?? [],
+        assignees: data.assignees?.map((a: any) => a.login) ?? [],
+      },
+    };
+  }
+
+  async unfurlRepo(
+    accessToken: string,
+    apiBaseUrl: string,
+    owner: string,
+    repo: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/repos/${owner}/${repo}`,
+    );
+
+    const visibility = data.private ? 'Private' : 'Public';
+
+    return {
+      title: data.full_name,
+      description: data.description?.slice(0, 200) ?? undefined,
+      url,
+      provider: 'github',
+      providerIcon: 'github',
+      status: visibility,
+      statusColor: data.private ? 'gray' : 'green',
+      author: data.owner?.login,
+      authorAvatarUrl: data.owner?.avatar_url,
+      metadata: {
+        type: 'repo',
+        repo: `${owner}/${repo}`,
+        stars: data.stargazers_count,
+        forks: data.forks_count,
+        language: data.language,
+        defaultBranch: data.default_branch,
+      },
+    };
+  }
+
+  async unfurlCommit(
+    accessToken: string,
+    apiBaseUrl: string,
+    owner: string,
+    repo: string,
+    sha: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/repos/${owner}/${repo}/commits/${sha}`,
+    );
+
+    const shortSha = data.sha?.slice(0, 7);
+
+    const commitAuthor = data.author?.login ?? data.commit?.author?.name;
+    const commitDesc = [
+      shortSha,
+      relativeTime(data.commit?.author?.date ?? data.commit?.committer?.date),
+      commitAuthor,
+    ].filter(Boolean).join(' · ');
+
+    return {
+      title: data.commit?.message?.split('\n')[0] ?? shortSha,
+      description: commitDesc,
+      url,
+      provider: 'github',
+      providerIcon: 'github',
+      author: commitAuthor,
+      authorAvatarUrl: data.author?.avatar_url,
+      metadata: {
+        type: 'commit',
+        sha: data.sha,
+        shortSha,
+        repo: `${owner}/${repo}`,
+        stats: data.stats,
+      },
+    };
+  }
+
+  unfurlFile(
+    owner: string,
+    repo: string,
+    ref: string,
+    path: string,
+    startLine: number | undefined,
+    endLine: number | undefined,
+    url: string,
+  ): UnfurlResult {
+    const fileName = path.split('/').pop() ?? path;
+    const lineRange = startLine
+      ? endLine
+        ? `L${startLine}-L${endLine}`
+        : `L${startLine}`
+      : undefined;
+
+    return {
+      title: lineRange ? `${fileName}#${lineRange}` : fileName,
+      description: `${owner}/${repo} · ${ref.slice(0, 7)}`,
+      url,
+      provider: 'github',
+      providerIcon: 'github',
+      metadata: {
+        type: 'file',
+        repo: `${owner}/${repo}`,
+        ref,
+        path,
+        startLine,
+        endLine,
+      },
+    };
+  }
+
+  async unfurlCollectionPage(
+    accessToken: string,
+    apiBaseUrl: string,
+    owner: string,
+    repo: string,
+    collectionType: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/repos/${owner}/${repo}`,
+    );
+
+    const labels: Record<string, string> = {
+      'pulls-list': 'Pull Requests',
+      'issues-list': 'Issues',
+      'releases-list': 'Releases',
+    };
+
+    return {
+      title: `${labels[collectionType] ?? collectionType} · ${data.full_name}`,
+      description: `${owner}/${repo}`,
+      url,
+      provider: 'github',
+      providerIcon: 'github',
+      author: data.owner?.login,
+      authorAvatarUrl: data.owner?.avatar_url,
+      metadata: {
+        type: collectionType,
+        repo: `${owner}/${repo}`,
+      },
+    };
+  }
+
+  private formatPrStatus(pr: any): string {
+    if (pr.merged) return 'merged';
+    if (pr.draft) return 'draft';
+    return pr.state;
+  }
+
+  private getPrStatusColor(pr: any): string {
+    if (pr.merged) return 'purple';
+    if (pr.draft) return 'gray';
+    if (pr.state === 'open') return 'green';
+    return 'red';
+  }
+
+  private async apiGet(
+    accessToken: string,
+    apiBaseUrl: string,
+    path: string,
+  ): Promise<any> {
+    const response = await providerApiFetch('GitHub', `${apiBaseUrl}${path}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/vnd.github.v3+json',
+        'User-Agent': 'Docmost',
+      },
+    });
+
+    return response.json();
+  }
+}

apps/server/src/core/integration/providers/gitlab/gitlab-patterns.ts

@@ -0,0 +1,68 @@
+import { UnfurlPattern } from '../../registry/integration-provider.interface';
+
+function escapeForRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function buildGitLabPatterns(baseUrl: string): UnfurlPattern[] {
+  const escaped = escapeForRegex(baseUrl);
+  return [
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/merge_requests\\/(\\d+)\\/diffs\\?.*commit_id=([a-f0-9]+)`,
+      ),
+      type: 'gitlab-commit-in-mr',
+    },
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/merge_requests\\/(\\d+)`,
+      ),
+      type: 'gitlab-mr',
+    },
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/issues\\/(\\d+)`,
+      ),
+      type: 'gitlab-issue',
+    },
+    // Issues renamed to work items; same iid, resolved via the issues API.
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/work_items\\/(\\d+)`,
+      ),
+      type: 'gitlab-issue',
+    },
+    // Work item opened as a drawer over the list; the target is base64 JSON
+    // in the show param, decoded by the provider.
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/work_items\\/?\\?(?:.*&)?show=`,
+      ),
+      type: 'gitlab-work-item-drawer',
+    },
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/commits?\\/([a-f0-9]+)`,
+      ),
+      type: 'gitlab-commit',
+    },
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/issues(?:\\/)?(?:\\?.*)?$`,
+      ),
+      type: 'gitlab-issues-list',
+    },
+    {
+      regex: new RegExp(
+        `^${escaped}\\/(.+)\\/-\\/merge_requests(?:\\/)?(?:\\?.*)?$`,
+      ),
+      type: 'gitlab-merges-list',
+    },
+    {
+      regex: new RegExp(
+        `^${escaped}\\/([a-zA-Z0-9\\-_.]+)\\/([a-zA-Z0-9\\-_]+)\\/?$`,
+      ),
+      type: 'gitlab-project',
+    },
+  ];
+}

apps/server/src/core/integration/providers/gitlab/gitlab.module.ts

@@ -0,0 +1,21 @@
+import { Module, OnModuleInit } from '@nestjs/common';
+import { GitLabProvider } from './gitlab.provider';
+import { GitLabService } from './gitlab.service';
+import { IntegrationRegistry } from '../../registry/integration-registry';
+import { IntegrationModule } from '../../integration.module';
+
+@Module({
+  imports: [IntegrationModule],
+  providers: [GitLabProvider, GitLabService],
+  exports: [GitLabProvider],
+})
+export class GitLabModule implements OnModuleInit {
+  constructor(
+    private readonly registry: IntegrationRegistry,
+    private readonly gitlabProvider: GitLabProvider,
+  ) {}
+
+  onModuleInit() {
+    this.registry.register(this.gitlabProvider);
+  }
+}

apps/server/src/core/integration/providers/gitlab/gitlab.provider.ts

@@ -0,0 +1,188 @@
+import { Injectable } from '@nestjs/common';
+import {
+  IntegrationProvider,
+  IntegrationDefinition,
+  LinkDescription,
+  OAuthConfig,
+  UnfurlPattern,
+  UnfurlOpts,
+  UnfurlResult,
+} from '../../registry/integration-provider.interface';
+import { GitLabService } from './gitlab.service';
+import { buildGitLabPatterns } from './gitlab-patterns';
+
+const DEFAULT_BASE_URL = 'https://gitlab.com';
+
+@Injectable()
+export class GitLabProvider extends IntegrationProvider {
+  definition: IntegrationDefinition = {
+    type: 'gitlab',
+    name: 'GitLab',
+    description: 'Link previews for projects, merge requests, issues, and commits',
+    icon: 'gitlab',
+    capabilities: ['oauth', 'unfurl'],
+    oauth: {
+      authUrl: 'https://gitlab.com/oauth/authorize',
+      tokenUrl: 'https://gitlab.com/oauth/token',
+      scopes: ['read_api', 'read_user'],
+    },
+    unfurlPatterns: buildGitLabPatterns('https://gitlab.com'),
+  };
+
+  constructor(private readonly gitlabService: GitLabService) {
+    super();
+  }
+
+  getOAuthConfig(settings: Record<string, any>): OAuthConfig {
+    const baseUrl = this.resolveBaseUrl();
+    return {
+      authUrl: `${baseUrl}/oauth/authorize`,
+      tokenUrl: `${baseUrl}/oauth/token`,
+      scopes: ['read_api', 'read_user'],
+    };
+  }
+
+  getUnfurlPatterns(settings: Record<string, any>): UnfurlPattern[] {
+    const baseUrl = this.resolveBaseUrl();
+    if (baseUrl === DEFAULT_BASE_URL) return [];
+    return buildGitLabPatterns(baseUrl);
+  }
+
+  async unfurl(opts: UnfurlOpts): Promise<UnfurlResult> {
+    const { match, patternType, accessToken, url } = opts;
+    const apiBaseUrl = this.resolveApiBaseUrl(url);
+
+    switch (patternType) {
+      case 'gitlab-mr': {
+        const projectPath = match[1];
+        const iid = parseInt(match[2], 10);
+        return this.gitlabService.unfurlMergeRequest(
+          accessToken, apiBaseUrl, projectPath, iid, url,
+        );
+      }
+
+      case 'gitlab-issue': {
+        const projectPath = match[1];
+        const iid = parseInt(match[2], 10);
+        return this.gitlabService.unfurlIssue(
+          accessToken, apiBaseUrl, projectPath, iid, url,
+        );
+      }
+
+      case 'gitlab-project': {
+        const projectPath = `${match[1]}/${match[2]}`;
+        return this.gitlabService.unfurlProject(
+          accessToken, apiBaseUrl, projectPath, url,
+        );
+      }
+
+      case 'gitlab-commit': {
+        const projectPath = match[1];
+        const commitSha = match[2];
+        return this.gitlabService.unfurlCommit(
+          accessToken, apiBaseUrl, projectPath, commitSha, url,
+        );
+      }
+
+      case 'gitlab-commit-in-mr': {
+        const projectPath = match[1];
+        const commitSha = match[3];
+        return this.gitlabService.unfurlCommit(
+          accessToken, apiBaseUrl, projectPath, commitSha, url,
+        );
+      }
+
+      case 'gitlab-work-item-drawer': {
+        const target = this.decodeWorkItemShowParam(url);
+        if (!target) {
+          throw new Error('Could not decode work item show param');
+        }
+        return this.gitlabService.unfurlIssue(
+          accessToken, apiBaseUrl, target.fullPath, target.iid, url,
+        );
+      }
+
+      case 'gitlab-issues-list': {
+        const projectPath = match[1];
+        return this.gitlabService.unfurlIssuesList(
+          accessToken, apiBaseUrl, projectPath, url,
+        );
+      }
+
+      case 'gitlab-merges-list': {
+        const projectPath = match[1];
+        return this.gitlabService.unfurlMergesList(
+          accessToken, apiBaseUrl, projectPath, url,
+        );
+      }
+
+      default:
+        throw new Error(`Unknown GitLab pattern type: ${patternType}`);
+    }
+  }
+
+  describeLink(
+    patternType: string,
+    match: RegExpMatchArray,
+    url: string,
+  ): LinkDescription | null {
+    const projectPath = match[1];
+    switch (patternType) {
+      case 'gitlab-mr':
+        return { title: `Merge Request !${match[2]}`, description: projectPath };
+      case 'gitlab-issue':
+        return { title: `Issue #${match[2]}`, description: projectPath };
+      case 'gitlab-work-item-drawer': {
+        const target = this.decodeWorkItemShowParam(url);
+        return target
+          ? { title: `Issue #${target.iid}`, description: target.fullPath }
+          : { title: 'Work item', description: projectPath };
+      }
+      case 'gitlab-commit':
+        return { title: `Commit ${match[2].slice(0, 8)}`, description: projectPath };
+      case 'gitlab-commit-in-mr':
+        return { title: `Commit ${match[3].slice(0, 8)}`, description: projectPath };
+      case 'gitlab-issues-list':
+        return { title: 'Issues', description: projectPath };
+      case 'gitlab-merges-list':
+        return { title: 'Merge Requests', description: projectPath };
+      case 'gitlab-project':
+        return { title: `${match[1]}/${match[2]}` };
+      default:
+        return null;
+    }
+  }
+
+  // The work items list opens an item as a drawer and encodes it in the URL
+  // as ?show=base64({ iid, full_path, id }). full_path beats the URL path:
+  // a drawer opened from a group-level list still names the actual project.
+  private decodeWorkItemShowParam(
+    url: string,
+  ): { fullPath: string; iid: number } | null {
+    try {
+      const show = new URL(url).searchParams.get('show');
+      if (!show) return null;
+      const base64 = show.replace(/-/g, '+').replace(/_/g, '/');
+      const payload = JSON.parse(
+        Buffer.from(base64, 'base64').toString('utf8'),
+      );
+      const iid = parseInt(payload.iid, 10);
+      if (typeof payload.full_path !== 'string' || Number.isNaN(iid)) {
+        return null;
+      }
+      return { fullPath: payload.full_path, iid };
+    } catch {
+      return null;
+    }
+  }
+
+  private resolveBaseUrl(): string {
+    const baseUrl = process.env.INTEGRATION_GITLAB_BASE_URL;
+    return baseUrl ? baseUrl.replace(/\/+$/, '') : DEFAULT_BASE_URL;
+  }
+
+  private resolveApiBaseUrl(url: string): string {
+    const parsed = new URL(url);
+    return `${parsed.origin}/api/v4`;
+  }
+}

apps/server/src/core/integration/providers/gitlab/gitlab.service.ts

@@ -0,0 +1,253 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { UnfurlResult } from '../../registry/integration-provider.interface';
+import { relativeTime } from '../../utils/relative-time';
+import { providerApiFetch } from '../../utils/provider-fetch';
+
+@Injectable()
+export class GitLabService {
+  private readonly logger = new Logger(GitLabService.name);
+
+  async unfurlMergeRequest(
+    accessToken: string,
+    apiBaseUrl: string,
+    projectPath: string,
+    iid: number,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const encodedProject = encodeURIComponent(projectPath);
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/projects/${encodedProject}/merge_requests/${iid}`,
+    );
+
+    const authorName = data.author?.name ?? data.author?.username;
+    const desc = [
+      `!${data.iid}`,
+      relativeTime(data.updated_at ?? data.created_at),
+      authorName,
+    ].filter(Boolean).join(' · ');
+
+    return {
+      title: data.title,
+      description: desc,
+      url,
+      provider: 'gitlab',
+      providerIcon: 'gitlab',
+      status: this.formatMrStatus(data),
+      statusColor: this.getMrStatusColor(data),
+      author: authorName,
+      authorAvatarUrl: data.author?.avatar_url,
+      metadata: {
+        type: 'mr',
+        iid: data.iid,
+        project: projectPath,
+        labels: data.labels ?? [],
+        draft: data.draft ?? data.work_in_progress,
+      },
+    };
+  }
+
+  async unfurlIssue(
+    accessToken: string,
+    apiBaseUrl: string,
+    projectPath: string,
+    iid: number,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const encodedProject = encodeURIComponent(projectPath);
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/projects/${encodedProject}/issues/${iid}`,
+    );
+
+    const issueAuthor = data.author?.name ?? data.author?.username;
+    const issueDesc = [
+      `#${data.iid}`,
+      relativeTime(data.updated_at ?? data.created_at),
+      issueAuthor,
+    ].filter(Boolean).join(' · ');
+
+    return {
+      title: data.title,
+      description: issueDesc,
+      url,
+      provider: 'gitlab',
+      providerIcon: 'gitlab',
+      status: data.state,
+      statusColor: data.state === 'opened' ? 'green' : 'blue',
+      author: issueAuthor,
+      authorAvatarUrl: data.author?.avatar_url,
+      metadata: {
+        type: 'issue',
+        iid: data.iid,
+        project: projectPath,
+        labels: data.labels ?? [],
+        assignees:
+          data.assignees?.map((a: any) => a.name ?? a.username) ?? [],
+      },
+    };
+  }
+
+  async unfurlProject(
+    accessToken: string,
+    apiBaseUrl: string,
+    projectPath: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const encodedProject = encodeURIComponent(projectPath);
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/projects/${encodedProject}`,
+    );
+
+    const visibility = data.visibility === 'public' ? 'Public' : data.visibility === 'internal' ? 'Internal' : 'Private';
+
+    return {
+      title: data.name,
+      description: data.description?.slice(0, 200) ?? undefined,
+      url,
+      provider: 'gitlab',
+      providerIcon: 'gitlab',
+      status: visibility,
+      statusColor: data.visibility === 'public' ? 'green' : 'gray',
+      author: data.namespace?.name,
+      authorAvatarUrl: data.avatar_url ?? data.namespace?.avatar_url,
+      metadata: {
+        type: 'project',
+        project: projectPath,
+        stars: data.star_count,
+        forks: data.forks_count,
+        defaultBranch: data.default_branch,
+      },
+    };
+  }
+
+  async unfurlCommit(
+    accessToken: string,
+    apiBaseUrl: string,
+    projectPath: string,
+    commitSha: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const encodedProject = encodeURIComponent(projectPath);
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/projects/${encodedProject}/repository/commits/${commitSha}`,
+    );
+
+    const shortSha = data.short_id ?? data.id?.slice(0, 8);
+
+    const commitDesc = [
+      shortSha,
+      relativeTime(data.committed_date ?? data.created_at),
+      data.author_name,
+    ].filter(Boolean).join(' · ');
+
+    return {
+      title: data.title ?? data.message?.split('\n')[0],
+      description: commitDesc,
+      url,
+      provider: 'gitlab',
+      providerIcon: 'gitlab',
+      author: data.author_name,
+      authorAvatarUrl: undefined,
+      metadata: {
+        type: 'commit',
+        sha: data.id,
+        shortSha,
+        project: projectPath,
+        stats: data.stats,
+      },
+    };
+  }
+
+  async unfurlIssuesList(
+    accessToken: string,
+    apiBaseUrl: string,
+    projectPath: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const encodedProject = encodeURIComponent(projectPath);
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/projects/${encodedProject}?statistics=false`,
+    );
+
+    return {
+      title: `Issues · ${data.name}`,
+      description: projectPath,
+      url,
+      provider: 'gitlab',
+      providerIcon: 'gitlab',
+      author: data.namespace?.name,
+      authorAvatarUrl: data.avatar_url ?? data.namespace?.avatar_url,
+      metadata: {
+        type: 'issues-list',
+        project: projectPath,
+        openIssuesCount: data.open_issues_count,
+      },
+    };
+  }
+
+  async unfurlMergesList(
+    accessToken: string,
+    apiBaseUrl: string,
+    projectPath: string,
+    url: string,
+  ): Promise<UnfurlResult> {
+    const encodedProject = encodeURIComponent(projectPath);
+    const data = await this.apiGet(
+      accessToken,
+      apiBaseUrl,
+      `/projects/${encodedProject}?statistics=false`,
+    );
+
+    return {
+      title: `Merge Requests · ${data.name}`,
+      description: projectPath,
+      url,
+      provider: 'gitlab',
+      providerIcon: 'gitlab',
+      author: data.namespace?.name,
+      authorAvatarUrl: data.avatar_url ?? data.namespace?.avatar_url,
+      metadata: {
+        type: 'merges-list',
+        project: projectPath,
+      },
+    };
+  }
+
+  private formatMrStatus(mr: any): string {
+    if (mr.state === 'merged') return 'merged';
+    if (mr.draft || mr.work_in_progress) return 'draft';
+    return mr.state;
+  }
+
+  private getMrStatusColor(mr: any): string {
+    if (mr.state === 'merged') return 'purple';
+    if (mr.draft || mr.work_in_progress) return 'gray';
+    if (mr.state === 'opened') return 'green';
+    if (mr.state === 'closed') return 'red';
+    return 'gray';
+  }
+
+  private async apiGet(
+    accessToken: string,
+    apiBaseUrl: string,
+    path: string,
+  ): Promise<any> {
+    const response = await providerApiFetch('GitLab', `${apiBaseUrl}${path}`, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+      },
+    });
+
+    return response.json();
+  }
+}

apps/server/src/core/integration/registry/integration-provider.interface.ts

@@ -0,0 +1,169 @@
+export type IntegrationCapability = 'oauth' | 'unfurl' | 'actions';
+
+export type OAuthConfig = {
+  authUrl: string;
+  tokenUrl: string;
+  scopes: string[];
+  // 'workspace' = one shared bot/app connection per integration (Slack model);
+  // 'user' (default) = each Docmost user OAuths separately and gets their own token (Linear, Jira, GitHub model)
+  connectionScope?: 'workspace' | 'user';
+};
+
+export type UnfurlPattern = {
+  regex: RegExp;
+  type: string;
+};
+
+export type UnfurlResult = {
+  title: string;
+  description?: string;
+  url: string;
+  provider: string;
+  providerIcon?: string;
+  status?: string;
+  statusColor?: string;
+  author?: string;
+  authorAvatarUrl?: string;
+  metadata?: Record<string, any>;
+};
+
+export type IntegrationDefinition = {
+  type: string;
+  name: string;
+  description: string;
+  icon: string;
+  capabilities: IntegrationCapability[];
+  oauth?: OAuthConfig;
+  unfurlPatterns?: UnfurlPattern[];
+  // Kept out of the available list and refused for install; existing
+  // installations keep unfurling.
+  hidden?: boolean;
+  // Install requires the INTEGRATIONS license feature; unset = free.
+  requiresLicense?: boolean;
+};
+
+export type ConnectedEvent = {
+  integrationId: string;
+  workspaceId: string;
+  accessToken: string;
+  refreshToken?: string;
+  // The Docmost user who completed the OAuth flow (installer for
+  // workspace-scoped providers).
+  userId: string;
+  metadata: Record<string, any>;
+};
+
+export type HandleEventOpts = {
+  eventName: string;
+  payload: Record<string, any>;
+  integration: {
+    id: string;
+    type: string;
+    settings: Record<string, any> | null;
+  };
+  connection?: {
+    accessToken: string;
+    userId: string;
+  };
+};
+
+export type UnfurlOpts = {
+  url: string;
+  accessToken: string;
+  match: RegExpMatchArray;
+  patternType: string;
+  settings?: Record<string, any>;
+  // The requesting Docmost user and integration. Providers backed by a shared
+  // (workspace) connection MUST authorize the requester against the target
+  // resource before returning content: the shared bot token is not itself
+  // proof that the requester may see it.
+  userId: string;
+  integrationId: string;
+};
+
+// Thrown by a provider's unfurl() when the requesting user is not authorized
+// to view the linked resource. UnfurlService turns it into a null result
+// (no card) rather than logging it as an error.
+export class UnfurlForbiddenError extends Error {
+  constructor(message = 'Not authorized to unfurl this link') {
+    super(message);
+    this.name = 'UnfurlForbiddenError';
+  }
+}
+
+// Thrown by a provider's unfurl() when the requesting user has no usable
+// identity with the provider yet (e.g. no Slack account link). UnfurlService
+// turns it into a needs-connection response, unlike UnfurlForbiddenError
+// which stays a silent null.
+export class UnfurlNeedsConnectionError extends Error {
+  constructor(message = 'User has not connected this integration') {
+    super(message);
+    this.name = 'UnfurlNeedsConnectionError';
+  }
+}
+
+// Thrown when the provider definitively rejects the stored credential (API 401,
+// or invalid_grant at the token endpoint). Callers retire the connection.
+export class TokenInvalidError extends Error {
+  constructor(message = 'Integration credential is no longer valid') {
+    super(message);
+    this.name = 'TokenInvalidError';
+  }
+}
+
+export class ProviderApiError extends Error {
+  constructor(
+    readonly provider: string,
+    readonly status: number,
+    statusText = '',
+  ) {
+    super(`${provider} API error: ${status} ${statusText}`.trimEnd());
+    this.name = 'ProviderApiError';
+  }
+}
+
+export type LinkDescription = {
+  title: string;
+  description?: string;
+};
+
+// Returned instead of an UnfurlResult when the link needs a per-user
+// connection the requesting user does not have yet.
+export type UnfurlNeedsConnection = {
+  needsConnection: true;
+  integrationId: string;
+  integrationType: string;
+  integrationName: string;
+  // true when a Docmost-initiated OAuth flow yields a personal connection
+  // for the requesting user (all OAuth-capable providers; workspace-scoped
+  // ones bind the authorizing user's identity in onConnected).
+  oauthConnect: boolean;
+  title: string;
+  description?: string;
+};
+
+export abstract class IntegrationProvider {
+  abstract definition: IntegrationDefinition;
+
+  getOAuthConfig?(
+    workspaceSettings: Record<string, any>,
+  ): OAuthConfig;
+
+  getUnfurlPatterns?(
+    workspaceSettings: Record<string, any>,
+  ): UnfurlPattern[];
+
+  onConnected?(opts: ConnectedEvent): Promise<void>;
+
+  unfurl?(opts: UnfurlOpts): Promise<UnfurlResult>;
+
+  // Tokenless summary of a matched link (e.g. "Pull Request #13337"),
+  // shown on the connect prompt before the user has authorized.
+  describeLink?(
+    patternType: string,
+    match: RegExpMatchArray,
+    url: string,
+  ): LinkDescription | null;
+
+  handleEvent?(opts: HandleEventOpts): Promise<void>;
+}

apps/server/src/core/integration/registry/integration-registry.ts

@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+import {
+  IntegrationDefinition,
+  IntegrationProvider,
+} from './integration-provider.interface';
+
+@Injectable()
+export class IntegrationRegistry {
+  private providers = new Map<string, IntegrationProvider>();
+
+  register(provider: IntegrationProvider): void {
+    this.providers.set(provider.definition.type, provider);
+  }
+
+  getProvider(type: string): IntegrationProvider | undefined {
+    return this.providers.get(type);
+  }
+
+  getAllProviders(): IntegrationProvider[] {
+    return Array.from(this.providers.values());
+  }
+
+  getAvailableIntegrations(): IntegrationDefinition[] {
+    return this.getAllProviders()
+      .map((p) => p.definition)
+      .filter((definition) => !definition.hidden);
+  }
+
+  findUnfurlProvider(
+    url: string,
+  ): {
+    provider: IntegrationProvider;
+    match: RegExpMatchArray;
+    patternType: string;
+  } | null {
+    for (const provider of this.providers.values()) {
+      if (!provider.definition.unfurlPatterns) continue;
+      for (const pattern of provider.definition.unfurlPatterns) {
+        const match = url.match(pattern.regex);
+        if (match) {
+          return { provider, match, patternType: pattern.type };
+        }
+      }
+    }
+    return null;
+  }
+}

apps/server/src/core/integration/repos/integration-connection.repo.ts

@@ -0,0 +1,361 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { sql } from 'kysely';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import {
+  IntegrationConnection,
+  InsertableIntegrationConnection,
+  UpdatableIntegrationConnection,
+} from '@docmost/db/types/entity.types';
+import { dbOrTx } from '@docmost/db/utils';
+
+@Injectable()
+export class IntegrationConnectionRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  async findById(
+    connectionId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .selectAll()
+      .where('id', '=', connectionId)
+      .executeTakeFirst();
+  }
+
+  async findByIntegrationAndUser(
+    integrationId: string,
+    userId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .selectAll()
+      .where('integrationId', '=', integrationId)
+      .where('userId', '=', userId)
+      .executeTakeFirst();
+  }
+
+  async findByWorkspaceTypeAndUser(
+    workspaceId: string,
+    integrationType: string,
+    userId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .innerJoin(
+        'integrations',
+        'integrations.id',
+        'integrationConnections.integrationId',
+      )
+      .selectAll('integrationConnections')
+      .where('integrations.workspaceId', '=', workspaceId)
+      .where('integrations.type', '=', integrationType)
+      .where('integrations.deletedAt', 'is', null)
+      .where('integrationConnections.userId', '=', userId)
+      .executeTakeFirst();
+  }
+
+  async findByIntegration(
+    integrationId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection[]> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .selectAll()
+      .where('integrationId', '=', integrationId)
+      .execute();
+  }
+
+  async upsert(
+    connection: InsertableIntegrationConnection,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection> {
+    const db = dbOrTx(this.db, trx);
+    // The (integration_id, user_id) unique index is partial on kind='user';
+    // ON CONFLICT must repeat that predicate or Postgres cannot infer it.
+    return db
+      .insertInto('integrationConnections')
+      .values(connection)
+      .onConflict((oc) =>
+        oc
+          .columns(['integrationId', 'userId'])
+          .where(sql.ref('kind'), '=', 'user')
+          .doUpdateSet({
+            accessToken: connection.accessToken,
+            refreshToken: connection.refreshToken,
+            tokenExpiresAt: connection.tokenExpiresAt,
+            invalidatedAt: null,
+            scopes: connection.scopes,
+            providerUserId: connection.providerUserId,
+            metadata: connection.metadata,
+            updatedAt: new Date(),
+          }),
+      )
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async upsertWorkspaceConnection(
+    input: {
+      integrationId: string;
+      userId: string;
+      workspaceId: string;
+      accessToken: string;
+      refreshToken?: string | null;
+      tokenExpiresAt?: Date | null;
+      scopes?: string | null;
+    },
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection> {
+    const db = dbOrTx(this.db, trx);
+
+    const existing = await this.findWorkspaceConnection(input.integrationId, trx);
+    if (existing) {
+      return this.update(
+        existing.id,
+        {
+          accessToken: input.accessToken,
+          refreshToken: input.refreshToken ?? null,
+          tokenExpiresAt: input.tokenExpiresAt ?? null,
+          invalidatedAt: null,
+          scopes: input.scopes ?? null,
+          userId: input.userId,
+        },
+        trx,
+      );
+    }
+
+    // No need to clear other rows: the (integration_id, user_id) unique index
+    // is partial on kind='user', so a workspace insert never conflicts with
+    // the installer's user-link row.
+
+    return db
+      .insertInto('integrationConnections')
+      .values({
+        integrationId: input.integrationId,
+        userId: input.userId,
+        workspaceId: input.workspaceId,
+        accessToken: input.accessToken,
+        refreshToken: input.refreshToken ?? null,
+        tokenExpiresAt: input.tokenExpiresAt ?? null,
+        scopes: input.scopes ?? null,
+        kind: 'workspace',
+      })
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async update(
+    connectionId: string,
+    data: UpdatableIntegrationConnection,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .updateTable('integrationConnections')
+      .set({ ...data, updatedAt: new Date() })
+      .where('id', '=', connectionId)
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async deleteByIntegrationAndUser(
+    integrationId: string,
+    userId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    // Never delete a kind='workspace' row from a per-user disconnect.
+    // For Slack (and any future workspace-scoped provider) the installer's
+    // userId matches the workspace connection's userId; without this filter
+    // a single user clicking Disconnect would wipe the shared bot token and
+    // break the integration for the whole workspace. Full uninstall uses
+    // deleteByIntegration which intentionally has no kind filter.
+    await db
+      .deleteFrom('integrationConnections')
+      .where('integrationId', '=', integrationId)
+      .where('userId', '=', userId)
+      .where('kind', '!=', 'workspace')
+      .execute();
+  }
+
+  async findByUserAndWorkspace(
+    userId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ) {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .innerJoin(
+        'integrations',
+        'integrations.id',
+        'integrationConnections.integrationId',
+      )
+      .select([
+        'integrationConnections.integrationId',
+        'integrations.type',
+        'integrationConnections.providerUserId',
+        'integrationConnections.metadata',
+        'integrationConnections.createdAt',
+        'integrationConnections.invalidatedAt',
+      ])
+      .where('integrationConnections.userId', '=', userId)
+      // The workspace bot row carries the installer's userId; without this
+      // filter it renders on the connections page as a personal link.
+      .where('integrationConnections.kind', '=', 'user')
+      .where('integrations.workspaceId', '=', workspaceId)
+      .where('integrations.deletedAt', 'is', null)
+      .execute();
+  }
+
+  async findExpiringTokens(
+    expiresBeforeMs: number,
+  ): Promise<IntegrationConnection[]> {
+    const threshold = new Date(Date.now() + expiresBeforeMs);
+    return this.db
+      .selectFrom('integrationConnections')
+      .innerJoin(
+        'integrations',
+        'integrations.id',
+        'integrationConnections.integrationId',
+      )
+      .selectAll('integrationConnections')
+      .where('integrations.deletedAt', 'is', null)
+      .where('integrationConnections.invalidatedAt', 'is', null)
+      .where('integrationConnections.refreshToken', 'is not', null)
+      .where('integrationConnections.tokenExpiresAt', 'is not', null)
+      .where('integrationConnections.tokenExpiresAt', '<', threshold)
+      .execute();
+  }
+
+  // Retire a rejected credential: flag for reconnect UX, drop the dead refresh token; no-op if the row is gone.
+  async invalidate(connectionId: string): Promise<void> {
+    await this.db
+      .updateTable('integrationConnections')
+      .set({
+        invalidatedAt: new Date(),
+        refreshToken: null,
+        tokenExpiresAt: null,
+        updatedAt: new Date(),
+      })
+      .where('id', '=', connectionId)
+      .execute();
+  }
+
+  async deleteByIntegration(
+    integrationId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .deleteFrom('integrationConnections')
+      .where('integrationId', '=', integrationId)
+      .execute();
+  }
+
+  async findWorkspaceConnection(
+    integrationId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .selectAll()
+      .where('integrationId', '=', integrationId)
+      .where('kind', '=', 'workspace')
+      .executeTakeFirst();
+  }
+
+  async findUserLink(
+    integrationId: string,
+    providerUserId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .selectAll()
+      .where('integrationId', '=', integrationId)
+      .where('providerUserId', '=', providerUserId)
+      .where('kind', '=', 'user')
+      .executeTakeFirst();
+  }
+
+  async findUserLinkByUserId(
+    integrationId: string,
+    userId: string,
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrationConnections')
+      .selectAll()
+      .where('integrationId', '=', integrationId)
+      .where('userId', '=', userId)
+      .where('kind', '=', 'user')
+      .executeTakeFirst();
+  }
+
+  async deleteUserLink(
+    integrationId: string,
+    userId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .deleteFrom('integrationConnections')
+      .where('integrationId', '=', integrationId)
+      .where('userId', '=', userId)
+      .where('kind', '=', 'user')
+      .execute();
+  }
+
+  async upsertUserLink(
+    input: {
+      integrationId: string;
+      workspaceId: string;
+      userId: string;
+      providerUserId: string;
+      metadata: Record<string, unknown>;
+    },
+    trx?: KyselyTransaction,
+  ): Promise<IntegrationConnection> {
+    const db = dbOrTx(this.db, trx);
+    // Target the partial unique index uq_integration_connections_user_per_integration
+    // (integration_id, user_id) WHERE kind = 'user'. Without the .where() hint,
+    // ON CONFLICT can't match a partial index. The kind discriminator means a
+    // workspace bot row sharing (integration_id, user_id) with this user-link
+    // is no longer a conflict, so we cannot flip its kind.
+    return await db
+      .insertInto('integrationConnections')
+      .values({
+        integrationId: input.integrationId,
+        workspaceId: input.workspaceId,
+        userId: input.userId,
+        providerUserId: input.providerUserId,
+        kind: 'user',
+        metadata: input.metadata as any,
+        accessToken: null,
+      })
+      .onConflict((oc) =>
+        oc
+          .columns(['integrationId', 'userId'])
+          .where(sql.ref('kind'), '=', 'user')
+          .doUpdateSet({
+            providerUserId: input.providerUserId,
+            metadata: input.metadata as any,
+            updatedAt: new Date(),
+          }),
+      )
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+}

apps/server/src/core/integration/repos/integration.repo.ts

@@ -0,0 +1,127 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { sql } from 'kysely';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import {
+  Integration,
+  InsertableIntegration,
+  UpdatableIntegration,
+} from '@docmost/db/types/entity.types';
+import { dbOrTx } from '@docmost/db/utils';
+
+@Injectable()
+export class IntegrationRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  async findById(
+    integrationId: string,
+    trx?: KyselyTransaction,
+  ): Promise<Integration | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrations')
+      .selectAll()
+      .where('id', '=', integrationId)
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst();
+  }
+
+  async findByWorkspaceAndType(
+    workspaceId: string,
+    type: string,
+    trx?: KyselyTransaction,
+  ): Promise<Integration | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrations')
+      .selectAll()
+      .where('workspaceId', '=', workspaceId)
+      .where('type', '=', type)
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst();
+  }
+
+  async findAllByWorkspace(
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<Integration[]> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('integrations')
+      .selectAll()
+      .where('workspaceId', '=', workspaceId)
+      .where('deletedAt', 'is', null)
+      .execute();
+  }
+
+  async insert(
+    integration: InsertableIntegration,
+    trx?: KyselyTransaction,
+  ): Promise<Integration> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .insertInto('integrations')
+      .values(integration)
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async insertOrRestore(
+    integration: InsertableIntegration,
+    trx?: KyselyTransaction,
+  ): Promise<Integration> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .insertInto('integrations')
+      .values(integration)
+      .onConflict((oc) =>
+        oc.columns(['type', 'workspaceId']).doUpdateSet({
+          deletedAt: null,
+          installedById: integration.installedById,
+          updatedAt: new Date(),
+        }),
+      )
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async update(
+    integrationId: string,
+    data: UpdatableIntegration,
+    trx?: KyselyTransaction,
+  ): Promise<Integration> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .updateTable('integrations')
+      .set({ ...data, updatedAt: new Date() })
+      .where('id', '=', integrationId)
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async softDelete(
+    integrationId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .updateTable('integrations')
+      .set({ deletedAt: new Date() })
+      .where('id', '=', integrationId)
+      .execute();
+  }
+
+  async findByTypeAndSettingsField(
+    type: string,
+    key: string,
+    value: string,
+  ): Promise<Integration | undefined> {
+    return this.db
+      .selectFrom('integrations')
+      .selectAll()
+      .where('type', '=', type)
+      .where('deletedAt', 'is', null)
+      .where(sql<string>`settings->>${sql.lit(key)}`, '=', value)
+      .executeTakeFirst();
+  }
+}

apps/server/src/core/integration/unfurl/unfurl.controller.ts

@@ -0,0 +1,35 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  HttpStatus,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '../../../common/guards/jwt-auth.guard';
+import { AuthUser } from '../../../common/decorators/auth-user.decorator';
+import { AuthWorkspace } from '../../../common/decorators/auth-workspace.decorator';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import { UnfurlService } from './unfurl.service';
+import { UnfurlDto } from '../dto/integration.dto';
+
+@Controller('integrations')
+export class UnfurlController {
+  constructor(private readonly unfurlService: UnfurlService) {}
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('unfurl')
+  async unfurl(
+    @Body() dto: UnfurlDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const result = await this.unfurlService.unfurl(
+      dto.url,
+      user.id,
+      workspace.id,
+    );
+    return { data: result };
+  }
+}

apps/server/src/core/integration/unfurl/unfurl.service.ts

@@ -0,0 +1,268 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { IntegrationRegistry } from '../registry/integration-registry';
+import { IntegrationConnectionRepo } from '../repos/integration-connection.repo';
+import { IntegrationRepo } from '../repos/integration.repo';
+import { OAuthService } from '../oauth/oauth.service';
+import {
+  UnfurlResult,
+  UnfurlNeedsConnection,
+  UnfurlForbiddenError,
+  UnfurlNeedsConnectionError,
+  TokenInvalidError,
+  ProviderApiError,
+  IntegrationProvider,
+} from '../registry/integration-provider.interface';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import type { Redis } from 'ioredis';
+import * as crypto from 'crypto';
+
+const UNFURL_CACHE_TTL = 300; // 5 minutes
+// Transient failures get a short negative cache so a broken provider is not
+// re-fetched on every view; 404s cache at the normal TTL (the target is gone).
+const UNFURL_ERROR_CACHE_TTL = 60;
+const UNFURL_CACHE_PREFIX = 'unfurl:';
+
+@Injectable()
+export class UnfurlService {
+  private readonly logger = new Logger(UnfurlService.name);
+  private readonly redis: Redis;
+
+  constructor(
+    private readonly registry: IntegrationRegistry,
+    private readonly integrationRepo: IntegrationRepo,
+    private readonly connectionRepo: IntegrationConnectionRepo,
+    private readonly oauthService: OAuthService,
+    private readonly redisService: RedisService,
+  ) {
+    this.redis = this.redisService.getOrThrow();
+  }
+
+  async unfurl(
+    url: string,
+    userId: string,
+    workspaceId: string,
+  ): Promise<UnfurlResult | UnfurlNeedsConnection | null> {
+    const cacheKey = this.buildCacheKey(workspaceId, userId, url);
+    const cached = await this.redis.get(cacheKey);
+    if (cached) {
+      return JSON.parse(cached);
+    }
+
+    const resolved = await this.resolveProvider(url, workspaceId);
+
+    if (!resolved) {
+      return null;
+    }
+
+    const { provider, match, patternType, integration } = resolved;
+
+    if (!provider.unfurl) {
+      return null;
+    }
+
+    // Workspace-scoped providers (Slack) share one bot connection that serves
+    // every member; user-scoped providers need the requester's own token.
+    const connectionScope =
+      provider.definition.oauth?.connectionScope ?? 'user';
+    const connection =
+      connectionScope === 'workspace'
+        ? await this.connectionRepo.findWorkspaceConnection(integration.id)
+        : await this.connectionRepo.findByIntegrationAndUser(
+            integration.id,
+            userId,
+          );
+
+    if (!connection || connection.invalidatedAt) {
+      // Dead workspace connections need an admin re-install; members get no card.
+      if (connectionScope === 'workspace') {
+        return null;
+      }
+      // Not cached: the card should load as soon as the user (re)connects.
+      return this.buildNeedsConnection(
+        provider,
+        integration.id,
+        patternType,
+        match,
+        url,
+      );
+    }
+
+    try {
+      const accessToken =
+        await this.oauthService.getValidAccessToken(connection);
+
+      const unfurlResult = await provider.unfurl({
+        url,
+        accessToken,
+        match,
+        patternType,
+        settings: (integration.settings as Record<string, any>) ?? {},
+        userId,
+        integrationId: integration.id,
+      });
+
+      await this.redis.set(
+        cacheKey,
+        JSON.stringify(unfurlResult),
+        'EX',
+        UNFURL_CACHE_TTL,
+      );
+
+      return unfurlResult;
+    } catch (err) {
+      // The provider needs the requester to link an identity first (Slack's
+      // workspace bot serves everyone, but only linked members may unfurl).
+      // Not cached: the card should load as soon as the user links.
+      if (err instanceof UnfurlNeedsConnectionError) {
+        return this.buildNeedsConnection(
+          provider,
+          integration.id,
+          patternType,
+          match,
+          url,
+        );
+      }
+      // Not-authorized is an expected outcome (no card), not an error.
+      if (err instanceof UnfurlForbiddenError) {
+        this.logger.debug(
+          `Unfurl not authorized for ${url}: ${(err as Error).message}`,
+        );
+        await this.cacheNull(cacheKey, UNFURL_ERROR_CACHE_TTL);
+        return null;
+      }
+      if (err instanceof TokenInvalidError) {
+        this.logger.warn(
+          `Retiring connection ${connection.id}: ${(err as Error).message}`,
+        );
+        await this.connectionRepo
+          .invalidate(connection.id)
+          .catch(() => undefined);
+        if (connectionScope === 'workspace') {
+          return null;
+        }
+        // Not cached so the card heals the moment the user reconnects.
+        return this.buildNeedsConnection(
+          provider,
+          integration.id,
+          patternType,
+          match,
+          url,
+        );
+      }
+      this.logger.error(`Unfurl failed for ${url}: ${(err as Error).message}`);
+      const ttl =
+        err instanceof ProviderApiError && err.status === 404
+          ? UNFURL_CACHE_TTL
+          : UNFURL_ERROR_CACHE_TTL;
+      await this.cacheNull(cacheKey, ttl);
+      return null;
+    }
+  }
+
+  private async cacheNull(cacheKey: string, ttl: number): Promise<void> {
+    await this.redis.set(cacheKey, 'null', 'EX', ttl);
+  }
+
+  async purgeUserCache(workspaceId: string, userId: string): Promise<void> {
+    const pattern = `${UNFURL_CACHE_PREFIX}${workspaceId}:${userId}:*`;
+    try {
+      const stream = this.redis.scanStream({ match: pattern, count: 100 });
+      for await (const keys of stream as AsyncIterable<string[]>) {
+        if (keys.length) {
+          await this.redis.unlink(...keys);
+        }
+      }
+    } catch (err) {
+      // best-effort by design: never fail a disconnect on cache purge; the TTL is the backstop
+      this.logger.error(
+        `Failed to purge unfurl cache for user ${userId}: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  private buildNeedsConnection(
+    provider: IntegrationProvider,
+    integrationId: string,
+    patternType: string,
+    match: RegExpMatchArray,
+    url: string,
+  ): UnfurlNeedsConnection {
+    const described =
+      provider.describeLink?.(patternType, match, url) ?? null;
+
+    let fallbackDescription: string | undefined;
+    try {
+      const parsed = new URL(url);
+      fallbackDescription = `${parsed.host}${parsed.pathname}`;
+    } catch {
+      fallbackDescription = undefined;
+    }
+
+    return {
+      needsConnection: true,
+      integrationId,
+      integrationType: provider.definition.type,
+      integrationName: provider.definition.name,
+      // Workspace-scoped providers also bind the authorizing user's identity
+      // on OAuth completion (onConnected upserts their user link), so any
+      // OAuth-capable provider supports connecting from Docmost.
+      oauthConnect: !!provider.definition.oauth,
+      title: described?.title ?? `${provider.definition.name} link`,
+      description: described?.description ?? fallbackDescription,
+    };
+  }
+
+  private async resolveProvider(
+    url: string,
+    workspaceId: string,
+  ): Promise<{
+    provider: IntegrationProvider;
+    match: RegExpMatchArray;
+    patternType: string;
+    integration: {
+      id: string;
+      type: string;
+      settings: unknown;
+    };
+  } | null> {
+    const staticResult = this.registry.findUnfurlProvider(url);
+    if (staticResult) {
+      const integration = await this.integrationRepo.findByWorkspaceAndType(
+        workspaceId,
+        staticResult.provider.definition.type,
+      );
+      if (integration) {
+        return { ...staticResult, integration };
+      }
+    }
+
+    const integrations =
+      await this.integrationRepo.findAllByWorkspace(workspaceId);
+
+    for (const integration of integrations) {
+      const provider = this.registry.getProvider(integration.type);
+      if (!provider?.getUnfurlPatterns || !provider.unfurl) continue;
+
+      const settings = (integration.settings as Record<string, any>) ?? {};
+      const patterns = provider.getUnfurlPatterns(settings);
+
+      for (const pattern of patterns) {
+        const match = url.match(pattern.regex);
+        if (match) {
+          return { provider, match, patternType: pattern.type, integration };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private buildCacheKey(workspaceId: string, userId: string, url: string): string {
+    const hash = crypto
+      .createHash('sha256')
+      .update(url)
+      .digest('hex')
+      .slice(0, 16);
+    return `${UNFURL_CACHE_PREFIX}${workspaceId}:${userId}:${hash}`;
+  }
+}

apps/server/src/core/integration/utils/provider-fetch.ts

@@ -0,0 +1,67 @@
+import {
+  ProviderApiError,
+  TokenInvalidError,
+  UnfurlForbiddenError,
+} from '../registry/integration-provider.interface';
+import { proxyFetch } from '../../../common/proxy-fetch';
+
+export const INTEGRATION_HTTP_TIMEOUT_MS = 10_000;
+
+// Providers explain refusals in the response body ("insufficient scope",
+// "not allowed", ...); without it a 403 is undiagnosable from the logs.
+const MAX_ERROR_BODY_CHARS = 300;
+
+async function readErrorBody(response: Response): Promise<string> {
+  try {
+    const text = await response.text();
+    return text.replace(/\s+/g, ' ').trim().slice(0, MAX_ERROR_BODY_CHARS);
+  } catch {
+    return '';
+  }
+}
+
+// Bounds every provider call and maps 401 to TokenInvalidError so callers can retire the connection.
+export async function providerApiFetch(
+  providerName: string,
+  url: string,
+  init: RequestInit = {},
+): Promise<Response> {
+  const response = await proxyFetch(url, {
+    ...init,
+    redirect: 'manual',
+    signal: AbortSignal.timeout(INTEGRATION_HTTP_TIMEOUT_MS),
+  });
+
+  // Don't follow redirects: a 3xx could hop to an internal address.
+  if (response.type === 'opaqueredirect' || response.status === 0) {
+    throw new ProviderApiError(providerName, 502, 'unexpected redirect');
+  }
+
+  if (response.status === 401) {
+    throw new TokenInvalidError(
+      `${providerName} API error: 401 Unauthorized ${await readErrorBody(response)}`.trimEnd(),
+    );
+  }
+  if (!response.ok) {
+    const body = await readErrorBody(response);
+
+    // 403 normally means the viewer simply can't reach that resource, which is
+    // an expected "no card" outcome. GitHub also spends 403 on secondary rate
+    // limits, so quota signals stay a real error an operator can see.
+    const rateLimited =
+      response.headers.get('retry-after') !== null ||
+      response.headers.get('x-ratelimit-remaining') === '0';
+    if (response.status === 403 && !rateLimited) {
+      throw new UnfurlForbiddenError(
+        `${providerName} API error: 403 ${body}`.trimEnd(),
+      );
+    }
+
+    throw new ProviderApiError(
+      providerName,
+      response.status,
+      `${response.statusText} ${body}`.trim(),
+    );
+  }
+  return response;
+}

apps/server/src/core/integration/utils/relative-time.ts

@@ -0,0 +1,5 @@
+import { formatDistanceStrict } from 'date-fns';
+
+export function relativeTime(iso: string): string {
+  return formatDistanceStrict(new Date(iso), new Date(), { addSuffix: true });
+}