forked from retoor/devplacepy
retoor
8e9d3fad98
Implements the moderation and consent obligations a social platform carries, so the web version and any client that speaks to it enforce the same rules. Moderation core (services/moderation/, database/moderation.py): a reportable target registry, the content filter and its choke points, the report queue with atomic resolution, enforcement actions, consent tracking, maturity gating, and account deletion with a grace window. Surfaces: POST /reports plus the member report list, /admin/moderation and the per-report admin view, /workspaces, terms acceptance at /auth/terms, consent and account deletion under /profile, the report button and dialog partials, the maturity gate, and the moderation stylesheet and ReportDialog client. Every user-generated surface stays reportable by construction: new content tables are registered in REPORTABLE_TARGETS or listed in UNREPORTABLE_TABLES with a reason, and the registry test fails the suite on anything left unclassified. Docs: community guidelines, content moderation, intellectual property, privacy, terms, contact, and the admin-only moderation operations page, plus the moderation API group and the Devii moderation actions. Compliance record: applecomp.md is the requirement register, applechanges.md the gap analysis against this codebase, and appleimpl.md the implementation design they resolve to. Tests cover the report flow, admin moderation, consent, account deletion, terms acceptance, workspaces, and the registry invariant across the unit, api, and e2e tiers.
490 lines
18 KiB
Python
490 lines
18 KiB
Python
# retoor <retoor@molodetz.nl>
|
|
|
|
from .._shared import endpoint, field
|
|
from devplacepy.database.moderation import (
|
|
CONSENT_KINDS,
|
|
MODERATION_ACTIONS,
|
|
REPORTABLE_TARGETS,
|
|
REPORT_REASONS,
|
|
REPORT_STATUSES,
|
|
)
|
|
|
|
REPORT_TARGETS = list(REPORTABLE_TARGETS)
|
|
REASON_KEYS = list(REPORT_REASONS)
|
|
CONSENT_KEYS = list(CONSENT_KINDS)
|
|
|
|
SAMPLE_REPORT = {
|
|
"uid": "REPORT_UID",
|
|
"target_type": "post",
|
|
"target_uid": "POST_UID",
|
|
"target_url": "/posts/a-post",
|
|
"reason": "harassment",
|
|
"reason_label": "Harassment or bullying",
|
|
"detail": "Repeated personal attacks in the thread.",
|
|
"severity": "warn",
|
|
"status": "open",
|
|
"origin": "member",
|
|
"categories": [],
|
|
"created_at": "2026-01-05T10:00:00+00:00",
|
|
"resolved_at": "",
|
|
"reporter_name": "alice",
|
|
"owner_name": "bob",
|
|
"report_count": 2,
|
|
}
|
|
|
|
GROUP = {
|
|
"slug": "moderation",
|
|
"title": "Reporting & Moderation",
|
|
"intro": """
|
|
# Reporting & Moderation
|
|
|
|
Every externally visible surface on DevPlace is reportable through one polymorphic
|
|
endpoint, and every report lands in one queue with one state machine. The reason
|
|
list is served by `GET /reports/reasons`, so a native client renders the same
|
|
dialog the web UI does.
|
|
|
|
DevPlace commits to reviewing every report within the window published on the
|
|
[content moderation](/docs/content-moderation.html) page. Filing a report always
|
|
returns an acknowledgement carrying that window.
|
|
|
|
The moderation endpoints under `/admin/moderation` are administrator-only and are
|
|
subject to the admin seniority rule: a junior administrator cannot action a more
|
|
senior one.
|
|
|
|
Every endpoint follows the shared [Conventions & Errors](/docs/conventions.html) (auth, content
|
|
negotiation, pagination, status codes); see [Authentication](/docs/authentication.html) for the
|
|
four ways to sign requests.
|
|
""",
|
|
"endpoints": [
|
|
endpoint(
|
|
id="report-reasons",
|
|
method="GET",
|
|
path="/reports/reasons",
|
|
title="List report reasons",
|
|
summary="The reason keys a report may be filed under, with their labels.",
|
|
auth="public",
|
|
sample_response={
|
|
"reasons": [{"key": "harassment", "label": "Harassment or bullying"}],
|
|
"severities": ["info", "warn", "critical"],
|
|
},
|
|
),
|
|
endpoint(
|
|
id="report-create",
|
|
method="POST",
|
|
path="/reports/{target_type}/{target_uid}",
|
|
title="Report content",
|
|
summary="File a report against any user-generated surface.",
|
|
auth="user",
|
|
encoding="form",
|
|
destructive=False,
|
|
params=[
|
|
field(
|
|
"target_type",
|
|
"path",
|
|
"enum",
|
|
True,
|
|
"post",
|
|
"The kind of content being reported.",
|
|
REPORT_TARGETS,
|
|
),
|
|
field(
|
|
"target_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POST_UID",
|
|
"UID of the reported item.",
|
|
),
|
|
field(
|
|
"reason",
|
|
"form",
|
|
"enum",
|
|
True,
|
|
"harassment",
|
|
"Why the content breaks the guidelines.",
|
|
REASON_KEYS,
|
|
),
|
|
field(
|
|
"detail",
|
|
"form",
|
|
"string",
|
|
False,
|
|
"",
|
|
"Free text for the moderator, up to 2000 characters.",
|
|
),
|
|
],
|
|
notes=[
|
|
"A second report on the same target by the same reporter updates the "
|
|
"open report instead of creating a duplicate.",
|
|
"You cannot report your own content.",
|
|
],
|
|
sample_response={
|
|
"ok": True,
|
|
"redirect": "/reports/mine",
|
|
"data": {
|
|
"uid": "REPORT_UID",
|
|
"status": "open",
|
|
"severity": "warn",
|
|
"sla_hours": 24,
|
|
},
|
|
},
|
|
),
|
|
endpoint(
|
|
id="reports-mine",
|
|
method="GET",
|
|
path="/reports/mine",
|
|
title="List your reports",
|
|
summary="The reports you filed and the outcome of each.",
|
|
auth="user",
|
|
params=[
|
|
field(
|
|
"status",
|
|
"query",
|
|
"enum",
|
|
False,
|
|
"open",
|
|
"Filter by report status.",
|
|
list(REPORT_STATUSES),
|
|
),
|
|
field("page", "query", "integer", False, "1", "Page number."),
|
|
],
|
|
sample_response={
|
|
"reports": [SAMPLE_REPORT],
|
|
"pagination": {"page": 1, "total": 1, "total_pages": 1},
|
|
"status": "",
|
|
},
|
|
),
|
|
endpoint(
|
|
id="admin-moderation",
|
|
method="GET",
|
|
path="/admin/moderation",
|
|
title="The moderation queue",
|
|
summary="Reported content awaiting a decision, oldest open first.",
|
|
auth="admin",
|
|
params=[
|
|
field(
|
|
"status",
|
|
"query",
|
|
"enum",
|
|
False,
|
|
"open",
|
|
"Filter by report status.",
|
|
list(REPORT_STATUSES),
|
|
),
|
|
field("page", "query", "integer", False, "1", "Page number."),
|
|
],
|
|
sample_response={
|
|
"reports": [SAMPLE_REPORT],
|
|
"counts": {"open": 1, "acknowledged": 0, "actioned": 0, "dismissed": 0},
|
|
"sla": {
|
|
"sla_hours": 24,
|
|
"oldest_open_hours": 1.5,
|
|
"breached": 0,
|
|
"within_sla": True,
|
|
},
|
|
},
|
|
),
|
|
endpoint(
|
|
id="admin-moderation-report",
|
|
method="GET",
|
|
path="/admin/moderation/{uid}",
|
|
title="Read one report",
|
|
summary="One report with its decisions and the author's history.",
|
|
auth="admin",
|
|
params=[
|
|
field("uid", "path", "string", True, "REPORT_UID", "Report UID."),
|
|
],
|
|
sample_response={
|
|
"report": SAMPLE_REPORT,
|
|
"actions": [],
|
|
"history": [],
|
|
"available_actions": list(MODERATION_ACTIONS),
|
|
"can_remove": True,
|
|
},
|
|
),
|
|
endpoint(
|
|
id="admin-moderation-status",
|
|
method="POST",
|
|
path="/admin/moderation/{uid}/status",
|
|
title="Set a report status",
|
|
summary="Move a report through the triage state machine.",
|
|
auth="admin",
|
|
encoding="form",
|
|
params=[
|
|
field("uid", "path", "string", True, "REPORT_UID", "Report UID."),
|
|
field(
|
|
"status",
|
|
"form",
|
|
"enum",
|
|
True,
|
|
"acknowledged",
|
|
"New status.",
|
|
list(REPORT_STATUSES),
|
|
),
|
|
],
|
|
sample_response={"ok": True, "redirect": "/admin/moderation/REPORT_UID"},
|
|
),
|
|
endpoint(
|
|
id="admin-moderation-decide",
|
|
method="POST",
|
|
path="/admin/moderation/{uid}/decide",
|
|
title="Decide a report",
|
|
summary="Apply a moderation decision and notify the affected user.",
|
|
auth="admin",
|
|
encoding="form",
|
|
destructive=True,
|
|
params=[
|
|
field("uid", "path", "string", True, "REPORT_UID", "Report UID."),
|
|
field(
|
|
"action",
|
|
"form",
|
|
"enum",
|
|
True,
|
|
"dismiss",
|
|
"The decision to apply.",
|
|
list(MODERATION_ACTIONS),
|
|
),
|
|
field(
|
|
"reason",
|
|
"form",
|
|
"string",
|
|
False,
|
|
"",
|
|
"Reason shown to the affected user.",
|
|
),
|
|
field("notes", "form", "string", False, "", "Internal notes."),
|
|
field(
|
|
"duration_hours",
|
|
"form",
|
|
"integer",
|
|
False,
|
|
"24",
|
|
"Suspension length in hours.",
|
|
),
|
|
],
|
|
notes=[
|
|
"A report already resolved by another moderator answers 409.",
|
|
"Content removal is unavailable for targets that have no removal "
|
|
"path (direct messages, accounts, workspaces, polls, assistant "
|
|
"output); act on the account instead.",
|
|
],
|
|
sample_response={"ok": True, "redirect": "/admin/moderation/REPORT_UID"},
|
|
),
|
|
endpoint(
|
|
id="admin-user-suspend",
|
|
method="POST",
|
|
path="/admin/users/{uid}/suspend",
|
|
title="Suspend an account",
|
|
summary="Suspend an account for a fixed period with a stated reason.",
|
|
auth="admin",
|
|
encoding="form",
|
|
destructive=True,
|
|
params=[
|
|
field("uid", "path", "string", True, "USER_UID", "User UID."),
|
|
field("reason", "form", "string", False, "", "Reason shown to the user."),
|
|
field(
|
|
"duration_hours",
|
|
"form",
|
|
"integer",
|
|
False,
|
|
"24",
|
|
"Suspension length in hours.",
|
|
),
|
|
],
|
|
notes=[
|
|
"A suspended account can still read, still see why, and still delete "
|
|
"itself, but cannot create content.",
|
|
],
|
|
sample_response={"ok": True, "redirect": "/admin/users"},
|
|
),
|
|
endpoint(
|
|
id="admin-user-lift",
|
|
method="POST",
|
|
path="/admin/users/{uid}/lift",
|
|
title="Lift a restriction",
|
|
summary="Clear a suspension or ban and restore the account.",
|
|
auth="admin",
|
|
encoding="form",
|
|
params=[field("uid", "path", "string", True, "USER_UID", "User UID.")],
|
|
sample_response={"ok": True, "redirect": "/admin/users"},
|
|
),
|
|
endpoint(
|
|
id="admin-user-ban",
|
|
method="POST",
|
|
path="/admin/users/{uid}/ban",
|
|
title="Ban an account",
|
|
summary="Permanently close an account and revoke every credential.",
|
|
auth="admin",
|
|
encoding="form",
|
|
destructive=True,
|
|
params=[
|
|
field("uid", "path", "string", True, "USER_UID", "User UID."),
|
|
field("reason", "form", "string", False, "", "Reason shown to the user."),
|
|
],
|
|
sample_response={"ok": True, "redirect": "/admin/users"},
|
|
),
|
|
endpoint(
|
|
id="auth-accept-terms-page",
|
|
method="GET",
|
|
path="/auth/accept-terms",
|
|
title="The terms acceptance page",
|
|
summary="The Terms of Service version in force and the version this account accepted.",
|
|
auth="user",
|
|
sample_response={"terms_version": "1", "accepted_version": ""},
|
|
),
|
|
endpoint(
|
|
id="auth-accept-terms",
|
|
method="POST",
|
|
path="/auth/accept-terms",
|
|
title="Accept the terms",
|
|
summary="Record acceptance of the Terms of Service version in force.",
|
|
auth="user",
|
|
encoding="form",
|
|
notes=[
|
|
"A member whose accepted version is behind the version in force is "
|
|
"redirected here on any mutating request. Reading, the docs, the "
|
|
"safety controls and account deletion are never blocked.",
|
|
],
|
|
sample_response={"ok": True, "redirect": "/feed", "data": {"terms_version": "1"}},
|
|
),
|
|
endpoint(
|
|
id="profile-consent",
|
|
method="POST",
|
|
path="/profile/{username}/consent",
|
|
title="Grant or withdraw a consent",
|
|
summary="Change one consent on your own account. Withdrawal takes effect at once.",
|
|
auth="user",
|
|
encoding="form",
|
|
params=[
|
|
field("username", "path", "string", True, "USERNAME", "Your own username."),
|
|
field(
|
|
"kind",
|
|
"form",
|
|
"enum",
|
|
True,
|
|
"ai_third_party",
|
|
"Consent to change.",
|
|
CONSENT_KEYS,
|
|
),
|
|
field("granted", "form", "enum", True, "1", "1 grants, 0 withdraws.", ["1", "0"]),
|
|
],
|
|
notes=[
|
|
"Withdrawing `ai_third_party` makes the AI gateway refuse every call "
|
|
"that would send your own content to the provider, whatever the "
|
|
"per-feature preference says.",
|
|
"Withdrawing `activity_recording` stops presence writes; you simply "
|
|
"appear offline.",
|
|
"Only the account holder can change a consent. An administrator "
|
|
"reads the record but never grants or withdraws it for someone else.",
|
|
],
|
|
sample_response={
|
|
"ok": True,
|
|
"redirect": "/profile/USERNAME?tab=privacy",
|
|
"data": {"kind": "ai_third_party", "state": "granted"},
|
|
},
|
|
),
|
|
endpoint(
|
|
id="profile-mature-content",
|
|
method="POST",
|
|
path="/profile/{username}/mature-content",
|
|
title="Set the mature-content preference",
|
|
summary="Show or hide content labelled mature for your own account.",
|
|
auth="user",
|
|
encoding="form",
|
|
params=[
|
|
field("username", "path", "string", True, "USERNAME", "Your own username."),
|
|
field(
|
|
"mature_opt_in",
|
|
"form",
|
|
"enum",
|
|
True,
|
|
"1",
|
|
"1 shows mature content, 0 hides it.",
|
|
["1", "0"],
|
|
),
|
|
],
|
|
notes=[
|
|
"Only the account holder can change this preference. An administrator "
|
|
"reads the privacy tab but never sets it for someone else.",
|
|
],
|
|
sample_response={
|
|
"ok": True,
|
|
"redirect": "/profile/USERNAME?tab=privacy",
|
|
"data": {"mature_opt_in": True},
|
|
},
|
|
),
|
|
endpoint(
|
|
id="profile-delete",
|
|
method="GET",
|
|
path="/profile/{username}/delete",
|
|
title="Account deletion page",
|
|
summary="What deletion removes, what is retained, and the grace window.",
|
|
auth="user",
|
|
params=[
|
|
field("username", "path", "string", True, "USERNAME", "Your own username."),
|
|
],
|
|
sample_response={
|
|
"username": "USERNAME",
|
|
"grace_hours": 24,
|
|
"removed": ["Your account record, username, email address and password"],
|
|
"retained": ["Append-only audit and moderation records"],
|
|
},
|
|
),
|
|
endpoint(
|
|
id="profile-delete-confirm",
|
|
method="POST",
|
|
path="/profile/{username}/delete",
|
|
title="Delete your account",
|
|
summary="Permanently delete your account and personal data.",
|
|
auth="user",
|
|
encoding="form",
|
|
destructive=True,
|
|
params=[
|
|
field("username", "path", "string", True, "USERNAME", "Your own username."),
|
|
field("password", "form", "string", True, "PASSWORD", "Your account password."),
|
|
],
|
|
notes=[
|
|
"Only the account holder can delete an account; an administrator uses "
|
|
"a ban instead.",
|
|
"Sessions and tokens are revoked and the profile is anonymised "
|
|
"immediately; the deletion event is purged after the grace window.",
|
|
],
|
|
sample_response={
|
|
"ok": True,
|
|
"redirect": "/",
|
|
"data": {"stamp": "2026-01-05T10:00:00+00:00", "rows": 42, "grace_hours": 24},
|
|
},
|
|
),
|
|
endpoint(
|
|
id="workspaces-index",
|
|
method="GET",
|
|
path="/workspaces/index",
|
|
title="Published workspace index",
|
|
summary="Every workspace published to the public ingress, with its link.",
|
|
auth="public",
|
|
params=[field("page", "query", "integer", False, "1", "Page number.")],
|
|
notes=[
|
|
"The project-derived `description` and `project_url` come back empty "
|
|
"unless you may view the workspace's project, so a private project "
|
|
"never leaks its title or description through this public listing.",
|
|
],
|
|
sample_response={
|
|
"workspaces": [
|
|
{
|
|
"uid": "INSTANCE_UID",
|
|
"name": "demo",
|
|
"slug": "demo",
|
|
"owner_uid": "USER_UID",
|
|
"url": "{{ base }}/p/demo",
|
|
"description": "A demo workspace.",
|
|
"owner": "alice",
|
|
"maturity": "general",
|
|
"project_url": "/projects/demo",
|
|
}
|
|
],
|
|
"total": 1,
|
|
},
|
|
),
|
|
],
|
|
}
|