---
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*