snapshot of https://github.com/docmost/docmost.git @ 6205bbeb908fe846f87dd6a2cbf562e24777db38 (2026-09-15)

2026-09-15 15:15:34 +05:00
commit 2653349432
1615 changed files with 202632 additions and 0 deletions
--- a/apps/server/.dockerignore
+++ b/apps/server/.dockerignore
@@ -0,0 +1,5 @@
+node_modules
+.git
+.gitignore
+dist
+data
--- a/apps/server/.gitignore
+++ b/apps/server/.gitignore
@@ -0,0 +1,38 @@
+.env
+package-lock.json
+# compiled output
+/dist
+/node_modules
+/data
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
--- a/apps/server/.prettierrc
+++ b/apps/server/.prettierrc
@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}
--- a/apps/server/README.md
+++ b/apps/server/README.md
@@ -0,0 +1,97 @@
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="200" alt="Nest Logo" /></a>
+</p>
+
+[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
+[circleci-url]: https://circleci.com/gh/nestjs/nest
+
+  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
+    <p align="center">
+<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
+<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
+<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
+<a href="https://coveralls.io/github/nestjs/nest?branch=master" target="_blank"><img src="https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#9" alt="Coverage" /></a>
+<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
+<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
+  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg"/></a>
+    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
+  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
+</p>
+  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
+  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+
+## Description
+
+[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
+
+## Installation
+
+```bash
+$ npm install
+```
+
+## Running the app
+
+```bash
+# development
+$ npm run start
+
+# watch mode
+$ npm run start:dev
+
+# production mode
+$ npm run start:prod
+```
+
+
+## Migrations
+
+```bash
+# This creates a new empty migration file named 'init'
+$ npm run migration:create --name=init
+
+# Generates 'init' migration file from existing entities to update the database schema
+$ npm run migration:generate --name=init
+
+# Runs all pending migrations to update the database schema
+$ npm run migration:run
+
+# Reverts the last executed migration
+$ npm run migration:revert
+
+# Reverts all migrations
+$ npm run migration:revert
+
+# Shows the list of executed and pending migrations
+$ npm run migration:show
+
+
+
+## Test
+
+```bash
+# unit tests
+$ npm run test
+
+# e2e tests
+$ npm run test:e2e
+
+# test coverage
+$ npm run test:cov
+```
+
+## Support
+
+Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+
+## Stay in touch
+
+- Author - [Kamil Myśliwiec](https://kamilmysliwiec.com)
+- Website - [https://nestjs.com](https://nestjs.com/)
+- Twitter - [@nestframework](https://twitter.com/nestframework)
+
+## License
+
+Nest is [MIT licensed](LICENSE).
--- a/apps/server/eslint.config.mjs
+++ b/apps/server/eslint.config.mjs
@@ -0,0 +1,34 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintConfigPrettier,
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  {
+    languageOptions: {
+      globals: { ...globals.node, ...globals.jest },
+      sourceType: 'module',
+      parser: tseslint.parser,
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      'prefer-rest-params': 'off',
+      'no-useless-catch': 'off',
+      'no-useless-escape': 'off',
+    },
+  },
+];
--- a/apps/server/nest-cli.json
+++ b/apps/server/nest-cli.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -0,0 +1,204 @@
+{
+  "name": "server",
+  "version": "0.96.0",
+  "description": "",
+  "author": "",
+  "private": true,
+  "license": "",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "cross-env NODE_ENV=development nest start",
+    "start:dev": "cross-env NODE_ENV=development nest start --watch",
+    "start:debug": "cross-env NODE_ENV=development nest start --debug --watch",
+    "start:prod": "cross-env NODE_ENV=production node dist/main",
+    "collab:prod": "cross-env NODE_ENV=production node dist/collaboration/server/collab-main",
+    "collab:dev": "cross-env NODE_ENV=development node dist/collaboration/server/collab-main",
+    "email:dev": "email dev -p 5019 -d ./src/integrations/transactional/emails",
+    "migration:create": "tsx src/database/migrate.ts create",
+    "migration:up": "tsx src/database/migrate.ts up",
+    "migration:down": "tsx src/database/migrate.ts down",
+    "migration:latest": "tsx src/database/migrate.ts latest",
+    "migration:redo": "tsx src/database/migrate.ts redo",
+    "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
+    "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config test/jest-e2e.json"
+  },
+  "dependencies": {
+    "@ai-sdk/google": "3.0.52",
+    "@ai-sdk/openai": "3.0.47",
+    "@ai-sdk/openai-compatible": "2.0.37",
+    "@aws-sdk/client-s3": "3.1050.0",
+    "@aws-sdk/lib-storage": "3.1050.0",
+    "@aws-sdk/s3-request-presigner": "3.1050.0",
+    "@azure/storage-blob": "12.31.0",
+    "@clickhouse/client": "1.18.2",
+    "@docmost/base-formula": "workspace:*",
+    "@docmost/pdf-inspector": "1.9.6",
+    "@fastify/cookie": "11.1.2",
+    "@fastify/multipart": "10.1.1",
+    "@fastify/static": "10.1.3",
+    "@jmondi/oauth2-server": "^4.3.7",
+    "@keyv/redis": "5.1.6",
+    "@langchain/core": "1.1.46",
+    "@langchain/textsplitters": "1.0.1",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@nest-lab/throttler-storage-redis": "1.2.0",
+    "@nestjs-labs/nestjs-ioredis": "11.0.4",
+    "@nestjs/bullmq": "11.0.5",
+    "@nestjs/cache-manager": "3.1.3",
+    "@nestjs/common": "11.2.1",
+    "@nestjs/config": "4.0.4",
+    "@nestjs/core": "11.2.1",
+    "@nestjs/event-emitter": "3.1.0",
+    "@nestjs/jwt": "11.0.2",
+    "@nestjs/mapped-types": "2.1.1",
+    "@nestjs/passport": "11.0.5",
+    "@nestjs/platform-fastify": "11.2.1",
+    "@nestjs/platform-socket.io": "11.2.1",
+    "@nestjs/schedule": "6.1.3",
+    "@nestjs/terminus": "11.1.1",
+    "@nestjs/throttler": "6.5.0",
+    "@nestjs/websockets": "11.2.1",
+    "@node-saml/passport-saml": "5.1.0",
+    "@socket.io/redis-adapter": "8.3.0",
+    "@turbopuffer/turbopuffer": "^2.8.0",
+    "ai": "6.0.134",
+    "ai-sdk-ollama": "3.8.1",
+    "bcrypt": "6.0.0",
+    "bowser": "2.14.1",
+    "bullmq": "5.79.0",
+    "cache-manager": "7.2.8",
+    "cheerio": "1.2.0",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "cookie": "1.1.1",
+    "csv-stringify": "6.8.0",
+    "fast-bm25": "0.0.5",
+    "fastify-ip": "2.0.0",
+    "fs-extra": "11.3.4",
+    "happy-dom": "20.8.9",
+    "ioredis": "5.10.1",
+    "js-tiktoken": "1.0.21",
+    "jsonwebtoken": "9.0.3",
+    "kysely": "0.28.17",
+    "kysely-migration-cli": "0.4.2",
+    "kysely-postgres-js": "3.0.0",
+    "ldapts": "8.1.7",
+    "mammoth": "1.12.0",
+    "mime-types": "3.0.2",
+    "msgpackr": "1.11.9",
+    "nanoid": "5.1.16",
+    "nestjs-cls": "6.2.0",
+    "nestjs-kysely": "3.1.2",
+    "nestjs-pino": "4.6.1",
+    "nodemailer": "9.0.1",
+    "openid-client": "6.8.2",
+    "otpauth": "9.5.0",
+    "p-limit": "7.3.0",
+    "passport-google-oauth20": "2.0.0",
+    "passport-jwt": "4.0.1",
+    "pg-tsquery": "8.4.2",
+    "pgvector": "0.2.1",
+    "pino-http": "11.0.0",
+    "pino-pretty": "13.1.3",
+    "postgres": "3.4.8",
+    "postmark": "4.0.7",
+    "react": "19.2.7",
+    "react-email": "6.6.3",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "^7.8.2",
+    "sanitize-filename": "1.6.3",
+    "scimmy": "1.3.5",
+    "socket.io": "4.8.3",
+    "stripe": "^17.7.0",
+    "tlds": "1.261.0",
+    "tmp-promise": "3.0.3",
+    "typesense": "3.0.5",
+    "undici": "7.29.0",
+    "ws": "8.21.3",
+    "yauzl": "3.4.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@nestjs/cli": "^11.0.21",
+    "@nestjs/schematics": "^11.0.10",
+    "@nestjs/testing": "^11.1.19",
+    "@types/bcrypt": "^6.0.0",
+    "@types/debounce": "^1.2.4",
+    "@types/fs-extra": "^11.0.4",
+    "@types/jest": "^30.0.0",
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^25.5.0",
+    "@types/nodemailer": "^7.0.11",
+    "@types/passport-google-oauth20": "^2.0.17",
+    "@types/passport-jwt": "^4.0.1",
+    "@types/supertest": "^6.0.3",
+    "@types/ws": "^8.18.1",
+    "@types/yauzl": "^2.10.3",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "jest": "^30.3.0",
+    "kysely-codegen": "^0.20.0",
+    "prettier": "^3.8.1",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.6",
+    "ts-loader": "^9.5.7",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.1"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts",
+      "tsx"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "happy-dom.+\\.js$": [
+        "babel-jest",
+        {
+          "presets": [
+            [
+              "@babel/preset-env",
+              {
+                "targets": {
+                  "node": "current"
+                }
+              }
+            ]
+          ]
+        }
+      ],
+      "^.+\\.(t|j)sx?$": "ts-jest"
+    },
+    "transformIgnorePatterns": [
+      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom)(@|/))"
+    ],
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node",
+    "moduleNameMapper": {
+      "^@docmost/db/(.*)$": "<rootDir>/database/$1",
+      "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
+      "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
+      "^src/(.*)$": "<rootDir>/$1",
+      "^@docmost/base-formula/server$": "<rootDir>/../../../packages/base-formula/src/index.server.ts",
+      "^@docmost/base-formula/client$": "<rootDir>/../../../packages/base-formula/src/index.client.ts"
+    }
+  }
+}
--- a/apps/server/src/app.controller.ts
+++ b/apps/server/src/app.controller.ts
@@ -0,0 +1,12 @@
+import { Controller, Get } from '@nestjs/common';
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}
--- a/apps/server/src/app.module.ts
+++ b/apps/server/src/app.module.ts
@@ -0,0 +1,114 @@
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { EnvironmentService } from './integrations/environment/environment.service';
+import { AuditActorInterceptor } from './common/interceptors/audit-actor.interceptor';
+import { CoreModule } from './core/core.module';
+import { EnvironmentModule } from './integrations/environment/environment.module';
+import { CollaborationModule } from './collaboration/collaboration.module';
+import { WsModule } from './ws/ws.module';
+import { DatabaseModule } from '@docmost/db/database.module';
+import { StorageModule } from './integrations/storage/storage.module';
+import { MailModule } from './integrations/mail/mail.module';
+import { QueueModule } from './integrations/queue/queue.module';
+import { StaticModule } from './integrations/static/static.module';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { HealthModule } from './integrations/health/health.module';
+import { ExportModule } from './integrations/export/export.module';
+import { ImportModule } from './integrations/import/import.module';
+import { SecurityModule } from './integrations/security/security.module';
+import { TelemetryModule } from './integrations/telemetry/telemetry.module';
+import { RedisModule } from '@nestjs-labs/nestjs-ioredis';
+import { RedisConfigService } from './integrations/redis/redis-config.service';
+import { CacheModule } from '@nestjs/cache-manager';
+import KeyvRedis, { defaultReconnectStrategy } from '@keyv/redis';
+import { parseRedisUrl } from './common/helpers';
+import { LoggerModule } from './common/logger/logger.module';
+import { ClsModule } from 'nestjs-cls';
+import { NoopAuditModule } from './integrations/audit/audit.module';
+import { ThrottleModule } from './integrations/throttle/throttle.module';
+import { OutboundModule } from './integrations/outbound/outbound.module';
+import { EncryptionModule } from './integrations/encryption/encryption.module';
+
+const enterpriseModules = [];
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  if (require('./ee/ee.module')?.EeModule) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    enterpriseModules.push(require('./ee/ee.module')?.EeModule);
+  }
+} catch (err) {
+  if (process.env.CLOUD === 'true') {
+    console.warn('Failed to load enterprise modules. Exiting program.\n', err);
+    process.exit(1);
+  }
+}
+
+@Module({
+  imports: [
+    ClsModule.forRoot({
+      global: true,
+      middleware: { mount: true },
+    }),
+    LoggerModule,
+    ...(enterpriseModules.length > 0 ? [] : [NoopAuditModule]),
+    CoreModule,
+    DatabaseModule,
+    EnvironmentModule,
+    EncryptionModule,
+    RedisModule.forRootAsync({
+      useClass: RedisConfigService,
+    }),
+    CacheModule.registerAsync({
+      isGlobal: true,
+      useFactory: async (environmentService: EnvironmentService) => {
+        const redisUrl = environmentService.getRedisUrl();
+        const { family, tls } = parseRedisUrl(redisUrl);
+
+        return {
+          ttl: 5 * 1000,
+          stores: [
+            new KeyvRedis({
+              url: redisUrl,
+              socket: {
+                family,
+                reconnectStrategy: defaultReconnectStrategy,
+                ...tls,
+              },
+            }),
+          ],
+        };
+      },
+      inject: [EnvironmentService],
+    }),
+    CollaborationModule,
+    WsModule,
+    QueueModule,
+    StaticModule,
+    HealthModule,
+    ImportModule,
+    ExportModule,
+    StorageModule.forRootAsync({
+      imports: [EnvironmentModule],
+    }),
+    MailModule.forRootAsync({
+      imports: [EnvironmentModule],
+    }),
+    EventEmitterModule.forRoot(),
+    SecurityModule,
+    TelemetryModule,
+    ThrottleModule,
+    OutboundModule,
+    ...enterpriseModules,
+  ],
+  controllers: [AppController],
+  providers: [
+    AppService,
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: AuditActorInterceptor,
+    },
+  ],
+})
+export class AppModule {}
--- a/apps/server/src/app.service.ts
+++ b/apps/server/src/app.service.ts
@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}
--- a/apps/server/src/collaboration/adapter/collab-ws.adapter.ts
+++ b/apps/server/src/collaboration/adapter/collab-ws.adapter.ts
@@ -0,0 +1,51 @@
+import { WebSocketServer } from 'ws';
+
+export class CollabWsAdapter {
+  private readonly wss: WebSocketServer;
+
+  constructor() {
+    this.wss = new WebSocketServer({ noServer: true });
+  }
+
+  handleUpgrade(path: string, httpServer: any) {
+    httpServer.on('upgrade', (request: any, socket: any, head: any) => {
+      try {
+        const baseUrl = 'ws://' + request.headers.host + '/';
+        const pathname = new URL(request.url, baseUrl).pathname;
+
+        if (pathname === path) {
+          this.wss.handleUpgrade(request, socket, head, (ws) => {
+            this.wss.emit('connection', ws, request);
+          });
+        } else if (pathname === '/socket.io/') {
+          return;
+        } else {
+          socket.destroy();
+        }
+      } catch (err) {
+        socket.end('HTTP/1.1 400\r\n' + (err as Error).message);
+      }
+    });
+
+    return this.wss;
+  }
+
+  public close() {
+    try {
+      this.wss.close();
+    } catch (err) {
+      console.error(err);
+    }
+  }
+
+  public destroy() {
+    try {
+      this.wss.close();
+      this.wss.clients.forEach((client) => {
+        client.terminate();
+      });
+    } catch (err) {
+      console.error(err);
+    }
+  }
+}
--- a/apps/server/src/collaboration/collaboration.gateway.ts
+++ b/apps/server/src/collaboration/collaboration.gateway.ts
@@ -0,0 +1,194 @@
+import { Hocuspocus } from '@hocuspocus/server';
+import { IncomingMessage } from 'http';
+import WebSocket from 'ws';
+import { AuthenticationExtension } from './extensions/authentication.extension';
+import { PersistenceExtension } from './extensions/persistence.extension';
+import { Injectable } from '@nestjs/common';
+import { EnvironmentService } from '../integrations/environment/environment.service';
+import {
+  createRetryStrategy,
+  parseRedisUrl,
+  RedisConfig,
+} from '../common/helpers';
+import { LoggerExtension } from './extensions/logger.extension';
+import {
+  RedisSyncExtension,
+  SerializedHTTPRequest,
+} from './extensions/redis-sync';
+import { toWebRequest } from './extensions/redis-sync/redis-sync.types';
+import { WsSocketWrapper } from './extensions/redis-sync/ws-socket-wrapper';
+import RedisClient from 'ioredis';
+import { pack, unpack } from 'msgpackr';
+import { nanoid } from 'nanoid';
+import * as os from 'node:os';
+import { CollabWsAdapter } from './adapter/collab-ws.adapter';
+import {
+  CollaborationHandler,
+  CollabEventHandlers,
+} from './collaboration.handler';
+
+@Injectable()
+export class CollaborationGateway {
+  private readonly hocuspocus: Hocuspocus;
+  private redisConfig: RedisConfig;
+  // @ts-ignore
+  private readonly redisSync: RedisSyncExtension<CollabEventHandlers> | null =
+    null;
+  private readonly withRedis: boolean;
+
+  constructor(
+    private authenticationExtension: AuthenticationExtension,
+    private persistenceExtension: PersistenceExtension,
+    private loggerExtension: LoggerExtension,
+    private environmentService: EnvironmentService,
+    private collabEventsService: CollaborationHandler,
+  ) {
+    this.redisConfig = parseRedisUrl(this.environmentService.getRedisUrl());
+    this.withRedis = !this.environmentService.isCollabDisableRedis();
+
+    this.hocuspocus = new Hocuspocus({
+      debounce: 10000,
+      maxDebounce: 45000,
+      unloadImmediately: false,
+      extensions: [
+        this.authenticationExtension,
+        this.persistenceExtension,
+        this.loggerExtension,
+      ],
+    });
+
+    if (this.withRedis) {
+      // @ts-ignore
+      this.redisSync = new RedisSyncExtension({
+        redis: new RedisClient({
+          host: this.redisConfig.host,
+          port: this.redisConfig.port,
+          username: this.redisConfig.username,
+          password: this.redisConfig.password,
+          db: this.redisConfig.db,
+          family: this.redisConfig.family,
+          tls: this.redisConfig.tls,
+          retryStrategy: createRetryStrategy(),
+        }),
+        serverId: `collab-${os?.hostname()}-${nanoid(10)}`,
+        prefix: 'collab',
+        pack,
+        unpack,
+        // @ts-ignore
+        customEvents: this.collabEventsService.getHandlers(this.hocuspocus),
+      });
+      this.hocuspocus.configuration.extensions.push(this.redisSync);
+      // @ts-ignore
+      this.redisSync.onConfigure({ instance: this.hocuspocus });
+    }
+  }
+
+  private serializeRequest(request: IncomingMessage): SerializedHTTPRequest {
+    return {
+      method: request.method ?? 'GET',
+      url: request.url ?? '/',
+      headers: {
+        'sec-websocket-key': request.headers['sec-websocket-key'] ?? '',
+        'sec-websocket-protocol':
+          request.headers['sec-websocket-protocol'] ?? '',
+      },
+      socket: { remoteAddress: request.socket?.remoteAddress ?? '' },
+    };
+  }
+
+  handleConnection(client: WebSocket, request: IncomingMessage): any {
+    if (this.redisSync) {
+      const serializedHTTPRequest = this.serializeRequest(request);
+      const socketId = serializedHTTPRequest.headers['sec-websocket-key'];
+
+      const wrappedSocket = new WsSocketWrapper(client);
+
+      // Route through RedisSync extension (this calls handleConnection internally)
+      this.redisSync.onSocketOpen(wrappedSocket, serializedHTTPRequest);
+
+      client.on('message', (data: ArrayBuffer) => {
+        this.redisSync!.onSocketMessage(serializedHTTPRequest, data);
+      });
+
+      client.on('close', (code: number, reason: Buffer) => {
+        this.redisSync!.onSocketClose(
+          socketId,
+          code,
+          new Uint8Array(reason).buffer,
+        );
+      });
+    } else {
+      // Fallback to direct Hocuspocus connection
+      const clientConnection = this.hocuspocus.handleConnection(
+        client,
+        toWebRequest(this.serializeRequest(request)),
+      );
+
+      client.on('message', (data: Buffer) => {
+        clientConnection.handleMessage(new Uint8Array(data));
+      });
+
+      client.on('close', (code: number, reason: Buffer) => {
+        clientConnection.handleClose({ code, reason: reason.toString() });
+      });
+    }
+  }
+
+  getConnectionCount() {
+    return this.hocuspocus.getConnectionsCount();
+  }
+
+  getDocumentCount() {
+    return this.hocuspocus.getDocumentsCount();
+  }
+
+  handleYjsEvent<TName extends keyof CollabEventHandlers>(
+    eventName: TName,
+    documentName: string,
+    payload: Parameters<CollabEventHandlers[TName]>[1],
+  ) {
+    return this.redisSync?.handleEvent(eventName, documentName, payload);
+  }
+
+  openDirectConnection(documentName: string, context?: any) {
+    return this.hocuspocus.openDirectConnection(documentName, context);
+  }
+
+  /*
+   *Can be used before calling openDirectConnection directly
+   */
+  async lockDocument(documentName: string) {
+    return this.redisSync.lockDocument(documentName);
+  }
+
+  /*
+   *Releases a document lock and stops the interval that maintains it.
+   */
+  async releaseLock(documentName: string) {
+    return this.redisSync.releaseLock(documentName);
+  }
+
+  async destroy(collabWsAdapter: CollabWsAdapter): Promise<void> {
+    // eslint-disable-next-line no-async-promise-executor
+    await new Promise(async (resolve) => {
+      try {
+        // Wait for all documents to unload
+        this.hocuspocus.configuration.extensions.push({
+          async afterUnloadDocument({ instance }) {
+            if (instance.getDocumentsCount() === 0) resolve('');
+          },
+        });
+
+        collabWsAdapter?.close();
+
+        if (this.hocuspocus.getDocumentsCount() === 0) resolve('');
+        this.hocuspocus.closeConnections();
+        this.hocuspocus.flushPendingStores();
+      } catch (error) {
+        console.error(error);
+      }
+    });
+
+    await this.hocuspocus.hooks('onDestroy', { instance: this.hocuspocus });
+  }
+}
--- a/apps/server/src/collaboration/collaboration.handler.ts
+++ b/apps/server/src/collaboration/collaboration.handler.ts
@@ -0,0 +1,134 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Hocuspocus, Document } from '@hocuspocus/server';
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import {
+  prosemirrorNodeToYElement,
+  tiptapExtensions,
+} from './collaboration.util';
+import { setYjsMark, updateYjsMarkAttribute, YjsSelection } from './yjs.util';
+import * as Y from 'yjs';
+import { User } from '@docmost/db/types/entity.types';
+
+export type CollabEventHandlers = ReturnType<
+  CollaborationHandler['getHandlers']
+>;
+
+@Injectable()
+export class CollaborationHandler {
+  private readonly logger = new Logger(CollaborationHandler.name);
+
+  constructor() {}
+
+  getHandlers(hocuspocus: Hocuspocus) {
+    return {
+      alterState: async (documentName: string, payload: { pageId: string }) => {
+        // dummy
+        // this.logger.log('Processing', documentName, payload);
+        // await this.withYdocConnection(hocuspocus, documentName, {}, (doc) => {
+        //   const fragment = doc.getXmlFragment('default');
+        //});
+      },
+      setCommentMark: async (
+        documentName: string,
+        payload: {
+          yjsSelection: YjsSelection;
+          commentId: string;
+          resolved: boolean;
+          user: User;
+        },
+      ) => {
+        const { yjsSelection, commentId, resolved, user } = payload;
+        await this.withYdocConnection(
+          hocuspocus,
+          documentName,
+          { user },
+          (doc) => {
+            const fragment = doc.getXmlFragment('default');
+            setYjsMark(doc, fragment, yjsSelection, 'comment', {
+              commentId,
+              resolved,
+            });
+          },
+        );
+      },
+      resolveCommentMark: async (
+        documentName: string,
+        payload: {
+          commentId: string;
+          resolved: boolean;
+          user: User;
+        },
+      ) => {
+        const { commentId, resolved, user } = payload;
+        await this.withYdocConnection(
+          hocuspocus,
+          documentName,
+          { user },
+          (doc) => {
+            const fragment = doc.getXmlFragment('default');
+            updateYjsMarkAttribute(
+              fragment,
+              'comment',
+              { name: 'commentId', value: commentId },
+              { resolved },
+            );
+          },
+        );
+      },
+      updatePageContent: async (
+        documentName: string,
+        payload: {
+          prosemirrorJson: any;
+          operation: string;
+          user: User;
+        },
+      ) => {
+        const { prosemirrorJson, operation, user } = payload;
+        this.logger.debug('Updating page content via yjs', documentName);
+        await this.withYdocConnection(
+          hocuspocus,
+          documentName,
+          { user },
+          (doc) => {
+            const fragment = doc.getXmlFragment('default');
+
+            if (operation === 'replace') {
+              if (fragment.length > 0) {
+                fragment.delete(0, fragment.length);
+              }
+
+              const newDoc = TiptapTransformer.toYdoc(
+                prosemirrorJson,
+                'default',
+                tiptapExtensions,
+              );
+              Y.applyUpdate(doc, Y.encodeStateAsUpdate(newDoc));
+            } else {
+              const newContent = prosemirrorJson.content || [];
+              const yElements = newContent.map(prosemirrorNodeToYElement);
+              const position = operation === 'prepend' ? 0 : fragment.length;
+              fragment.insert(position, yElements);
+            }
+          },
+        );
+      },
+    };
+  }
+
+  async withYdocConnection(
+    hocuspocus: Hocuspocus,
+    documentName: string,
+    context: any = {},
+    fn: (doc: Document) => void,
+  ): Promise<void> {
+    const connection = await hocuspocus.openDirectConnection(
+      documentName,
+      context,
+    );
+    try {
+      await connection.transact(fn);
+    } finally {
+      await connection.disconnect();
+    }
+  }
+}
--- a/apps/server/src/collaboration/collaboration.module.ts
+++ b/apps/server/src/collaboration/collaboration.module.ts
@@ -0,0 +1,74 @@
+import { Logger, Module, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { AuthenticationExtension } from './extensions/authentication.extension';
+import { PersistenceExtension } from './extensions/persistence.extension';
+import { CollaborationGateway } from './collaboration.gateway';
+import { HttpAdapterHost } from '@nestjs/core';
+import { CollabWsAdapter } from './adapter/collab-ws.adapter';
+import { IncomingMessage } from 'http';
+import { WebSocket } from 'ws';
+import { TokenModule } from '../core/auth/token.module';
+import { HistoryProcessor } from './processors/history.processor';
+import { LoggerExtension } from './extensions/logger.extension';
+import { CollaborationHandler } from './collaboration.handler';
+import { CollabHistoryService } from './services/collab-history.service';
+import { WatcherModule } from '../core/watcher/watcher.module';
+import { TransclusionService } from '../core/page/transclusion/transclusion.service';
+import { TransclusionModule } from '../core/page/transclusion/transclusion.module';
+import { StorageModule } from '../integrations/storage/storage.module';
+import { EnvironmentModule } from '../integrations/environment/environment.module';
+
+@Module({
+  providers: [
+    CollaborationGateway,
+    AuthenticationExtension,
+    PersistenceExtension,
+    LoggerExtension,
+    HistoryProcessor,
+    CollabHistoryService,
+    CollaborationHandler,
+    TransclusionService,
+  ],
+  exports: [CollaborationGateway],
+  imports: [
+    TokenModule,
+    WatcherModule,
+    StorageModule.forRootAsync({
+      imports: [EnvironmentModule],
+    }),
+    TransclusionModule,
+  ],
+})
+export class CollaborationModule implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(CollaborationModule.name);
+  private collabWsAdapter: CollabWsAdapter;
+  private path = '/collab';
+
+  constructor(
+    private readonly collaborationGateway: CollaborationGateway,
+    private readonly httpAdapterHost: HttpAdapterHost,
+  ) {}
+
+  onModuleInit() {
+    this.collabWsAdapter = new CollabWsAdapter();
+    const httpServer = this.httpAdapterHost.httpAdapter.getHttpServer();
+
+    const wss = this.collabWsAdapter.handleUpgrade(this.path, httpServer);
+
+    wss.on('connection', (client: WebSocket, request: IncomingMessage) => {
+      this.collaborationGateway.handleConnection(client, request);
+
+      client.on('error', (error) => {
+        this.logger.error('WebSocket client error:', error);
+      });
+    });
+
+    wss.on('error', (error) =>
+      this.logger.error('WebSocket server error:', error),
+    );
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.collaborationGateway?.destroy(this.collabWsAdapter);
+    this.collabWsAdapter?.destroy();
+  }
+}
--- a/apps/server/src/collaboration/collaboration.util.ts
+++ b/apps/server/src/collaboration/collaboration.util.ts
@@ -0,0 +1,249 @@
+import { StarterKit } from '@tiptap/starter-kit';
+import { Document } from '@tiptap/extension-document';
+import { TextAlign } from '@tiptap/extension-text-align';
+import { Superscript } from '@tiptap/extension-superscript';
+import SubScript from '@tiptap/extension-subscript';
+import { Typography } from '@tiptap/extension-typography';
+import { TextStyle } from '@tiptap/extension-text-style';
+import { Color } from '@tiptap/extension-color';
+import { Youtube } from '@tiptap/extension-youtube';
+import { TaskList, TaskItem } from '@tiptap/extension-list';
+import {
+  Heading,
+  Callout,
+  Comment,
+  CustomCodeBlock,
+  Details,
+  DetailsContent,
+  DetailsSummary,
+  LinkExtension,
+  MathBlock,
+  MathInline,
+  TableHeader,
+  TableCell,
+  TableRow,
+  CustomTable,
+  TiptapImage,
+  TiptapVideo,
+  TiptapAudio,
+  TiptapPdf,
+  PageBreak,
+  TrailingNode,
+  Attachment,
+  Drawio,
+  Excalidraw,
+  Embed,
+  Mention,
+  Subpages,
+  Highlight,
+  Indent,
+  UniqueID,
+  Columns,
+  Column,
+  Status,
+  addUniqueIdsToDoc,
+  htmlToMarkdown,
+  TransclusionSource,
+  TransclusionReference,
+  BaseEmbed,
+  Footnotes,
+  Footnote,
+  FootnoteReference,
+} from '@docmost/editor-ext';
+import {
+  extensions as coreExtensions,
+  generateText,
+  getSchema,
+  JSONContent,
+} from '@tiptap/core';
+import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
+import { collapseBlankLines } from '../common/helpers';
+// @tiptap/html library works best for generating prosemirror json state but not HTML
+// see: https://github.com/ueberdosis/tiptap/issues/5352
+// see:https://github.com/ueberdosis/tiptap/issues/4089
+//import { generateJSON } from '@tiptap/html';
+import { Node, Schema } from '@tiptap/pm/model';
+import * as Y from 'yjs';
+import { Logger } from '@nestjs/common';
+
+export const tiptapExtensions = [
+  coreExtensions.TextDirection.configure({ direction: 'auto' }),
+  StarterKit.configure({
+    document: false,
+    codeBlock: false,
+    link: false,
+    trailingNode: false,
+    heading: false,
+  }),
+  Document.extend({
+    content: 'block+ footnotes?',
+  }),
+  Heading,
+  UniqueID.configure({
+    types: ['heading', 'paragraph', 'transclusionSource'],
+  }),
+  Comment,
+  TextAlign.configure({ types: ['heading', 'paragraph'] }),
+  Indent,
+  TaskList,
+  TaskItem.configure({
+    nested: true,
+  }),
+  LinkExtension,
+  Superscript,
+  SubScript,
+  Highlight,
+  Typography,
+  TrailingNode,
+  TextStyle,
+  Color,
+  MathInline,
+  MathBlock,
+  Details,
+  DetailsContent,
+  DetailsSummary,
+  CustomTable,
+  TableCell,
+  TableRow,
+  TableHeader,
+  Youtube,
+  TiptapImage,
+  TiptapVideo,
+  TiptapAudio,
+  TiptapPdf,
+  PageBreak,
+  Callout,
+  Attachment,
+  CustomCodeBlock,
+  Drawio,
+  Excalidraw,
+  Embed,
+  Mention,
+  Subpages,
+  Columns,
+  Column,
+  Status,
+  TransclusionSource,
+  TransclusionReference,
+  BaseEmbed,
+  Footnotes,
+  Footnote,
+  FootnoteReference,
+] as any;
+
+export function jsonToHtml(tiptapJson: any) {
+  return generateHTML(tiptapJson, tiptapExtensions);
+}
+
+export function htmlToJson(html: string) {
+  const pmJson = generateJSON(html, tiptapExtensions);
+
+  try {
+    return addUniqueIdsToDoc(pmJson, tiptapExtensions);
+  } catch (error) {
+    console.warn('failed to add unique ids to doc', error);
+    return pmJson;
+  }
+}
+
+export function jsonToText(tiptapJson: JSONContent) {
+  return collapseBlankLines(generateText(tiptapJson, tiptapExtensions));
+}
+
+export function jsonToNode(tiptapJson: JSONContent) {
+  const schema = getSchema(tiptapExtensions);
+  try {
+    return Node.fromJSON(schema, tiptapJson);
+  } catch (error) {
+    if (
+      error instanceof RangeError &&
+      error.message.includes('Unknown node type')
+    ) {
+      Logger.warn('Stripping unknown node types from document:', error.message);
+      const cleanedJson = stripUnknownNodes(tiptapJson, schema);
+      return Node.fromJSON(schema, cleanedJson);
+    }
+    throw error;
+  }
+}
+
+export function getPageId(documentName: string) {
+  return documentName.split('.')[1];
+}
+
+export function isEmptyParagraphDoc(tiptapJson: JSONContent): boolean {
+  if (!tiptapJson || tiptapJson.type !== 'doc') return false;
+  const content = tiptapJson.content;
+  if (!Array.isArray(content) || content.length !== 1) return false;
+  const child = content[0];
+  if (!child || child.type !== 'paragraph') return false;
+  return (
+    !child.content ||
+    (Array.isArray(child.content) && child.content.length === 0)
+  );
+}
+
+function stripUnknownNodes(
+  json: JSONContent,
+  schema: Schema,
+): JSONContent | null {
+  if (!json || typeof json !== 'object') return json;
+
+  // Recursively clean children first, flattening any unwrapped content
+  if (json.content && Array.isArray(json.content)) {
+    const newContent: JSONContent[] = [];
+    for (const child of json.content) {
+      const cleaned = stripUnknownNodes(child, schema);
+      if (Array.isArray(cleaned)) {
+        newContent.push(...cleaned);
+      } else if (cleaned) {
+        newContent.push(cleaned);
+      }
+    }
+    json.content = newContent;
+  }
+
+  // Check if this node is unknown AFTER processing children
+  if (json.type && !schema.nodes[json.type]) {
+    // Unwrap: return cleaned children directly instead of wrapping
+    return (
+      json.content && json.content.length > 0 ? json.content : null
+    ) as any;
+  }
+
+  return json;
+}
+
+export function prosemirrorNodeToYElement(node: any): Y.XmlElement | Y.XmlText {
+  if (node.type === 'text') {
+    const ytext = new Y.XmlText();
+    ytext.insert(0, node.text || '');
+    if (node.marks?.length > 0) {
+      const attrs: Record<string, any> = {};
+      for (const mark of node.marks) {
+        attrs[mark.type] = mark.attrs || true;
+      }
+      ytext.format(0, node.text?.length || 0, attrs);
+    }
+    return ytext;
+  }
+
+  const element = new Y.XmlElement(node.type);
+  if (node.attrs) {
+    for (const [key, value] of Object.entries(node.attrs)) {
+      if (value !== null && value !== undefined) {
+        element.setAttribute(key, value as any);
+      }
+    }
+  }
+  if (node.content?.length > 0) {
+    const children = node.content.map(prosemirrorNodeToYElement);
+    element.insert(0, children);
+  }
+  return element;
+}
+
+export function jsonToMarkdown(tiptapJson: any): string {
+  const html = jsonToHtml(tiptapJson);
+  return htmlToMarkdown(html);
+}
--- a/apps/server/src/collaboration/constants.ts
+++ b/apps/server/src/collaboration/constants.ts
@@ -0,0 +1,3 @@
+export const HISTORY_INTERVAL = 5 * 60 * 1000;
+export const HISTORY_FAST_INTERVAL = 60 * 1000;
+export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
--- a/apps/server/src/collaboration/extensions/authentication.extension.ts
+++ b/apps/server/src/collaboration/extensions/authentication.extension.ts
@@ -0,0 +1,110 @@
+import { Extension, onAuthenticatePayload } from '@hocuspocus/server';
+import {
+  Injectable,
+  Logger,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { TokenService } from '../../core/auth/services/token.service';
+import { UserRepo } from '@docmost/db/repos/user/user.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { findHighestUserSpaceRole } from '@docmost/db/repos/space/utils';
+import { SpaceRole } from '../../common/helpers/types/permission';
+import { isUserDisabled } from '../../common/helpers';
+import { getPageId } from '../collaboration.util';
+import { JwtCollabPayload, JwtType } from '../../core/auth/dto/jwt-payload';
+
+@Injectable()
+export class AuthenticationExtension implements Extension {
+  private readonly logger = new Logger(AuthenticationExtension.name);
+
+  constructor(
+    private tokenService: TokenService,
+    private userRepo: UserRepo,
+    private pageRepo: PageRepo,
+    private readonly spaceMemberRepo: SpaceMemberRepo,
+    private readonly pagePermissionRepo: PagePermissionRepo,
+  ) {}
+
+  async onAuthenticate(data: onAuthenticatePayload) {
+    const { documentName, token } = data;
+    const pageId = getPageId(documentName);
+
+    let jwtPayload: JwtCollabPayload;
+
+    try {
+      jwtPayload = await this.tokenService.verifyJwt(token, JwtType.COLLAB);
+    } catch (error) {
+      throw new UnauthorizedException('Invalid collab token');
+    }
+
+    const userId = jwtPayload.sub;
+    const workspaceId = jwtPayload.workspaceId;
+
+    const user = await this.userRepo.findById(userId, workspaceId);
+
+    if (!user) {
+      throw new UnauthorizedException();
+    }
+
+    if (isUserDisabled(user)) {
+      throw new UnauthorizedException();
+    }
+
+    const page = await this.pageRepo.findById(pageId);
+    if (!page) {
+      this.logger.debug(`Page not found: ${pageId}`);
+      throw new NotFoundException('Page not found');
+    }
+
+    const userSpaceRoles = await this.spaceMemberRepo.getUserSpaceRoles(
+      user.id,
+      page.spaceId,
+    );
+
+    const userSpaceRole = findHighestUserSpaceRole(userSpaceRoles);
+
+    if (!userSpaceRole) {
+      this.logger.warn(`User not authorized to access page: ${pageId}`);
+      throw new UnauthorizedException();
+    }
+
+    // Check page-level permissions
+    const { hasAnyRestriction, canAccess, canEdit } =
+      await this.pagePermissionRepo.canUserEditPage(user.id, page.id);
+
+    if (hasAnyRestriction) {
+      if (!canAccess) {
+        this.logger.warn(
+          `User ${user.id} denied page-level access to page: ${pageId}`,
+        );
+        throw new UnauthorizedException();
+      }
+
+      if (!canEdit) {
+        data.connectionConfig.readOnly = true;
+        this.logger.debug(
+          `User ${user.id} granted readonly access to restricted page: ${pageId}`,
+        );
+      }
+    } else {
+      // No restrictions - use space-level permissions
+      if (userSpaceRole === SpaceRole.READER) {
+        data.connectionConfig.readOnly = true;
+        this.logger.debug(`User granted readonly access to page: ${pageId}`);
+      }
+    }
+
+    if (page.deletedAt) {
+      data.connectionConfig.readOnly = true;
+    }
+
+    this.logger.debug(`Authenticated user ${user.id} on page ${pageId}`);
+
+    return {
+      user,
+    };
+  }
+}
--- a/apps/server/src/collaboration/extensions/logger.extension.ts
+++ b/apps/server/src/collaboration/extensions/logger.extension.ts
@@ -0,0 +1,19 @@
+import {
+  Extension,
+  onDisconnectPayload,
+  onLoadDocumentPayload,
+} from '@hocuspocus/server';
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class LoggerExtension implements Extension {
+  private readonly logger = new Logger('Collab' + LoggerExtension.name);
+
+  async afterUnloadDocument(data: onLoadDocumentPayload) {
+    this.logger.debug('Unloaded ' + data.documentName + ' from memory');
+  }
+
+  async onDisconnect(data: onDisconnectPayload) {
+    this.logger.debug('User disconnected from ' + data.documentName);
+  }
+}
--- a/apps/server/src/collaboration/extensions/persistence.extension.ts
+++ b/apps/server/src/collaboration/extensions/persistence.extension.ts
@@ -0,0 +1,296 @@
+import {
+  afterUnloadDocumentPayload,
+  Extension,
+  onChangePayload,
+  onLoadDocumentPayload,
+  onStoreDocumentPayload,
+} from '@hocuspocus/server';
+import * as Y from 'yjs';
+import { Injectable, Logger } from '@nestjs/common';
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import { getPageId, jsonToText, tiptapExtensions } from '../collaboration.util';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';
+import { InjectQueue } from '@nestjs/bullmq';
+import { QueueJob, QueueName } from '../../integrations/queue/constants';
+import { Queue } from 'bullmq';
+import {
+  extractMentions,
+  extractUserMentions,
+} from '../../common/helpers/prosemirror/utils';
+import { isDeepStrictEqual } from 'node:util';
+import {
+  IPageHistoryJob,
+  IPageMentionNotificationJob,
+} from '../../integrations/queue/constants/queue.interface';
+import { Page } from '@docmost/db/types/entity.types';
+import { CollabHistoryService } from '../services/collab-history.service';
+import {
+  HISTORY_FAST_INTERVAL,
+  HISTORY_FAST_THRESHOLD,
+  HISTORY_INTERVAL,
+} from '../constants';
+import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
+
+@Injectable()
+export class PersistenceExtension implements Extension {
+  private readonly logger = new Logger(PersistenceExtension.name);
+  private contributors: Map<string, Set<string>> = new Map();
+
+  constructor(
+    private readonly pageRepo: PageRepo,
+    @InjectKysely() private readonly db: KyselyDB,
+    @InjectQueue(QueueName.AI_QUEUE) private aiQueue: Queue,
+    @InjectQueue(QueueName.HISTORY_QUEUE) private historyQueue: Queue,
+    @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
+    private readonly collabHistory: CollabHistoryService,
+    private readonly transclusionService: TransclusionService,
+  ) {}
+
+  async onLoadDocument(data: onLoadDocumentPayload) {
+    const { documentName, document } = data;
+    const pageId = getPageId(documentName);
+
+    if (!document.isEmpty('default')) {
+      return;
+    }
+
+    const page = await this.pageRepo.findById(pageId, {
+      includeContent: true,
+      includeYdoc: true,
+    });
+
+    if (!page) {
+      this.logger.warn('page not found');
+      return;
+    }
+
+    if (page.ydoc) {
+      this.logger.debug(`ydoc loaded from db: ${pageId}`);
+
+      const doc = new Y.Doc();
+      const dbState = new Uint8Array(page.ydoc);
+
+      Y.applyUpdate(doc, dbState);
+      return doc;
+    }
+
+    // if no ydoc state in db convert json in page.content to Ydoc.
+    if (page.content) {
+      this.logger.debug(`converting json to ydoc: ${pageId}`);
+
+      const ydoc = TiptapTransformer.toYdoc(
+        page.content,
+        'default',
+        tiptapExtensions,
+      );
+
+      Y.encodeStateAsUpdate(ydoc);
+      return ydoc;
+    }
+
+    this.logger.debug(`creating fresh ydoc: ${pageId}`);
+    return new Y.Doc();
+  }
+
+  async onStoreDocument(data: onStoreDocumentPayload) {
+    const { documentName, document, lastContext } = data;
+
+    const pageId = getPageId(documentName);
+
+    const tiptapJson = TiptapTransformer.fromYdoc(document, 'default');
+    const ydocState = Buffer.from(Y.encodeStateAsUpdate(document));
+
+    let textContent = null;
+
+    try {
+      textContent = jsonToText(tiptapJson);
+    } catch (err) {
+      this.logger.warn('jsonToText' + err?.['message']);
+    }
+
+    let page: Page = null;
+    const editingUserIds = this.consumeContributors(documentName);
+
+    try {
+      await executeTx(this.db, async (trx) => {
+        page = await this.pageRepo.findById(pageId, {
+          withLock: true,
+          includeContent: true,
+          trx,
+        });
+
+        if (!page) {
+          this.logger.error(`Page with id ${pageId} not found`);
+          return;
+        }
+
+        if (isDeepStrictEqual(tiptapJson, page.content)) {
+          page = null;
+          return;
+        }
+
+        let contributorIds = undefined;
+        try {
+          const existingContributors = page.contributorIds || [];
+          contributorIds = Array.from(
+            new Set([
+              ...existingContributors,
+              ...editingUserIds,
+              page.creatorId,
+            ]),
+          );
+        } catch (err) {
+          //this.logger.debug('Contributors error:' + err?.['message']);
+        }
+
+        await this.pageRepo.updatePage(
+          {
+            content: tiptapJson,
+            textContent: textContent,
+            ydoc: ydocState,
+            lastUpdatedById: lastContext.user.id,
+            contributorIds: contributorIds,
+          },
+          pageId,
+          trx,
+        );
+
+        this.logger.debug(`Page updated: ${pageId} - SlugId: ${page.slugId}`);
+      });
+    } catch (err) {
+      this.logger.error(`Failed to update page ${pageId}`, err);
+    }
+
+    if (page) {
+      document.broadcastStateless(
+        JSON.stringify({
+          type: 'page.updated',
+          updatedAt: new Date().toISOString(),
+          lastUpdatedById: lastContext?.user?.id,
+          lastUpdatedBy: lastContext?.user
+            ? {
+                id: lastContext.user?.id,
+                name: lastContext.user?.name,
+                avatarUrl: lastContext.user?.avatarUrl,
+              }
+            : undefined,
+        }),
+      );
+
+      await this.syncTransclusion(pageId, page.workspaceId, tiptapJson);
+    }
+
+    if (page) {
+      await this.collabHistory.addContributors(pageId, editingUserIds);
+
+      const mentions = extractMentions(tiptapJson);
+
+      const userMentions = extractUserMentions(mentions);
+      const oldMentions = page.content ? extractMentions(page.content) : [];
+      const oldMentionedUserIds = extractUserMentions(oldMentions).map(
+        (m) => m.entityId,
+      );
+
+      if (userMentions.length > 0) {
+        await this.notificationQueue.add(QueueJob.PAGE_MENTION_NOTIFICATION, {
+          userMentions: userMentions.map((m) => ({
+            userId: m.entityId,
+            mentionId: m.id,
+            creatorId: m.creatorId,
+          })),
+          oldMentionedUserIds,
+          pageId,
+          spaceId: page.spaceId,
+          workspaceId: page.workspaceId,
+        } as IPageMentionNotificationJob);
+      }
+
+      await this.aiQueue.add(QueueJob.PAGE_CONTENT_UPDATED, {
+        pageIds: [pageId],
+        workspaceId: page.workspaceId,
+      });
+
+      await this.enqueuePageHistory(page);
+    }
+  }
+
+  async onChange(data: onChangePayload) {
+    const documentName = data.documentName;
+    const userId = data.context?.user?.id;
+
+    if (!userId) return;
+
+    if (!this.contributors.has(documentName)) {
+      this.contributors.set(documentName, new Set());
+    }
+
+    this.contributors.get(documentName).add(userId);
+  }
+
+  async afterUnloadDocument(data: afterUnloadDocumentPayload) {
+    const documentName = data.documentName;
+    this.contributors.delete(documentName);
+  }
+
+  private consumeContributors(documentName: string): string[] {
+    const contributorSet = this.contributors.get(documentName);
+    if (!contributorSet) return [];
+    const userIds = [...contributorSet];
+    this.contributors.delete(documentName);
+    return userIds;
+  }
+
+  private async enqueuePageHistory(page: Page): Promise<void> {
+    const pageAge = Date.now() - new Date(page.createdAt).getTime();
+    const delay =
+      pageAge < HISTORY_FAST_THRESHOLD
+        ? HISTORY_FAST_INTERVAL
+        : HISTORY_INTERVAL;
+
+    await this.historyQueue.add(
+      QueueJob.PAGE_HISTORY,
+      { pageId: page.id } as IPageHistoryJob,
+      { jobId: page.id, delay },
+    );
+  }
+
+  /**
+   * Refresh `page_transclusions` and `page_transclusion_references` to match
+   * the page's current content. Runs outside the page-write transaction and
+   * isolates each call so a failure here cannot affect the page save itself.
+   * The diff is idempotent — the next save converges if a round drops anything.
+   */
+  private async syncTransclusion(
+    pageId: string,
+    workspaceId: string,
+    tiptapJson: unknown,
+  ): Promise<void> {
+    try {
+      await this.transclusionService.syncPageTransclusions(
+        pageId,
+        workspaceId,
+        tiptapJson,
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, pageId },
+        'Failed to sync transclusions for page',
+      );
+    }
+    try {
+      await this.transclusionService.syncPageReferences(
+        pageId,
+        workspaceId,
+        tiptapJson,
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, pageId },
+        'Failed to sync transclusion references for page',
+      );
+    }
+  }
+}
--- a/apps/server/src/collaboration/extensions/redis-sync/collab-proxy-socket.ts
+++ b/apps/server/src/collaboration/extensions/redis-sync/collab-proxy-socket.ts
@@ -0,0 +1,46 @@
+import type RedisClient from 'ioredis';
+import type { WebSocketLike } from '@hocuspocus/server';
+import type { Pack, RSAMessageClose, RSAMessageSend } from './redis-sync.types';
+
+// Stands in for the client WebSocket on the server that owns the document.
+// Outgoing traffic is relayed over redis to the origin server, which holds the real socket.
+export class CollabProxySocket implements WebSocketLike {
+  private readonly replyTo: string;
+  private readonly socketId: string;
+  private pub: RedisClient;
+  private readonly pack: Pack;
+  readyState = 1;
+  onClose?: (code?: number, reason?: string) => void;
+
+  constructor(pub: RedisClient, pack: Pack, replyTo: string, socketId: string) {
+    this.replyTo = replyTo;
+    this.socketId = socketId;
+    this.pub = pub;
+    this.pack = pack;
+  }
+
+  private publish(msg: RSAMessageClose | RSAMessageSend) {
+    this.pub.publish(this.replyTo, this.pack(msg));
+  }
+
+  // The origin server already closed the real socket; stop relaying without echoing a close back
+  markClosed() {
+    this.readyState = 3;
+  }
+
+  close(code?: number, reason?: string) {
+    if (this.readyState !== 1) return;
+    this.readyState = 3;
+    this.onClose?.(code, reason);
+  }
+
+  send(message: Uint8Array) {
+    if (this.readyState !== 1) return;
+    const msg: RSAMessageSend = {
+      type: 'send',
+      socketId: this.socketId,
+      message,
+    };
+    this.publish(msg);
+  }
+}
--- a/apps/server/src/collaboration/extensions/redis-sync/index.ts
+++ b/apps/server/src/collaboration/extensions/redis-sync/index.ts
@@ -0,0 +1,2 @@
+export * from './redis-sync.extension';
+export type { SerializedHTTPRequest } from './redis-sync.extension';
--- a/apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.ts
+++ b/apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.ts
@@ -0,0 +1,428 @@
+// Source https://github.com/ueberdosis/hocuspocus/pull/1008 - MIT
+import {
+  Extension,
+  Hocuspocus,
+  IncomingMessage,
+  onConfigurePayload,
+  onLoadDocumentPayload,
+  afterUnloadDocumentPayload,
+  WebSocketLike,
+} from '@hocuspocus/server';
+import { ConnectionTimeout, Unauthorized } from '@hocuspocus/common';
+import RedisClient from 'ioredis';
+import { CollabProxySocket } from './collab-proxy-socket';
+import {
+  Configuration,
+  CustomEvents,
+  Pack,
+  RSAMessage,
+  RSAMessageClose,
+  RSAMessageCloseProxy,
+  RSAMessageCustomEventComplete,
+  RSAMessageCustomEventStart,
+  RSAMessageProxy,
+  RSAMessageUnload,
+  SerializedHTTPRequest,
+  Unpack,
+  OriginConnection,
+  ProxyConnection,
+  toWebRequest,
+} from './redis-sync.types';
+
+export type { Pack, SerializedHTTPRequest } from './redis-sync.types';
+
+type ServerId = string;
+type DocumentName = string;
+type SocketId = string;
+
+export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
+  priority = 1000;
+  private readonly pub: RedisClient;
+  private sub: RedisClient;
+  private readonly pack: Pack;
+  private readonly unpack: Unpack;
+  private originConnections: Record<SocketId, OriginConnection> = {};
+  private locks: Record<DocumentName, NodeJS.Timeout> = {};
+  private lockPromises: Record<DocumentName, Promise<ServerId | null>> = {};
+  private proxyConnections: Record<SocketId, ProxyConnection> = {};
+  private readonly prefix: string;
+  private readonly lockPrefix: string;
+  private readonly msgChannel: string;
+  private readonly serverId: ServerId;
+  private readonly customEventTTL: number;
+  private readonly lockTTL: number;
+  private instance!: Hocuspocus;
+  private readonly customEvents: TCE;
+  private replyIdCounter: number = 0;
+  // @ts-ignore
+  private pendingReplies: Record<number, PromiseWithResolvers<any>['resolve']> =
+    {};
+  private deriveContext: (
+    serializedHTTPRequest: SerializedHTTPRequest,
+  ) => Record<string, any>;
+
+  constructor(configuration: Configuration<TCE>) {
+    const {
+      redis,
+      pack,
+      unpack,
+      serverId,
+      lockTTL,
+      prefix,
+      customEvents,
+      customEventTTL,
+      deriveContext,
+    } = configuration;
+    this.pub = redis.duplicate();
+    this.sub = redis.duplicate();
+    this.pack = pack;
+    this.unpack = unpack;
+    this.serverId = serverId;
+    this.lockTTL = lockTTL ?? 10_000;
+    this.customEventTTL = customEventTTL ?? 30_000;
+    this.prefix = prefix ?? 'collab';
+    this.lockPrefix = `${this.prefix}Lock`;
+    this.msgChannel = `${this.prefix}Msg`;
+    this.customEvents = (customEvents as any) ?? ({} as any as CustomEvents);
+    this.deriveContext = deriveContext ?? (() => ({}));
+    this.sub.subscribe(this.msgChannel, `${this.msgChannel}:${this.serverId}`);
+    this.sub.on('messageBuffer', this.handleRedisMessage);
+    this.pub.on('error', () => {});
+    this.sub.on('error', () => {});
+  }
+  private getKey(documentName: string) {
+    return `${this.lockPrefix}:${documentName}`;
+  }
+
+  private closeProxy(socketId: string) {
+    const entry = this.proxyConnections[socketId];
+    if (entry) {
+      delete this.proxyConnections[socketId];
+      const { socket, clientConnection } = entry;
+      // The origin socket is already gone; don't echo a close message back
+      socket.markClosed();
+      clientConnection.handleClose({
+        code: 1000,
+        reason: 'provider_initiated',
+      });
+    }
+  }
+
+  private handleProxyMessage(
+    msg: Pick<RSAMessageProxy, 'replyTo' | 'message' | 'serializedHTTPRequest'>,
+  ) {
+    const { replyTo, message, serializedHTTPRequest } = msg;
+    const { headers } = serializedHTTPRequest;
+    const socketId = headers['sec-websocket-key'];
+    let entry = this.proxyConnections[socketId];
+    if (!entry) {
+      const socket = new CollabProxySocket(
+        this.pub,
+        this.pack,
+        replyTo,
+        socketId,
+      );
+      // A proxy connection with no live documents (client left the page, auth
+      // failed, or the origin server crashed) is reaped by hocuspocus' message
+      // timeout. Dispose it silently in that case: relaying the timeout close
+      // to the origin would kill the client's real socket, which may be busy
+      // serving other documents. Genuine protocol closes are still relayed.
+      socket.onClose = (code, reason) => {
+        delete this.proxyConnections[socketId];
+        if (code !== ConnectionTimeout.code) {
+          const msg: RSAMessageClose = {
+            type: 'close',
+            code,
+            reason,
+            socketId,
+          };
+          this.pub.publish(replyTo, this.pack(msg));
+        }
+      };
+      const clientConnection = this.instance.handleConnection(
+        socket,
+        toWebRequest(serializedHTTPRequest),
+        this.deriveContext(serializedHTTPRequest),
+      );
+      entry = { clientConnection, socket };
+      this.proxyConnections[socketId] = entry;
+    }
+    entry.clientConnection.handleMessage(message);
+  }
+
+  private getLock(documentName: string) {
+    return this.pub.get(this.getKey(documentName));
+  }
+
+  private getOrClaimLock(documentName: string) {
+    const lockPromise = this.pub.set(
+      this.getKey(documentName),
+      this.serverId,
+      'PX',
+      this.lockTTL,
+      'NX',
+      'GET',
+    );
+    this.lockPromises[documentName] = lockPromise;
+    // Briefly cache the serverId that claimed the doc to reduce load on redis
+    // When the claimant unloads the doc, it will send an unload message to immediately clear this
+    // a lockTTL / 2 guarantees stale reads < lockTTL upon server crash
+    setTimeout(() => {
+      delete this.lockPromises[documentName];
+    }, this.lockTTL / 2);
+    return lockPromise;
+  }
+
+  private getOrClaimLockThrottled(documentName: string) {
+    const existingWorkerIdPromise = this.lockPromises[documentName];
+    if (existingWorkerIdPromise) return existingWorkerIdPromise;
+    return this.getOrClaimLock(documentName);
+  }
+
+  private handleRedisMessage = async (
+    _channel: Buffer,
+    packedMessage: Buffer,
+  ) => {
+    const msg = this.unpack(packedMessage) as RSAMessage;
+    const { type } = msg;
+    if (type === 'proxy') {
+      this.handleProxyMessage(msg);
+      return;
+    }
+    if (type === 'closeProxy') {
+      this.closeProxy(msg.socketId);
+      return;
+    }
+    if (type === 'unload') {
+      delete this.lockPromises[msg.documentName];
+      return;
+    }
+    if (type === 'customEventStart') {
+      const { documentName, eventName, payload, replyTo, replyId } = msg;
+      const res = await this.handleEventLocally(
+        eventName as Extract<keyof TCE, string>,
+        documentName,
+        payload,
+      );
+      const reply: RSAMessageCustomEventComplete = {
+        type: 'customEventComplete',
+        replyId,
+        payload: res,
+      };
+      this.pub.publish(`${replyTo}`, this.pack(reply));
+      return;
+    }
+    if (type === 'customEventComplete') {
+      const { replyId, payload } = msg;
+      const resolveFn = this.pendingReplies[replyId];
+      if (!resolveFn) return;
+      delete this.pendingReplies[replyId];
+      resolveFn(payload);
+      return;
+    }
+    const { socketId } = msg;
+    const entry = this.originConnections[socketId];
+    if (!entry) {
+      // origin socket already cleaned up
+      return;
+    }
+    const { socket } = entry;
+    if (type === 'close') {
+      socket.close(msg.code, msg.reason);
+    } else if (type === 'send') {
+      socket.send(msg.message);
+    }
+  };
+
+  async maintainLock(documentName: string) {
+    this.locks[documentName] = setInterval(() => {
+      this.pub.set(
+        this.getKey(documentName),
+        this.serverId,
+        'PX',
+        this.lockTTL,
+      );
+    }, this.lockTTL / 2);
+  }
+
+  async releaseLock(documentName: string) {
+    clearInterval(this.locks[documentName]);
+    delete this.locks[documentName];
+    return this.pub.del(this.getKey(documentName));
+  }
+
+  private async handleEventLocally<TName extends Extract<keyof TCE, string>>(
+    eventName: TName,
+    documentName: string,
+    payload: any,
+  ) {
+    const handler = this.customEvents[eventName];
+    if (!handler) throw new Error(`Invalid eventName: ${eventName}`);
+    const result = await handler(documentName, payload);
+    return result as Promise<ReturnType<TCE[TName]>>;
+  }
+
+  async handleEvent<TName extends Extract<keyof TCE, string>>(
+    eventName: TName,
+    documentName: string,
+    payload: any,
+    // if true, don't claim the lock. Useful for targeting pages that are currently open
+    onlyIfOpen = false,
+  ) {
+    const isDocLoadedOnInstance = this.instance.documents.has(documentName);
+
+    if (isDocLoadedOnInstance) {
+      return this.handleEventLocally(eventName, documentName, payload);
+    }
+
+    const proxyTo = await (onlyIfOpen
+      ? this.getLock(documentName)
+      : this.getOrClaimLockThrottled(documentName));
+
+    if (!proxyTo && onlyIfOpen) {
+      return;
+    }
+
+    if (proxyTo && proxyTo !== this.serverId) {
+      ++this.replyIdCounter; // bug in biome thinks this.replyIdCounter is not used if written on the line below
+      const replyId = this.replyIdCounter;
+      // another server owns the doc
+      const proxyMessage: RSAMessageCustomEventStart = {
+        eventName,
+        documentName,
+        payload,
+        replyTo: `${this.msgChannel}:${this.serverId}`,
+        replyId,
+        type: 'customEventStart',
+      };
+      const msg = this.pack(proxyMessage);
+      this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
+      // @ts-ignore
+      const { promise, resolve, reject } = Promise.withResolvers();
+      this.pendingReplies[replyId] = resolve;
+      setTimeout(() => {
+        delete this.pendingReplies[replyId];
+        reject(new Error('TIMEOUT'));
+      }, this.customEventTTL);
+      return promise as Promise<ReturnType<TCE[TName]>>;
+    }
+    // This server owns the document, but hocuspocus hasn't loaded it yet
+    return this.handleEventLocally(eventName, documentName, payload);
+  }
+
+  async lockDocument(documentName: string) {
+    const proxyTo = await this.getOrClaimLockThrottled(documentName);
+    if (proxyTo && proxyTo !== this.serverId) {
+      throw new Error(`Could not lock document: ${documentName}`);
+    }
+    this.maintainLock(documentName);
+    return () => this.releaseLock(documentName);
+  }
+
+  /* WebSocket Server Hooks */
+  onSocketOpen(
+    ws: WebSocketLike,
+    serializedHTTPRequest: SerializedHTTPRequest,
+  ) {
+    const socketId = serializedHTTPRequest.headers['sec-websocket-key'];
+    const clientConnection = this.instance.handleConnection(
+      ws,
+      toWebRequest(serializedHTTPRequest),
+      this.deriveContext(serializedHTTPRequest),
+    );
+    this.originConnections[socketId] = { clientConnection, socket: ws };
+  }
+
+  async onSocketMessage(
+    serializedHTTPRequest: SerializedHTTPRequest,
+    detachableMsg: ArrayBuffer,
+  ) {
+    const socketId = serializedHTTPRequest.headers['sec-websocket-key'];
+    const entry = this.originConnections[socketId];
+    if (!entry) return;
+    const { clientConnection } = entry;
+
+    let message: Uint8Array;
+    let documentName: string;
+    try {
+      message = new Uint8Array(detachableMsg.slice());
+      const tmpMsg = new IncomingMessage(detachableMsg);
+      const documentNameAndSessionId = tmpMsg.readVarString();
+      // session-aware providers suffix the documentName with \0sessionId
+      const sepIdx = documentNameAndSessionId.indexOf('\0');
+      documentName =
+        sepIdx === -1
+          ? documentNameAndSessionId
+          : documentNameAndSessionId.slice(0, sepIdx);
+    } catch (error) {
+      entry.socket.close(Unauthorized.code, Unauthorized.reason);
+      return;
+    }
+    const isDocLoadedOnInstance = this.instance.documents.has(documentName);
+
+    if (isDocLoadedOnInstance) {
+      clientConnection.handleMessage(message);
+      return;
+    }
+
+    const proxyTo = await this.getOrClaimLockThrottled(documentName);
+    if (proxyTo && proxyTo !== this.serverId) {
+      // Proxied messages bypass handleMessage, so refresh the connection's
+      // liveness fields manually or hocuspocus' message timeout would reap the
+      // real socket every `timeout` ms. connectionEstablishedAt is the
+      // reference while unauthenticated (auth for remote docs is proxied too)
+      // and is private upstream.
+      clientConnection.lastMessageReceivedAt = Date.now();
+      (clientConnection as any).connectionEstablishedAt = Date.now();
+      // another server owns the doc
+      const proxyMessage: RSAMessageProxy = {
+        serializedHTTPRequest: serializedHTTPRequest,
+        replyTo: `${this.msgChannel}:${this.serverId}`,
+        message,
+        type: 'proxy',
+      };
+      const msg = this.pack(proxyMessage);
+      this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
+      return;
+    }
+    // This server owns the document, but hocuspocus hasn't loaded it yet
+    clientConnection.handleMessage(message);
+  }
+
+  onSocketClose(socketId: string, code?: number, reason?: ArrayBuffer) {
+    const entry = this.originConnections[socketId];
+    if (!entry) return;
+    delete this.originConnections[socketId];
+    entry.clientConnection.handleClose({
+      code: code ?? 1000,
+      reason: reason ? Buffer.from(reason).toString() : '',
+    });
+    const msg: RSAMessageCloseProxy = { type: 'closeProxy', socketId };
+    this.pub.publish(this.msgChannel, this.pack(msg)).catch(() => {});
+  }
+
+  /* Hocuspocus hooks */
+  async onConfigure({ instance }: onConfigurePayload) {
+    this.instance = instance;
+  }
+
+  async onLoadDocument(data: onLoadDocumentPayload) {
+    const { documentName } = data;
+    // Refresh the lock TTL
+    this.maintainLock(documentName);
+  }
+
+  async afterUnloadDocument(data: afterUnloadDocumentPayload) {
+    const { documentName } = data;
+    this.releaseLock(documentName);
+    // Broadcast to cluster to immediately remove the cached redis value
+    const msg: RSAMessageUnload = { type: 'unload', documentName };
+    this.pub.publish(this.msgChannel, this.pack(msg));
+  }
+
+  async onDestroy() {
+    this.pendingReplies = {};
+    this.pub.disconnect(false);
+    this.sub.disconnect(false);
+  }
+}
--- a/apps/server/src/collaboration/extensions/redis-sync/redis-sync.types.ts
+++ b/apps/server/src/collaboration/extensions/redis-sync/redis-sync.types.ts
@@ -0,0 +1,138 @@
+import { IncomingHttpHeaders } from 'node:http2';
+import RedisClient from 'ioredis';
+import { CollabProxySocket } from './collab-proxy-socket';
+import { type Hocuspocus, type WebSocketLike } from '@hocuspocus/server';
+
+export type SecondParam<T> = T extends (
+  arg1: any,
+  arg2: infer A,
+  ...args: any[]
+) => any
+  ? A
+  : never;
+
+export type SerializedHTTPRequest = {
+  method: string;
+  url: string;
+  headers: IncomingHttpHeaders;
+  socket: { remoteAddress: string };
+};
+
+export type RSAMessageProxy = {
+  type: 'proxy';
+  replyTo: string;
+  message: Uint8Array<ArrayBufferLike>;
+  serializedHTTPRequest: SerializedHTTPRequest;
+};
+
+export type RSAMessageCloseProxy = {
+  type: 'closeProxy';
+  socketId: string;
+};
+
+export type RSAMessageUnload = {
+  type: 'unload';
+  documentName: string;
+};
+
+export type RSAMessageClose = {
+  type: 'close';
+  code?: number;
+  reason?: string;
+  socketId: string;
+};
+
+export type RSAMessageSend = {
+  type: 'send';
+  // @ts-ignore
+  message: Uint8Array<ArrayBufferLike>;
+  socketId: string;
+};
+
+export type RSAMessageCustomEventStart<TName = string, TPayload = any> = {
+  type: 'customEventStart';
+  documentName: string;
+  eventName: TName;
+  payload: TPayload;
+  replyTo: string;
+  replyId: number;
+};
+
+export type RSAMessageCustomEventComplete = {
+  type: 'customEventComplete';
+  replyId: number;
+  payload: any;
+};
+
+export type RSAMessage =
+  | RSAMessageProxy
+  | RSAMessageCloseProxy
+  | RSAMessageUnload
+  | RSAMessageClose
+  | RSAMessageSend
+  | RSAMessageCustomEventStart
+  | RSAMessageCustomEventComplete;
+
+// @ts-ignore
+export type Pack = (msg: RSAMessage) => string | Buffer<ArrayBufferLike>;
+
+export type Unpack = (
+  // @ts-ignore
+  packedMessage: Uint8Array | Buffer<ArrayBufferLike>,
+) => RSAMessage;
+
+type ServerId = string;
+type DocumentName = string;
+type CustomEventName = string;
+
+export type CustomEvents = Record<
+  CustomEventName,
+  (documentName: string, payload: any) => Promise<any>
+>;
+
+// Not exported by @hocuspocus/server
+export type ClientConnection = ReturnType<Hocuspocus['handleConnection']>;
+export type OriginConnection = {
+  clientConnection: ClientConnection;
+  socket: WebSocketLike;
+};
+export type ProxyConnection = {
+  clientConnection: ClientConnection;
+  socket: CollabProxySocket;
+};
+
+export interface Configuration<TCE> {
+  redis: RedisClient;
+  pack: Pack;
+  unpack: Unpack;
+  serverId: ServerId;
+  lockTTL?: number;
+  customEventTTL?: number;
+  prefix?: string;
+  customEvents?: TCE;
+  // Derive the hocuspocus context once per socket instead of re-deriving it in a
+  // per-document hook like onConnect/onAuthenticate. Runs on the origin server when
+  // the socket opens and on the doc owner when the first proxied message arrives.
+  deriveContext?: (
+    serializedHTTPRequest: SerializedHTTPRequest,
+  ) => Record<string, any>;
+}
+
+// Hocuspocus expects a web-standard Request, so rehydrate one from what crossed the wire
+export const toWebRequest = (serializedHTTPRequest: SerializedHTTPRequest) => {
+  const { method, url, headers } = serializedHTTPRequest;
+  const webHeaders = new Headers();
+  Object.entries(headers).forEach(([name, value]) => {
+    if (Array.isArray(value)) {
+      value.forEach((v) => {
+        webHeaders.append(name, v);
+      });
+    } else if (value !== undefined) {
+      webHeaders.set(name, value);
+    }
+  });
+  return new Request(new URL(url, 'http://localhost'), {
+    method,
+    headers: webHeaders,
+  });
+};
--- a/apps/server/src/collaboration/extensions/redis-sync/ws-socket-wrapper.ts
+++ b/apps/server/src/collaboration/extensions/redis-sync/ws-socket-wrapper.ts
@@ -0,0 +1,35 @@
+import type WebSocket from 'ws';
+import type { WebSocketLike } from '@hocuspocus/server';
+
+/**
+ * Wrapper around ws WebSocket that Hocuspocus only writes to.
+ * Incoming socket events are forwarded separately by the gateway,
+ * which prevents double-handling with RedisSyncExtension.
+ */
+export class WsSocketWrapper implements WebSocketLike {
+  private ws: WebSocket;
+  readyState = 1;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+  }
+
+  close(code?: number, reason?: string) {
+    if (this.readyState !== 1) return;
+    this.readyState = 3;
+    try {
+      this.ws.close(code, reason);
+    } catch (e) {
+      // Socket already closed
+    }
+  }
+
+  send(message: Uint8Array) {
+    if (this.readyState !== 1) return;
+    try {
+      this.ws.send(message);
+    } catch (e) {
+      // Socket already closed
+    }
+  }
+}
--- a/apps/server/src/collaboration/processors/history.processor.ts
+++ b/apps/server/src/collaboration/processors/history.processor.ts
@@ -0,0 +1,142 @@
+import { Logger, OnModuleDestroy } from '@nestjs/common';
+import { OnWorkerEvent, Processor, WorkerHost } from '@nestjs/bullmq';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Job, Queue } from 'bullmq';
+import { QueueJob, QueueName } from '../../integrations/queue/constants';
+import {
+  IPageBacklinkJob,
+  IPageHistoryJob,
+  IPageUpdateNotificationJob,
+} from '../../integrations/queue/constants/queue.interface';
+import {
+  extractMentions,
+  extractPageMentions,
+  extractInternalLinkSlugIds,
+} from '../../common/helpers/prosemirror/utils';
+import { PageHistoryRepo } from '@docmost/db/repos/page/page-history.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { isDeepStrictEqual } from 'node:util';
+import { CollabHistoryService } from '../services/collab-history.service';
+import { WatcherService } from '../../core/watcher/watcher.service';
+import { isEmptyParagraphDoc } from '../collaboration.util';
+
+@Processor(QueueName.HISTORY_QUEUE)
+export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
+  private readonly logger = new Logger(HistoryProcessor.name);
+
+  constructor(
+    private readonly pageHistoryRepo: PageHistoryRepo,
+    private readonly pageRepo: PageRepo,
+    private readonly collabHistory: CollabHistoryService,
+    private readonly watcherService: WatcherService,
+    @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
+    @InjectQueue(QueueName.GENERAL_QUEUE) private generalQueue: Queue,
+  ) {
+    super();
+  }
+
+  async process(job: Job<IPageHistoryJob, void>): Promise<void> {
+    if (job.name !== QueueJob.PAGE_HISTORY) return;
+
+    try {
+      const { pageId } = job.data;
+
+      const page = await this.pageRepo.findById(pageId, {
+        includeContent: true,
+      });
+
+      if (!page) {
+        this.logger.warn(`Page ${pageId} not found, skipping history`);
+        await this.collabHistory.clearContributors(pageId);
+        return;
+      }
+
+      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+        pageId,
+        { includeContent: true },
+      );
+
+      if (!lastHistory && isEmptyParagraphDoc(page.content as any)) {
+        this.logger.debug(
+          `Skipping first history for page ${pageId}: empty content`,
+        );
+        await this.collabHistory.clearContributors(pageId);
+        return;
+      }
+
+      if (
+        !lastHistory ||
+        !isDeepStrictEqual(lastHistory.content, page.content)
+      ) {
+        const contributorIds = await this.collabHistory.popContributors(pageId);
+
+        try {
+          await this.watcherService.addPageWatchers(
+            contributorIds,
+            pageId,
+            page.spaceId,
+            page.workspaceId,
+          );
+
+          await this.pageHistoryRepo.saveHistory(page, { contributorIds });
+          this.logger.debug(`History created for page: ${pageId}`);
+        } catch (err) {
+          await this.collabHistory.addContributors(pageId, contributorIds);
+          throw err;
+        }
+
+        const mentions = extractMentions(page.content);
+        const pageMentions = extractPageMentions(mentions);
+        const internalLinkSlugIds = extractInternalLinkSlugIds(page.content);
+
+        await this.generalQueue
+          .add(QueueJob.PAGE_BACKLINKS, {
+            pageId,
+            workspaceId: page.workspaceId,
+            mentions: pageMentions,
+            internalLinkSlugIds,
+          } as IPageBacklinkJob)
+          .catch((err) => {
+            this.logger.error(
+              `Failed to queue backlinks for ${pageId}: ${err.message}`,
+            );
+          });
+
+        if (contributorIds.length > 0 && lastHistory?.content) {
+          await this.notificationQueue
+            .add(QueueJob.PAGE_UPDATED, {
+              pageId,
+              spaceId: page.spaceId,
+              workspaceId: page.workspaceId,
+              actorIds: contributorIds,
+            } as IPageUpdateNotificationJob)
+            .catch((err) => {
+              this.logger.error(
+                `Failed to queue page update notification for ${pageId}: ${err.message}`,
+              );
+            });
+        }
+      }
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  @OnWorkerEvent('active')
+  onActive(job: Job) {
+    this.logger.debug(`Processing ${job.name} for page: ${job.data.pageId}`);
+  }
+
+  @OnWorkerEvent('failed')
+  onError(job: Job) {
+    this.logger.error(
+      `Failed ${job.name} for page: ${job.data.pageId}. Reason: ${job.failedReason}`,
+    );
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.worker) {
+      await this.worker.close();
+    }
+  }
+}
--- a/apps/server/src/collaboration/server/collab-app.module.ts
+++ b/apps/server/src/collaboration/server/collab-app.module.ts
@@ -0,0 +1,64 @@
+import { Module } from '@nestjs/common';
+import { AppController } from '../../app.controller';
+import { AppService } from '../../app.service';
+import { EnvironmentModule } from '../../integrations/environment/environment.module';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { CollaborationModule } from '../collaboration.module';
+import { DatabaseModule } from '@docmost/db/database.module';
+import { QueueModule } from '../../integrations/queue/queue.module';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { HealthModule } from '../../integrations/health/health.module';
+import { CollaborationController } from './collaboration.controller';
+import { LoggerModule } from '../../common/logger/logger.module';
+import { RedisModule } from '@nestjs-labs/nestjs-ioredis';
+import { RedisConfigService } from '../../integrations/redis/redis-config.service';
+import { CaslModule } from '../../core/casl/casl.module';
+import { CacheModule } from '@nestjs/cache-manager';
+import KeyvRedis, { defaultReconnectStrategy } from '@keyv/redis';
+import { parseRedisUrl } from '../../common/helpers';
+
+@Module({
+  imports: [
+    LoggerModule,
+    DatabaseModule,
+    EnvironmentModule,
+    CaslModule,
+    CollaborationModule,
+    QueueModule,
+    HealthModule,
+    EventEmitterModule.forRoot(),
+    RedisModule.forRootAsync({
+      useClass: RedisConfigService,
+    }),
+    CacheModule.registerAsync({
+      isGlobal: true,
+      useFactory: async (environmentService: EnvironmentService) => {
+        const redisUrl = environmentService.getRedisUrl();
+        const { family, tls } = parseRedisUrl(redisUrl);
+
+        return {
+          ttl: 5 * 1000,
+          stores: [
+            new KeyvRedis({
+              url: redisUrl,
+              socket: {
+                family,
+                reconnectStrategy: defaultReconnectStrategy,
+                ...tls,
+              },
+            }),
+          ],
+        };
+      },
+      inject: [EnvironmentService],
+    }),
+  ],
+  controllers: [
+    AppController,
+    ...(process.env.COLLAB_SHOW_STATS?.toLowerCase() === 'true'
+      ? [CollaborationController]
+      : []),
+  ],
+  providers: [AppService],
+})
+export class CollabAppModule {}
--- a/apps/server/src/collaboration/server/collab-main.ts
+++ b/apps/server/src/collaboration/server/collab-main.ts
@@ -0,0 +1,47 @@
+import { NestFactory, Reflector } from '@nestjs/core';
+import { CollabAppModule } from './collab-app.module';
+import {
+  FastifyAdapter,
+  NestFastifyApplication,
+} from '@nestjs/platform-fastify';
+import { TransformHttpResponseInterceptor } from '../../common/interceptors/http-response.interceptor';
+import { Logger } from '@nestjs/common';
+import { Logger as PinoLogger } from 'nestjs-pino';
+import { InternalLogFilter } from '../../common/logger/internal-log-filter';
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    CollabAppModule,
+    new FastifyAdapter({
+      routerOptions: {
+        maxParamLength: 1000,
+        ignoreTrailingSlash: true,
+        ignoreDuplicateSlashes: true,
+      },
+    }),
+    {
+      logger: new InternalLogFilter(),
+      bufferLogs: false,
+    },
+  );
+
+  app.useLogger(app.get(PinoLogger));
+
+  app.setGlobalPrefix('api', { exclude: ['/'] });
+
+  app.enableCors();
+
+  const reflector = app.get(Reflector);
+  app.useGlobalInterceptors(new TransformHttpResponseInterceptor(reflector));
+  app.enableShutdownHooks();
+
+  const logger = new Logger('CollabServer');
+
+  const port = process.env.COLLAB_PORT || 3001;
+  const host = process.env.HOST || '0.0.0.0';
+  await app.listen(port, host, () => {
+    logger.log(`Listening on http://127.0.0.1:${port}`);
+  });
+}
+
+bootstrap();
--- a/apps/server/src/collaboration/server/collaboration.controller.ts
+++ b/apps/server/src/collaboration/server/collaboration.controller.ts
@@ -0,0 +1,15 @@
+import { Controller, Get } from '@nestjs/common';
+import { CollaborationGateway } from '../collaboration.gateway';
+
+@Controller('collab')
+export class CollaborationController {
+  constructor(private readonly collaborationGateway: CollaborationGateway) {}
+
+  @Get('stats')
+  async getStats() {
+    return {
+      connections: this.collaborationGateway.getConnectionCount(),
+      documents: this.collaborationGateway.getDocumentCount(),
+    };
+  }
+}
--- a/apps/server/src/collaboration/services/collab-history.service.ts
+++ b/apps/server/src/collaboration/services/collab-history.service.ts
@@ -0,0 +1,30 @@
+import { Injectable } from '@nestjs/common';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import type { Redis } from 'ioredis';
+
+const REDIS_KEY_PREFIX = 'history:contributors:';
+
+@Injectable()
+export class CollabHistoryService {
+  private readonly redis: Redis;
+
+  constructor(private readonly redisService: RedisService) {
+    this.redis = this.redisService.getOrThrow();
+  }
+
+  async addContributors(pageId: string, userIds: string[]): Promise<void> {
+    if (userIds.length === 0) return;
+    await this.redis.sadd(REDIS_KEY_PREFIX + pageId, ...userIds);
+  }
+
+  async popContributors(pageId: string): Promise<string[]> {
+    const key = REDIS_KEY_PREFIX + pageId;
+    const count = await this.redis.scard(key);
+    if (count === 0) return [];
+    return await this.redis.spop(key, count);
+  }
+
+  async clearContributors(pageId: string): Promise<void> {
+    await this.redis.del(REDIS_KEY_PREFIX + pageId);
+  }
+}
--- a/apps/server/src/collaboration/yjs.util.ts
+++ b/apps/server/src/collaboration/yjs.util.ts
@@ -0,0 +1,177 @@
+import {
+  initProseMirrorDoc,
+  relativePositionToAbsolutePosition,
+} from '@tiptap/y-tiptap';
+import * as Y from 'yjs';
+import { Document } from '@hocuspocus/server';
+import { getSchema } from '@tiptap/core';
+import { tiptapExtensions } from './collaboration.util';
+
+export type YjsSelection = {
+  anchor: any;
+  head: any;
+};
+
+export function setYjsMark(
+  doc: Document,
+  fragment: Y.XmlFragment,
+  yjsSelection: YjsSelection,
+  markName: string,
+  markAttributes: Record<string, any>,
+) {
+  const schema = getSchema(tiptapExtensions);
+  const { mapping } = initProseMirrorDoc(fragment, schema);
+
+  // Convert JSON positions to Y.js RelativePosition objects
+  const anchorRelPos = Y.createRelativePositionFromJSON(yjsSelection.anchor);
+  const headRelPos = Y.createRelativePositionFromJSON(yjsSelection.head);
+
+  const anchor = relativePositionToAbsolutePosition(
+    doc,
+    fragment,
+    anchorRelPos,
+    mapping,
+  );
+  const head = relativePositionToAbsolutePosition(
+    doc,
+    fragment,
+    headRelPos,
+    mapping,
+  );
+
+  if (anchor === null || head === null) {
+    throw new Error(
+      'Could not resolve Y.js relative positions to absolute positions',
+    );
+  }
+
+  const from = Math.min(anchor, head);
+  const to = Math.max(anchor, head);
+
+  // Apply mark directly to Y.js XmlText nodes
+  // This bypasses updateYFragment which has compatibility issues
+  applyMarkToYFragment(fragment, from, to, markName, markAttributes);
+}
+
+function applyMarkToYFragment(
+  fragment: Y.XmlFragment,
+  from: number,
+  to: number,
+  markName: string,
+  markAttributes: Record<string, any>,
+) {
+  let pos = 0;
+
+  const processItem = (item: any, parentNodeName?: string): boolean => {
+    if (pos >= to) return false;
+
+    if (item instanceof Y.XmlText) {
+      const textLength = item.length;
+      const itemEnd = pos + textLength;
+
+      if (itemEnd > from && pos < to && parentNodeName !== 'codeBlock') {
+        const formatFrom = Math.max(0, from - pos);
+        const formatTo = Math.min(textLength, to - pos);
+        const formatLength = formatTo - formatFrom;
+
+        if (formatLength > 0) {
+          item.format(formatFrom, formatLength, { [markName]: markAttributes });
+        }
+      }
+      pos = itemEnd;
+    } else if (item instanceof Y.XmlElement) {
+      pos++; // Opening tag
+      for (let i = 0; i < item.length; i++) {
+        if (!processItem(item.get(i), item.nodeName)) return false;
+      }
+      pos++; // Closing tag
+    }
+    return true;
+  };
+
+  for (let i = 0; i < fragment.length; i++) {
+    if (!processItem(fragment.get(i))) break;
+  }
+}
+
+/**
+ * Removes a mark from all text in the fragment that has the specified attribute value.
+ * Useful for deleting comments by commentId.
+ */
+export function removeYjsMarkByAttribute(
+  fragment: Y.XmlFragment,
+  markName: string,
+  attributeName: string,
+  attributeValue: string,
+) {
+  const processItem = (item: any) => {
+    if (item instanceof Y.XmlText) {
+      // Get all formatting deltas to find ranges with this mark
+      const deltas = item.toDelta();
+      let offset = 0;
+
+      for (const delta of deltas) {
+        const length = delta.insert?.length ?? 0;
+        const attributes = delta.attributes ?? {};
+        const markAttr = attributes[markName];
+
+        if (markAttr && markAttr[attributeName] === attributeValue) {
+          // Remove the mark by setting it to null
+          item.format(offset, length, { [markName]: null });
+        }
+        offset += length;
+      }
+    } else if (item instanceof Y.XmlElement) {
+      for (let i = 0; i < item.length; i++) {
+        processItem(item.get(i));
+      }
+    }
+  };
+
+  for (let i = 0; i < fragment.length; i++) {
+    processItem(fragment.get(i));
+  }
+}
+
+/**
+ * Updates a mark's attributes for all text that has the specified attribute value.
+ * Useful for resolving/unresolving comments by commentId.
+ */
+export function updateYjsMarkAttribute(
+  fragment: Y.XmlFragment,
+  markName: string,
+  findByAttribute: { name: string; value: string },
+  newAttributes: Record<string, any>,
+) {
+  const processItem = (item: any) => {
+    if (item instanceof Y.XmlText) {
+      const deltas = item.toDelta();
+      let offset = 0;
+
+      for (const delta of deltas) {
+        const length = delta.insert?.length ?? 0;
+        const attributes = delta.attributes ?? {};
+        const markAttr = attributes[markName];
+
+        if (
+          markAttr &&
+          markAttr[findByAttribute.name] === findByAttribute.value
+        ) {
+          // Update the mark with new attributes (merge with existing)
+          item.format(offset, length, {
+            [markName]: { ...markAttr, ...newAttributes },
+          });
+        }
+        offset += length;
+      }
+    } else if (item instanceof Y.XmlElement) {
+      for (let i = 0; i < item.length; i++) {
+        processItem(item.get(i));
+      }
+    }
+  };
+
+  for (let i = 0; i < fragment.length; i++) {
+    processItem(fragment.get(i));
+  }
+}
--- a/apps/server/src/common/decorators/auth-user.decorator.ts
+++ b/apps/server/src/common/decorators/auth-user.decorator.ts
@@ -0,0 +1,16 @@
+import {
+  BadRequestException,
+  createParamDecorator,
+  ExecutionContext,
+} from '@nestjs/common';
+
+export const AuthUser = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    if (!request?.user?.user) {
+      throw new BadRequestException('Invalid User');
+    }
+
+    return request.user.user;
+  },
+);
--- a/apps/server/src/common/decorators/auth-workspace.decorator.ts
+++ b/apps/server/src/common/decorators/auth-workspace.decorator.ts
@@ -0,0 +1,18 @@
+import {
+  BadRequestException,
+  createParamDecorator,
+  ExecutionContext,
+} from '@nestjs/common';
+
+export const AuthWorkspace = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    const workspace = request.raw?.workspace ?? request?.user?.workspace;
+
+    if (!workspace) {
+      throw new BadRequestException('Invalid workspace');
+    }
+
+    return workspace;
+  },
+);
--- a/apps/server/src/common/decorators/oauth-scope.decorator.ts
+++ b/apps/server/src/common/decorators/oauth-scope.decorator.ts
@@ -0,0 +1,8 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const OAUTH_SCOPE_KEY = 'oauthScope';
+
+export type OAuthRouteScope = 'read' | 'write';
+
+export const OAuthScope = (scope: OAuthRouteScope) =>
+  SetMetadata(OAUTH_SCOPE_KEY, scope);
--- a/apps/server/src/common/decorators/public.decorator.ts
+++ b/apps/server/src/common/decorators/public.decorator.ts
@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
--- a/apps/server/src/common/decorators/require-session-auth.decorator.ts
+++ b/apps/server/src/common/decorators/require-session-auth.decorator.ts
@@ -0,0 +1,6 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const REQUIRE_SESSION_AUTH_KEY = 'requireSessionAuth';
+
+export const RequireSessionAuth = () =>
+  SetMetadata(REQUIRE_SESSION_AUTH_KEY, true);
--- a/apps/server/src/common/decorators/skip-transform.decorator.ts
+++ b/apps/server/src/common/decorators/skip-transform.decorator.ts
@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const SKIP_TRANSFORM_KEY = 'SKIP_TRANSFORM';
+export const SkipTransform = () => SetMetadata(SKIP_TRANSFORM_KEY, true);
--- a/apps/server/src/common/events/audit-events.ts
+++ b/apps/server/src/common/events/audit-events.ts
@@ -0,0 +1,179 @@
+export const AuditEvent = {
+  // Workspace
+  WORKSPACE_CREATED: 'workspace.created',
+  WORKSPACE_UPDATED: 'workspace.updated',
+  WORKSPACE_INVITE_CREATED: 'workspace.invite_created',
+  WORKSPACE_INVITE_RESENT: 'workspace.invite_resent',
+  WORKSPACE_INVITE_REVOKED: 'workspace.invite_revoked',
+
+  // User
+  USER_CREATED: 'user.created',
+  USER_DELETED: 'user.deleted',
+  USER_LOGIN: 'user.login',
+  USER_LOGOUT: 'user.logout',
+  USER_ROLE_CHANGED: 'user.role_changed',
+  USER_PASSWORD_CHANGED: 'user.password_changed',
+  USER_PASSWORD_RESET: 'user.password_reset',
+  USER_PASSWORD_RESET_REQUESTED: 'user.password_reset_requested',
+  USER_UPDATED: 'user.updated',
+  USER_DEACTIVATED: 'user.deactivated',
+  USER_ACTIVATED: 'user.activated',
+
+  // API Keys
+  API_KEY_CREATED: 'api_key.created',
+  API_KEY_UPDATED: 'api_key.updated',
+  API_KEY_DELETED: 'api_key.deleted',
+
+  // OAuth
+  OAUTH_CLIENT_REGISTERED: 'oauth_client.registered',
+  OAUTH_GRANT_CREATED: 'oauth_grant.created',
+  OAUTH_GRANT_REVOKED: 'oauth_grant.revoked',
+
+  // SCIM Tokens
+  SCIM_TOKEN_CREATED: 'scim_token.created',
+  SCIM_TOKEN_UPDATED: 'scim_token.updated',
+  SCIM_TOKEN_DELETED: 'scim_token.deleted',
+
+  // Space
+  SPACE_CREATED: 'space.created',
+  SPACE_UPDATED: 'space.updated',
+  SPACE_DELETED: 'space.deleted',
+  SPACE_MEMBER_ADDED: 'space.member_added',
+  SPACE_MEMBER_REMOVED: 'space.member_removed',
+  SPACE_MEMBER_ROLE_CHANGED: 'space.member_role_changed',
+
+  // Group
+  GROUP_CREATED: 'group.created',
+  GROUP_UPDATED: 'group.updated',
+  GROUP_DELETED: 'group.deleted',
+  GROUP_MEMBER_ADDED: 'group.member_added',
+  GROUP_MEMBER_REMOVED: 'group.member_removed',
+
+  // Comment
+  COMMENT_CREATED: 'comment.created',
+  COMMENT_DELETED: 'comment.deleted',
+
+  // Comment updates / resolve
+  COMMENT_UPDATED: 'comment.updated',
+  COMMENT_RESOLVED: 'comment.resolved',
+  COMMENT_REOPENED: 'comment.reopened',
+
+  // Page
+  PAGE_CREATED: 'page.created',
+  PAGE_TRASHED: 'page.trashed',
+  PAGE_DELETED: 'page.deleted',
+  PAGE_RESTORED: 'page.restored',
+  PAGE_MOVED_TO_SPACE: 'page.moved_to_space',
+  PAGE_DUPLICATED: 'page.duplicated',
+  // Page permission
+  PAGE_RESTRICTED: 'page.restricted',
+  PAGE_RESTRICTION_REMOVED: 'page.restriction_removed',
+  PAGE_PERMISSION_ADDED: 'page.permission_added',
+  PAGE_PERMISSION_REMOVED: 'page.permission_removed',
+  PAGE_PERMISSION_ROLE_CHANGED: 'page.permission_role_changed',
+  // Page verification
+  PAGE_VERIFICATION_CREATED: 'page.verification_created',
+  PAGE_VERIFICATION_UPDATED: 'page.verification_updated',
+  PAGE_VERIFICATION_REMOVED: 'page.verification_removed',
+  PAGE_VERIFIED: 'page.verified',
+  PAGE_APPROVAL_REQUESTED: 'page.approval_requested',
+  PAGE_APPROVAL_REJECTED: 'page.approval_rejected',
+  PAGE_MARKED_OBSOLETE: 'page.marked_obsolete',
+
+  // Share
+  SHARE_CREATED: 'share.created',
+  SHARE_DELETED: 'share.deleted',
+
+  // Import / Export
+  PAGE_IMPORTED: 'page.imported',
+  PAGE_EXPORTED: 'page.exported',
+  SPACE_EXPORTED: 'space.exported',
+
+  // SSO provider management
+  SSO_PROVIDER_CREATED: 'sso.provider_created',
+  SSO_PROVIDER_UPDATED: 'sso.provider_updated',
+  SSO_PROVIDER_DELETED: 'sso.provider_deleted',
+
+  // MFA
+  USER_MFA_ENABLED: 'user.mfa_enabled',
+  USER_MFA_DISABLED: 'user.mfa_disabled',
+  USER_MFA_BACKUP_CODE_GENERATED: 'user.mfa_backup_code_generated',
+
+  // License
+  LICENSE_ACTIVATED: 'license.activated',
+  LICENSE_REMOVED: 'license.removed',
+
+  // Attachment
+  ATTACHMENT_UPLOADED: 'attachment.uploaded',
+  // ATTACHMENT_DELETED: 'attachment.deleted',
+
+  // SIEM streaming
+  SIEM_DESTINATION_CREATED: 'siem_destination.created',
+  SIEM_DESTINATION_UPDATED: 'siem_destination.updated',
+  SIEM_DESTINATION_DELETED: 'siem_destination.deleted',
+  SIEM_DESTINATION_TEST: 'siem_destination.test',
+
+  // Template
+  TEMPLATE_CREATED: 'template.created',
+  TEMPLATE_DELETED: 'template.deleted',
+} as const;
+
+export type AuditEventType = (typeof AuditEvent)[keyof typeof AuditEvent];
+
+export const EXCLUDED_AUDIT_EVENTS: Set<string> = new Set([
+  AuditEvent.PAGE_CREATED,
+  AuditEvent.PAGE_MOVED_TO_SPACE,
+  AuditEvent.PAGE_DUPLICATED,
+  AuditEvent.COMMENT_CREATED,
+  AuditEvent.COMMENT_UPDATED,
+  AuditEvent.COMMENT_RESOLVED,
+  AuditEvent.COMMENT_REOPENED,
+  AuditEvent.ATTACHMENT_UPLOADED,
+  AuditEvent.SIEM_DESTINATION_TEST,
+]);
+
+export const AuditResource = {
+  WORKSPACE: 'workspace',
+  USER: 'user',
+  PAGE: 'page',
+  SPACE: 'space',
+  SPACE_MEMBER: 'space_member',
+  GROUP: 'group',
+  COMMENT: 'comment',
+  SHARE: 'share',
+  API_KEY: 'api_key',
+  OAUTH_CLIENT: 'oauth_client',
+  OAUTH_GRANT: 'oauth_grant',
+  SCIM_TOKEN: 'scim_token',
+  SSO_PROVIDER: 'sso_provider',
+  WORKSPACE_INVITATION: 'workspace_invitation',
+  ATTACHMENT: 'attachment',
+  LICENSE: 'license',
+  SIEM_DESTINATION: 'siem_destination',
+  TEMPLATE: 'template',
+} as const;
+
+export type AuditResourceType =
+  (typeof AuditResource)[keyof typeof AuditResource];
+
+export type ActorType = 'user' | 'system' | 'api_key';
+
+export interface AuditLogPayload {
+  event: AuditEventType;
+  resourceType: AuditResourceType;
+  resourceId?: string;
+  spaceId?: string;
+  changes?: {
+    before?: Record<string, any>;
+    after?: Record<string, any>;
+  };
+  metadata?: Record<string, any>;
+}
+
+export interface AuditLogData extends AuditLogPayload {
+  workspaceId: string;
+  actorId?: string;
+  actorType: ActorType;
+  ipAddress?: string;
+  userAgent?: string;
+}
--- a/apps/server/src/common/events/event.contants.ts
+++ b/apps/server/src/common/events/event.contants.ts
@@ -0,0 +1,45 @@
+export enum EventName {
+  COLLAB_PAGE_UPDATED = 'collab.page.updated',
+  PAGE_CREATED = 'page.created',
+  PAGE_UPDATED = 'page.updated',
+  PAGE_CONTENT_UPDATED = 'page-content-updated',
+  PAGE_MOVED_TO_SPACE = 'page-moved-to-space',
+  PAGE_DELETED = 'page.deleted',
+  PAGE_SOFT_DELETED = 'page.soft_deleted',
+  PAGE_RESTORED = 'page.restored',
+
+  SPACE_CREATED = 'space.created',
+  SPACE_UPDATED = 'space.updated',
+  SPACE_DELETED = 'space.deleted',
+
+  USER_PASSWORD_RESET = 'user.password.reset',
+
+  WORKSPACE_CREATED = 'workspace.created',
+  WORKSPACE_UPDATED = 'workspace.updated',
+  WORKSPACE_DELETED = 'workspace.deleted',
+
+  BASE_CREATED = 'base.created',
+  BASE_UPDATED = 'base.updated',
+  BASE_DELETED = 'base.deleted',
+
+  BASE_ROW_CREATED = 'base.row.created',
+  BASE_ROW_UPDATED = 'base.row.updated',
+  BASE_ROW_DELETED = 'base.row.deleted',
+  BASE_ROWS_DELETED = 'base.rows.deleted',
+  BASE_ROW_RESTORED = 'base.row.restored',
+  BASE_ROW_REORDERED = 'base.row.reordered',
+
+  BASE_PROPERTY_CREATED = 'base.property.created',
+  BASE_PROPERTY_UPDATED = 'base.property.updated',
+  BASE_PROPERTY_DELETED = 'base.property.deleted',
+  BASE_PROPERTY_REORDERED = 'base.property.reordered',
+
+  BASE_VIEW_CREATED = 'base.view.created',
+  BASE_VIEW_UPDATED = 'base.view.updated',
+  BASE_VIEW_DELETED = 'base.view.deleted',
+
+  BASE_SCHEMA_BUMPED = 'base.schema.bumped',
+  BASE_ROWS_UPDATED = 'base.rows.updated',
+  BASE_FORMULA_RECOMPUTE_STARTED = 'base.formula.recompute.started',
+  BASE_FORMULA_RECOMPUTE_COMPLETED = 'base.formula.recompute.completed',
+}
--- a/apps/server/src/common/features.ts
+++ b/apps/server/src/common/features.ts
@@ -0,0 +1,33 @@
+export const Feature = {
+  SSO_CUSTOM: 'sso:custom',
+  SSO_GOOGLE: 'sso:google',
+  MFA: 'mfa',
+  API_KEYS: 'api:keys',
+  COMMENT_RESOLUTION: 'comment:resolution',
+  PAGE_PERMISSIONS: 'page:permissions',
+  AI: 'ai',
+  CONFLUENCE_IMPORT: 'import:confluence',
+  DOCX_IMPORT: 'import:docx',
+  PDF_IMPORT: 'import:pdf',
+  ATTACHMENT_INDEXING: 'attachment:indexing',
+  SECURITY_SETTINGS: 'security:settings',
+  MCP: 'mcp',
+  SCIM: 'scim',
+  PAGE_VERIFICATION: 'page:verification',
+  AUDIT_LOGS: 'audit:logs',
+  RETENTION: 'retention',
+  SHARING_CONTROLS: 'sharing:controls',
+  VIEWER_COMMENTS: 'comment:viewer',
+  TEMPLATES: 'templates',
+  PDF_EXPORT: 'export:pdf',
+  PERSONAL_SPACES: 'spaces:personal',
+  DOCX_EXPORT: 'export:docx',
+  BASES: 'bases',
+  OAUTH: 'oauth',
+  AI_CONTROLS: 'ai:controls',
+  MCP_CONTROLS: 'mcp:controls',
+  PUBLIC_SPACE_APPEARANCE: 'public-space:appearance',
+  SIEM: 'siem',
+} as const;
+
+export type FeatureKey = (typeof Feature)[keyof typeof Feature];
--- a/apps/server/src/common/guards/jwt-auth.guard.spec.ts
+++ b/apps/server/src/common/guards/jwt-auth.guard.spec.ts
@@ -0,0 +1,186 @@
+import {
+  ExecutionContext,
+  ForbiddenException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { JwtAuthGuard } from './jwt-auth.guard';
+import { OAUTH_SCOPE_KEY } from '../decorators/oauth-scope.decorator';
+import { REQUIRE_SESSION_AUTH_KEY } from '../decorators/require-session-auth.decorator';
+import { JwtType } from '../../core/auth/dto/jwt-payload';
+
+const handlerSentinel = () => 'handler';
+const classSentinel = class Controller {};
+
+function createCtx(): ExecutionContext {
+  return {
+    getHandler: () => handlerSentinel,
+    getClass: () => classSentinel,
+  } as any;
+}
+
+function createGuard(scopeMetadata?: unknown, requireSession?: boolean) {
+  const reflector = {
+    getAllAndOverride: jest.fn((key: string) =>
+      key === REQUIRE_SESSION_AUTH_KEY ? requireSession : scopeMetadata,
+    ),
+  } as any;
+  const environmentService = {
+    isCloud: jest.fn().mockReturnValue(false),
+  } as any;
+  const guard = new JwtAuthGuard(reflector, environmentService);
+  return { guard, reflector };
+}
+
+function oauthUser(scopes: string[]) {
+  return {
+    user: { id: 'user_1' },
+    workspace: { id: 'ws_1' },
+    oauth: { grantId: 'grant_1', scopes },
+  };
+}
+
+describe('JwtAuthGuard.handleRequest', () => {
+  it('rethrows the strategy error', () => {
+    const { guard } = createGuard();
+    const err = new UnauthorizedException('bad token');
+
+    expect(() => guard.handleRequest(err, null, null, createCtx())).toThrow(err);
+  });
+
+  it('throws UnauthorizedException when there is no user', () => {
+    const { guard } = createGuard();
+
+    expect(() => guard.handleRequest(null, null, null, createCtx())).toThrow(
+      UnauthorizedException,
+    );
+  });
+
+  it('returns a non-oauth user untouched without consulting scope metadata', () => {
+    const { guard, reflector } = createGuard();
+    const user = { user: { id: 'user_1' }, workspace: { id: 'ws_1' } };
+
+    expect(guard.handleRequest(null, user, null, createCtx())).toBe(user);
+    expect(reflector.getAllAndOverride).not.toHaveBeenCalledWith(
+      OAUTH_SCOPE_KEY,
+      expect.anything(),
+    );
+  });
+
+  it('forbids an oauth user on a route without scope metadata', () => {
+    const { guard, reflector } = createGuard(undefined);
+
+    expect(() =>
+      guard.handleRequest(null, oauthUser(['read', 'write']), null, createCtx()),
+    ).toThrow(ForbiddenException);
+    expect(reflector.getAllAndOverride).toHaveBeenCalledWith(OAUTH_SCOPE_KEY, [
+      handlerSentinel,
+      classSentinel,
+    ]);
+  });
+
+  it('passes read scope on a read route', () => {
+    const { guard } = createGuard('read');
+    const user = oauthUser(['read']);
+
+    expect(guard.handleRequest(null, user, null, createCtx())).toBe(user);
+  });
+
+  it('forbids read scope on a write route with insufficient_scope', () => {
+    const { guard } = createGuard('write');
+
+    expect(() =>
+      guard.handleRequest(null, oauthUser(['read']), null, createCtx()),
+    ).toThrow('insufficient_scope');
+  });
+
+  it('passes write scope on a read route', () => {
+    const { guard } = createGuard('read');
+    const user = oauthUser(['write']);
+
+    expect(guard.handleRequest(null, user, null, createCtx())).toBe(user);
+  });
+
+  it('passes write scope on a write route', () => {
+    const { guard } = createGuard('write');
+    const user = oauthUser(['write']);
+
+    expect(guard.handleRequest(null, user, null, createCtx())).toBe(user);
+  });
+
+  describe('session-only routes', () => {
+    const sessionUser = {
+      user: { id: 'user_1' },
+      workspace: { id: 'ws_1' },
+      authType: JwtType.ACCESS,
+    };
+
+    it('allows a signed-in session', () => {
+      const { guard } = createGuard(undefined, true);
+
+      expect(guard.handleRequest(null, sessionUser, null, createCtx())).toBe(
+        sessionUser,
+      );
+    });
+
+    it('forbids an api key', () => {
+      const { guard } = createGuard(undefined, true);
+      const apiKeyUser = {
+        user: { id: 'user_1' },
+        workspace: { id: 'ws_1' },
+        authType: JwtType.API_KEY,
+      };
+
+      expect(() =>
+        guard.handleRequest(null, apiKeyUser, null, createCtx()),
+      ).toThrow('This action requires an interactive user session');
+    });
+
+    it('forbids an oauth token even when it carries write scope', () => {
+      const { guard } = createGuard('write', true);
+      const user = { ...oauthUser(['write']), authType: JwtType.OAUTH_ACCESS };
+
+      expect(() => guard.handleRequest(null, user, null, createCtx())).toThrow(
+        'This action requires an interactive user session',
+      );
+    });
+
+    it('leaves api keys working on routes without the marker', () => {
+      const { guard } = createGuard(undefined, undefined);
+      const apiKeyUser = {
+        user: { id: 'user_1' },
+        workspace: { id: 'ws_1' },
+        authType: JwtType.API_KEY,
+      };
+
+      expect(guard.handleRequest(null, apiKeyUser, null, createCtx())).toBe(
+        apiKeyUser,
+      );
+    });
+  });
+
+  it('lets handler metadata override class metadata', () => {
+    const metadataByTarget = new Map<unknown, string>([
+      [handlerSentinel, 'write'],
+      [classSentinel, 'read'],
+    ]);
+    const reflector = {
+      getAllAndOverride: jest.fn((key: string, targets: unknown[]) => {
+        if (key === REQUIRE_SESSION_AUTH_KEY) {
+          return undefined;
+        }
+        for (const target of targets) {
+          if (metadataByTarget.has(target)) {
+            return metadataByTarget.get(target);
+          }
+        }
+        return undefined;
+      }),
+    } as any;
+    const environmentService = { isCloud: jest.fn().mockReturnValue(false) } as any;
+    const guard = new JwtAuthGuard(reflector, environmentService);
+
+    expect(() =>
+      guard.handleRequest(null, oauthUser(['read']), null, createCtx()),
+    ).toThrow('insufficient_scope');
+  });
+});
--- a/apps/server/src/common/guards/jwt-auth.guard.ts
+++ b/apps/server/src/common/guards/jwt-auth.guard.ts
@@ -0,0 +1,114 @@
+import {
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+  Logger,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+import { IS_PUBLIC_KEY } from '../decorators/public.decorator';
+import {
+  OAUTH_SCOPE_KEY,
+  OAuthRouteScope,
+} from '../decorators/oauth-scope.decorator';
+import { REQUIRE_SESSION_AUTH_KEY } from '../decorators/require-session-auth.decorator';
+import { JwtType } from '../../core/auth/dto/jwt-payload';
+import { Reflector } from '@nestjs/core';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { addDays } from 'date-fns';
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  private logger = new Logger('JwtAuthGuard');
+
+  constructor(
+    private reflector: Reflector,
+    private environmentService: EnvironmentService,
+  ) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isPublic) {
+      return true;
+    }
+
+    return super.canActivate(context);
+  }
+
+  handleRequest(err: any, user: any, info: any, ctx: ExecutionContext) {
+    if (err || !user) {
+      throw err || new UnauthorizedException();
+    }
+
+    const requiresSession = this.reflector.getAllAndOverride<boolean>(
+      REQUIRE_SESSION_AUTH_KEY,
+      [ctx.getHandler(), ctx.getClass()],
+    );
+    if (requiresSession && user.authType !== JwtType.ACCESS) {
+      this.logger.debug(
+        `session-only endpoint ${ctx.getClass()?.name}.${ctx.getHandler()?.name} refused authType ${user.authType}`,
+      );
+      throw new ForbiddenException(
+        'This action requires an interactive user session',
+      );
+    }
+
+    if (user.oauth) {
+      const required = this.reflector.getAllAndOverride<
+        OAuthRouteScope | undefined
+      >(OAUTH_SCOPE_KEY, [ctx.getHandler(), ctx.getClass()]);
+      if (!required) {
+        this.logger.warn(
+          `oauth scope check: no @OAuthScope metadata on ${ctx.getClass()?.name}.${ctx.getHandler()?.name}`,
+        );
+        throw new ForbiddenException('OAuth tokens cannot access this endpoint');
+      }
+      const scopes: string[] = user.oauth.scopes ?? [];
+      const satisfied =
+        required === 'read'
+          ? scopes.includes('read') || scopes.includes('write')
+          : scopes.includes('write');
+      if (!satisfied) {
+        throw new ForbiddenException('insufficient_scope');
+      }
+    }
+
+    this.setJoinedWorkspacesCookie(user, ctx);
+    return user;
+  }
+
+  setJoinedWorkspacesCookie(user: any, ctx: ExecutionContext) {
+    if (this.environmentService.isCloud()) {
+      const req = ctx.switchToHttp().getRequest();
+      const res = ctx.switchToHttp().getResponse();
+
+      const workspaceId = user?.workspace?.id;
+      let workspaceIds = [];
+      try {
+        workspaceIds = req.cookies.joinedWorkspaces
+          ? JSON.parse(req.cookies.joinedWorkspaces)
+          : [];
+      } catch (err) {
+        /* empty */
+      }
+
+      if (!workspaceIds.includes(workspaceId)) {
+        workspaceIds.push(workspaceId);
+      }
+
+      res.setCookie('joinedWorkspaces', JSON.stringify(workspaceIds), {
+        httpOnly: false,
+        domain: '.' + this.environmentService.getSubdomainHost(),
+        path: '/',
+        expires: addDays(new Date(), 365),
+        secure: this.environmentService.isHttps(),
+      });
+    }
+  }
+}
--- a/apps/server/src/common/helpers/cache-keys.ts
+++ b/apps/server/src/common/helpers/cache-keys.ts
@@ -0,0 +1,12 @@
+export const CacheKey = {
+  LICENSE_VALID: (workspaceId: string) => `license:valid:${workspaceId}`,
+  SPACE_ROLES: (userId: string, spaceId: string) =>
+    `perm:space-roles:${userId}:${spaceId}`,
+  PAGE_CAN_EDIT: (userId: string, pageId: string) =>
+    `perm:can-edit:${userId}:${pageId}`,
+  SIEM_LICENSED: (workspaceId: string) => `siem:licensed:${workspaceId}`,
+};
+
+// Permission caches dedupe repeated checks within and across short request bursts.
+// 5s keeps staleness on revocations bounded.
+export const PERMISSION_CACHE_TTL_MS = 5_000;
--- a/apps/server/src/common/helpers/constants.ts
+++ b/apps/server/src/common/helpers/constants.ts
@@ -0,0 +1,18 @@
+import * as path from 'path';
+
+export const APP_DATA_PATH = 'data';
+const LOCAL_STORAGE_DIR = `${APP_DATA_PATH}/storage`;
+
+export const LOCAL_STORAGE_PATH = path.resolve(
+  process.cwd(),
+  '..',
+  '..',
+  LOCAL_STORAGE_DIR,
+);
+
+export function getPageTitle(
+  title: string | null | undefined,
+  isBase?: boolean,
+): string {
+  return title || (isBase ? 'Untitled base' : 'untitled');
+}
--- a/apps/server/src/common/helpers/file.helper.ts
+++ b/apps/server/src/common/helpers/file.helper.ts
@@ -0,0 +1,7 @@
+import * as mime from 'mime-types';
+import * as path from 'node:path';
+
+export function getMimeType(filePath: string): string {
+  const ext = path.extname(filePath);
+  return mime.contentType(ext) || 'application/octet-stream';
+}
--- a/apps/server/src/common/helpers/html-escaper.ts
+++ b/apps/server/src/common/helpers/html-escaper.ts
@@ -0,0 +1,71 @@
+// https://github.com/WebReflection/html-escaper
+/**
+ * Copyright (C) 2017-present by Andrea Giammarchi - @WebReflection
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+const { replace } = '';
+
+// escape
+const es = /&(?:amp|#38|lt|#60|gt|#62|apos|#39|quot|#34);/g;
+const ca = /[&<>'"]/g;
+
+const esca = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  "'": '&#39;',
+  '"': '&quot;',
+};
+const pe = (m) => esca[m];
+
+/**
+ * Safely escape HTML entities such as `&`, `<`, `>`, `"`, and `'`.
+ * @param {string} es the input to safely escape
+ * @returns {string} the escaped input, and it **throws** an error if
+ *  the input type is unexpected, except for boolean and numbers,
+ *  converted as string.
+ */
+export const htmlEscape = (es) => replace.call(es, ca, pe);
+
+// unescape
+const unes = {
+  '&amp;': '&',
+  '&#38;': '&',
+  '&lt;': '<',
+  '&#60;': '<',
+  '&gt;': '>',
+  '&#62;': '>',
+  '&apos;': "'",
+  '&#39;': "'",
+  '&quot;': '"',
+  '&#34;': '"',
+};
+const cape = (m) => unes[m];
+
+/**
+ * Safely unescape previously escaped entities such as `&`, `<`, `>`, `"`,
+ * and `'`.
+ * @param {string} un a previously escaped string
+ * @returns {string} the unescaped input, and it **throws** an error if
+ *  the input type is unexpected, except for boolean and numbers,
+ *  converted as string.
+ */
+export const htmlUnescape = (un) => replace.call(un, es, cape);
--- a/apps/server/src/common/helpers/index.ts
+++ b/apps/server/src/common/helpers/index.ts
@@ -0,0 +1,6 @@
+export * from './utils';
+export * from './text.utils';
+export * from './nanoid.utils';
+export * from './file.helper';
+export * from './constants';
+export * from './security-headers';
--- a/apps/server/src/common/helpers/nanoid.utils.ts
+++ b/apps/server/src/common/helpers/nanoid.utils.ts
@@ -0,0 +1,13 @@
+import { customAlphabet } from 'nanoid';
+
+const alphabet = '0123456789abcdefghijklmnopqrstuvwxyz';
+export const nanoIdGen = customAlphabet(alphabet, 10);
+
+const slugIdAlphabet =
+  '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+export const generateSlugId = customAlphabet(slugIdAlphabet, 10);
+
+const baseIdSuffix = customAlphabet(alphabet, 9);
+
+export const generateBasePropertyId = (): string => `prp${baseIdSuffix()}`;
+export const generateBaseChoiceId = (): string => `opt${baseIdSuffix()}`;
--- a/apps/server/src/common/helpers/prosemirror/attachment-node-types.ts
+++ b/apps/server/src/common/helpers/prosemirror/attachment-node-types.ts
@@ -0,0 +1,13 @@
+const ATTACHMENT_NODE_TYPES = [
+  'attachment',
+  'image',
+  'video',
+  'audio',
+  'pdf',
+  'excalidraw',
+  'drawio',
+];
+
+export function isAttachmentNode(nodeType: string): boolean {
+  return ATTACHMENT_NODE_TYPES.includes(nodeType);
+}
--- a/apps/server/src/common/helpers/prosemirror/html/generateHTML.ts
+++ b/apps/server/src/common/helpers/prosemirror/html/generateHTML.ts
@@ -0,0 +1,29 @@
+import { type Extensions, type JSONContent, getSchema } from '@tiptap/core';
+import { Node } from '@tiptap/pm/model';
+import { getHTMLFromFragment } from './getHTMLFromFragment';
+
+/**
+ * This function generates HTML from a ProseMirror JSON content object.
+ *
+ * @remarks **Important**: This function requires `happy-dom` to be installed in your project.
+ * @param doc - The ProseMirror JSON content object.
+ * @param extensions - The Tiptap extensions used to build the schema.
+ * @returns The generated HTML string.
+ * @example
+ * ```js
+ * const html = generateHTML(doc, extensions)
+ * console.log(html)
+ * ```
+ */
+export function generateHTML(doc: JSONContent, extensions: Extensions): string {
+  if (typeof window !== 'undefined') {
+    throw new Error(
+      'generateHTML can only be used in a Node environment\nIf you want to use this in a browser environment, use the `@tiptap/html` import instead.',
+    );
+  }
+
+  const schema = getSchema(extensions);
+  const contentNode = Node.fromJSON(schema, doc);
+
+  return getHTMLFromFragment(contentNode, schema);
+}
--- a/apps/server/src/common/helpers/prosemirror/html/generateJSON.ts
+++ b/apps/server/src/common/helpers/prosemirror/html/generateJSON.ts
@@ -0,0 +1,55 @@
+import type { Extensions } from '@tiptap/core';
+import { getSchema } from '@tiptap/core';
+import { type ParseOptions, DOMParser as PMDOMParser } from '@tiptap/pm/model';
+import { Window } from 'happy-dom';
+
+/**
+ * Generates a JSON object from the given HTML string and converts it into a Prosemirror node with content.
+ * @remarks **Important**: This function requires `happy-dom` to be installed in your project.
+ * @param {string} html - The HTML string to be converted into a Prosemirror node.
+ * @param {Extensions} extensions - The extensions to be used for generating the schema.
+ * @param {ParseOptions} options - The options to be supplied to the parser.
+ * @returns {Promise<Record<string, any>>} - A promise with the generated JSON object.
+ * @example
+ * const html = '<p>Hello, world!</p>'
+ * const extensions = [...]
+ * const json = generateJSON(html, extensions)
+ * console.log(json) // { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello, world!' }] }] }
+ */
+export function generateJSON(
+  html: string,
+  extensions: Extensions,
+  options?: ParseOptions,
+): Record<string, any> {
+  if (typeof window !== 'undefined') {
+    throw new Error(
+      'generateJSON can only be used in a Node environment\nIf you want to use this in a browser environment, use the `@tiptap/html` import instead.',
+    );
+  }
+
+  const localWindow = new Window();
+  const localDOMParser = new localWindow.DOMParser();
+  let result: Record<string, any>;
+
+  try {
+    const schema = getSchema(extensions);
+    let doc: ReturnType<typeof localDOMParser.parseFromString> | null = null;
+
+    const htmlString = `<!DOCTYPE html><html><body>${html}</body></html>`;
+    doc = localDOMParser.parseFromString(htmlString, 'text/html');
+
+    if (!doc) {
+      throw new Error('Failed to parse HTML string');
+    }
+
+    result = PMDOMParser.fromSchema(schema)
+      .parse(doc.body as unknown as Node, options)
+      .toJSON();
+  } finally {
+    // clean up happy-dom to avoid memory leaks
+    localWindow.happyDOM.abort();
+    localWindow.happyDOM.close();
+  }
+
+  return result;
+}
--- a/apps/server/src/common/helpers/prosemirror/html/getHTMLFromFragment.ts
+++ b/apps/server/src/common/helpers/prosemirror/html/getHTMLFromFragment.ts
@@ -0,0 +1,54 @@
+import type { Node, Schema } from '@tiptap/pm/model';
+import { DOMSerializer } from '@tiptap/pm/model';
+import { Window } from 'happy-dom';
+
+/**
+ * Returns the HTML string representation of a given document node.
+ *
+ * @remarks **Important**: This function requires `happy-dom` to be installed in your project.
+ * @param doc - The document node to serialize.
+ * @param schema - The Prosemirror schema to use for serialization.
+ * @returns A promise containing the HTML string representation of the document fragment.
+ *
+ * @example
+ * ```typescript
+ * const html = getHTMLFromFragment(doc, schema)
+ * ```
+ */
+export function getHTMLFromFragment(
+  doc: Node,
+  schema: Schema,
+  options?: { document?: Document },
+): string {
+  if (options?.document) {
+    const wrap = options.document.createElement('div');
+
+    DOMSerializer.fromSchema(schema).serializeFragment(
+      doc.content,
+      { document: options.document },
+      wrap,
+    );
+    return wrap.innerHTML;
+  }
+
+  const localWindow = new Window();
+  let result: string;
+
+  try {
+    const fragment = DOMSerializer.fromSchema(schema).serializeFragment(
+      doc.content,
+      {
+        document: localWindow.document as unknown as Document,
+      },
+    );
+
+    const serializer = new localWindow.XMLSerializer();
+    result = serializer.serializeToString(fragment as any);
+  } finally {
+    // clean up happy-dom to avoid memory leaks
+    localWindow.happyDOM.abort();
+    localWindow.happyDOM.close();
+  }
+
+  return result;
+}
--- a/apps/server/src/common/helpers/prosemirror/html/index.ts
+++ b/apps/server/src/common/helpers/prosemirror/html/index.ts
@@ -0,0 +1,2 @@
+export * from './generateHTML';
+export * from './generateJSON';
--- a/apps/server/src/common/helpers/prosemirror/indent-schema.spec.ts
+++ b/apps/server/src/common/helpers/prosemirror/indent-schema.spec.ts
@@ -0,0 +1,63 @@
+import { htmlToJson, jsonToHtml } from '../../../collaboration/collaboration.util';
+
+const findFirstChild = (
+  json: any,
+  type: string,
+): any | undefined => {
+  if (!json || typeof json !== 'object') return undefined;
+  if (json.type === type) return json;
+  if (Array.isArray(json.content)) {
+    for (const child of json.content) {
+      const found = findFirstChild(child, type);
+      if (found) return found;
+    }
+  }
+  return undefined;
+};
+
+describe('indent attribute round-trip', () => {
+  it('parses data-indent on a paragraph into the indent attribute', () => {
+    const html = '<p data-indent="3">Hello</p>';
+    const json = htmlToJson(html);
+    const paragraph = findFirstChild(json, 'paragraph');
+    expect(paragraph).toBeDefined();
+    expect(paragraph.attrs.indent).toBe(3);
+  });
+
+  it('parses data-indent on a heading into the indent attribute', () => {
+    const html = '<h2 data-indent="2">Heading</h2>';
+    const json = htmlToJson(html);
+    const heading = findFirstChild(json, 'heading');
+    expect(heading).toBeDefined();
+    expect(heading.attrs.indent).toBe(2);
+    expect(heading.attrs.level).toBe(2);
+  });
+
+  it('clamps out-of-range data-indent values', () => {
+    const html = '<p data-indent="42">Too deep</p>';
+    const json = htmlToJson(html);
+    const paragraph = findFirstChild(json, 'paragraph');
+    expect(paragraph.attrs.indent).toBe(8);
+  });
+
+  it('renders nonzero indent back to data-indent on HTML serialization', () => {
+    const html = '<p data-indent="4">Round-trip</p>';
+    const json = htmlToJson(html);
+    const out = jsonToHtml(json);
+    expect(out).toContain('data-indent="4"');
+  });
+
+  it('omits data-indent for indent zero', () => {
+    const html = '<p>No indent</p>';
+    const json = htmlToJson(html);
+    const out = jsonToHtml(json);
+    expect(out).not.toContain('data-indent');
+  });
+
+  it('preserves indent through HTML → JSON → HTML', () => {
+    const original = '<p data-indent="5">Five deep</p>';
+    const json = htmlToJson(original);
+    const final = jsonToHtml(json);
+    expect(final).toContain('data-indent="5"');
+  });
+});
--- a/apps/server/src/common/helpers/prosemirror/utils.ts
+++ b/apps/server/src/common/helpers/prosemirror/utils.ts
@@ -0,0 +1,170 @@
+import { Node } from '@tiptap/pm/model';
+import {
+  jsonToNode,
+  tiptapExtensions,
+} from '../../../collaboration/collaboration.util';
+import { validate as isValidUUID } from 'uuid';
+import { Transform } from '@tiptap/pm/transform';
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import * as Y from 'yjs';
+import {
+  INTERNAL_LINK_REGEX,
+  extractPageSlugId,
+} from '../../../integrations/export/utils';
+import { isAttachmentNode } from './attachment-node-types';
+
+export interface MentionNode {
+  id: string;
+  label: string;
+  entityType: 'user' | 'page';
+  entityId: string;
+  creatorId: string;
+}
+
+export function extractMentions(prosemirrorJson: any) {
+  const mentionList: MentionNode[] = [];
+  const doc = jsonToNode(prosemirrorJson);
+
+  doc.descendants((node: Node) => {
+    if (node.type.name === 'mention') {
+      if (
+        node.attrs.id &&
+        !mentionList.some((mention) => mention.id === node.attrs.id)
+      ) {
+        mentionList.push({
+          id: node.attrs.id,
+          label: node.attrs.label,
+          entityType: node.attrs.entityType,
+          entityId: node.attrs.entityId,
+          creatorId: node.attrs.creatorId,
+        });
+      }
+    }
+  });
+  return mentionList;
+}
+
+export function extractUserMentions(mentionList: MentionNode[]): MentionNode[] {
+  const userList = [];
+  for (const mention of mentionList) {
+    if (mention.entityType === 'user') {
+      userList.push(mention);
+    }
+  }
+  return userList as MentionNode[];
+}
+
+export function extractPageMentions(mentionList: MentionNode[]): MentionNode[] {
+  const pageMentionList = [];
+  for (const mention of mentionList) {
+    if (
+      mention.entityType === 'page' &&
+      !pageMentionList.some(
+        (pageMention) => pageMention.entityId === mention.entityId,
+      )
+    ) {
+      pageMentionList.push(mention);
+    }
+  }
+  return pageMentionList as MentionNode[];
+}
+
+export function extractInternalLinkSlugIds(prosemirrorJson: any): string[] {
+  const slugIds: string[] = [];
+  const doc = jsonToNode(prosemirrorJson);
+
+  doc.descendants((node: Node) => {
+    for (const mark of node.marks) {
+      if (mark.type.name === 'link' && mark.attrs.internal && mark.attrs.href) {
+        const match = mark.attrs.href.match(INTERNAL_LINK_REGEX);
+        if (match) {
+          const slugId = extractPageSlugId(match[5]);
+          if (slugId && !slugIds.includes(slugId)) {
+            slugIds.push(slugId);
+          }
+        }
+      }
+    }
+  });
+
+  return slugIds;
+}
+
+export function extractUserMentionIdsFromJson(json: any): string[] {
+  const userIds: string[] = [];
+
+  function walk(node: any) {
+    if (!node) return;
+    if (
+      node.type === 'mention' &&
+      node.attrs?.entityType === 'user' &&
+      node.attrs?.entityId &&
+      !userIds.includes(node.attrs.entityId)
+    ) {
+      userIds.push(node.attrs.entityId);
+    }
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) {
+        walk(child);
+      }
+    }
+  }
+
+  walk(json);
+  return userIds;
+}
+
+export function getProsemirrorContent(content: any) {
+  return (
+    content ?? {
+      type: 'doc',
+      content: [{ type: 'paragraph', attrs: { textAlign: 'left' } }],
+    }
+  );
+}
+
+export { isAttachmentNode };
+
+export function getAttachmentIds(prosemirrorJson: any) {
+  const doc = jsonToNode(prosemirrorJson);
+  const attachmentIds = [];
+
+  doc?.descendants((node: Node) => {
+    if (isAttachmentNode(node.type.name)) {
+      if (node.attrs.attachmentId && isValidUUID(node.attrs.attachmentId)) {
+        if (!attachmentIds.includes(node.attrs.attachmentId)) {
+          attachmentIds.push(node.attrs.attachmentId);
+        }
+      }
+    }
+  });
+
+  return attachmentIds;
+}
+
+export function removeMarkTypeFromDoc(doc: Node, markName: string): Node {
+  const { schema } = doc.type;
+  const markType = schema.marks[markName];
+
+  if (!markType) {
+    return doc;
+  }
+
+  const tr = new Transform(doc).removeMark(0, doc.content.size, markType);
+  return tr.doc;
+}
+
+export function createYdocFromJson(prosemirrorJson: any): Buffer | null {
+  if (prosemirrorJson) {
+    const ydoc = TiptapTransformer.toYdoc(
+      prosemirrorJson,
+      'default',
+      tiptapExtensions,
+    );
+
+    Y.encodeStateAsUpdate(ydoc);
+
+    return Buffer.from(Y.encodeStateAsUpdate(ydoc));
+  }
+  return null;
+}
--- a/apps/server/src/common/helpers/security-headers.spec.ts
+++ b/apps/server/src/common/helpers/security-headers.spec.ts
@@ -0,0 +1,66 @@
+import {
+  resolveFrameHeader,
+  resolveFrameHeadersForPath,
+  SecurityHeader,
+} from './security-headers';
+
+describe('resolveFrameHeader', () => {
+  it('denies framing with X-Frame-Options when embedding is off', () => {
+    expect(resolveFrameHeader(false, [])).toEqual({
+      name: 'X-Frame-Options',
+      value: 'SAMEORIGIN',
+    });
+  });
+
+  it('returns null when embedding is on but no origins are configured', () => {
+    expect(resolveFrameHeader(true, [])).toBeNull();
+  });
+
+  it('emits a frame-ancestors CSP for the allowed origins', () => {
+    expect(resolveFrameHeader(true, ['https://a.example', 'https://b.example']))
+      .toEqual({
+        name: 'Content-Security-Policy',
+        value: "frame-ancestors 'self' https://a.example https://b.example",
+      });
+  });
+});
+
+describe('resolveFrameHeadersForPath', () => {
+  const configured: SecurityHeader = {
+    name: 'Content-Security-Policy',
+    value: "frame-ancestors 'self' https://a.example",
+  };
+
+  it.each(['/oauth/consent', '/oauth/consent/nested'])(
+    'force-denies %s regardless of configured header',
+    (path) => {
+      expect(resolveFrameHeadersForPath(path, configured)).toEqual([
+        { name: 'X-Frame-Options', value: 'DENY' },
+        { name: 'Content-Security-Policy', value: "frame-ancestors 'none'" },
+      ]);
+    },
+  );
+
+  it('force-denies consent even when the global header is absent', () => {
+    expect(resolveFrameHeadersForPath('/oauth/consent', null)).toEqual([
+      { name: 'X-Frame-Options', value: 'DENY' },
+      { name: 'Content-Security-Policy', value: "frame-ancestors 'none'" },
+    ]);
+  });
+
+  it('does not match an unrelated path that merely contains the prefix', () => {
+    expect(
+      resolveFrameHeadersForPath('/oauth/consenting-adults', configured),
+    ).toEqual([configured]);
+  });
+
+  it('passes the configured header through for other paths', () => {
+    expect(resolveFrameHeadersForPath('/home', configured)).toEqual([
+      configured,
+    ]);
+  });
+
+  it('returns nothing for other paths when no header is configured', () => {
+    expect(resolveFrameHeadersForPath('/home', null)).toEqual([]);
+  });
+});
--- a/apps/server/src/common/helpers/security-headers.ts
+++ b/apps/server/src/common/helpers/security-headers.ts
@@ -0,0 +1,35 @@
+export type SecurityHeader = { name: string; value: string };
+
+export function resolveFrameHeader(
+  iframeEmbedAllowed: boolean,
+  allowedOrigins: string[],
+): SecurityHeader | null {
+  if (!iframeEmbedAllowed) {
+    return { name: 'X-Frame-Options', value: 'SAMEORIGIN' };
+  }
+
+  if (allowedOrigins.length === 0) {
+    return null;
+  }
+
+  return {
+    name: 'Content-Security-Policy',
+    value: `frame-ancestors 'self' ${allowedOrigins.join(' ')}`,
+  };
+}
+
+// Deny OAuth consent in iframe
+export const OAUTH_CONSENT_PATH = '/oauth/consent';
+
+export function resolveFrameHeadersForPath(
+  path: string,
+  configuredHeader: SecurityHeader | null,
+): SecurityHeader[] {
+  if (path === OAUTH_CONSENT_PATH || path.startsWith(`${OAUTH_CONSENT_PATH}/`)) {
+    return [
+      { name: 'X-Frame-Options', value: 'DENY' },
+      { name: 'Content-Security-Policy', value: "frame-ancestors 'none'" },
+    ];
+  }
+  return configuredHeader ? [configuredHeader] : [];
+}
--- a/apps/server/src/common/helpers/text.utils.spec.ts
+++ b/apps/server/src/common/helpers/text.utils.spec.ts
@@ -0,0 +1,14 @@
+import { collapseBlankLines } from './text.utils';
+
+describe('collapseBlankLines', () => {
+  it.each([
+    ['a\n\n\n\nb', 'a\n\nb'],
+    ['a\n\nb', 'a\n\nb'],
+    ['a\nb', 'a\nb'],
+    ['\n\n\n\na\n\n\n', '\n\na\n\n'],
+    ['no newlines', 'no newlines'],
+    ['', ''],
+  ])('collapses %j to %j', (input, expected) => {
+    expect(collapseBlankLines(input)).toBe(expected);
+  });
+});
--- a/apps/server/src/common/helpers/text.utils.ts
+++ b/apps/server/src/common/helpers/text.utils.ts
@@ -0,0 +1,3 @@
+export function collapseBlankLines(text: string): string {
+  return text.replace(/\n{2,}/g, '\n\n');
+}
--- a/apps/server/src/common/helpers/types/export-metadata.types.ts
+++ b/apps/server/src/common/helpers/types/export-metadata.types.ts
@@ -0,0 +1,16 @@
+export type ExportPageMetadata = {
+  pageId: string;
+  slugId: string;
+  icon: string | null;
+  position: string;
+  parentPath: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type ExportMetadata = {
+  exportedAt: string;
+  source: 'docmost';
+  version: string;
+  pages: Record<string, ExportPageMetadata>;
+};
--- a/apps/server/src/common/helpers/types/permission.ts
+++ b/apps/server/src/common/helpers/types/permission.ts
@@ -0,0 +1,30 @@
+export enum UserRole {
+  OWNER = 'owner',
+  ADMIN = 'admin', // can have owner permissions but cannot delete workspace
+  MEMBER = 'member',
+}
+
+export enum InviteUserRole {
+  ADMIN = 'admin', // can have owner permissions but cannot delete workspace
+  MEMBER = 'member',
+}
+
+export enum SpaceRole {
+  ADMIN = 'admin', // can manage space settings, members, and delete space
+  WRITER = 'writer', // can read and write pages in space
+  READER = 'reader', // can only read pages in space
+}
+
+export enum SpaceVisibility {
+  OPEN = 'open', // any workspace member can see that it exists and join.
+  PRIVATE = 'private', // only added space users can see
+}
+
+export enum PageAccessLevel {
+  RESTRICTED = 'restricted', // only specific users/groups can view or edit
+}
+
+export enum PagePermissionRole {
+  READER = 'reader', // can only view content and descendants
+  WRITER = 'writer', // can edit content, descendants, and add new users to permission
+}
--- a/apps/server/src/common/helpers/utils.spec.ts
+++ b/apps/server/src/common/helpers/utils.spec.ts
--- a/apps/server/src/common/helpers/utils.ts
+++ b/apps/server/src/common/helpers/utils.ts
@@ -0,0 +1,217 @@
+import * as path from 'path';
+import * as bcrypt from 'bcrypt';
+import sanitize = require('sanitize-filename');
+import { FastifyRequest } from 'fastify';
+import { Readable, Transform } from 'stream';
+
+export const envPath = path.resolve(process.cwd(), '..', '..', '.env');
+
+export async function hashPassword(password: string) {
+  const saltRounds = 12;
+  return bcrypt.hash(password, saltRounds);
+}
+
+export async function comparePasswordHash(
+  plainPassword: string,
+  passwordHash: string,
+): Promise<boolean> {
+  return bcrypt.compare(plainPassword, passwordHash);
+}
+
+export function generateRandomSuffixNumbers(length: number) {
+  return Math.random()
+    .toFixed(length)
+    .substring(2, 2 + length);
+}
+
+export type RedisConfig = {
+  host: string;
+  port: number;
+  db: number;
+  username?: string;
+  password?: string;
+  family?: number;
+  tls?: { rejectUnauthorized?: boolean };
+};
+
+export function parseRedisUrl(redisUrl: string): RedisConfig {
+  // format - redis[s]://[[username][:password]@][host][:port][/db-number][?family=4|6][&rejectUnauthorized=false]
+  const url = new URL(redisUrl);
+  const {
+    hostname,
+    port,
+    username,
+    password,
+    pathname,
+    protocol,
+    searchParams,
+  } = url;
+  const portInt = port ? parseInt(port, 10) : 6379;
+
+  let db: number = 0;
+  // extract db value if present
+  if (pathname.length > 1) {
+    const value = pathname.slice(1);
+    if (!isNaN(parseInt(value))) {
+      db = parseInt(value, 10);
+    }
+  }
+
+  // extract family from query parameters
+  let family: number | undefined;
+  const familyParam = searchParams.get('family');
+  if (familyParam && !isNaN(parseInt(familyParam))) {
+    family = parseInt(familyParam, 10);
+  }
+
+  const tls =
+    protocol === 'rediss:'
+      ? searchParams.get('rejectUnauthorized') === 'false'
+        ? { rejectUnauthorized: false }
+        : {}
+      : undefined;
+
+  return {
+    host: hostname,
+    port: portInt,
+    username: username ? decodeURIComponent(username) : undefined,
+    password: password ? decodeURIComponent(password) : undefined,
+    db,
+    family,
+    tls,
+  };
+}
+
+export function createRetryStrategy() {
+  return function (times: number): number {
+    return Math.max(Math.min(Math.exp(times), 20000), 3000);
+  };
+}
+
+export function extractDateFromUuid7(uuid7: string) {
+  //https://park.is/blog_posts/20240803_extracting_timestamp_from_uuid_v7/
+  const parts = uuid7.split('-');
+  const highBitsHex = parts[0] + parts[1].slice(0, 4);
+  const timestamp = parseInt(highBitsHex, 16);
+
+  return new Date(timestamp);
+}
+
+export type SanitizeFileNameOptions = {
+  /** Keep spaces and `#` instead of replacing them with `_`. Useful for
+   * download filenames where readability matters. Defaults to false. */
+  preserveSpaces?: boolean;
+};
+
+export function sanitizeFileName(
+  fileName: string,
+  options: SanitizeFileNameOptions = {},
+): string {
+  // Decode percent-encoded sequences so that bypasses like "..%2F" reach
+  // sanitize() as literal "../" and get stripped. sanitize-filename only
+  // strips literal characters and won't catch encoded path separators
+  // on its own.
+  const decoded = fileName.replace(/%[0-9a-fA-F]{2}/g, (m) => {
+    try {
+      return decodeURIComponent(m);
+    } catch {
+      return m;
+    }
+  });
+
+  const sanitized = sanitize(decoded);
+  if (options.preserveSpaces) {
+    return sanitized;
+  }
+  return sanitized.replace(/ /g, '_').replace(/#/g, '_');
+}
+
+export function removeAccent(str: string): string {
+  if (!str) return str;
+  return str.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+
+export function extractBearerTokenFromHeader(
+  request: FastifyRequest,
+): string | undefined {
+  const [type, token] = request.headers.authorization?.split(' ') ?? [];
+  return type?.toLowerCase() === 'bearer' ? token : undefined;
+}
+
+/**
+ * Normalizes a database URL for postgres.js compatibility.
+ * - Removes `sslmode=no-verify` (not supported by postgres.js), keeps other sslmode values
+ * - Removes `schema` parameter (has no effect via connection string)
+ * Note: If we don't strip them, the connection will fail
+ */
+export function normalizePostgresUrl(url: string): string {
+  const parsed = new URL(url);
+  const newParams = new URLSearchParams();
+
+  for (const [key, value] of parsed.searchParams) {
+    if (key === 'sslmode' && value === 'no-verify') continue;
+    if (key === 'schema') continue;
+    newParams.append(key, value);
+  }
+
+  parsed.search = newParams.toString();
+  return parsed.toString();
+}
+
+export function diffAuditTrackedFields(
+  fields: readonly string[],
+  dto: Record<string, any>,
+  before: Record<string, any> | undefined | null,
+  after: Record<string, any> | undefined | null,
+): { before: Record<string, any>; after: Record<string, any> } | null {
+  const beforeDiff: Record<string, any> = {};
+  const afterDiff: Record<string, any> = {};
+  let hasChanges = false;
+
+  for (const field of fields) {
+    if (typeof dto[field] === 'undefined') continue;
+    const oldVal = JSON.stringify(before?.[field] ?? null);
+    const newVal = JSON.stringify(after?.[field] ?? null);
+    if (oldVal !== newVal) {
+      beforeDiff[field] = before?.[field];
+      afterDiff[field] = after?.[field];
+      hasChanges = true;
+    }
+  }
+
+  return hasChanges ? { before: beforeDiff, after: afterDiff } : null;
+}
+
+export function isUserDisabled(user: {
+  deactivatedAt?: Date | null;
+  deletedAt?: Date | null;
+}): boolean {
+  return !!(user.deactivatedAt || user.deletedAt);
+}
+
+const SENSITIVE_URL_PREFIXES = ['/api/sso/'];
+
+export function redactSensitiveUrl(url: string): string {
+  if (url && SENSITIVE_URL_PREFIXES.some((prefix) => url.includes(prefix))) {
+    const qsIndex = url.indexOf('?');
+    if (qsIndex !== -1) {
+      return url.substring(0, qsIndex);
+    }
+  }
+  return url;
+}
+
+export function createByteCountingStream(source: Readable) {
+  let bytesRead = 0;
+  const stream = new Transform({
+    transform(chunk, encoding, callback) {
+      bytesRead += chunk.length;
+      callback(null, chunk);
+    },
+  });
+
+  source.pipe(stream);
+  source.on('error', (err) => stream.emit('error', err));
+
+  return { stream, getBytesRead: () => bytesRead };
+}
--- a/apps/server/src/common/helpers/with-cache.ts
+++ b/apps/server/src/common/helpers/with-cache.ts
@@ -0,0 +1,27 @@
+import { Cache } from 'cache-manager';
+
+export async function withCache<T>(
+  cacheManager: Cache,
+  key: string,
+  ttlMs: number,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    const cached = await cacheManager.get<{ v: T }>(key);
+    if (cached !== undefined && cached !== null) {
+      return cached.v;
+    }
+  } catch (err) {
+    console.warn(`[withCache] get failed for "${key}", falling back to source`, err);
+  }
+
+  const value = await fn();
+
+  try {
+    await cacheManager.set(key, { v: value }, ttlMs);
+  } catch (err) {
+    console.warn(`[withCache] set failed for "${key}"`, err);
+  }
+
+  return value;
+}
--- a/apps/server/src/common/interceptors/audit-actor.interceptor.ts
+++ b/apps/server/src/common/interceptors/audit-actor.interceptor.ts
@@ -0,0 +1,29 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { ClsService } from 'nestjs-cls';
+import { AuditContext, AUDIT_CONTEXT_KEY } from '../middlewares/audit-context.middleware';
+
+@Injectable()
+export class AuditActorInterceptor implements NestInterceptor {
+  constructor(private readonly cls: ClsService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const request = context.switchToHttp().getRequest();
+    const user = request.user?.user;
+
+    if (user?.id) {
+      const auditContext = this.cls.get<AuditContext>(AUDIT_CONTEXT_KEY);
+      if (auditContext) {
+        auditContext.actorId = user.id;
+        this.cls.set(AUDIT_CONTEXT_KEY, auditContext);
+      }
+    }
+
+    return next.handle();
+  }
+}
--- a/apps/server/src/common/interceptors/file.interceptor.ts
+++ b/apps/server/src/common/interceptors/file.interceptor.ts
@@ -0,0 +1,25 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  BadRequestException,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { FastifyRequest } from 'fastify';
+
+@Injectable()
+export class FileInterceptor implements NestInterceptor {
+  public intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<any> {
+    const req: FastifyRequest = context.switchToHttp().getRequest();
+
+    if (!req.isMultipart() || !req.file) {
+      throw new BadRequestException('Invalid multipart content type');
+    }
+
+    return next.handle();
+  }
+}
--- a/apps/server/src/common/interceptors/http-response.interceptor.ts
+++ b/apps/server/src/common/interceptors/http-response.interceptor.ts
@@ -0,0 +1,40 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { map, Observable } from 'rxjs';
+import { Reflector } from '@nestjs/core';
+import { SKIP_TRANSFORM_KEY } from '../decorators/skip-transform.decorator';
+export interface Response<T> {
+  data: T;
+}
+
+@Injectable()
+export class TransformHttpResponseInterceptor<T>
+  implements NestInterceptor<T, Response<T>>
+{
+  constructor(private reflector: Reflector) {}
+
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler<T>,
+  ): Observable<Response<T> | any> {
+    const skipTransform = this.reflector.get(
+      SKIP_TRANSFORM_KEY,
+      context.getHandler(),
+    );
+
+    if (skipTransform) {
+      return next.handle();
+    }
+
+    return next.handle().pipe(
+      map((data) => {
+        const status = context.switchToHttp().getResponse().statusCode;
+        return { data, success: true, status };
+      }),
+    );
+  }
+}
--- a/apps/server/src/common/logger/internal-log-filter.ts
+++ b/apps/server/src/common/logger/internal-log-filter.ts
@@ -0,0 +1,82 @@
+import { ConsoleLogger, LogLevel } from '@nestjs/common';
+
+export class InternalLogFilter extends ConsoleLogger {
+  static contextsToIgnore = [
+    'NestFactory',
+    'InstanceLoader',
+    'RoutesResolver',
+    'RouterExplorer',
+    'WebSocketsController',
+  ];
+
+  private allowedLogLevels: string[];
+
+  constructor() {
+    const isProduction = process.env.NODE_ENV === 'production';
+    super({
+      json: isProduction,
+    });
+    const isDebugMode = process.env.DEBUG_MODE === 'true';
+
+    if (isProduction && !isDebugMode) {
+      this.allowedLogLevels = ['info', 'error', 'fatal'];
+    } else {
+      this.allowedLogLevels = [
+        'info',
+        'debug',
+        'verbose',
+        'warn',
+        'error',
+        'fatal',
+      ];
+    }
+  }
+
+  private isLogLevelAllowed(level: string): boolean {
+    return this.allowedLogLevels.includes(level);
+  }
+
+  log(_: any, context?: string): void {
+    if (
+      this.isLogLevelAllowed('info') &&
+      !InternalLogFilter.contextsToIgnore.includes(context)
+    ) {
+      super.log.apply(this, arguments);
+    }
+  }
+
+  warn(_: any, context?: string): void {
+    if (this.isLogLevelAllowed('warn')) {
+      super.warn.apply(this, arguments);
+    }
+  }
+
+  error(_: any, stack?: string, context?: string): void {
+    if (this.isLogLevelAllowed('error')) {
+      super.error.apply(this, arguments);
+    }
+  }
+
+  debug(_: any, context?: string): void {
+    if (this.isLogLevelAllowed('debug')) {
+      super.debug.apply(this, arguments);
+    }
+  }
+
+  verbose(_: any, context?: string): void {
+    if (this.isLogLevelAllowed('verbose')) {
+      super.verbose.apply(this, arguments);
+    }
+  }
+
+  protected printMessages(
+    messages: unknown[],
+    context?: string,
+    logLevel?: LogLevel,
+    writeStreamType?: 'stdout' | 'stderr',
+    errorStack?: unknown,
+  ): void {
+    const level = logLevel === 'log' ? ('info' as LogLevel) : logLevel;
+    super.printMessages(messages, context, level, writeStreamType, errorStack);
+  }
+}
--- a/apps/server/src/common/logger/logger.module.ts
+++ b/apps/server/src/common/logger/logger.module.ts
@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { LoggerModule as PinoLoggerModule } from 'nestjs-pino';
+import { createPinoConfig } from './pino.config';
+
+@Module({
+  imports: [PinoLoggerModule.forRoot(createPinoConfig())],
+  exports: [PinoLoggerModule],
+})
+export class LoggerModule {}
--- a/apps/server/src/common/logger/pino.config.ts
+++ b/apps/server/src/common/logger/pino.config.ts
@@ -0,0 +1,77 @@
+import { Params } from 'nestjs-pino';
+import { stdTimeFunctions } from 'pino';
+import { redactSensitiveUrl } from '../helpers/utils';
+
+const CONTEXTS_TO_IGNORE = [
+  'InstanceLoader',
+  'RoutesResolver',
+  'RouterExplorer',
+  'LegacyRouteConverter',
+  'WebSocketsController',
+];
+
+export function createPinoConfig(): Params {
+  const isProduction = process.env.NODE_ENV?.toLowerCase() === 'production';
+  const isDebugMode = process.env.DEBUG_MODE?.toLowerCase() === 'true';
+  const logHttp = process.env.LOG_HTTP?.toLowerCase() === 'true';
+
+  const level = isProduction && !isDebugMode ? 'info' : 'debug';
+
+  return {
+    pinoHttp: {
+      level,
+      timestamp: stdTimeFunctions.isoTime,
+      transport: !isProduction
+        ? {
+            target: 'pino-pretty',
+            options: {
+              colorize: true,
+              singleLine: true,
+              translateTime: 'SYS:standard',
+              ignore: 'pid,hostname',
+            },
+          }
+        : undefined,
+      formatters: {
+        level: (label) => ({ level: label }),
+      },
+      hooks: {
+        logMethod(inputArgs, method) {
+          if (isProduction && !isDebugMode) {
+            for (const arg of inputArgs) {
+              if (typeof arg === 'object' && arg !== null && 'context' in arg) {
+                const context = (arg as Record<string, unknown>)['context'];
+                if (typeof context === 'string' && CONTEXTS_TO_IGNORE.includes(context)) {
+                  return;
+                }
+              }
+            }
+          }
+          return method.apply(this, inputArgs);
+        },
+      },
+      serializers: {
+        req: (req) => ({
+          method: req.method,
+          url: redactSensitiveUrl(req.url),
+          ip: req.ip || req.remoteAddress,
+          userAgent: req.headers?.['user-agent'],
+        }),
+        res: (res) => ({
+          statusCode: res.statusCode,
+        }),
+      },
+      customLogLevel: (_req, res, err) => {
+        if (res.statusCode >= 500 || err) return 'error';
+        if (res.statusCode >= 400) return 'warn';
+        return 'info';
+      },
+      autoLogging: logHttp
+        ? {
+            ignore: (req) =>
+              req.url === '/api/health' || req.url === '/api/health/live',
+          }
+        : false,
+    },
+  };
+}
--- a/apps/server/src/common/middlewares/audit-context.middleware.ts
+++ b/apps/server/src/common/middlewares/audit-context.middleware.ts
@@ -0,0 +1,39 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { ClsService } from 'nestjs-cls';
+
+export interface AuditContext {
+  workspaceId: string | null;
+  actorId: string | null;
+  actorType: 'user' | 'system' | 'api_key';
+  ipAddress: string | null;
+  userAgent: string | null;
+}
+
+export const AUDIT_CONTEXT_KEY = 'auditContext';
+
+@Injectable()
+export class AuditContextMiddleware implements NestMiddleware {
+  constructor(private readonly cls: ClsService) {}
+
+  use(req: FastifyRequest['raw'], res: FastifyReply['raw'], next: () => void) {
+    const workspaceId = (req as any).workspaceId ?? null;
+
+    const ipAddress = (req as any).ip ?? (req as any).socket?.remoteAddress ?? null;
+
+    const userAgent =
+      (req.headers['user-agent'] as string) ?? null;
+
+    const auditContext: AuditContext = {
+      workspaceId,
+      actorId: null,
+      actorType: 'user',
+      ipAddress,
+      userAgent,
+    };
+
+    this.cls.set(AUDIT_CONTEXT_KEY, auditContext);
+
+    next();
+  }
+}
--- a/apps/server/src/common/middlewares/domain.middleware.ts
+++ b/apps/server/src/common/middlewares/domain.middleware.ts
@@ -0,0 +1,45 @@
+import { Injectable, NestMiddleware, NotFoundException } from '@nestjs/common';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+
+@Injectable()
+export class DomainMiddleware implements NestMiddleware {
+  constructor(
+    private workspaceRepo: WorkspaceRepo,
+    private environmentService: EnvironmentService,
+  ) {}
+  async use(
+    req: FastifyRequest['raw'],
+    res: FastifyReply['raw'],
+    next: () => void,
+  ) {
+    if (this.environmentService.isSelfHosted()) {
+      const workspace = await this.workspaceRepo.findFirst();
+      if (!workspace) {
+        //throw new NotFoundException('Workspace not found');
+        (req as any).workspaceId = null;
+        return next();
+      }
+
+      // TODO: unify
+      (req as any).workspaceId = workspace.id;
+      (req as any).workspace = workspace;
+    } else if (this.environmentService.isCloud()) {
+      const header = req.headers.host;
+      const subdomain = header.split('.')[0];
+
+      const workspace = await this.workspaceRepo.findByHostname(subdomain);
+
+      if (!workspace) {
+        (req as any).workspaceId = null;
+        return next();
+      }
+
+      (req as any).workspaceId = workspace.id;
+      (req as any).workspace = workspace;
+    }
+
+    next();
+  }
+}
--- a/apps/server/src/common/validators/is-iso6391.ts
+++ b/apps/server/src/common/validators/is-iso6391.ts
@@ -0,0 +1,34 @@
+// MIT - https://github.com/typestack/class-validator/pull/2626
+import isISO6391Validator from 'validator/lib/isISO6391';
+import { buildMessage, ValidateBy, ValidationOptions } from 'class-validator';
+
+export const IS_ISO6391 = 'isISO6391';
+
+/**
+ * Check if the string is a valid [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) officially assigned language code.
+ */
+export function isISO6391(value: unknown): boolean {
+  return typeof value === 'string' && isISO6391Validator(value);
+}
+
+/**
+ * Check if the string is a valid [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) officially assigned language code.
+ */
+export function IsISO6391(
+  validationOptions?: ValidationOptions,
+): PropertyDecorator {
+  return ValidateBy(
+    {
+      name: IS_ISO6391,
+      validator: {
+        validate: (value, args): boolean => isISO6391(value),
+        defaultMessage: buildMessage(
+          (eachPrefix) =>
+            eachPrefix + '$property must be a valid ISO 639-1 language code',
+          validationOptions,
+        ),
+      },
+    },
+    validationOptions,
+  );
+}
--- a/apps/server/src/common/validators/no-urls.validator.spec.ts
+++ b/apps/server/src/common/validators/no-urls.validator.spec.ts
@@ -0,0 +1,142 @@
+import { containsDomain } from './no-urls.validator';
+
+// containsDomain returns true if value contains a domain-like pattern
+// The full NoUrls validator also checks for https:// URLs separately
+
+describe('containsDomain', () => {
+  describe('bare domains with real TLDs — should block', () => {
+    it.each([
+      'example.com',
+      'example.net',
+      'example.org',
+      'example.io',
+      'example.co',
+      'example.dev',
+      'example.app',
+      'example.me',
+      'example.info',
+      'example.tech',
+      'example.aero',
+      'example.cloud',
+      'example.museum',
+      'example.abc',
+      'example.uk',
+      'example.de',
+      'example.fr',
+      'example.ru',
+    ])('blocks "%s"', (value) => {
+      expect(containsDomain(value)).toBe(true);
+    });
+  });
+
+  describe('domains with paths — should block', () => {
+    it.each([
+      'example.com/reset',
+      'example.com/reset-password',
+      'click example.com/page',
+      'go to example.net/login',
+    ])('blocks "%s"', (value) => {
+      expect(containsDomain(value)).toBe(true);
+    });
+  });
+
+  describe('multi-part domains — should block', () => {
+    it.each([
+      'Foo.com.net',
+      'Foo.com.',
+      'Foo.mine.net',
+      'Foo.mine.ne',
+      'sub.example.com',
+      'login.example.co.uk',
+    ])('blocks "%s"', (value) => {
+      expect(containsDomain(value)).toBe(true);
+    });
+  });
+
+  describe('domain in sentence — should block', () => {
+    it.each([
+      'Reset your password at example.com',
+      'URGENT click example.com/reset',
+      'Visit example.org for details',
+      'go to mysite.io now',
+    ])('blocks "%s"', (value) => {
+      expect(containsDomain(value)).toBe(true);
+    });
+  });
+
+  describe('case insensitive — should block', () => {
+    it.each(['EXAMPLE.COM', 'Example.Com', 'example.COM'])('blocks "%s"', (value) => {
+      expect(containsDomain(value)).toBe(true);
+    });
+  });
+
+  describe('fake TLDs — should allow', () => {
+    it.each([
+      'Foo.mine',
+      'Foo.blarg',
+      'Foo.qqq',
+      'Foo.zz',
+      'Foo.abcd',
+      'Foo.abcde',
+      'Foo.abcdef',
+      'Foo.abcdefg',
+    ])('allows "%s"', (value) => {
+      expect(containsDomain(value)).toBe(false);
+    });
+  });
+
+  describe('too short suffix — should allow', () => {
+    it.each(['Foo.a', 'Foo.c', 'A.B'])('allows "%s"', (value) => {
+      expect(containsDomain(value)).toBe(false);
+    });
+  });
+
+  describe('multi-part with fake TLD — should allow', () => {
+    it.each(['Foo.mine.', 'Foo.mine.n'])('allows "%s"', (value) => {
+      expect(containsDomain(value)).toBe(false);
+    });
+  });
+
+  describe('emails — should allow', () => {
+    it.each([
+      'user@example.com',
+      'admin@company.org',
+      'test@sub.domain.co.uk',
+    ])('allows "%s"', (value) => {
+      expect(containsDomain(value)).toBe(false);
+    });
+  });
+
+  describe('normal names — should allow', () => {
+    it.each([
+      'John Smith',
+      'Dr. Smith',
+      'A. B. Charlie',
+      'John',
+      'Mary Jane',
+      "O'Brien",
+      'Jean-Pierre',
+      'José García',
+    ])('allows "%s"', (value) => {
+      expect(containsDomain(value)).toBe(false);
+    });
+  });
+
+  describe('IP addresses — should allow', () => {
+    it.each(['192.168.1.1', '10.0.0.1', '127.0.0.1'])(
+      'allows "%s"',
+      (value) => {
+        expect(containsDomain(value)).toBe(false);
+      },
+    );
+  });
+
+  describe('edge cases — should allow', () => {
+    it.each(['', ' ', '.', '..', 'hello', '.com', 'a.b'])(
+      'allows "%s"',
+      (value) => {
+        expect(containsDomain(value)).toBe(false);
+      },
+    );
+  });
+});
--- a/apps/server/src/common/validators/no-urls.validator.ts
+++ b/apps/server/src/common/validators/no-urls.validator.ts
@@ -0,0 +1,42 @@
+import { registerDecorator, ValidationOptions } from 'class-validator';
+import * as tlds from 'tlds';
+
+const URL_PATTERN = /https?:\/\//i;
+const tldSet = new Set(tlds.map((t) => t.toLowerCase()));
+
+export function containsDomain(value: string): boolean {
+  const tokens = value.split(/\s+/);
+  for (const token of tokens) {
+    if (token.includes('@')) continue;
+    const segments = token.split('.');
+    for (let i = 1; i < segments.length; i++) {
+      const suffix = segments[i].replace(/[^\w].*/g, '');
+      if (segments[i - 1] && suffix && tldSet.has(suffix.toLowerCase())) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function NoUrls(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      name: 'noUrls',
+      target: object.constructor,
+      propertyName,
+      options: {
+        message: 'Must not contain URLs or domain names',
+        ...validationOptions,
+      },
+      validator: {
+        validate(value: unknown) {
+          if (typeof value !== 'string') return true;
+          if (URL_PATTERN.test(value)) return false;
+          if (containsDomain(value)) return false;
+          return true;
+        },
+      },
+    });
+  };
+}
--- a/apps/server/src/core/attachment/attachment.constants.ts
+++ b/apps/server/src/core/attachment/attachment.constants.ts
@@ -0,0 +1,24 @@
+export enum AttachmentType {
+  Avatar = 'avatar',
+  WorkspaceIcon = 'workspace-icon',
+  SpaceIcon = 'space-icon',
+  File = 'file',
+  Chat = 'chat',
+}
+
+export const validImageExtensions = ['.jpg', '.png', '.jpeg'];
+export const MAX_AVATAR_SIZE = '10MB';
+
+export const inlineFileExtensions = [
+  '.jpg',
+  '.png',
+  '.jpeg',
+  '.pdf',
+  '.mp4',
+  '.mov',
+  '.mp3',
+  '.wav',
+  '.ogg',
+  '.m4a',
+  '.webm',
+];
--- a/apps/server/src/core/attachment/attachment.controller.ts
+++ b/apps/server/src/core/attachment/attachment.controller.ts
@@ -0,0 +1,584 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  ForbiddenException,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  Logger,
+  NotFoundException,
+  Param,
+  Post,
+  Query,
+  Req,
+  Res,
+  UseGuards,
+  UseInterceptors,
+} from '@nestjs/common';
+import { AttachmentService } from './services/attachment.service';
+import { FastifyReply, FastifyRequest } from 'fastify';
+import { FileInterceptor } from '../../common/interceptors/file.interceptor';
+import * as bytes from 'bytes';
+import { AuthUser } from '../../common/decorators/auth-user.decorator';
+import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { OAuthScope } from '../../common/decorators/oauth-scope.decorator';
+import { Attachment, User, Workspace } from '@docmost/db/types/entity.types';
+import { StorageService } from '../../integrations/storage/storage.service';
+import {
+  getAttachmentFolderPath,
+  validAttachmentTypes,
+} from './attachment.utils';
+import { getMimeType } from '../../common/helpers';
+import {
+  AttachmentType,
+  inlineFileExtensions,
+  MAX_AVATAR_SIZE,
+} from './attachment.constants';
+import {
+  SpaceCaslAction,
+  SpaceCaslSubject,
+} from '../casl/interfaces/space-ability.type';
+import SpaceAbilityFactory from '../casl/abilities/space-ability.factory';
+import {
+  WorkspaceCaslAction,
+  WorkspaceCaslSubject,
+} from '../casl/interfaces/workspace-ability.type';
+import WorkspaceAbilityFactory from '../casl/abilities/workspace-ability.factory';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
+import { validate as isValidUUID } from 'uuid';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { TokenService } from '../auth/services/token.service';
+import { JwtAttachmentPayload, JwtType } from '../auth/dto/jwt-payload';
+import * as path from 'path';
+import {
+  AttachmentInfoDto,
+  PageIdDto,
+  RemoveIconDto,
+} from './dto/attachment.dto';
+import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
+import { PageAccessService } from '../page/page-access/page-access.service';
+import { DomainService } from '../../integrations/environment/domain.service';
+import { AuditEvent, AuditResource } from '../../common/events/audit-events';
+import {
+  AUDIT_SERVICE,
+  IAuditService,
+} from '../../integrations/audit/audit.service';
+
+@Controller()
+export class AttachmentController {
+  private readonly logger = new Logger(AttachmentController.name);
+
+  constructor(
+    private readonly attachmentService: AttachmentService,
+    private readonly storageService: StorageService,
+    private readonly workspaceAbility: WorkspaceAbilityFactory,
+    private readonly spaceAbility: SpaceAbilityFactory,
+    private readonly pageRepo: PageRepo,
+    private readonly attachmentRepo: AttachmentRepo,
+    private readonly environmentService: EnvironmentService,
+    private readonly tokenService: TokenService,
+    private readonly pageAccessService: PageAccessService,
+    private readonly domainService: DomainService,
+    @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
+  ) {}
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('files/upload')
+  @UseInterceptors(FileInterceptor)
+  async uploadFile(
+    @Req() req: any,
+    @Res() res: FastifyReply,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const maxFileSize = bytes(this.environmentService.getFileUploadSizeLimit());
+
+    let file = null;
+    try {
+      file = await req.file({
+        limits: { fileSize: maxFileSize, fields: 3, files: 1 },
+      });
+    } catch (err: any) {
+      this.logger.error(err.message);
+      if (err?.statusCode === 413) {
+        throw new BadRequestException(
+          `File too large. Exceeds the ${this.environmentService.getFileUploadSizeLimit()} limit`,
+        );
+      }
+    }
+
+    if (!file) {
+      throw new BadRequestException('Failed to upload file');
+    }
+
+    const pageId = file.fields?.pageId?.value;
+
+    if (!pageId) {
+      throw new BadRequestException('PageId is required');
+    }
+
+    const page = await this.pageRepo.findById(pageId);
+
+    if (!page) {
+      throw new NotFoundException('Page not found');
+    }
+
+    await this.pageAccessService.validateCanEdit(page, user);
+
+    const spaceId = page.spaceId;
+
+    const attachmentId = file.fields?.attachmentId?.value;
+    if (attachmentId && !isValidUUID(attachmentId)) {
+      throw new BadRequestException('Invalid attachment id');
+    }
+
+    try {
+      const fileResponse = await this.attachmentService.uploadFile({
+        filePromise: file,
+        pageId: pageId,
+        spaceId: spaceId,
+        userId: user.id,
+        workspaceId: workspace.id,
+        attachmentId: attachmentId,
+      });
+
+      this.auditService.log({
+        event: AuditEvent.ATTACHMENT_UPLOADED,
+        resourceType: AuditResource.ATTACHMENT,
+        resourceId: fileResponse?.id ?? attachmentId,
+        spaceId,
+        metadata: {
+          fileName: fileResponse?.fileName,
+          pageId,
+          spaceId,
+        },
+      });
+
+      return res.send({
+        ...fileResponse,
+        url: this.buildFileUrl(workspace, fileResponse),
+      });
+    } catch (err: any) {
+      if (err?.statusCode === 413) {
+        const errMessage = `File too large. Exceeds the ${this.environmentService.getFileUploadSizeLimit()} limit`;
+        this.logger.error(errMessage);
+        throw new BadRequestException(errMessage);
+      }
+      this.logger.error(err);
+      throw new BadRequestException('Error processing file upload.');
+    }
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @Get('/files/:fileId/:fileName')
+  @OAuthScope('read')
+  async getFile(
+    @Req() req: FastifyRequest,
+    @Res() res: FastifyReply,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+    @Param('fileId') fileId: string,
+    @Param('fileName') fileName?: string,
+  ) {
+    if (!isValidUUID(fileId)) {
+      throw new NotFoundException('Invalid file id');
+    }
+
+    const attachment = await this.attachmentRepo.findById(fileId);
+    if (!attachment || attachment.workspaceId !== workspace.id) {
+      throw new NotFoundException();
+    }
+
+    if (attachment.aiChatId) {
+      // Chat-owned attachment: only the user who uploaded (and therefore
+      // owns the chat, per AttachmentRepo.claimAttachmentsForChat) can
+      // read it back.
+      if (attachment.creatorId !== user.id) {
+        throw new NotFoundException();
+      }
+    } else {
+      if (!attachment.pageId || !attachment.spaceId) {
+        throw new NotFoundException();
+      }
+
+      const page = await this.pageRepo.findById(attachment.pageId);
+      if (!page) {
+        throw new NotFoundException();
+      }
+
+      await this.pageAccessService.validateCanView(page, user);
+    }
+
+    try {
+      return await this.sendFileResponse(req, res, attachment, 'private');
+    } catch (err) {
+      this.logger.error(err);
+      throw new NotFoundException('File not found');
+    }
+  }
+
+  @Get('/files/public/:fileId/:fileName')
+  async getPublicFile(
+    @Req() req: FastifyRequest,
+    @Res() res: FastifyReply,
+    @AuthWorkspace() workspace: Workspace,
+    @Param('fileId') fileId: string,
+    @Param('fileName') fileName?: string,
+    @Query('jwt') jwtToken?: string,
+  ) {
+    let jwtPayload: JwtAttachmentPayload = null;
+    try {
+      jwtPayload = await this.tokenService.verifyJwt(
+        jwtToken,
+        JwtType.ATTACHMENT,
+      );
+    } catch (err) {
+      throw new BadRequestException(
+        'Expired or invalid attachment access token',
+      );
+    }
+
+    if (
+      !isValidUUID(fileId) ||
+      fileId !== jwtPayload.attachmentId ||
+      jwtPayload.workspaceId !== workspace.id
+    ) {
+      throw new NotFoundException('File not found');
+    }
+
+    const attachment = await this.attachmentRepo.findById(fileId);
+    if (
+      !attachment ||
+      attachment.workspaceId !== workspace.id ||
+      !attachment.pageId ||
+      !attachment.spaceId ||
+      jwtPayload.pageId !== attachment.pageId
+    ) {
+      throw new NotFoundException('File not found');
+    }
+
+    try {
+      return await this.sendFileResponse(req, res, attachment, 'public');
+    } catch (err) {
+      this.logger.error(err);
+      throw new NotFoundException('File not found');
+    }
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('attachments/upload-image')
+  @UseInterceptors(FileInterceptor)
+  async uploadAvatarOrLogo(
+    @Req() req: any,
+    @Res() res: FastifyReply,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const maxFileSize = bytes(MAX_AVATAR_SIZE);
+
+    let file = null;
+    try {
+      file = await req.file({
+        limits: { fileSize: maxFileSize, fields: 3, files: 1 },
+      });
+    } catch (err: any) {
+      if (err?.statusCode === 413) {
+        throw new BadRequestException(
+          `File too large. Exceeds the ${MAX_AVATAR_SIZE} limit`,
+        );
+      }
+    }
+
+    if (!file) {
+      throw new BadRequestException('Invalid file upload');
+    }
+
+    const attachmentType = file.fields?.type?.value;
+    const spaceId = file.fields?.spaceId?.value;
+
+    if (!attachmentType) {
+      throw new BadRequestException('attachment type is required');
+    }
+
+    if (
+      !validAttachmentTypes.includes(attachmentType) ||
+      attachmentType === AttachmentType.File
+    ) {
+      throw new BadRequestException('Invalid image attachment type');
+    }
+
+    if (attachmentType === AttachmentType.WorkspaceIcon) {
+      const ability = this.workspaceAbility.createForUser(user, workspace);
+      if (
+        ability.cannot(
+          WorkspaceCaslAction.Manage,
+          WorkspaceCaslSubject.Settings,
+        )
+      ) {
+        throw new ForbiddenException();
+      }
+    }
+
+    if (attachmentType === AttachmentType.SpaceIcon) {
+      if (!spaceId) {
+        throw new BadRequestException('spaceId is required');
+      }
+
+      const spaceAbility = await this.spaceAbility.createForUser(user, spaceId);
+      if (
+        spaceAbility.cannot(SpaceCaslAction.Manage, SpaceCaslSubject.Settings)
+      ) {
+        throw new ForbiddenException();
+      }
+    }
+
+    try {
+      const fileResponse = await this.attachmentService.uploadImage(
+        file,
+        attachmentType,
+        user.id,
+        workspace.id,
+        spaceId,
+      );
+
+      return res.send(fileResponse);
+    } catch (err: any) {
+      this.logger.error(err);
+      throw new BadRequestException('Error processing file upload.');
+    }
+  }
+
+  @Get('attachments/img/:attachmentType/:fileName')
+  async getLogoOrAvatar(
+    @Res() res: FastifyReply,
+    @AuthWorkspace() workspace: Workspace,
+    @Param('attachmentType') attachmentType: AttachmentType,
+    @Param('fileName') fileName?: string,
+  ) {
+    if (
+      !validAttachmentTypes.includes(attachmentType) ||
+      attachmentType === AttachmentType.File
+    ) {
+      throw new BadRequestException('Invalid image attachment type');
+    }
+
+    if (!fileName) {
+      throw new BadRequestException('Invalid file name');
+    }
+
+    const ext = path.extname(fileName);
+    const filenameWithoutExt = path.basename(fileName, ext);
+
+    if (
+      !ext ||
+      !isValidUUID(filenameWithoutExt) ||
+      `${filenameWithoutExt}${ext}` !== fileName
+    ) {
+      throw new BadRequestException('Invalid file name');
+    }
+
+    const filePath = `${getAttachmentFolderPath(attachmentType, workspace.id)}/${fileName}`;
+
+    try {
+      const fileStream = await this.storageService.readStream(filePath);
+      res.headers({
+        'Content-Type': getMimeType(filePath),
+        'Cache-Control': 'private, max-age=86400',
+      });
+      return res.send(fileStream);
+    } catch (err) {
+      // this.logger.error(err);
+      throw new NotFoundException('File not found');
+    }
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('files/info')
+  async getAttachmentInfo(
+    @Body() dto: AttachmentInfoDto,
+    @AuthWorkspace() workspace: Workspace,
+    @AuthUser() user: User,
+  ) {
+    const attachment = await this.attachmentRepo.findById(dto.attachmentId);
+    if (
+      !attachment ||
+      !attachment.pageId ||
+      attachment.workspaceId !== workspace.id ||
+      attachment.type !== AttachmentType.File
+    ) {
+      throw new NotFoundException('File not found');
+    }
+
+    const page = await this.pageRepo.findById(attachment.pageId);
+    if (!page) {
+      throw new NotFoundException('File not found');
+    }
+
+    await this.pageAccessService.validateCanView(page, user);
+
+    return { ...attachment, url: this.buildFileUrl(workspace, attachment) };
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('pages/attachments')
+  @OAuthScope('read')
+  async getPageAttachments(
+    @Body() dto: PageIdDto,
+    @Body() pagination: PaginationOptions,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const page = await this.pageRepo.findById(dto.pageId);
+    if (!page || page.workspaceId !== workspace.id) {
+      throw new NotFoundException('Page not found');
+    }
+
+    await this.pageAccessService.validateCanView(page, user);
+
+    const result = await this.attachmentRepo.findPageAttachments(
+      page.id,
+      pagination,
+    );
+
+    return {
+      ...result,
+      items: result.items.map((attachment) => ({
+        ...attachment,
+        url: this.buildFileUrl(workspace, attachment),
+      })),
+    };
+  }
+
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('attachments/remove-icon')
+  async removeIcon(
+    @Body() dto: RemoveIconDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const { type, spaceId } = dto;
+
+    // remove current user avatar
+    if (type === AttachmentType.Avatar) {
+      await this.attachmentService.removeUserAvatar(user);
+      return;
+    }
+
+    // remove space icon
+    if (type === AttachmentType.SpaceIcon) {
+      if (!spaceId) {
+        throw new BadRequestException(
+          'spaceId is required to change space icons',
+        );
+      }
+
+      const spaceAbility = await this.spaceAbility.createForUser(user, spaceId);
+      if (
+        spaceAbility.cannot(SpaceCaslAction.Manage, SpaceCaslSubject.Settings)
+      ) {
+        throw new ForbiddenException();
+      }
+
+      await this.attachmentService.removeSpaceIcon(spaceId, workspace.id);
+      return;
+    }
+
+    // remove workspace icon
+    if (type === AttachmentType.WorkspaceIcon) {
+      const ability = this.workspaceAbility.createForUser(user, workspace);
+      if (
+        ability.cannot(
+          WorkspaceCaslAction.Manage,
+          WorkspaceCaslSubject.Settings,
+        )
+      ) {
+        throw new ForbiddenException();
+      }
+      await this.attachmentService.removeWorkspaceIcon(workspace);
+      return;
+    }
+  }
+
+  private buildFileUrl(workspace: Workspace, attachment: Attachment): string {
+    return `${this.domainService.getUrl(workspace.hostname)}/api/files/${attachment.id}/${encodeURIComponent(attachment.fileName)}`;
+  }
+
+  private async sendFileResponse(
+    req: FastifyRequest,
+    res: FastifyReply,
+    attachment: Attachment,
+    cacheScope: 'private' | 'public',
+  ) {
+    const fileSize = Number(attachment.fileSize);
+    const rangeHeader = req.headers.range;
+
+    res.header('Accept-Ranges', 'bytes');
+    res.header(
+      'Content-Security-Policy',
+      "base-uri 'none'; object-src 'self'; default-src 'self';",
+    );
+
+    if (!inlineFileExtensions.includes(attachment.fileExt)) {
+      res.header(
+        'Content-Disposition',
+        `attachment; filename="${encodeURIComponent(attachment.fileName)}"`,
+      );
+    }
+
+    if (rangeHeader && fileSize) {
+      const match = rangeHeader.match(/bytes=(\d+)-(\d*)/);
+      if (match) {
+        const start = parseInt(match[1], 10);
+        const end = match[2]
+          ? Math.min(parseInt(match[2], 10), fileSize - 1)
+          : fileSize - 1;
+
+        if (start >= fileSize || start > end) {
+          res.status(416);
+          res.header('Content-Range', `bytes */${fileSize}`);
+          return res.send();
+        }
+
+        const fileStream = await this.storageService.readRangeStream(
+          attachment.filePath,
+          { start, end },
+        );
+
+        res.status(206);
+        res.headers({
+          'Content-Type': attachment.mimeType,
+          'Content-Range': `bytes ${start}-${end}/${fileSize}`,
+          'Content-Length': end - start + 1,
+          'Cache-Control': `${cacheScope}, max-age=3600`,
+        });
+
+        return res.send(fileStream);
+      }
+    }
+
+    const fileStream = await this.storageService.readStream(
+      attachment.filePath,
+    );
+
+    res.headers({
+      'Content-Type': attachment.mimeType,
+      'Cache-Control': `${cacheScope}, max-age=3600`,
+    });
+
+    const isSvg = attachment.fileExt === '.svg';
+    if (fileSize && !isSvg) {
+      res.header('Content-Length', fileSize);
+    }
+
+    return res.send(fileStream);
+  }
+}
--- a/apps/server/src/core/attachment/attachment.module.ts
+++ b/apps/server/src/core/attachment/attachment.module.ts
@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { AttachmentService } from './services/attachment.service';
+import { AttachmentController } from './attachment.controller';
+import { StorageModule } from '../../integrations/storage/storage.module';
+import { UserModule } from '../user/user.module';
+import { WorkspaceModule } from '../workspace/workspace.module';
+import { AttachmentProcessor } from './processors/attachment.processor';
+import { TokenModule } from '../auth/token.module';
+
+@Module({
+  imports: [StorageModule, UserModule, WorkspaceModule, TokenModule],
+  controllers: [AttachmentController],
+  providers: [AttachmentService, AttachmentProcessor],
+})
+export class AttachmentModule {}
--- a/apps/server/src/core/attachment/attachment.utils.ts
+++ b/apps/server/src/core/attachment/attachment.utils.ts
@@ -0,0 +1,81 @@
+import { MultipartFile } from '@fastify/multipart';
+import * as path from 'path';
+import { AttachmentType } from './attachment.constants';
+import { sanitizeFileName } from '../../common/helpers';
+import { getMimeType } from '../../common/helpers';
+
+export interface PreparedFile {
+  buffer?: Buffer;
+  fileName: string;
+  fileSize: number;
+  fileExtension: string;
+  mimeType: string;
+  multiPartFile?: MultipartFile;
+}
+
+export async function prepareFile(
+  filePromise: Promise<MultipartFile>,
+  options: { skipBuffer?: boolean } = {},
+): Promise<PreparedFile> {
+  const file = await filePromise;
+
+  if (!file) {
+    throw new Error('No file provided');
+  }
+
+  try {
+    let buffer: Buffer | undefined;
+    let fileSize = 0;
+
+    if (!options.skipBuffer) {
+      buffer = await file.toBuffer();
+      fileSize = buffer.length;
+    }
+
+    const sanitizedFilename = sanitizeFileName(file.filename);
+    const fileName = sanitizedFilename.slice(0, 255);
+    const fileExtension = path.extname(file.filename).toLowerCase();
+
+    return {
+      buffer,
+      fileName,
+      fileSize,
+      fileExtension,
+      mimeType: getMimeType(file.filename),
+      multiPartFile: file,
+    };
+  } catch (error) {
+    throw error;
+  }
+}
+
+export function validateFileType(
+  fileExtension: string,
+  allowedTypes: string[],
+) {
+  if (!allowedTypes.includes(fileExtension)) {
+    throw new Error('Invalid file type');
+  }
+}
+
+export function getAttachmentFolderPath(
+  type: AttachmentType,
+  workspaceId: string,
+): string {
+  switch (type) {
+    case AttachmentType.Avatar:
+      return `${workspaceId}/avatars`;
+    case AttachmentType.WorkspaceIcon:
+      return `${workspaceId}/workspace-logos`;
+    case AttachmentType.SpaceIcon:
+      return `${workspaceId}/space-logos`;
+    case AttachmentType.File:
+      return `${workspaceId}/files`;
+    case AttachmentType.Chat:
+      return `${workspaceId}/chat-files`;
+    default:
+      return `${workspaceId}/files`;
+  }
+}
+
+export const validAttachmentTypes = Object.values(AttachmentType);
--- a/apps/server/src/core/attachment/dto/attachment.dto.ts
+++ b/apps/server/src/core/attachment/dto/attachment.dto.ts
@@ -0,0 +1,36 @@
+import {
+  IsEnum,
+  IsIn,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUUID,
+} from 'class-validator';
+import { AttachmentType } from '../attachment.constants';
+
+export class AttachmentInfoDto {
+  @IsNotEmpty()
+  @IsUUID()
+  attachmentId: string;
+}
+
+export class PageIdDto {
+  @IsString()
+  @IsNotEmpty()
+  pageId: string;
+}
+
+export class RemoveIconDto {
+  @IsEnum(AttachmentType)
+  @IsIn([
+    AttachmentType.Avatar,
+    AttachmentType.SpaceIcon,
+    AttachmentType.WorkspaceIcon,
+  ])
+  @IsNotEmpty()
+  type: AttachmentType;
+
+  @IsOptional()
+  @IsUUID()
+  spaceId: string;
+}
--- a/apps/server/src/core/attachment/processors/attachment.processor.ts
+++ b/apps/server/src/core/attachment/processors/attachment.processor.ts
@@ -0,0 +1,96 @@
+import { Logger, OnModuleDestroy } from '@nestjs/common';
+import { OnWorkerEvent, Processor, WorkerHost } from '@nestjs/bullmq';
+import { Job } from 'bullmq';
+import { AttachmentService } from '../services/attachment.service';
+import { QueueJob, QueueName } from 'src/integrations/queue/constants';
+import { ModuleRef } from '@nestjs/core';
+
+@Processor(QueueName.ATTACHMENT_QUEUE)
+export class AttachmentProcessor extends WorkerHost implements OnModuleDestroy {
+  private readonly logger = new Logger(AttachmentProcessor.name);
+  constructor(
+    private readonly attachmentService: AttachmentService,
+    private moduleRef: ModuleRef,
+  ) {
+    super();
+  }
+
+  async process(job: Job<any, void>): Promise<void> {
+    try {
+      if (job.name === QueueJob.DELETE_SPACE_ATTACHMENTS) {
+        await this.attachmentService.handleDeleteSpaceAttachments(job.data.id);
+      }
+      if (job.name === QueueJob.DELETE_USER_AVATARS) {
+        await this.attachmentService.handleDeleteUserAvatars(job.data.id);
+      }
+      if (job.name === QueueJob.DELETE_PAGE_ATTACHMENTS) {
+        await this.attachmentService.handleDeletePageAttachments(
+          job.data.pageId,
+        );
+      }
+      if (job.name === QueueJob.DELETE_AI_CHAT_ATTACHMENTS) {
+        await this.attachmentService.handleDeleteAiChatAttachments(
+          job.data.aiChatId,
+        );
+      }
+      if (
+        job.name === QueueJob.ATTACHMENT_INDEX_CONTENT ||
+        job.name === QueueJob.ATTACHMENT_INDEXING
+      ) {
+        let AttachmentEeModule: any;
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          AttachmentEeModule = require('./../../../ee/attachments-ee/attachment-ee.service');
+        } catch (err) {
+          this.logger.debug(
+            'Attachment enterprise module requested but EE module not bundled in this build',
+          );
+          return;
+        }
+        const attachmentEeService = this.moduleRef.get(
+          AttachmentEeModule.AttachmentEeService,
+          { strict: false },
+        );
+
+        if (job.name === QueueJob.ATTACHMENT_INDEX_CONTENT) {
+          await attachmentEeService.indexAttachment(job.data.attachmentId);
+        } else if (job.name === QueueJob.ATTACHMENT_INDEXING) {
+          await attachmentEeService.indexAttachments(
+            job.data.workspaceId,
+          );
+        }
+      }
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  @OnWorkerEvent('active')
+  onActive(job: Job) {
+    this.logger.debug(`Processing ${job.name} job`);
+  }
+
+  @OnWorkerEvent('failed')
+  onError(job: Job) {
+    if (job.name === QueueJob.ATTACHMENT_INDEX_CONTENT) {
+      this.logger.debug(
+        `Error processing ${job.name} job for attachment ${job.data?.attachmentId}. Reason: ${job.failedReason}`,
+      );
+    } else {
+      this.logger.error(
+        `Error processing ${job.name} job. Reason: ${job.failedReason}`,
+      );
+    }
+  }
+
+  @OnWorkerEvent('completed')
+  onCompleted(job: Job) {
+    this.logger.debug(`Completed ${job.name} job`);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.worker) {
+      await this.worker.close();
+    }
+  }
+}
--- a/apps/server/src/core/attachment/services/attachment.service.ts
+++ b/apps/server/src/core/attachment/services/attachment.service.ts
@@ -0,0 +1,464 @@
+import {
+  BadRequestException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Readable } from 'stream';
+import { StorageService } from '../../../integrations/storage/storage.service';
+import { MultipartFile } from '@fastify/multipart';
+import {
+  getAttachmentFolderPath,
+  PreparedFile,
+  prepareFile,
+  validateFileType,
+} from '../attachment.utils';
+import { v4 as uuid4, v7 as uuid7 } from 'uuid';
+import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
+import { AttachmentType, validImageExtensions } from '../attachment.constants';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { Attachment, User, Workspace } from '@docmost/db/types/entity.types';
+import { InjectKysely } from 'nestjs-kysely';
+import { executeTx } from '@docmost/db/utils';
+import { UserRepo } from '@docmost/db/repos/user/user.repo';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { SpaceRepo } from '@docmost/db/repos/space/space.repo';
+import { InjectQueue } from '@nestjs/bullmq';
+import { QueueJob, QueueName } from '../../../integrations/queue/constants';
+import { Queue } from 'bullmq';
+import { createByteCountingStream } from '../../../common/helpers/utils';
+
+@Injectable()
+export class AttachmentService {
+  private readonly logger = new Logger(AttachmentService.name);
+  constructor(
+    private readonly storageService: StorageService,
+    private readonly attachmentRepo: AttachmentRepo,
+    private readonly userRepo: UserRepo,
+    private readonly workspaceRepo: WorkspaceRepo,
+    private readonly spaceRepo: SpaceRepo,
+    @InjectKysely() private readonly db: KyselyDB,
+    @InjectQueue(QueueName.ATTACHMENT_QUEUE) private attachmentQueue: Queue,
+  ) {}
+
+  async uploadFile(opts: {
+    filePromise: Promise<MultipartFile>;
+    pageId?: string;
+    userId: string;
+    spaceId: string;
+    workspaceId: string;
+    attachmentId?: string;
+  }) {
+    const { filePromise, pageId, spaceId, userId, workspaceId } = opts;
+    const preparedFile: PreparedFile = await prepareFile(filePromise, {
+      skipBuffer: true,
+    });
+
+    let isUpdate = false;
+    let attachmentId = null;
+
+    // passing attachmentId to allow for updating diagrams
+    // instead of creating new files for each save
+    if (opts?.attachmentId) {
+      const existingAttachment = await this.attachmentRepo.findById(
+        opts.attachmentId,
+      );
+      if (!existingAttachment) {
+        throw new NotFoundException(
+          'Existing attachment to overwrite not found',
+        );
+      }
+
+      if (
+        existingAttachment.pageId !== pageId ||
+        existingAttachment.fileExt !== preparedFile.fileExtension ||
+        existingAttachment.workspaceId !== workspaceId
+      ) {
+        throw new BadRequestException('File attachment does not match');
+      }
+      attachmentId = opts.attachmentId;
+      isUpdate = true;
+    } else {
+      attachmentId = uuid7();
+    }
+
+    const filePath = `${getAttachmentFolderPath(AttachmentType.File, workspaceId)}/${attachmentId}/${preparedFile.fileName}`;
+
+    const { stream, getBytesRead } = createByteCountingStream(
+      preparedFile.multiPartFile.file,
+    );
+
+    await this.uploadToDrive(filePath, stream);
+
+    // Update fileSize from the consumed stream
+    preparedFile.fileSize = getBytesRead();
+
+    let attachment: Attachment = null;
+    try {
+      if (isUpdate) {
+        attachment = await this.attachmentRepo.updateAttachment(
+          {
+            fileSize: preparedFile.fileSize,
+            updatedAt: new Date(),
+          },
+          attachmentId,
+        );
+      } else {
+        attachment = await this.saveAttachment({
+          attachmentId,
+          preparedFile,
+          filePath,
+          type: AttachmentType.File,
+          userId,
+          spaceId,
+          workspaceId,
+          pageId,
+        });
+      }
+
+      // Only index PDF, DOCX and TXT files
+      if (['.pdf', '.docx', '.txt'].includes(attachment.fileExt.toLowerCase())) {
+        await this.attachmentQueue.add(
+          QueueJob.ATTACHMENT_INDEX_CONTENT,
+          {
+            attachmentId: attachmentId,
+          },
+          {
+            attempts: 2,
+            backoff: {
+              type: 'exponential',
+              delay: 10000,
+            },
+          },
+        );
+      }
+    } catch (err) {
+      // delete uploaded file on error
+      this.logger.error(err);
+    }
+
+    return attachment;
+  }
+
+  async uploadImage(
+    filePromise: Promise<MultipartFile>,
+    type:
+      | AttachmentType.Avatar
+      | AttachmentType.WorkspaceIcon
+      | AttachmentType.SpaceIcon,
+    userId: string,
+    workspaceId: string,
+    spaceId?: string,
+  ) {
+    const preparedFile: PreparedFile = await prepareFile(filePromise);
+    validateFileType(preparedFile.fileExtension, validImageExtensions);
+
+    preparedFile.fileName = uuid4() + preparedFile.fileExtension;
+
+    const filePath = `${getAttachmentFolderPath(type, workspaceId)}/${preparedFile.fileName}`;
+
+    await this.uploadToDrive(filePath, preparedFile.buffer);
+
+    let attachment: Attachment = null;
+    let oldFileName: string = null;
+
+    try {
+      await executeTx(this.db, async (trx) => {
+        attachment = await this.saveAttachment({
+          preparedFile,
+          filePath,
+          type,
+          userId,
+          workspaceId,
+          trx,
+        });
+
+        if (type === AttachmentType.Avatar) {
+          const user = await this.userRepo.findById(userId, workspaceId, {
+            trx,
+          });
+
+          oldFileName = user.avatarUrl;
+
+          await this.userRepo.updateUser(
+            { avatarUrl: preparedFile.fileName },
+            userId,
+            workspaceId,
+            trx,
+          );
+        } else if (type === AttachmentType.WorkspaceIcon) {
+          const workspace = await this.workspaceRepo.findById(workspaceId, {
+            trx,
+          });
+
+          oldFileName = workspace.logo;
+
+          await this.workspaceRepo.updateWorkspace(
+            { logo: preparedFile.fileName },
+            workspaceId,
+            trx,
+          );
+        } else if (type === AttachmentType.SpaceIcon && spaceId) {
+          const space = await this.spaceRepo.findById(spaceId, workspaceId, {
+            trx,
+          });
+
+          oldFileName = space.logo;
+
+          await this.spaceRepo.updateSpace(
+            { logo: preparedFile.fileName },
+            spaceId,
+            workspaceId,
+            trx,
+          );
+        } else {
+          throw new BadRequestException(`Image upload aborted.`);
+        }
+      });
+    } catch (err) {
+      // delete uploaded file on db update failure
+      await this.deleteRedundantFile(filePath);
+      throw new BadRequestException('Failed to upload image');
+    }
+
+    if (oldFileName && !oldFileName.toLowerCase().startsWith('http')) {
+      // delete old avatar or logo
+      const oldFilePath =
+        getAttachmentFolderPath(type, workspaceId) + '/' + oldFileName;
+      await this.deleteRedundantFile(oldFilePath);
+    }
+
+    return attachment;
+  }
+
+  async deleteRedundantFile(filePath: string) {
+    try {
+      await this.storageService.delete(filePath);
+      await this.attachmentRepo.deleteAttachmentByFilePath(filePath);
+    } catch (error) {
+      this.logger.error('deleteRedundantFile', error);
+    }
+  }
+
+  async uploadToDrive(filePath: string, fileContent: Buffer | Readable) {
+    try {
+      await this.storageService.upload(filePath, fileContent);
+    } catch (err) {
+      this.logger.error('Error uploading file to drive:', err);
+      throw new BadRequestException('Error uploading file to drive');
+    }
+  }
+
+  async saveAttachment(opts: {
+    attachmentId?: string;
+    preparedFile: PreparedFile;
+    filePath: string;
+    type: AttachmentType;
+    userId: string;
+    workspaceId: string;
+    pageId?: string;
+    spaceId?: string;
+    trx?: KyselyTransaction;
+  }): Promise<Attachment> {
+    const {
+      attachmentId,
+      preparedFile,
+      filePath,
+      type,
+      userId,
+      workspaceId,
+      pageId,
+      spaceId,
+      trx,
+    } = opts;
+    return this.attachmentRepo.insertAttachment(
+      {
+        id: attachmentId,
+        type: type,
+        filePath: filePath,
+        fileName: preparedFile.fileName,
+        fileSize: preparedFile.fileSize,
+        mimeType: preparedFile.mimeType,
+        fileExt: preparedFile.fileExtension,
+        creatorId: userId,
+        workspaceId: workspaceId,
+        pageId: pageId,
+        spaceId: spaceId,
+      },
+      trx,
+    );
+  }
+
+  async handleDeleteAiChatAttachments(aiChatId: string) {
+    try {
+      const attachments = await this.attachmentRepo.findByAiChatId(aiChatId);
+      if (!attachments || attachments.length === 0) {
+        return;
+      }
+
+      await Promise.all(
+        attachments.map(async (attachment) => {
+          try {
+            await this.storageService.delete(attachment.filePath);
+            await this.attachmentRepo.deleteAttachmentById(attachment.id);
+          } catch (err) {
+            this.logger.log(
+              `DeleteAiChatAttachments: failed to delete attachment ${attachment.id}:`,
+              err,
+            );
+          }
+        }),
+      );
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  async handleDeleteSpaceAttachments(spaceId: string) {
+    try {
+      const attachments = await this.attachmentRepo.findBySpaceId(spaceId);
+      if (!attachments || attachments.length === 0) {
+        return;
+      }
+
+      const failedDeletions = [];
+
+      await Promise.all(
+        attachments.map(async (attachment) => {
+          try {
+            await this.storageService.delete(attachment.filePath);
+            await this.attachmentRepo.deleteAttachmentById(attachment.id);
+          } catch (err) {
+            failedDeletions.push(attachment.id);
+            this.logger.log(
+              `DeleteSpaceAttachments: failed to delete attachment ${attachment.id}:`,
+              err,
+            );
+          }
+        }),
+      );
+
+      if (failedDeletions.length === attachments.length) {
+        throw new Error(
+          `Failed to delete any attachments for spaceId: ${spaceId}`,
+        );
+      }
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  async handleDeleteUserAvatars(userId: string) {
+    try {
+      const userAvatars = await this.db
+        .selectFrom('attachments')
+        .select(['id', 'filePath'])
+        .where('creatorId', '=', userId)
+        .where('type', '=', AttachmentType.Avatar)
+        .execute();
+
+      if (!userAvatars || userAvatars.length === 0) {
+        return;
+      }
+
+      await Promise.all(
+        userAvatars.map(async (attachment) => {
+          try {
+            await this.storageService.delete(attachment.filePath);
+            await this.attachmentRepo.deleteAttachmentById(attachment.id);
+          } catch (err) {
+            this.logger.log(
+              `DeleteUserAvatar: failed to delete user avatar ${attachment.id}:`,
+              err,
+            );
+          }
+        }),
+      );
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  async handleDeletePageAttachments(pageId: string) {
+    try {
+      // Fetch attachments for this page from database
+      const attachments = await this.db
+        .selectFrom('attachments')
+        .select(['id', 'filePath'])
+        .where('pageId', '=', pageId)
+        .execute();
+
+      if (!attachments || attachments.length === 0) {
+        return;
+      }
+
+      const failedDeletions = [];
+
+      await Promise.all(
+        attachments.map(async (attachment) => {
+          try {
+            // Delete from storage
+            await this.storageService.delete(attachment.filePath);
+            // Delete from database
+            await this.attachmentRepo.deleteAttachmentById(attachment.id);
+          } catch (err) {
+            failedDeletions.push(attachment.id);
+            this.logger.error(
+              `Failed to delete attachment ${attachment.id} for page ${pageId}:`,
+              err,
+            );
+          }
+        }),
+      );
+
+      if (failedDeletions.length > 0) {
+        this.logger.warn(
+          `Failed to delete ${failedDeletions.length} attachments for page ${pageId}`,
+        );
+      }
+    } catch (err) {
+      this.logger.error(
+        `Error in handleDeletePageAttachments for page ${pageId}:`,
+        err,
+      );
+      throw err;
+    }
+  }
+
+  async removeUserAvatar(user: User) {
+    if (user.avatarUrl && !user.avatarUrl.toLowerCase().startsWith('http')) {
+      const filePath = `${getAttachmentFolderPath(AttachmentType.Avatar, user.workspaceId)}/${user.avatarUrl}`;
+      await this.deleteRedundantFile(filePath);
+    }
+
+    await this.userRepo.updateUser(
+      { avatarUrl: null },
+      user.id,
+      user.workspaceId,
+    );
+  }
+
+  async removeSpaceIcon(spaceId: string, workspaceId: string) {
+    const space = await this.spaceRepo.findById(spaceId, workspaceId);
+
+    if (!space) {
+      throw new NotFoundException('Space not found');
+    }
+
+    if (space.logo && !space.logo.toLowerCase().startsWith('http')) {
+      const filePath = `${getAttachmentFolderPath(AttachmentType.SpaceIcon, workspaceId)}/${space.logo}`;
+      await this.deleteRedundantFile(filePath);
+    }
+
+    await this.spaceRepo.updateSpace({ logo: null }, spaceId, workspaceId);
+  }
+
+  async removeWorkspaceIcon(workspace: Workspace) {
+    if (workspace.logo && !workspace.logo.toLowerCase().startsWith('http')) {
+      const filePath = `${getAttachmentFolderPath(AttachmentType.WorkspaceIcon, workspace.id)}/${workspace.logo}`;
+      await this.deleteRedundantFile(filePath);
+    }
+
+    await this.workspaceRepo.updateWorkspace({ logo: null }, workspace.id);
+  }
+}
--- a/apps/server/src/core/auth/auth.constants.ts
+++ b/apps/server/src/core/auth/auth.constants.ts
@@ -0,0 +1,4 @@
+export enum UserTokenType {
+  FORGOT_PASSWORD = 'forgot-password',
+  EMAIL_VERIFICATION = 'email-verification',
+}
--- a/apps/server/src/core/auth/auth.controller.spec.ts
+++ b/apps/server/src/core/auth/auth.controller.spec.ts
@@ -0,0 +1,18 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AuthController } from './auth.controller';
+
+describe('AuthController', () => {
+  let controller: AuthController;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [AuthController],
+    }).compile();
+
+    controller = module.get<AuthController>(AuthController);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+});
--- a/apps/server/src/core/auth/auth.controller.ts
+++ b/apps/server/src/core/auth/auth.controller.ts
@@ -0,0 +1,231 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  Post,
+  Req,
+  Res,
+  UseGuards,
+  Logger,
+} from '@nestjs/common';
+import { SkipThrottle, ThrottlerGuard } from '@nestjs/throttler';
+import {
+  ALL_NAMED_THROTTLERS_SKIPPED,
+  AUTH_THROTTLER,
+} from '../../integrations/throttle/throttler-names';
+import { LoginDto } from './dto/login.dto';
+import { AuthService } from './services/auth.service';
+import { SessionService } from '../session/session.service';
+import { SetupGuard } from './guards/setup.guard';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { CreateAdminUserDto } from './dto/create-admin-user.dto';
+import { ChangePasswordDto } from './dto/change-password.dto';
+import { AuthUser } from '../../common/decorators/auth-user.decorator';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { ForgotPasswordDto } from './dto/forgot-password.dto';
+import { PasswordResetDto } from './dto/password-reset.dto';
+import { VerifyUserTokenDto } from './dto/verify-user-token.dto';
+import { FastifyReply, FastifyRequest } from 'fastify';
+import { validateSsoEnforcement } from './auth.util';
+import { ModuleRef } from '@nestjs/core';
+import { AuditEvent, AuditResource } from '../../common/events/audit-events';
+import {
+  AUDIT_SERVICE,
+  IAuditService,
+} from '../../integrations/audit/audit.service';
+
+@SkipThrottle({ ...ALL_NAMED_THROTTLERS_SKIPPED, [AUTH_THROTTLER]: false })
+@UseGuards(ThrottlerGuard)
+@Controller('auth')
+export class AuthController {
+  private readonly logger = new Logger(AuthController.name);
+
+  constructor(
+    private authService: AuthService,
+    private sessionService: SessionService,
+    private environmentService: EnvironmentService,
+    private moduleRef: ModuleRef,
+    @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
+  ) {}
+
+  @HttpCode(HttpStatus.OK)
+  @Post('login')
+  async login(
+    @AuthWorkspace() workspace: Workspace,
+    @Res({ passthrough: true }) res: FastifyReply,
+    @Body() loginInput: LoginDto,
+  ) {
+    validateSsoEnforcement(workspace);
+
+    let MfaModule: any;
+    let isMfaModuleReady = false;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      MfaModule = require('./../../ee/mfa/services/mfa.service');
+      isMfaModuleReady = true;
+    } catch (err) {
+      this.logger.debug(
+        'MFA module requested but EE module not bundled in this build',
+      );
+      isMfaModuleReady = false;
+    }
+    if (isMfaModuleReady) {
+      const mfaService = this.moduleRef.get(MfaModule.MfaService, {
+        strict: false,
+      });
+
+      const mfaResult = await mfaService.checkMfaRequirements(
+        loginInput,
+        workspace,
+        res,
+      );
+
+      if (mfaResult) {
+        // If user has MFA enabled OR workspace enforces MFA, require MFA verification
+        if (mfaResult.userHasMfa || mfaResult.requiresMfaSetup) {
+          return {
+            userHasMfa: mfaResult.userHasMfa,
+            requiresMfaSetup: mfaResult.requiresMfaSetup,
+            isMfaEnforced: mfaResult.isMfaEnforced,
+          };
+        } else if (mfaResult.authToken) {
+          // User doesn't have MFA and workspace doesn't require it
+          this.setAuthCookie(res, mfaResult.authToken);
+          return;
+        }
+      }
+    }
+
+    const authToken = await this.authService.login(loginInput, workspace.id);
+    this.setAuthCookie(res, authToken);
+  }
+
+  @UseGuards(SetupGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('setup')
+  async setupWorkspace(
+    @Res({ passthrough: true }) res: FastifyReply,
+    @Body() createAdminUserDto: CreateAdminUserDto,
+  ) {
+    const { workspace, authToken } =
+      await this.authService.setup(createAdminUserDto);
+
+    this.setAuthCookie(res, authToken);
+    return workspace;
+  }
+
+  @SkipThrottle({ [AUTH_THROTTLER]: true })
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('change-password')
+  async changePassword(
+    @Body() dto: ChangePasswordDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+    @Req() req: FastifyRequest,
+  ) {
+    const currentSessionId = (req.raw as any).sessionId;
+    return this.authService.changePassword(
+      dto,
+      user.id,
+      workspace.id,
+      currentSessionId,
+    );
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('forgot-password')
+  async forgotPassword(
+    @Body() forgotPasswordDto: ForgotPasswordDto,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    validateSsoEnforcement(workspace);
+    return this.authService.forgotPassword(forgotPasswordDto, workspace);
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('password-reset')
+  async passwordReset(
+    @Res({ passthrough: true }) res: FastifyReply,
+    @Body() passwordResetDto: PasswordResetDto,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const result = await this.authService.passwordReset(
+      passwordResetDto,
+      workspace,
+    );
+
+    if (result.requiresLogin) {
+      return {
+        requiresLogin: true,
+      };
+    }
+
+    // Set auth cookie if no MFA is required
+    this.setAuthCookie(res, result.authToken);
+    return {
+      requiresLogin: false,
+    };
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('verify-token')
+  async verifyResetToken(
+    @Body() verifyUserTokenDto: VerifyUserTokenDto,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.authService.verifyUserToken(verifyUserTokenDto, workspace.id);
+  }
+
+  @SkipThrottle({ [AUTH_THROTTLER]: true })
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('collab-token')
+  async collabToken(
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.authService.getCollabToken(user, workspace.id);
+  }
+
+  @SkipThrottle({ [AUTH_THROTTLER]: true })
+  @UseGuards(JwtAuthGuard)
+  @HttpCode(HttpStatus.OK)
+  @Post('logout')
+  async logout(
+    @AuthUser() user: User,
+    @Req() req: FastifyRequest,
+    @Res({ passthrough: true }) res: FastifyReply,
+  ) {
+    const sessionId = (req.raw as any).sessionId;
+    if (sessionId) {
+      await this.sessionService.revokeSession(
+        sessionId,
+        user.id,
+        user.workspaceId,
+      );
+    }
+
+    res.clearCookie('authToken');
+
+    this.auditService.log({
+      event: AuditEvent.USER_LOGOUT,
+      resourceType: AuditResource.USER,
+      resourceId: user.id,
+    });
+  }
+
+  setAuthCookie(res: FastifyReply, token: string) {
+    res.setCookie('authToken', token, {
+      httpOnly: true,
+      sameSite: 'lax',
+      path: '/',
+      expires: this.environmentService.getCookieExpiresIn(),
+      secure: this.environmentService.isHttps(),
+    });
+  }
+}
--- a/apps/server/src/core/auth/auth.module.ts
+++ b/apps/server/src/core/auth/auth.module.ts
@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { AuthController } from './auth.controller';
+import { AuthService } from './services/auth.service';
+import { JwtStrategy } from './strategies/jwt.strategy';
+import { WorkspaceModule } from '../workspace/workspace.module';
+import { SignupService } from './services/signup.service';
+import { TokenModule } from './token.module';
+
+@Module({
+  imports: [TokenModule, WorkspaceModule],
+  controllers: [AuthController],
+  providers: [AuthService, SignupService, JwtStrategy],
+  exports: [SignupService],
+})
+export class AuthModule {}
--- a/apps/server/src/core/auth/auth.util.ts
+++ b/apps/server/src/core/auth/auth.util.ts
@@ -0,0 +1,53 @@
+import { BadRequestException } from '@nestjs/common';
+import { Workspace } from '@docmost/db/types/entity.types';
+import { createHmac } from 'node:crypto';
+
+export function computeEmailSignature(
+  email: string,
+  workspaceId: string,
+  appSecret: string,
+): string {
+  return createHmac('sha256', appSecret)
+    .update(`${email.toLowerCase()}:${workspaceId}`)
+    .digest('hex');
+}
+
+export function throwIfEmailNotVerified(opts: {
+  isCloud: boolean;
+  emailVerifiedAt: Date | null;
+  email: string;
+  workspaceId: string;
+  appSecret: string;
+}): void {
+  if (!opts.isCloud || opts.emailVerifiedAt) return;
+
+  const emailSignature = computeEmailSignature(
+    opts.email,
+    opts.workspaceId,
+    opts.appSecret,
+  );
+  throw new BadRequestException({
+    message:
+      'Please verify your email address. Check your inbox for the verification link.',
+    emailSignature,
+  });
+}
+
+export function validateSsoEnforcement(workspace: Workspace) {
+  if (workspace.enforceSso) {
+    throw new BadRequestException('This workspace has enforced SSO login.');
+  }
+}
+
+export function validateAllowedEmail(userEmail: string, workspace: Workspace) {
+  const emailParts = userEmail.split('@');
+  const emailDomain = emailParts[1].toLowerCase();
+  if (
+    workspace.emailDomains?.length > 0 &&
+    !workspace.emailDomains.includes(emailDomain)
+  ) {
+    throw new BadRequestException(
+      `The email domain "${emailDomain}" is not approved for this workspace.`,
+    );
+  }
+}
--- a/apps/server/src/core/auth/dto/change-password.dto.ts
+++ b/apps/server/src/core/auth/dto/change-password.dto.ts
@@ -0,0 +1,13 @@
+import { IsNotEmpty, IsString, MinLength } from 'class-validator';
+
+export class ChangePasswordDto {
+  @IsNotEmpty()
+  @MinLength(8)
+  @IsString()
+  oldPassword: string;
+
+  @IsNotEmpty()
+  @MinLength(8)
+  @IsString()
+  newPassword: string;
+}
--- a/apps/server/src/core/auth/dto/create-admin-user.dto.ts
+++ b/apps/server/src/core/auth/dto/create-admin-user.dto.ts
@@ -0,0 +1,33 @@
+import {
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  MaxLength,
+  MinLength,
+} from 'class-validator';
+import { CreateUserDto } from './create-user.dto';
+import { Transform, TransformFnParams } from 'class-transformer';
+import { NoUrls } from '../../../common/validators/no-urls.validator';
+
+export class CreateAdminUserDto extends CreateUserDto {
+  @IsNotEmpty()
+  @MinLength(1)
+  @MaxLength(50)
+  @NoUrls()
+  @Transform(({ value }: TransformFnParams) => value?.trim())
+  name: string;
+
+  @IsOptional()
+  @MinLength(1)
+  @MaxLength(50)
+  @IsString()
+  @Transform(({ value }: TransformFnParams) => value?.trim())
+  workspaceName: string;
+
+  @IsOptional()
+  @MinLength(4)
+  @MaxLength(50)
+  @IsString()
+  @Transform(({ value }: TransformFnParams) => value?.trim())
+  hostname?: string;
+}
--- a/apps/server/src/core/auth/dto/create-user.dto.ts
+++ b/apps/server/src/core/auth/dto/create-user.dto.ts
@@ -0,0 +1,30 @@
+import {
+  IsEmail,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  MaxLength,
+  MinLength,
+} from 'class-validator';
+import { Transform, TransformFnParams } from 'class-transformer';
+import { NoUrls } from '../../../common/validators/no-urls.validator';
+
+export class CreateUserDto {
+  @IsOptional()
+  @MinLength(1)
+  @MaxLength(50)
+  @IsString()
+  @NoUrls()
+  @Transform(({ value }: TransformFnParams) => value?.trim())
+  name: string;
+
+  @IsNotEmpty()
+  @IsEmail()
+  email: string;
+
+  @IsNotEmpty()
+  @MinLength(8)
+  @MaxLength(70)
+  @IsString()
+  password: string;
+}
--- a/apps/server/src/core/auth/dto/forgot-password.dto.ts
+++ b/apps/server/src/core/auth/dto/forgot-password.dto.ts
@@ -0,0 +1,7 @@
+import { IsEmail, IsNotEmpty } from 'class-validator';
+
+export class ForgotPasswordDto {
+  @IsNotEmpty()
+  @IsEmail()
+  email: string;
+}
--- a/apps/server/src/core/auth/dto/jwt-payload.ts
+++ b/apps/server/src/core/auth/dto/jwt-payload.ts
@@ -0,0 +1,73 @@
+export enum JwtType {
+  ACCESS = 'access',
+  COLLAB = 'collab',
+  EXCHANGE = 'exchange',
+  ATTACHMENT = 'attachment',
+  MFA_TOKEN = 'mfa_token',
+  API_KEY = 'api_key',
+  PDF_RENDER = 'pdf_render',
+  PDF_EXPORT_DOWNLOAD = 'pdf_export_download',
+  OAUTH_ACCESS = 'oauth_access',
+}
+export type JwtPayload = {
+  sub: string;
+  email: string;
+  workspaceId: string;
+  type: 'access';
+  sessionId?: string;
+};
+
+export type JwtCollabPayload = {
+  sub: string;
+  workspaceId: string;
+  type: 'collab';
+};
+
+export type JwtExchangePayload = {
+  sub: string;
+  workspaceId: string;
+  type: 'exchange';
+};
+
+export type JwtAttachmentPayload = {
+  attachmentId: string;
+  pageId: string;
+  workspaceId: string;
+  type: 'attachment';
+};
+
+export interface JwtMfaTokenPayload {
+  sub: string;
+  workspaceId: string;
+  type: 'mfa_token';
+}
+
+export type JwtApiKeyPayload = {
+  sub: string;
+  workspaceId: string;
+  apiKeyId: string;
+  type: 'api_key';
+};
+
+export type JwtPdfRenderPayload = {
+  pageId: string;
+  workspaceId: string;
+  type: 'pdf_render';
+};
+
+export type JwtPdfExportDownloadPayload = {
+  fileTaskId: string;
+  workspaceId: string;
+  type: 'pdf_export_download';
+};
+
+export type JwtOAuthPayload = {
+  sub: string;
+  workspaceId: string;
+  grantId: string;
+  scope: string;
+  aud: string;
+  iss: string;
+  jti: string;
+  type: JwtType.OAUTH_ACCESS;
+};
--- a/apps/server/src/core/auth/dto/login.dto.ts
+++ b/apps/server/src/core/auth/dto/login.dto.ts
@@ -0,0 +1,11 @@
+import { IsEmail, IsNotEmpty, IsString } from 'class-validator';
+
+export class LoginDto {
+  @IsNotEmpty()
+  @IsEmail()
+  email: string;
+
+  @IsNotEmpty()
+  @IsString()
+  password: string;
+}
--- a/apps/server/src/core/auth/dto/password-reset.dto.ts
+++ b/apps/server/src/core/auth/dto/password-reset.dto.ts
@@ -0,0 +1,10 @@
+import { IsString, MinLength } from 'class-validator';
+
+export class PasswordResetDto {
+  @IsString()
+  token: string;
+
+  @IsString()
+  @MinLength(8)
+  newPassword: string;
+}
--- a/apps/server/src/core/auth/dto/verify-user-token.dto.ts
+++ b/apps/server/src/core/auth/dto/verify-user-token.dto.ts
@@ -0,0 +1,9 @@
+import { IsString } from 'class-validator';
+
+export class VerifyUserTokenDto {
+  @IsString()
+  token: string;
+
+  @IsString()
+  type: string;
+}
--- a/apps/server/src/core/auth/guards/setup.guard.ts
+++ b/apps/server/src/core/auth/guards/setup.guard.ts
@@ -0,0 +1,23 @@
+import { CanActivate, ForbiddenException, Injectable } from '@nestjs/common';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { EnvironmentService } from '../../../integrations/environment/environment.service';
+
+@Injectable()
+export class SetupGuard implements CanActivate {
+  constructor(
+    private workspaceRepo: WorkspaceRepo,
+    private environmentService: EnvironmentService,
+  ) {}
+
+  async canActivate(): Promise<boolean> {
+    if (this.environmentService.isCloud()) {
+      return false;
+    }
+
+    const workspaceCount = await this.workspaceRepo.count();
+    if (workspaceCount > 0) {
+      throw new ForbiddenException('Workspace setup already completed.');
+    }
+    return true;
+  }
+}
--- a/apps/server/src/core/auth/services/auth.service.spec.ts
+++ b/apps/server/src/core/auth/services/auth.service.spec.ts
@@ -0,0 +1,18 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AuthService } from './auth.service';
+
+describe('AuthService', () => {
+  let service: AuthService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [AuthService],
+    }).compile();
+
+    service = module.get<AuthService>(AuthService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+});
--- a/apps/server/src/core/auth/services/auth.service.ts
+++ b/apps/server/src/core/auth/services/auth.service.ts
@@ -0,0 +1,351 @@
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { LoginDto } from '../dto/login.dto';
+import { CreateUserDto } from '../dto/create-user.dto';
+import { TokenService } from './token.service';
+import { SessionService } from '../../session/session.service';
+import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
+import { SignupService } from './signup.service';
+import { CreateAdminUserDto } from '../dto/create-admin-user.dto';
+import { UserRepo } from '@docmost/db/repos/user/user.repo';
+import {
+  comparePasswordHash,
+  hashPassword,
+  isUserDisabled,
+  nanoIdGen,
+} from '../../../common/helpers';
+import { throwIfEmailNotVerified } from '../auth.util';
+import { ChangePasswordDto } from '../dto/change-password.dto';
+import { MailService } from '../../../integrations/mail/mail.service';
+import ChangePasswordEmail from '@docmost/transactional/emails/change-password-email';
+import { ForgotPasswordDto } from '../dto/forgot-password.dto';
+import ForgotPasswordEmail from '@docmost/transactional/emails/forgot-password-email';
+import { UserTokenRepo } from '@docmost/db/repos/user-token/user-token.repo';
+import { PasswordResetDto } from '../dto/password-reset.dto';
+import { User, UserToken, Workspace } from '@docmost/db/types/entity.types';
+import { UserTokenType } from '../auth.constants';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { InjectKysely } from 'nestjs-kysely';
+import { executeTx } from '@docmost/db/utils';
+import { VerifyUserTokenDto } from '../dto/verify-user-token.dto';
+import { DomainService } from '../../../integrations/environment/domain.service';
+import { AuditEvent, AuditResource } from '../../../common/events/audit-events';
+import {
+  AUDIT_SERVICE,
+  IAuditService,
+} from '../../../integrations/audit/audit.service';
+import { EnvironmentService } from '../../../integrations/environment/environment.service';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { EventName } from '../../../common/events/event.contants';
+
+@Injectable()
+export class AuthService {
+  private readonly logger = new Logger(AuthService.name);
+
+  constructor(
+    private signupService: SignupService,
+    private tokenService: TokenService,
+    private sessionService: SessionService,
+    private userSessionRepo: UserSessionRepo,
+    private userRepo: UserRepo,
+    private userTokenRepo: UserTokenRepo,
+    private mailService: MailService,
+    private domainService: DomainService,
+    private environmentService: EnvironmentService,
+    private eventEmitter: EventEmitter2,
+    @InjectKysely() private readonly db: KyselyDB,
+    @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
+  ) {}
+
+  async login(loginDto: LoginDto, workspaceId: string) {
+    const user = await this.userRepo.findByEmail(loginDto.email, workspaceId, {
+      includePassword: true,
+    });
+
+    const errorMessage = 'Email or password does not match';
+    if (!user || isUserDisabled(user)) {
+      throw new UnauthorizedException(errorMessage);
+    }
+
+    const isPasswordMatch = await comparePasswordHash(
+      loginDto.password,
+      user.password,
+    );
+
+    if (!isPasswordMatch) {
+      throw new UnauthorizedException(errorMessage);
+    }
+
+    throwIfEmailNotVerified({
+      isCloud: this.environmentService.isCloud(),
+      emailVerifiedAt: user.emailVerifiedAt,
+      email: user.email,
+      workspaceId,
+      appSecret: this.environmentService.getAppSecret(),
+    });
+
+    user.lastLoginAt = new Date();
+    await this.userRepo.updateLastLogin(user.id, workspaceId);
+
+    this.auditService.log({
+      event: AuditEvent.USER_LOGIN,
+      resourceType: AuditResource.USER,
+      resourceId: user.id,
+      metadata: { source: 'password' },
+    });
+
+    return this.sessionService.createSessionAndToken(user);
+  }
+
+  async register(createUserDto: CreateUserDto, workspaceId: string) {
+    const user = await this.signupService.signup(createUserDto, workspaceId);
+    return this.sessionService.createSessionAndToken(user);
+  }
+
+  async setup(createAdminUserDto: CreateAdminUserDto) {
+    const { workspace, user } =
+      await this.signupService.initialSetup(createAdminUserDto);
+
+    const authToken = await this.sessionService.createSessionAndToken(user);
+    return { workspace, authToken };
+  }
+
+  async changePassword(
+    dto: ChangePasswordDto,
+    userId: string,
+    workspaceId: string,
+    currentSessionId?: string,
+  ): Promise<void> {
+    const user = await this.userRepo.findById(userId, workspaceId, {
+      includePassword: true,
+    });
+
+    if (!user || isUserDisabled(user)) {
+      throw new NotFoundException('User not found');
+    }
+
+    const comparePasswords = await comparePasswordHash(
+      dto.oldPassword,
+      user.password,
+    );
+
+    if (!comparePasswords) {
+      throw new BadRequestException('Current password is incorrect');
+    }
+
+    const newPasswordHash = await hashPassword(dto.newPassword);
+    await this.userRepo.updateUser(
+      {
+        password: newPasswordHash,
+        hasGeneratedPassword: false,
+      },
+      userId,
+      workspaceId,
+    );
+
+    if (currentSessionId) {
+      await this.userSessionRepo.deleteAllExceptCurrent(
+        currentSessionId,
+        userId,
+        workspaceId,
+      );
+    } else {
+      await this.userSessionRepo.deleteByUserId(userId, workspaceId);
+    }
+
+    this.auditService.log({
+      event: AuditEvent.USER_PASSWORD_CHANGED,
+      resourceType: AuditResource.USER,
+      resourceId: userId,
+    });
+
+    const emailTemplate = ChangePasswordEmail({ username: user.name });
+    await this.mailService.sendToQueue({
+      to: user.email,
+      subject: 'Your password has been changed',
+      template: emailTemplate,
+    });
+  }
+
+  async forgotPassword(
+    forgotPasswordDto: ForgotPasswordDto,
+    workspace: Workspace,
+  ): Promise<void> {
+    const user = await this.userRepo.findByEmail(
+      forgotPasswordDto.email,
+      workspace.id,
+    );
+
+    if (!user || isUserDisabled(user)) {
+      return;
+    }
+
+    const token = nanoIdGen(16);
+
+    await executeTx(this.db, async (trx) => {
+      await trx
+        .deleteFrom('userTokens')
+        .where('userId', '=', user.id)
+        .where('type', '=', UserTokenType.FORGOT_PASSWORD)
+        .execute();
+
+      await this.userTokenRepo.insertUserToken(
+        {
+          token,
+          userId: user.id,
+          workspaceId: user.workspaceId,
+          expiresAt: new Date(Date.now() + 30 * 60 * 1000), // 30 minutes
+          type: UserTokenType.FORGOT_PASSWORD,
+        },
+        { trx },
+      );
+    });
+
+    const resetLink = `${this.domainService.getUrl(workspace.hostname)}/password-reset?token=${token}`;
+
+    const emailTemplate = ForgotPasswordEmail({
+      username: user.name,
+      resetLink: resetLink,
+    });
+
+    await this.mailService.sendToQueue({
+      to: user.email,
+      subject: 'Reset your password',
+      template: emailTemplate,
+    });
+
+    this.auditService.log({
+      event: AuditEvent.USER_PASSWORD_RESET_REQUESTED,
+      resourceType: AuditResource.USER,
+      resourceId: user.id,
+      metadata: { source: 'forgot_password' },
+    });
+  }
+
+  async passwordReset(
+    passwordResetDto: PasswordResetDto,
+    workspace: Workspace,
+  ) {
+    const userToken = await this.userTokenRepo.findById(
+      passwordResetDto.token,
+      workspace.id,
+    );
+
+    if (
+      !userToken ||
+      userToken.type !== UserTokenType.FORGOT_PASSWORD ||
+      userToken.expiresAt < new Date()
+    ) {
+      throw new BadRequestException('Invalid or expired token');
+    }
+
+    const user = await this.userRepo.findById(userToken.userId, workspace.id, {
+      includeUserMfa: true,
+    });
+    if (!user || isUserDisabled(user)) {
+      throw new NotFoundException('User not found');
+    }
+
+    const newPasswordHash = await hashPassword(passwordResetDto.newPassword);
+
+    await executeTx(this.db, async (trx) => {
+      await this.userRepo.updateUser(
+        {
+          password: newPasswordHash,
+          hasGeneratedPassword: false,
+        },
+        user.id,
+        workspace.id,
+        trx,
+      );
+
+      await trx
+        .deleteFrom('userTokens')
+        .where('userId', '=', user.id)
+        .where('type', '=', UserTokenType.FORGOT_PASSWORD)
+        .execute();
+    });
+
+    await this.userSessionRepo.deleteByUserId(user.id, workspace.id);
+
+    // A failed revocation must not block the reset itself; log loudly instead.
+    try {
+      await this.eventEmitter.emitAsync(EventName.USER_PASSWORD_RESET, {
+        userId: user.id,
+        workspaceId: workspace.id,
+      });
+    } catch (err) {
+      this.logger.error(
+        `failed to revoke oauth grants for user ${user.id} after password reset`,
+        err,
+      );
+    }
+
+    this.auditService.setActorId(user.id);
+    this.auditService.log({
+      event: AuditEvent.USER_PASSWORD_RESET,
+      resourceType: AuditResource.USER,
+      resourceId: user.id,
+    });
+
+    const emailTemplate = ChangePasswordEmail({ username: user.name });
+    await this.mailService.sendToQueue({
+      to: user.email,
+      subject: 'Your password has been changed',
+      template: emailTemplate,
+    });
+
+    if (this.environmentService.isCloud() && !user.emailVerifiedAt) {
+      await this.userRepo.updateUser(
+        { emailVerifiedAt: new Date() },
+        user.id,
+        workspace.id,
+      );
+    }
+
+    // Check if user has MFA enabled or workspace enforces MFA
+    const userHasMfa = user?.['mfa']?.isEnabled || false;
+    const workspaceEnforcesMfa = workspace.enforceMfa || false;
+
+    if (userHasMfa || workspaceEnforcesMfa) {
+      return {
+        requiresLogin: true,
+      };
+    }
+
+    const authToken = await this.sessionService.createSessionAndToken(user);
+    return { authToken };
+  }
+
+  async verifyUserToken(
+    userTokenDto: VerifyUserTokenDto,
+    workspaceId: string,
+  ): Promise<void> {
+    const userToken: UserToken = await this.userTokenRepo.findById(
+      userTokenDto.token,
+      workspaceId,
+    );
+
+    if (
+      !userToken ||
+      userToken.type !== userTokenDto.type ||
+      userToken.expiresAt < new Date()
+    ) {
+      throw new BadRequestException('Invalid or expired token');
+    }
+  }
+
+  async getCollabToken(user: User, workspaceId: string) {
+    const token = await this.tokenService.generateCollabToken(
+      user,
+      workspaceId,
+    );
+    return { token };
+  }
+}
--- a/apps/server/src/core/auth/services/signup.service.ts
+++ b/apps/server/src/core/auth/services/signup.service.ts
@@ -0,0 +1,144 @@
+import { BadRequestException, Inject, Injectable } from '@nestjs/common';
+import { CreateUserDto } from '../dto/create-user.dto';
+import { WorkspaceService } from '../../workspace/services/workspace.service';
+import { CreateWorkspaceDto } from '../../workspace/dto/create-workspace.dto';
+import { CreateAdminUserDto } from '../dto/create-admin-user.dto';
+import { UserRepo } from '@docmost/db/repos/user/user.repo';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { getWorkspaceDefaultPageEditMode } from '../../workspace/workspace.util';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';
+import { InjectKysely } from 'nestjs-kysely';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import { GroupUserRepo } from '@docmost/db/repos/group/group-user.repo';
+import { UserRole } from '../../../common/helpers/types/permission';
+import { AuditEvent, AuditResource } from '../../../common/events/audit-events';
+import {
+  AUDIT_SERVICE,
+  IAuditService,
+} from '../../../integrations/audit/audit.service';
+
+@Injectable()
+export class SignupService {
+  constructor(
+    private userRepo: UserRepo,
+    private workspaceRepo: WorkspaceRepo,
+    private workspaceService: WorkspaceService,
+    private groupUserRepo: GroupUserRepo,
+    @InjectKysely() private readonly db: KyselyDB,
+    @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
+  ) {}
+
+  async signup(
+    createUserDto: CreateUserDto,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<User> {
+    const userCheck = await this.userRepo.findByEmail(
+      createUserDto.email,
+      workspaceId,
+    );
+
+    if (userCheck) {
+      throw new BadRequestException(
+        'An account with this email already exists in this workspace',
+      );
+    }
+
+    const user = await executeTx(
+      this.db,
+      async (trx) => {
+        // create user
+        const workspace = await this.workspaceRepo.findById(workspaceId, {
+          trx,
+        });
+        const user = await this.userRepo.insertUser(
+          {
+            ...createUserDto,
+            workspaceId: workspaceId,
+          },
+          trx,
+          { pageEditMode: getWorkspaceDefaultPageEditMode(workspace) },
+        );
+
+        // add user to workspace
+        await this.workspaceService.addUserToWorkspace(
+          user.id,
+          workspaceId,
+          undefined,
+          trx,
+        );
+
+        // add user to default group
+        await this.groupUserRepo.addUserToDefaultGroup(
+          user.id,
+          workspaceId,
+          trx,
+        );
+        return user;
+      },
+      trx,
+    );
+
+    this.auditService.log({
+      event: AuditEvent.USER_CREATED,
+      resourceType: AuditResource.USER,
+      resourceId: user.id,
+      changes: {
+        after: {
+          name: user.name,
+          email: user.email,
+          role: user.role,
+        },
+      },
+      metadata: {
+        source: 'signup',
+      },
+    });
+
+    return user;
+  }
+
+  async initialSetup(
+    createAdminUserDto: CreateAdminUserDto,
+    trx?: KyselyTransaction,
+  ) {
+    let user: User,
+      workspace: Workspace = null;
+
+    await executeTx(
+      this.db,
+      async (trx) => {
+        // create user
+        user = await this.userRepo.insertUser(
+          {
+            name: createAdminUserDto.name,
+            email: createAdminUserDto.email,
+            password: createAdminUserDto.password,
+            role: UserRole.OWNER,
+            emailVerifiedAt: new Date(),
+          },
+          trx,
+        );
+
+        // create workspace with full setup
+        const workspaceData: CreateWorkspaceDto = {
+          name: createAdminUserDto.workspaceName || 'My workspace',
+          hostname: createAdminUserDto.hostname,
+        };
+
+        workspace = await this.workspaceService.create(
+          user,
+          workspaceData,
+          trx,
+        );
+
+        user.workspaceId = workspace.id;
+        return user;
+      },
+      trx,
+    );
+
+    return { user, workspace };
+  }
+}
--- a/apps/server/src/core/auth/services/token.service.spec.ts
+++ b/apps/server/src/core/auth/services/token.service.spec.ts
@@ -0,0 +1,18 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { TokenService } from './token.service';
+
+describe('TokenService', () => {
+  let service: TokenService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [TokenService],
+    }).compile();
+
+    service = module.get<TokenService>(TokenService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+});
--- a/apps/server/src/core/auth/services/token.service.ts
+++ b/apps/server/src/core/auth/services/token.service.ts
@@ -0,0 +1,157 @@
+import {
+  ForbiddenException,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import type { StringValue } from 'ms';
+import { EnvironmentService } from '../../../integrations/environment/environment.service';
+import {
+  JwtApiKeyPayload,
+  JwtAttachmentPayload,
+  JwtCollabPayload,
+  JwtExchangePayload,
+  JwtMfaTokenPayload,
+  JwtPayload,
+  JwtPdfExportDownloadPayload,
+  JwtPdfRenderPayload,
+  JwtType,
+} from '../dto/jwt-payload';
+import { User } from '@docmost/db/types/entity.types';
+import { isUserDisabled } from '../../../common/helpers';
+
+@Injectable()
+export class TokenService {
+  constructor(
+    private jwtService: JwtService,
+    private environmentService: EnvironmentService,
+  ) {}
+
+  async generateAccessToken(user: User, sessionId: string): Promise<string> {
+    if (isUserDisabled(user)) {
+      throw new ForbiddenException();
+    }
+
+    const payload: JwtPayload = {
+      sub: user.id,
+      email: user.email,
+      workspaceId: user.workspaceId,
+      type: JwtType.ACCESS,
+      sessionId,
+    };
+    return this.jwtService.sign(payload);
+  }
+
+  async generateCollabToken(user: User, workspaceId: string): Promise<string> {
+    if (isUserDisabled(user)) {
+      throw new ForbiddenException();
+    }
+
+    const payload: JwtCollabPayload = {
+      sub: user.id,
+      workspaceId,
+      type: JwtType.COLLAB,
+    };
+    const expiresIn = '24h';
+    return this.jwtService.sign(payload, { expiresIn });
+  }
+
+  async generateExchangeToken(
+    userId: string,
+    workspaceId: string,
+  ): Promise<string> {
+    const payload: JwtExchangePayload = {
+      sub: userId,
+      workspaceId: workspaceId,
+      type: JwtType.EXCHANGE,
+    };
+    return this.jwtService.sign(payload, { expiresIn: '10s' });
+  }
+
+  async generateAttachmentToken(opts: {
+    attachmentId: string;
+    pageId: string;
+    workspaceId: string;
+  }): Promise<string> {
+    const { attachmentId, pageId, workspaceId } = opts;
+    const payload: JwtAttachmentPayload = {
+      attachmentId: attachmentId,
+      pageId: pageId,
+      workspaceId: workspaceId,
+      type: JwtType.ATTACHMENT,
+    };
+    return this.jwtService.sign(payload, { expiresIn: '1h' });
+  }
+
+  async generateMfaToken(user: User, workspaceId: string): Promise<string> {
+    if (isUserDisabled(user)) {
+      throw new ForbiddenException();
+    }
+
+    const payload: JwtMfaTokenPayload = {
+      sub: user.id,
+      workspaceId,
+      type: JwtType.MFA_TOKEN,
+    };
+    return this.jwtService.sign(payload, { expiresIn: '5m' });
+  }
+
+  async generateApiToken(opts: {
+    apiKeyId: string;
+    user: User;
+    workspaceId: string;
+    expiresIn?: StringValue | number;
+  }): Promise<string> {
+    const { apiKeyId, user, workspaceId, expiresIn } = opts;
+    if (isUserDisabled(user)) {
+      throw new ForbiddenException();
+    }
+
+    const payload: JwtApiKeyPayload = {
+      sub: user.id,
+      apiKeyId: apiKeyId,
+      workspaceId,
+      type: JwtType.API_KEY,
+    };
+
+    return this.jwtService.sign(payload, expiresIn ? { expiresIn } : {});
+  }
+
+  async generatePdfRenderToken(
+    pageId: string,
+    workspaceId: string,
+  ): Promise<string> {
+    const payload: JwtPdfRenderPayload = {
+      pageId,
+      workspaceId,
+      type: JwtType.PDF_RENDER,
+    };
+    return this.jwtService.sign(payload, { expiresIn: '60s' });
+  }
+
+  async generatePdfExportDownloadToken(
+    fileTaskId: string,
+    workspaceId: string,
+  ): Promise<string> {
+    const payload: JwtPdfExportDownloadPayload = {
+      fileTaskId,
+      workspaceId,
+      type: JwtType.PDF_EXPORT_DOWNLOAD,
+    };
+    return this.jwtService.sign(payload, { expiresIn: '1h' });
+  }
+
+  async verifyJwt(token: string, tokenType: string) {
+    const payload = await this.jwtService.verifyAsync(token, {
+      secret: this.environmentService.getAppSecret(),
+    });
+
+    if (payload.type !== tokenType) {
+      throw new UnauthorizedException(
+        'Invalid JWT token. Token type does not match.',
+      );
+    }
+
+    return payload;
+  }
+}
--- a/Show More
+++ b/Show More