@digilogiclabs/create-saas-app 2.0.0 → 2.2.0

package/src/templates/shared/observability/web/lib/observability.ts

@@ -0,0 +1,135 @@
+import { getClientIp } from '@digilogiclabs/platform-core/auth';
+
+/**
+ * Observability helpers — audit logging, error reporting, metrics.
+ *
+ * All functions are fire-and-forget (no await needed) and fail silently.
+ * Uses platform-core adapters when available, falls back to console.
+ *
+ * Customize the SERVICE_NAME and add app-specific audit actions.
+ */
+
+const SERVICE_NAME = 'my-app';
+
+// ─── Lazy Singletons ────────────────────────────────────────
+
+let auditLogPromise: Promise<AuditLogger> | null = null;
+
+interface AuditLogger {
+  log(event: AuditEvent): Promise<void>;
+}
+
+interface AuditEvent {
+  action: string;
+  actor: { id: string; type: string; email?: string };
+  resource?: { type: string; id?: string };
+  outcome: 'success' | 'failure' | 'blocked';
+  metadata?: Record<string, unknown>;
+  category?: string;
+  ip?: string;
+  userAgent?: string;
+}
+
+async function getAuditLog(): Promise<AuditLogger> {
+  if (!auditLogPromise) {
+    auditLogPromise = (async () => {
+      try {
+        const { getPlatform } = await import('@/lib/platform');
+        const platform = await getPlatform();
+        const { DatabaseAuditLog } = await import('@digilogiclabs/platform-core');
+        return new DatabaseAuditLog(platform.db, { serviceName: SERVICE_NAME });
+      } catch {
+        return {
+          log: async (event: AuditEvent) => {
+            console.log(`[Audit] ${event.action}`, JSON.stringify(event));
+          },
+        };
+      }
+    })();
+  }
+  return auditLogPromise;
+}
+
+// ─── Public Helpers ──────────────────────────────────────────
+
+/** Get user agent string from request */
+export function getUserAgent(request: Request): string {
+  return request.headers.get('user-agent') || 'unknown';
+}
+
+// Re-export getClientIp from platform-core
+export { getClientIp } from '@digilogiclabs/platform-core/auth';
+
+/** Log an audit event (fire-and-forget) */
+export function auditAction(params: {
+  action: string;
+  actorId: string;
+  actorEmail?: string;
+  resourceType?: string;
+  resourceId?: string;
+  outcome?: 'success' | 'failure' | 'blocked';
+  metadata?: Record<string, unknown>;
+  request?: Request;
+}): void {
+  const category = inferCategory(params.action);
+  getAuditLog()
+    .then((log) =>
+      log.log({
+        action: params.action,
+        actor: {
+          id: params.actorId,
+          type: params.actorId === 'system' ? 'system' : 'user',
+          email: params.actorEmail,
+        },
+        resource: params.resourceType
+          ? { type: params.resourceType, id: params.resourceId }
+          : undefined,
+        outcome: params.outcome || 'success',
+        metadata: params.metadata,
+        category,
+        ip: params.request ? getClientIp(params.request) : undefined,
+        userAgent: params.request ? getUserAgent(params.request) : undefined,
+      })
+    )
+    .catch(() => {});
+}
+
+/** Log an admin action */
+export function auditAdminAction(
+  params: Omit<Parameters<typeof auditAction>[0], 'action'> & { action: string }
+): void {
+  auditAction({ ...params, action: `admin.${params.action}` });
+}
+
+/** Log a cron job action */
+export function auditCronAction(
+  params: Omit<Parameters<typeof auditAction>[0], 'actorId'> & { action: string }
+): void {
+  auditAction({ ...params, actorId: 'system', action: `cron.${params.action}` });
+}
+
+/** Capture an error (fire-and-forget) */
+export function captureError(error: unknown, context?: Record<string, unknown>): void {
+  try {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[${SERVICE_NAME}] Error:`, message, context || '');
+    if (stack && process.env.NODE_ENV === 'development') {
+      console.error(stack);
+    }
+  } catch {
+    // Silent fail — observability must never crash the app
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function inferCategory(action: string): string {
+  if (action.startsWith('admin.')) return 'admin';
+  if (action.startsWith('payment.')) return 'billing';
+  if (action.startsWith('account.')) return 'data_mutation';
+  if (action.startsWith('auth.')) return 'authentication';
+  if (action.startsWith('cron.')) return 'system';
+  if (action.startsWith('security.')) return 'security';
+  return 'general';
+}

package/src/templates/shared/payments/web/app/api/webhooks/stripe/route.ts

@@ -0,0 +1,109 @@
+/**
+ * Stripe Webhook Handler
+ *
+ * Handles Stripe webhook events for subscription lifecycle management.
+ * Uses HMAC signature verification and Redis-based idempotency.
+ *
+ * Required env vars:
+ *   STRIPE_SECRET_KEY      - Stripe API key
+ *   STRIPE_WEBHOOK_SECRET  - Webhook signing secret (whsec_...)
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import Stripe from 'stripe';
+import { getRedisClient } from '@/lib/redis';
+import { enforceRateLimit, AppRateLimits } from '@/lib/api-security';
+
+export const dynamic = 'force-dynamic';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',
+});
+
+/**
+ * Check if this webhook event has already been processed (idempotency).
+ * Uses Redis SET NX + EX pattern — atomic check-and-set with 24h TTL.
+ * Returns true if already processed, false if new.
+ */
+async function isEventProcessed(eventId: string): Promise<boolean> {
+  const redis = getRedisClient();
+  if (!redis) return false; // No Redis — allow processing (best-effort)
+  try {
+    const result = await redis.set(`webhook:${eventId}`, '1', 'EX', 86400, 'NX');
+    return result === null; // null = key already existed = already processed
+  } catch {
+    return false; // Redis error — allow processing
+  }
+}
+
+export async function POST(request: NextRequest) {
+  // Rate limit webhook calls (generous — Stripe retries on failure)
+  const rateLimited = await enforceRateLimit(request, 'stripe-webhook', AppRateLimits.webhook);
+  if (rateLimited) return rateLimited;
+
+  const body = await request.text();
+  const signature = request.headers.get('stripe-signature');
+
+  if (!signature) {
+    return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
+  }
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch (err) {
+    console.error('[Stripe Webhook] Signature verification failed:', err);
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  // Idempotency check — prevent duplicate processing
+  if (await isEventProcessed(event.id)) {
+    return NextResponse.json({ received: true, duplicate: true });
+  }
+
+  try {
+    switch (event.type) {
+      case 'checkout.session.completed': {
+        const session = event.data.object as Stripe.Checkout.Session;
+        console.log('[Stripe Webhook] Checkout completed:', session.id);
+        // TODO: Activate subscription, provision access, send welcome email
+        break;
+      }
+
+      case 'invoice.paid': {
+        const invoice = event.data.object as Stripe.Invoice;
+        console.log('[Stripe Webhook] Invoice paid:', invoice.id);
+        // TODO: Record payment, extend subscription
+        break;
+      }
+
+      case 'invoice.payment_failed': {
+        const invoice = event.data.object as Stripe.Invoice;
+        console.log('[Stripe Webhook] Payment failed:', invoice.id);
+        // TODO: Notify user, start grace period
+        break;
+      }
+
+      case 'customer.subscription.updated': {
+        const subscription = event.data.object as Stripe.Subscription;
+        console.log('[Stripe Webhook] Subscription updated:', subscription.id);
+        // TODO: Handle plan changes, cancellation scheduling
+        break;
+      }
+
+      case 'customer.subscription.deleted': {
+        const subscription = event.data.object as Stripe.Subscription;
+        console.log('[Stripe Webhook] Subscription deleted:', subscription.id);
+        // TODO: Revoke access, send cancellation email
+        break;
+      }
+
+      default:
+        console.log(`[Stripe Webhook] Unhandled event type: ${event.type}`);
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    console.error('[Stripe Webhook] Handler error:', error);
+    return NextResponse.json({ error: 'Webhook handler failed' }, { status: 500 });
+  }
+}

package/src/templates/shared/platform/web/lib/platform.ts

@@ -0,0 +1,37 @@
+/**
+ * Platform-Core Singleton
+ *
+ * Lazy-initialized platform instance with adapter auto-selection from env vars.
+ * Uses a promise-based lock to prevent race conditions during initialization.
+ *
+ * Usage:
+ *   import { getPlatform } from '@/lib/platform';
+ *   const platform = await getPlatform();
+ *   await platform.cache.set('key', value, 3600);
+ */
+import 'server-only';
+import { createPlatformAsync, type IPlatform } from '@digilogiclabs/platform-core';
+
+let _platform: IPlatform | null = null;
+let _initPromise: Promise<IPlatform> | null = null;
+
+/**
+ * Get or initialize the platform singleton.
+ * Adapters are selected automatically based on environment variables:
+ * - DATABASE_URL → PostgreSQL adapter
+ * - REDIS_URL → Redis cache adapter
+ * - RESEND_API_KEY → Resend email adapter
+ * Falls back to memory adapters when env vars are not set.
+ */
+export async function getPlatform(): Promise<IPlatform> {
+  if (_platform) return _platform;
+
+  if (!_initPromise) {
+    _initPromise = createPlatformAsync().then((p) => {
+      _platform = p;
+      return p;
+    });
+  }
+
+  return _initPromise;
+}

package/src/templates/shared/redis/web/lib/rate-limit-store.ts

@@ -0,0 +1,18 @@
+import 'server-only';
+import { createRedisRateLimitStore } from '@digilogiclabs/platform-core/auth';
+import type { RateLimitStore } from '@digilogiclabs/platform-core/auth';
+import { getRedisClient } from './redis';
+
+let _store: RateLimitStore | null = null;
+
+/**
+ * Returns a Redis-backed rate limit store, or undefined to fall back to in-memory.
+ * The store is created lazily on first call and reused thereafter.
+ */
+export function getRateLimitStore(): RateLimitStore | undefined {
+  if (_store) return _store;
+  const redis = getRedisClient();
+  if (!redis) return undefined; // falls back to in-memory in enforceRateLimit
+  _store = createRedisRateLimitStore(redis, { keyPrefix: 'rl:' });
+  return _store;
+}

package/src/templates/shared/redis/web/lib/redis.ts

@@ -0,0 +1,48 @@
+import 'server-only';
+
+/**
+ * Minimal Redis client interface matching ioredis.
+ * Avoids importing ioredis at type-check time (may not be installed yet).
+ */
+interface RedisClient {
+  zremrangebyscore(key: string, min: number | string, max: number | string): Promise<number>;
+  zadd(key: string, score: number, member: string): Promise<number>;
+  zcard(key: string): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<string | null>;
+  ttl(key: string): Promise<number>;
+  setex(key: string, seconds: number, value: string): Promise<string>;
+  del(...keys: string[]): Promise<number>;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+let _client: RedisClient | null = null;
+
+/**
+ * Lazy Redis client singleton.
+ * Returns null if REDIS_URL is not set or ioredis is not installed.
+ * Graceful degradation — rate limiting falls back to in-memory.
+ */
+export function getRedisClient(): RedisClient | null {
+  if (_client) return _client;
+  const url = process.env.REDIS_URL;
+  if (!url) return null;
+
+  try {
+    // Dynamic require — only loads if ioredis is installed
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Redis = require('ioredis');
+    _client = new Redis(url, {
+      keyPrefix: process.env.REDIS_KEY_PREFIX || 'app:',
+      maxRetriesPerRequest: 3,
+      lazyConnect: true,
+    }) as RedisClient;
+    _client.connect().catch(() => {});
+    return _client;
+  } catch {
+    // ioredis not installed — graceful fallback
+    return null;
+  }
+}

package/src/templates/shared/security/web/lib/api-security.ts

@@ -0,0 +1,318 @@
+/**
+ * Shared API security utilities.
+ *
+ * Built on platform-core/auth building blocks — no local reimplementations.
+ * Uses constantTimeEqual, classifyError, rate limiting, and audit from the package.
+ *
+ * Two usage patterns:
+ *   1. Wrappers: withPublicApi / withAuthenticatedApi / withAdminApi (recommended)
+ *   2. Primitives: enforceRateLimit, isAdminRequest, errorResponse (manual composition)
+ */
+import 'server-only';
+import { NextRequest, NextResponse } from 'next/server';
+import { randomUUID } from 'crypto';
+import {
+  // Security primitives
+  constantTimeEqual,
+  // Rate limiting
+  CommonRateLimits,
+  type RateLimitRule,
+  type RateLimitOptions,
+  // Next.js API helpers
+  enforceRateLimit as _enforceRateLimit,
+  errorResponse,
+  zodErrorResponse,
+  classifyError,
+} from '@digilogiclabs/platform-core/auth';
+
+// Trigger env validation on first import (fail-fast in production)
+import { config } from '@/lib/config';
+
+// Re-export for convenience in routes
+export { escapeHtml } from '@digilogiclabs/platform-core/auth';
+export { errorResponse, zodErrorResponse };
+
+// ---------------------------------------------------------------------------
+// Request ID / Correlation ID
+// ---------------------------------------------------------------------------
+
+/** Generate or extract a request ID for correlation. */
+export function getRequestId(request: NextRequest): string {
+  return request.headers.get('x-request-id') || randomUUID();
+}
+
+/**
+ * Rate-limit a request using Redis-backed store (if REDIS_URL is set)
+ * or in-memory fallback. Wraps platform-core's enforceRateLimit to
+ * automatically inject the store.
+ */
+export async function enforceRateLimit(
+  request: { headers: { get(name: string): string | null } },
+  operation: string,
+  rule: RateLimitRule,
+  options?: {
+    identifier?: string;
+    userId?: string;
+    rateLimitOptions?: RateLimitOptions;
+  }
+): Promise<Response | null> {
+  const { getRateLimitStore } = await import('@/lib/rate-limit-store');
+  const store = getRateLimitStore();
+  return _enforceRateLimit(request, operation, rule, {
+    ...options,
+    rateLimitOptions: { ...options?.rateLimitOptions, ...(store ? { store } : {}) },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Admin / Cron auth helpers
+// ---------------------------------------------------------------------------
+
+/** Extract bearer token from Authorization header. */
+function extractBearerToken(request: NextRequest): string | null {
+  const header = request.headers.get('authorization');
+  if (!header?.startsWith('Bearer ')) return null;
+  return header.slice(7);
+}
+
+/** Check if request has a valid admin bearer token (ADMIN_SECRET). Timing-safe. */
+export function isAdminRequest(request: NextRequest): boolean {
+  const secret = config.adminSecret;
+  if (!secret) return false;
+  const token = extractBearerToken(request);
+  if (!token) return false;
+  return constantTimeEqual(token, secret);
+}
+
+/** Check if request has a valid cron bearer token (CRON_SECRET). Timing-safe. */
+export function isCronRequest(request: NextRequest): boolean {
+  const secret = config.cronSecret;
+  if (!secret) return false;
+  const token = extractBearerToken(request);
+  if (!token) return false;
+  return constantTimeEqual(token, secret);
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiting presets — tune for your app's traffic patterns
+// ---------------------------------------------------------------------------
+
+/** App-specific rate limit presets. Extend or override as needed. */
+export const AppRateLimits = {
+  /** Public read endpoints */
+  publicRead: { limit: 60, windowSeconds: 60 } satisfies RateLimitRule,
+  /** Authenticated mutations */
+  authMutation: { limit: 30, windowSeconds: 60 } satisfies RateLimitRule,
+  /** Admin endpoints */
+  admin: CommonRateLimits.adminAction,
+  /** Beta code validation */
+  betaValidation: CommonRateLimits.betaValidation,
+  /** Webhook endpoints (generous — Stripe retries) */
+  webhook: { limit: 100, windowSeconds: 60 } satisfies RateLimitRule,
+} as const;
+
+// ---------------------------------------------------------------------------
+// API Wrapper Types
+// ---------------------------------------------------------------------------
+
+interface ApiWrapperConfig {
+  /** Rate limit rule (defaults to preset based on wrapper type) */
+  rateLimit?: RateLimitRule;
+  /** Operation name for rate limiting and logging */
+  operation?: string;
+}
+
+interface AuthenticatedApiContext {
+  /** The authenticated session */
+  session: { user: { id: string; email: string; roles?: string[] } };
+  /** Request correlation ID */
+  requestId: string;
+}
+
+interface PublicApiContext {
+  /** Request correlation ID */
+  requestId: string;
+}
+
+type PublicApiHandler = (request: NextRequest, context: PublicApiContext) => Promise<NextResponse>;
+
+type AuthenticatedApiHandler = (
+  request: NextRequest,
+  context: AuthenticatedApiContext
+) => Promise<NextResponse>;
+
+type AdminApiHandler = (request: NextRequest, context: PublicApiContext) => Promise<NextResponse>;
+
+type CronApiHandler = (request: NextRequest, context: PublicApiContext) => Promise<NextResponse>;
+
+// ---------------------------------------------------------------------------
+// API Wrappers — compose auth, rate limiting, error handling automatically
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a public API route with rate limiting and error handling.
+ * No authentication required.
+ *
+ * @example
+ * export const GET = withPublicApi({ operation: 'list-items' }, async (req, ctx) => {
+ *   return NextResponse.json({ items: [] });
+ * });
+ */
+export function withPublicApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: PublicApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'public';
+
+    try {
+      // Rate limiting
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.publicRead
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, { requestId });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}
+
+/**
+ * Wrap an authenticated API route with session validation, rate limiting, and error handling.
+ * Requires a valid Auth.js session.
+ *
+ * @example
+ * export const POST = withAuthenticatedApi({ operation: 'create-item' }, async (req, ctx) => {
+ *   const { session, requestId } = ctx;
+ *   return NextResponse.json({ userId: session.user.id });
+ * });
+ */
+export function withAuthenticatedApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: AuthenticatedApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'authenticated';
+
+    try {
+      // Dynamic import to avoid Edge runtime issues
+      const { auth } = await import('@/auth');
+      const session = await auth();
+
+      if (!session?.user?.id) {
+        return NextResponse.json({ error: 'Unauthorized', requestId }, { status: 401 });
+      }
+
+      // Rate limiting (per-user)
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.authMutation,
+        { userId: session.user.id }
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, {
+        session: session as AuthenticatedApiContext['session'],
+        requestId,
+      });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}
+
+/**
+ * Wrap an admin API route with Bearer token auth, rate limiting, and error handling.
+ * Requires ADMIN_SECRET Bearer token.
+ *
+ * @example
+ * export const POST = withAdminApi({ operation: 'admin-action' }, async (req, ctx) => {
+ *   return NextResponse.json({ success: true });
+ * });
+ */
+export function withAdminApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: AdminApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'admin';
+
+    try {
+      if (!isAdminRequest(request)) {
+        return NextResponse.json({ error: 'Forbidden', requestId }, { status: 403 });
+      }
+
+      // Rate limiting
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.admin
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, { requestId });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}
+
+/**
+ * Wrap a cron/scheduled API route with CRON_SECRET Bearer token auth,
+ * falling back to admin session check. Uses generous rate limits since
+ * cron jobs are server-to-server.
+ *
+ * @example
+ * export const POST = withCronApi({ operation: 'daily-digest' }, async (req, ctx) => {
+ *   // Run scheduled task...
+ *   return NextResponse.json({ processed: 42 });
+ * });
+ */
+export function withCronApi(
+  handlerConfig: ApiWrapperConfig,
+  handler: CronApiHandler
+): (request: NextRequest) => Promise<NextResponse> {
+  return async (request: NextRequest) => {
+    const requestId = getRequestId(request);
+    const operation = handlerConfig.operation || 'cron';
+
+    try {
+      // Accept CRON_SECRET Bearer token or fall back to ADMIN_SECRET
+      if (!isCronRequest(request) && !isAdminRequest(request)) {
+        return NextResponse.json({ error: 'Forbidden', requestId }, { status: 403 });
+      }
+
+      // Rate limiting (generous — cron jobs are server-to-server)
+      const rateLimited = await enforceRateLimit(
+        request,
+        operation,
+        handlerConfig.rateLimit || AppRateLimits.webhook
+      );
+      if (rateLimited) return rateLimited as NextResponse;
+
+      const response = await handler(request, { requestId });
+      response.headers.set('x-request-id', requestId);
+      return response;
+    } catch (error) {
+      const { status, body } = classifyError(error, process.env.NODE_ENV === 'development');
+      return NextResponse.json({ ...body, requestId }, { status });
+    }
+  };
+}