# OTP and Secure Message Handling

## Overview

The MediLink cloud daemon handles OTP (One-Time Password) and secure message flows differently from regular file attachments. This is a **deferred feature** with no UI - manual intervention is required.

## How It Works

When the orchestrator detects a secure/protected message (via subject or snippet keywords), it:

1. Flags the queue item as `otp_required: true`
2. Generates a unique OTP token
3. Does NOT download any attachments automatically

When the XP daemon polls `/ready` and receives an OTP item:

1. Records it in `cache_dir/pending_otps.json`
2. Creates an instruction file: `cache_dir/OTP_<token>.txt`
3. Logs a message indicating the OTP token
4. **Does NOT automatically acknowledge** - waits for manual completion

## User Workflow

1. Check the daemon log or `cache_dir` for `OTP_*.txt` instruction files
2. Open the secure message portal (typically via MediLink menu or direct link)
3. Complete the OTP challenge in the secure portal
4. Download the file manually from the secure portal to your working folder
5. Once the file is saved, acknowledge the item:

   ```cmd
   python medilink_cloud_daemon.py --ack-otp <token>
   ```

   Example:
   ```cmd
   python medilink_cloud_daemon.py --ack-otp a1b2c3d4e5f6
   ```

6. The daemon will send the acknowledgment to the orchestrator and remove the OTP from pending

## Why Manual?

Secure message portals typically require:
- Interactive authentication (OTP codes sent via SMS/email)
- CAPTCHA challenges
- Browser-based workflows that cannot be automated

The current implementation defers this complexity to manual handling rather than attempting to automate portal login.

## Configuration

No special configuration is needed. The OTP flow is automatically triggered when:
- Email subject contains "protected message" or "secure message"
- Email snippet contains "secure message"

## Future Enhancements

Potential improvements (not currently implemented):
- Browser automation via headless Chrome/Playwright
- SMS/email OTP interception and auto-fill
- UI to manage pending OTP items and launch secure portals
- Integration with secure message providers' APIs (if available)

## Files and State

- `cache_dir/pending_otps.json`: All pending OTP items awaiting manual acknowledgment
- `cache_dir/OTP_<token>.txt`: Per-OTP instruction files (deleted after ack)
- `cache_dir/cloud_daemon.log`: Contains OTP token and queue item references
