[468][592] Populate NCMEC reports with the ipAddress schema field role

[juanmrad]

Fixes #468
Fixes #592

Context & Requests for Reviewers

Adopters can already tag User and Content items with the new ipAddress schema field role from previous prs. This PR closes the loop by sending those IPs to NCMEC.

When buildSubmitReportParamsFromDecision assembles a CyberTip payload it now reads the ipAddress role off the reported user and each reported media item. submitReport appends those IPs to <ipCaptureEvent> on the user (Unknown event at the report's incident time) and on each file (Upload at the media's createdAt).

The additional-info webhook stays the authoritative source. Its events come first, and the role IP is appended alongside, so adopters who haven't yet wired the webhook still get the reported IP into the submission.

If neither source has data, the element is omitted entirely as usual.

Summary by CodeRabbit

• New Features

  • IP address field mapping and capture now supported in NCMEC incident reports for users and media items.

• Documentation

  • Updated NCMEC integration documentation to clarify IP capture event handling and configuration.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR extends NCMEC reporting to capture IP addresses from configured item type field role mappings. When users and media items have an ipAddress field role defined, those IPs are automatically synthesized into capture events during report submission: user IPs become Unknown events at incident time, media IPs become Upload events at their creation time, merged with any webhook-provided or param-supplied events.

Changes

NCMEC IP address to capture events

Layer / File(s)	Summary
IP event merge types and helper server/services/ncmecService/ncmecReporting.ts, server/services/ncmecService/ncmecReporting.test.ts	Media and NCMECUserParams input types now accept ipCaptureEvent as single or array, plus optional ipAddress string. Exported mergeFieldRoleIpIntoEvents helper concatenates webhook events, param events, and synthesized role-IP events in order, returning undefined when empty.
IP event integration in submitReport and media upload server/services/ncmecService/ncmecReporting.ts	During submitReport, user IP events are computed via merge helper with Unknown event name and clamped incident datetime, assigned to personOrUserReported.ipCaptureEvent. Media upload similarly merges ipCaptureEvent sources with synthesized Upload events from media.ipAddress and media.createdAt.
IP address extraction from configured field roles server/services/ncmecService/buildSubmitReportParamsFromDecision.ts, server/services/ncmecService/buildSubmitReportParamsFromDecision.test.ts	Resolved user and media item types are queried for ipAddress field role mappings. Extracted IPs are attached to reportedUser and each media item in NCMECReportParams. Test fixtures provide helpers to configure optional roles and verify IP propagation and omission rules.
Documentation of IP capture event synthesis docs/integrations/ncmec.md	CyberTip and Additional Info Endpoint documentation now describe how mapped ipAddress roles become synthesized events: Unknown at incident time for users, Upload at media creation time, with allowed eventName values listed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• roostorg/coop#477: Both PRs modify server/services/ncmecService/ncmecReporting.ts and the NCMECReportParams / submitReport XML payload construction logic; PR #477 adds additionalInfo and related report-field validation, while this PR adds ipCaptureEvent generation from role-mapped ipAddress.

Suggested labels

NCMEC, integration

Suggested reviewers

• vinaysrao1
• cassidyjames
• dom-notion
• julietshen

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly references the two linked issues (#468 and #592) and accurately summarizes the main change: populating NCMEC reports with the ipAddress schema field role.
Description check	✅ Passed	The description provides context, links both issues, explains the implementation approach, and covers how the feature works, including webhook integration and fallback behavior.
Linked Issues check	✅ Passed	The PR successfully implements both linked issue objectives: #468 (ipAddress role introduced in prior work) and #592 (ipAddress role values now automatically included in NCMEC reports via buildSubmitReportParamsFromDecision and submitReport).
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the stated objectives of populating NCMEC reports with ipAddress field role data and supporting the new field in report payloads.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-468-ip-in-ncmec-reports

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR completes ipAddress schema field role support for NCMEC submissions by carrying role-derived IPs from reported users and media into CyberTip payloads while preserving Additional Info webhook data as the first source.

Changes:

• Adds role-derived ipAddress extraction when building NCMEC report params from decisions.
• Merges webhook, explicit param, and role-derived IP events into user and media NCMEC payloads.
• Adds unit coverage and updates NCMEC integration docs for the new behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
server/services/ncmecService/ncmecReporting.ts	Adds IP event merging and applies role IPs to reported user and media submissions.
server/services/ncmecService/ncmecReporting.test.ts	Covers merge behavior, ordering, trimming, and empty-source handling.
server/services/ncmecService/buildSubmitReportParamsFromDecision.ts	Reads ipAddress schema field roles from user and media item data.
server/services/ncmecService/buildSubmitReportParamsFromDecision.test.ts	Adds regression coverage for role-derived user/media IP propagation.
docs/integrations/ncmec.md	Documents appended role-derived IP events in NCMEC submissions and webhook responses.

[coderabbitai]

🧹 Nitpick comments (1)

docs/integrations/ncmec.md (1)

216-216: 💤 Low value

Add timestamp detail for consistency.

For consistency with line 350, consider mentioning the timestamp for the synthesized Unknown event. Line 350 states "as an Unknown event at the report's incident time" which provides helpful clarity.

📝 Suggested revision

-     - `ipCaptureEvent`: IP addresses associated with the user (e.g. login, upload events), from your Additional Info endpoint. Providing IP data significantly improves NCMEC's ability to identify and locate the suspect. If the user item's item type maps the `ipAddress` schema field role, that IP is also appended as an `Unknown` event.
+     - `ipCaptureEvent`: IP addresses associated with the user (e.g. login, upload events), from your Additional Info endpoint. Providing IP data significantly improves NCMEC's ability to identify and locate the suspect. If the user item's item type maps the `ipAddress` schema field role, that IP is also appended as an `Unknown` event at the report's incident time.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/integrations/ncmec.md` at line 216, Update the ipCaptureEvent
documentation to mention the timestamp for the synthesized `Unknown` event: when
an item's `ipAddress` schema field role is appended as an `Unknown` event, state
that it is created "at the report's incident time" (same phrasing used on line
350) so readers understand the event's timestamp; update the sentence that
references `ipCaptureEvent`, `ipAddress`, and `Unknown` to include this
timestamp detail for consistency.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/integrations/ncmec.md`:
- Line 216: Update the ipCaptureEvent documentation to mention the timestamp for
the synthesized `Unknown` event: when an item's `ipAddress` schema field role is
appended as an `Unknown` event, state that it is created "at the report's
incident time" (same phrasing used on line 350) so readers understand the
event's timestamp; update the sentence that references `ipCaptureEvent`,
`ipAddress`, and `Unknown` to include this timestamp detail for consistency.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7d8088a2-3837-4c13-b594-2dcdffb5047b

📥 Commits

Reviewing files that changed from the base of the PR and between 58923ed and ee11aee.

📒 Files selected for processing (5)

• docs/integrations/ncmec.md
• server/services/ncmecService/buildSubmitReportParamsFromDecision.test.ts
• server/services/ncmecService/buildSubmitReportParamsFromDecision.ts
• server/services/ncmecService/ncmecReporting.test.ts
• server/services/ncmecService/ncmecReporting.ts

[julietshen]

looks fine, left one comment about lint likely to fail

[julietshen]

this might fail linting

The repo enforces functional/immutable-data. I hit this rule on PR #643 and had to rewrite rows.push(...) to spread instead. Even though events is a fresh local array, the rule typically fires on the call site. Maybe:

  const events: IPNCMECEvent[] = [
    ...(webhookEvents ?? []),
    ...paramEventsArray,
    ...(trimmedRoleIp !== ''
      ? [{ ipAddress: trimmedRoleIp, eventName: synthesisedEvent.eventName, dateTime: synthesisedEvent.dateTime }]
      : []),
  ];
  return events.length > 0 ? events : undefined;

[julietshen]

this is separate from your change but should we do format validation here? could add a Date.parse(createdAt) sanity check in a follow-up at some point