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)

239class AdminOverview(CtfyModel):
240    """Single aggregate payload for the admin landing page."""
241
242    nodes: AdminOverviewCounts = Field(default_factory=AdminOverviewCounts)
243    capacity: int = 0
244    running_instances: int = 0
245    teams_total: int = 0
246    solves_total: int = 0
247    solves_today: int = 0
248    # User-engagement counters — the "are people actually on the platform right
249    # now?" signal the infra/challenge/team metrics above don't answer.
250    # ``users_active_24h`` is distinct humans who triggered a write action
251    # (launch / submit / solve / join / answer) in the last 24h, not raw logins
252    # (pure browsing leaves no activity row). ``users_new_24h`` is registrations
253    # in the same window. All default to 0 so the field set stays additive.
254    users_total: int = 0
255    users_active_24h: int = 0
256    users_new_24h: int = 0

64class AdminOverviewCounts(CtfyModel):
65    total: int = 0
66    healthy: 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

388class AdminTaskInfo(CtfyModel):
389    """One background task on ``GET /admin/tasks`` / detail. A projection
390    of ``TaskState`` onto the wire (these routes are admin-only, so the
391    full ``error_detail`` traceback tail is included)."""
392
393    id: str = ""
394    kind: str = ""
395    status: str = ""
396    params: dict[str, Any] = Field(default_factory=dict)
397    result: dict[str, Any] = Field(default_factory=dict)
398    progress: float = 0.0
399    progress_message: str = ""
400    error: str = ""
401    error_detail: str = ""
402    cancel_requested: bool = False
403    created_by_user_id: str = ""
404    created_by_name: str = ""
405    created_at_ts: float = 0.0
406    started_at_ts: float = 0.0
407    finished_at_ts: float = 0.0

410class AdminTaskListResponse(CtfyModel):
411    """Paginated task list."""
412
413    items: list[AdminTaskInfo] = Field(default_factory=list)
414    total: int = 0
415    offset: int = 0
416    limit: int = 50

419class AdminTaskLogLine(CtfyModel):
420    """One verbose log line for a task (admin-only)."""
421
422    seq: int = 0
423    ts: float = 0.0
424    level: str = "info"
425    message: str = ""

428class AdminTaskLogsResponse(CtfyModel):
429    """A cursor page of task logs. ``next_after`` is the ``seq`` to pass as
430    ``?after=`` on the next poll (the last item's seq, or the request's
431    ``after`` when the page is empty — so an empty poll never rewinds the
432    cursor)."""
433
434    items: list[AdminTaskLogLine] = Field(default_factory=list)
435    next_after: int = 0

438class AdminTaskSubmitRequest(CtfyModel):
439    """Body of ``POST /admin/tasks``. ``kind`` is validated against the
440    runner's handler registry; ``params`` is the kind-specific input
441    (e.g. ``{"competition_id": ...}`` or ``{"job": "ttl_sweep"}``)."""
442
443    kind: str = ""
444    params: dict[str, Any] = Field(default_factory=dict)

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

274class AdminTrafficInstanceRow(CtfyModel):
275    """One instance × team × challenge row for the admin traffic dashboard."""
276
277    instance_id: str
278    team_id: str
279    team_name: str = ""
280    challenge_id: str = ""
281    name: str = ""
282    status: str = ""
283    request_count: int = 0
284    started_at: float = 0.0
285    stopped_at: float = 0.0
286    # ``True`` if the instance is still running (request_count is approximate
287    # — refreshed only when the dashboard re-fetches).
288    live: bool = False

291class AdminTrafficSummary(CtfyModel):
292    """Top-level response for ``GET /admin/traffic/summary``."""
293
294    teams: list[AdminTrafficTeamRow] = Field(default_factory=list)
295    instances: list[AdminTrafficInstanceRow] = Field(default_factory=list)
296    total_requests: int = 0

259class AdminTrafficTeamRow(CtfyModel):
260    """Per-team aggregate row for the admin traffic dashboard.
261
262    Sums HTTP request counts across every archived instance the team has
263    ever launched, plus the live count for any instances the team is
264    still running.
265    """
266
267    team_id: str
268    team_name: str = ""
269    instance_count: int = 0
270    request_count: int = 0
271    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

72class AdminUserInfo(UserInfo):
73    """Admin-only view of a user. Carries the privilege tier and the
74    most recent role-change audit fields."""
75
76    email: str = ""
77    role: Literal["user", "admin", "super_admin"] = "user"
78    promoted_by: str | None = None
79    promoted_at: datetime | None = None
80    # OAuth providers the user has bound (e.g. ``["github", "google"]``),
81    # so the admin user list can surface which SSO accounts are linked.
82    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

29class AnnouncementUpdate(CtfyModel):
30    """PATCH body — every field optional, ``None`` means "leave alone"."""
31
32    title: str | None = Field(default=None, min_length=1, max_length=200)
33    body: str | None = Field(default=None, max_length=20000)
34    severity: AnnouncementSeverity | None = None
35    starts_at: datetime | None = None
36    ends_at: datetime | None = None

85class AttachmentList(CtfyModel):
86    """Response payload for ``GET /challenges/{id}/attachments``.
87
88    Same data as ``ChallengeInfo.attachments`` but addressable directly
89    so pre-launch UI / agent tooling can fetch it without paging through
90    the catalog. Order matches the on-disk sort.
91    """
92
93    files: list[AttachmentInfo] = Field(default_factory=list)

72class AuthTokenResponse(CtfyModel):
73    """Returned by ``POST /auth/register`` and ``POST /auth/login``.
74
75    The plaintext user token is returned directly (not via fragment) since
76    these endpoints are called by first-party XHR, not redirects.
77    """
78
79    token: str
80    redirect_to: str = "/"

122class CalendarBucket(CtfyModel):
123    """One UTC-day cell on the contribution calendar.
124
125    ``count`` aggregates correct submissions + first-time solves on that
126    day; effectively "did anything productive happen". The series is
127    dense — every day in the requested window is present, zero-filled."""
128
129    date: str = ""  # YYYY-MM-DD, UTC
130    count: int = 0

215class ChallengeBuildKickoffNodeResult(CtfyModel):
216    """One node's response to a build kickoff (single or all).
217
218    ``queued`` is populated only on the ``build-all`` fan-out; for the
219    single-challenge variant the platform inspects ``status`` to learn
220    what the node accepted.
221    """
222
223    node_id: str
224    ok: bool
225    status: str = ""
226    queued: list[str] = Field(default_factory=list)
227    skipped_built: list[str] = Field(default_factory=list)
228    skipped_in_progress: list[str] = Field(default_factory=list)
229    error: str = ""

232class ChallengeBuildKickoffResponse(CtfyModel):
233    """Admin ``POST /admin/challenges/{id}/build`` and ``…/build-all`` response."""
234
235    challenge_id: str = ""  # empty for build-all
236    nodes: list[ChallengeBuildKickoffNodeResult] = Field(default_factory=list)

172class ChallengeBuildNodeState(CtfyModel):
173    """One worker node's view of a single challenge's build state.
174
175    ``status`` is one of ``unbuilt`` / ``building`` / ``built`` /
176    ``failed``. ``node_error`` is non-empty only when the platform
177    could not reach the node at all (heartbeat stale / 5xx) — in that
178    case ``status`` is forced to ``unbuilt`` for the aggregate.
179    """
180
181    node_id: str
182    status: str = "unbuilt"
183    built_at: float = 0.0
184    error: str = ""
185    node_error: str = ""

209class ChallengeBuildStateResponse(CtfyModel):
210    """Admin ``GET /admin/challenges/build-state`` response."""
211
212    rows: list[ChallengeBuildStateRow] = Field(default_factory=list)

188class ChallengeBuildStateRow(CtfyModel):
189    """Per-challenge build state aggregated across every online node.
190
191    ``aggregated`` rolls up ``nodes`` using a worst-case rule so the
192    table's single status column behaves intuitively:
193
194    * any ``building`` → ``building`` (yellow)
195    * any ``failed``  → ``failed`` (red)
196    * any ``unbuilt`` → ``unbuilt`` (grey)
197    * else            → ``built`` (green)
198
199    A node that couldn't be reached at all contributes ``unbuilt`` so
200    the aggregate stays conservative — the admin still sees a
201    "missing" pip and can drill into the modal to find out why.
202    """
203
204    challenge_id: str
205    aggregated: str = "unbuilt"
206    nodes: list[ChallengeBuildNodeState] = Field(default_factory=list)

 96class ChallengeFacetCount(CtfyModel):
 97    """One bucket on the challenge catalog facet summary.
 98
 99    ``value`` is the difficulty / tag string; ``total`` is how many
100    challenges in scope carry it. ``solved`` is the *calling* user's
101    solved count in that bucket (across every team they have been on);
102    it is 0 for anonymous callers and for tag buckets (the UI only
103    renders a solved/total ratio for difficulty).
104    """
105
106    value: str
107    total: int = 0
108    solved: int = 0

111class ChallengeFacets(CtfyModel):
112    """Catalog aggregates for the Challenges page side panels + filter
113    pill counts — served by ``GET /challenges/facets`` so the page no
114    longer derives them from a bulk fetch of the whole catalog.
115
116    Scoped by ``competition_id`` (when given) exactly like the list
117    endpoint, so the pills/charts reflect the same subset the paged
118    list pages through.
119    """
120
121    total: int = 0
122    difficulty: list[ChallengeFacetCount] = Field(default_factory=list)
123    # Per-category counts (only categories with ≥1 challenge in scope
124    # show up). Ordered by the canonical category sequence so the
125    # filter pills always render web → pwn → reverse → crypto → misc.
126    category: list[ChallengeFacetCount] = Field(default_factory=list)
127    tags: list[ChallengeFacetCount] = Field(default_factory=list)
128    # Per-status counts for the calling caller (``solved`` / ``unsolved``
129    # / ``running``). Drives the count chip on each status filter pill
130    # so the page doesn't N+1 a status-filtered list per pill. Buckets
131    # are always present (in canonical order) for layout stability; on
132    # anonymous callers every count is 0 — never leaking another
133    # team's state.
134    status: list[ChallengeFacetCount] = Field(default_factory=list)

304class ChallengeFlagStats(CtfyModel):
305    """Per-flag aggregate for one challenge (for the detail page)."""
306
307    flag_id: str
308    solves_count: int = 0

45class ChallengeInfo(CtfyModel):
46    id: str
47    name: str
48    category: ChallengeCategory = ChallengeCategory.WEB
49    difficulty: str = ""
50    description: str = ""
51    # Full-challenge solves: teams that captured every declared
52    # question (across all modes — dynamic + static + select).
53    solves_count: int = 0
54    # Times this challenge has been instantiated, ever — one per
55    # archived InstanceRecord (every terminal path writes one). A
56    # "how much has this been run" signal for the challenge card;
57    # platform-wide, not scoped to the viewing team or competition.
58    launch_count: int = 0
59    tags: list[str] = Field(default_factory=list)
60    # Every question declared on this challenge, in author-declared
61    # order. Single-question challenges have a single entry with
62    # id ``"flag"``. ``QuestionPublicInfo`` exposes prompt/mode/choices
63    # but never the answer.
64    questions: list[QuestionPublicInfo] = Field(default_factory=list)
65    # Per-question solve counts (how many teams captured each
66    # question). Keyed by question id. Useful for the challenge
67    # detail page's progress breakdown. Counts span every mode;
68    # the multi_select grader records one solve per fully-correct
69    # submission, not per chosen choice.
70    flag_solves: dict[str, int] = Field(default_factory=dict)
71    # Files shipped under the challenge's ``attachments/`` directory,
72    # downloadable via ``GET /challenges/{id}/attachments/{name}``.
73    # Empty for pure-network challenges that ship nothing.
74    attachments: list[AttachmentInfo] = Field(default_factory=list)
75    # True for pure question-answer challenges (``category: misc``,
76    # no ``docker-compose.yml`` on disk, every declared question
77    # carries a static ``answer:``). The frontend keys off this flag
78    # to switch the competition surface to a quiz UI and skip the
79    # launch-confirm flow. Source of truth lives in
80    # :attr:`ctfy.core.challenge.ChallengeSpec.is_qa_only`, ultimately
81    # derived from :attr:`BenchmarkContext.is_qa_only`.
82    is_qa_only: bool = False