---
phase: 15-multi-signer-backend
plan: "01"
subsystem: signing
tags: [multi-signer, jwt, email, download-route]
dependency_graph:
  requires: [14-multi-signer-schema]
  provides: [signer-download-token, signer-completion-email, public-download-route]
  affects: [15-02-send-route, 15-03-sign-handler]
tech_stack:
  added: []
  patterns: [jose-jwt, nodemailer-plain-text, nextjs-app-router-route-handler]
key_files:
  created:
    - teressa-copeland-homes/src/app/api/sign/download/[token]/route.ts
  modified:
    - teressa-copeland-homes/src/lib/signing/token.ts
    - teressa-copeland-homes/src/lib/signing/signing-mailer.tsx
decisions:
  - "signerEmail stored in DB only (not JWT) — keeps JWT payload minimal, consistent with D-03"
  - "signer-download token is 72h with no DB record — same pattern as agent-download, longer TTL for signer latency"
  - "public download route guards on doc.status === Signed AND signedFilePath — prevents serving partial accumulation files"
metrics:
  duration: "2 min"
  completed: "2026-04-03"
  tasks_completed: 3
  files_modified: 3
---

# Phase 15 Plan 01: Multi-Signer Utility Building Blocks Summary

**One-liner:** Extended createSigningToken with optional signerEmail, added signer-download JWT pair (72h), sendSignerCompletionEmail mailer, and public GET /api/sign/download/[token] route.

## Tasks Completed

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | Extend token.ts with signerEmail param and signer-download token pair | 70c48cc | src/lib/signing/token.ts |
| 2 | Add sendSignerCompletionEmail to signing-mailer.tsx | e1cdfe9 | src/lib/signing/signing-mailer.tsx |
| 3 | Create public signer download route GET /api/sign/download/[token] | 14efa1d | src/app/api/sign/download/[token]/route.ts |

## What Was Built

### token.ts changes
- `createSigningToken` now accepts optional `signerEmail?: string` — persists to `signingTokens.signerEmail` column (written as `null` if absent, preserving all existing call sites)
- `createSignerDownloadToken(documentId)` — 72h JWT with `purpose: 'signer-download'` claim, no DB record
- `verifySignerDownloadToken(token)` — validates purpose claim, returns `{ documentId }`

### signing-mailer.tsx changes
- `sendSignerCompletionEmail({ to, documentName, downloadUrl })` — plain-text email "All parties have signed...", subject "Signed copy ready: {name}", 72h expiry noted in body

### New route: GET /api/sign/download/[token]
- Public (no auth session)
- App Router async params pattern: `{ params }: { params: Promise<{ token: string }> }`
- Guards: invalid/expired token → 401, doc not Signed or no signedFilePath → 404, path traversal → 403
- Serves PDF with `Content-Type: application/pdf` and `Content-Disposition: attachment`

## Verification

- `npx tsc --noEmit` passes with zero errors
- Token utility now has 4 token types: sign, download, agent-download, signer-download
- Mailer now has 3 email functions: sendSigningRequestEmail, sendAgentNotificationEmail, sendSignerCompletionEmail
- Download route file exists at correct App Router path and imports from token.ts

## Deviations from Plan

None — plan executed exactly as written.

## Known Stubs

None — all functionality is fully implemented. Plans 02 and 03 will wire these utilities into the send route and sign handler.

## Self-Check: PASSED

- [x] teressa-copeland-homes/src/lib/signing/token.ts — modified, committed 70c48cc
- [x] teressa-copeland-homes/src/lib/signing/signing-mailer.tsx — modified, committed e1cdfe9
- [x] teressa-copeland-homes/src/app/api/sign/download/[token]/route.ts — created, committed 14efa1d
- [x] All three commits confirmed in git log