Saltar a contenido

SEC-001 Auth Model Decision Record

Date: 2026-05-24

Status: accepted risk with required follow-up

Scope: EPPA clinical/research deployment for LABIS, including the Next.js frontend and FastAPI analysis backend under fronts/eppa/.

Decision

The current shared nginx basic-auth gate is accepted only as a short-term deployment control for a single LABIS research operator or a tightly supervised lab workstation. It is not sufficient as the final auth model for clinical research use where multiple practitioners can access patient-linked studies.

EPPA must move to per-user authentication before broader multi-user clinical operation. The recommended path is to finish the existing self-hosted FastAPI auth lane already present in python/routers/auth.py and the frontend login flow, then enforce it at the route/API boundary. Institutional SSO can replace local credentials later if the university requires centralized identity.

Users

Minimum viable users are:

  • LABIS principal investigator or responsible researcher, accountable for approving the deployment and data-handling posture.
  • Kinesiologist or trained lab operator, responsible for uploading images, placing markers, running analyses, and exporting results.
  • Research assistant or reviewer, potentially needing read-only access to completed sessions once patient/study persistence exists.
  • Technical maintainer, responsible for deployment, logs, backups, and incident response.

The shared basic-auth model cannot distinguish these users. Any action behind the shared password is attributable only to the shared secret, not to a named person.

Data And PII

Radiographs and posture images can identify a patient directly or indirectly. They may include face, body shape, image metadata, patient identifiers in file names, or study IDs entered by the operator. These should be treated as clinical personal data.

Current browser-first analysis pages load images into browser memory and send marker coordinates, calibration values, and region-specific points to the analysis API. The standard /api/anterior/*, /api/posterior/*, and /api/lateral/* analysis calls do not upload the full radiograph. PII risk is therefore lower for those calculation calls, but not absent because marker sets, patient IDs, exported files, and optional image processing endpoints can still be tied to a patient workflow.

Endpoints that do receive image or file content, such as /api/anonymize, /api/detect-markers, and /api/upload-mat, require separate retention and audit review before production clinical use. Do not log payloads or raw patient identifiers from those endpoints.

Basic Auth Risk Acceptance

Shared basic auth is acceptable only if all of the following are true:

  • Access is limited to a private LABIS deployment or supervised lab device.
  • The password is rotated when staff leave or the secret may have been exposed.
  • The deployment is not presented as per-user audited clinical software.
  • No broad remote multi-user workflow depends on the shared password.
  • The LABIS PI or responsible researcher approves this residual risk in writing or through GitHub review.

If any condition is false, per-user auth is required before clinical use.

Minimum Logging Requirement

Every analysis API request must emit a server log entry sufficient to reconstruct who did what without exposing clinical payloads:

  • UTC timestamp generated by the server.
  • Actor context: authenticated user ID when available, otherwise a hashed local EPPA session identifier.
  • HTTP method and API path.
  • Analysis type derived from the path, such as anterior/escapular-ms.
  • Response status and duration.

The log must not include raw radiographs, marker coordinates, patient IDs, access tokens, refresh tokens, reset tokens, passwords, or clinical payloads.

Implemented posture: python/api.py now logs analysis calls for /api/analyze/*, /api/anterior/*, /api/posterior/*, and /api/lateral/*. The browser API client sends a per-tab X-EPPA-Session-ID; the server hashes it before logging. When the self-hosted auth access token is present, the server logs the user ID instead.

Formal Deferrals

  • Per-user auth enforcement is deferred to AUTH follow-up work because the repo already has local invitation/registration/auth WIP and issue #203 explicitly scopes this worker to the decision record, logging posture, and follow-up creation.
  • Database-backed audit persistence is deferred until patient/study persistence is finalized. The current change writes structured server logs only.
  • Institutional SSO is deferred pending LABIS/university identity-provider requirements.
  • Ethics committee audit-log requirements are unresolved. The LABIS PI or responsible researcher must confirm whether timestamped per-user audit logs are required for the approved research protocol.

Follow-Up Issues

Created AUTH follow-ups:

  • 210 [AUTH-001] Enforce per-user auth on EPPA app and analysis API.

  • 207 [AUTH-002] Finish invitation-based onboarding and token registration.

  • 211 [AUTH-003] Persist immutable EPPA audit events for clinical workflows.

Institutional SSO remains a deployment decision for LABIS/university review after the local per-user model is working end to end.

Sign-Off

Required validation is review by the LABIS PI or responsible researcher. Approval on issue #203 or the closing PR is sufficient for this decision record.

No real patient data, secrets, tokens, or clinical payloads are included in this record.