@tyroneross/build-loop 0.30.3

package/skills/authentication/references/google-places.md

@@ -0,0 +1,173 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Places API (New) v1 — 2026
+
+The legacy Places API can no longer be enabled on new projects. Use **Places API (New)** with the v1 REST endpoints and **field masks** on every call.
+
+## Core Endpoints
+
+| Endpoint | Method | Use |
+|----------|--------|-----|
+| `POST https://places.googleapis.com/v1/places:searchText` | POST | Text Search — "summer camps near me" |
+| `POST https://places.googleapis.com/v1/places:searchNearby` | POST | Nearby Search — points within radius |
+| `POST https://places.googleapis.com/v1/places:autocomplete` | POST | Autocomplete — as user types |
+| `GET  https://places.googleapis.com/v1/places/{PLACE_ID}` | GET | Place Details — after picking a result |
+
+## Field Masks (MANDATORY — affects pricing)
+
+Every Places API (New) request requires an `X-Goog-FieldMask` header. Google **charges per field category requested**. Don't request what you won't use.
+
+```
+X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location
+```
+
+Categories (as of April 2026):
+
+- **IDs Only** (cheapest): `places.id`, `places.name`
+- **Essentials**: `places.displayName`, `places.formattedAddress`, `places.location`, `places.shortFormattedAddress`
+- **Pro**: adds `photos`, `priceLevel`, `rating`, `userRatingCount`, `businessStatus`, `types`
+- **Enterprise**: adds `reviews`, `editorialSummary`, `openingHours`, `websiteUri`, etc.
+
+The finer the mask, the cheaper the call. Start with Essentials and add fields only when the UI needs them.
+
+## Text Search Example
+
+```ts
+// Server-side only — use the API key that's restricted to your server's IP,
+// NOT the browser-exposed Maps JS key.
+async function searchPlaces(query: string, bias?: { lat: number; lng: number; radius: number }) {
+  const res = await fetch('https://places.googleapis.com/v1/places:searchText', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Goog-Api-Key': process.env.GOOGLE_PLACES_API_KEY!,
+      'X-Goog-FieldMask': [
+        'places.id',
+        'places.displayName',
+        'places.formattedAddress',
+        'places.location',
+        'places.types',
+        'places.primaryType',
+        'places.primaryTypeDisplayName',
+      ].join(','),
+    },
+    body: JSON.stringify({
+      textQuery: query,
+      ...(bias && {
+        locationBias: {
+          circle: {
+            center: { latitude: bias.lat, longitude: bias.lng },
+            radius: bias.radius,
+          },
+        },
+      }),
+      maxResultCount: 10,
+    }),
+  })
+
+  if (!res.ok) throw new Error(`Places API ${res.status}: ${await res.text()}`)
+  return res.json() as Promise<{
+    places: Array<{
+      id: string
+      displayName: { text: string; languageCode: string }
+      formattedAddress: string
+      location: { latitude: number; longitude: number }
+      types?: string[]
+      primaryType?: string
+      primaryTypeDisplayName?: { text: string }
+    }>
+  }>
+}
+```
+
+**Key Places API (New) note**: Use `X-Goog-Api-Key` header, NOT `?key=` query param. The query-param style is legacy.
+
+## Autocomplete + Session Tokens
+
+Session tokens bundle a series of Autocomplete requests with a single final Place Details request into one session → Google bills it as one request instead of N+1. Use a fresh UUID per autocomplete "session" (one user typing → one selection).
+
+```ts
+import { randomUUID } from 'crypto'
+
+// Start a session when the user focuses the input
+const sessionToken = randomUUID()
+
+// Each keystroke
+async function autocomplete(input: string) {
+  return fetch('https://places.googleapis.com/v1/places:autocomplete', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Goog-Api-Key': process.env.GOOGLE_PLACES_API_KEY!,
+    },
+    body: JSON.stringify({
+      input,
+      sessionToken,  // same for every keystroke in this session
+      locationBias: { /* optional */ },
+    }),
+  }).then(r => r.json())
+}
+
+// User picks a result → fetch details with the same token
+async function getDetails(placeId: string) {
+  return fetch(`https://places.googleapis.com/v1/places/${placeId}?sessionToken=${sessionToken}`, {
+    headers: {
+      'X-Goog-Api-Key': process.env.GOOGLE_PLACES_API_KEY!,
+      'X-Goog-FieldMask': 'id,displayName,formattedAddress,location,websiteUri,internationalPhoneNumber',
+    },
+  }).then(r => r.json())
+}
+```
+
+After the Place Details call, the session is consumed. Start a fresh token for the next query.
+
+## The "Camp at a Parent Location" Problem
+
+The Trip Planner / Summer Camps use case has a wrinkle: a camp is an _activity_ that runs at a _venue_ that has its own Google Place. E.g. "Kids Coding Camp" at "YMCA Brooklyn". You want to store both.
+
+**Data model approach:**
+
+```
+camps
+  id
+  name              -- "Kids Coding Camp"
+  provider          -- "Code Ninjas" (who runs the camp)
+  provider_place_id -- Google Place ID for Code Ninjas HQ (optional)
+  venue_place_id    -- Google Place ID for YMCA Brooklyn (where it actually meets)
+  venue_name        -- cached displayName
+  venue_address     -- cached formattedAddress
+  venue_lat, venue_lng
+  start_date, end_date
+  daily_start, daily_end  -- e.g. 09:00 - 15:00
+  ages_min, ages_max
+  cost
+  url
+  notes
+```
+
+The key insight: **`venue_place_id` and `provider_place_id` are different Google Places**, and you should store and display both. Users care about where to drop off (venue) AND who to contact (provider).
+
+When searching Places for a camp venue, query for the venue name directly — don't try to match the camp name to a Google Place, it won't exist as one.
+
+## Caching + Terms of Service
+
+Google's Places API ToS allow you to cache Place IDs **indefinitely** (they're considered stable identifiers), but most other Place data is capped at **30 days** before you must refetch. In practice:
+
+- Store `place_id`, `displayName`, `formattedAddress`, `location` in your DB
+- Refresh from Google if the cached row is > 30 days old
+- Never display cached data older than 30 days without refetching
+
+## Common Failures
+
+- **HTTP 400 "Field mask is required"** — add `X-Goog-FieldMask` header
+- **HTTP 400 "Invalid field mask"** — you can't request `places.name` alongside other `places.*` fields without the correct prefix. Check the [field-mask docs](https://developers.google.com/maps/documentation/places/web-service/text-search#fieldmask)
+- **HTTP 403 "API has not been used"** — enable Places API (New), not legacy
+- **HTTP 429** — rate limited. Default quota is generous but enforce client-side debounce on autocomplete (200-400ms)
+- **Empty results but no error** — check `languageCode` and `regionCode` in the request body
+
+## Sources
+
+- [Places API New overview](https://developers.google.com/maps/documentation/places/web-service/overview)
+- [Text Search (New)](https://developers.google.com/maps/documentation/places/web-service/text-search)
+- [Place Details (New)](https://developers.google.com/maps/documentation/places/web-service/place-details)
+- [Migrate to New from Legacy](https://developers.google.com/maps/documentation/places/web-service/legacy/migrate-text)

package/skills/authentication/references/lessons-example-web-app-better-auth.md

@@ -0,0 +1,126 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Example Web App — Better Auth lessons
+
+## When to use
+
+Read this when you're hitting a class of problem the Example Web App build hit during the migration from `@supabase/ssr` to Better Auth + Drizzle + Neon. Each section is a real incident or near-miss documented at the time. Diagnostic-style — symptom first, cause, what to look for, how it was fixed.
+
+For runnable Better Auth config, see `better-auth-setup.md`.
+For the Google-API-side lessons (Calendar, Places, Maps, Cloud Console), see the older `google-lessons-example-web-app.md`.
+
+## Incident: Production sign-in works, then the next request 401s
+
+**Symptom.** Sign-in completes successfully, browser redirects to the app, the dashboard renders briefly, then every subsequent API call returns 401. Hard refresh shows logged-out state.
+
+**Cause.** `BETTER_AUTH_URL` was set to `https://my-app.vercel.app` but the actual production deployment was reachable at a custom CNAME `https://app.example.com`. Better Auth's cookie was scoped to `my-app.vercel.app`; the browser was on `app.example.com`; cookies didn't apply.
+
+**What to look for.**
+- `set-cookie` response header on `/api/auth/callback/google` lists a `Domain=` that doesn't match the URL bar
+- Sign-in works on the `*.vercel.app` URL but not on the custom domain
+- `Network` tab shows session reads returning empty before any API call
+
+**Fix.** Boot-time validation that asserts `process.env.BETTER_AUTH_URL` matches `process.env.VERCEL_URL` (with `https://` prefix) OR a known custom domain. Crash the boot if it doesn't — silent mismatch was the killer here.
+
+Cross-reference: Universal footgun #7 (`NEXT_PUBLIC_APP_URL` / `BETTER_AUTH_URL` mismatch on Vercel CNAMEs) in `../SKILL.md`.
+
+## Incident: Calendar API call fails with `invalid_grant` after 7 days
+
+**Symptom.** Family Calendar feature works for a week after the user signs in. Then every Google Calendar API call returns `invalid_grant`. Re-signing in fixes it for another week.
+
+**Cause.** Google access tokens expire in ~60 minutes. Without a `refresh_token`, the access token can't be silently renewed. The `refresh_token` is only granted on first consent — second sign-in (without `prompt: 'consent'`) returns no `refresh_token`, and the row in `account.refresh_token` is null.
+
+**What to look for.**
+- `account.refresh_token` is null in your DB for users who can't make Google API calls
+- `account.expires_at` is in the past
+- Google Cloud Console "Credentials" page shows OAuth consent has been granted, but the app never asked for offline access
+
+**Fix.** Better Auth Google provider config:
+
+```ts
+google: {
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  accessType: 'offline',           // requests refresh_token
+  prompt: 'select_account consent', // forces consent screen every sign-in
+  scope: ['openid', 'email', 'profile', 'https://www.googleapis.com/auth/calendar.app.created'],
+}
+```
+
+Both `accessType` AND `prompt` are required. `accessType: 'offline'` alone won't issue a `refresh_token` if Google thinks the user has already consented to offline access in a previous session.
+
+Verify before shipping by signing in twice (sign out between) and confirming `account.refresh_token` is non-null both times.
+
+Cross-reference: Universal footgun #8 in `../SKILL.md`.
+
+## Incident: Family Calendar creation triggers a second consent prompt
+
+**Symptom.** User signs in to Example Web App (Google OAuth, basic scopes). Clicks "Create Family Calendar." Browser redirects back to Google for ANOTHER consent screen requesting Calendar scope. Half of users abandon at this second prompt.
+
+**Cause.** The initial sign-in only requested `openid email profile`. Calendar scope (`https://www.googleapis.com/auth/calendar.app.created`) was added in a later `auth.api.linkOAuth` call.
+
+**Fix.** Pre-approve every scope you'll EVER need at sign-in time:
+
+```ts
+scope: [
+  'openid',
+  'email',
+  'profile',
+  'https://www.googleapis.com/auth/calendar.app.created',
+]
+```
+
+Trade-off: more scopes = scarier consent screen at first sign-in. But far better than losing 50% of users at a second prompt mid-flow.
+
+If a scope is genuinely optional or rare, defer it — but acknowledge you'll lose some users at the second prompt. Document the choice.
+
+## Incident: User A could query User B's data
+
+**Symptom.** Found during a code review pre-launch. The `getCamps()` route handler did `db.select().from(camps).where(eq(camps.id, request.body.campId))` — no user check.
+
+**Cause.** Better Auth gives you a `session.user.id`, but it does NOT enforce per-row authorization. Every query has to manually scope to the session's user id. With dozens of route handlers, "manually" inevitably misses spots — exactly what happened here.
+
+**Fix.** A single `dbForUser(userId)` factory in `lib/db/index.ts` that returns CRUD methods pre-bound to that user. Route handlers MUST go through it. Code review can grep for any `from(schema.X)` outside `dbForUser` to find violations.
+
+```ts
+const userDb = dbForUser(session.user.id)
+const camp = await userDb.camps.get(campId) // returns [] if user doesn't own it
+```
+
+The grep audit caught 7 violations that had passed PR review.
+
+Cross-reference: Universal footgun #9 in `../SKILL.md`. Implementation pattern in `better-auth-setup.md`.
+
+## Incident: `sameSite: 'strict'` broke Google sign-in
+
+**Symptom.** Tried to harden cookies by setting `sameSite: 'strict'`. Google sign-in stopped working — the OAuth callback could not see the auth cookie.
+
+**Cause.** `sameSite: 'strict'` blocks cookies on cross-site redirect responses. The Google OAuth callback IS a cross-site redirect. Cookie isn't sent → Better Auth treats the callback as a fresh session → no link between callback and the sign-in attempt.
+
+**Fix.** `sameSite: 'lax'` is the correct value for cookies that need to survive OAuth redirects. Better Auth's default is correct; the override was the bug.
+
+```ts
+// betterAuth({ ... advancedCookies: { sameSite: 'lax' } })  // default — leave it
+```
+
+Cross-reference: Universal footgun #11 in `../SKILL.md`.
+
+## Migration narrative: `@supabase/ssr` → Better Auth
+
+The Example Web App migration took ~2 weeks part-time. Order of operations:
+
+1. **Stand up Better Auth in parallel**, on `/api/auth/[...all]`. Supabase auth still active on the old `/auth/callback`. App routes fall back to either depending on a feature flag.
+2. **Migrate user records** with a one-time script. Map Supabase `auth.users` → Better Auth `user`, add corresponding `account` rows for OAuth provider linkage. Test on a copy of prod first.
+3. **Switch the route handler** from Supabase callbacks to `app/api/auth/[...all]/route.ts`. Update sign-in / sign-out buttons to call `authClient.signIn` / `signOut`.
+4. **Delete Supabase-specific cookie code.** This was the biggest source of bugs — orphaned `getAll`/`setAll` adapters, leftover `createServerClient` imports.
+5. **Replace RLS-based auth with `dbForUser(userId)`.** Audit every route handler. The migration triggered the IDOR-pattern adoption.
+
+The biggest risks were in step 2 (schema mismatch) and step 4 (latent dead code). Spent the most time there.
+
+## What we'd do differently next time
+
+- **Boot-time URL validation from day one.** The Vercel CNAME mismatch ate a deploy.
+- **Pre-approve scopes at sign-in.** The mid-flow consent prompt cost users.
+- **Adopt `dbForUser` from the first route handler.** Retrofitting it is fine, but you'll find IDORs you didn't expect.
+- **Don't override Better Auth cookie defaults.** They're correct; "hardening" introduced the `sameSite: 'strict'` regression.
+- **Test sign-in twice (sign out between)** before declaring the OAuth flow shipped — that's the only way to catch missing `refresh_token` on second consent.

package/skills/authentication/references/resend-email.md

@@ -0,0 +1,227 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Resend — Transactional Email + Webhooks
+
+## When to use
+
+- Sending transactional email from a Better Auth or custom backend
+- Wiring `Better Auth`'s `sendVerificationEmail` or `magicLink.sendMagicLink` to Resend
+- Verifying Resend webhook signatures (so bounces/complaints update your DB safely)
+- Tracking delivery status (sent → delivered → bounced) per message
+
+For magic-link / OTP delivery patterns specifically (templates, retry, bounce handling at the user-flow level), see `resend-otp-magic-link.md`.
+
+For runtime API doc lookups, use `mcp__plugin_context7_context7__query-docs` with library `/websites/resend` (broader SDK surface) or `/resend/resend-skills` (better tuned for agent-flavored questions).
+
+## Sending — basic transactional
+
+```ts
+// lib/email/resend.ts
+import { Resend } from 'resend'
+
+const resend = new Resend(process.env.RESEND_API_KEY!)
+
+export async function sendTransactional({
+  to,
+  subject,
+  html,
+  tags,
+}: {
+  to: string | string[]
+  subject: string
+  html: string
+  tags?: Array<{ name: string; value: string }>
+}) {
+  const { data, error } = await resend.emails.send({
+    from: process.env.AUTH_EMAIL_FROM || 'YourApp <noreply@example.com>',
+    to,
+    subject,
+    html,
+    tags, // showed up in webhook payloads — useful for routing webhooks to the right tracker
+  })
+  if (error) throw new Error(`Resend: ${error.message}`)
+  return data!.id // store this; webhook events reference it
+}
+```
+
+## Wiring Better Auth's `sendVerificationEmail` (or `sendMagicLink`)
+
+Pattern from example-app. The handler is small because Better Auth gives you the URL and email; Resend just delivers:
+
+```ts
+// lib/email/send-magic-link.ts
+import { Resend } from 'resend'
+
+export async function sendMagicLinkEmail({ email, url }: { email: string; url: string }) {
+  if (!process.env.RESEND_API_KEY) {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('[auth] sendMagicLinkEmail: RESEND_API_KEY missing')
+    }
+    // Dev: log to console (see better-auth-magic-link.md for the full pattern)
+    console.log(`[dev] magic link → ${email}: ${url}`)
+    return
+  }
+
+  const resend = new Resend(process.env.RESEND_API_KEY)
+  const { error } = await resend.emails.send({
+    from: process.env.AUTH_EMAIL_FROM || 'YourApp <noreply@example.com>',
+    to: email,
+    subject: 'Sign in to YourApp',
+    html: `<a href="${url}">Sign in</a>`, // see better-auth-magic-link.md for a styled template
+  })
+  if (error) throw new Error(`[auth] Resend send failed: ${error.message}`)
+}
+```
+
+Then in `lib/auth.ts`:
+
+```ts
+import { magicLink } from 'better-auth/plugins'
+import { sendMagicLinkEmail } from '@/lib/email/send-magic-link'
+
+magicLink({
+  expiresIn: 60 * 10,
+  sendMagicLink: async ({ email, url }) => sendMagicLinkEmail({ email, url }),
+})
+```
+
+For email-verification on email/password sign-up, swap `magicLink` for `emailVerification` and pass `sendVerificationEmail` instead — same handoff shape.
+
+## Webhook signature verification
+
+**Critical:** without signature verification, an attacker can POST fake `email.bounced` events at your webhook to mark legit emails as bounced (potentially blocking real users from receiving mail, depending on your bounce-handling policy).
+
+Pattern from `Example Web App/app/api/webhooks/resend/route.ts`:
+
+```ts
+// app/api/webhooks/resend/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { headers } from 'next/headers'
+import { createHash, timingSafeEqual } from 'crypto'
+
+interface ResendWebhookEvent {
+  type: 'email.sent' | 'email.delivered' | 'email.bounced' | 'email.complained' | 'email.delivery_delayed'
+  created_at: string
+  data: {
+    id: string
+    to: string[]
+    from: string
+    subject: string
+    created_at: string
+    tags?: Array<{ name: string; value: string }>
+  }
+}
+
+function verifyWebhookSignature(body: string, signature: string, secret: string): boolean {
+  try {
+    const expected = createHash('sha256').update(body).update(secret).digest('hex')
+    const provided = signature.replace('sha256=', '')
+    return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(provided, 'hex'))
+  } catch (err) {
+    console.error('webhook signature verify failed:', err)
+    return false
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const headersList = await headers()
+  const signature = headersList.get('resend-signature')
+  const webhookSecret = process.env.RESEND_WEBHOOK_SECRET
+
+  if (!webhookSecret) {
+    // Decision call: warn vs hard-fail. Example Web App warns. For a stricter
+    // posture, return 401 here when the secret isn't configured in prod.
+    console.warn('RESEND_WEBHOOK_SECRET not configured — verification disabled')
+  }
+
+  const body = await request.text() // MUST read raw text BEFORE JSON.parse — signature is over the raw bytes
+  if (webhookSecret && signature) {
+    if (!verifyWebhookSignature(body, signature, webhookSecret)) {
+      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })
+    }
+  }
+
+  let event: ResendWebhookEvent
+  try {
+    event = JSON.parse(body)
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 })
+  }
+
+  // Idempotency: events can deliver more than once. Use event.data.id + event.type
+  // as the dedupe key against your delivery-status table.
+
+  // Map and persist:
+  const status = (
+    {
+      'email.sent': 'sent',
+      'email.delivered': 'delivered',
+      'email.bounced': 'bounced',
+      'email.complained': 'complained',
+      'email.delivery_delayed': 'sent', // keep as sent, log the delay separately
+    } as const
+  )[event.type]
+
+  if (!status) {
+    return NextResponse.json({ received: true })
+  }
+
+  await updateEmailDeliveryStatus(event.data.id, status, {
+    webhook_type: event.type,
+    webhook_received_at: new Date().toISOString(),
+    resend_created_at: event.created_at,
+    recipients: event.data.to,
+    tags: event.data.tags,
+  })
+
+  return NextResponse.json({ received: true, messageId: event.data.id, status })
+}
+
+export async function GET() {
+  // Health check — useful for verifying the webhook URL is wired before pointing Resend at it
+  return NextResponse.json({
+    status: 'ok',
+    configured: {
+      webhook_secret: !!process.env.RESEND_WEBHOOK_SECRET,
+      resend_api_key: !!process.env.RESEND_API_KEY,
+    },
+  })
+}
+```
+
+### Why the specific crypto choices
+
+- **`timingSafeEqual`** (not `===`) — prevents timing-based signature forgery. `===` short-circuits on first mismatched byte and leaks signature length info.
+- **`createHash('sha256').update(body).update(secret)`** — the order matches what Resend signs. If you swap them, signatures won't verify.
+- **Read raw text BEFORE `JSON.parse`** — Next.js will not give you the unparsed body if you call `request.json()` first; the bytes for signature verification have to be the exact wire bytes.
+
+## Idempotency — same event twice
+
+Resend webhooks are at-least-once. If your `updateEmailDeliveryStatus` is non-idempotent, a redelivered event flips `bounced` → `sent` → `bounced`. Two patterns:
+
+1. **State-machine guard** — `delivered` is terminal; once a message is `delivered`, ignore subsequent non-`bounced` events. `bounced`/`complained` always wins.
+2. **Event-id dedupe** — store `(message_id, event_type, received_at)` as a unique tuple; if it's a duplicate, no-op.
+
+Pattern 1 is simpler; pattern 2 is correct under arbitrary event ordering. For most apps, pattern 1 is fine.
+
+## Required env vars
+
+```env
+RESEND_API_KEY=re_...
+RESEND_WEBHOOK_SECRET=whsec_...   # configure in Resend dashboard, then paste here
+AUTH_EMAIL_FROM="YourApp <noreply@yourdomain.com>"   # MUST match a verified domain
+```
+
+## Verification
+
+1. Send a test email via the SDK. Confirm Resend dashboard shows it.
+2. Check the webhook health endpoint: `GET /api/webhooks/resend` should return `configured: { webhook_secret: true, resend_api_key: true }`.
+3. From the Resend dashboard, send a test webhook. Confirm 200 response with valid signature; tamper with the body and confirm 401.
+4. Send to a bouncing address (`bounce@simulator.amazonses.com` if Resend is on SES) and confirm the `email.bounced` event lands and updates your tracker.
+5. Confirm the `from` address matches a verified domain — sending from an unverified domain returns a permission error from the SDK, not a webhook event.
+
+## Cross-references
+
+- `resend-otp-magic-link.md` — delivery / retry / bounce-handling patterns at the user-flow level
+- `better-auth-magic-link.md` — caller-side handoff pattern
+- For domain verification, DKIM, and SPF setup: query Context7 with `library: "/websites/resend"`, `topic: "domain verification"`

package/skills/authentication/references/resend-otp-magic-link.md

@@ -0,0 +1,153 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Resend — OTP / Magic-Link Delivery Patterns
+
+## When to use
+
+- Designing the user-flow side of magic-link or OTP delivery (templates, retry, bounce handling)
+- Choosing between magic-link and OTP for your app
+- Handling delivery failures gracefully without exposing email-existence to attackers
+
+For the SDK + webhook signature verification side, see `resend-email.md`.
+For the Better Auth plugin side (server config, expiry, single-use), see `better-auth-magic-link.md`.
+For runtime API doc lookups, use `mcp__plugin_context7_context7__query-docs` with `library: "/websites/resend"` (broader) or `/resend/resend-skills` (agent patterns).
+
+## Magic-link vs OTP — pick one
+
+| Factor | Magic Link | OTP (numeric code) |
+|---|---|---|
+| UX on the device that requested sign-in | One click — best | Type 6 digits |
+| UX on a different device than the request | Awful (have to forward link) | Good (read code on phone, type on laptop) |
+| Mobile app sign-in | OK with deep links, but easy to misconfigure | Better — code transcription works regardless of platform |
+| Phishing surface | Higher — link can be cloaked | Lower — code in body is hard to fake |
+| Server complexity | Same plugin, simpler delivery | Same plugin, slightly different UX |
+
+**Default**: magic-link for web-first apps, OTP for mobile-first or multi-device flows. Both can co-exist behind a "Send code" / "Email link instead" toggle.
+
+## Template — magic-link (HTML)
+
+Inline styles only — many email clients strip `<style>` blocks. Keep the styled CTA above the fold (most clients only show the first ~600px).
+
+```ts
+const html = `
+<!DOCTYPE html>
+<html>
+<body style="margin: 0; background: #f5f5f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;">
+  <div style="max-width: 480px; margin: 0 auto; padding: 32px 24px;">
+    <h1 style="font-size: 22px; color: #111; margin: 0 0 12px;">Sign in to ${appName}</h1>
+    <p style="color: #555; line-height: 1.5; margin: 0 0 24px;">
+      Click the button below to sign in. This link expires in 10 minutes and can only be used once.
+    </p>
+    <a href="${url}" style="display: inline-block; padding: 14px 24px; background: #111; color: #fff; text-decoration: none; border-radius: 8px; font-weight: 500;">
+      Sign in
+    </a>
+    <p style="color: #888; font-size: 12px; margin: 32px 0 0; line-height: 1.5;">
+      If the button doesn't work, paste this into your browser:<br>
+      <span style="color: #555; word-break: break-all;">${url}</span>
+    </p>
+    <p style="color: #aaa; font-size: 12px; margin: 16px 0 0;">
+      If you didn't request this, you can ignore this email.
+    </p>
+  </div>
+</body>
+</html>
+`
+```
+
+## Template — OTP (HTML)
+
+```ts
+const html = `
+<!DOCTYPE html>
+<html>
+<body style="margin: 0; background: #f5f5f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;">
+  <div style="max-width: 480px; margin: 0 auto; padding: 32px 24px;">
+    <h1 style="font-size: 22px; color: #111; margin: 0 0 12px;">Your sign-in code</h1>
+    <p style="color: #555; line-height: 1.5; margin: 0 0 24px;">
+      Enter this code in ${appName} to sign in. It expires in 10 minutes.
+    </p>
+    <div style="font-size: 32px; letter-spacing: 8px; font-weight: 700; text-align: center; padding: 20px; background: #fff; border: 1px solid #e5e5e7; border-radius: 8px; color: #111; font-family: 'SF Mono', Monaco, Consolas, monospace;">
+      ${code}
+    </div>
+    <p style="color: #aaa; font-size: 12px; margin: 24px 0 0;">
+      If you didn't request this, you can ignore this email.
+    </p>
+  </div>
+</body>
+</html>
+`
+```
+
+OTP-specific UX rules:
+- **Don't include the OTP in the email subject line** — visible in lock-screen previews. Use a generic subject ("Your sign-in code").
+- **Plain-text fallback** — many auto-readers (smart watches, accessibility tools) parse plain text only.
+- **No clickable URL alongside the code** — defeats the phishing-resistance benefit.
+
+## Retry / backoff on 429
+
+Resend returns 429 if you exceed your rate plan. Pattern:
+
+```ts
+async function sendWithRetry({ to, subject, html, attempt = 0 }: {
+  to: string; subject: string; html: string; attempt?: number
+}): Promise<{ id: string }> {
+  const resend = new Resend(process.env.RESEND_API_KEY!)
+  const { data, error } = await resend.emails.send({
+    from: process.env.AUTH_EMAIL_FROM!, to, subject, html,
+  })
+
+  if (!error) return { id: data!.id }
+
+  // Retry on 429 with jittered exponential backoff, max 3 attempts
+  if (error.name === 'rate_limit_exceeded' && attempt < 2) {
+    const delay = (2 ** attempt) * 500 + Math.random() * 250
+    await new Promise((r) => setTimeout(r, delay))
+    return sendWithRetry({ to, subject, html, attempt: attempt + 1 })
+  }
+
+  // 4xx other than 429 are config errors — don't retry, surface up
+  // 5xx are Resend-side; retry once then surface
+  if (error.name === 'application_error' && attempt < 1) {
+    await new Promise((r) => setTimeout(r, 1000))
+    return sendWithRetry({ to, subject, html, attempt: attempt + 1 })
+  }
+
+  throw new Error(`Resend send failed: ${error.message}`)
+}
+```
+
+Don't queue magic-link / OTP sends through a worker — they're sub-second user-blocking actions. If retries fail, surface "Couldn't send code, try again" rather than silently failing.
+
+## Bounce handling — what to show the user
+
+When Resend webhooks report `email.bounced` for a magic-link / OTP send, the user is sitting at the "check your email" screen. Options:
+
+1. **Generic message** ("If your email is registered, you'll receive a code in a minute") — does NOT distinguish bounce from success. Best for security; protects against email-existence enumeration.
+2. **Specific message after timeout** — after, say, 45s without delivery confirmation, show "We couldn't reach that email — double-check the address." Slightly leaks existence info but better UX.
+
+**Default to (1) unless your threat model says otherwise.** Email-existence enumeration is a real attack class (drives credential-stuffing target lists).
+
+For ops: log every `bounced` and `complained` event with context. A spike usually means either a misconfigured domain (DKIM/SPF) or an attacker enumerating addresses.
+
+## Idempotent re-send
+
+Users will tap "Resend code" / "Send link again" repeatedly. Behavior:
+
+- **Within `expiresIn` window**: invalidate the previous token, send a new one. Don't accumulate active tokens.
+- **Rate-limit per email**: max 3 sends per 10 minutes. After that, return generic success without sending — don't reveal the rate-limit to a flood attacker.
+- **Track resend count in your DB** so abuse stands out.
+
+## Verification
+
+1. Send a magic-link, click it, confirm session.
+2. Send a magic-link, wait 11 min, click it — confirm "expired" state.
+3. Send a magic-link, then immediately request another — confirm the first is invalidated (or both work, depending on your design; pick one and document).
+4. Send to a bouncing address — confirm the user sees the generic "check your email" UI, not an error, and the bounce is logged server-side.
+5. Resend 4 times in a minute — confirm rate-limit kicks in, user sees identical UI.
+6. Open the email on a phone — verify CTA button is finger-sized (≥44pt) and OTP code is selectable as a single block.
+
+## Cross-references
+
+- `resend-email.md` — SDK + webhook signature verification
+- `better-auth-magic-link.md` — server-side plugin config (`expiresIn`, single-use)
+- Universal footgun #10 (magic-link expiry & idempotency) in `../SKILL.md`