Mark Phase 4 as completed

IMPLEMENTATION-PHASES.md

@@ -0,0 +1,136 @@
+# MemoriC Agent Direct-LAN + UI Roadmap (Phased)
+
+## Summary
+
+Shift agent architecture from localhost-only control to **LAN-capable agent endpoint** so phones can upload directly when on the same network, while keeping broker/tunnel path for remote/off-LAN cases.
+Deliver in phases: architecture first, then safe storage migration UI, then direct-LAN data plane.
+
+## Phase 1: Networking & Security Foundation
+
+Status: ✅ Completed (2026-05-18)
+
+- Replace localhost-only UI assumption with configurable bind strategy.
+- Add agent listener config:
+  - `bind_host` (default: `0.0.0.0`)
+  - `bind_port`
+  - `allowed_subnets` (default: RFC1918 private ranges)
+- Define auth model for LAN access (required before direct upload):
+  - Pairing token or short-lived device token
+  - Per-request auth on all mutable endpoints
+- Add transport policy:
+  - HTTP for local development only
+  - TLS option planned for production LAN usage
+- Threat model doc for LAN attack surface (unauthorized upload, path abuse, replay).
+
+### Acceptance
+
+- Agent can bind on LAN interface.
+- Unauthorized requests are rejected.
+- Private-network restrictions are enforceable via config.
+
+## Phase 2: Agent UI v1 (Settings + Status Only)
+
+Status: ✅ Completed (2026-05-18)
+
+- Build local web UI served by agent, reachable over LAN per bind config.
+- UI includes:
+  - Connection status (broker + LAN endpoint)
+  - Current storage directory
+  - Health indicators and recent errors
+- No photo library management yet.
+- API surface:
+  - `GET /api/status`
+  - `POST /api/storage/validate`
+  - `POST /api/storage/change`
+  - `GET /api/storage/migration`
+
+### Acceptance
+
+- User can open UI from another device on same network (authorized).
+- Storage settings are visible and editable through UI.
+
+## Phase 3: Storage Relocation with Safe Migration
+
+Status: ✅ Completed (2026-05-18)
+
+- Implement storage change flow with your rule:
+  - Destination must be empty.
+- Migration behavior:
+  - Validate destination exists/is writable/is empty.
+  - Move files preserving paths.
+  - Rename when possible; copy+remove fallback for cross-device moves.
+- Atomic cutover behavior:
+  - Active storage path switches only after migration completes successfully.
+  - On any failure, remain on old storage path and return detailed error report.
+- Persist selected storage location in config file.
+
+### Acceptance
+
+- Successful migration moves all files and switches path.
+- Failed migration never leaves partial active-path switch.
+
+## Phase 4: Direct Phone-to-Agent Upload (LAN Data Plane)
+
+Status: ✅ Completed (2026-05-18)
+
+- Add authenticated upload endpoint on agent for same-network phone backup.
+- Keep broker relay as fallback path when phone is off-LAN.
+- Define upload routing policy:
+  - Phone tries direct agent first if discoverable/reachable.
+  - Falls back to broker if direct path fails.
+- Add simple discovery approach (phase target):
+  - Agent publishes LAN endpoint hints (IP:port candidates) to broker on connect.
+  - Phone fetches broker-provided hints and attempts direct upload automatically.
+  - Manual endpoint entry remains available as override/debug path.
+
+### Acceptance
+
+- On same LAN, phone uploads directly to agent without broker relay.
+- Off-LAN upload still works through broker fallback.
+
+## Phase 5: Platform Integration & Hardening
+
+- Align Linux service + Windows task launchers with new network/config settings.
+- Add rate limits and upload size checks on LAN endpoint.
+- Add migration/upload concurrency controls.
+- Add operational logs/metrics for:
+  - Auth failures
+  - Direct vs broker upload ratio
+  - Migration outcomes and duration.
+
+### Acceptance
+
+- Windows and Linux agents behave consistently with LAN mode enabled.
+- Security and reliability checks pass in repeated real-network tests.
+
+## Public Interfaces / Config Additions
+
+- Config fields:
+  - `storage_dir`
+  - `bind_host`
+  - `bind_port`
+  - `allowed_subnets`
+  - `auth_mode`
+  - `pairing_token` (or token issuer reference)
+- New/extended APIs:
+  - `GET /api/status`
+  - `POST /api/storage/validate`
+  - `POST /api/storage/change`
+  - `GET /api/storage/migration`
+  - `POST /api/upload` (direct LAN upload)
+- Existing broker protocol remains supported for fallback path.
+
+## Test Plan
+
+- Unit:
+  - Path validation, empty-destination rule, migration rollback behavior.
+  - Auth checks for all LAN-accessible endpoints.
+- Integration:
+  - Same-LAN direct upload success.
+  - Broker fallback when direct upload unavailable.
+  - Migration under active upload load (defined behavior, no corruption).
+- Platform:
+  - Windows + Linux startup/restart persistence and config application.
+- Security:
+  - Unauthorized LAN client denied.
+  - Path traversal and invalid filename rejection.