Plans 01–11, CONTEXT, PATTERNS, RESEARCH, REVIEW-FIX, and updated
SUMMARY and CONTEXT for the virtual-local-cloud-operations phase.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.
path
provides
backend/tests/test_cloud_mutations.py
Red endpoint and mutation-result coverage for open, preview, upload, create, rename, move, and delete.
path
provides
backend/tests/test_cloud_reconnect.py
Red reconnect, health, cache invalidation, and credential-refresh persistence coverage.
path
provides
backend/tests/test_cloud_audit.py
Red metadata-only audit assertions for successful cloud operations.
path
provides
backend/tests/test_cloud_backends.py
Provider-specific mutation and conflict/error normalization coverage.
path
provides
backend/tests/test_cloud_provider_contract.py
Canonical mutable-adapter contract coverage across Google Drive, OneDrive, Nextcloud, and WebDAV.
from
to
via
pattern
mutable adapter methods
provider contract suites
normalized kind/reason result assertions
kind
from
to
via
pattern
OneDrive token refresh success
cloud_connections.credentials_enc persistence
reconnect and content-operation regressions
refresh_token
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.
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.
Task 1: Add red API and audit contracts for reconnect, content, and mutation flows
backend/tests/test_cloud_mutations.py, backend/tests/test_cloud_reconnect.py, backend/tests/test_cloud_audit.py
- 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
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.
- 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
docker compose run --rm backend pytest -v tests/test_cloud_mutations.py tests/test_cloud_reconnect.py tests/test_cloud_audit.py -x
Backend red suites now define the Phase 13 reconnect, content, mutation, and audit truth.
Task 2: Extend provider contract suites for four-provider mutable-operation parity
backend/tests/test_cloud_backends.py, backend/tests/test_cloud_provider_contract.py
- 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
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.
- 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
docker compose run --rm backend pytest -v tests/test_cloud_backends.py tests/test_cloud_provider_contract.py -x
Four-provider mutable-operation parity is now blocked by red backend contract coverage.
<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>
- 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.
<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>
Create `.planning/phases/13-virtual-local-cloud-operations/13-01-SUMMARY.md` when done
