feat: add denylist CRUD endpoints with moderator authorization (#114)

* feat: add denylist table, migrations, and CRUD endpoints with moderator authorization

- Migration 1745846400000_denylist.ts: new denylist table with entity_id (PK),
  reason, created_by, created_at, updated_at audit columns and case-insensitive indexes
- Extends IDbComponent with getDenylist / addDenylistEntry / removeDenylistEntry
- Extends IRefreshableFeaturesComponent with getUserModerators() polling
  dapps-platform_user_moderators feature flag (same pattern as malicious-profiles)
- GET /denylist: public endpoint returning all blocked entity IDs
- POST /denylist/:entityId: signed-fetch + moderator-only, upserts an entry
- DELETE /denylist/:entityId: signed-fetch + moderator-only, removes an entry
- Unit and integration tests covering all paths including 403 for non-moderators

* fix: address PR feedback on denylist feature

- Wrap long line in refreshable-features/component.ts (prettier)
- Preserve original created_by on upsert conflict
- Remove redundant LOWER(entity_id) index (data already stored lowercase)

* docs: add denylist endpoints to OpenAPI spec

* feat: filter denylisted entities from POST /entities/active (#115)

* feat: filter denylisted entities from POST /entities/active

Mirrors the catalyst behavior by excluding denylisted entities at the
SQL level using a NOT EXISTS subquery against the denylist table, avoiding
a separate round-trip to fetch the full denylist.

* fix: drop redundant LOWER on denylist side and fix flaky ordering test

- Use denylist.entity_id = LOWER(registries.id) instead of comparing
  both sides with LOWER(), since addDenylistEntry already stores entity_id
  in lowercase — allows PostgreSQL to use the PK index on entity_id
- Make "should return multiple entities" order-independent with
  arrayContaining since getSortedRegistriesByPointers has no guaranteed
  ordering when sortOrder is not set

Author: kevinszuchet

docs/openapi.yaml

@@ -55,6 +55,8 @@ tags:
     description: Processing queue status and monitoring
   - name: Admin
     description: Administrative endpoints (requires bearer token authentication)
+  - name: Denylist
+    description: Denylist management endpoints — block specific entity IDs from being served
 paths:
   /status:
     get:
@@ -374,6 +376,129 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /denylist:
+    get:
+      tags:
+        - Denylist
+      summary: Get all denylist entries
+      description: |
+        Returns all entity IDs currently in the denylist. This endpoint is public and requires no authentication.
+      operationId: getDenylist
+      security: []
+      responses:
+        '200':
+          description: List of denylist entries
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/DenylistEntry'
+  /denylist/{entityId}:
+    post:
+      tags:
+        - Denylist
+      summary: Add or update a denylist entry
+      description: |
+        Adds an entity ID to the denylist or updates an existing entry. Requires a valid signed fetch
+        from an address listed in the `dapps-platform_user_moderators` feature flag.
+
+        If the entity is already in the denylist, its `reason` and `updated_at` fields are updated
+        but `created_by` is preserved from the original entry.
+      operationId: addDenylistEntry
+      security:
+        - SignedFetch: []
+      parameters:
+        - name: entityId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Entity ID (e.g. a Catalyst CID) to add to the denylist
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+                  nullable: true
+                  description: Optional human-readable reason for denylisting this entity
+      responses:
+        '201':
+          description: Entry created or updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DenylistEntry'
+        '400':
+          description: Bad request — entity ID is missing
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationResult'
+        '401':
+          description: Unauthorized — invalid or missing signed fetch
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: Forbidden — signer is not an authorized moderator
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationResult'
+    delete:
+      tags:
+        - Denylist
+      summary: Remove a denylist entry
+      description: |
+        Removes an entity ID from the denylist. Requires a valid signed fetch from an address
+        listed in the `dapps-platform_user_moderators` feature flag.
+      operationId: removeDenylistEntry
+      security:
+        - SignedFetch: []
+      parameters:
+        - name: entityId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Entity ID to remove from the denylist
+      responses:
+        '200':
+          description: Entry successfully removed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationResult'
+        '400':
+          description: Bad request — entity ID is missing
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationResult'
+        '401':
+          description: Unauthorized — invalid or missing signed fetch
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: Forbidden — signer is not an authorized moderator
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationResult'
+        '404':
+          description: Entity ID not found in the denylist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OperationResult'
   /flush-cache:
     delete:
       tags:
@@ -796,6 +921,43 @@ components:
       required:
         - ok
         - message
+    DenylistEntry:
+      type: object
+      description: A single entry in the denylist, representing a blocked entity
+      properties:
+        entity_id:
+          type: string
+          description: Lowercase entity ID (Catalyst CID) that is blocked
+        reason:
+          type: string
+          nullable: true
+          description: Optional human-readable reason why this entity was denylisted
+        created_by:
+          type: string
+          description: Lowercase Ethereum address of the moderator who first added the entry
+        created_at:
+          type: number
+          description: Unix timestamp in milliseconds when the entry was created
+        updated_at:
+          type: number
+          description: Unix timestamp in milliseconds when the entry was last updated
+      required:
+        - entity_id
+        - created_by
+        - created_at
+        - updated_at
+    OperationResult:
+      type: object
+      description: Generic result for mutating operations
+      properties:
+        ok:
+          type: boolean
+          description: Whether the operation succeeded
+        message:
+          type: string
+          description: Optional human-readable message
+      required:
+        - ok
     Error:
       type: object
       properties:

src/adapters/db.ts

@@ -1,6 +1,7 @@
 import SQL, { SQLStatement } from 'sql-template-strings'
 import {
   AppComponents,
+  Denylist,
   IDbComponent,
   Registry,
   SetSpawnCoordinateResult,
@@ -61,7 +62,7 @@ export function createDbAdapter({ pg }: Pick<AppComponents, 'pg'>): IDbComponent
     pointers: string[],
     options?: GetSortedRegistriesByPointersOptions
   ): Promise<Registry.DbEntity[]> {
-    const { statuses, sortOrder, worldName } = options ?? {}
+    const { statuses, sortOrder, worldName, excludeDenylisted } = options ?? {}
     const order = sortOrder === SortOrder.DESC ? 'DESC' : 'ASC'
     const lowerCasePointers = pointers.map((p) => p.toLowerCase())
 
@@ -100,6 +101,14 @@ export function createDbAdapter({ pg }: Pick<AppComponents, 'pg'>): IDbComponent
       `)
     }
 
+    if (excludeDenylisted) {
+      query.append(SQL`
+        AND NOT EXISTS (
+          SELECT 1 FROM denylist WHERE denylist.entity_id = LOWER(registries.id)
+        )
+      `)
+    }
+
     if (sortOrder) {
       query.append(`ORDER BY timestamp ${order}`)
     }
@@ -1434,6 +1443,43 @@ export function createDbAdapter({ pg }: Pick<AppComponents, 'pg'>): IDbComponent
     })
   }
 
+  async function getDenylist(): Promise<Denylist.DbEntity[]> {
+    const query: SQLStatement = SQL`
+      SELECT entity_id, reason, created_by, created_at, updated_at
+      FROM denylist
+      ORDER BY created_at DESC
+    `
+    const result = await pg.query<Denylist.DbEntity>(query)
+    return result.rows
+  }
+
+  async function addDenylistEntry(
+    entityId: string,
+    createdBy: string,
+    reason?: string | null
+  ): Promise<Denylist.DbEntity> {
+    const now = Date.now()
+    const query: SQLStatement = SQL`
+      INSERT INTO denylist (entity_id, reason, created_by, created_at, updated_at)
+      VALUES (${entityId.toLowerCase()}, ${reason ?? null}, ${createdBy.toLowerCase()}, ${now}, ${now})
+      ON CONFLICT (entity_id) DO UPDATE
+        SET reason = EXCLUDED.reason,
+            updated_at = EXCLUDED.updated_at
+      RETURNING entity_id, reason, created_by, created_at, updated_at
+    `
+    const result = await pg.query<Denylist.DbEntity>(query)
+    return result.rows[0]
+  }
+
+  async function removeDenylistEntry(entityId: string): Promise<boolean> {
+    const query: SQLStatement = SQL`
+      DELETE FROM denylist
+      WHERE LOWER(entity_id) = ${entityId.toLowerCase()}
+    `
+    const result = await pg.query(query)
+    return (result.rowCount ?? 0) > 0
+  }
+
   return {
     insertRegistry,
     updateRegistriesStatus,
@@ -1471,6 +1517,9 @@ export function createDbAdapter({ pg }: Pick<AppComponents, 'pg'>): IDbComponent
     recalculateSpawnCoordinate,
     undeployWorldScenes,
     undeployWorldByName,
-    persistRegistryInTransaction
+    persistRegistryInTransaction,
+    getDenylist,
+    addDenylistEntry,
+    removeDenylistEntry
   }
 }

src/controllers/handlers/delete-denylist-entry.ts

@@ -0,0 +1,44 @@
+import { DecentralandSignatureContext } from '@dcl/platform-crypto-middleware'
+import { HandlerContextWithPath } from '../../types'
+
+export async function deleteDenylistEntryHandler(
+  context: HandlerContextWithPath<'db' | 'refreshableFeatures', '/denylist/:entityId'> &
+    DecentralandSignatureContext<any>
+) {
+  const {
+    components: { db, refreshableFeatures },
+    params,
+    verification
+  } = context
+
+  const { entityId } = params
+  if (!entityId) {
+    return {
+      status: 400,
+      body: { ok: false, message: 'Entity ID is required' }
+    }
+  }
+
+  const signerAddress = verification!.auth.toLowerCase()
+  const moderators = await refreshableFeatures.getUserModerators()
+
+  if (!moderators || !moderators.includes(signerAddress)) {
+    return {
+      status: 403,
+      body: { ok: false, message: 'Forbidden: signer is not an authorized moderator' }
+    }
+  }
+
+  const deleted = await db.removeDenylistEntry(entityId)
+  if (!deleted) {
+    return {
+      status: 404,
+      body: { ok: false, message: 'Entity ID not found in denylist' }
+    }
+  }
+
+  return {
+    status: 200,
+    body: { ok: true }
+  }
+}

src/controllers/handlers/get-active-entities.ts

@@ -27,7 +27,8 @@ export async function getActiveEntityHandler(context: HandlerContextWithPath<'db
 
   const entities = await db.getSortedRegistriesByPointers(pointers, {
     statuses: [Registry.Status.COMPLETE, Registry.Status.FALLBACK],
-    worldName
+    worldName,
+    excludeDenylisted: true
   })
 
   if (entities.length === 0) {

src/controllers/handlers/get-denylist.ts

@@ -0,0 +1,13 @@
+import { HandlerContextWithPath } from '../../types'
+
+export async function getDenylistHandler(context: HandlerContextWithPath<'db', '/denylist'>) {
+  const {
+    components: { db }
+  } = context
+
+  const entries = await db.getDenylist()
+
+  return {
+    body: entries
+  }
+}

src/controllers/handlers/post-denylist-entry.ts

@@ -0,0 +1,41 @@
+import { DecentralandSignatureContext } from '@dcl/platform-crypto-middleware'
+import { HandlerContextWithPath } from '../../types'
+
+export async function postDenylistEntryHandler(
+  context: HandlerContextWithPath<'db' | 'refreshableFeatures', '/denylist/:entityId'> &
+    DecentralandSignatureContext<any>
+) {
+  const {
+    components: { db, refreshableFeatures },
+    params,
+    verification
+  } = context
+
+  const { entityId } = params
+  if (!entityId) {
+    return {
+      status: 400,
+      body: { ok: false, message: 'Entity ID is required' }
+    }
+  }
+
+  const signerAddress = verification!.auth.toLowerCase()
+  const moderators = await refreshableFeatures.getUserModerators()
+
+  if (!moderators || !moderators.includes(signerAddress)) {
+    return {
+      status: 403,
+      body: { ok: false, message: 'Forbidden: signer is not an authorized moderator' }
+    }
+  }
+
+  const body = await context.request.json().catch(() => ({}))
+  const reason: string | null = body?.reason ?? null
+
+  const entry = await db.addDenylistEntry(entityId, signerAddress, reason)
+
+  return {
+    status: 201,
+    body: entry
+  }
+}