ctfy.server.models

28class AchievementCatalogEntry(CtfyModel):
29    """One badge as advertised to the frontend."""
30
31    id: str
32    name: str
33    description: str
34    icon: str
35    tier: str
36    secret: bool = False
37    # Only populated for locked entries on /me/achievements — the
38    # general catalog endpoint and unlocked entries don't carry it.
39    progress: AchievementProgress | None = None
40    # Score weight per tier (bronze=10, silver=25, gold=50, secret=100).
41    points: int = 0
42    # Number of distinct teams that have unlocked this badge.
43    earned_by_count: int = 0
44    # ``common`` | ``uncommon`` | ``rare`` | ``epic`` | ``mythic`` |
45    # ``unearned``.
46    rarity: str = "unearned"

14class AchievementProgress(CtfyModel):
15    """Quantifiable progress toward a locked badge.
16
17    ``current`` is what the team has so far, ``target`` is the
18    threshold the rule predicate checks against. Provided only when
19    the achievement has a registered progress provider (decathlete,
20    centurion, completionist, sisyphus, unicorn). Time-of-day /
21    first-blood / easter-egg badges return ``progress = null``.
22    """
23
24    current: int
25    target: int

65class AchievementSummary(CtfyModel):
66    """Aggregate roll-up for the Achievements page header."""
67
68    unlocked_count: int = 0
69    total_count: int = 0
70    score: int = 0
71    total_score: int = 0

18class Activity(CtfyModel):
19    """A single activity event in the platform log."""
20
21    id: str = ""
22    timestamp: datetime | None = None
23    event: str  # See PlatformEvent enum for valid values
24    team_id: str = ""
25    team_name: str = ""
26    challenge_id: str = ""
27    # Who triggered this event — surfaced on the public feed so admins
28    # can filter by actor and auditors can trace back. Values mirror
29    # the ActivityState fields in core.state.models.
30    actor_id: str = ""
31    actor_name: str = ""
32    actor_type: str = ""
33    # Denormalised actor avatar (GitHub/Google), surfaced on the feed so
34    # each event can render the actor's real face. Empty ⇒ the frontend
35    # renders a generated initials chip instead.
36    actor_avatar_url: str = ""
37    detail: ActivityDetail = Field(default_factory=ActivityDetail)

55class ActivityTimeseries(CtfyModel):
56    """Bucketed activity counts for the per-team activity histogram.
57
58    Same ``ts`` semantics as ``AdminTimeseries`` — oldest-first, right
59    edge anchored to "now". ``events`` is the sorted union of event
60    types that appear in any bucket, so the frontend has a stable list
61    of stack segments to render even when individual buckets are empty.
62    """
63
64    window_s: int = 0
65    bucket_s: int = 0
66    events: list[str] = Field(default_factory=list)
67    buckets: list[ActivityTimeseriesBucket] = Field(default_factory=list)

40class ActivityTimeseriesBucket(CtfyModel):
41    """One bucket of the team's activity histogram.
42
43    ``counts`` is keyed by event type (``flag_correct``, ``instance_started``,
44    …) so the frontend can stack each event as its own bar segment without
45    a follow-up shape-change to add new event types.
46
47    See :class:`AdminTimeseriesBucket` for the ``partial`` semantics.
48    """
49
50    ts: float = 0.0  # right edge, Unix seconds
51    counts: dict[str, int] = Field(default_factory=dict)
52    partial: bool = False

69class AdminChallengeLastError(CtfyModel):
70    """Most-recent error against a challenge, surfaced on the per-challenge
71    admin row so an admin can spot a broken challenge without opening
72    instance history."""
73
74    ts: float = 0.0  # stopped_at of the failing instance
75    message: str = ""
76    instance_id: str = ""

111class AdminChallengeLatencyBucket(CtfyModel):
112    """One fixed bucket of the cluster-wide launch-duration histogram.
113
114    The Challenges admin table paginates server-side, so the pooled
115    "how slow are launches overall" picture can't be re-derived in the
116    browser from one page of rows — this endpoint pools every
117    challenge's recent successful launches and bins them with the same
118    absolute edges the per-row drawer uses, so cross-page the shape
119    stays comparable.
120    """
121
122    label: str
123    count: int = 0

 79class AdminChallengeStatsRow(CtfyModel):
 80    """One row of the per-challenge admin dashboard.
 81
 82    Aggregates over ``InstanceRecord`` (lifetime) plus live ``InstanceState``
 83    (running). Launch-duration percentiles are computed only over rows with
 84    both ``requested_at`` and ``ready_at`` populated — error rows that never
 85    reached READY contribute to ``errors`` / ``error_rate`` but not to p50/p95.
 86    """
 87
 88    challenge_id: str
 89    name: str = ""
 90    difficulty: str = ""
 91    # Spec metadata folded in so the admin table no longer has to join
 92    # a second /challenges bulk fetch in the browser to show / sort /
 93    # filter by these (it paginates server-side now).
 94    category: str = ""
 95    tags: list[str] = Field(default_factory=list)
 96    question_count: int = 0
 97    launches: int = 0
 98    errors: int = 0
 99    error_rate: float = 0.0
100    avg_launch_s: float = 0.0
101    p50_launch_s: float = 0.0
102    p95_launch_s: float = 0.0
103    solve_rate: float = 0.0
104    running_count: int = 0
105    last_error: AdminChallengeLastError | None = None
106    # Newest-first launch durations, capped at 20, used for the inline
107    # sparkline. Recorded only for successful launches.
108    recent_launch_durations: list[float] = Field(default_factory=list)

225class AdminChallengeTimeseries(CtfyModel):
226    """Per-challenge bucketed health metrics for the admin drilldown.
227
228    Backs the row-level drawer on /admin/challenges that surfaces "did
229    this challenge's error rate spike at some specific time" without
230    forcing the operator to scrub through raw activity.
231    """
232
233    challenge_id: str = ""
234    window_s: int = 0
235    bucket_s: int = 0
236    buckets: list[AdminChallengeTimeseriesBucket] = Field(default_factory=list)

206class AdminChallengeTimeseriesBucket(CtfyModel):
207    """One bucket of the per-challenge health time-series.
208
209    Carries enough fields for the admin UI to render error-rate **and**
210    launch-duration trends from a single response — no need for the
211    frontend to issue three calls or do its own bucketing.
212
213    See :class:`AdminTimeseriesBucket` for the ``partial`` semantics.
214    """
215
216    ts: float = 0.0  # right edge, Unix seconds
217    launches: int = 0
218    errors: int = 0
219    error_rate: float = 0.0  # errors / launches; 0 when no launches
220    p50_launch_s: float = 0.0
221    p95_launch_s: float = 0.0
222    partial: bool = False

43class AdminFeedbackRow(CtfyModel):
44    """One row on the admin feedback audit list.
45
46    Mirrors ``SolveFeedbackState`` plus denormalised user identity for
47    triage convenience. Only ``require_admin``-gated endpoints expose
48    this shape; the public ``stats`` endpoint never includes per-user
49    fields.
50    """
51
52    user_id: str
53    user_display_name: str = ""
54    user_email: str = ""
55    challenge_id: str
56    team_id: str
57    competition_id: str
58    reaction: Reaction
59    created_at: datetime | None = None
60    updated_at: datetime | None = None

167class AdminHealthFlags(CtfyModel):
168    """Aggregated red-flag panels for the admin Overview "needs attention"
169    section. All four lists are independently populated and may be empty."""
170
171    stuck_starting: list[AdminStuckInstance] = Field(default_factory=list)
172    recent_errors: list[AdminRecentError] = Field(default_factory=list)
173    unhealthy_nodes: list[AdminUnhealthyNode] = Field(default_factory=list)
174    silent_challenges: list[AdminSilentChallenge] = Field(default_factory=list)

255class AdminOverview(CtfyModel):
256    """Single aggregate payload for the admin landing page."""
257
258    nodes: AdminOverviewCounts = Field(default_factory=AdminOverviewCounts)
259    config: DeploymentConfig = Field(default_factory=DeploymentConfig)
260    capacity: int = 0
261    running_instances: int = 0
262    teams_total: int = 0
263    solves_total: int = 0
264    solves_today: int = 0
265    # User-engagement counters — the "are people actually on the platform right
266    # now?" signal the infra/challenge/team metrics above don't answer.
267    # ``users_active_24h`` is distinct humans who triggered a write action
268    # (launch / submit / solve / join / answer) in the last 24h, not raw logins
269    # (pure browsing leaves no activity row). ``users_new_24h`` is registrations
270    # in the same window. All default to 0 so the field set stays additive.
271    users_total: int = 0
272    users_active_24h: int = 0
273    users_new_24h: int = 0

64class AdminOverviewCounts(CtfyModel):
65    total: int = 0
66    healthy: int = 0

852class AdminPatchSubmissionDetail(AdminPatchSubmissionInfo):
853    """One submission with the code it carried.
854
855    This is what keeping the bytes was *for*: a team disputes a verdict,
856    or a checker bug is found on day two, and someone has to read what
857    was actually submitted. Without a reader the stored blobs bought
858    nothing.
859    """
860
861    #: ``{path: base64(bytes)}``. Base64 rather than text because a
862    #: patch target may legitimately be binary, and decoding it into a
863    #: string would corrupt it into something that merely looks like a
864    #: bad submission.
865    files_b64: dict[str, str] = Field(default_factory=dict)
866    #: ``{path: sha256}`` — an equality match across teams, which is
867    #: what is left once uniqueness has stopped flag sharing but nothing
868    #: stops *patch* sharing.
869    digests: dict[str, str] = Field(default_factory=dict)

831class AdminPatchSubmissionInfo(PatchSubmissionInfo):
832    """One row of the organiser's defence queue.
833
834    The player's view plus the four things only an organiser asks:
835    *whose* it is, and — when a verdict is disputed — which worker
836    decided it after how many tries.
837
838    Still **without the code**, and here that is a stronger requirement
839    than on the parent: this is a competition-wide listing, so shipping
840    bodies would mean reading every stored patch of the event to render
841    a table of statuses. The bytes live on
842    :class:`AdminPatchSubmissionDetail`, one row at a time.
843    """
844
845    team_id: str = ""
846    user_id: str = ""
847    #: Which worker judged it, for correlating with that node's logs.
848    node_id: str = ""
849    attempts: int = 0

872class AdminPatchSubmissionPage(CtfyModel):
873    """A page of the defence queue, with the total behind it.
874
875    ``total`` is its own query rather than ``len(items)`` so a pager can
876    say "1-20 of 340" — and, with a ``status`` filter, it is also the
877    answer to "is the queue draining".
878    """
879
880    items: list[AdminPatchSubmissionInfo] = Field(default_factory=list)
881    total: int = 0

138class AdminRecentError(CtfyModel):
139    """An archived instance that ended in ``stop_reason="error"``."""
140
141    instance_id: str
142    challenge_id: str = ""
143    team_id: str = ""
144    node_id: str = ""
145    error: str = ""
146    stopped_at: float = 0.0

157class AdminSilentChallenge(CtfyModel):
158    """A challenge that has launches and submissions but no full solves —
159    a strong signal that the challenge or its flag is broken."""
160
161    challenge_id: str
162    name: str = ""
163    launches: int = 0
164    submissions: int = 0

18class AdminSolveCell(CtfyModel):
19    """One cell in the team × challenge solve matrix.
20
21    Unsolved cells are emitted when the team has at least one submission
22    against the challenge (``attempts > 0``) so the UI can distinguish
23    "tried and failed" from "never attempted".
24    """
25
26    team_id: str
27    challenge_id: str
28    solved: bool = False
29    solved_at: datetime | None = None
30    solve_time_s: float = 0.0
31    attempts: int = 0
32    # True when this team is the first (fastest) solver of the challenge.
33    first_blood: bool = False

50class AdminSolveMatrix(CtfyModel):
51    """Team × challenge solve matrix for the admin dashboard.
52
53    Rows (teams) and columns (challenges) pre-sorted — teams by solve count
54    desc, challenges by category → difficulty — so the frontend can render
55    the grid verbatim without re-sorting. Cells are sparse: only teams that
56    have at least attempted a challenge contribute a row there.
57    """
58
59    teams: list[AdminSolveMatrixTeam] = Field(default_factory=list)
60    challenges: list[AdminSolveMatrixChallenge] = Field(default_factory=list)
61    cells: list[AdminSolveCell] = Field(default_factory=list)

42class AdminSolveMatrixChallenge(CtfyModel):
43    challenge_id: str
44    name: str = ""
45    category: str = ""
46    difficulty: str = ""
47    solves_count: int = 0

36class AdminSolveMatrixTeam(CtfyModel):
37    team_id: str
38    name: str = ""
39    solved: int = 0

126class AdminStuckInstance(CtfyModel):
127    """A live instance stuck in STARTING for too long — likely a node-side
128    failure that didn't reconcile to ERROR cleanly."""
129
130    instance_id: str
131    challenge_id: str = ""
132    team_id: str = ""
133    node_id: str = ""
134    requested_at: float = 0.0
135    stuck_for_s: float = 0.0

490class AdminTaskInfo(CtfyModel):
491    """One background task on ``GET /admin/tasks`` / detail. A projection
492    of ``TaskState`` onto the wire (these routes are admin-only, so the
493    full ``error_detail`` traceback tail is included)."""
494
495    id: str = ""
496    kind: str = ""
497    status: str = ""
498    params: dict[str, Any] = Field(default_factory=dict)
499    result: dict[str, Any] = Field(default_factory=dict)
500    progress: float = 0.0
501    progress_message: str = ""
502    error: str = ""
503    error_detail: str = ""
504    cancel_requested: bool = False
505    created_by_user_id: str = ""
506    created_by_name: str = ""
507    created_at_ts: float = 0.0
508    started_at_ts: float = 0.0
509    finished_at_ts: float = 0.0

512class AdminTaskListResponse(CtfyModel):
513    """Paginated task list."""
514
515    items: list[AdminTaskInfo] = Field(default_factory=list)
516    total: int = 0
517    offset: int = 0
518    limit: int = 50

521class AdminTaskLogLine(CtfyModel):
522    """One verbose log line for a task (admin-only)."""
523
524    seq: int = 0
525    ts: float = 0.0
526    level: str = "info"
527    message: str = ""

530class AdminTaskLogsResponse(CtfyModel):
531    """A cursor page of task logs. ``next_after`` is the ``seq`` to pass as
532    ``?after=`` on the next poll (the last item's seq, or the request's
533    ``after`` when the page is empty — so an empty poll never rewinds the
534    cursor)."""
535
536    items: list[AdminTaskLogLine] = Field(default_factory=list)
537    next_after: int = 0

540class AdminTaskSubmitRequest(CtfyModel):
541    """Body of ``POST /admin/tasks``. ``kind`` is validated against the
542    runner's handler registry; ``params`` is the kind-specific input
543    (e.g. ``{"competition_id": ...}`` or ``{"job": "ttl_sweep"}``)."""
544
545    kind: str = ""
546    params: dict[str, Any] = Field(default_factory=dict)

281class AdminTeamRow(CtfyModel):
282    """One row of the organiser's team table.
283
284    Deliberately **not** ``TeamInfo`` plus a field. ``TeamInfo`` is the
285    public projection, and standing is not public: a disqualification
286    reaches the team and the organisers, and announcing it more widely is
287    the organiser's call — the same reasoning that keeps
288    ``team_disqualified`` off the public SSE feed. Putting
289    ``disqualified`` on the public model would publish the verdict on
290    every team page, from a route nobody had to think about.
291
292    Also **not** ``RegistrationTeamRow``: that one carries every member's
293    sealed personal details and lands an audit row for the bulk read.
294    Managing a roster does not need anybody's phone number, and paying
295    that price to render a table would make the audit trail meaningless
296    by filling it with routine work.
297    """
298
299    id: str
300    name: str
301    description: str = ""
302    competition_id: str = ""
303    captain_user_id: str = ""
304    captain_display_name: str = ""
305    member_count: int = 0
306    created_at: datetime | None = None
307    review_status: str = ""
308    disqualified: bool = False
309    disqualified_at: datetime | None = None
310    disqualification_reason: str = ""
311    members: list[TeamMemberInfo] = Field(default_factory=list)

197class AdminTimeseries(CtfyModel):
198    """24h-by-default bucketed counts driving the admin Overview pulse charts."""
199
200    metric: str = ""
201    window_s: int = 0
202    bucket_s: int = 0
203    buckets: list[AdminTimeseriesBucket] = Field(default_factory=list)

177class AdminTimeseriesBucket(CtfyModel):
178    """One bucket of an admin time-series chart.
179
180    ``ts`` is the right edge of the bucket in Unix seconds — the natural
181    point to evaluate "active right now" metrics like running_instances —
182    and the natural label to render at the right of the bucket on the
183    frontend.
184
185    ``partial=True`` marks the rightmost bucket whose right edge is
186    ``now``; it represents an in-progress window that hasn't finished
187    accumulating yet. The frontend renders these with a "live" indicator
188    (semi-transparent fill, pulsing label) to signal the value will
189    grow until the bucket's right edge passes.
190    """
191
192    ts: float = 0.0
193    value: int = 0
194    partial: bool = False

291class AdminTrafficInstanceRow(CtfyModel):
292    """One instance × team × challenge row for the admin traffic dashboard."""
293
294    instance_id: str
295    team_id: str
296    team_name: str = ""
297    challenge_id: str = ""
298    name: str = ""
299    status: str = ""
300    request_count: int = 0
301    started_at: float = 0.0
302    stopped_at: float = 0.0
303    # ``True`` if the instance is still running (request_count is approximate
304    # — refreshed only when the dashboard re-fetches).
305    live: bool = False

308class AdminTrafficSummary(CtfyModel):
309    """Top-level response for ``GET /admin/traffic/summary``."""
310
311    teams: list[AdminTrafficTeamRow] = Field(default_factory=list)
312    instances: list[AdminTrafficInstanceRow] = Field(default_factory=list)
313    total_requests: int = 0

276class AdminTrafficTeamRow(CtfyModel):
277    """Per-team aggregate row for the admin traffic dashboard.
278
279    Sums HTTP request counts across every archived instance the team has
280    ever launched, plus the live count for any instances the team is
281    still running.
282    """
283
284    team_id: str
285    team_name: str = ""
286    instance_count: int = 0
287    request_count: int = 0
288    last_activity_at: float = 0.0

149class AdminUnhealthyNode(CtfyModel):
150    node_id: str
151    display_name: str = ""
152    url: str = ""
153    last_heartbeat_ts: float = 0.0
154    downtime_s: float = 0.0

77class AdminUserInfo(UserInfo):
78    """Admin-only view of a user. Carries the privilege tier and the
79    most recent role-change audit fields."""
80
81    email: str = ""
82    role: Literal["user", "admin", "super_admin"] = "user"
83    promoted_by: str | None = None
84    promoted_at: datetime | None = None
85    # OAuth providers the user has bound (e.g. ``["github", "google"]``),
86    # so the admin user list can surface which SSO accounts are linked.
87    providers: list[str] = Field(default_factory=list)

14class AnnouncementCreate(CtfyModel):
15    """Request body for ``POST /admin/announcements``.
16
17    Time fields accept ISO 8601 strings; empty means "no bound" (live
18    immediately / never expires). Severity defaults to ``info`` so a
19    minimal "title + body" payload still validates.
20    """
21
22    title: str = Field(min_length=1, max_length=200)
23    body: str = Field(default="", max_length=20000)
24    severity: AnnouncementSeverity = "info"
25    starts_at: datetime | None = None
26    ends_at: datetime | None = None

39class AnnouncementInfo(CtfyModel):
40    """Response shape — mirrors ``AnnouncementState`` field-for-field."""
41
42    id: str
43    title: str
44    body: str
45    severity: AnnouncementSeverity
46    starts_at: datetime | None = None
47    ends_at: datetime | None = None
48    created_at: datetime | None = None
49    updated_at: datetime | None = None
50    created_by: str
51    created_by_name: str