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:

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:

{
  "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.