docs(07-01): complete agent download token and route plan

- 07-01-SUMMARY.md: execution summary with decisions and file references - STATE.md: position updated to Phase 7 Plan 1 complete; two decisions logged - ROADMAP.md: Phase 7 progress updated (1/3 plans complete) - REQUIREMENTS.md: SIGN-07 and LEGAL-03 marked complete
2026-03-21 10:36:19 -06:00
parent ebc47ae954
commit 36069cb1ef
4 changed files with 129 additions and 18 deletions
--- a/.planning/phases/07-audit-trail-and-download/07-01-SUMMARY.md
+++ b/.planning/phases/07-audit-trail-and-download/07-01-SUMMARY.md
@@ -0,0 +1,108 @@
+---
+phase: 07-audit-trail-and-download
+plan: "01"
+subsystem: api
+tags: [jwt, jose, pdf, download, security, next.js]
+
+# Dependency graph
+requires:
+  - phase: 06-signing-flow
+    provides: token.ts with createDownloadToken/verifyDownloadToken pattern and SIGNING_JWT_SECRET
+  - phase: 04-pdf-ingest
+    provides: uploads/ directory and path traversal guard pattern
+provides:
+  - createAgentDownloadToken (purpose:'agent-download', 5-min TTL) in src/lib/signing/token.ts
+  - verifyAgentDownloadToken in src/lib/signing/token.ts
+  - GET /api/documents/[id]/download?adt=[token] — agent-authenticated signed PDF streaming
+affects:
+  - 07-02 (audit trail plan will likely link download events to this route)
+  - document detail page (will need createAgentDownloadToken server-side to generate adt links)
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Agent download token — purpose:'agent-download', 5-min TTL, no DB record (mirrors client download pattern)
+    - Route-level document ID cross-check — token documentId must match route [id] param (403 on mismatch)
+    - Path traversal guard: absPath.startsWith(UPLOADS_DIR) before every readFile from uploads/
+    - new Uint8Array(fileBuffer) for Response BodyInit compatibility in Next.js 16 TypeScript strict mode
+
+key-files:
+  created:
+    - teressa-copeland-homes/src/app/api/documents/[id]/download/route.ts
+  modified:
+    - teressa-copeland-homes/src/lib/signing/token.ts
+
+key-decisions:
+  - "Agent download token uses same SIGNING_JWT_SECRET as other tokens, purpose:'agent-download' claim distinguishes it"
+  - "5-min TTL for agent-download (shorter than 15-min client download) — agent generates token on demand per LEGAL-03"
+  - "No Auth.js session check in download route — short-lived JWT is the credential (same as client download pattern)"
+  - "Token documentId vs route [id] cross-check added as defense-in-depth against token reuse across documents"
+
+patterns-established:
+  - "Agent download token pattern: createAgentDownloadToken server-side → adt query param → GET /api/documents/[id]/download"
+  - "Path traversal guard: always check absPath.startsWith(UPLOADS_DIR) before readFile, no exceptions"
+
+requirements-completed:
+  - SIGN-07
+  - LEGAL-03
+
+# Metrics
+duration: 2min
+completed: 2026-03-21
+---
+
+# Phase 7 Plan 01: Agent Download Token and Authenticated PDF Download Route Summary
+
+**agent-download JWT (5-min TTL, purpose:'agent-download') added to token.ts plus new GET /api/documents/[id]/download route that streams signed PDFs behind presigned tokens with path traversal guard and document ID cross-check**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-03-21T15:53:23Z
+- **Completed:** 2026-03-21T15:55:10Z
+- **Tasks:** 2
+- **Files modified:** 2
+
+## Accomplishments
+- Added `createAgentDownloadToken` and `verifyAgentDownloadToken` to `src/lib/signing/token.ts` — all 6 exports intact, no existing exports modified
+- Created `GET /api/documents/[id]/download` route with complete security surface: 401 for missing/expired token, 403 for ID mismatch, 403 for path traversal, 404 for unsigned/missing files
+- `tsc --noEmit` and `npm run build` both pass with zero errors after both changes
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add agent download token functions to token.ts** - `cd4cb75` (feat)
+2. **Task 2: Create GET /api/documents/[id]/download route** - `ebc47ae` (feat)
+
+## Files Created/Modified
+- `teressa-copeland-homes/src/lib/signing/token.ts` - Appended `createAgentDownloadToken` (5-min TTL, purpose:'agent-download') and `verifyAgentDownloadToken` (throws if purpose mismatch)
+- `teressa-copeland-homes/src/app/api/documents/[id]/download/route.ts` - New agent-authenticated download endpoint streaming signed PDFs via adt query param JWT
+
+## Decisions Made
+- Agent download token reuses `SIGNING_JWT_SECRET` with a distinct `purpose:'agent-download'` claim — consistent with existing token pattern, no new secret needed
+- 5-min TTL (shorter than 15-min client download token) satisfies LEGAL-03 requirement for presigned URLs
+- No Auth.js session check in the download route — the short-lived JWT is the sole credential (established Phase 6 client download pattern)
+- `documentId !== id` cross-check as defense-in-depth: a valid token for document A cannot download document B
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- `createAgentDownloadToken` is ready for use in the document detail server component (generate adt URL server-side, render download link)
+- Download route is live at `/api/documents/[id]/download?adt=[token]` — ready to be linked from agent portal document pages
+- Phase 7 plan 02 (audit trail) can log download events against this endpoint
+
+---
+*Phase: 07-audit-trail-and-download*
+*Completed: 2026-03-21*