kite/.planning/phases/13-virtual-local-cloud-operations/13-04-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
13	04	execute	2	13-01 13-03	backend/api/cloud/operations.py backend/api/cloud/connections.py backend/api/cloud/schemas.py frontend/src/api/cloud.js backend/tests/test_cloud_mutations.py backend/tests/test_cloud_reconnect.py backend/tests/test_cloud_security.py	true	CONN-01 CONN-02 CONN-03 CLOUD-02	truths artifacts key_links Reconnect is a connection-ID patch flow, not a second-row account insertion. Google Drive reconnect and connect flows explicitly request broader Phase 13 access. Open, preview, and fallback download use DocuVault-controlled endpoints with typed result bodies and binary-only preview rules. path provides backend/api/cloud/operations.py Owner-scoped test, open, preview, and fallback download endpoints. path provides backend/api/cloud/connections.py Connection-ID reconnect patching and broader Drive OAuth scope handling. path provides backend/api/cloud/schemas.py Whitelisted typed health, reconnect, and content result schemas. from to via pattern OAuth reconnect state existing cloud_connections row connection-ID patching connection_id from to via pattern preview result typing frontend shared browser handlers whitelisted kind/reason response bodies reason

Implement the connection-ID reconnect, explicit health-test, and authorized content-route slice of Phase 13, including broader Google Drive scope handling and binary-only preview fallback rules.

Purpose: Put the owner-scoped route layer in place before upload and folder mutations build on it. Output: Typed reconnect and content endpoints plus centralized frontend API helpers.

<execution_context> @$HOME/.codex/gsd-core/workflows/execute-plan.md @$HOME/.codex/gsd-core/templates/summary.md </execution_context>

@AGENTS.md @.planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md @.planning/phases/13-virtual-local-cloud-operations/13-RESEARCH.md @.planning/phases/13-virtual-local-cloud-operations/13-PATTERNS.md @backend/api/cloud/connections.py @backend/api/cloud/schemas.py @frontend/src/api/cloud.js @backend/tests/test_cloud_mutations.py @backend/tests/test_cloud_reconnect.py @backend/tests/test_cloud_security.py

Artifacts this phase produces

• backend/api/cloud/operations.py — owner-scoped explicit test and content-access routes.
• backend/api/cloud/connections.py — connection-ID reconnect patching and scope-aware OAuth handling.
• backend/api/cloud/schemas.py — typed health, reconnect, preview, and download fallback bodies.
• frontend/src/api/cloud.js — centralized client helpers for the new route family.

Pattern analogs

• backend/api/cloud/browse.py — owner-scoped connection-ID route structure.
• backend/api/documents/content.py — authorized streaming and controlled error translation.
• backend/api/cloud/connections.py — existing connect/update/disconnect patterns.
• frontend/src/api/cloud.js — centralized client boundary for cloud routes.

Task 1: Patch reconnect and explicit test flows onto the existing connection row backend/api/cloud/connections.py, backend/api/cloud/schemas.py, frontend/src/api/cloud.js, backend/tests/test_cloud_reconnect.py, backend/tests/test_cloud_security.py - backend/api/cloud/connections.py - backend/api/cloud/schemas.py - frontend/src/api/cloud.js - backend/tests/test_cloud_reconnect.py - .planning/phases/13-virtual-local-cloud-operations/13-RESEARCH.md - Test 1: reconnect patches the existing owned connection row by ID and invalidates caches without deleting metadata - Test 2: explicit test and credential-failure recovery classify reauth versus transient offline states - Test 3: Google Drive OAuth uses the broader Phase 13 access scope and exposes that state through controlled responses Update the OAuth initiation and callback flow so reconnect is an existing-connection repair path keyed by connection ID rather than a new-row insertion. Persist refreshed encrypted credentials in place, invalidate connection-scoped capability and listing caches, and mark cached metadata stale while a refresh follows D-14. Preserve D-15 by keeping transient outages non-destructive. Make the Google Drive path request the broader Phase 13 scope explicitly and keep the response schema typed so the frontend can render honest consent and health states without parsing provider payloads. - reconnect and security tests pass without creating a second connection row - broader Google Drive access is explicit in the backend flow rather than implicit or undocumented - transient offline and reauth-required states are distinguishable and credential-safe docker compose run --rm backend pytest -v tests/test_cloud_reconnect.py tests/test_cloud_security.py -k "reconnect or health or credential or scope" -x Reconnect and health routes now satisfy the connection-ID, scope, and cache-invalidating Phase 13 contract. Task 2: Add authorized open, preview, and fallback download routes with typed bodies backend/api/cloud/operations.py, backend/api/cloud/schemas.py, frontend/src/api/cloud.js, backend/tests/test_cloud_mutations.py, backend/tests/test_cloud_security.py - backend/api/documents/content.py - backend/api/cloud/schemas.py - backend/tests/test_cloud_mutations.py - backend/tests/test_cloud_security.py - .planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md - Test 1: authorized content routes expose binary-only preview and typed unsupported-preview fallback - Test 2: preview and download responses never expose raw provider URLs or credentials - Test 3: ordinary folder navigation still does not trigger a provider health probe Add `backend/api/cloud/operations.py` and expose owner-scoped open, preview, and authorized download fallback routes that call the service layer only. Use typed response and error bodies with stable `kind` and `reason` codes, limit preview support to the Phase 13 binary matrix, and keep unsupported formats on the download fallback path. Extend `frontend/src/api/cloud.js` with centralized helpers for the new routes so later UI work does not call raw URLs or construct provider-specific content paths. - content and security suites pass with typed route outputs - preview support remains explicitly binary-only and does not introduce Office-native or Google Workspace rendering - no content route leaks provider URLs, tokens, or decrypted credentials docker compose run --rm backend pytest -v tests/test_cloud_mutations.py tests/test_cloud_security.py -k "open or preview or download or content" -x The route layer now exposes safe reconnect and content endpoints that later upload and UI plans can reuse.

<threat_model>

Trust Boundaries

Boundary	Description
browser → reconnect/content routes	Untrusted requests must stay owner-scoped and CSRF-protected.
cloud route → provider bytes	Provider content must stay behind DocuVault authorization and typed error shaping.

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-13-13	E	reconnect flow	mitigate	Connection-ID patching and owner-scoped lookup are verified in reconnect and security tests.
T-13-14	I	preview/download routes	mitigate	Typed route outputs plus content/security tests forbid provider URL or token leakage.
T-13-15	T	navigation health behavior	mitigate	Reconnect tests and later UI tests assert no health probe on ordinary folder navigation.
</threat_model>

- Pass the reconnect, content, and security suites introduced in Wave 0. - Confirm every backend verification command is containerized. - Confirm binary-only preview and broader Drive scope handling are explicitly encoded in the route layer.

<success_criteria>

• Reconnect now patches the existing connection row and exposes honest health states.
• The backend has safe open, preview, and fallback download routes with typed result bodies.
• Phase 13 now encodes broader Google Drive access, binary-only preview, and no-probe-on-navigation rules concretely. </success_criteria>

Create `.planning/phases/13-virtual-local-cloud-operations/13-04-SUMMARY.md` when done