[Feature] : API ENDPOINTS PR 2: Auth

[pulk17]

[FEATURE]

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.

My familiarity with the project is as follows (check one):

• I have never used the project.
• I have used the project briefly.
• I have used the project extensively, but have not contributed previously.
• I am an active contributor to the project.

---

Auth and token management endpoints (PR 2/6)

Summary

Part 2 of 6 (supersedes #1117). Builds on the middleware and ApiToken model
from PR 1 (#1130) to add the token lifecycle: create, list, revoke.

Stacking: stacked on PR 1 (#1130) — until it merges, the diff here includes
its files. Please review #1130 first.

Endpoints (mod_api/routes/auth.py, mounted at /api/v1/auth/tokens)

• POST / — create token. Public (the only public endpoint besides
  /system/health); authenticates with email + password, rate-limited 5/15min
  by IP, and returns the plaintext token once. Scope grants are role-based:
  every authenticated role may request runs:read, runs:write, results:read,
  system:read; tokens:manage and baselines:write are admin-only.
  Default scopes when none are requested: runs:read, results:read.
• GET / — list tokens. Requires tokens:manage (so, in practice, admin).
  Returns the caller's tokens (admins may pass ?all=true). Metadata only —
  never the plaintext or hash; revoked/expired tokens are included with an
  is_revoked flag.
• DELETE /current — self-revoke. Scope-free by design: any valid token may
  revoke itself.
• DELETE /{token_id} — revoke by ID. Owners revoke their own; admins revoke
  anyone's. Non-owners get a uniform 404 to prevent token-ID enumeration.

Validation (mod_api/schemas/auth.py)

TokenCreateRequestSchema is strict (unknown=RAISE): validated email,
password length, token_name regex, expires_in_days (1–30), scope whitelist.
Response schemas never serialize the hash.

Notes for reviewers

• Missing-user logins still run a dummy password hash to avoid a timing
  side-channel.
• Global middleware integration tests arrive in PR 3, where the endpoints they
  exercise exist.

Testing

New tests for token creation, RBAC boundaries, and edge cases (duplicate name,
bad credentials). Lint/type clean.

Next

PR 3 (#1132): system status and run management.

[cfsmp3]

Missing tests:

• Rate limiter still untested (tests bypass it via TESTING + _rate_limit_store.clear()). The 5/15min create limit is unverified.
• H4 fix (500→JSON) still unverified — no test forces a real route 500.

Bug:

• Non-admins can still request tokens:manage scope (harmless given role gates, but loose).

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud