From a8ff57cd40918256964ab12a5231fdeca9c606b1 Mon Sep 17 00:00:00 2001
From: Jun-te Kim <junte.kim@mealcraft.com>
Date: Mon, 29 Dec 2025 14:42:49 +0000
Subject: [PATCH] save plan

---
 stripe_to_invoice/README.md | 200 +++++++++++++++++++++++++++++++-----
 1 file changed, 177 insertions(+), 23 deletions(-)

diff --git a/stripe_to_invoice/README.md b/stripe_to_invoice/README.md
index e215bc4..29d91ae 100644
--- a/stripe_to_invoice/README.md
+++ b/stripe_to_invoice/README.md
@@ -1,36 +1,190 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# 🚀 MVP Next Steps – Post SES Setup
 
-## Getting Started
+This document outlines the concrete next steps to build the MVP now that
+Amazon SES email delivery is fully configured and verified.
 
-First, run the development server:
+---
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
+## ✅ Phase 0 — Email Infrastructure (COMPLETED)
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+**Status: DONE**
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+- SES domain verified (`juntekim.com`)
+- DKIM, SPF, DMARC configured
+- Custom MAIL FROM domain enabled
+- Test email delivered to Gmail inbox
+- SES production access requested
+- SMTP credentials generated and stored securely
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+No further SES work is required for MVP.
 
-## Learn More
+---
 
-To learn more about Next.js, take a look at the following resources:
+## 🔐 Phase 1 — Magic Link Authentication (Core MVP)
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+### 1️⃣ Define Authentication Model
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+**Decisions**
+- Email-only authentication (no passwords)
+- Magic links are:
+  - Single-use
+  - Time-limited (e.g. 15 minutes)
+  - Hashed before storage
+- No persistent email storage
 
-## Deploy on Vercel
+**Outcome**
+- Clear security model before implementation
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+---
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+### 2️⃣ Create Magic Link Token Table
+
+**Required fields**
+- `id`
+- `email`
+- `token_hash`
+- `expires_at`
+- `used_at`
+- `created_at`
+
+**Rules**
+- Never store raw tokens
+- Reject expired tokens
+- Reject reused tokens
+- Mark token as used immediately after login
+
+**Outcome**
+- Database migration + model ready
+
+---
+
+### 3️⃣ Build Email Sending Adapter (SES SMTP)
+
+**Requirements**
+- Uses Amazon SES SMTP credentials
+- Sends from `no-reply@juntekim.com`
+- Generates secure magic link URLs
+- Plain-text email (HTML later)
+
+**Example responsibility**
+- `sendMagicLink(email, url)`
+
+**Outcome**
+- Single reusable email-sending utility
+
+---
+
+## 🔑 Phase 2 — NextAuth Integration
+
+### 4️⃣ Configure NextAuth (Email Provider)
+
+**Actions**
+- Enable NextAuth Email provider
+- Configure SES SMTP transport
+- Disable default token storage
+- Use custom DB token table
+
+**Outcome**
+- NextAuth initialized and functional
+
+---
+
+### 5️⃣ Implement `/auth/callback` Logic
+
+**Flow**
+1. User clicks magic link
+2. Token is hashed and validated
+3. Token expiry checked
+4. Token marked as used
+5. Session created
+6. Redirect to app
+
+**Outcome**
+- End-to-end login flow works
+
+---
+
+### 6️⃣ Minimal Authentication UI
+
+**Pages**
+- Email input form
+- “Check your email” confirmation screen
+- Error states:
+  - Invalid token
+  - Expired token
+  - Already-used token
+
+**Outcome**
+- Usable authentication UX
+
+---
+
+## 🛡 Phase 3 — MVP Hardening (Still Lightweight)
+
+### 7️⃣ Rate Limiting
+
+Add limits for:
+- Magic link requests per email
+- Magic link requests per IP
+
+Purpose:
+- Prevent abuse
+- Protect SES reputation
+
+---
+
+### 8️⃣ Basic Logging
+
+Log only:
+- Email requested
+- Email send success/failure
+- Login success/failure
+
+Do **not** store email content.
+
+---
+
+### 9️⃣ Production Sanity Checks
+
+Before real users:
+- Test login on mobile + desktop
+- Test Gmail + Outlook
+- Test expired link behavior
+- Test reused link rejection
+
+---
+
+## 🚦 MVP Definition of Done
+
+The MVP is considered complete when:
+
+- User enters email
+- User receives magic link
+- User clicks link
+- User is authenticated
+- Session persists
+
+No additional features are required to ship.
+
+---
+
+## 🧠 Guiding Principles
+
+- Infrastructure first (done)
+- Security before UX polish
+- Ship working flows early
+- Avoid overbuilding before user feedback
+
+---
+
+## 🧩 Post-MVP (Optional, Later)
+
+Do NOT block MVP on:
+- HTML email templates
+- Branded emails
+- Email analytics
+- Admin dashboards
+- Multi-provider auth
+- Password fallback
+
+Ship first, iterate later.