[196] Add reported NCMEC media to a hash bank

CHANGELOG.md

@@ -10,6 +10,7 @@ For more information about each release including git tags and artifacts, see [R
 
 ### Added
 
+- Setting to add media from accepted NCMEC reports to a hash bank ([#1208](https://github.com/roostorg/coop/pull/1208) by [@maarkN](https://github.com/maarkN), closes [#196](https://github.com/roostorg/coop/issues/196))
 - Optional policy and audit callbacks with bounded deadlines for review and item content responses ([#1270](https://github.com/roostorg/coop/pull/1270) by [@sunilatlas](https://github.com/sunilatlas), closes [#1269](https://github.com/roostorg/coop/issues/1269))
 - Native OpenTelemetry manual-review counters, decision-source labels and elapsed timings ([#1286](https://github.com/roostorg/coop/pull/1286) by [@sunilatlas](https://github.com/sunilatlas), relates to [#1287](https://github.com/roostorg/coop/issues/1287))
 

client/src/webpages/settings/NCMECSettings.tsx

@@ -48,6 +48,11 @@ gql`
       contactPersonPhone
       mediaReviewRequirement
       minMediaToReview
+      reportedMediaHashBankId
+    }
+    hashBanks {
+      id
+      name
     }
     myOrg {
       hasNCMECReportingEnabled
@@ -83,6 +88,7 @@ type NcmecSettings = {
   contactPersonPhone: string;
   mediaReviewRequirement: GQLNcmecMediaReviewRequirement;
   minMediaToReview: string;
+  reportedMediaHashBankId: string;
 };
 
 export default function NCMECSettings() {
@@ -104,6 +110,7 @@ export default function NCMECSettings() {
     contactPersonPhone: '',
     mediaReviewRequirement: GQLNcmecMediaReviewRequirement.All,
     minMediaToReview: '1',
+    reportedMediaHashBankId: '',
   });
 
   const { loading, error, data } = useGQLNcmecOrgSettingsQuery({
@@ -149,6 +156,8 @@ export default function NCMECSettings() {
           data.ncmecOrgSettings.mediaReviewRequirement ??
           GQLNcmecMediaReviewRequirement.All,
         minMediaToReview: String(data.ncmecOrgSettings.minMediaToReview ?? 1),
+        reportedMediaHashBankId:
+          data.ncmecOrgSettings.reportedMediaHashBankId?.toString() ?? '',
       });
     }
   }, [data?.ncmecOrgSettings]);
@@ -237,6 +246,9 @@ export default function NCMECSettings() {
           contactPersonPhone: settings.contactPersonPhone || null,
           mediaReviewRequirement: settings.mediaReviewRequirement,
           minMediaToReview: isMinimumPolicy ? parsedMinMedia : null,
+          reportedMediaHashBankId: settings.reportedMediaHashBankId
+            ? Number(settings.reportedMediaHashBankId)
+            : null,
         },
       },
     });
@@ -573,6 +585,43 @@ export default function NCMECSettings() {
             </Text>
           </div>
 
+          <div className="flex flex-col gap-2">
+            <Label
+              htmlFor="reportedMediaHashBankId"
+              className="text-sm font-medium"
+            >
+              Hash bank for reported media
+            </Label>
+            <Select
+              value={settings.reportedMediaHashBankId || '__none__'}
+              onValueChange={(value) =>
+                setSettings({
+                  ...settings,
+                  reportedMediaHashBankId: value === '__none__' ? '' : value,
+                })
+              }
+            >
+              <SelectTrigger id="reportedMediaHashBankId">
+                <SelectValue placeholder="Don't add reported media to a bank" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="__none__">
+                  Don&apos;t add reported media to a bank
+                </SelectItem>
+                {(data?.hashBanks ?? []).map((bank) => (
+                  <SelectItem key={bank.id} value={bank.id}>
+                    {bank.name}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <Text size="XS" className="text-gray-500">
+              Media from each report accepted by NCMEC is added to this bank so
+              it can be matched if it is uploaded again. Only applies when
+              reports are sent to the NCMEC production endpoint.
+            </Text>
+          </div>
+
           <div className="flex flex-col gap-2">
             <Label
               htmlFor="defaultInternetDetailType"

db/src/scripts/api-server-pg/2026.09.15T04.40.33.add_reported_media_hash_bank_to_ncmec_org_settings.sql

@@ -0,0 +1,16 @@
+ALTER TABLE ncmec_reporting.ncmec_org_settings
+  ADD COLUMN IF NOT EXISTS reported_media_hash_bank_id integer NULL;
+
+DO $$
+BEGIN
+  ALTER TABLE ncmec_reporting.ncmec_org_settings
+    ADD CONSTRAINT ncmec_org_settings_reported_media_hash_bank_fkey
+    FOREIGN KEY (reported_media_hash_bank_id)
+    REFERENCES public.hash_banks(id)
+    ON DELETE SET NULL;
+EXCEPTION
+  WHEN duplicate_object THEN NULL;
+END $$;
+
+COMMENT ON COLUMN ncmec_reporting.ncmec_org_settings.reported_media_hash_bank_id IS
+  'When set, media from accepted production NCMEC reports is added to this hash bank.';

docs/development/local.md

@@ -164,6 +164,14 @@ npm run runWorkerOrJob ItemProcessingWorker
 
 Without this running, submitted items will be enqueued in Redis but not processed. Other available workers/jobs can be found in `server/iocContainer/services/workersAndJobs.ts`.
 
+Media from accepted NCMEC reports is added to the configured hash bank by
+another worker, which you only need when working on that flow:
+
+```sh
+cd server
+npm run runWorkerOrJob ReportedMediaBankingWorker
+```
+
 To preview emails locally without configuring SES or SendGrid, add the
 following to `server/.env`. The recipient, subject, and rendered content will
 be printed in the server terminal. This transport requires

docs/integrations/ncmec.md

@@ -45,6 +45,7 @@ Configure NCMEC reporting under **Settings** → **NCMEC Settings**.
 | **Contact Person (for law enforcement)** | A contact person law enforcement can reach (other than the reporting contact email): first name, last name, email, phone.                                                                                                                           |
 | **More Info URL**                        | URL for additional information about your reporting process (e.g. `https://yourcompany.com/ncmec-info`). Used as the web page URL when "Default internet detail type" is set to "Web page."                                                         |
 | **Default NCMEC Queue**                  | When reviewers click "Enqueue to NCMEC," jobs are sent to this queue. Leave as "Use org default queue" to fall back to the organization's default queue.                                                                                            |
+| **Hash Bank for Reported Media**         | Media from each CyberTip accepted by NCMEC is added to this hash bank so it can be matched if it is uploaded again. Only applies to [production submissions](#test-vs-production-submissions).                                                      |
 | **Default Internet Detail Type**         | The incident context (channel/medium) included in every CyberTip: Web page, Email, Newsgroup, Chat/IM, Online gaming, Cell phone, Non-internet, or Peer-to-peer.                                                                                    |
 | **NCMEC Additional Info Endpoint**       | Webhook URL Coop calls before submitting a CyberTip to fetch enriched user and media metadata. See [Additional Info Endpoint](#additional-info-endpoint) below. Strongly recommended as without it, CyberTips are submitted with minimal user data. |
 | **NCMEC Preservation Endpoint**          | Webhook URL Coop calls after a successful CyberTip submission with the report ID. See [Preservation Endpoint](#preservation-endpoint) below.                                                                                                        |

server/graphql/modules/ncmec.ts

@@ -79,6 +79,7 @@ const typeDefs = /* GraphQL */ `
     contactPersonPhone: String
     mediaReviewRequirement: NcmecMediaReviewRequirement
     minMediaToReview: Int
+    reportedMediaHashBankId: Int
   }
 
   input NcmecOrgSettingsInput {
@@ -99,6 +100,7 @@ const typeDefs = /* GraphQL */ `
     contactPersonPhone: String
     mediaReviewRequirement: NcmecMediaReviewRequirement
     minMediaToReview: Int
+    reportedMediaHashBankId: Int
   }
 
   type UpdateNcmecOrgSettingsResponse {
@@ -349,6 +351,19 @@ const Mutation: GQLMutationResolvers = {
     const { mediaReviewRequirement, minMediaToReview } =
       parseMediaReviewPolicy(input);
 
+    const reportedMediaHashBankId = input.reportedMediaHashBankId ?? null;
+
+    if (reportedMediaHashBankId !== null) {
+      const bank = await context.services.HMAHashBankService.getBankById(
+        user.orgId,
+        reportedMediaHashBankId,
+      );
+
+      if (!bank) {
+        throw userInputError('Selected hash bank was not found.');
+      }
+    }
+
     await context.services.NcmecService.updateNcmecOrgSettings({
       orgId: user.orgId,
       username,
@@ -368,6 +383,7 @@ const Mutation: GQLMutationResolvers = {
       contactPersonPhone: input.contactPersonPhone ?? null,
       mediaReviewRequirement,
       minMediaToReview,
+      reportedMediaHashBankId,
     });
 
     return { success: true };

server/graphql/modules/ncmecOrgSettingsValidation.ts

@@ -20,6 +20,7 @@ export type NcmecOrgSettingsInputShape = {
   contactPersonPhone?: string | null;
   mediaReviewRequirement?: string | null;
   minMediaToReview?: number | null;
+  reportedMediaHashBankId?: number | null;
 };
 
 const VALID_NCMEC_MEDIA_REVIEW_REQUIREMENTS = ['ALL', 'MINIMUM'] as const;

server/iocContainer/index.ts

@@ -33,6 +33,10 @@ import {
   makeItemSubmissionBulkWrite,
   type ItemSubmissionBulkWrite,
 } from '../queues/itemSubmissionQueue.js';
+import {
+  makeReportedMediaBankingEnqueue,
+  type ReportedMediaBankingEnqueue,
+} from '../queues/reportedMediaBankingQueue.js';
 import makeActionPublisher, {
   type ActionPublisher,
   type ActionTargetItem,
@@ -348,6 +352,8 @@ export interface Dependencies {
 
   itemSubmissionQueueBulkWrite: ItemSubmissionBulkWrite;
   itemSubmissionRetryQueueBulkWrite: ItemSubmissionBulkWrite;
+  /** Enqueues media of accepted NCMEC reports for hash banking. */
+  reportedMediaBankingEnqueue: ReportedMediaBankingEnqueue;
   IORedis: IORedis.Redis | Cluster;
   /**
    * Dedicated ioredis client for the items-async enqueue path. Same Redis
@@ -740,6 +746,11 @@ export default async function getBottle(
   bottle.factory('itemSubmissionRetryQueueBulkWrite', (container) =>
     makeItemSubmissionBulkWrite(container.IORedis, ITEM_SUBMISSION_DLQ_NAME),
   );
+  // Enqueued from the NCMEC submission path, so a Redis outage has to fail
+  // fast instead of buffering and holding up an accepted report.
+  bottle.factory('reportedMediaBankingEnqueue', (container) =>
+    makeReportedMediaBankingEnqueue(container.IORedisEnqueueNoBuffer),
+  );
 
   // Loggers
   register(bottle, 'RuleExecutionLogger', makeRuleExecutionLogger);
@@ -1745,6 +1756,7 @@ export default async function getBottle(
             'Scylla',
             'itemSubmissionQueueBulkWrite',
             'itemSubmissionRetryQueueBulkWrite',
+            'reportedMediaBankingEnqueue',
             'IORedis',
             'IORedisEnqueueNoBuffer',
             // Storage abstractions

server/iocContainer/services/workersAndJobs.ts

@@ -9,6 +9,7 @@ import {
 } from '../../workers_jobs/index.js';
 import makeItemProcessingWorker from '../../workers_jobs/ItemProcessingWorker.js';
 import makeRefreshMRTDecisionsMaterializedViewJob from '../../workers_jobs/RefreshMRTDecisionsMaterializedViewJob.js';
+import makeReportedMediaBankingWorker from '../../workers_jobs/ReportedMediaBankingWorker.js';
 import makeRetryFailedNcmecDecisionsJob from '../../workers_jobs/RetryFailedNcmecDecisionsJob.js';
 import makeRunUserRulesJob from '../../workers_jobs/RunUserRulesJob.js';
 import { type Dependencies } from '../index.js';
@@ -19,6 +20,7 @@ declare module '../index.js' {
     // NB: worker deps cannot be renamed
     // w/o breaking the deployment that starts them!
     ItemProcessingWorker: Worker;
+    ReportedMediaBankingWorker: Worker;
 
     // Jobs. Like workers, can't be renamed w/o breaking stuff.
     // The distinction between jobs and workers is that workers run continuously,
@@ -34,6 +36,7 @@ declare module '../index.js' {
 
 const workerAndJobFactories = {
   ItemProcessingWorker: makeItemProcessingWorker,
+  ReportedMediaBankingWorker: makeReportedMediaBankingWorker,
   RunUserRulesJob: makeRunUserRulesJob,
   RefreshMRTDecisionsMaterializedViewJob:
     makeRefreshMRTDecisionsMaterializedViewJob,