@mars-stack/cli 0.2.0 → 0.2.2

package/template/.cursor/skills/configure-two-factor/SKILL.md

@@ -0,0 +1,518 @@
+# Skill: Configure Two-Factor Authentication
+
+Set up TOTP-based two-factor authentication (2FA) with backup codes in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add 2FA, two-factor authentication, TOTP, authenticator app support, or backup codes.
+
+## Prerequisites
+
+- Auth system configured with session management
+- User model exists in Prisma schema
+
+## Architecture
+
+MARS 2FA uses TOTP (Time-based One-Time Password) compatible with Google Authenticator, Authy, 1Password, and similar apps. The flow:
+
+1. **Setup**: User enables 2FA → server generates a TOTP secret, displays QR code → user scans and enters a code to confirm
+2. **Login**: After password verification, if 2FA is enabled → user enters TOTP code or backup code → session is created
+3. **Backup codes**: Generated during setup, hashed and stored, each single-use
+
+## Step 1: Install Dependencies
+
+```bash
+yarn add otpauth qrcode
+yarn add -D @types/qrcode
+```
+
+- `otpauth` — TOTP/HOTP token generation and verification (lightweight, standards-compliant)
+- `qrcode` — QR code generation for the setup URI
+
+## Step 2: Prisma Schema
+
+```prisma
+// prisma/schema/auth.prisma — add to User model
+model User {
+  // ... existing fields
+  twoFactorSecret   String?
+  twoFactorEnabled  Boolean  @default(false)
+  backupCodes       String?  // JSON array of hashed codes
+}
+```
+
+Run `yarn db:push` after changes.
+
+## Step 3: TOTP Service
+
+```typescript
+// src/features/auth/server/two-factor.ts
+import 'server-only';
+
+import { TOTP } from 'otpauth';
+import { randomBytes, createHash } from 'crypto';
+import { prisma } from '@/lib/prisma';
+import { appConfig } from '@/config/app.config';
+
+function hashCode(code: string): string {
+  return createHash('sha256').update(code).digest('hex');
+}
+
+function generateBackupCodes(count: number = 10): string[] {
+  return Array.from({ length: count }, () =>
+    randomBytes(4).toString('hex').toUpperCase().match(/.{4}/g)!.join('-'),
+  );
+}
+
+export function createTOTP(secret: string, email: string): TOTP {
+  return new TOTP({
+    issuer: appConfig.name,
+    label: email,
+    algorithm: 'SHA1',
+    digits: 6,
+    period: 30,
+    secret,
+  });
+}
+
+export async function initiate2FASetup(
+  userId: string,
+  email: string,
+): Promise<{ secret: string; uri: string; qrDataUrl: string }> {
+  const { Secret } = await import('otpauth');
+  const QRCode = await import('qrcode');
+
+  const secret = new Secret({ size: 20 });
+  const totp = createTOTP(secret.base32, email);
+  const uri = totp.toString();
+  const qrDataUrl = await QRCode.toDataURL(uri);
+
+  // Store the secret but don't enable 2FA yet (requires confirmation)
+  await prisma.user.update({
+    where: { id: userId },
+    data: { twoFactorSecret: secret.base32 },
+  });
+
+  return { secret: secret.base32, uri, qrDataUrl };
+}
+
+export async function confirm2FASetup(
+  userId: string,
+  code: string,
+): Promise<{ success: boolean; backupCodes?: string[]; error?: string }> {
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { twoFactorSecret: true, email: true },
+  });
+
+  if (!user?.twoFactorSecret) {
+    return { success: false, error: '2FA setup not initiated' };
+  }
+
+  const totp = createTOTP(user.twoFactorSecret, user.email);
+  const isValid = totp.validate({ token: code, window: 1 }) !== null;
+
+  if (!isValid) {
+    return { success: false, error: 'Invalid code. Please try again.' };
+  }
+
+  const backupCodes = generateBackupCodes();
+  const hashedCodes = backupCodes.map(hashCode);
+
+  await prisma.user.update({
+    where: { id: userId },
+    data: {
+      twoFactorEnabled: true,
+      backupCodes: JSON.stringify(hashedCodes),
+    },
+  });
+
+  return { success: true, backupCodes };
+}
+
+export async function verify2FACode(
+  userId: string,
+  code: string,
+): Promise<{ success: boolean; error?: string }> {
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { twoFactorSecret: true, twoFactorEnabled: true, email: true, backupCodes: true },
+  });
+
+  if (!user?.twoFactorEnabled || !user.twoFactorSecret) {
+    return { success: false, error: '2FA is not enabled' };
+  }
+
+  // Try TOTP code first
+  const totp = createTOTP(user.twoFactorSecret, user.email);
+  const isValidTOTP = totp.validate({ token: code, window: 1 }) !== null;
+
+  if (isValidTOTP) {
+    return { success: true };
+  }
+
+  // Try backup code
+  const hashedInput = hashCode(code);
+  const storedCodes: string[] = JSON.parse(user.backupCodes || '[]');
+  const codeIndex = storedCodes.findIndex((stored) => stored === hashedInput);
+
+  if (codeIndex !== -1) {
+    // Remove the used backup code
+    storedCodes.splice(codeIndex, 1);
+    await prisma.user.update({
+      where: { id: userId },
+      data: { backupCodes: JSON.stringify(storedCodes) },
+    });
+    return { success: true };
+  }
+
+  return { success: false, error: 'Invalid code' };
+}
+
+export async function disable2FA(userId: string): Promise<void> {
+  await prisma.user.update({
+    where: { id: userId },
+    data: {
+      twoFactorEnabled: false,
+      twoFactorSecret: null,
+      backupCodes: null,
+    },
+  });
+}
+
+export async function regenerateBackupCodes(userId: string): Promise<string[]> {
+  const backupCodes = generateBackupCodes();
+  const hashedCodes = backupCodes.map(hashCode);
+
+  await prisma.user.update({
+    where: { id: userId },
+    data: { backupCodes: JSON.stringify(hashedCodes) },
+  });
+
+  return backupCodes;
+}
+```
+
+## Step 4: 2FA Setup API Routes
+
+```typescript
+// src/app/api/protected/user/two-factor/setup/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { initiate2FASetup } from '@/features/auth/server/two-factor';
+import { NextResponse } from 'next/server';
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const result = await initiate2FASetup(request.session.userId, request.session.email);
+    return NextResponse.json({
+      qrDataUrl: result.qrDataUrl,
+      secret: result.secret,
+    });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/user/two-factor/setup' });
+  }
+});
+```
+
+```typescript
+// src/app/api/protected/user/two-factor/confirm/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { confirm2FASetup } from '@/features/auth/server/two-factor';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const confirmSchema = z.object({
+  code: z.string().length(6, 'Code must be 6 digits'),
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const { code } = confirmSchema.parse(await request.json());
+    const result = await confirm2FASetup(request.session.userId, code);
+
+    if (!result.success) {
+      return NextResponse.json({ error: result.error }, { status: 400 });
+    }
+
+    return NextResponse.json({ backupCodes: result.backupCodes });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/user/two-factor/confirm' });
+  }
+});
+```
+
+```typescript
+// src/app/api/protected/user/two-factor/disable/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { disable2FA } from '@/features/auth/server/two-factor';
+import { NextResponse } from 'next/server';
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    await disable2FA(request.session.userId);
+    return NextResponse.json({ message: '2FA has been disabled' });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/user/two-factor/disable' });
+  }
+});
+```
+
+## Step 5: Modify Login Flow
+
+Update the login route to check for 2FA after password verification:
+
+```typescript
+// In src/app/api/auth/login/route.ts — after password verification
+import { prisma } from '@/lib/prisma';
+
+// After verifying password...
+const user = await prisma.user.findUnique({
+  where: { email },
+  select: { id: true, twoFactorEnabled: true },
+});
+
+if (user.twoFactorEnabled) {
+  // Return a pending-2FA response with a temporary token
+  const pendingToken = randomBytes(32).toString('hex');
+  // Store in short-lived cache or DB with 5-minute expiry
+  await storePending2FAToken(pendingToken, user.id);
+
+  return NextResponse.json({
+    requiresTwoFactor: true,
+    pendingToken,
+  });
+}
+
+// If no 2FA, create session as normal
+```
+
+```typescript
+// src/app/api/auth/two-factor/verify/route.ts
+import { handleApiError } from '@/lib/mars';
+import { verify2FACode } from '@/features/auth/server/two-factor';
+import { createSession } from '@/features/auth/server/sessions';
+import { NextResponse, type NextRequest } from 'next/server';
+import { z } from 'zod';
+
+const verifySchema = z.object({
+  pendingToken: z.string().min(1),
+  code: z.string().min(1),
+});
+
+export async function POST(request: NextRequest) {
+  try {
+    const { pendingToken, code } = verifySchema.parse(await request.json());
+
+    const userId = await validatePending2FAToken(pendingToken);
+    if (!userId) {
+      return NextResponse.json({ error: 'Invalid or expired session' }, { status: 401 });
+    }
+
+    const result = await verify2FACode(userId, code);
+    if (!result.success) {
+      return NextResponse.json({ error: result.error }, { status: 401 });
+    }
+
+    const response = NextResponse.json({ success: true });
+    await createSession(userId, response);
+    return response;
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/auth/two-factor/verify' });
+  }
+}
+```
+
+## Step 6: Settings UI — 2FA Management
+
+```typescript
+// src/features/auth/components/TwoFactorSetup.tsx
+'use client';
+
+import { useState } from 'react';
+
+type SetupStep = 'idle' | 'scanning' | 'confirming' | 'backup-codes' | 'complete';
+
+export function TwoFactorSetup({ enabled }: { enabled: boolean }) {
+  const [step, setStep] = useState<SetupStep>('idle');
+  const [qrDataUrl, setQrDataUrl] = useState('');
+  const [secret, setSecret] = useState('');
+  const [code, setCode] = useState('');
+  const [backupCodes, setBackupCodes] = useState<string[]>([]);
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  async function handleStartSetup() {
+    setLoading(true);
+    setError('');
+    try {
+      const res = await fetch('/api/protected/user/two-factor/setup', { method: 'POST' });
+      const data = await res.json();
+      setQrDataUrl(data.qrDataUrl);
+      setSecret(data.secret);
+      setStep('scanning');
+    } catch {
+      setError('Failed to start setup');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function handleConfirm() {
+    setLoading(true);
+    setError('');
+    try {
+      const res = await fetch('/api/protected/user/two-factor/confirm', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code }),
+      });
+      const data = await res.json();
+
+      if (!res.ok) {
+        setError(data.error || 'Invalid code');
+        return;
+      }
+
+      setBackupCodes(data.backupCodes);
+      setStep('backup-codes');
+    } catch {
+      setError('Verification failed');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function handleDisable() {
+    setLoading(true);
+    try {
+      await fetch('/api/protected/user/two-factor/disable', { method: 'POST' });
+      window.location.reload();
+    } catch {
+      setError('Failed to disable 2FA');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (enabled) {
+    return (
+      <div className="space-y-4">
+        <div className="flex items-center gap-2">
+          <span className="h-2 w-2 rounded-full bg-status-success" />
+          <span className="text-content-primary font-medium">Two-factor authentication is enabled</span>
+        </div>
+        <button
+          onClick={handleDisable}
+          disabled={loading}
+          className="rounded-md bg-status-error px-4 py-2 text-white hover:bg-status-error/90 disabled:opacity-50"
+        >
+          Disable 2FA
+        </button>
+      </div>
+    );
+  }
+
+  // Render setup flow based on current step...
+  // (scanning → QR code display, confirming → code input, backup-codes → display codes)
+  return (
+    <div className="space-y-4">
+      {step === 'idle' && (
+        <button
+          onClick={handleStartSetup}
+          disabled={loading}
+          className="rounded-md bg-interactive-primary px-4 py-2 text-white hover:bg-interactive-primary-hover disabled:opacity-50"
+        >
+          Enable Two-Factor Authentication
+        </button>
+      )}
+
+      {step === 'scanning' && (
+        <div className="space-y-4">
+          <p className="text-content-secondary">Scan this QR code with your authenticator app:</p>
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img src={qrDataUrl} alt="2FA QR Code" className="mx-auto h-48 w-48" />
+          <details className="text-sm">
+            <summary className="cursor-pointer text-content-tertiary">Can&apos;t scan? Enter manually</summary>
+            <code className="mt-2 block break-all rounded bg-surface-secondary p-2 text-xs">{secret}</code>
+          </details>
+          <button
+            onClick={() => setStep('confirming')}
+            className="rounded-md bg-interactive-primary px-4 py-2 text-white hover:bg-interactive-primary-hover"
+          >
+            Next
+          </button>
+        </div>
+      )}
+
+      {step === 'confirming' && (
+        <div className="space-y-4">
+          <p className="text-content-secondary">Enter the 6-digit code from your authenticator app:</p>
+          <input
+            type="text"
+            value={code}
+            onChange={(e) => setCode(e.target.value)}
+            maxLength={6}
+            placeholder="000000"
+            className="block w-full rounded-md border border-border-primary bg-surface-primary px-3 py-2 text-center text-2xl tracking-widest text-content-primary focus:border-interactive-primary focus:outline-none focus:ring-1 focus:ring-interactive-primary"
+          />
+          {error && <p className="text-sm text-status-error">{error}</p>}
+          <button
+            onClick={handleConfirm}
+            disabled={loading || code.length !== 6}
+            className="w-full rounded-md bg-interactive-primary px-4 py-2 text-white hover:bg-interactive-primary-hover disabled:opacity-50"
+          >
+            Verify & Enable
+          </button>
+        </div>
+      )}
+
+      {step === 'backup-codes' && (
+        <div className="space-y-4">
+          <h3 className="text-lg font-semibold text-content-primary">Save your backup codes</h3>
+          <p className="text-content-secondary">
+            Store these codes in a safe place. Each can be used once if you lose access to your authenticator.
+          </p>
+          <div className="grid grid-cols-2 gap-2 rounded-md bg-surface-secondary p-4">
+            {backupCodes.map((bc) => (
+              <code key={bc} className="font-mono text-sm text-content-primary">{bc}</code>
+            ))}
+          </div>
+          <button
+            onClick={() => setStep('complete')}
+            className="rounded-md bg-interactive-primary px-4 py-2 text-white hover:bg-interactive-primary-hover"
+          >
+            I&apos;ve saved my codes
+          </button>
+        </div>
+      )}
+
+      {step === 'complete' && (
+        <p className="text-status-success font-medium">Two-factor authentication is now enabled.</p>
+      )}
+    </div>
+  );
+}
+```
+
+## Testing
+
+1. Enable 2FA in settings — scan QR with an authenticator app (or use the manual key).
+2. Enter the 6-digit code — verify backup codes are displayed.
+3. Log out and log back in — verify 2FA prompt appears after password.
+4. Enter a valid TOTP code — verify login succeeds.
+5. Enter an invalid code — verify it's rejected.
+6. Use a backup code — verify login succeeds and the code is consumed.
+7. Try the same backup code again — verify it's rejected.
+8. Disable 2FA — verify login no longer requires a code.
+
+## Checklist
+
+- [ ] `otpauth` and `qrcode` installed
+- [ ] User model updated with `twoFactorSecret`, `twoFactorEnabled`, `backupCodes`
+- [ ] TOTP service handles setup, confirm, verify, disable, and backup code regeneration
+- [ ] Login flow branched to handle 2FA prompt
+- [ ] 2FA verification route creates session after code validation
+- [ ] Backup codes are hashed and single-use
+- [ ] Settings UI allows enable/disable with QR code flow
+- [ ] Pending-2FA tokens are short-lived (5 minutes)
+- [ ] `db:push` run after schema changes