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

---
phase: "13"
plan: "01"
type: tdd
wave: 0
depends_on: []
files_modified:
  - backend/tests/test_cloud_mutations.py
  - backend/tests/test_cloud_reconnect.py
  - backend/tests/test_cloud_audit.py
  - backend/tests/test_cloud_backends.py
  - backend/tests/test_cloud_provider_contract.py
autonomous: true
requirements:
  - CONN-01
  - CONN-02
  - CONN-03
  - CLOUD-02
  - CLOUD-03
  - CLOUD-04
  - CLOUD-05
  - CLOUD-06
  - CLOUD-07
  - CLOUD-09
must_haves:
  truths:
    - "Phase 13 backend work starts from failing contracts instead of inferred behavior."
    - "All four providers are held to one mutation, reconnect, health, and secrecy contract before implementation."
    - "Reconnect, refreshed-credential persistence, conflict typing, unsupported-operation disclosure, and metadata-only auditing are blocked by tests, not left implicit."
  artifacts:
    - path: "backend/tests/test_cloud_mutations.py"
      provides: "Red endpoint and mutation-result coverage for open, preview, upload, create, rename, move, and delete."
    - path: "backend/tests/test_cloud_reconnect.py"
      provides: "Red reconnect, health, cache invalidation, and credential-refresh persistence coverage."
    - path: "backend/tests/test_cloud_audit.py"
      provides: "Red metadata-only audit assertions for successful cloud operations."
    - path: "backend/tests/test_cloud_backends.py"
      provides: "Provider-specific mutation and conflict/error normalization coverage."
    - path: "backend/tests/test_cloud_provider_contract.py"
      provides: "Canonical mutable-adapter contract coverage across Google Drive, OneDrive, Nextcloud, and WebDAV."
  key_links:
    - from: "mutable adapter methods"
      to: "provider contract suites"
      via: "normalized kind/reason result assertions"
      pattern: "kind"
    - from: "OneDrive token refresh success"
      to: "cloud_connections.credentials_enc persistence"
      via: "reconnect and content-operation regressions"
      pattern: "refresh_token"
---

<objective>
Create the missing red backend and provider-contract suites for Phase 13 so reconnect, content access, uploads, folder mutations, audit secrecy, and provider normalization are fully specified before implementation.

Purpose: Turn the resolved Phase 13 decisions into executable backend contracts.
Output: Failing backend test files and extensions that cover all ten Phase 13 requirements.
</objective>

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

<context>
@AGENTS.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.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/tests/test_cloud.py
@backend/tests/test_cloud_security.py
@backend/tests/test_cloud_backends.py
@backend/tests/test_cloud_provider_contract.py
@backend/tests/test_cloud_items.py
</context>

## Artifacts this phase produces

- `backend/tests/test_cloud_mutations.py` — red endpoint contracts for typed `{kind, reason}` content and mutation results.
- `backend/tests/test_cloud_reconnect.py` — red reconnect, health, cache invalidation, and refreshed-credential persistence coverage.
- `backend/tests/test_cloud_audit.py` — red metadata-only audit coverage for successful cloud operations.
- Extended `backend/tests/test_cloud_backends.py` and `backend/tests/test_cloud_provider_contract.py` for four-provider mutable-operation coverage.

## Pattern analogs

- `backend/tests/test_cloud.py` — connection-ID API integration style and DB side-effect assertions.
- `backend/tests/test_cloud_security.py` — owner/admin/credential/SSRF negative coverage style.
- `backend/tests/test_cloud_backends.py` — provider-specific fixture and normalization style.
- `backend/tests/test_cloud_provider_contract.py` — canonical contract verification style for all providers.
- `backend/tests/test_cloud_items.py` — reconciliation and freshness truth assertions.

<tasks>

<task type="auto">
  <name>Task 1: Add red API and audit contracts for reconnect, content, and mutation flows</name>
  <files>backend/tests/test_cloud_mutations.py, backend/tests/test_cloud_reconnect.py, backend/tests/test_cloud_audit.py</files>
  <read_first>
    - backend/tests/test_cloud.py
    - backend/tests/test_cloud_security.py
    - backend/tests/test_cloud_items.py
    - .planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md
  </read_first>
  <action>
    Create failing integration and security tests for D-02 through D-18 and CONN-01 through CONN-03. Require connection-ID reconnect patching of the existing row, explicit connection test behavior, automatic health re-evaluation after credential failures, cached metadata preservation during transient outages, and typed `kind` plus `reason` bodies for conflict, stale, offline, reauth-required, invalid-destination, unsupported-preview, and unsupported-operation outcomes.

    Cover binary-only preview per D-18, authorized download fallback for unsupported preview formats per D-02, metadata-only audit rows for successful reconnect/open/preview/upload/create/rename/move/delete, and disconnect semantics that remove credentials and connection-scoped metadata without touching provider files. Add negative cases proving raw provider URLs, access tokens, refresh tokens, `credentials_enc`, and provider-owned bytes never leak through responses, logs, or audit payloads.
  </action>
  <acceptance_criteria>
    - the new suites fail against the current codebase because the Phase 13 routes and semantics do not yet exist
    - reconnect tests require patch-in-place row preservation and persisted refreshed credentials
    - mutation tests require typed `kind` and `reason` bodies instead of Vue-side inference
    - audit tests reject provider URLs, tokens, bytes, and document content in successful-operation metadata
  </acceptance_criteria>
  <verify>
    <automated>docker compose run --rm backend pytest -v tests/test_cloud_mutations.py tests/test_cloud_reconnect.py tests/test_cloud_audit.py -x</automated>
  </verify>
  <done>Backend red suites now define the Phase 13 reconnect, content, mutation, and audit truth.</done>
</task>

<task type="auto">
  <name>Task 2: Extend provider contract suites for four-provider mutable-operation parity</name>
  <files>backend/tests/test_cloud_backends.py, backend/tests/test_cloud_provider_contract.py</files>
  <read_first>
    - backend/tests/test_cloud_backends.py
    - backend/tests/test_cloud_provider_contract.py
    - backend/storage/cloud_base.py
    - backend/storage/google_drive_backend.py
    - backend/storage/onedrive_backend.py
    - backend/storage/nextcloud_backend.py
    - backend/storage/webdav_backend.py
    - .planning/phases/13-virtual-local-cloud-operations/13-RESEARCH.md
  </read_first>
  <action>
    Add red provider-level coverage for Google Drive, OneDrive, Nextcloud, and WebDAV so the mutable contract explicitly proves normalized create-folder, rename, move, delete, upload, preview-support, and explicit unsupported-operation disclosure behavior. Include D-17 broader Google Drive access expectations, OneDrive refreshed-credential handoff to the service layer, Nextcloud and WebDAV SSRF or redirect protections, collision normalization, trash-versus-permanent delete disclosure, and explicit unsupported preview or replace semantics where providers cannot honor a requested operation.

    Keep the contract provider-neutral: signature, caller identity, no direct `cloud_items` writes, no browse-time byte transfer, and no hidden overwrite path. Use the existing contract-test idiom so later implementation must satisfy one canonical interface instead of per-provider router branching.
  </action>
  <acceptance_criteria>
    - the provider suites fail until mutable contract methods and normalized result types exist
    - every supported provider has explicit assertions for conflict/error normalization, refreshed-credential persistence handoff, SSRF defense, and unsupported-operation disclosure
    - no new test encodes provider-specific API payloads in router-visible shapes
  </acceptance_criteria>
  <verify>
    <automated>docker compose run --rm backend pytest -v tests/test_cloud_backends.py tests/test_cloud_provider_contract.py -x</automated>
  </verify>
  <done>Four-provider mutable-operation parity is now blocked by red backend contract coverage.</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| client → cloud API | Untrusted user input can trigger reconnect, content, and mutation operations. |
| cloud API → provider SDK/HTTP | Provider failures and URLs must be normalized before reaching API responses. |
| request transaction → audit log | Successful operations must log metadata only, with no secret or byte leakage. |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-13-01 | E | reconnect/content/mutation routes | mitigate | Red owner-scope tests cover wrong-user, admin, and cross-connection access paths. |
| T-13-02 | I | content and preview responses | mitigate | Red tests inspect bodies, headers, and audit rows for provider URLs, tokens, and `credentials_enc`. |
| T-13-03 | T | provider conflict handling | mitigate | Red tests require typed `kind`/`reason` conflict bodies and no silent overwrite path. |
| T-13-04 | T | Nextcloud/WebDAV outbound calls | mitigate | Provider contract tests require SSRF validation and controlled redirect handling. |
| T-13-05 | R | audit trail accuracy | mitigate | Audit tests require metadata-only rows for successful operations and no false overwrite events. |
</threat_model>

<verification>
- Confirm the new backend suites fail in the expected places.
- Confirm every backend verification command uses `docker compose run --rm backend pytest ...`.
- Confirm provider-level mutable-operation coverage exists for Google Drive, OneDrive, Nextcloud, and WebDAV.
</verification>

<success_criteria>
- Phase 13 backend implementation cannot start without failing tests for reconnect, content, upload, folder mutations, and audit secrecy.
- Provider-level contract coverage now includes lifecycle, content, upload, token persistence, unsupported-capability disclosure, conflict normalization, and SSRF protections.
- No host `pytest` command remains in this plan.
</success_criteria>

<output>
Create `.planning/phases/13-virtual-local-cloud-operations/13-01-SUMMARY.md` when done
</output>