## ACCESS API Docs
https://dsacms.github.io/cmmi-access-model/en/
(Also see: `ACCESS API Operations Manual.pdf`)

# CMS Authentication Patterns

## Blue Button 2.0 Sandbox
CMS provides a sandbox which includes synthetic sample beneficiary data.
https://sandbox.bluebutton.cms.gov/

### Python SDK
https://github.com/CMSgov/cms-bb2-python-sdk

### Auth Flow (Incompatible with Our Use Case)
Blue Button uses patient-mediated OAuth 2.0 with PKCE + JWT assertions:
1. Patient initiates consent flow via browser redirect
2. PKCE code challenge/verifier exchanged for auth code
3. Auth code + JWT assertion → bearer token at `/oauth/token`

**Problem:** This requires a patient-initiated browser flow and short-lived auth codes. Our server-to-server ACCESS operations (`$check-eligibility`, `$align`, `$report-data`, `$unalign`) cannot use this pattern — no way to obtain or refresh tokens programmatically without patient interaction.

## BCDA (Beneficiary Data Access) Sandbox
https://bcda.cms.gov/api-documentation/get-a-bearer-token.html

### Auth Flow (Matches Our Pattern)
BCDA uses Basic Auth client credentials:
1. `POST /auth/token` with `Authorization: Basic base64(client_id:client_secret)` header + empty body
2. Response includes bearer token valid for subsequent API calls

**Problem:** BCDA hosts bulk data export operations (`$export`, `$group`, etc.) but does NOT host CKD OAP ACCESS-specific operations (`$check-eligibility`, `$align`, etc.).

## Real CKD OAP ACCESS API
The actual endpoints hosting `$check-eligibility`, `$align`, `$report-data`, and `$unalign` require program-specific credentials not publicly available in any sandbox environment. When real credentials are provisioned by the CKD OAP program, swap `CMS_API_BASE_URL` in `.env.local`.

# Local Mock Server (access-fhir-apis)

Our local development mock: `scripts/access-fhir-sandbox/`
Source: https://github.com/hadijaveed/access-fhir-apis

Implements all 5 ACCESS operations with spec-accurate business logic from the published IG v0.9.12:

### Operations

| Operation | Endpoint | Result Codes | Business Logic |
|-----------|----------|--------------|----------------|
| Screen | `POST /fhir/Patient/$check-eligibility` | 8 codes | MBI check → exclusion conditions → control group (SHA-256 hash) → ICD-10 validation |
| Enroll | `POST /fhir/Patient/$align` | 7 codes | Control group check → exclusion → ICD-10 match → 90-day lock-in enforcement |
| Report | `POST /fhir/$report-data` | 4 codes | Timing windows (baseline/quarterly/end-of-period) → LOINC measure validation → OAP target evaluation |
| Poll | `GET /fhir/Patient/$submission-status?submissionID=...` | 3 statuses | Async 202 → poll → 200 pattern with configurable delay |
| Exit | `POST /fhir/Patient/$unalign` | 3 codes | Alignment lookup → reason validation (geographic-relocated, loss-of-contact, etc.) |

### Track-Specific Validation

**ICD-10 prefixes per track:** eCKM (I10/I25/E11/E78...), CKM (N18/E11/I10), MSK (M17/M54/M75), BH (F32/F41/F31)

**LOINC measures per report type:** Each track requires specific biomarkers/PROMs for baseline, quarterly, and end-of-period reports. MSK has alternative LOINCs for PROMIS physical function measures.

**OAP target evaluation at end-of-period:** Compares current vs baseline values against CMS-defined thresholds (e.g., systolic BP ≥10 mmHg reduction OR <130).

### Configuration

| Env Var | Default | Purpose |
|---------|---------|---------|
| `MOCK_PORT` | `3001` | Port to listen on |
| `LOCK_IN_DAYS` | `90` | Days before patient can switch participants |
| `BASELINE_WINDOW_DAYS` | `60` | Days to submit baseline after alignment |
| `ASYNC_DELAY_MS` | `500` | Simulated processing delay (ms) |

### Run Options

**Docker Compose:**
```bash
docker compose up -d cms-mock
# Accessible at http://localhost:3001/
```

**Node.js locally (pinned to the commit used by `access_fhir_sandbox/Dockerfile`):**
```bash
git clone https://github.com/hadijaveed/access-fhir-apis.git /tmp/access-fhir-apis && \
  cd /tmp/access-fhir-apis && git checkout 4e897bb && npm install && npm run start:mock
```

### Interactive API Explorer

The mock serves a browser-based explorer at `http://localhost:3001/`:
- Walk through complete patient lifecycle (screen → enroll → report → exit)
- 24 pre-built scenarios covering every result code  
- Editable FHIR payloads with track-aware ICD-10 and LOINC codes
- Plain-English explanations for every result

### Debug Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/fhir/$mock-state` | GET | View current alignments, submissions, data reports |
| `/fhir/$mock-reset` | POST | Clear all in-memory state (use between test runs) |
| `/fhir/metadata` | GET | FHIR CapabilityStatement with supported operations |