feat(admin): moderation tools for limits and activity stats by Ferryx349 · Pull Request #941 · cameri/nostream

Ferryx349 · 2026-10-23T08:22:14Z

Description

This PR adds Admin Console Moderation :- view/update pubkey & kind lists and rate-limit bypass lists, quick ban/unban and IP bypass actions, and 7-day stats (top publishers, client IPs, rate-limit hits). Persists limit changes to settings with audit logging.

Related Issue

Closes #634

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Screen.Recording.2026-10-23.at.13.38.14.mov

Types of changes

Non-functional change (docs, style, minor refactor)
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my code changes.
I added a changeset, or this is docs-only and I added an empty changeset.
All new and existing tests passed.

Closes #634. Adds admin API and Moderation console for pubkey/kind lists, rate-limit bypass, ban/unban actions, and publisher/IP/rate-limit stats.

changeset-bot · 2026-10-23T08:22:24Z

🦋 Changeset detected

Latest commit: fddff7f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
nostream	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

greptile-apps · 2026-10-23T08:26:59Z

Confidence Score: 4/5

[Medium impact] The changes affect relay event moderation within the authenticated admin workflow.

Concurrent moderation saves can silently undo bans, so this needs a fix before merging.

Findings

Concurrent saves undo bans ▶
Recent uploads miss activity totals ▶
Valid IPv6 bypasses do nothing ▶

Summary

Adds a Moderation page and admin APIs for limit lists, quick bans, bypass changes, and activity statistics.

Admins can change event limits and take quick moderation actions.
Admins can rank publishers and client IPs by recent event activity.
The relay counts rate-limit hits for moderation activity stats.

The supplied previous threads have no comment numbers. Earlier fixes preserve whitelist membership, isolate test settings, deep-merge defaults, aggregate rankings before limiting, and delete temporary Redis sets. Ferryx349 manually resolved the remaining rolling-window thread without explanation.

Diagram

sequenceDiagram
  participant Admin
  participant API as Admin API
  participant Settings as Settings file
  participant Workers as Relay workers
  participant Stores as PostgreSQL and Redis
  Admin->>API: Read limits and activity
  API->>Stores: Query activity and rate-limit hits
  Stores-->>Admin: Ranked counts
  Admin->>API: Ban or change bypass
  API->>Settings: Save updated lists
  Settings-->>Workers: File change triggers reload
  API-->>Admin: Success

_{Reviews (10) · Last reviewed commit: "Merge branch 'main' into feat/admin-mode..." · Reviewed by Greptile}

coveralls · 2026-10-23T08:27:59Z

Coverage Report for CI Build 40060142350

Warning

No base build found for commit c40e570 on main.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 75.733%

Details

Patch coverage: 22 uncovered changes across 5 files (268 of 290 lines covered, 92.41%).

Uncovered Changes

File	Changed	Covered	%
src/utils/admin-moderation.ts	79	69	87.34%
src/controllers/admin/patch-moderation-limits-controller.ts	21	17	80.95%
src/controllers/admin/post-moderation-actions-controller.ts	25	21	84.0%
src/utils/admin-moderation-persist.ts	19	16	84.21%
src/utils/moderation-rate-limit-stats.ts	62	61	98.39%
Total (15 files)	290	268	92.41%

Coverage Regressions

Requires a base build to compare against. How to fix this →

Coverage Stats


Relevant Lines:	11576
Covered Lines:	9174
Line Coverage:	79.25%
Relevant Branches:	5983
Covered Branches:	4124
Branch Coverage:	68.93%
Branches in Coverage %:	Yes
Coverage Strength:	789.94 hits per line

💛 - Coveralls

Keep pubkey whitelist on ban; use daily Redis buckets for rate-limit hits; isolate moderation tests with temp NOSTR_CONFIG_DIR; skip stats when cache has no eval.

Use ZREVRANGE with the requested limit instead of scanning full daily sets.

Union day buckets in Redis, then return top N so multi-day totals stay correct.

Drop the temporary ZUNIONSTORE destination immediately so stats refresh does not retain duplicate daily bucket copies in Redis.

Improve coverage for moderation limits, actions, stats, and rate-limit helpers.

Use callCount in rate-limit stats tests, cover query helpers and factory wiring, and add error-path cases for moderation actions and stats.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

…dows Deep-merge defaults before validateSettings so partial info overrides work, and include every UTC day bucket touched by the requested stats window.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

greptile-apps · 2026-10-24T03:58:43Z

+  const userSettings = loadUserSettings() as Settings
+  const nextUserSettings = applyLimitsToUserSettings(userSettings, normalized)
+  const mergedNext = mergeDeepRight(loadDefaults(), nextUserSettings) as Settings
+
+  const issues = validateSettings(mergedNext)
+  if (issues.length > 0) {
+    throw new ValidationError('Validation failed', issues)
+  }
+
+  saveSettings(nextUserSettings)


Concurrent saves undo bans

On relays with multiple workers, two moderation actions can overwrite each other. Each request reads every list, changes its copy, then replaces all lists without a shared lock. If two workers read before either saves, banning different pubkeys leaves only the last ban, even though both requests succeed.

Lock the full read-change-save operation across workers and read the current lists inside that lock.

greptile-apps · 2026-10-24T03:58:43Z

+    .select(db.raw(`encode(event_pubkey, 'hex') as pubkey`))
+    .count('* as eventCount')
+    .whereNull('deleted_at')
+    .where('event_created_at', '>=', sinceUnixSeconds)


Recent uploads miss activity totals

Both activity queries filter by event_created_at, which copies the publisher's created_at, rather than when the relay received the event. With the default maxNegativeDelta: 0, clients can upload older events today without appearing in today's activity totals. Admins can therefore miss recent heavy publishers and client IPs.

Use first_seen for the receipt window in both queries.

greptile-apps · 2026-10-24T03:58:43Z

+    case 'whitelist-ip': {
+      const ip = fields.ip?.trim()
+      if (!ip || isIP(ip) === 0) {
+        throw new Error('ip is required and must be a valid IPv4 or IPv6 address')
+      }
+      return {
+        ...current,
+        rateLimitBypass: {
+          ...current.rateLimitBypass,
+          ipAddresses: [...new Set([...current.rateLimitBypass.ipAddresses, ip])],


Valid IPv6 bypasses do nothing

IP bypass actions accept any valid IPv6 spelling but save and remove it as an exact string. The socket uses SocketAddress, which returns a standard spelling, while the rate-limit check uses includes. Entering 2001:0db8:0:0:0:0:0:1 succeeds but does not match the client's 2001:db8::1. Another valid spelling can also fail to remove an existing bypass.

Normalize addresses the same way before adding, removing, and comparing them.

feat(admin): moderation tools for limits and activity stats

9b32c9f

Closes #634. Adds admin API and Moderation console for pubkey/kind lists, rate-limit bypass, ban/unban actions, and publisher/IP/rate-limit stats.