docs(05-01): complete Wave 0 Nyquist scaffold plan
- Create 05-01-SUMMARY.md documenting all 3 tasks and 5 files modified - Update STATE.md: session record, progress 78% (25/32 plans), resume file → 05-02 - Update ROADMAP.md: Phase 5 progress (1/8 summaries, In Progress) - Update REQUIREMENTS.md: mark CLOUD-01..07 complete (Wave 0 scaffold)
This commit is contained in:
curo1305
@@ -66,13 +66,13 @@ _Last updated: 2026-05-21_
|
||||
|
||||
### Cloud Storage (CLOUD)
|
||||
|
||||
- [ ] **CLOUD-01**: User can connect OneDrive (Microsoft Graph), Google Drive (v3 API), Nextcloud, or generic WebDAV as a personal storage backend
|
||||
- [ ] **CLOUD-02**: Cloud OAuth credentials encrypted using HKDF per-user key derivation (`HKDF(master_key, salt=user_id_bytes, info=b"cloud-credentials")`); master key in `CLOUD_CREDS_KEY` env var; never stored in DB
|
||||
- [ ] **CLOUD-03**: Local MinIO storage and connected cloud backends coexist; user can select their default storage destination
|
||||
- [ ] **CLOUD-04**: Each cloud connection displays status: `ACTIVE | REQUIRES_REAUTH | ERROR`
|
||||
- [ ] **CLOUD-05**: On OAuth revocation (`invalid_grant`), connection status transitions to `REQUIRES_REAUTH` — the error is surfaced to the user, not retried silently
|
||||
- [ ] **CLOUD-06**: User can disconnect a cloud backend; credentials are permanently deleted from the DB
|
||||
- [ ] **CLOUD-07**: Storage backend abstracted via `StorageBackend` ABC + factory in `storage/` module (mirrors existing `ai/` provider pattern)
|
||||
- [x] **CLOUD-01**: User can connect OneDrive (Microsoft Graph), Google Drive (v3 API), Nextcloud, or generic WebDAV as a personal storage backend
|
||||
- [x] **CLOUD-02**: Cloud OAuth credentials encrypted using HKDF per-user key derivation (`HKDF(master_key, salt=user_id_bytes, info=b"cloud-credentials")`); master key in `CLOUD_CREDS_KEY` env var; never stored in DB
|
||||
- [x] **CLOUD-03**: Local MinIO storage and connected cloud backends coexist; user can select their default storage destination
|
||||
- [x] **CLOUD-04**: Each cloud connection displays status: `ACTIVE | REQUIRES_REAUTH | ERROR`
|
||||
- [x] **CLOUD-05**: On OAuth revocation (`invalid_grant`), connection status transitions to `REQUIRES_REAUTH` — the error is surfaced to the user, not retried silently
|
||||
- [x] **CLOUD-06**: User can disconnect a cloud backend; credentials are permanently deleted from the DB
|
||||
- [x] **CLOUD-07**: Storage backend abstracted via `StorageBackend` ABC + factory in `storage/` module (mirrors existing `ai/` provider pattern)
|
||||
|
||||
### Documents & AI (DOC)
|
||||
|
||||
|
||||
+41
-2
@@ -25,18 +25,21 @@ Before any phase is marked complete, all three gates must pass:
|
||||
## Phase Details
|
||||
|
||||
### Phase 1: Infrastructure Foundation
|
||||
|
||||
**Goal**: PostgreSQL + MinIO are wired into Docker Compose with a complete Alembic-managed schema; all services boot cleanly and the existing single-user document scanner continues to work exactly as before — no user-facing behavior change.
|
||||
**Mode:** mvp
|
||||
**Depends on**: Nothing (first phase)
|
||||
**Requirements**: STORE-01, STORE-02, STORE-07
|
||||
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. `docker compose up` starts PostgreSQL, MinIO, and the FastAPI backend with no errors; health checks pass for all three services
|
||||
2. Running `alembic upgrade head` applies the initial migration cleanly against the fresh PostgreSQL instance with no errors
|
||||
3. The full existing document upload, text extraction, and AI classification workflow completes successfully — no regression in single-user behavior
|
||||
4. MinIO object key schema `{user_id}/{document_id}/{uuid4()}{ext}` is enforced in the model layer; human-readable filenames are stored in the DB column, not in the MinIO key
|
||||
|
||||
**Plans**: 5 plans
|
||||
|
||||
- [x] 01-01-PLAN.md — Docker Compose service topology + Postgres init + Pydantic Settings + requirements
|
||||
- [x] 01-02-PLAN.md — Wave 0 test scaffolds (xfail/skip stubs) + async pytest fixtures
|
||||
- [x] 01-03-PLAN.md — SQLAlchemy ORM models + async engine + Alembic async migration (incl. alembic upgrade head)
|
||||
@@ -46,12 +49,14 @@ Before any phase is marked complete, all three gates must pass:
|
||||
---
|
||||
|
||||
### Phase 2: Users & Authentication
|
||||
|
||||
**Goal**: Users can register, log in (with optional TOTP 2FA), reset their password, and sign out all active sessions; admins can manage user accounts and assign AI providers — all enforced by a complete FastAPI dependency chain.
|
||||
**Mode:** mvp
|
||||
**Depends on**: Phase 1
|
||||
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06, AUTH-07, AUTH-08, SEC-01, SEC-02, SEC-03, SEC-05, SEC-06, SEC-07, ADMIN-01, ADMIN-02, ADMIN-03, ADMIN-04, ADMIN-05, ADMIN-07
|
||||
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. A new user can register with an email and password that passes strength validation; a password from the HaveIBeenPwned list is rejected with a clear error
|
||||
2. A logged-in user can enroll a TOTP authenticator app, receive 8–10 backup codes, explicitly acknowledge them, and thereafter be required to supply a TOTP code (or backup code) on every login — a backup code is invalidated on first use
|
||||
3. A user who forgets their password can receive a reset email, follow the link within 1 hour, set a new password, and is then returned to the TOTP login gate (not auto-logged in)
|
||||
@@ -61,21 +66,27 @@ Before any phase is marked complete, all three gates must pass:
|
||||
**Plans**: 5 plans
|
||||
|
||||
**Wave 1** — Foundation
|
||||
|
||||
- [x] 02-01-PLAN.md — Auth service layer (Argon2, JWT, refresh tokens, TOTP, backup codes, HIBP, security alert), FastAPI deps, BackupCode model + password_must_change migration
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
|
||||
- [x] 02-02-PLAN.md — Register/login (TOTP + backup code paths) + refresh/logout/change-password endpoints + CSP/Origin validation/rate-limit (IP + per-account) + Vue auth store + router guard + Login/Register views
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
|
||||
- [x] 02-03-PLAN.md — TOTP enrollment + backup codes + password reset + sign-out-all endpoints + AccountView + TotpEnrollment + BackupCodesDisplay + PasswordReset views
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
|
||||
- [x] 02-04-PLAN.md — Admin backend: user CRUD, quota, AI config endpoints with get_current_admin enforced + tests
|
||||
|
||||
**Wave 5** *(blocked on Wave 4 completion)*
|
||||
|
||||
- [x] 02-05-PLAN.md — Admin panel frontend: AdminView + three tab components + AppSidebar admin link and user identity footer
|
||||
|
||||
**Cross-cutting constraints:**
|
||||
|
||||
- JWT access token in Pinia memory only — never localStorage (Plans 02, 03, 05)
|
||||
- Refresh token httpOnly SameSite=Strict cookie on all token issuance (Plans 02, 03)
|
||||
- Admin endpoints never return document content or credentials_enc (Plans 04, 05)
|
||||
@@ -86,12 +97,14 @@ Before any phase is marked complete, all three gates must pass:
|
||||
---
|
||||
|
||||
### Phase 3: Document Migration & Multi-User Isolation
|
||||
|
||||
**Goal**: All existing documents have been migrated from flat-file JSON + filesystem into PostgreSQL + MinIO; all new uploads use the presigned URL flow; per-user isolation is enforced at the DB level; the existing document UI works without regression; the backend is stateless and ready for horizontal scaling.
|
||||
**Mode:** mvp
|
||||
**Depends on**: Phase 2
|
||||
**Requirements**: STORE-03, STORE-04, STORE-05, STORE-06, STORE-08, SEC-04, DOC-03, DOC-04, DOC-05
|
||||
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. Every document present before migration is accessible after migration with the same metadata and extracted text; a count reconciliation check confirms zero document loss
|
||||
2. Two concurrent uploads that would together exceed a user's 100 MB quota result in exactly one success and one 413 rejection — the quota never goes over limit
|
||||
3. A document delete atomically decrements the user's recorded quota usage; after deletion the quota reflects the freed bytes
|
||||
@@ -101,27 +114,34 @@ Before any phase is marked complete, all three gates must pass:
|
||||
**Plans**: 5 plans
|
||||
|
||||
**Wave 1** — Migration + test scaffolds
|
||||
|
||||
- [x] 03-01-PLAN.md — Wave 0 test scaffolds (auth_user/admin_user/MinIO mock fixtures + 19 xfail stubs) + Alembic migration 0003 (null-user cleanup, NOT NULL constraint, topic cleanup, quota reconciliation, ix_topics_user_id) — Complete 2026-05-23
|
||||
|
||||
**Wave 2** *(blocked on Wave 1)*
|
||||
|
||||
- [ ] 03-02-PLAN.md — Presigned upload backend: StorageBackend ABC + MinIOBackend dual client + generate_presigned_put_url/stat_object + /api/documents/upload-url + /api/documents/{id}/confirm with atomic quota UPDATE + GET /api/auth/me/quota + delete-with-quota + abandoned-upload Celery beat + docker-compose CORS/celery-beat
|
||||
|
||||
**Wave 3** *(blocked on Wave 2)*
|
||||
|
||||
- [x] 03-03-PLAN.md — Auth guards: get_regular_user dep + ownership assertions on every /api/documents/* handler (404 not 403) + admin 403 + real user_id in object_key + namespace-scoped /api/topics/* + POST /api/admin/topics + classifier topic-namespace plumbing
|
||||
|
||||
**Wave 4** *(blocked on Wave 3)*
|
||||
|
||||
- [x] 03-04-PLAN.md — Settings retirement + per-user AI: delete /api/settings + remove load_settings/save_settings + classifier accepts ai_provider/ai_model kwargs + Celery task resolves user.ai_provider via DB + frontend SettingsView placeholder + remove settings store/API — Complete 2026-05-23
|
||||
|
||||
**Wave 5** *(blocked on Wave 4)*
|
||||
|
||||
- [ ] 03-05-PLAN.md — Frontend upload flow + quota bar: 3-step upload action with XHR progress + UploadProgress.vue progress bar and quota rejection error block + QuotaBar.vue + AppSidebar embed + quota state in auth store + human checkpoint
|
||||
|
||||
**Cross-cutting constraints:**
|
||||
|
||||
- Atomic quota UPDATE pattern only lives in Plan 02; never duplicate (CLAUDE.md)
|
||||
- Every /api/documents/* handler injects get_regular_user (Plan 03)
|
||||
- AI provider/model resolved only via Celery task DB lookup (Plan 04)
|
||||
- Browser XHR PUT to MinIO sends NO Authorization header (Plan 05)
|
||||
|
||||
**Phase gates (must pass before Phase 3 is complete):**
|
||||
|
||||
- [ ] `pytest -v` — zero failures; presigned URL, quota enforcement, ownership isolation, and admin-403 all covered
|
||||
- [ ] Security agent: path traversal check on object key construction; cross-user IDOR tests; quota race condition test
|
||||
- [ ] Bandit + pip audit + npm audit all clean
|
||||
@@ -131,12 +151,14 @@ Before any phase is marked complete, all three gates must pass:
|
||||
---
|
||||
|
||||
### Phase 4: Folders, Sharing, Quotas & Document UX
|
||||
|
||||
**Goal**: Users have a complete document management experience — organized with folders, shared by handle, warned before they hit quota, able to preview PDFs in-browser, and served by a searchable document list; admins can view the append-only audit log.
|
||||
**Mode:** mvp
|
||||
**Depends on**: Phase 3
|
||||
**Requirements**: FOLD-01, FOLD-02, FOLD-03, FOLD-04, FOLD-05, SHARE-01, SHARE-02, SHARE-03, SHARE-04, SHARE-05, SEC-08, SEC-09, ADMIN-06, DOC-01, DOC-02
|
||||
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. A user can create, rename, and delete folders; moving a document between folders preserves its metadata and AI classification; deleting a non-empty folder prompts with the content count before proceeding
|
||||
2. A user can share a document with another user by handle; the recipient sees it appear in a "Shared with me" virtual folder with no storage quota charged against them; the owner can revoke access and the shared entry disappears immediately for the recipient
|
||||
3. The sidebar quota bar displays current usage in MB; it turns amber at 80% and red at 95%; an upload that would exceed the limit is rejected with an error showing current usage, the rejected file size, and a link to storage settings
|
||||
@@ -146,27 +168,34 @@ Before any phase is marked complete, all three gates must pass:
|
||||
**Plans**: 9 plans
|
||||
|
||||
**Wave 1** — Test scaffolds + DB migration (parallel)
|
||||
|
||||
- [x] 04-01-PLAN.md — Wave 0 test stubs: test_folders.py + test_shares.py + test_audit.py + proxy stubs in test_documents.py + SEC-08/SEC-09 stubs in test_security.py
|
||||
- [x] 04-02-PLAN.md — Alembic migration 0004 (users.pdf_open_mode, GIN FTS index, audit-logs bucket) + MinIOBackend.put_object_raw()
|
||||
|
||||
**Wave 2** *(blocked on Wave 1)*
|
||||
|
||||
- [x] 04-03-PLAN.md — Audit service (write_audit_log) + Folders API (FOLD-01..05): POST/GET/PATCH/DELETE /api/folders + PATCH /api/documents/{id}/folder + document list sort/search/is_shared extension
|
||||
- [ ] 04-04-PLAN.md — Shares API (SHARE-01..05): POST/GET /api/shares + GET /api/shares/received + DELETE /api/shares/{id} with IDOR protection
|
||||
|
||||
**Wave 3** *(blocked on Wave 2)*
|
||||
|
||||
- [ ] 04-05-PLAN.md — PDF streaming proxy GET /api/documents/{id}/content with Range header support + PATCH /api/auth/me/preferences (pdf_open_mode)
|
||||
- [ ] 04-06-PLAN.md — Admin audit log API (GET /api/admin/audit-log, CSV export) + Celery beat daily audit export task + celery_app.py beat schedule
|
||||
|
||||
**Wave 4** *(blocked on Wave 3)*
|
||||
|
||||
- [ ] 04-07-PLAN.md — SEC-08/SEC-09 hardening + audit log backfill into auth.py/admin.py/documents.py + CloudConnectionOut Pydantic model + delete-user file cleanup
|
||||
|
||||
**Wave 5** *(blocked on Wave 4)*
|
||||
|
||||
- [ ] 04-08-PLAN.md — Frontend data layer: API client functions + useFoldersStore + documents store extension + Vue Router routes (/folders/:folderId, /shared)
|
||||
|
||||
**Wave 6** *(blocked on Wave 5)*
|
||||
|
||||
- [ ] 04-09-PLAN.md — Frontend UI: all new components (FolderRow, FolderBreadcrumb, FolderDeleteModal, ShareModal, DocumentPreviewModal, SearchBar, SortControls, AuditLogTab) + view wiring (AppSidebar, DocumentCard, HomeView, FolderView, SharedView, SettingsView, AdminView) + human checkpoint
|
||||
|
||||
**Phase gates (must pass before Phase 4 is complete):**
|
||||
|
||||
- [ ] `pytest -v` — zero failures; folder ownership, share revocation, quota bar, PDF proxy (no presigned URL exposure) all covered
|
||||
- [ ] Security agent: audit log verified to contain zero document content; sharing IDOR tests; PDF proxy verified to not leak presigned URLs or object keys
|
||||
- [ ] Bandit + pip audit + npm audit all clean
|
||||
@@ -176,12 +205,14 @@ Before any phase is marked complete, all three gates must pass:
|
||||
---
|
||||
|
||||
### Phase 5: Cloud Storage Backends
|
||||
|
||||
**Goal**: Users can connect OneDrive, Google Drive, Nextcloud, or a generic WebDAV server as a personal storage backend; credentials are encrypted with a per-user HKDF-derived key; connection status is visible; local and cloud storage coexist; the `StorageBackend` ABC makes adding further backends straightforward.
|
||||
**Mode:** mvp
|
||||
**Depends on**: Phase 4
|
||||
**Requirements**: CLOUD-01, CLOUD-02, CLOUD-03, CLOUD-04, CLOUD-05, CLOUD-06, CLOUD-07
|
||||
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. A user can connect OneDrive, Google Drive, Nextcloud, or a WebDAV endpoint through an OAuth or credential flow; the connection status is displayed as `ACTIVE`, `REQUIRES_REAUTH`, or `ERROR` — never shows raw credentials
|
||||
2. When an OAuth token is revoked externally (simulated `invalid_grant` response), the connection status transitions to `REQUIRES_REAUTH` without a 500 error; the user is shown a re-authentication prompt
|
||||
3. A user can select their connected cloud backend as the default storage destination for new uploads; local MinIO storage remains available as an alternative; existing local documents are unaffected
|
||||
@@ -191,28 +222,36 @@ Before any phase is marked complete, all three gates must pass:
|
||||
**Plans**: 8 plans
|
||||
|
||||
**Wave 1** — Test scaffold + dependencies
|
||||
- [ ] 05-01-PLAN.md — Wave 0 xfail stubs, conftest cloud fixtures, requirements.txt packages, config.py settings
|
||||
|
||||
- [x] 05-01-PLAN.md — Wave 0 xfail stubs, conftest cloud fixtures, requirements.txt packages, config.py settings
|
||||
|
||||
**Wave 2** — Shared utilities
|
||||
|
||||
- [ ] 05-02-PLAN.md — cloud_utils.py (SSRF + HKDF), cloud_cache.py (TTLCache), storage factory extension
|
||||
|
||||
**Wave 3** — Cloud backends (parallel, both blocked on Wave 2 / Plan 05-02)
|
||||
|
||||
- [ ] 05-03-PLAN.md — GoogleDriveBackend + OneDriveBackend (all 7 StorageBackend methods)
|
||||
- [ ] 05-04-PLAN.md — NextcloudBackend + WebDAVBackend (all 7 StorageBackend methods)
|
||||
|
||||
**Wave 4** — Cloud API
|
||||
|
||||
- [ ] 05-05-PLAN.md — All /api/cloud/* endpoints + /api/users/me/default-storage + main.py router registration
|
||||
|
||||
**Wave 5** — Document routing + full test suite
|
||||
|
||||
- [ ] 05-06-PLAN.md — Upload/content proxy cloud routing + all 15 tests promoted to passing
|
||||
|
||||
**Wave 6** — Frontend settings UI
|
||||
|
||||
- [ ] 05-07-PLAN.md — cloudConnections store + API client + SettingsView 3-tab + SettingsCloudTab + CloudCredentialModal
|
||||
|
||||
**Wave 7** — Frontend sidebar (human checkpoint)
|
||||
|
||||
- [ ] 05-08-PLAN.md — AppSidebar cloud section + CloudProviderTreeItem + CloudFolderTreeItem + human checkpoint
|
||||
|
||||
**Phase gates (must pass before Phase 5 is complete):**
|
||||
|
||||
- [ ] `pytest -v` — zero failures; SSRF prevention on WebDAV/Nextcloud user-supplied URLs; credential encryption/decryption round-trip; admin response never exposes `credentials_enc`; OAuth invalid_grant handling
|
||||
- [ ] Security agent: SSRF allowlist verification; credential key derivation correctness; connection status never leaks raw credential values
|
||||
- [ ] Bandit + pip audit + npm audit all clean
|
||||
@@ -229,4 +268,4 @@ Before any phase is marked complete, all three gates must pass:
|
||||
| 2. Users & Authentication | 5/5 | Complete | 2026-05-22 |
|
||||
| 3. Document Migration & Multi-User Isolation | 5/5 | Complete | 2026-05-25 |
|
||||
| 4. Folders, Sharing, Quotas & Document UX | 9/9 | Complete | 2026-05-28 |
|
||||
| 5. Cloud Storage Backends | 0/8 | In Progress | - |
|
||||
| 5. Cloud Storage Backends | 1/8 | In Progress| |
|
||||
|
||||
+8
-7
@@ -3,14 +3,14 @@ gsd_state_version: 1.0
|
||||
milestone: v1.0
|
||||
milestone_name: milestone
|
||||
current_phase: 5
|
||||
status: planned
|
||||
last_updated: "2026-05-28T19:45:00.000Z"
|
||||
status: executing
|
||||
last_updated: "2026-05-28T18:54:16.369Z"
|
||||
progress:
|
||||
total_phases: 5
|
||||
completed_phases: 4
|
||||
total_plans: 32
|
||||
completed_plans: 24
|
||||
percent: 80
|
||||
completed_plans: 25
|
||||
percent: 78
|
||||
---
|
||||
|
||||
# Project State
|
||||
@@ -34,7 +34,7 @@ progress:
|
||||
|
||||
**Phase:** 05-cloud-storage-backends — Not started
|
||||
**Plan:** 0/TBD
|
||||
**Progress:** ████████░░ 80% (4/5 phases complete)
|
||||
**Progress:** [████████░░] 78%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
@@ -163,6 +163,7 @@ _Updated at each phase transition._
|
||||
| Last session | 2026-05-28 — Phase 4 UAT complete (14/15 passed, 1 bug found + fixed: duplicate folder on creation); sidebar collapsible folder tree added; Phase 4 marked complete |
|
||||
| Last session | 2026-05-28 — Phase 5 UI-SPEC approved (6/6 dimensions passed; 2 revision rounds: Cancel label → context-specific, text-lg → text-xl) |
|
||||
| Last session | 2026-05-28 — Phase 5 planned (8 plans, 7 waves); verification passed (4 blockers → resolved: D-05 API-layer refresh path, SEC-09 cloud cleanup, frontend_url config, RESEARCH resolved markers) |
|
||||
| Next action | Execute Phase 5: Cloud Storage Backends — run /gsd:execute-phase 5 |
|
||||
| Last session | 2026-05-28 — Plan 05-01 executed: Wave 0 Nyquist scaffold — 19 xfail stubs in test_cloud.py, 4 cloud fixtures in conftest.py, 6 package pins, 8 config settings; 172 passed / 43 xfailed |
|
||||
| Next action | Execute Plan 05-02: HKDF cloud credential encryption (cloud_utils.py) |
|
||||
| Pending decisions | None |
|
||||
| Resume file | `.planning/phases/05-cloud-storage-backends/05-01-PLAN.md` |
|
||||
| Resume file | `.planning/phases/05-cloud-storage-backends/05-02-PLAN.md` |
|
||||
|
||||
@@ -0,0 +1,162 @@
|
||||
---
|
||||
phase: 05-cloud-storage-backends
|
||||
plan: 01
|
||||
subsystem: testing
|
||||
tags: [pytest, cloud-storage, google-drive, onedrive, webdav, cryptography, msal, xfail, nyquist]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 04-folders-sharing-quotas
|
||||
provides: conftest.py fixture patterns (auth_user, admin_user, db_session, async_client)
|
||||
provides:
|
||||
- 19 xfail test stubs in backend/tests/test_cloud.py (CLOUD-01..07, SSRF D-17, IDOR SEC-08)
|
||||
- 4 cloud fixtures in backend/tests/conftest.py (mock_google_drive_creds, mock_onedrive_creds, mock_webdav_client, cloud_connection_factory)
|
||||
- 6 new PyPI package pins in backend/requirements.txt
|
||||
- 8 new Settings fields in backend/config.py for cloud OAuth and credential encryption
|
||||
affects: [05-02, 05-03, 05-04, 05-05, 05-06, 05-07, 05-08]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added:
|
||||
- cryptography>=41.0.0
|
||||
- google-auth-oauthlib>=1.3.1
|
||||
- google-api-python-client>=2.196.0
|
||||
- msal>=1.36.0
|
||||
- webdavclient3>=3.14.7
|
||||
- cachetools>=5.3.0
|
||||
patterns:
|
||||
- xfail(strict=False) Wave 0 Nyquist scaffolding — stubs xfail, never fail, until implementation turns them green
|
||||
- pytest_asyncio.fixture factory pattern for cloud_connection_factory (inner async function)
|
||||
- MagicMock with explicit method wiring (mock_webdav_client)
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- backend/tests/test_cloud.py
|
||||
- .planning/phases/05-cloud-storage-backends/deferred-items.md
|
||||
modified:
|
||||
- backend/requirements.txt
|
||||
- backend/config.py
|
||||
- backend/tests/conftest.py
|
||||
- .env.example
|
||||
|
||||
key-decisions:
|
||||
- "frontend_url reused from Phase 2 — field already declared in Settings; no duplicate added"
|
||||
- "test_ssrf_validation parametrized with 5 cases (4 blocked + 1 valid) to match D-17 threat register"
|
||||
- "cloud_connection_factory accepts session as first arg (not fixture-injected) for flexibility across test patterns"
|
||||
|
||||
patterns-established:
|
||||
- "Wave 0 stub body: only pytest.xfail('not implemented yet') — no assertions; strict=False prevents xpass CI breakage"
|
||||
- "Cloud fixture naming convention: mock_{provider}_creds for credential dicts, cloud_connection_factory for ORM rows"
|
||||
|
||||
requirements-completed:
|
||||
- CLOUD-01
|
||||
- CLOUD-02
|
||||
- CLOUD-03
|
||||
- CLOUD-04
|
||||
- CLOUD-05
|
||||
- CLOUD-06
|
||||
- CLOUD-07
|
||||
|
||||
# Metrics
|
||||
duration: 5min
|
||||
completed: 2026-05-28
|
||||
---
|
||||
|
||||
# Phase 5 Plan 01: Wave 0 Nyquist Scaffold Summary
|
||||
|
||||
**19 xfail test stubs for CLOUD-01..07 + SSRF + IDOR, 4 cloud conftest fixtures, 6 new PyPI package pins (cryptography/google-auth-oauthlib/msal/webdavclient3), and 8 new cloud Settings fields**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 5 min
|
||||
- **Started:** 2026-05-28T18:47:26Z
|
||||
- **Completed:** 2026-05-28T18:52:27Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 5
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Added 6 Phase 5 package dependencies (cryptography, google-auth-oauthlib, google-api-python-client, msal, webdavclient3, cachetools) with exact version pins to requirements.txt
|
||||
- Added 8 new Settings fields to config.py (cloud_creds_key, google OAuth, OneDrive OAuth, backend_url, frontend_url already present)
|
||||
- Created test_cloud.py with 19 xfail stubs covering all Phase 5 requirements and security invariants
|
||||
- Added 4 cloud-specific conftest fixtures (mock_google_drive_creds, mock_onedrive_creds, mock_webdav_client, cloud_connection_factory) without modifying any existing fixture
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: Add Phase 5 packages to requirements.txt and settings to config.py** - `a052ed4` (feat)
|
||||
2. **Task 2: Create test_cloud.py with all 15 xfail stubs** - `231dfcd` (test)
|
||||
3. **Task 3: Add cloud fixtures to conftest.py** - `b53ea86` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/backend/requirements.txt` - Added 6 cloud package pins
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/backend/config.py` - Added Cloud Storage (Phase 5) settings block with 7 new fields (frontend_url reused)
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/test_cloud.py` - Created with 15 named test stubs (19 collected including parametrize variants)
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/backend/tests/conftest.py` - Appended 4 cloud fixtures
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/.env.example` - Appended Cloud Storage Backends section
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- `frontend_url` was already declared in Settings (Phase 2, password reset links) — no duplicate field added; the plan noted "shared field"
|
||||
- `test_ssrf_validation` was parametrized with 5 cases (4 RFC-1918/loopback blocked + 1 valid URL that should pass) matching D-17 threat register, resulting in 19 total collected tests vs 15 named stubs
|
||||
- `cloud_connection_factory` returns an inner async function that takes `session` as first argument, giving callers full control over which session to use (not locked to db_session fixture)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
**Pre-existing (out of scope):** `tests/test_extractor.py::test_extract_docx` fails with `ModuleNotFoundError: No module named 'docx'` — python-docx is not installed in the local Python 3.9.6 environment. This failure was present before Plan 05-01 started and is unrelated to Phase 5 changes. Documented in `deferred-items.md`. Resolution: install python-docx locally or run tests inside the Docker container where all requirements.txt packages are installed.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
Phase 5 introduces new environment variables for cloud OAuth. Add to `.env` before testing cloud provider connections:
|
||||
|
||||
```
|
||||
CLOUD_CREDS_KEY=<32+ byte random key — generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))">
|
||||
GOOGLE_CLIENT_ID=<from Google Cloud Console>
|
||||
GOOGLE_CLIENT_SECRET=<from Google Cloud Console>
|
||||
ONEDRIVE_CLIENT_ID=<from Azure Portal>
|
||||
ONEDRIVE_CLIENT_SECRET=<from Azure Portal>
|
||||
ONEDRIVE_TENANT_ID=common
|
||||
BACKEND_URL=http://localhost:8000
|
||||
FRONTEND_URL=http://localhost:5173
|
||||
```
|
||||
|
||||
See `.env.example` for full documentation. All new settings have safe defaults so the app boots without cloud credentials configured.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Wave 0 Nyquist scaffold complete: all 19 stubs xfail cleanly, full suite at 172 passed / 43 xfailed
|
||||
- Plan 05-02 can immediately begin implementing `cloud_utils.py` (HKDF encryption) — `test_credential_round_trip` and `test_credentials_enc_not_exposed` are ready to turn green
|
||||
- `cloud_connection_factory` fixture ready for use in Plans 05-03 through 05-06 integration tests
|
||||
|
||||
## Known Stubs
|
||||
|
||||
All 15 named stubs (19 with parametrize) in `backend/tests/test_cloud.py` are intentional scaffolding. Each will be promoted to a real test by the plan that implements the corresponding behavior:
|
||||
|
||||
| Stub | Plan to resolve |
|
||||
|------|----------------|
|
||||
| test_credential_round_trip, test_credentials_enc_not_exposed | 05-02 |
|
||||
| test_connect_google_drive, test_oauth_callback_valid_state/invalid_state, test_webdav_connect_validates, test_ssrf_validation, test_ssrf_link_local | 05-03 |
|
||||
| test_invalid_grant_sets_requires_reauth, test_disconnect_deletes_credentials | 05-04 |
|
||||
| test_cloud_upload_no_presigned, test_factory_returns_correct_backend | 05-05 |
|
||||
| test_connection_status_display, test_admin_cannot_see_credentials, test_cross_user_idor | 05-06 |
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
Files verified present:
|
||||
- backend/tests/test_cloud.py: FOUND
|
||||
- backend/tests/conftest.py: FOUND (contains cloud_connection_factory)
|
||||
- backend/requirements.txt: FOUND (contains cryptography)
|
||||
- backend/config.py: FOUND (contains cloud_creds_key)
|
||||
|
||||
Commits verified:
|
||||
- a052ed4: feat(05-01): add Phase 5 cloud storage packages and config settings — FOUND
|
||||
- 231dfcd: test(05-01): create test_cloud.py with all 15 Phase 5 xfail stubs — FOUND
|
||||
- b53ea86: feat(05-01): add Phase 5 cloud fixtures to conftest.py — FOUND
|
||||
|
||||
---
|
||||
*Phase: 05-cloud-storage-backends*
|
||||
*Completed: 2026-05-28*
|
||||
Reference in New Issue
Block a user