# Handoff: IMAP Proxy Integration (Phase 6.2)

**From:** Daedalus (Frontend)  
**To:** Socrates (Backend)  
**Date:** 2026-04-28 20:58 UTC  
**Priority:** Medium — Blocks zero-config ingress for consumer appliance model

---

## ✅ Already Built (by Daedalus — needs Socrates review/integration)

**Files:**
- `hoffdesk-api/imap_proxy/proxy.py` — IMAPProxy class with IDLE, provider presets, circuit breaker
- `hoffdesk-api/imap_proxy/dashboard_router.py` — Status/metrics endpoints
- `hoffdesk-api/imap_proxy/__init__.py` — Module exports
- `main_v2.py` — Router registration + startup/shutdown hooks

**Current State:**
- Proxy starts automatically if `IMAP_USER` + `IMAP_PASSWORD` env vars are set
- Connects via IMAP IDLE (outbound only)
- Dashboard card shows status at `family.hoffdesk.com`
- Status endpoint: `GET /imap/status` (public, no auth)

---

## 🔧 What Socrates Needs To Do

### 1. Document Pipeline Integration
In `main_v2.py`, `_on_email_received()` is currently a stub:

```python
def _on_email_received(email_data: dict):
    logger.info(f"New email: {email_data.get('subject', '(no subject)')}")
```

**Action:** Wire it to your vision pipeline. Call `icarus.core.vision.classify_document()` or whatever the right entry point is.

**Email data structure:**
```json
{
  "subject": "string",
  "from": "string",
  "to": "string",
  "body_text": "string",
  "body_html": "string",
  "date": "ISO8601",
  "message_id": "string"
}
```

### 2. Auth Middleware Review
Daedalus added `/imap/` to `EXEMPT_PREFIXES` in `shared/session_auth.py` for the status endpoint. This is acknowledged as a hack — Socrates should review if there's a cleaner way (e.g., `/api/public/imap/`).

### 3. Credential Storage
Currently reads from `.env`. Should this use the secrets manager? iCloud app-specific password flow needs proper handling.

### 4. Error Handling
- Circuit breaker is basic — should tie into Socrates' alerting system
- IMAP disconnect/reconnect logic could be more robust

---

## 📋 Files to Review

```
hoffdesk-api/imap_proxy/proxy.py              # Core IMAP logic
hoffdesk-api/imap_proxy/dashboard_router.py   # Status endpoints
hoffdesk-api/main_v2.py                       # Startup/shutdown + email handler
hoffdesk-api/shared/session_auth.py           # Auth exemption (temporary)
```

---

## Context

- **Goal:** Zero-config ingress for consumer appliance model
- **Provider:** iCloud Mail via app-specific passwords (not OAuth)
- **Connection:** Outbound-only IMAP IDLE (no inbound tunnels)
- **Fallback:** Polling every 30s if IDLE unsupported

---

## Next Steps

1. Socrates reviews the scaffold code
2. Wire `_on_email_received()` to document pipeline
3. Clean up auth middleware exemption
4. Integrate with secrets/alerting systems
5. Daedalus available for sync/walkthrough on request

---

*Routed by Wadsworth per Board protocol.*