@mars-stack/core 0.4.0

package/cursor/skills/mars-add-api-route/SKILL.md

@@ -0,0 +1,120 @@
+# Skill: Add an API Route
+
+Create a new Next.js API route following MARS conventions for authentication, validation, error handling, and testing.
+
+## When to Use
+
+Use this skill when the user asks to create a new endpoint, API route, or backend handler.
+
+## Decision: Public or Protected?
+
+| Type | Location | Auth Wrapper | Use Case |
+|------|----------|-------------|----------|
+| Public | `src/app/api/<name>/route.ts` | None (but add rate limiting) | Auth endpoints, webhooks, health checks |
+| Protected | `src/app/api/protected/<name>/route.ts` | `withAuth` / `withRole` / `withOwnership` | User data, settings, admin |
+
+## Protected Route Template
+
+```typescript
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const userId = request.session.userId;
+    // ... business logic using userId for scoping
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<name>' });
+  }
+});
+```
+
+### Auth Wrapper Reference
+
+| Wrapper | Signature | When to Use |
+|---------|-----------|-------------|
+| `withAuth` | `(request, { params })` | Routes with dynamic URL params |
+| `withAuthNoParams` | `(request)` | Routes without URL params |
+| `withAuthSimple` | `()` | Routes that only need session verification |
+| `withRole` | `withRole(['admin'], handler)` | Admin-only routes (verifies role from DB) |
+| `withOwnership` | `withOwnership(getResourceUserId, handler)` | User must own the resource |
+
+## Public Route Template (with Rate Limiting)
+
+```typescript
+import { handleApiError } from '@/lib/mars';
+import { checkRateLimit, getClientIP, RATE_LIMITS, rateLimitResponse } from '@mars-stack/core/rate-limit';
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const ip = getClientIP(request);
+  const rateLimit = await checkRateLimit(ip, RATE_LIMITS.default);
+  if (!rateLimit.success) return rateLimitResponse(rateLimit.resetAt);
+
+  try {
+    // ... business logic
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/<name>' });
+  }
+}
+```
+
+## Input Validation
+
+Always validate request bodies with Zod before use:
+
+```typescript
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+});
+
+// Inside the handler:
+const body = schema.parse(await request.json());
+```
+
+`handleApiError` will automatically catch `ZodError` and return a 400 with the first error message.
+
+## Dynamic Routes
+
+For routes with URL parameters like `/api/protected/widgets/[id]/route.ts`:
+
+```typescript
+export const GET = withAuth(async (request, context) => {
+  try {
+    const { id } = await context.params;
+    const userId = request.session.userId;
+    // ... fetch by id, scoped to userId
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/widgets/[id]' });
+  }
+});
+```
+
+## Error Handling Reference
+
+`handleApiError` from `@/lib/mars` handles:
+
+| Error Type | HTTP Status | Client Response |
+|-----------|-------------|----------------|
+| `ZodError` | 400 | First validation error message |
+| Prisma / Database | 503 | "Service temporarily unavailable" + detailed terminal diagnostics |
+| All others | 500 | Custom `fallbackMessage` or "An unexpected error occurred" |
+
+## Testing
+
+Create `route.test.ts` beside the route file. See the `add-feature` skill for the full testing pattern.
+
+## Checklist
+
+- [ ] Correct directory (public vs protected)
+- [ ] Appropriate auth wrapper applied
+- [ ] Rate limiting on public endpoints
+- [ ] Zod validation for all inputs
+- [ ] Queries scoped by `request.session.userId`
+- [ ] `handleApiError` in every catch block
+- [ ] Test file created

package/cursor/skills/mars-add-audit-log/SKILL.md

@@ -0,0 +1,373 @@
+# Skill: Add Audit Log
+
+Add user action tracking with a Prisma `AuditLog` model, server-side logging helper, admin view, and retention policy.
+
+## When to Use
+
+Use this skill when the user asks to add audit logging, activity tracking, compliance logging, user action history, or admin activity monitoring.
+
+## Prerequisites
+
+- Read `src/lib/mars.ts` to check available auth wrappers.
+- Read `prisma/schema/` to see existing models.
+
+## Step 1: Prisma Schema
+
+```prisma
+// prisma/schema/audit-log.prisma
+model AuditLog {
+  id           String   @id @default(cuid())
+  userId       String?
+  action       String
+  resourceType String
+  resourceId   String?
+  metadata     Json?
+  ipAddress    String?
+  userAgent    String?
+  timestamp    DateTime @default(now())
+
+  user User? @relation(fields: [userId], references: [id], onDelete: SetNull)
+
+  @@index([userId])
+  @@index([action])
+  @@index([resourceType])
+  @@index([resourceType, resourceId])
+  @@index([timestamp])
+}
+```
+
+Update the User model in `prisma/schema/auth.prisma` to add the relation:
+
+```prisma
+model User {
+  // ... existing fields
+  auditLogs AuditLog[]
+}
+```
+
+Run `yarn db:push` to sync.
+
+## Step 2: Audit Log Types
+
+```typescript
+// src/features/audit-log/types.ts
+export interface AuditEventInput {
+  userId?: string;
+  action: AuditAction;
+  resourceType: string;
+  resourceId?: string;
+  metadata?: Record<string, unknown>;
+  ipAddress?: string;
+  userAgent?: string;
+}
+
+export type AuditAction =
+  | 'create'
+  | 'read'
+  | 'update'
+  | 'delete'
+  | 'login'
+  | 'logout'
+  | 'login_failed'
+  | 'password_change'
+  | 'password_reset'
+  | 'email_verify'
+  | 'role_change'
+  | 'export'
+  | 'invite'
+  | 'settings_change';
+
+export interface AuditLogQuery {
+  userId?: string;
+  action?: AuditAction;
+  resourceType?: string;
+  resourceId?: string;
+  startDate?: Date;
+  endDate?: Date;
+  limit?: number;
+  cursor?: string;
+}
+```
+
+## Step 3: Server-Side Audit Logger
+
+```typescript
+// src/features/audit-log/server/index.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import { apiLogger } from '@/lib/mars';
+import type { AuditEventInput, AuditLogQuery } from '../types';
+
+export async function logAuditEvent(event: AuditEventInput): Promise<void> {
+  try {
+    await prisma.auditLog.create({
+      data: {
+        userId: event.userId,
+        action: event.action,
+        resourceType: event.resourceType,
+        resourceId: event.resourceId,
+        metadata: event.metadata ?? undefined,
+        ipAddress: event.ipAddress,
+        userAgent: event.userAgent,
+      },
+    });
+  } catch (error) {
+    apiLogger.error({ error, event: event.action }, 'Failed to write audit log');
+  }
+}
+
+export function logAuditEventFromRequest(
+  request: Request,
+  event: Omit<AuditEventInput, 'ipAddress' | 'userAgent'>,
+): Promise<void> {
+  return logAuditEvent({
+    ...event,
+    ipAddress: request.headers.get('x-forwarded-for')?.split(',')[0]?.trim()
+      ?? request.headers.get('x-real-ip')
+      ?? undefined,
+    userAgent: request.headers.get('user-agent') ?? undefined,
+  });
+}
+
+export async function queryAuditLogs(query: AuditLogQuery) {
+  const where: Record<string, unknown> = {};
+
+  if (query.userId) where.userId = query.userId;
+  if (query.action) where.action = query.action;
+  if (query.resourceType) where.resourceType = query.resourceType;
+  if (query.resourceId) where.resourceId = query.resourceId;
+
+  if (query.startDate || query.endDate) {
+    where.timestamp = {};
+    if (query.startDate) (where.timestamp as Record<string, unknown>).gte = query.startDate;
+    if (query.endDate) (where.timestamp as Record<string, unknown>).lte = query.endDate;
+  }
+
+  const take = Math.min(query.limit ?? 50, 100);
+
+  return prisma.auditLog.findMany({
+    where,
+    orderBy: { timestamp: 'desc' },
+    take,
+    ...(query.cursor ? { skip: 1, cursor: { id: query.cursor } } : {}),
+    include: {
+      user: { select: { id: true, email: true, name: true } },
+    },
+  });
+}
+
+export async function cleanupOldAuditLogs(retentionDays: number = 90): Promise<number> {
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - retentionDays);
+
+  const result = await prisma.auditLog.deleteMany({
+    where: { timestamp: { lt: cutoff } },
+  });
+
+  apiLogger.info({ deleted: result.count, retentionDays }, 'Audit log cleanup completed');
+  return result.count;
+}
+```
+
+## Step 4: Usage in API Routes
+
+Integrate audit logging into existing route handlers:
+
+```typescript
+// Example: in an existing update route
+import { logAuditEventFromRequest } from '@/features/audit-log/server';
+
+export const PUT = withAuth(async (request, { params }) => {
+  try {
+    const { id } = await params;
+    const body = updateSchema.parse(await request.json());
+    const updated = await updateResource(request.session.userId, id, body);
+
+    await logAuditEventFromRequest(request, {
+      userId: request.session.userId,
+      action: 'update',
+      resourceType: 'widget',
+      resourceId: id,
+      metadata: { fields: Object.keys(body) },
+    });
+
+    return NextResponse.json(updated);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/widgets/[id]' });
+  }
+});
+```
+
+### Auth event logging
+
+```typescript
+// In login route: src/app/api/auth/login/route.ts
+await logAuditEventFromRequest(request, {
+  userId: user.id,
+  action: 'login',
+  resourceType: 'session',
+});
+
+// On failed login
+await logAuditEventFromRequest(request, {
+  action: 'login_failed',
+  resourceType: 'auth',
+  metadata: { email: body.email },
+});
+```
+
+## Step 5: Admin Audit Log API
+
+```typescript
+// src/app/api/protected/admin/audit-logs/route.ts
+import { handleApiError, withRole } from '@/lib/mars';
+import { queryAuditLogs } from '@/features/audit-log/server';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  userId: z.string().optional(),
+  action: z.string().optional(),
+  resourceType: z.string().optional(),
+  resourceId: z.string().optional(),
+  startDate: z.coerce.date().optional(),
+  endDate: z.coerce.date().optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+  cursor: z.string().optional(),
+});
+
+export const GET = withRole(['admin'], async (request) => {
+  try {
+    const url = new URL(request.url);
+    const query = querySchema.parse(Object.fromEntries(url.searchParams));
+    const logs = await queryAuditLogs(query);
+    return NextResponse.json(logs);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/admin/audit-logs' });
+  }
+});
+```
+
+## Step 6: Cleanup API (Admin)
+
+```typescript
+// src/app/api/protected/admin/audit-logs/cleanup/route.ts
+import { handleApiError, withRole } from '@/lib/mars';
+import { cleanupOldAuditLogs } from '@/features/audit-log/server';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const cleanupSchema = z.object({
+  retentionDays: z.number().int().min(1).max(365).default(90),
+});
+
+export const POST = withRole(['admin'], async (request) => {
+  try {
+    const body = cleanupSchema.parse(await request.json());
+    const deleted = await cleanupOldAuditLogs(body.retentionDays);
+    return NextResponse.json({ deleted, retentionDays: body.retentionDays });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/admin/audit-logs/cleanup' });
+  }
+});
+```
+
+## Step 7: Retention Policy
+
+Set up automated cleanup using a cron job or scheduled function:
+
+```typescript
+// src/app/api/cron/audit-cleanup/route.ts
+import { NextResponse } from 'next/server';
+import { cleanupOldAuditLogs } from '@/features/audit-log/server';
+
+export async function GET(request: Request) {
+  const authHeader = request.headers.get('authorization');
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const deleted = await cleanupOldAuditLogs(90);
+  return NextResponse.json({ deleted });
+}
+```
+
+Add to `vercel.json` for Vercel Cron:
+
+```json
+{
+  "crons": [
+    {
+      "path": "/api/cron/audit-cleanup",
+      "schedule": "0 3 * * 0"
+    }
+  ]
+}
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { logAuditEvent, queryAuditLogs } from './index';
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    auditLog: {
+      create: vi.fn(),
+      findMany: vi.fn(),
+      deleteMany: vi.fn(),
+    },
+  },
+}));
+
+vi.mock('@/lib/mars', () => ({
+  apiLogger: { error: vi.fn(), info: vi.fn() },
+}));
+
+describe('logAuditEvent', () => {
+  it('creates an audit log entry', async () => {
+    const { prisma } = await import('@/lib/prisma');
+    await logAuditEvent({
+      userId: 'user-1',
+      action: 'create',
+      resourceType: 'widget',
+      resourceId: 'widget-1',
+    });
+    expect(prisma.auditLog.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          userId: 'user-1',
+          action: 'create',
+          resourceType: 'widget',
+        }),
+      }),
+    );
+  });
+
+  it('does not throw if database write fails', async () => {
+    const { prisma } = await import('@/lib/prisma');
+    (prisma.auditLog.create as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('DB error'));
+    await expect(logAuditEvent({
+      action: 'login',
+      resourceType: 'session',
+    })).resolves.toBeUndefined();
+  });
+});
+```
+
+## Checklist
+
+- [ ] `AuditLog` model in Prisma schema with proper indexes
+- [ ] User relation added (with `onDelete: SetNull`)
+- [ ] `logAuditEvent()` and `logAuditEventFromRequest()` helpers created
+- [ ] Server module imports `'server-only'`
+- [ ] Audit logging integrated into key routes (auth, CRUD, admin actions)
+- [ ] Admin query API with filtering and cursor pagination
+- [ ] Cleanup endpoint and retention policy (default 90 days)
+- [ ] Cron job for automated cleanup
+- [ ] Audit logger never throws (fire-and-forget with error logging)
+- [ ] No PII logged in metadata (no passwords, tokens, or full request bodies)
+- [ ] `db:push` run after schema changes
+- [ ] Tests written for audit log service