Tea journaling on ATProto (alpha) forked from arabica.social/arabica
oolong docs api moderation.md
11 kB · 227 lines
Markdown
at main

Moderation API #

JSON read and mutation surface for the moderation dashboard. Every endpoint is server-gated twice: the router wraps it in RequireModerator / RequireAdmin / RequirePermission, and the handler repeats the check, so no panel or admin-only field is exposed to callers that lack the matching permission.

Conventions #

  • Every /api/* path answers with JSON. APIJSONMiddleware sets Accept: application/json on the way in and rewrites any non-JSON error body into the envelope.
  • Shared mutation handlers accept application/json bodies or form-encoded bodies (readModerationParams) and always answer with the JSON action result.
  • Errors are {"error": "...", "code": "..."} with a matching HTTP status. code is one of authentication_required, permission_denied, invalid_request, not_found, internal_error, service_unavailable.
  • All timestamps are RFC 3339. Lists are always arrays ([], never null). A null panel means the caller lacks the permission that guards it.
  • Request bodies for the mutation endpoints may be application/x-www-form-urlencoded (as the dashboard sends them) or JSON with the same snake_case field names.

GET /api/moderation #

Handler: (*Handler).HandleAdminJSON. Required: authenticated moderator.

Query parameters:

name default validation
limit 50 1–200
offset 0 >= 0
enrich_reports false true enables enrichment

Pagination is applied to every list panel the caller may read. Invalid values produce 400 invalid_request. Unless enrich_reports=true is passed, the endpoint never makes network calls.

Response:

{
  "viewer": {
    "did": "did:plc:...",
    "is_moderator": true,
    "is_admin": false,
    "can_hide": true,
    "can_unhide": true,
    "can_view_logs": false,
    "can_view_reports": true,
    "can_block": false,
    "can_unblock": false,
    "can_reset_autohide": false,
    "can_dismiss_reports": true,
    "can_manage_labels": false
  },
  "hidden":   {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
  "blocked":  {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
  "reports":  {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
  "activity": {"items": [], "total": null, "limit": 50, "offset": 0, "has_more": false},
  "labels":   {"items": [], "total": 0, "limit": 50, "offset": 0, "has_more": false},
  "stats": null,
  "cache": null
}

Panel permissions:

panel visible when
hidden can_hide or can_unhide
blocked can_block or can_unblock
reports can_view_reports (pending reports)
activity can_view_logs
labels can_manage_labels
stats is_admin
cache is_admin

The pending-reports panel's Dismiss action is gated by can_dismiss_reports; the server re-checks it on every mutation.

Panel pagination: total is the exact pre-pagination count for hidden, blocked, reports and labels. The activity log is read newest-first from a bounded window (offset + limit + 1, at most 1000 rows), so total is null there and clients page with has_more.

Item shapes:

// hidden.items[]
{"at_uri": "at://...", "hidden_at": "...", "hidden_by": "did:plc:...",
 "reason": "...", "auto_hidden": false}

// blocked.items[]
{"did": "did:plc:...", "blacklisted_at": "...", "blacklisted_by": "did:plc:...",
 "reason": "..."}

// reports.items[]
{"id": "3k...", "subject_uri": "at://...", "subject_did": "did:plc:...",
 "reporter_did": "did:plc:...", "owner_handle": "alice.example.com",
 "reporter_handle": "bob.example.com", "preview": "Brew: longSteep",
 "reason": "...", "created_at": "...", "status": "pending", "resolved_by": "",
 "resolved_at": null}

// activity.items[]
{"id": "3k...", "action": "hide_record", "actor_did": "did:plc:...",
 "target_uri": "at://...", "reason": "...", "details": {},
 "timestamp": "...", "auto_mod": false}

// labels.items[]
{"id": "3k...", "entity_type": "user", "entity_id": "did:plc:...",
 "label": "warned", "value": "", "created_at": "...", "created_by": "did:plc:...",
 "expires_at": null, "expired": false}

// stats
{"known_users": 0, "registered_users": 0, "indexed_records": 0,
 "total_likes": 0, "total_comments": 0, "firehose_connected": false,
 "records_by_collection": {}, "backups": []}

// cache
{"witness_cache_available": false, "feed_index_available": false,
 "backup_service_available": false,
 "actions": {"export": false, "fetch_pds_records": true,
             "refresh_handles": false, "rebuild": false, "purge": false}}

Reports are the stored pending reports. With enrich_reports=true, the endpoint resolves owner and reporter handles plus a short content preview for the visible page only, using the dashboard's existing enrichment path (AppView profile lookups and the record's PDS, through the same resolver caches). Enrichment has a hard two-second per-page budget; on timeout or lookup failure the stored fields are still returned and owner_handle, reporter_handle or preview stay empty. Default reads skip enrichment entirely, so pagination and totals are unaffected either way.

stats.backups[]:

{"source": "feed", "healthy": true, "last_run": "...", "last_success": "...",
 "last_failure": null, "last_error": "", "last_duration_ms": 0,
 "last_size_bytes": 0, "retained_count": 0, "next_run": "..."}

Zero timestamps are emitted as null.

GET /api/moderation/stats #

Handler: (*Handler).HandleAdminStatsJSON. Required: admin.

Returns the same object as the stats panel (including backups), admin-only: moderators receive 403 permission_denied.

Mutations #

Handlers: HandleHideRecord, HandleUnhideRecord, HandleBlockUser, HandleUnblockUser, HandleResetAutoHide, HandleDismissReport, HandleAddLabel, HandleRemoveLabel.

They are served only under /api/moderation/...; /_mod is the Solid dashboard page, not a handler prefix.

JSON success body:

{"ok": true, "action": "hide_record", "target": "at://...", "message": "Record hidden from feed"}

action matches the audit-log action name. The body is the whole response: there is no HTML fragment or redirect variant.

Request fields:

endpoint fields
POST .../hide uri, reason
POST .../unhide uri, reason
POST .../block did, reason
POST .../unblock did
POST .../reset-autohide did
POST .../dismiss-report id
POST .../label/add entity_type (user/record), entity_id, label, value, expires (Go duration, e.g. 24h)
POST .../label/remove entity_type, entity_id, label

Missing or invalid fields produce 400 invalid_request with the validation message; store failures produce 500 internal_error.

Operational endpoints #

These answer JSON, or an attachment, rather than the dashboard shape. The mutations take did from the query string or from the body:

route required response
GET /api/moderation/export admin witness-cache export, Content-Disposition: attachment
GET /api/moderation/pds-records moderator PDS export, Content-Disposition: attachment
POST /api/moderation/purge admin {"did","purged","purgedAt"}
POST /api/moderation/rebuild admin {"did","handle","rebuilt","rebuiltAt"}
POST /api/moderation/refresh-handles admin {"refreshed","failed","durationMs","finishedAt"}

Their payload keys are camelCase for compatibility with existing operator scripts. Validation failures are written as plain text by the handler and rewritten into the error envelope by APIJSONMiddleware.

Router wiring #

method path middleware + handler
GET /api/moderation RequireModerator → HandleAdminJSON
GET /api/moderation/stats RequireAdmin → HandleAdminStatsJSON
GET /api/moderation/export RequireAdmin → HandleAdminExportDID
GET /api/moderation/pds-records RequireModerator → HandleAdminFetchPDSRecords
POST /api/moderation/purge RequireAdmin (+ CSRF) → HandleAdminPurgeDID
POST /api/moderation/rebuild RequireAdmin (+ CSRF) → HandleAdminRebuildDID
POST /api/moderation/refresh-handles RequireAdmin (+ CSRF) → HandleAdminRefreshHandles
POST /api/moderation/hide RequirePermission(hide_record) → HandleHideRecord
POST /api/moderation/unhide RequirePermission(unhide_record) → HandleUnhideRecord
POST /api/moderation/block RequirePermission(blacklist_user) → HandleBlockUser
POST /api/moderation/unblock RequirePermission(unblacklist_user) → HandleUnblockUser
POST /api/moderation/reset-autohide RequirePermission(reset_autohide) → HandleResetAutoHide
POST /api/moderation/dismiss-report RequirePermission(dismiss_report) → HandleDismissReport
POST /api/moderation/label/add RequirePermission(manage_labels) → HandleAddLabel
POST /api/moderation/label/remove RequirePermission(manage_labels) → HandleRemoveLabel

The handlers repeat the authentication and permission checks internally, so a missing middleware wrapper cannot leak the dashboard payload; the middleware is still required for consistent 401/403 CSRF and rate-limit handling.