CareMax Auth

OAuth Device Flow authentication for CareMax Health API. This skill is a PREREQUISITE for all other caremax-* skills — invoke it automatically when no token...

Security Scan

The skill's code implements a legitimate OAuth device flow and related API helpers, but there are notable coherence and behaviour concerns — chiefly that the skill demands silent, automatic authentication and the package metadata omits required runtime tools (curl/python3).

Purpose & Capability

The skill claims to provide CareMax OAuth Device Flow and the included scripts implement that flow plus API wrappers, uploads, OCR streaming and file download — which matches the stated purpose. However the registry metadata declares no required binaries or environment, while the scripts clearly depend on curl, python3, mktemp, and standard POSIX utilities and also open a browser (open/xdg-open). This mismatch between declared requirements and actual runtime needs is incoherent and could cause unexpected failures or security exposure if the agent auto-runs without those tools or with different tool variants.

Instruction Scope

SKILL.md instructs the agent (and sibling caremax-* skills) to "Do NOT ask the user, just execute" the auth flow automatically when no token exists. The scripts themselves only access ~/.caremax/credentials.json and the configured base_url, and they call the CareMax endpoints (or a developer localhost). There is no evidence of exfiltration or unrelated filesystem access, but the explicit instruction to run the flow silently (open a browser and auto-poll) is scope creep for an auth operation and creates a privacy/consent risk.

Install Mechanism

This is an instruction-only skill (no external downloads), which minimizes install-time risk. The skill bundle contains shell scripts that will run locally. That is reasonable for this purpose, but the package metadata did not declare the real runtime binary requirements (curl, python3, open/xdg-open). No external arbitrary download URLs or archive extraction were found.

Credentials

The skill does not request any external credentials or environment variables in metadata. It stores OAuth tokens in ~/.caremax/credentials.json, which is appropriate for a local OAuth flow. No unrelated credentials or secret environment variables are requested.

Persistence & Privilege

always is false and the skill does not modify other skills' configs, which is good. However SKILL.md explicitly directs the agent to silently run the auth flow when no token exists. Because autonomous invocation is allowed by default, that instruction could cause the agent to perform authentication and write tokens to the user's home directory without explicit user consent. This combination increases the privacy risk and should be considered before enabling automatic invocation.

What to consider before installing

This skill's scripts implement the CareMax device OAuth flow and related API helpers; that is coherent with its description. However: - The SKILL.md explicitly orders the agent to "Do NOT ask the user, just execute" the auth flow; if you expect explicit user consent before authentication, do not enable autonomous invocation of this skill or require a prompt. - The registry metadata lists no required binaries, but the scripts require curl, python3, and a browser opener (open or xdg-open). Ensure your environment has these tools and be aware the skill will call them. - Tokens are written to ~/.caremax/credentials.json. If you install this skill, review that file and consider whether you trust storing CareMax credentials there. - The default API base_url is https://api.caremax.ai, but the skill allows a custom base_url (including localhost). Verify the base_url used before authenticating. - The skill source is listed as unknown with no homepage. If possible, obtain provenance or an official source before installing; prefer skills from known publishers. Recommended actions before installing: review the included scripts locally, confirm you want the agent to open your browser and auto-poll for authorization, and consider requiring the agent to prompt you before running auth-flow.sh. If you must restrict risk, run this skill only in a controlled environment or sandbox.

CareMax Authentication

CRITICAL RULES

1. This is a silent prerequisite for ALL caremax-* skills. Do NOT ask "do you want to authenticate?" — just execute.
2. NEVER write your own curl commands. Only use the scripts below.
3. NEVER split auth into multiple steps manually. Use ./scripts/auth-flow.sh (from this skill root) — it opens browser AND auto-polls until done.
4. BASE URL DETECTION: If the user specifies a custom URL (local dev 默认 http://localhost:8788，须与后端 wrangler [dev] 端口一致), you MUST:
   • Pass it as the first argument: bash ./scripts/auth-flow.sh http://localhost:8788 (run from this skill root — see path convention below)
   • After auth completes, credentials.json will have base_url set to that URL
   • All subsequent api-call.sh, list-system-presets.sh, quick-log.sh, upload.sh, ocr-stream.sh will auto-use it
   • Look for URL patterns like http://localhost:XXXX, caremax(http://...), or explicit "use local" / "use localhost"

Scripts

Path convention (no ~/.claude — product-agnostic)

• This skill (caremax-auth): run commands with current working directory = this folder (the directory that contains SKILL.md and scripts/). Invoke scripts as ./scripts/<name>.sh.
• Other caremax-* skills sit as sibling directories next to caremax-auth (e.g. skills/caremax-indicators/ and skills/caremax-auth/ in the repo, or ~/.agents/skills/<name>/ after install). From those folders, call auth as ../caremax-auth/scripts/<name>.sh.

Credentials file location is unchanged: ~/.caremax/credentials.json (not under any product’s config dir).

api-call.sh — Make authenticated API calls (PRIMARY TOOL)

This is what you should use for all API calls. It auto-checks token, auto-refreshes if expired.

bash ./scripts/api-call.sh GET /api/skill/indicators
bash ./scripts/api-call.sh POST /api/skill/records/search '{"query":"血常规"}'
bash ./scripts/api-call.sh GET "/api/skill/indicators/trend?id=xxx"

If it returns {"error":"no_credentials",...} → run ./scripts/auth-flow.sh (see below), then retry.

list-system-presets.sh — 当前账号可快捷记录的指标列表

与 App 「快捷记一笔」 芯片一致：先看有哪些 preset_key / 显示名 / 默认单位，再调用 quick-log.sh。

bash ./scripts/list-system-presets.sh

quick-log.sh — 快捷记一笔（单条数值）

bash ./scripts/quick-log.sh <preset_key> <value>
bash ./scripts/quick-log.sh weight 72.5 --unit kg --date 2026-03-29
bash ./scripts/quick-log.sh height 175 --member <family_member_uuid>

可选参数：--unit、--date（YYYY-MM-DD）、--member（家庭成员 UUID）。底层走 api-call.sh，自动带用户 OAuth token。

upload.sh — Upload files (images/PDFs) to CareMax

bash ./scripts/upload.sh /path/to/report.jpg
bash ./scripts/upload.sh /path/to/img1.jpg /path/to/img2.png

Returns: {"files":[{"id":"...","member_id":"...","original_name":"..."}]}

Use the returned id values as fileIds for ocr-stream.sh.

IMPORTANT: Do NOT use api-call.sh for file uploads — it only supports JSON body. Always use upload.sh for multipart file uploads.

download-file.sh — Download a source file from a session

bash ./scripts/download-file.sh <file_id> [output_path]
# Example:
bash ./scripts/download-file.sh abc-123 ~/Downloads/report.jpg

Get file_id from session detail (source_files[].id in reports, or files[].id in session).

ocr-stream.sh — OCR with real-time SSE progress (for caremax-ocr skill)

bash ./scripts/ocr-stream.sh <session_id>

Outputs one JSON per line as OCR progresses. Last line (step=done) has the full results. Read each line and display progress to the user. See caremax-ocr skill for details.

Handles errors gracefully:

• 409 (session already processing) → outputs {"step":"error","code":"processing_in_progress",...}
• 403 (quota exceeded) → outputs {"step":"error","code":"ocr_limit_exceeded",...}
• Pipeline auto-resumes from saved checkpoint on retry (no work is lost)

auth-flow.sh — One-shot full authorization (opens browser + auto-polls)

# Default (production)
bash ./scripts/auth-flow.sh

# Custom base URL (localhost / staging)
bash ./scripts/auth-flow.sh http://localhost:8788

This script does EVERYTHING in one shot:

1. Requests device code from the API
2. Opens the user's browser to the authorize page
3. Automatically polls every 5 seconds until the user approves (up to 15 min)
4. Saves token to ~/.caremax/credentials.json

Output when done: {"status":"authorized","access_token":"sk-caremax-...","base_url":"..."}

Run this in the background so you can tell the user what's happening while it polls:

bash ./scripts/auth-flow.sh &

Then tell the user: "I've opened the authorization page in your browser. Please log in and click Allow. I'll detect it automatically."

Wait for the background job to finish — it will output the result.

check-token.sh — Check token status (used internally by api-call.sh)

bash ./scripts/check-token.sh

Output: {"status":"valid"|"expired"|"missing", ...}

refresh-token.sh — Refresh expired token (used internally by api-call.sh)

bash ./scripts/refresh-token.sh

Standard Workflow

Quick vitals (快捷记一笔)

User wants to log height / weight / etc.
  → ./scripts/list-system-presets.sh  →  pick preset_key from JSON
  → ./scripts/quick-log.sh <preset_key> <value> [--unit ...] [--date ...] [--member ...]

Query data

User asks about health data
  → run: ./scripts/api-call.sh GET /api/skill/xxx
      ├── token valid → returns data → done
      ├── token expired → auto-refreshes → returns data → done
      └── no token → returns error
          → run: ./scripts/auth-flow.sh [base_url] (background)
          → auth-flow.sh auto-polls and saves token
          → retry: ./scripts/api-call.sh → returns data → done

Upload + OCR (save medical reports from images)

This is a session-based multi-step workflow. One upload session groups all files + reports together.

Step 1: Upload → creates a session

bash ./scripts/upload.sh /path/to/image1.jpg /path/to/image2.jpg

Returns:

{ "session_id": "uuid", "member_id": "uuid", "files": [{ "id": "...", "original_name": "..." }] }

Save session_id — it's used for all subsequent steps.

Step 2: OCR (with real-time progress)

bash ./scripts/ocr-stream.sh <session_id>

Each output line is a JSON progress event. Relay to the user:

• step=normalize → "正在预处理文件..."
• step=ocr → "正在 OCR 识别第 X/Y 页..."
• step=structure → "AI 正在分析报告结构..."
• step=normalize_indicators → "正在标准化指标名称..."
• step=done → OCR complete, data contains reports array

Step 3: Present results for user review (MANDATORY)

Do NOT call confirm automatically. Parse the step=done data and show:

识别到 N 份报告：

📋 报告 1: {report_title}
   来源: {sourcePages.join(', ')}
   日期: {test_date}  医生: {doctor}  科室: {department}
   ┌──────────────────┬────────┬────────┬──────────┬──────┐
   │ 指标名称         │ 结果   │ 单位   │ 参考范围 │ 异常 │
   ├──────────────────┼────────┼────────┼──────────┼──────┤
   │ xxx              │ 1.23   │ mg/L   │ 0-5      │      │
   │ yyy              │ 9.99   │ mmol/L │ 1-8      │  ⬆   │
   └──────────────────┴────────┴────────┴──────────┴──────┘

📋 报告 2: ...

确认保存吗？

Wait for user to say 确认/保存/OK.

Step 4: Confirm and save

bash ./scripts/api-call.sh POST /api/skill/sessions/<session_id>/confirm '{"reports":[<reports array from step 2>]}'

Returns: {"success":true,"message":"2 report(s) saved","recordIds":["uuid1","uuid2"]}

After success: "已保存 N 份报告。"

Query sessions

bash ./scripts/api-call.sh GET /api/skill/sessions
bash ./scripts/api-call.sh GET "/api/skill/sessions/<session_id>"
bash ./scripts/api-call.sh GET "/api/skill/sessions/<session_id>/status"   # lightweight progress polling

Delete session (undo entire upload)

bash ./scripts/api-call.sh DELETE /api/skill/sessions/<session_id>

Deletes the session + all files + all reports atomically.