feat: filter _design docs from all replication (#215)

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Abhinegi2 <negiabhishek253@gmail.com>

Author: 3 people

.env.template

@@ -10,6 +10,10 @@ JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n<PUBLIC_KEY>\n-----END PUBLIC KEY---
 # secret to create JWT tokens. They are used in the JWT auth which works similar to CouchDB's `POST /_session` endpoint. This should be changed to prevent others to create fake JWT tokens.
 JWT_SECRET=someJwtSecret
 
+# (optional) comma-separated list of document ID prefixes to exclude from replication.
+# Defaults to "_design/" if unset. Override to filter additional doc types.
+# REPLICATION_IGNORED_PREFIXES=_design/
+
 # (optional) the [Sentry DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). If defined, error messages are sent to the sentry.io application monitoring & logging service.
 SENTRY_DSN=
 SENTRY_ENABLED=true

src/restricted-endpoints/replication/bulk-document/bulk-document.service.spec.ts

@@ -1,16 +1,18 @@
+import { ConfigService } from '@nestjs/config';
 import { Test, TestingModule } from '@nestjs/testing';
+import { of } from 'rxjs';
+import { CouchdbService } from '../../../couchdb/couchdb.service';
+import { PermissionService } from '../../../permissions/permission/permission.service';
+import { RulesService } from '../../../permissions/rules/rules.service';
+import { UserInfo } from '../../session/user-auth.dto';
+import { DocumentFilterService } from '../document-filter/document-filter.service';
 import { BulkDocumentService } from './bulk-document.service';
-import { BulkGetResponse } from './couchdb-dtos/bulk-get.dto';
 import { AllDocsResponse } from './couchdb-dtos/all-docs.dto';
 import {
   BulkDocsRequest,
   DatabaseDocument,
 } from './couchdb-dtos/bulk-docs.dto';
-import { UserInfo } from '../../session/user-auth.dto';
-import { PermissionService } from '../../../permissions/permission/permission.service';
-import { RulesService } from '../../../permissions/rules/rules.service';
-import { of } from 'rxjs';
-import { CouchdbService } from '../../../couchdb/couchdb.service';
+import { BulkGetResponse } from './couchdb-dtos/bulk-get.dto';
 
 describe('BulkDocumentService', () => {
   let service: BulkDocumentService;
@@ -38,6 +40,8 @@ describe('BulkDocumentService', () => {
       providers: [
         BulkDocumentService,
         PermissionService,
+        DocumentFilterService,
+        { provide: ConfigService, useValue: { get: () => undefined } },
         { provide: RulesService, useValue: mockRulesService },
         { provide: CouchdbService, useValue: mockCouchDBService },
       ],
@@ -207,6 +211,71 @@ describe('BulkDocumentService', () => {
     });
   });
 
+  it('should filter out _design/ docs in BulkGet', () => {
+    const designDoc: DatabaseDocument = {
+      _id: '_design/some-view',
+      _rev: 'rev1',
+    };
+    const bulkGetResponse = createBulkGetResponse(schoolDoc, designDoc);
+    jest
+      .spyOn(mockRulesService, 'getRulesForUser')
+      .mockReturnValue([{ action: 'manage', subject: 'all' }]);
+
+    const result = service.filterBulkGetResponse(bulkGetResponse, normalUser);
+
+    expect(result.results.map((r) => r.id)).toEqual([schoolDoc._id]);
+  });
+
+  it('should filter out _design/ docs in AllDocs', () => {
+    const designDoc: DatabaseDocument = {
+      _id: '_design/conflicts',
+      _rev: 'rev1',
+    };
+    const allDocsResponse = createAllDocsResponse(schoolDoc, designDoc);
+    jest
+      .spyOn(mockRulesService, 'getRulesForUser')
+      .mockReturnValue([{ action: 'manage', subject: 'all' }]);
+
+    const result = service.filterAllDocsResponse(allDocsResponse, normalUser);
+
+    expect(result.rows.map((r) => r.id)).toEqual([schoolDoc._id]);
+  });
+
+  it('should filter out _design/ docs in BulkDocs writes', async () => {
+    const designDoc: DatabaseDocument = {
+      _id: '_design/search_index',
+      _rev: 'rev1',
+    };
+    const request: BulkDocsRequest = {
+      new_edits: false,
+      docs: [childDoc, designDoc],
+    };
+    jest
+      .spyOn(mockCouchDBService, 'post')
+      .mockReturnValue(of(createAllDocsResponse(childDoc)));
+
+    const result = await service.filterBulkDocsRequest(request, normalUser, '');
+
+    expect(result.docs.map((d) => d._id)).toEqual([childDoc._id]);
+  });
+
+  it('should filter out _design/ docs in Find responses', () => {
+    const designDoc: DatabaseDocument = {
+      _id: '_design/some-index',
+      _rev: 'rev1',
+    };
+    jest
+      .spyOn(mockRulesService, 'getRulesForUser')
+      .mockReturnValue([{ action: 'manage', subject: 'all' }]);
+
+    const result = service.filterFindResponse(
+      { docs: [getSchoolDoc(), designDoc], bookmark: '' },
+      normalUser,
+    );
+
+    expect(result.docs.map((d) => d._id)).toEqual([schoolDoc._id]);
+  });
+
   function getSchoolDoc(): DatabaseDocument {
     return {
       _id: 'School:1',

src/restricted-endpoints/replication/bulk-document/bulk-document.service.ts

@@ -19,6 +19,7 @@ import {
 import { firstValueFrom } from 'rxjs';
 import { Ability } from '@casl/ability';
 import { CouchdbService } from '../../../couchdb/couchdb.service';
+import { DocumentFilterService } from '../document-filter/document-filter.service';
 
 /**
  * Handle bulk document requests with the remote CouchDB server
@@ -29,19 +30,22 @@ export class BulkDocumentService {
   constructor(
     private permissionService: PermissionService,
     private couchdbService: CouchdbService,
+    private documentFilter: DocumentFilterService,
   ) {}
 
   filterBulkGetResponse(
     response: BulkGetResponse,
     user: UserInfo,
   ): BulkGetResponse {
     const ability = this.permissionService.getAbilityFor(user);
-    const withPermissions: BulkGetResult[] = response.results.map((result) => ({
-      id: result.id,
-      docs: result.docs.filter((doc) =>
-        this.isPermittedBulkGetDoc(doc, ability),
-      ),
-    }));
+    const withPermissions: BulkGetResult[] = response.results
+      .filter((result) => this.documentFilter.isReplicable(result.id))
+      .map((result) => ({
+        id: result.id,
+        docs: result.docs.filter((doc) =>
+          this.isPermittedBulkGetDoc(doc, ability),
+        ),
+      }));
     // Only return results where at least one document is left
     return {
       results: withPermissions.filter((result) => result.docs.length > 0),
@@ -66,8 +70,10 @@ export class BulkDocumentService {
     return {
       total_rows: response.total_rows,
       offset: response.offset,
-      rows: response.rows.filter((row) =>
-        row.doc ? row.doc._deleted || ability.can('read', row.doc) : true,
+      rows: response.rows.filter(
+        (row) =>
+          this.documentFilter.isReplicable(row.id) &&
+          (row.doc ? row.doc._deleted || ability.can('read', row.doc) : true),
       ),
     };
   }
@@ -93,12 +99,15 @@ export class BulkDocumentService {
     );
     return {
       new_edits: request.new_edits,
-      docs: request.docs.filter((doc) =>
-        this.hasPermissionsForDoc(
-          doc,
-          response.rows.find((responseDoc) => responseDoc.id === doc._id)?.doc,
-          ability,
-        ),
+      docs: request.docs.filter(
+        (doc) =>
+          this.documentFilter.isReplicable(doc._id) &&
+          this.hasPermissionsForDoc(
+            doc,
+            response.rows.find((responseDoc) => responseDoc.id === doc._id)
+              ?.doc,
+            ability,
+          ),
       ),
     };
   }
@@ -108,7 +117,11 @@ export class BulkDocumentService {
     return {
       bookmark: request.bookmark,
       warning: request.warning,
-      docs: request.docs.filter((doc) => ability.can('read', doc)),
+      docs: request.docs.filter(
+        (doc) =>
+          this.documentFilter.isReplicable(doc._id) &&
+          ability.can('read', doc),
+      ),
     };
   }
 

src/restricted-endpoints/replication/changes/changes.controller.spec.ts

@@ -11,6 +11,8 @@ import {
   ChangesResponse,
 } from '../bulk-document/couchdb-dtos/changes.dto';
 import { ChangesController } from './changes.controller';
+import { DocumentFilterService } from '../document-filter/document-filter.service';
+import { ConfigService } from '@nestjs/config';
 
 describe('ChangesController', () => {
   let controller: ChangesController;
@@ -50,6 +52,8 @@ describe('ChangesController', () => {
         { provide: CouchdbService, useValue: mockCouchdbService },
         { provide: RulesService, useValue: mockRulesService },
         PermissionService,
+        DocumentFilterService,
+        { provide: ConfigService, useValue: { get: () => undefined } },
       ],
     }).compile();
 
@@ -328,6 +332,20 @@ describe('ChangesController', () => {
     expect(res.results).toEqual([docToChange(deletedWithoutProps)]);
   });
 
+  it('should silently skip _design/ documents without adding them to results or lostPermissions', async () => {
+    const designDoc: DatabaseDocument = { _id: '_design/some-view' };
+    getRulesSpy.mockReturnValue([{ subject: 'all', action: 'manage' }]);
+    getSpy.mockReturnValue(createChanges([schoolDoc, designDoc, childDoc]));
+
+    const res = await controller.changes('some-db', user);
+
+    expect(res.results.map((r) => r.id)).toEqual([
+      schoolDoc._id,
+      childDoc._id,
+    ]);
+    expect(res.lostPermissions).toEqual([]);
+  });
+
   function createChanges(
     docs: DatabaseDocument[],
     pending = 0,

src/restricted-endpoints/replication/changes/changes.controller.ts

@@ -14,13 +14,15 @@ import {
   ChangesParams,
   ChangesResponse,
 } from '../bulk-document/couchdb-dtos/changes.dto';
+import { DocumentFilterService } from '../document-filter/document-filter.service';
 
 @UseGuards(CombinedAuthGuard)
 @Controller()
 export class ChangesController {
   constructor(
     private couchdbService: CouchdbService,
     private permissionService: PermissionService,
+    private documentFilter: DocumentFilterService,
   ) {}
 
   /**
@@ -98,6 +100,12 @@ export class ChangesController {
 
     for (let i = 0; i < changes.results.length; i++) {
       const change = changes.results[i];
+
+      if (!this.documentFilter.isReplicable(change.id)) {
+        lastProcessedSeq = change.seq;
+        continue;
+      }
+
       const { doc } = change;
 
       const isPermitted = !doc

src/restricted-endpoints/replication/document-filter/document-filter.service.spec.ts

@@ -0,0 +1,58 @@
+import { ConfigService } from '@nestjs/config';
+import { DocumentFilterService } from './document-filter.service';
+
+describe('DocumentFilterService', () => {
+  function createService(envValue?: string): DocumentFilterService {
+    const configService = {
+      get: jest.fn().mockReturnValue(envValue),
+    } as any as ConfigService;
+    return new DocumentFilterService(configService);
+  }
+
+  describe('default configuration', () => {
+    let service: DocumentFilterService;
+
+    beforeEach(() => {
+      service = createService(undefined);
+    });
+
+    it('should filter _design/ documents', () => {
+      expect(service.isReplicable('_design/some-view')).toBe(false);
+      expect(service.isReplicable('_design/conflicts')).toBe(false);
+    });
+
+    it('should allow regular entity documents', () => {
+      expect(service.isReplicable('Child:abc123')).toBe(true);
+      expect(service.isReplicable('School:1')).toBe(true);
+    });
+
+    it('should allow documents whose ID contains but does not start with _design/', () => {
+      expect(service.isReplicable('Note:_design/test')).toBe(true);
+    });
+  });
+
+  describe('custom configuration', () => {
+    it('should use prefixes from environment variable', () => {
+      const service = createService('_design/, test-');
+
+      expect(service.isReplicable('_design/foo')).toBe(false);
+      expect(service.isReplicable('test-doc')).toBe(false);
+      expect(service.isReplicable('Child:1')).toBe(true);
+    });
+
+    it('should handle a single custom prefix', () => {
+      const service = createService('custom_prefix:');
+
+      expect(service.isReplicable('custom_prefix:doc')).toBe(false);
+      expect(service.isReplicable('_design/foo')).toBe(true);
+    });
+
+    it('should ignore empty entries in comma-separated list', () => {
+      const service = createService('_design/,,, _local/');
+
+      expect(service.isReplicable('_design/x')).toBe(false);
+      expect(service.isReplicable('_local/y')).toBe(false);
+      expect(service.isReplicable('Child:1')).toBe(true);
+    });
+  });
+});

src/restricted-endpoints/replication/document-filter/document-filter.service.ts

@@ -0,0 +1,38 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+/**
+ * Filters documents that should not be replicated to/from clients.
+ *
+ * By default, documents whose IDs start with `_design/` are excluded.
+ * This can be overridden via the `REPLICATION_IGNORED_PREFIXES` environment
+ * variable (comma-separated list of prefixes). If set to an empty string,
+ * filtering is disabled.
+ */
+@Injectable()
+export class DocumentFilterService {
+  private static readonly DEFAULT_IGNORED_PREFIXES = ['_design/'];
+
+  private readonly ignoredPrefixes: string[];
+
+  constructor(configService: ConfigService) {
+    const envValue = configService.get<string | undefined>(
+      'REPLICATION_IGNORED_PREFIXES',
+    );
+    this.ignoredPrefixes =
+      envValue === undefined
+        ? DocumentFilterService.DEFAULT_IGNORED_PREFIXES
+        : envValue
+            .split(',')
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0);
+  }
+
+  /**
+   * Whether the given document ID is eligible for replication.
+   * Returns `false` for IDs that match any ignored prefix.
+   */
+  isReplicable(docId: string): boolean {
+    return !this.ignoredPrefixes.some((prefix) => docId.startsWith(prefix));
+  }
+}

src/restricted-endpoints/replication/replication.module.ts

@@ -6,6 +6,7 @@ import { PermissionModule } from '../../permissions/permission.module';
 import { AuthModule } from '../../auth/auth.module';
 import { BulkDocEndpointsController } from './bulk-document/bulk-doc-endpoints.controller';
 import { ChangesController } from './changes/changes.controller';
+import { DocumentFilterService } from './document-filter/document-filter.service';
 
 @Module({
   imports: [HttpModule, PermissionModule, AuthModule],
@@ -14,6 +15,6 @@ import { ChangesController } from './changes/changes.controller';
     InfoEndpointsController,
     BulkDocEndpointsController,
   ],
-  providers: [BulkDocumentService],
+  providers: [BulkDocumentService, DocumentFilterService],
 })
 export class ReplicationModule {}