@mars-stack/cli 0.2.0 → 0.2.2

package/template/.cursor/skills/configure-magic-links/SKILL.md

@@ -0,0 +1,385 @@
+# Skill: Configure Magic Links
+
+Set up passwordless authentication via magic links in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add passwordless login, magic link authentication, email-only login, or remove the password requirement from sign-in.
+
+## Prerequisites
+
+- Email provider configured (see `configure-email` skill)
+- Prisma schema includes a `User` model
+
+## Architecture
+
+Magic link flow:
+1. User enters email → server generates a single-use token, stores it hashed with expiry, sends the raw token via email
+2. User clicks link → server hashes the incoming token, validates against DB, creates a session, and invalidates the token
+3. Tokens are single-use and time-limited to prevent replay attacks
+
+The magic link service lives in `src/features/auth/server/magic-link.ts`.
+
+## Step 1: Prisma Schema
+
+Add magic link fields to the `User` model or create a dedicated model:
+
+```prisma
+// prisma/schema/auth.prisma
+model MagicLink {
+  id        String   @id @default(cuid())
+  token     String   @unique
+  email     String
+  expiresAt DateTime
+  usedAt    DateTime?
+  createdAt DateTime @default(now())
+
+  @@index([token])
+  @@index([email])
+}
+```
+
+Run `yarn db:push` after changes.
+
+## Step 2: Configuration
+
+Add magic link settings to `src/config/app.config.ts`:
+
+```typescript
+auth: {
+  magicLink: {
+    enabled: true,
+    tokenExpiryMinutes: 15,
+    tokenLength: 32,
+  },
+},
+```
+
+## Step 3: Magic Link Service
+
+```typescript
+// src/features/auth/server/magic-link.ts
+import 'server-only';
+
+import { randomBytes, createHash } from 'crypto';
+import { prisma } from '@/lib/prisma';
+import { sendEmail } from '@/lib/mars';
+import { appConfig } from '@/config/app.config';
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+export async function createMagicLink(email: string): Promise<void> {
+  const rawToken = randomBytes(appConfig.auth.magicLink.tokenLength).toString('hex');
+  const hashedToken = hashToken(rawToken);
+  const expiryMinutes = appConfig.auth.magicLink.tokenExpiryMinutes;
+
+  // Invalidate any existing unused tokens for this email
+  await prisma.magicLink.updateMany({
+    where: { email, usedAt: null },
+    data: { usedAt: new Date() },
+  });
+
+  await prisma.magicLink.create({
+    data: {
+      token: hashedToken,
+      email,
+      expiresAt: new Date(Date.now() + expiryMinutes * 60 * 1000),
+    },
+  });
+
+  const baseUrl = process.env.APP_URL || 'http://localhost:3000';
+  const loginUrl = `${baseUrl}/api/auth/magic-link/verify?token=${rawToken}`;
+
+  await sendEmail({
+    to: email,
+    subject: `Sign in to ${appConfig.name}`,
+    text: `Click here to sign in: ${loginUrl}\n\nThis link expires in ${expiryMinutes} minutes and can only be used once.`,
+    html: `
+      <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
+        <h2>Sign in to ${appConfig.name}</h2>
+        <p>Click the button below to sign in:</p>
+        <div style="text-align: center; margin: 30px 0;">
+          <a href="${loginUrl}" style="background-color: #2563eb; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">
+            Sign In
+          </a>
+        </div>
+        <p style="color: #6b7280; font-size: 14px;">
+          This link expires in ${expiryMinutes} minutes and can only be used once.
+        </p>
+        <p style="color: #6b7280; font-size: 14px;">
+          If you didn't request this, you can safely ignore this email.
+        </p>
+      </div>
+    `,
+  });
+}
+
+export async function verifyMagicLink(
+  rawToken: string,
+): Promise<{ success: boolean; email?: string; error?: string }> {
+  const hashedToken = hashToken(rawToken);
+
+  const magicLink = await prisma.magicLink.findUnique({
+    where: { token: hashedToken },
+  });
+
+  if (!magicLink) {
+    return { success: false, error: 'Invalid or expired link' };
+  }
+
+  if (magicLink.usedAt) {
+    return { success: false, error: 'This link has already been used' };
+  }
+
+  if (magicLink.expiresAt < new Date()) {
+    return { success: false, error: 'This link has expired' };
+  }
+
+  // Mark token as used (single-use enforcement)
+  await prisma.magicLink.update({
+    where: { id: magicLink.id },
+    data: { usedAt: new Date() },
+  });
+
+  return { success: true, email: magicLink.email };
+}
+```
+
+## Step 4: Request Magic Link Route
+
+```typescript
+// src/app/api/auth/magic-link/route.ts
+import { handleApiError } from '@/lib/mars';
+import { checkRateLimit } from '@/lib/core/rate-limit';
+import { createMagicLink } from '@/features/auth/server/magic-link';
+import { NextResponse, type NextRequest } from 'next/server';
+import { z } from 'zod';
+
+const requestSchema = z.object({
+  email: z.string().email('Invalid email address'),
+});
+
+export async function POST(request: NextRequest) {
+  try {
+    const { email } = requestSchema.parse(await request.json());
+
+    await checkRateLimit(`magic-link:${email}`, {
+      maxAttempts: 5,
+      windowMs: 15 * 60 * 1000,
+    });
+
+    // Always return success to prevent email enumeration
+    try {
+      await createMagicLink(email);
+    } catch {
+      // Silently fail — don't reveal whether the email exists
+    }
+
+    return NextResponse.json({
+      message: 'If an account exists with that email, a sign-in link has been sent.',
+    });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/auth/magic-link' });
+  }
+}
+```
+
+## Step 5: Verify Magic Link Route
+
+```typescript
+// src/app/api/auth/magic-link/verify/route.ts
+import { handleApiError } from '@/lib/mars';
+import { verifyMagicLink } from '@/features/auth/server/magic-link';
+import { createSession } from '@/features/auth/server/sessions';
+import { prisma } from '@/lib/prisma';
+import { NextResponse, type NextRequest } from 'next/server';
+import { z } from 'zod';
+
+const verifySchema = z.object({
+  token: z.string().min(1),
+});
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const { token } = verifySchema.parse({ token: searchParams.get('token') });
+
+    const result = await verifyMagicLink(token);
+
+    if (!result.success) {
+      return NextResponse.redirect(
+        new URL(`/auth/login?error=${encodeURIComponent(result.error!)}`, request.url),
+      );
+    }
+
+    // Find or create the user
+    let user = await prisma.user.findUnique({ where: { email: result.email! } });
+
+    if (!user) {
+      user = await prisma.user.create({
+        data: {
+          email: result.email!,
+          emailVerified: true,
+        },
+      });
+    } else if (!user.emailVerified) {
+      await prisma.user.update({
+        where: { id: user.id },
+        data: { emailVerified: true },
+      });
+    }
+
+    // Create session and redirect
+    const response = NextResponse.redirect(new URL('/dashboard', request.url));
+    await createSession(user.id, response);
+
+    return response;
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/auth/magic-link/verify' });
+  }
+}
+```
+
+## Step 6: Login Page — Magic Link Form
+
+Add a magic link option to the login page:
+
+```typescript
+// src/features/auth/components/MagicLinkForm.tsx
+'use client';
+
+import { useState } from 'react';
+
+export function MagicLinkForm() {
+  const [email, setEmail] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+
+    try {
+      const res = await fetch('/api/auth/magic-link', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email }),
+      });
+
+      if (!res.ok) {
+        const data = await res.json();
+        setError(data.error || 'Something went wrong');
+        return;
+      }
+
+      setSubmitted(true);
+    } catch {
+      setError('Network error. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (submitted) {
+    return (
+      <div className="text-center">
+        <h2 className="text-xl font-semibold text-content-primary">Check your email</h2>
+        <p className="mt-2 text-content-secondary">
+          We sent a sign-in link to <strong>{email}</strong>.
+        </p>
+        <p className="mt-1 text-sm text-content-tertiary">
+          The link expires in 15 minutes.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <div>
+        <label htmlFor="email" className="block text-sm font-medium text-content-primary">
+          Email address
+        </label>
+        <input
+          id="email"
+          type="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+          className="mt-1 block w-full rounded-md border border-border-primary bg-surface-primary px-3 py-2 text-content-primary placeholder:text-content-tertiary focus:border-interactive-primary focus:outline-none focus:ring-1 focus:ring-interactive-primary"
+          placeholder="you@example.com"
+        />
+      </div>
+      {error && <p className="text-sm text-status-error">{error}</p>}
+      <button
+        type="submit"
+        disabled={loading}
+        className="w-full rounded-md bg-interactive-primary px-4 py-2 text-white hover:bg-interactive-primary-hover disabled:opacity-50"
+      >
+        {loading ? 'Sending...' : 'Send Magic Link'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Step 7: Cleanup Expired Tokens
+
+Add a lazy cleanup function to prevent unbounded growth:
+
+```typescript
+// In magic-link.ts
+export async function cleanupExpiredTokens(): Promise<void> {
+  await prisma.magicLink.deleteMany({
+    where: {
+      OR: [
+        { expiresAt: { lt: new Date() } },
+        { usedAt: { not: null }, createdAt: { lt: new Date(Date.now() - 24 * 60 * 60 * 1000) } },
+      ],
+    },
+  });
+}
+```
+
+Call this lazily during token creation (1% chance per request) to keep the table clean without `setInterval`:
+
+```typescript
+if (Math.random() < 0.01) {
+  cleanupExpiredTokens().catch(() => {});
+}
+```
+
+## Security Considerations
+
+- **Single-use tokens**: Each token is marked as used immediately upon verification.
+- **Previous tokens invalidated**: When a new magic link is requested, all previous unused tokens for that email are invalidated.
+- **Hashed storage**: Raw tokens are never stored; only SHA-256 hashes are persisted.
+- **No email enumeration**: The request endpoint always returns a success message regardless of whether the email exists.
+- **Rate limiting**: Magic link requests are rate-limited per email address.
+- **Short expiry**: Default 15 minutes prevents stale token abuse.
+
+## Testing
+
+1. Request a magic link with `console` email provider — check terminal for the link.
+2. Click the link — verify a session is created and the user is redirected.
+3. Click the same link again — should show "already used" error.
+4. Request a link, wait for expiry, then click — should show "expired" error.
+5. Request two links for the same email — only the second should work.
+6. Send 6 requests in 15 minutes — the 6th should be rate-limited.
+
+## Checklist
+
+- [ ] `MagicLink` model added to Prisma schema
+- [ ] Magic link config added to `app.config.ts`
+- [ ] Token generation stores hashed token with expiry
+- [ ] Previous tokens invalidated on new request
+- [ ] Verification marks token as used before creating session
+- [ ] Request endpoint prevents email enumeration
+- [ ] Rate limiting applied to magic link requests
+- [ ] Login page includes `MagicLinkForm` component
+- [ ] Expired token cleanup runs lazily
+- [ ] `db:push` run after schema changes