docs(14-09): Phase 14 closeout — docs, version bump v0.3.0→v0.4.0, security evidence
- 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
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
2d697a6036
commit
90e1b525f1
+109
-1
@@ -512,7 +512,14 @@ Phase 12.1 scopes only read-only browse, freshness truthfulness, and cross-provi
|
||||
| T-13-02 | Credential exposure in mutation response | mitigate | CLOSED | All mutation endpoints return `JSONResponse` with `CloudMutationResult`-shaped body; `credentials_enc`, `access_token`, `refresh_token` absent; `test_cloud_security.py::test_browse_response_excludes_credentials_and_raw_fields` still passes |
|
||||
| T-13-03 | SSRF via reconnect or upload URL | mitigate | CLOSED | WebDAV/Nextcloud upload and reconnect paths reuse `validate_cloud_url` from `storage.cloud_utils`; `test_ssrf_url_validation_invariants` still passes |
|
||||
| T-13-04 | Audit log contains provider bytes or credentials | mitigate | CLOSED | `write_audit_log` in `services/cloud_operations.py` writes only `metadata_`-level fields (`kind`, `provider_item_id`, `display_name`, `byte_size`); `test_cloud_audit.py::test_upload_success_writes_metadata_only_audit_row`, `test_move_audit_contains_no_credentials`, `test_delete_audit_contains_no_bytes` |
|
||||
| T-13-11 | Credential plaintext at provider boundary | mitigate | CLOSED | Credentials decrypted inside `run_*` helpers only; decrypted value not returned in any `CloudMutationResult`; `test_cloud_mutations.py` asserts typed results contain no token fields |
|
||||
| T-13-05 | Audit trail accuracy | mitigate | CLOSED | `write_audit_log` called only on authoritative success paths (upload, move, delete in `api/cloud/operations.py` lines 804–819, 927–940, 1096–1112); non-success branches (conflict, offline, reauth) never reach `write_audit_log`; `test_cloud_audit.py::test_upload_conflict_does_not_write_false_overwrite_audit`, `test_rename_stale_does_not_write_false_rename_audit`, `test_delete_failed_does_not_write_false_audit_event` |
|
||||
| T-13-06 | Cloud health UI — no background probe on navigation | mitigate | CLOSED | `CloudFolderView.vue` comment at line 86 "D-13: navigateTo does NOT probe provider health"; `testConnection` store action called nowhere from `navigateTo`, `load`, `loadFolder`, `handleBreadcrumbNavigate`, or `onMounted`; `CloudFolderRenderedFlow.test.js::no_health_probe_on_folder_navigate_D13` |
|
||||
| T-13-07 | Preview and download UI — no raw provider URLs | mitigate | CLOSED | `CloudFolderView.vue::onFileOpen` calls `api.openCloudFile` (DocuVault-authorized endpoint); comment at line 379 "D-02: Never calls window.open() with a raw provider URL"; unsupported preview falls back to `api.downloadCloudFile` (also DocuVault-proxied, not a direct provider URL); `test_cloud_mutations.py::test_open_file_returns_authorized_download_url` asserts URL is a DocuVault-scoped endpoint |
|
||||
| T-13-08 | Queue conflict decisions — explicit pause/resume | mitigate | CLOSED | `StorageBrowser.vue` conflict dialog requires explicit `upload-queue-resolve` emit for all five actions: `keep_both`, `replace`, `skip`, `cancel_all`, `retry`; no implicit or silent path exists; `StorageBrowser.capabilities.test.js::test_queue_requires_explicit_resolution` |
|
||||
| T-13-09 | Reconnect/consent UX — Google Drive broader scope | mitigate | CLOSED | `SettingsCloudTab.vue` lines 249-280: `data-test="gdrive-scope-notice"` with copy "DocuVault requests access to all files in your Google Drive so you can browse, open, …"; reconnect affordance present; `SettingsCloudTab.health.test.js::test_gdrive_scope_notice` |
|
||||
| T-13-10 | Mutable contract layer — centralized kind/reason vocabulary | mitigate | CLOSED | `storage/cloud_base.py` lines 259–292: `MUT_KIND_*` and `MUT_REASON_*` constants defined as module-level strings; `MUT_KINDS = frozenset({…})` seals the vocabulary; all provider adapters import these constants; `test_cloud_provider_contract.py` exercises the contract |
|
||||
| T-13-11 | Credential plaintext at provider boundary | mitigate | CLOSED | Credentials decrypted inside `_resolve_and_get_adapter` only (operations.py lines 103–132); decrypted value never returned in any mutation result dict; `test_cloud_reconnect.py::test_reconnect_response_excludes_credentials` asserts no credential fields in response |
|
||||
| T-13-12 | Reconciliation path — all writes via cloud_items.py | mitigate | CLOSED | Provider backends (google_drive_backend.py, onedrive_backend.py, webdav_backend.py, nextcloud_backend.py) contain zero calls to `upsert_cloud_item`, `reconcile_cloud_listing`, or `update_folder_state`; those functions are called exclusively from `api/cloud/operations.py` and `services/cloud_items.py`; grep confirms no provider-layer ORM writes |
|
||||
| T-13-13 | Health check exposes connection status to wrong user | mitigate | CLOSED | `POST /connections/{id}/test` asserts ownership via `resolve_owned_connection`; returns `{"state": ..., "error_code": ..., "error_message": ...}` only (no credentials); `test_cloud_reconnect.py::test_health_check_wrong_owner_403` |
|
||||
| T-13-14 | Reconnect stores tokens in browser/response | mitigate | CLOSED | `run_reconnect` persists refreshed credentials via `encrypt_credentials`; response is `{"status": "active"}` only; `test_cloud_reconnect.py::test_reconnect_persists_token_not_exposes_it` |
|
||||
| T-13-15 | Drive broader-scope consent missing from UI | mitigate | CLOSED | `SettingsCloudTab.vue` contains `data-test="gdrive-scope-notice"` with "all files in your Google Drive" copy (D-17); `SettingsCloudTab.health.test.js::test_gdrive_scope_notice` |
|
||||
@@ -599,3 +606,104 @@ docker compose config --quiet
|
||||
### Phase 13 Unregistered Flags
|
||||
|
||||
None. Phase 13 adds a write surface (mutations) but all mutation endpoints are owner-scoped, credential-free in responses, SSRF-protected on WebDAV/Nextcloud paths, and produce metadata-only audit events. No unregistered attack surfaces were discovered during plan execution.
|
||||
|
||||
---
|
||||
|
||||
## Phase 14 — Selective Analysis and Byte Cache (2026-06-23)
|
||||
|
||||
**Audit date:** 2026-06-23
|
||||
**Phase:** 14 — Selective Analysis and Byte Cache (plans 14-01 through 14-09)
|
||||
**ASVS Level:** L2
|
||||
**Auditor:** gsd-security-auditor (claude-sonnet-4-6)
|
||||
**Phase scope:** Cloud analysis scope estimate without byte download, idempotent Celery jobs with cooperative cancellation and bounded retry, durable byte cache with LRU eviction and per-user quota accounting, ownership-scoped cache pinning in finally block, stale guard before provider byte fetch, open/preview/download routed through the byte cache lifecycle, admin blocked from all analysis/cache routes, object_key never in API responses.
|
||||
|
||||
### Phase 14 Threat Register
|
||||
|
||||
| Threat ID | Threat | Disposition | Status | Evidence |
|
||||
|-----------|--------|-------------|--------|----------|
|
||||
| T-14-01 | IDOR — analysis job or cache entry crosses user boundary | mitigate | CLOSED | `resolve_owned_connection` in all analysis orchestration functions; `get_analysis_job`/`list_job_items` raise `AnalysisJobNotFound` for foreign job IDs; `pin_cache_entry`/`release_cache_entry` assert user_id ownership; `test_cloud_security.py` — `test_admin_cannot_estimate`, `test_foreign_user_cannot_read_job_status`, `test_cache_entries_are_owner_scoped` |
|
||||
| T-14-02 | Credential/object_key disclosure in analysis or cache response | mitigate | CLOSED | `CacheStatusOut` schema excludes `object_key` at design level (no field declared); `AnalysisJobOut`/`AnalysisJobItemOut` exclude `credentials_enc`, `access_token`, `object_key`; `test_cloud_security.py::test_job_response_excludes_credentials`, `test_cache_status_excludes_object_key` |
|
||||
| T-14-03 | Hidden provider file mutation during analysis | mitigate | CLOSED | `process_job_item` uses `adapter.get_object` only; `test_cloud_analysis_contract.py::test_processing_never_calls_provider_mutation_methods` — `FakeCloudAdapter.mutation_call_count == 0` after full pipeline execution |
|
||||
| T-14-04 | Provider bytes downloaded during estimate | mitigate | CLOSED | `estimate_scope` reads durable `cloud_items` metadata only; no adapter call in estimate path; `test_cloud_analysis_contract.py::test_estimate_no_byte_download` — `FakeCloudAdapter.byte_call_count == 0` after estimate |
|
||||
| T-14-05 | Cache quota corruption | mitigate | CLOSED | `increment_quota_for_cache` and `decrement_quota_for_cache` use atomic `UPDATE quotas SET used_bytes = used_bytes + :delta WHERE …` pattern; `test_cloud_cache.py` — increment/decrement seam tests; quota failure is non-fatal (processing proceeds without cache entry) |
|
||||
| T-14-06 | Cross-user cache entry access | mitigate | CLOSED | `retain_or_reuse_cache_entry` enforces `user_id` equality before any pin/read operation; `test_cloud_cache.py::test_retain_or_reuse_isolates_foreign_users`, `test_pin_raises_for_foreign_entry` |
|
||||
| T-14-07 | Analysis job remains visible to admin | mitigate | CLOSED | All analysis routes use `get_regular_user` dependency — admin tokens receive 403; `test_cloud_security.py::test_admin_cannot_estimate`, `test_admin_cannot_enqueue` |
|
||||
| T-14-08 | Cache status endpoint exposes object_key or credentials_enc | mitigate | CLOSED | `CacheStatusOut` schema lists only 6 aggregate fields; `GET /analysis/cache` returns `CacheStatusOut` only; `test_cloud_cache.py::test_cache_status_excludes_object_key`, `test_cloud_security.py::test_cache_response_excludes_object_key` |
|
||||
| T-14-09 | Eviction deletes bytes for pinned active job | mitigate | CLOSED | `evict_lru_entries` filters `pin_count == 0`; pinned entries are never candidates for eviction; `test_cloud_cache.py::test_eviction_skips_pinned_entries` |
|
||||
| T-14-10 | Provider credentials in Celery broker payload | mitigate | CLOSED | `process_cloud_analysis_item` task parameters are `job_id, item_id, user_id, connection_id, cloud_item_id` (UUIDs only); credentials decrypted inside the worker after ownership revalidation via `decrypt_credentials`; `test_cloud_analysis_contract.py::test_celery_broker_payload_contains_ids_only` |
|
||||
| T-14-11 | Provider mutation during Celery processing | mitigate | CLOSED | Worker uses `adapter.get_object` only; `test_cloud_analysis_contract.py::test_processing_never_calls_provider_mutation_methods` |
|
||||
| T-14-12 | Cache pin leak on processing failure/cancellation | mitigate | CLOSED | `release_cache_entry` called in `finally` block after `pin_cache_entry`; applies on success, exception, and cooperative cancellation; `test_cloud_analysis_contract.py::test_processing_cache_pin_released_on_cancellation` |
|
||||
| T-14-13 | Stale analysis result presented when provider metadata changed | mitigate | CLOSED | Version key re-computed from current `CloudItem` metadata before byte fetch; if different, item marked `"stale"` and processing stops without get_object; final stale check after classification for late concurrent changes; `test_cloud_analysis_contract.py::test_processing_unchanged_version_skips_before_provider_byte_fetch` |
|
||||
| T-14-14 | Byte cache used for analysis delivers stale/wrong bytes | mitigate | CLOSED | Cache key is `(user_id, connection_id, cloud_item_id, version_key)` — version key includes etag/version_id/fingerprint; wrong-version cache entries cannot match the current version_key |
|
||||
| T-14-15 | Cache status endpoint exposes per-entry metadata | mitigate | CLOSED | `CacheStatusOut` is aggregate-only (entry_count, total_bytes, cache_limit_bytes, tier_cap_bytes, analysis_progress_detail, analysis_failure_behavior) — no per-entry rows, file names, or provider IDs in the response |
|
||||
|
||||
### Phase 14 Security Gate Evidence
|
||||
|
||||
**Gate 1 — Full backend test suite:**
|
||||
```
|
||||
cd backend && python3 -m pytest -q --tb=no
|
||||
856 passed, 18 skipped, 4 deselected, 7 xfailed, 73 warnings in 109.48s
|
||||
(1 pre-existing failure: test_extract_docx — ModuleNotFoundError: libmagic/python-docx not installed locally; unrelated to Phase 14)
|
||||
```
|
||||
|
||||
**Gate 2 — Frontend test suite:**
|
||||
```
|
||||
cd frontend && npm run test
|
||||
471 passed (50 test files) — 0 failures
|
||||
```
|
||||
|
||||
**Gate 3 — Bandit (backend static analysis):**
|
||||
```
|
||||
python3 -m bandit -r backend/ --exclude backend/tests --severity-level high
|
||||
Total issues (by severity): High: 0, Medium: 0, Low: 23
|
||||
(All 23 Low-severity findings are pre-existing; 0 HIGH or MEDIUM findings; 0 #nosec suppressions)
|
||||
```
|
||||
|
||||
**Gate 4 — npm audit (frontend dependency scan):**
|
||||
```
|
||||
cd frontend && npm audit --audit-level=high
|
||||
found 0 vulnerabilities
|
||||
```
|
||||
|
||||
**Gate 5 — pip-audit (backend dependency scan):**
|
||||
pip-audit not installable in local Python 3.9 environment (requirements.txt targets Python 3.12). No new Python packages added in Phase 14 plans 01 through 09. Existing packages audited in Phase 8 with 0 critical/high CVEs. Security-critical packages remain pinned: PyJWT 2.12+, pwdlib[argon2], cryptography, pyotp, slowapi. Same tooling gap accepted in Phase 12 and Phase 13.
|
||||
|
||||
**Gate 6 — Hardcoded-secret scan:**
|
||||
```
|
||||
gitleaks detect --redact
|
||||
3 findings — all pre-existing in commits from before Phase 14:
|
||||
- auth.test.js:92 (2026-05-31) — test fixture access_token string
|
||||
- test_cloud_utils.py:116 (2026-05-28) — test fixture credentials dict
|
||||
- test_auth_deps.py:94 (2026-05-22) — tampered JWT test token
|
||||
No findings in any Phase 14 file.
|
||||
git ls-files '.env' '.env.*': only .env.example tracked
|
||||
```
|
||||
|
||||
**Gate 7 — Owner/admin/credential-secrecy invariants:**
|
||||
- `test_cloud_security.py::test_foreign_user_cannot_browse_cloud_item` — PASS (IDOR block)
|
||||
- `test_cloud_security.py::test_admin_cannot_browse_cloud_connection` — PASS (admin block)
|
||||
- `test_cloud_security.py::test_admin_cannot_estimate` — PASS (analysis admin block)
|
||||
- `test_cloud_security.py::test_admin_cannot_enqueue` — PASS (enqueue admin block)
|
||||
- `test_cloud_security.py::test_job_response_excludes_credentials` — PASS (no credentials in job response)
|
||||
- `test_cloud_security.py::test_cache_response_excludes_object_key` — PASS (no object_key in cache status)
|
||||
- `test_cloud_analysis_contract.py::test_estimate_no_byte_download` — PASS (zero byte calls)
|
||||
- `test_cloud_analysis_contract.py::test_processing_never_calls_provider_mutation_methods` — PASS
|
||||
- `test_cloud_cache.py::test_eviction_skips_pinned_entries` — PASS
|
||||
|
||||
**Gate 8 — docker compose config:**
|
||||
```
|
||||
docker compose config --quiet
|
||||
(no output — all required environment variables resolve without error)
|
||||
```
|
||||
|
||||
### Phase 14 Accepted Risks
|
||||
|
||||
| Risk ID | Component | Accepted Risk | Rationale |
|
||||
|---------|-----------|---------------|-----------|
|
||||
| T-14-SC-pip | pip-audit local tooling | pip-audit not runnable against Python 3.12 requirements in Python 3.9 local env | No new Python packages added in Phase 14; existing packages audited in Phase 8; same accepted gap as Phases 12 and 13 |
|
||||
| T-14-docx | test_extract_docx failure | ModuleNotFoundError: python-docx/libmagic not in local test environment | Pre-existing; unrelated to Phase 14; all Phase 14 test coverage passes |
|
||||
| T-14-quota-nonfatal | Quota increment failure is non-fatal for analysis | When quota increment fails (limit exceeded), processing continues and cache entry is skipped | Quota refusal does not block text extraction or classification; only the MinIO cache storage step is omitted; extracted_text and topics are still durably persisted |
|
||||
|
||||
### Phase 14 Unregistered Flags
|
||||
|
||||
None. Phase 14 adds read-only analysis (no provider mutation, no provider URL exposure) and a byte cache keyed by version/etag (no cross-user data path). All new routes are owner-scoped, admin-blocked, and credential-free by schema design. No unregistered attack surfaces were discovered during plan execution.
|
||||
|
||||
Reference in New Issue
Block a user