feat(giver): personal letter authoring step

[xBalbinus]

Summary

Adds a /onboarding/letter step where the giver writes the personal note their recipient sees first on /r/:token/letter. Inserts between delivery and send in the onboarding flow.

Changes

• Migration 005: ALTER TYPE onboarding_step ADD VALUE 'letter' BEFORE 'send'. (gifts.personal_message already exists from migration 004.)
• server/src/db/schema.ts + gift-store.ts + gifts.ts: extend OnboardingStep and the stepSchema with letter.
• web/app/onboarding/letter/page.tsx: new page modeled on /onboarding/recipient: textarea (4000 char cap) + Whisper voice button. Optional — Skip routes to send and falls back to the generic letter on the parent side. Placeholder pre-fills with the canonical "I made you something. Open whenever you have a quiet minute."
• delivery/page.tsx: routes to /onboarding/letter instead of /onboarding/send.
• _lib/sync.ts: patchGiftFields now propagates personalMessage so the snapshot sync persists it to the backend column.
• _lib/state.ts: ONBOARDING_STEPS gains letter before send.

Drive-by

• server/src/lib/email.test.ts had pre-existing typeof fetch cast errors that surfaced on the current type-check — fixed via as unknown as typeof fetch and a more inferable capture-state shape. 71/71 server tests still pass.

Test plan

• Migration applied cleanly to local + e2e DBs.
• bun run --filter '*' type-check clean.
• bun run --filter '*' lint clean (7 pre-existing web warnings).
• bun --cwd server test with INTEGRATION=1 → 71/71 pass.
• Browser smoke: delivery → letter → send routes correctly, personalMessage lands in local state, headline + placeholder personalize to the chosen intent.
• (post-merge) full E2E from /onboarding through send + check parent-side /r/:token/letter renders the giver's letter once the recipient frontend is wired to the API envelope.

[slopless-scanner]

⚠️ Slopless Review

Confidence: 🟡 4/5 · Verdict: REQUEST_CHANGES · Risk: HIGH · Findings: 8

Reviewed the PR diff without prior scan context (no architecture artifacts found). Produced 8 finding(s) across 3 vulnerability class(es) (best_practice, code_quality, security) in 24.0s.

PR review complete: 8 findings, verdict: request_changes

Scope & coverage

• Lines: 298
• Checks performed: best_practice · code_quality · security

Findings

🛑 CRITICAL — Missing Authorization Check on Personal Message Endpoint

web/app/onboarding/_lib/sync.ts:100-101 · confidence: high · CWE-639

The PR adds logic to patch personalMessage via patchGiftFields() in sync.ts (line 100-101), but there is no evidence of authorization verification that the current user owns the gift being modified. This is a classic BOLA (Broken Object Level Authorization) vulnerability. An attacker could modify another user's personal message by knowing their gift ID.

Suggested fix: Verify that the backend endpoint /api/gifts/{id} PATCH handler checks that current_user.id === gift.giver_id before allowing the personalMessage field to be updated. The check must happen server-side, not client-side.

Code context

if (typeof data.personalMessage === "string")
		patch.personalMessage = data.personalMessage

🔴 HIGH — Unvalidated Audio Transcription Endpoint

web/app/onboarding/letter/page.tsx:88-92 · confidence: high · CWE-434

The /api/transcribe endpoint (called at line 88 in letter/page.tsx) accepts audio file uploads with no visible input validation, file size limits, or rate limiting shown in the PR. This could enable: (1) DoS attacks via large file uploads, (2) abuse of third-party transcription API quota, (3) processing of malicious audio files.

Suggested fix: Implement server-side validation on the /api/transcribe endpoint: (1) Enforce maximum file size (e.g., 25MB), (2) Validate MIME type is audio, (3) Implement rate limiting per user/IP, (4) Add authentication check to ensure only logged-in users can transcribe, (5) Consider adding virus scanning for uploaded files.

Code context

const fd = new FormData()
fd.append("audio", blob, `audio.${ext}`)
const res = await fetch(`/api/transcribe`, { method: "POST", body: fd })
const data = (await res.json()) as { text?: string; error?: string }

🔴 HIGH — Missing Authentication on Transcription Endpoint

web/app/onboarding/letter/page.tsx:88-92 · confidence: high · CWE-306

The transcription endpoint at /api/transcribe is called without any visible authentication token or session validation. This endpoint should require the user to be authenticated to prevent unauthorized use and quota abuse.

Suggested fix: Ensure the backend /api/transcribe endpoint: (1) Requires authentication (check session/JWT), (2) Validates the user is in an active onboarding flow, (3) Associates transcription quota with the authenticated user.

Code context

const res = await fetch(`/api/transcribe`, { method: "POST", body: fd })

🟠 MEDIUM — Unhandled Promise Rejection in Voice Recording

web/app/onboarding/letter/page.tsx:88-92 · confidence: medium

In the transcribe() function (line 82-102), if res.json() throws an error, it will cause an unhandled promise rejection. The error handling only checks res.ok after parsing, but parsing itself could fail.

Suggested fix: Wrap the JSON parsing in a try-catch block or check response headers before parsing: const data = res.ok ? await res.json() : { error: 'Server error' }

Code context

const res = await fetch(`/api/transcribe`, { method: "POST", body: fd })
const data = (await res.json()) as { text?: string; error?: string }
if (!res.ok) {

🟠 MEDIUM — Incomplete PR Description - Missing Backend Implementation

web/app/onboarding/delivery/page.tsx:1 · confidence: high

The PR description mentions changes to delivery/page.tsx but the diff is truncated. More critically, the PR does not show the backend implementation of the /api/transcribe endpoint or the PATCH endpoint for updating personalMessage. These are critical for security review.

Suggested fix: Provide complete diffs for all modified files, especially backend API endpoints. Ensure the PR includes the implementation of /api/transcribe and the gift PATCH endpoint with full authorization checks.

Code context

N/A - File diff truncated

🟠 MEDIUM — No CSRF Protection Visible on Form Submission

web/app/onboarding/letter/page.tsx:130-135 · confidence: medium · CWE-352

The letter form submission (line 130-135 in the truncated code) does not show CSRF token handling. While Next.js may handle this automatically, it should be explicitly verified.

Suggested fix: Verify that the backend PATCH endpoint for updating personalMessage validates CSRF tokens or uses SameSite cookie attributes. Ensure the API client includes CSRF tokens in requests.

Code context

N/A - Code truncated

🟡 LOW — Hardcoded Default Message Could Be Externalized

web/app/onboarding/letter/page.tsx:1-246 · confidence: low

The placeholder message 'I made you something. Open whenever you have a quiet minute.' is hardcoded in the component. This should be configurable or externalized for i18n support.

Suggested fix: Move the default message to a constants file or i18n configuration for easier maintenance and localization.

Code context

Placeholder pre-fills with the canonical _"I made you something. Open whenever you have a quiet minute."_

🟠 MEDIUM — Potential XSS via Transcribed Text

web/app/onboarding/letter/page.tsx:95-102 · confidence: medium · CWE-79

The transcribed text from the audio is inserted into the letter state and eventually saved to the database. If the transcription service returns unsanitized content or if there's a backend vulnerability, this could lead to XSS when the letter is displayed to the recipient.

Suggested fix: Ensure that: (1) The transcription API response is validated and sanitized, (2) The backend sanitizes personalMessage before storing, (3) The recipient-facing letter display uses proper HTML escaping or React's built-in XSS protection.

Code context

const text = (data.text || "")
// ... text is appended to letter state

---

Reviewed by Slopless · Install on your repo · comment @slopless to re-run

[xBalbinus]

@valet-test-env please review

[valet-test-env]

Solid PR — the intent matches the diff, conventions are consistent throughout, and all CI checks pass.

One real issue worth fixing before merge:

• web/app/onboarding/letter/page.tsx (mic leak on navigate-away): If the user starts recording and then hits Back/Skip/Continue without stopping, recorderRef.current is left running and the mic stream tracks are never stopped. Add a useEffect cleanup that calls stopRecording() on unmount.

---

Created on behalf of xiangan@turnkey.io xiangan@turnkey.io