curo/kite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(14-09): Phase 14 closeout — docs, version bump v0.3.0→v0.4.0, security evidence

Browse Source 
- CLAUDE.md/AGENTS.md: update current-state line to v0.4.0 Phase 14 complete;
  add Phase 14 shared module map entries (cloud_cache, cloud_analysis,
  cloud_analysis_processing, cloud_analysis_tasks, analysis router, cache API);
  add Phase 14 non-negotiable rules (hydrate_and_cache_bytes single entry point,
  IDs-only broker payload, object_key/credentials_enc excluded at schema level)
- README.md: bump to v0.4.0; add Selective cloud analysis and Cloud byte cache
  features; add Analysis API table (Phase 14 endpoints)
- SECURITY.md: add Phase 14 threat register (T-14-01..T-14-15) with evidence,
  security gate results, and accepted risks
- backend/main.py: bump FastAPI version to 0.4.0
- frontend/package.json: bump version to 0.4.0
- ROADMAP.md: mark Phase 14 complete (9/9 plans), plan 14-09 checked off
- 14-VALIDATION.md: gate evidence, requirement coverage, acceptance criteria check
- 14-SECURITY.md: security evidence summary and gate checklist

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
curo1305
2026-06-23 20:05:49 +02:00
co-authored by Claude Sonnet 4.6
parent 2d697a6036
commit 90e1b525f1
9 changed files with 287 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+15 -4
View File
@@ -4,7 +4,7 @@
DocuVault is a multi-user SaaS document management platform built on FastAPI (Python) + Vue 3. It handles document upload, text extraction (PDF/DOCX/image/text), AI-based topic classification, per-user isolated storage, folder organization, document sharing, and pluggable cloud storage backends (OneDrive, Google Drive, Nextcloud, WebDAV).
**Current state:** v0.3.0 — Phase 13 complete 2026-06-23. Full virtual-local cloud operations: connection health/reconnect/disconnect, authorized open/preview, sequential upload queue with typed conflict resolution, create-folder/rename with collision retry and stale guard, move with descendant safety, delete with disclosure confirmation, and metadata-only audit events. 766 backend + 429 frontend tests pass. Not cleared for public internet deployment.
**Current state:** v0.4.0 — Phase 14 complete 2026-06-23. Selective cloud analysis with per-file/selection/folder/connection scope estimates (metadata-only, no bytes), idempotent Celery analysis jobs with cooperative cancellation, stale guard, and bounded retry, durable byte cache (CloudByteCacheEntry) with LRU eviction and ownership-scoped pinning, open/preview/download routed through the cache, frontend analysis queue with per-item controls and Settings integration. 856 backend + 471 frontend tests pass. Not cleared for public internet deployment.
## Stack
@@ -44,9 +44,15 @@ Before adding a helper, check if it belongs in an existing shared module:
| `backend/storage/cloud_utils.py` | `validate_cloud_url`, `normalize_nextcloud_url`, `encrypt_credentials`, `decrypt_credentials` — Phase 12.1 adds `normalize_nextcloud_url` |
| `backend/services/cloud_items.py` | `resolve_owned_connection`, `upsert_cloud_item`, `reconcile_cloud_listing`, `get_or_create_folder_state`, `apply_listing_and_finalize`, `ListingResult` — owner-scoped cloud metadata service; `apply_listing_and_finalize` is the single shared freshness gate |
| `backend/services/cloud_operations.py` | `keep_both_name(filename, counter)` — canonical D-03/D-05 keep-both collision naming (counter before first extension); `run_health_check`, `run_reconnect`, `run_upload`, `run_create_folder`, `run_rename`, `run_move`, `run_delete` — all mutation orchestration with stale guard, reconciliation, and metadata-only audit |
| `backend/api/cloud/schemas.py` | `CloudBrowseResponse`, `CloudItemOut`, `FolderFreshnessOut`, `ConnectionRenameRequest`, `CloudMutationResult`, `CloudConflictResult`, `CloudUploadResult` — credential-free cloud response schemas |
| `backend/api/cloud/schemas.py` | `CloudBrowseResponse`, `CloudItemOut`, `FolderFreshnessOut`, `ConnectionRenameRequest`, `CloudMutationResult`, `CloudConflictResult`, `CloudUploadResult`, `AnalysisEstimateOut`, `AnalysisJobOut`, `CacheStatusOut` — credential-free cloud response schemas |
| `backend/storage/cloud_base.py` | Phase 13 adds `CloudMutableAdapter` extending `CloudResourceAdapter` — normalized mutation contract (upload, create_folder, rename, move, delete) with `CloudMutationResult` typed returns; all 4 providers implement this |
| `backend/api/cloud/operations.py` | Owner-scoped cloud mutation routes: `POST /upload`, `POST /folders`, `PATCH /rename`, `POST /move`, `DELETE /items/{id}`, `POST /connections/{id}/test`, `POST /connections/{id}/reconnect`, `GET /connections/{id}/open/{item_id}`, `GET /connections/{id}/download/{item_id}` |
| `backend/services/cloud_cache.py` | Phase 14: `compute_version_key`, `create_cache_entry`, `evict_lru_entries`, `retain_or_reuse_cache_entry`, `pin_cache_entry`, `release_cache_entry`, `update_cache_access`, `hydrate_and_cache_bytes` — byte cache lifecycle; `hydrate_and_cache_bytes` is the single entry point for open/preview/download byte hydration |
| `backend/services/cloud_analysis.py` | Phase 14: `estimate_scope`, `enqueue_analysis_job`, `get_analysis_job`, `list_analysis_jobs`, `cancel_job`, `cancel_job_item`, `skip_job_item`, `retry_job_item`, `check_scan_quota` — analysis job orchestration |
| `backend/services/cloud_analysis_processing.py` | Phase 14: `process_job_item`, `ProcessingResult` — single-item Celery processing pipeline (stale guard, cache hydration, extraction, classification, cooperative cancellation) |
| `backend/tasks/cloud_analysis_tasks.py` | Phase 14: `process_cloud_analysis_item` — Celery task (IDs only in broker payload; credentials decrypted inside worker after revalidation) |
| `backend/api/cloud/analysis.py` | Phase 14: analysis router aggregator — `/api/cloud/analysis/*` namespace (estimate, jobs, controls, cache settings) |
| `backend/api/cloud/cache.py` | Phase 14: `GET /analysis/cache`, `PATCH /analysis/cache/settings` — aggregate cache status/settings; admin blocked; object_key excluded at schema level |
**Rules:**
- No router may define `_ip()`, `_get_ip()`, or any other local variant of `get_client_ip`. Import from `deps.utils`.
@@ -60,6 +66,11 @@ Before adding a helper, check if it belongs in an existing shared module:
- All cloud mutation orchestration (health, reconnect, upload, create-folder, rename, move, delete) routes through `services.cloud_operations` — never inline in the router.
- No mutation route may independently manage folder state after a mutation. Reconciliation (upsert_cloud_item + update_folder_state) is called only via `services.cloud_operations` mutation helpers.
- `testCloudConnection` is an explicit user-initiated action only — never called as a side effect of folder navigation (D-13).
- Phase 14: All byte hydration for open/preview/download/analysis routes through `hydrate_and_cache_bytes` in `services.cloud_cache` — never call `adapter.get_object` directly in router handlers.
- Phase 14: `process_cloud_analysis_item` Celery task accepts UUIDs only — credentials decrypted inside the worker after ownership revalidation (no credentials in broker payload, T-14-10).
- Phase 14: `CacheStatusOut` and `AnalysisJobOut` schemas never include `object_key` or `credentials_enc` — enforced at schema design level.
- Phase 14: Analysis estimate and already-current detection use durable `cloud_items` metadata only — zero provider bytes downloaded during estimate (T-14-04).
- Phase 14: `translateAnalysisStatus` in `cloudConnections` store is the single translation source — components never translate internal status strings independently (D-06).
### Frontend: shared module map
@@ -133,9 +144,9 @@ Before any GSD workflow or agent edits project files, create or switch into a de
/gsd:progress — check status and advance workflow
```
### Current state: v0.3.0 — Phase 13 complete (2026-06-23)
### Current state: v0.4.0 — Phase 14 complete (2026-06-23)
Phase 13 (virtual-local cloud operations) complete. Cloud browse, health/reconnect/disconnect, authorized open/preview, upload queue, create-folder, rename, move, and delete are all shipped. Phase 14 (selective analysis and byte cache) is next. Not cleared for public internet deployment.
Phase 14 (selective analysis and byte cache) complete. Selective cloud analysis with scope estimates (metadata-only), Celery processing pipeline, durable byte cache with LRU eviction and pinning, analysis queue UI with per-item controls, and Settings integration are all shipped. Phase 15 (unified smart search) is next. Not cleared for public internet deployment.
## Development Setup