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/collaboration/collaboration.handler.html-embed.spec.ts

@@ -48,8 +48,18 @@ const docWithEmbed = () => ({
  * TiptapTransformer.toYdoc(<gated json>) and applies it to the doc, so decoding
  * the doc afterward yields exactly the gated content.
  */
-async function gatedContentFor(role: string | null | undefined) {
-  const handler = new CollaborationHandler();
+async function gatedContentFor(
+  role: string | null | undefined,
+  featureEnabled = true,
+) {
+  // Workspace settings read used by the toggle-AND-admin gate.
+  const workspaceRepo = {
+    findById: jest.fn(async () => ({
+      id: 'ws-1',
+      settings: { htmlEmbed: featureEnabled },
+    })),
+  };
+  const handler = new CollaborationHandler(workspaceRepo as any);
   const captureDoc = new Y.Doc();
 
   jest
@@ -70,7 +80,7 @@ async function gatedContentFor(role: string | null | undefined) {
   await handlers.updatePageContent('page-1', {
     prosemirrorJson: docWithEmbed(),
     operation: 'replace',
-    user: { id: 'u1', role } as any,
+    user: { id: 'u1', role, workspaceId: 'ws-1' } as any,
   });
 
   return TiptapTransformer.fromYdoc(captureDoc, 'default');
@@ -92,11 +102,19 @@ describe('CollaborationHandler.updatePageContent htmlEmbed admin gate (real code
     }
   });
 
-  it('admin: htmlEmbed preserved', async () => {
-    expect(hasHtmlEmbedNode(await gatedContentFor('admin'))).toBe(true);
+  it('toggle ON + admin: htmlEmbed preserved', async () => {
+    expect(hasHtmlEmbedNode(await gatedContentFor('admin', true))).toBe(true);
   });
 
-  it('owner: htmlEmbed preserved', async () => {
-    expect(hasHtmlEmbedNode(await gatedContentFor('owner'))).toBe(true);
+  it('toggle ON + owner: htmlEmbed preserved', async () => {
+    expect(hasHtmlEmbedNode(await gatedContentFor('owner', true))).toBe(true);
+  });
+
+  it('toggle OFF + admin: stripped (feature disabled for everyone)', async () => {
+    expect(hasHtmlEmbedNode(await gatedContentFor('admin', false))).toBe(false);
+  });
+
+  it('toggle OFF + member: stripped', async () => {
+    expect(hasHtmlEmbedNode(await gatedContentFor('member', false))).toBe(false);
   });
 });

apps/server/src/collaboration/collaboration.handler.ts

@@ -9,10 +9,12 @@ import { setYjsMark, updateYjsMarkAttribute, YjsSelection } from './yjs.util';
 import * as Y from 'yjs';
 import { User } from '@docmost/db/types/entity.types';
 import {
-  canAuthorHtmlEmbed,
   hasHtmlEmbedNode,
+  htmlEmbedAllowed,
+  isHtmlEmbedFeatureEnabled,
   stripHtmlEmbedNodes,
 } from '../common/helpers/prosemirror/html-embed.util';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 
 export type CollabEventHandlers = ReturnType<
   CollaborationHandler['getHandlers']
@@ -22,7 +24,7 @@ export type CollabEventHandlers = ReturnType<
 export class CollaborationHandler {
   private readonly logger = new Logger(CollaborationHandler.name);
 
-  constructor() {}
+  constructor(private readonly workspaceRepo: WorkspaceRepo) {}
 
   getHandlers(hocuspocus: Hocuspocus) {
     return {
@@ -98,10 +100,16 @@ export class CollaborationHandler {
         // arbitrary JS in every reader's browser, so a NON-admin caller must not
         // be able to persist them here. If the editing user is not a workspace
         // admin/owner, strip every htmlEmbed node before it reaches the ydoc.
-        if (!canAuthorHtmlEmbed(user?.role)) {
+        // Toggle-AND-admin gate: htmlEmbed survives only when the workspace
+        // feature toggle is ON and the editing user is an admin/owner. OFF
+        // (default) => stripped for everyone.
+        const htmlEmbedEnabled = isHtmlEmbedFeatureEnabled(
+          (await this.workspaceRepo.findById(user?.workspaceId))?.settings,
+        );
+        if (!htmlEmbedAllowed(htmlEmbedEnabled, user?.role)) {
           if (hasHtmlEmbedNode(prosemirrorJson)) {
             this.logger.warn(
-              `Stripping htmlEmbed node(s) from non-admin update by user ${user?.id} on ${documentName}`,
+              `Stripping htmlEmbed node(s) from update by user ${user?.id} on ${documentName}`,
             );
             prosemirrorJson = stripHtmlEmbedNodes(prosemirrorJson);
           }

apps/server/src/collaboration/extensions/persistence.extension.html-embed.spec.ts

@@ -121,7 +121,7 @@ function nodeTypeCounts(json: any): Record<string, number> {
  * onStoreDocument to reach the strip + persist branch, and capture the content
  * that would be written to the page row.
  */
-function buildExtension() {
+function buildExtension(featureEnabled = true) {
   const captured: { content?: any } = {};
 
   const existingPage = {
@@ -159,6 +159,14 @@ function buildExtension() {
     syncPageReferences: jest.fn(async () => undefined),
   } as any;
 
+  // Workspace settings read used by the toggle-AND-admin gate.
+  const workspaceRepo = {
+    findById: jest.fn(async () => ({
+      id: 'ws-1',
+      settings: { htmlEmbed: featureEnabled },
+    })),
+  };
+
   const ext = new PersistenceExtension(
     pageRepo as any,
     pageHistoryRepo as any,
@@ -168,13 +176,18 @@ function buildExtension() {
     noopQueue,
     collabHistory,
     transclusionService,
+    workspaceRepo as any,
   );
 
   return { ext, captured, pageRepo };
 }
 
-async function runStore(role: string | null | undefined, doc: Y.Doc) {
-  const { ext, captured } = buildExtension();
+async function runStore(
+  role: string | null | undefined,
+  doc: Y.Doc,
+  featureEnabled = true,
+) {
+  const { ext, captured } = buildExtension(featureEnabled);
   // hocuspocus augments the Y.Doc with broadcastStateless; a bare Y.Doc has
   // none, so stub it (the post-persist broadcast is not under test here).
   (doc as any).broadcastStateless = () => undefined;
@@ -216,18 +229,33 @@ describe('PersistenceExtension.onStoreDocument htmlEmbed admin gate (real code)'
     expect(hasHtmlEmbedNode(reDecoded)).toBe(false);
   });
 
-  it('admin store: htmlEmbed preserved in persisted content', async () => {
-    const captured = await runStore('admin', buildYdoc(RICH_DOC));
+  it('toggle ON + admin store: htmlEmbed preserved in persisted content', async () => {
+    const captured = await runStore('admin', buildYdoc(RICH_DOC), true);
     expect(captured.content).toBeDefined();
     expect(hasHtmlEmbedNode(captured.content)).toBe(true);
     expect(nodeTypeCounts(captured.content)[HTML_EMBED_NODE_NAME]).toBe(2);
   });
 
-  it('owner store: htmlEmbed preserved', async () => {
-    const captured = await runStore('owner', buildYdoc(RICH_DOC));
+  it('toggle ON + owner store: htmlEmbed preserved', async () => {
+    const captured = await runStore('owner', buildYdoc(RICH_DOC), true);
     expect(hasHtmlEmbedNode(captured.content)).toBe(true);
   });
 
+  it('toggle OFF + admin store: stripped (feature disabled for everyone)', async () => {
+    const captured = await runStore('admin', buildYdoc(RICH_DOC), false);
+    expect(hasHtmlEmbedNode(captured.content)).toBe(false);
+  });
+
+  it('toggle OFF + owner store: stripped', async () => {
+    const captured = await runStore('owner', buildYdoc(RICH_DOC), false);
+    expect(hasHtmlEmbedNode(captured.content)).toBe(false);
+  });
+
+  it('toggle OFF + member store: stripped', async () => {
+    const captured = await runStore('member', buildYdoc(RICH_DOC), false);
+    expect(hasHtmlEmbedNode(captured.content)).toBe(false);
+  });
+
   it('unknown/empty role: fails closed (stripped)', async () => {
     expect(
       hasHtmlEmbedNode((await runStore(undefined, buildYdoc(RICH_DOC))).content),

apps/server/src/collaboration/extensions/persistence.extension.ts

@@ -40,10 +40,12 @@ import {
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
 import {
-  canAuthorHtmlEmbed,
   hasHtmlEmbedNode,
+  htmlEmbedAllowed,
+  isHtmlEmbedFeatureEnabled,
   stripHtmlEmbedNodes,
 } from '../../common/helpers/prosemirror/html-embed.util';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
 
 @Injectable()
 export class PersistenceExtension implements Extension {
@@ -64,6 +66,7 @@ export class PersistenceExtension implements Extension {
     @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
     private readonly collabHistory: CollabHistoryService,
     private readonly transclusionService: TransclusionService,
+    private readonly workspaceRepo: WorkspaceRepo,
   ) {}
 
   async onLoadDocument(data: onLoadDocumentPayload) {
@@ -146,10 +149,16 @@ export class PersistenceExtension implements Extension {
     // page-editor), and the PERSISTED page row plus every share/readonly read
     // path are protected by this strip. The window is therefore accepted rather
     // than mitigated with an inbound beforeBroadcast strip.
-    if (!canAuthorHtmlEmbed(context?.user?.role)) {
+    // Toggle-AND-admin gate: htmlEmbed survives only when the workspace feature
+    // toggle is ON and the storing user is an admin/owner. OFF (default) =>
+    // stripped for everyone (existing embeds get cleaned up on next save).
+    const htmlEmbedEnabled = isHtmlEmbedFeatureEnabled(
+      (await this.workspaceRepo.findById(context?.user?.workspaceId))?.settings,
+    );
+    if (!htmlEmbedAllowed(htmlEmbedEnabled, context?.user?.role)) {
       if (hasHtmlEmbedNode(tiptapJson)) {
         this.logger.warn(
-          `Stripping htmlEmbed node(s) from non-admin collab store by user ${context?.user?.id} on ${documentName}`,
+          `Stripping htmlEmbed node(s) from collab store by user ${context?.user?.id} on ${documentName}`,
         );
         tiptapJson = stripHtmlEmbedNodes(tiptapJson);
         // Reflect the stripped content back into the shared ydoc so the node is