feat(html-embed): per-workspace feature toggle, default OFF

The admin-only raw HTML/JS embed is a deliberate stored-XSS surface, so gate the
whole feature behind a workspace toggle that is OFF by default; it only works
when a workspace admin explicitly enables it.

- settings.htmlEmbed (boolean, default false) + workspace-update field htmlEmbed,
  persisted via WorkspaceRepo.updateSetting with an audit diff. Flipping it is
  admin-only (same Manage Settings CASL as other workspace toggles).
- New gate htmlEmbedAllowed(featureEnabled, role) = featureEnabled && admin/owner.
  All 7 server write paths (create, duplicate, collab onStoreDocument, REST/MCP/AI
  updatePageContent, single + zip import, transclusion unsync) now read the
  workspace's settings.htmlEmbed and strip unless (toggle ON AND admin). OFF
  (default, or a failed/empty workspace lookup) strips htmlEmbed for EVERYONE
  including admins -> existing embeds are cleaned up on next save, none persist.
- Client (defense-in-depth): the /html slash item is hidden unless toggle ON +
  admin; the NodeView executes nothing and shows a 'disabled in this workspace'
  placeholder when OFF; an admin Switch in Workspace Settings -> General with a
  description of the behavior.
- docs/html-embed-admin.md documents the toggle + admin-only + fail-closed
  coedit (a non-admin save strips an admin's embed) + execution semantics.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/server/src/integrations/import/services/file-import-task.service.ts

@@ -21,11 +21,13 @@ import { FileTask, InsertablePage } from '@docmost/db/types/entity.types';
 import { markdownToHtml } from '@docmost/editor-ext';
 import { getProsemirrorContent } from '../../../common/helpers/prosemirror/utils';
 import {
-  canAuthorHtmlEmbed,
   hasHtmlEmbedNode,
+  htmlEmbedAllowed,
+  isHtmlEmbedFeatureEnabled,
   stripHtmlEmbedNodes,
 } from '../../../common/helpers/prosemirror/html-embed.util';
 import { UserRepo } from '@docmost/db/repos/user/user.repo';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 import { formatImportHtml } from '../utils/import-formatter';
 import {
   buildAttachmentCandidates,
@@ -60,6 +62,7 @@ export class FileImportTaskService {
     @InjectKysely() private readonly db: KyselyDB,
     private readonly importAttachmentService: ImportAttachmentService,
     private readonly userRepo: UserRepo,
+    private readonly workspaceRepo: WorkspaceRepo,
     private eventEmitter: EventEmitter2,
     @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
   ) {}
@@ -168,7 +171,16 @@ export class FileImportTaskService {
       fileTask.creatorId,
       fileTask.workspaceId,
     );
-    const importerCanAuthorHtmlEmbed = canAuthorHtmlEmbed(importingUser?.role);
+    // Toggle-AND-admin gate, resolved ONCE for the whole import: htmlEmbed
+    // survives only when the workspace feature toggle is ON and the importer is
+    // an admin/owner. OFF (default) => stripped for everyone.
+    const htmlEmbedEnabled = isHtmlEmbedFeatureEnabled(
+      (await this.workspaceRepo.findById(fileTask.workspaceId))?.settings,
+    );
+    const importerCanAuthorHtmlEmbed = htmlEmbedAllowed(
+      htmlEmbedEnabled,
+      importingUser?.role,
+    );
 
     const pagesMap = new Map<string, ImportPageNode>();
 

apps/server/src/integrations/import/services/import-html-embed-identity.spec.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
-  canAuthorHtmlEmbed,
   hasHtmlEmbedNode,
+  htmlEmbedAllowed,
   stripHtmlEmbedNodes,
 } from '../../../common/helpers/prosemirror/html-embed.util';
 
@@ -36,39 +36,53 @@ const docWithEmbed = () => ({
 // The real predicate both import entrypoints apply (see the SECURITY blocks in
 // import.service.ts and file-import-task.service.ts): resolve the importer via
 // userRepo.findById, then `!canAuthorHtmlEmbed(role) && hasHtmlEmbedNode(json)`.
-function applyImportGate(json: any, importingUser: { role?: string } | undefined) {
-  if (!canAuthorHtmlEmbed(importingUser?.role) && hasHtmlEmbedNode(json)) {
+function applyImportGate(
+  json: any,
+  featureEnabled: boolean,
+  importingUser: { role?: string } | undefined,
+) {
+  if (
+    !htmlEmbedAllowed(featureEnabled, importingUser?.role) &&
+    hasHtmlEmbedNode(json)
+  ) {
     return stripHtmlEmbedNodes(json);
   }
   return json;
 }
 
-describe('import gate fail-closed by resolved-user role (real helpers)', () => {
-  it('missing user (userRepo.findById -> undefined) strips the embed', () => {
+describe('import gate fail-closed by toggle AND resolved-user role (real helpers)', () => {
+  it('toggle ON + missing user (userRepo.findById -> undefined) strips the embed', () => {
     // findById returns undefined when the user/workspace pair does not resolve;
-    // undefined?.role is undefined -> canAuthorHtmlEmbed(undefined) === false.
-    const importingUser = undefined;
-    const result = applyImportGate(docWithEmbed(), importingUser);
+    // undefined?.role is undefined -> htmlEmbedAllowed(true, undefined) === false.
+    const result = applyImportGate(docWithEmbed(), true, undefined);
     expect(hasHtmlEmbedNode(result)).toBe(false);
   });
 
-  it("resolved role 'member' strips", () => {
+  it("toggle ON + resolved role 'member' strips", () => {
     expect(
-      hasHtmlEmbedNode(applyImportGate(docWithEmbed(), { role: 'member' })),
+      hasHtmlEmbedNode(applyImportGate(docWithEmbed(), true, { role: 'member' })),
     ).toBe(false);
   });
 
-  it("resolved role 'admin' keeps the embed", () => {
+  it("toggle ON + resolved role 'admin' keeps the embed", () => {
     expect(
-      hasHtmlEmbedNode(applyImportGate(docWithEmbed(), { role: 'admin' })),
+      hasHtmlEmbedNode(applyImportGate(docWithEmbed(), true, { role: 'admin' })),
     ).toBe(true);
   });
 
-  it("resolved role 'owner' keeps the embed", () => {
+  it("toggle ON + resolved role 'owner' keeps the embed", () => {
     expect(
-      hasHtmlEmbedNode(applyImportGate(docWithEmbed(), { role: 'owner' })),
+      hasHtmlEmbedNode(applyImportGate(docWithEmbed(), true, { role: 'owner' })),
     ).toBe(true);
   });
+
+  it('toggle OFF strips for every role (admin/owner/member)', () => {
+    for (const role of ['admin', 'owner', 'member'] as const) {
+      expect(
+        hasHtmlEmbedNode(applyImportGate(docWithEmbed(), false, { role })),
+      ).toBe(false);
+    }
+  });
 });
 
 // Source-pin the identity each entrypoint feeds to userRepo.findById. These are
@@ -83,7 +97,11 @@ describe('import gate identity is pinned to the importer (source contract)', ()
     expect(src).toMatch(
       /this\.userRepo\.findById\(\s*userId\s*,\s*workspaceId\s*\)/,
     );
-    expect(src).toMatch(/canAuthorHtmlEmbed\(\s*importingUser\?\.role\s*\)/);
+    expect(src).toMatch(
+      /htmlEmbedAllowed\(\s*htmlEmbedEnabled\s*,\s*importingUser\?\.role\s*\)/,
+    );
+    // And the toggle is resolved from the workspace settings.
+    expect(src).toContain('isHtmlEmbedFeatureEnabled(');
     // And the gate uses the real strip helper.
     expect(src).toContain('stripHtmlEmbedNodes(prosemirrorJson)');
   });
@@ -97,8 +115,9 @@ describe('import gate identity is pinned to the importer (source contract)', ()
       /this\.userRepo\.findById\(\s*fileTask\.creatorId\s*,\s*fileTask\.workspaceId\s*,?\s*\)/,
     );
     expect(src).toMatch(
-      /importerCanAuthorHtmlEmbed\s*=\s*canAuthorHtmlEmbed\(\s*importingUser\?\.role\s*\)/,
+      /importerCanAuthorHtmlEmbed\s*=\s*htmlEmbedAllowed\(\s*htmlEmbedEnabled\s*,\s*importingUser\?\.role\s*,?\s*\)/,
     );
+    expect(src).toContain('isHtmlEmbedFeatureEnabled(');
     expect(src).toContain('stripHtmlEmbedNodes(prosemirrorJson)');
   });
 });

apps/server/src/integrations/import/services/import.service.ts

@@ -2,10 +2,12 @@ import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { UserRepo } from '@docmost/db/repos/user/user.repo';
 import {
-  canAuthorHtmlEmbed,
   hasHtmlEmbedNode,
+  htmlEmbedAllowed,
+  isHtmlEmbedFeatureEnabled,
   stripHtmlEmbedNodes,
 } from '../../../common/helpers/prosemirror/html-embed.util';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 import { MultipartFile } from '@fastify/multipart';
 import * as path from 'path';
 import {
@@ -48,6 +50,7 @@ export class ImportService {
     @InjectKysely() private readonly db: KyselyDB,
     @InjectQueue(QueueName.FILE_TASK_QUEUE)
     private readonly fileTaskQueue: Queue,
+    private readonly workspaceRepo: WorkspaceRepo,
   ) {}
 
   async importPage(
@@ -101,9 +104,15 @@ export class ImportService {
     // imports performed by a non-admin user.
     if (prosemirrorJson && hasHtmlEmbedNode(prosemirrorJson)) {
       const importingUser = await this.userRepo.findById(userId, workspaceId);
-      if (!canAuthorHtmlEmbed(importingUser?.role)) {
+      // Toggle-AND-admin gate: htmlEmbed survives only when the workspace
+      // feature toggle is ON and the importer is an admin/owner. OFF (default)
+      // => stripped for everyone.
+      const htmlEmbedEnabled = isHtmlEmbedFeatureEnabled(
+        (await this.workspaceRepo.findById(workspaceId))?.settings,
+      );
+      if (!htmlEmbedAllowed(htmlEmbedEnabled, importingUser?.role)) {
         this.logger.warn(
-          `Stripping htmlEmbed node(s) from non-admin import by user ${userId}`,
+          `Stripping htmlEmbed node(s) from import by user ${userId}`,
         );
         prosemirrorJson = stripHtmlEmbedNodes(prosemirrorJson);
       }