test-base 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. test_base/__init__.py +20 -0
  2. test_base/adapters/__init__.py +354 -0
  3. test_base/adapters/base.py +263 -0
  4. test_base/adapters/canonical_json.py +1088 -0
  5. test_base/adapters/junit_xml.py +1272 -0
  6. test_base/api/__init__.py +0 -0
  7. test_base/api/app.py +314 -0
  8. test_base/api/deps.py +178 -0
  9. test_base/api/routes/__init__.py +0 -0
  10. test_base/api/routes/failures.py +104 -0
  11. test_base/api/routes/health.py +35 -0
  12. test_base/api/routes/imports.py +143 -0
  13. test_base/api/routes/queries.py +295 -0
  14. test_base/api/routes/retention.py +130 -0
  15. test_base/api/routes/runs.py +147 -0
  16. test_base/api/routes/server.py +65 -0
  17. test_base/api/routes/stream.py +117 -0
  18. test_base/api/schemas.py +390 -0
  19. test_base/api/security.py +183 -0
  20. test_base/cli/__init__.py +125 -0
  21. test_base/cli/commands/__init__.py +0 -0
  22. test_base/cli/commands/db.py +76 -0
  23. test_base/cli/commands/demo.py +103 -0
  24. test_base/cli/commands/formats.py +41 -0
  25. test_base/cli/commands/ingest.py +119 -0
  26. test_base/cli/commands/init.py +738 -0
  27. test_base/cli/commands/prune.py +146 -0
  28. test_base/cli/commands/publish.py +133 -0
  29. test_base/cli/commands/serve.py +118 -0
  30. test_base/cli/commands/token.py +97 -0
  31. test_base/cli/options.py +189 -0
  32. test_base/cli/render.py +223 -0
  33. test_base/config.py +519 -0
  34. test_base/demo/__init__.py +0 -0
  35. test_base/demo/evidence.py +447 -0
  36. test_base/demo/seed.py +628 -0
  37. test_base/domain/__init__.py +61 -0
  38. test_base/domain/events.py +422 -0
  39. test_base/domain/failures.py +327 -0
  40. test_base/domain/identity.py +205 -0
  41. test_base/domain/metrics.py +176 -0
  42. test_base/domain/models.py +947 -0
  43. test_base/domain/status.py +246 -0
  44. test_base/errors.py +136 -0
  45. test_base/logging.py +174 -0
  46. test_base/py.typed +0 -0
  47. test_base/sdk/__init__.py +28 -0
  48. test_base/sdk/client.py +607 -0
  49. test_base/service/__init__.py +0 -0
  50. test_base/service/bus.py +331 -0
  51. test_base/service/coalesce.py +133 -0
  52. test_base/service/imports.py +552 -0
  53. test_base/service/retention.py +640 -0
  54. test_base/service/runs.py +394 -0
  55. test_base/service/runtime.py +123 -0
  56. test_base/storage/__init__.py +41 -0
  57. test_base/storage/artifacts.py +347 -0
  58. test_base/storage/base.py +350 -0
  59. test_base/storage/db.py +595 -0
  60. test_base/storage/failures.py +321 -0
  61. test_base/storage/locks.py +104 -0
  62. test_base/storage/migrations/env.py +108 -0
  63. test_base/storage/migrations/script.py.mako +26 -0
  64. test_base/storage/migrations/versions/0001_initial.py +289 -0
  65. test_base/storage/migrations/versions/0002_retention_indexes.py +38 -0
  66. test_base/storage/migrations/versions/0003_postgresql_bigint.py +74 -0
  67. test_base/storage/migrations/versions/0004_run_shards.py +37 -0
  68. test_base/storage/migrations/versions/0005_failure_groups.py +206 -0
  69. test_base/storage/models.py +560 -0
  70. test_base/storage/repositories.py +2481 -0
  71. test_base/storage/uow.py +138 -0
  72. test_base/version.py +17 -0
  73. test_base/web/assets/css/app.css +3567 -0
  74. test_base/web/assets/favicon.svg +5 -0
  75. test_base/web/assets/js/00-util.js +829 -0
  76. test_base/web/assets/js/05-windows.js +551 -0
  77. test_base/web/assets/js/10-provider.js +396 -0
  78. test_base/web/assets/js/12-live-provider.js +804 -0
  79. test_base/web/assets/js/20-charts.js +715 -0
  80. test_base/web/assets/js/30-store.js +793 -0
  81. test_base/web/assets/js/40-components.js +2141 -0
  82. test_base/web/assets/js/42-timeline.js +629 -0
  83. test_base/web/assets/js/50-view-overview.js +747 -0
  84. test_base/web/assets/js/52-view-analytics.js +842 -0
  85. test_base/web/assets/js/53-view-suites.js +508 -0
  86. test_base/web/assets/js/54-view-metrics.js +438 -0
  87. test_base/web/assets/js/55-view-runs.js +244 -0
  88. test_base/web/assets/js/56-view-evidence.js +703 -0
  89. test_base/web/assets/js/57-view-failures.js +596 -0
  90. test_base/web/assets/js/60-view-run.js +788 -0
  91. test_base/web/assets/js/65-view-test.js +402 -0
  92. test_base/web/assets/js/70-view-settings.js +524 -0
  93. test_base/web/assets/js/75-view-help.js +554 -0
  94. test_base/web/assets/js/80-settings.js +99 -0
  95. test_base/web/assets/js/85-activity.js +727 -0
  96. test_base/web/assets/js/90-app.js +595 -0
  97. test_base/web/assets/manifest.json +70 -0
  98. test_base/web/index.html +210 -0
  99. test_base-0.1.1.dist-info/METADATA +285 -0
  100. test_base-0.1.1.dist-info/RECORD +103 -0
  101. test_base-0.1.1.dist-info/WHEEL +4 -0
  102. test_base-0.1.1.dist-info/entry_points.txt +6 -0
  103. test_base-0.1.1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,390 @@
1
+ """Request and response bodies for ``/api/v1``.
2
+
3
+ These are the *public* contract — separate from the canonical domain models they
4
+ wrap, and separate again from the ORM (ADR-0001 D3). Responses mostly re-export
5
+ domain models unchanged; requests are their own thing, because what a publisher
6
+ is allowed to *send* is a much smaller surface than what Test Base *stores*. You
7
+ cannot, for instance, post a run's counts: they are derived, and accepting them
8
+ would create two sources of truth for the number on the front page.
9
+
10
+ Every model forbids unknown fields. A publisher with a typo in a field name gets
11
+ a 422 naming the field rather than a silently ignored value and a wrong dashboard.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import uuid
17
+ from typing import Annotated, Any
18
+
19
+ from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, field_validator
20
+
21
+ from test_base.domain.events import DomainEvent
22
+ from test_base.domain.failures import TriageStatus
23
+ from test_base.domain.models import (
24
+ Artifact,
25
+ ArtifactKind,
26
+ ImportResult,
27
+ Project,
28
+ RunContext,
29
+ RunCounts,
30
+ RunSummary,
31
+ ShardRef,
32
+ TestRun,
33
+ TestType,
34
+ TriggerType,
35
+ utcnow,
36
+ )
37
+ from test_base.domain.status import RunStatus
38
+ from test_base.version import SCHEMA_VERSION, __version__
39
+
40
+ __all__ = [
41
+ "ArtifactResponse",
42
+ "CreateRunRequest",
43
+ "ErrorResponse",
44
+ "EventsRequest",
45
+ "EventsResponse",
46
+ "FinishRunRequest",
47
+ "HealthResponse",
48
+ "ImportResponse",
49
+ "ProjectListResponse",
50
+ "PruneRequest",
51
+ "PruneResponse",
52
+ "RetentionSettingsResponse",
53
+ "RunListResponse",
54
+ "ServerDatabase",
55
+ "ServerInfoResponse",
56
+ ]
57
+
58
+
59
+ class _Request(BaseModel):
60
+ model_config = ConfigDict(extra="forbid", str_strip_whitespace=True, populate_by_name=True)
61
+
62
+
63
+ class _Response(BaseModel):
64
+ model_config = ConfigDict(extra="forbid")
65
+
66
+
67
+ # ------------------------------------------------------------------ requests
68
+
69
+
70
+ class CreateRunRequest(_Request):
71
+ """``POST /api/v1/runs``.
72
+
73
+ ``run_id`` is optional and, when supplied, makes the call idempotent: a CI
74
+ step that is retried announces the same run rather than creating a second.
75
+ Publishers that can generate a UUID should always send one.
76
+ """
77
+
78
+ project_key: Annotated[str, Field(min_length=1, max_length=120)]
79
+ run_id: uuid.UUID | None = None
80
+ name: str | None = None
81
+ team: str | None = None
82
+ component: str | None = None
83
+ test_type: TestType = TestType.OTHER
84
+ trigger: TriggerType = TriggerType.UNKNOWN
85
+ context: RunContext = Field(default_factory=RunContext)
86
+ tags: list[str] = Field(default_factory=list, max_length=64)
87
+ metadata: dict[str, Any] = Field(default_factory=dict)
88
+ expected_tests: int | None = Field(
89
+ default=None, ge=0, description="Collected test count, if known before execution."
90
+ )
91
+ started: bool = Field(
92
+ default=True, description="False to open the run as queued rather than running."
93
+ )
94
+ run_key: str | None = Field(
95
+ default=None,
96
+ max_length=512,
97
+ description="Name of the CI run, e.g. $GITHUB_RUN_ID, instead of run_id: every "
98
+ "publisher sending the same key and project opens the same run.",
99
+ )
100
+ shard: ShardRef | None = Field(
101
+ default=None,
102
+ description="Which slice of a sharded run this publisher is; the run then stays open "
103
+ "until every shard has finished.",
104
+ )
105
+
106
+
107
+ class EventsRequest(_Request):
108
+ """``POST /api/v1/runs/{run_id}/events``.
109
+
110
+ Send ``sequence: 0`` on every event to have the server allocate a contiguous
111
+ block; send your own monotonic numbers if you want gap detection, which you
112
+ probably do for a long-running suite.
113
+ """
114
+
115
+ events: Annotated[list[DomainEvent], Field(min_length=1, max_length=5000)]
116
+
117
+
118
+ class FinishRunRequest(_Request):
119
+ """``POST /api/v1/runs/{run_id}/finish``.
120
+
121
+ ``status`` is advisory and only honoured for ``cancelled``; every other
122
+ outcome is folded from the results that were actually reported.
123
+ """
124
+
125
+ finished_at: AwareDatetime | None = None
126
+ status: RunStatus | None = None
127
+ duration_ms: int | None = Field(default=None, ge=0)
128
+ metadata: dict[str, Any] = Field(default_factory=dict)
129
+ shard: ShardRef | None = Field(
130
+ default=None,
131
+ description="Finish one shard rather than the run. Without it the whole run closes, "
132
+ "including shards that never reported.",
133
+ )
134
+
135
+
136
+ # ----------------------------------------------------------------- responses
137
+
138
+
139
+ class ImportResponse(_Response):
140
+ """``POST /api/v1/imports``.
141
+
142
+ Deliberately verbose: which adapter was chosen and how confident detection
143
+ was are the first two questions asked when an import produces a surprise.
144
+ """
145
+
146
+ result: ImportResult
147
+
148
+
149
+ class RunListResponse(_Response):
150
+ runs: list[RunSummary]
151
+ total: int
152
+ limit: int
153
+ offset: int
154
+
155
+
156
+ class ProjectListResponse(_Response):
157
+ projects: list[Project]
158
+
159
+
160
+ class EventsResponse(_Response):
161
+ """What applying a batch did.
162
+
163
+ ``ignored`` is how a publisher confirms idempotency worked: repost a batch
164
+ and every event comes back ignored, with the counts unchanged.
165
+ """
166
+
167
+ run_id: uuid.UUID
168
+ applied: int
169
+ ignored: int
170
+ created_run: bool
171
+ counts: RunCounts
172
+ status: RunStatus
173
+
174
+
175
+ class ArtifactResponse(_Response):
176
+ artifact: Artifact
177
+ deduplicated: bool = Field(
178
+ default=False, description="True when identical content was already stored."
179
+ )
180
+
181
+
182
+ class RunResponse(_Response):
183
+ run: TestRun
184
+
185
+
186
+ class ArtifactListResponse(_Response):
187
+ artifacts: list[Artifact]
188
+
189
+
190
+ class ErrorResponse(_Response):
191
+ """The single error shape every failing endpoint returns."""
192
+
193
+ error: str = Field(description="Stable machine-readable code, e.g. `unknown_format`.")
194
+ message: str
195
+ detail: dict[str, Any] = Field(default_factory=dict)
196
+
197
+
198
+ class AdapterInfo(_Response):
199
+ """One row of ``GET /api/v1/adapters``.
200
+
201
+ Extra keys from an adapter's ``describe()`` are ignored rather than rejected:
202
+ a third-party adapter is entitled to describe itself with fields this build
203
+ has never heard of, and refusing the whole listing over one of them would
204
+ make an unrelated plugin able to break the endpoint.
205
+ """
206
+
207
+ model_config = ConfigDict(extra="ignore")
208
+
209
+ name: str
210
+ display_name: str = ""
211
+ description: str = ""
212
+ priority: int = 0
213
+ extensions: list[str] = Field(default_factory=list)
214
+ content_types: list[str] = Field(default_factory=list)
215
+
216
+
217
+ class AdapterListResponse(_Response):
218
+ adapters: list[AdapterInfo]
219
+
220
+
221
+ class HealthResponse(_Response):
222
+ """``GET /healthz`` — cheap enough for a container healthcheck every 10s."""
223
+
224
+ status: str = "ok"
225
+ version: str = __version__
226
+ schema_version: int = SCHEMA_VERSION
227
+ database: str = "ok"
228
+ workspace_id: uuid.UUID | None = None
229
+ live_subscribers: int = 0
230
+ time: AwareDatetime = Field(default_factory=utcnow)
231
+
232
+
233
+ class ServerDatabase(_Response):
234
+ """The database this server writes to."""
235
+
236
+ backend: str = Field(description="`sqlite` or `postgresql`.")
237
+ label: str = Field(description="`SQLite` or `PostgreSQL`, for display.")
238
+ server: str | None = Field(
239
+ default=None,
240
+ description="Engine and version, such as `PostgreSQL 16.4`. Administrators only.",
241
+ )
242
+ location: str | None = Field(
243
+ default=None,
244
+ description="The SQLite file, or the PostgreSQL URL without driver or password. "
245
+ "Administrators only.",
246
+ )
247
+
248
+
249
+ class ServerInfoResponse(_Response):
250
+ """``GET /api/v1/server`` — what this server runs on, for Settings and Help.
251
+
252
+ Which kind of database is no secret; where it lives is. A host name, a
253
+ database user and a home directory in a path are a small map of the
254
+ infrastructure, so those fields are filled for administrators only
255
+ (:func:`test_base.api.deps.is_admin`) and are ``null`` for everyone else.
256
+ """
257
+
258
+ admin: bool = Field(description="Whether this caller may see the details.")
259
+ auth_enabled: bool = Field(
260
+ description="Whether publishing needs a token. No secret: an unauthenticated POST "
261
+ "answers the same question with a 401."
262
+ )
263
+ version: str = Field(default=__version__, description="The Test Base version.")
264
+ database: ServerDatabase
265
+ artifacts_dir: str | None = Field(default=None, description="Administrators only.")
266
+ settings_file: str | None = Field(
267
+ default=None,
268
+ description="The settings file `test-base init` saved, when there is one. "
269
+ "Administrators only.",
270
+ )
271
+
272
+
273
+ ARTIFACT_KINDS = [kind.value for kind in ArtifactKind]
274
+
275
+
276
+ # ----------------------------------------------------------------- retention
277
+
278
+
279
+ class RetentionSettingsResponse(_Response):
280
+ """What the dashboard needs to draw the retention panel.
281
+
282
+ ``admin`` is about *this caller*, not about the server: it answers "may the
283
+ person holding this page delete anything", which is the only question the UI
284
+ can act on. A dashboard that drew a delete button and then got a 403 would be
285
+ worse than one that never drew it.
286
+ """
287
+
288
+ admin: bool = Field(description="Whether this caller may run a prune.")
289
+ retention_days: int | None = Field(
290
+ default=None, description="The configured default cutoff, if any."
291
+ )
292
+ min_runs: int = Field(description="Runs always kept per project.")
293
+ grace_hours: float = Field(description="How long a new artifact blob is protected.")
294
+ units: dict[str, int] = Field(description="The duration grammar, in hours per unit.")
295
+
296
+
297
+ class PruneRequest(_Request):
298
+ """A cutoff, expressed the way the caller prefers.
299
+
300
+ Exactly one of ``older_than`` and ``before``. ``confirm`` is required for the
301
+ destructive endpoint and ignored by the preview: an API that deletes a year
302
+ of history on a request a client sent by accident is an API with one field
303
+ missing.
304
+ """
305
+
306
+ older_than: str | None = Field(
307
+ default=None,
308
+ description="A duration: 90d, 6m, 2w, 1y, 12h, or a bare number of days.",
309
+ )
310
+ before: AwareDatetime | None = Field(
311
+ default=None, description="An absolute cutoff. Runs at or before it are removed."
312
+ )
313
+ keep_min: int | None = Field(
314
+ default=None, ge=0, description="Runs kept per project. Defaults to the server setting."
315
+ )
316
+ project_keys: list[str] = Field(default_factory=list, description="Restrict to these projects.")
317
+ by_import_date: bool = Field(
318
+ default=False, description="Cut on when the run was imported, not when it ran."
319
+ )
320
+ include_unfinished: bool = Field(
321
+ default=False, description="Also remove queued and running runs past the cutoff."
322
+ )
323
+ confirm: bool = Field(default=False, description="Required by the destructive endpoint.")
324
+
325
+
326
+ class PruneResponse(_Response):
327
+ """What a prune did, or — when ``dry_run`` — what it would do."""
328
+
329
+ dry_run: bool
330
+ cutoff: AwareDatetime
331
+ runs: int
332
+ rows: int
333
+ deleted: dict[str, int]
334
+ blobs_unlinked: int
335
+ blobs_retained: int
336
+ bytes_freed: int
337
+ skipped_live: int
338
+ protected: int
339
+ batches: int
340
+ vacuumed: bool = Field(
341
+ default=False,
342
+ description=(
343
+ "Always false over HTTP. VACUUM rewrites the whole database behind an "
344
+ "exclusive lock, which is not something a web request should start; run "
345
+ "`test-base prune --vacuum` on the host to reclaim the file space."
346
+ ),
347
+ )
348
+ by_project: dict[str, int]
349
+ oldest: AwareDatetime | None = None
350
+ newest: AwareDatetime | None = None
351
+
352
+
353
+ # ------------------------------------------------------------------ triage
354
+
355
+
356
+ class TriageRequest(_Request):
357
+ """``PATCH /api/v1/failures/{fingerprint}``.
358
+
359
+ Only the fields present change. ``null`` or an empty string clears
360
+ ``owner``, ``issue_url`` and ``note``; ``status`` cannot be cleared, only
361
+ set — ``untriaged`` is how to take a verdict back.
362
+ """
363
+
364
+ status: TriageStatus | None = None
365
+ owner: Annotated[str, Field(max_length=120)] | None = None
366
+ issue_url: Annotated[str, Field(max_length=2048)] | None = None
367
+ note: Annotated[str, Field(max_length=4000)] | None = None
368
+
369
+ @field_validator("status", mode="before")
370
+ @classmethod
371
+ def _settable(cls, value: object) -> object:
372
+ # Sent as null, it would be a verdict that changes nothing yet still
373
+ # stamps the group as triaged just now.
374
+ if value is None:
375
+ raise ValueError("status cannot be cleared; set it to untriaged instead")
376
+ return value
377
+
378
+ @field_validator("owner", "issue_url", "note", mode="before")
379
+ @classmethod
380
+ def _strip(cls, value: object) -> object:
381
+ return value.strip() if isinstance(value, str) else value
382
+
383
+ @field_validator("issue_url")
384
+ @classmethod
385
+ def _web_link(cls, value: str | None) -> str | None:
386
+ # A link the dashboard renders as an <a href>: only http(s), so a
387
+ # `javascript:` URL can never become one.
388
+ if value and not value.lower().startswith(("http://", "https://")):
389
+ raise ValueError("issue_url must be an http:// or https:// link")
390
+ return value or None
@@ -0,0 +1,183 @@
1
+ """Bearer-token authentication, and the token hashing behind it.
2
+
3
+ Test Base stores **only hashes**. A stolen database gives an attacker a list of
4
+ PBKDF2 digests, not a list of working tokens. The plaintext exists exactly once,
5
+ in the terminal output of ``test-base token create``, and it is the operator's job
6
+ to put it somewhere safe from there.
7
+
8
+ Why PBKDF2 rather than a bare SHA-256 of a random token: the tokens *we* generate
9
+ carry 256 bits of entropy and a bare hash would be fine for them, but nothing
10
+ stops an operator setting ``TEST_BASE_API_TOKENS=letmein``. PBKDF2 makes that
11
+ mistake expensive to exploit instead of free. To keep the per-request cost off
12
+ the hot path, a successful verification is memoized for the life of the process,
13
+ keyed on a SHA-256 of the presented token — so the KDF runs once per distinct
14
+ token, not once per request.
15
+
16
+ Everything here is timing-safe: :func:`hmac.compare_digest` for the comparison,
17
+ and a uniform "invalid token" response whether the token was unknown, malformed
18
+ or simply absent.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import hashlib
24
+ import hmac
25
+ import secrets
26
+ from dataclasses import dataclass, field
27
+
28
+ from test_base.errors import AuthenticationError, ConfigurationError
29
+
30
+ __all__ = [
31
+ "PBKDF2_ITERATIONS",
32
+ "TokenVerifier",
33
+ "generate_token",
34
+ "hash_token",
35
+ "parse_authorization",
36
+ "verify_token_hash",
37
+ ]
38
+
39
+ PBKDF2_ITERATIONS = 120_000
40
+ _ALGORITHM = "sha256"
41
+ _SALT_BYTES = 16
42
+ _TOKEN_BYTES = 32
43
+
44
+
45
+ def generate_token() -> str:
46
+ """A fresh API token: 256 bits, URL-safe, prefixed so it is greppable.
47
+
48
+ The ``ths_`` prefix means a leaked token can be found by secret scanners and
49
+ recognised in a log by a human, which is worth more than the four characters
50
+ it costs.
51
+ """
52
+ return f"ths_{secrets.token_urlsafe(_TOKEN_BYTES)}"
53
+
54
+
55
+ def hash_token(
56
+ token: str, *, salt: bytes | None = None, iterations: int = PBKDF2_ITERATIONS
57
+ ) -> str:
58
+ """Hash a token into the storable ``pbkdf2_sha256$iterations$salt$hash`` form."""
59
+ if not token:
60
+ raise ConfigurationError("refusing to hash an empty token")
61
+ salt = salt or secrets.token_bytes(_SALT_BYTES)
62
+ digest = hashlib.pbkdf2_hmac(_ALGORITHM, token.encode("utf-8"), salt, iterations)
63
+ return f"pbkdf2_{_ALGORITHM}${iterations}${salt.hex()}${digest.hex()}"
64
+
65
+
66
+ def verify_token_hash(token: str, stored: str) -> bool:
67
+ """Constant-time check of ``token`` against one stored hash.
68
+
69
+ Accepts the legacy ``sha256$salt$hash`` form as well, so an operator who
70
+ generated hashes with an older build is not locked out by an upgrade.
71
+ """
72
+ if not token or not stored:
73
+ return False
74
+ parts = stored.split("$")
75
+ try:
76
+ if len(parts) == 4 and parts[0] == f"pbkdf2_{_ALGORITHM}":
77
+ iterations = int(parts[1])
78
+ salt = bytes.fromhex(parts[2])
79
+ expected = bytes.fromhex(parts[3])
80
+ actual = hashlib.pbkdf2_hmac(_ALGORITHM, token.encode("utf-8"), salt, iterations)
81
+ elif len(parts) == 3 and parts[0] == _ALGORITHM:
82
+ salt = bytes.fromhex(parts[1])
83
+ expected = bytes.fromhex(parts[2])
84
+ actual = hashlib.sha256(salt + token.encode("utf-8")).digest()
85
+ else:
86
+ return False
87
+ except (ValueError, TypeError):
88
+ return False
89
+ return hmac.compare_digest(actual, expected)
90
+
91
+
92
+ def parse_authorization(header: str | None) -> str | None:
93
+ """Extract the token from an ``Authorization: Bearer …`` header.
94
+
95
+ Returns ``None`` for anything else — including ``Basic`` — rather than
96
+ raising, so the caller decides whether a missing credential is an error.
97
+ """
98
+ if not header:
99
+ return None
100
+ scheme, _, value = header.partition(" ")
101
+ if scheme.lower() != "bearer":
102
+ return None
103
+ token = value.strip()
104
+ return token or None
105
+
106
+
107
+ @dataclass
108
+ class TokenVerifier:
109
+ """Checks presented tokens against the configured hashes.
110
+
111
+ Built once at startup from :class:`~test_base.config.Settings`. Plaintext
112
+ tokens from configuration are hashed immediately and the plaintext is not
113
+ retained anywhere on the instance.
114
+ """
115
+
116
+ hashes: list[str] = field(default_factory=list)
117
+ enabled: bool = True
118
+ _accepted: set[str] = field(default_factory=set, repr=False)
119
+ _rejected: set[str] = field(default_factory=set, repr=False)
120
+
121
+ @classmethod
122
+ def from_settings(cls, settings: object) -> TokenVerifier:
123
+ hashes = list(getattr(settings, "api_token_hashes", []) or [])
124
+ for plaintext in getattr(settings, "api_tokens", []) or []:
125
+ hashes.append(hash_token(plaintext))
126
+ return cls(hashes=hashes, enabled=bool(getattr(settings, "auth_enabled", False)))
127
+
128
+ @classmethod
129
+ def admin_from_settings(cls, settings: object) -> TokenVerifier:
130
+ """The verifier for destructive maintenance.
131
+
132
+ Always ``enabled``, whatever ``auth_enabled`` says, and deliberately so:
133
+ this verifier answers "is this caller an administrator", which is not the
134
+ same question as "is authentication switched on". An instance with no
135
+ admin tokens configured therefore accepts no admin token at all, and
136
+ :func:`test_base.api.deps.require_admin` is the only thing that decides
137
+ whether an unauthenticated loopback caller may proceed without one.
138
+ """
139
+ hashes = list(getattr(settings, "admin_token_hashes", []) or [])
140
+ for plaintext in getattr(settings, "admin_tokens", []) or []:
141
+ hashes.append(hash_token(plaintext))
142
+ return cls(hashes=hashes, enabled=True)
143
+
144
+ def __bool__(self) -> bool:
145
+ return bool(self.hashes)
146
+
147
+ def verify(self, token: str | None) -> bool:
148
+ """True when ``token`` matches one configured hash."""
149
+ if not self.enabled:
150
+ return True
151
+ if not token:
152
+ return False
153
+ fingerprint = hashlib.sha256(token.encode("utf-8")).hexdigest()
154
+ if fingerprint in self._accepted:
155
+ return True
156
+ if fingerprint in self._rejected:
157
+ return False
158
+ for stored in self.hashes:
159
+ if verify_token_hash(token, stored):
160
+ self._accepted.add(fingerprint)
161
+ return True
162
+ # Bounded, so a flood of bad tokens cannot grow the process without limit.
163
+ if len(self._rejected) < 4096:
164
+ self._rejected.add(fingerprint)
165
+ return False
166
+
167
+ def require(self, header: str | None) -> None:
168
+ """Raise :class:`AuthenticationError` unless the header carries a valid token.
169
+
170
+ The message is identical for a missing, malformed and wrong token: telling
171
+ a caller *which* of those it was is free information for an attacker.
172
+ """
173
+ if not self.enabled:
174
+ return
175
+ if not self.hashes:
176
+ raise ConfigurationError(
177
+ "authentication is enabled but no tokens are configured; "
178
+ "create one with `test-base token create`"
179
+ )
180
+ if not self.verify(parse_authorization(header)):
181
+ raise AuthenticationError(
182
+ "a valid bearer token is required; send it as `Authorization: Bearer <token>`"
183
+ )
@@ -0,0 +1,125 @@
1
+ """The ``test-base`` command line.
2
+
3
+ Each command is a thin wrapper over the service layer — nothing here contains
4
+ business logic::
5
+
6
+ test-base init choose SQLite or PostgreSQL, check it, and save the choice
7
+ test-base serve start the API and the dashboard
8
+ test-base ingest import a report into the local store
9
+ test-base publish send a report to a remote Test Base
10
+ test-base demo fill the store with realistic sample data
11
+ test-base prune delete runs older than a retention cutoff
12
+ test-base db check the configured database and migrate it
13
+ test-base token create and hash API tokens
14
+ test-base formats list the installed report adapters
15
+
16
+ Everything here is also reachable over HTTP and from Python, with one deliberate
17
+ exception: ``prune`` is the terminal only. Authentication has two scopes, and the
18
+ write one is what every CI publisher token holds, so a prune endpoint behind it
19
+ would let a token that lives in a repository's CI settings delete a year of
20
+ history (ADR-0002 D8).
21
+
22
+ One rule shows up everywhere: **tokens are never taken as arguments.** A token on
23
+ a command line lands in shell history, in ``ps`` output for every user on the
24
+ box, and in the CI log if the step is echoed. ``--token-env`` and ``--token-file``
25
+ are the supported ways in.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import sys
31
+ from typing import Annotated
32
+
33
+ import typer
34
+
35
+ from test_base.errors import TestBaseError
36
+ from test_base.version import SCHEMA_VERSION, __version__
37
+
38
+ __all__ = ["app", "main"]
39
+
40
+ app = typer.Typer(
41
+ name="test-base",
42
+ help="One live dashboard for every test run — any team, any framework, any CI.",
43
+ no_args_is_help=True,
44
+ add_completion=True,
45
+ rich_markup_mode="rich",
46
+ context_settings={"help_option_names": ["-h", "--help"]},
47
+ )
48
+
49
+
50
+ def _version_callback(value: bool) -> None:
51
+ if value:
52
+ typer.echo(f"test-base {__version__} (canonical schema v{SCHEMA_VERSION})")
53
+ raise typer.Exit
54
+
55
+
56
+ @app.callback()
57
+ def _root(
58
+ version: Annotated[
59
+ bool,
60
+ typer.Option(
61
+ "--version",
62
+ "-V",
63
+ callback=_version_callback,
64
+ is_eager=True,
65
+ help="Show the version and exit.",
66
+ ),
67
+ ] = False,
68
+ ) -> None:
69
+ """Test Base."""
70
+
71
+
72
+ def _register() -> None:
73
+ """Attach the sub-commands.
74
+
75
+ Imported lazily and inside a function so that ``test-base --help`` does not
76
+ pay for importing FastAPI, SQLAlchemy and every adapter. On a cold cache that
77
+ is the difference between a command that feels instant and one that does not.
78
+ """
79
+ from test_base.cli.commands import (
80
+ db,
81
+ demo,
82
+ formats,
83
+ ingest,
84
+ prune,
85
+ publish,
86
+ serve,
87
+ token,
88
+ )
89
+ from test_base.cli.commands import init as setup
90
+
91
+ app.command(
92
+ "init", help="Set up Test Base: choose SQLite or PostgreSQL, check it, save the choice."
93
+ )(setup.init)
94
+ app.command("serve", help="Start the API and serve the dashboard.")(serve.serve)
95
+ app.command("ingest", help="Import a report file into the local store.")(ingest.ingest)
96
+ app.command("publish", help="Send a report to a remote Test Base server.")(publish.publish)
97
+ app.command("demo", help="Populate the store with realistic sample data.")(demo.demo)
98
+ app.command("prune", help="Delete runs older than a retention cutoff.")(prune.prune)
99
+ app.command("formats", help="List the installed report adapters.")(formats.formats)
100
+ app.add_typer(token.app, name="token", help="Create and hash API tokens.")
101
+ app.add_typer(db.app, name="db", help="Check the configured database and migrate it.")
102
+
103
+
104
+ def main() -> None:
105
+ """Console-script entry point.
106
+
107
+ Catches :class:`~test_base.errors.TestBaseError` and turns it into a clean
108
+ message plus that error's own exit code, so a CI step can branch on *why* it
109
+ failed rather than only on the fact that it did.
110
+ """
111
+ _register()
112
+ try:
113
+ app()
114
+ except TestBaseError as exc:
115
+ typer.secho(f"error: {exc.message}", fg=typer.colors.RED, err=True)
116
+ for key, value in exc.detail.items():
117
+ typer.secho(f" {key}: {value}", fg=typer.colors.BRIGHT_BLACK, err=True)
118
+ raise SystemExit(exc.exit_code) from exc
119
+ except KeyboardInterrupt: # pragma: no cover - interactive
120
+ typer.secho("interrupted", fg=typer.colors.YELLOW, err=True)
121
+ raise SystemExit(130) from None
122
+
123
+
124
+ if __name__ == "__main__": # pragma: no cover
125
+ sys.exit(main()) # type: ignore[func-returns-value]
File without changes