14 KiB
14 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 15-multi-signer-backend | 01 | execute | 1 |
|
true |
|
|
Purpose: Plans 02 and 03 depend on these utilities being in place before the send route and sign handlers can be rewritten. Output: Extended token.ts, extended signing-mailer.tsx, new download route file.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/15-multi-signer-backend/15-CONTEXT.md @.planning/phases/15-multi-signer-backend/15-RESEARCH.md@teressa-copeland-homes/src/lib/signing/token.ts @teressa-copeland-homes/src/lib/signing/signing-mailer.tsx @teressa-copeland-homes/src/lib/db/schema.ts
From src/lib/signing/token.ts:
// Existing — extend, do not break
export async function createSigningToken(documentId: string): Promise<{ token: string; jti: string; expiresAt: Date }>;
export async function verifySigningToken(token: string): Promise<{ documentId: string; jti: string; exp: number }>;
export async function createAgentDownloadToken(documentId: string): Promise<string>;
export async function verifyAgentDownloadToken(token: string): Promise<{ documentId: string }>;
From src/lib/signing/signing-mailer.tsx:
export async function sendSigningRequestEmail(opts: { to: string; clientName?: string; documentName: string; signingUrl: string; expiresAt: Date }): Promise<void>;
export async function sendAgentNotificationEmail(opts: { clientName: string; documentName: string; signedAt: Date }): Promise<void>;
From src/lib/db/schema.ts:
export interface SignatureFieldData { id: string; page: number; x: number; y: number; width: number; height: number; type?: SignatureFieldType; signerEmail?: string; }
export interface DocumentSigner { email: string; color: string; }
// signingTokens table has: jti, documentId, signerEmail (nullable TEXT), createdAt, expiresAt, usedAt
Add two new functions after the existing `verifyAgentDownloadToken`:
```typescript
export async function createSignerDownloadToken(documentId: string): Promise<string> {
return await new SignJWT({ documentId, purpose: 'signer-download' })
.setProtectedHeader({ alg: 'HS256' })
.setIssuedAt()
.setExpirationTime('72h')
.sign(getSecret());
}
export async function verifySignerDownloadToken(token: string): Promise<{ documentId: string }> {
const { payload } = await jwtVerify(token, getSecret());
if (payload['purpose'] !== 'signer-download') throw new Error('Not a signer download token');
return { documentId: payload['documentId'] as string };
}
```
The signer-download token has 72h TTL (longer than agent-download 5m) because signers may not open the completion email immediately. No DB record — same as agent-download tokens. Purpose claim `'signer-download'` distinguishes from all other token types.
```typescript
export async function sendSignerCompletionEmail(opts: {
to: string;
documentName: string;
downloadUrl: string;
}): Promise<void> {
const transporter = createTransporter();
await transporter.sendMail({
from: '"Teressa Copeland Homes" <teressa@tcopelandhomes.com>',
to: opts.to,
subject: `Signed copy ready: ${opts.documentName}`,
text: [
`All parties have signed "${opts.documentName}".`,
'',
'Download your signed copy using the link below (expires in 72 hours):',
opts.downloadUrl,
].join('\n'),
});
}
```
The function accepts `to`, `documentName`, and `downloadUrl`. No `expiresAt` param — the 72h expiry is baked into the text. This keeps the interface simple; the caller constructs the URL from `createSignerDownloadToken`.
1. Extracts `token` from dynamic path params (App Router async params pattern: `{ params }: { params: Promise<{ token: string }> }`)
2. Calls `verifySignerDownloadToken(token)` — returns `{ documentId }` or throws
3. On verification failure: returns `new Response('Invalid or expired download link', { status: 401 })`
4. Queries `db.query.documents.findFirst` for `signedFilePath`, `status`, `name` where `id = documentId`
5. Guards: `!doc || doc.status !== 'Signed' || !doc.signedFilePath` returns 404 "Document not yet complete" (Pitfall 6 — signedFilePath alone is not a completion signal)
6. Builds absolute path: `path.join(UPLOADS_DIR, doc.signedFilePath)`
7. Path traversal guard: `!absPath.startsWith(UPLOADS_DIR)` returns 403
8. Reads file with `readFile(absPath)`
9. Returns `new Response(fileBytes, { headers: { 'Content-Type': 'application/pdf', 'Content-Disposition': 'attachment; filename="DOC_NAME-signed.pdf"' } })`
Full implementation:
```typescript
import { NextRequest } from 'next/server';
import { verifySignerDownloadToken } from '@/lib/signing/token';
import { db } from '@/lib/db';
import { documents } from '@/lib/db/schema';
import { eq } from 'drizzle-orm';
import path from 'node:path';
import { readFile } from 'node:fs/promises';
const UPLOADS_DIR = path.join(process.cwd(), 'uploads');
export async function GET(
_req: NextRequest,
{ params }: { params: Promise<{ token: string }> }
) {
const { token } = await params;
let documentId: string;
try {
({ documentId } = await verifySignerDownloadToken(token));
} catch {
return new Response('Invalid or expired download link', { status: 401 });
}
const doc = await db.query.documents.findFirst({
where: eq(documents.id, documentId),
columns: { signedFilePath: true, status: true, name: true },
});
if (!doc || doc.status !== 'Signed' || !doc.signedFilePath) {
return new Response('Document not yet complete', { status: 404 });
}
const absPath = path.join(UPLOADS_DIR, doc.signedFilePath);
if (!absPath.startsWith(UPLOADS_DIR)) {
return new Response('Forbidden', { status: 403 });
}
const fileBytes = await readFile(absPath);
return new Response(fileBytes, {
headers: {
'Content-Type': 'application/pdf',
'Content-Disposition': `attachment; filename="${doc.name}-signed.pdf"`,
},
});
}
```
<success_criteria>
createSigningToken(docId, 'alice@example.com')compiles and persists signerEmail to DBcreateSigningToken(docId)still compiles (backward compatible — no signerEmail written)createSignerDownloadToken(docId)returns a JWT string;verifySignerDownloadToken(jwt)returns{ documentId }sendSignerCompletionEmail({ to, documentName, downloadUrl })compiles and follows established mailer patternGET /api/sign/download/[token]route file exists, compiles, and guards against all failure modesnpx tsc --noEmitpasses with zero errors across the entire project </success_criteria>