@digilogiclabs/create-saas-app 2.0.0 → 2.2.0

package/dist/templates/shared/auth/keycloak/web/app/api/auth/federated-logout/route.ts

@@ -0,0 +1,173 @@
+/**
+ * Federated Logout Route
+ *
+ * Handles proper logout from both Auth.js and Keycloak.
+ * Ensures the Keycloak session is cleared so users aren't auto-logged-in
+ * when they try to sign in again.
+ *
+ * Flow:
+ * 1. Get the id_token from the Auth.js session
+ * 2. Return an HTML page with Set-Cookie headers to clear all auth cookies
+ * 3. The HTML page auto-redirects to Keycloak's logout endpoint
+ * 4. Keycloak clears its session and redirects back to the app
+ *
+ * Returns HTML (200) instead of 307 redirect because browsers may not
+ * reliably process Set-Cookie headers on redirect responses.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { auth } from '@/auth';
+import { getToken } from 'next-auth/jwt';
+
+/** Serialize a Set-Cookie header string for cookie deletion. */
+function expireCookie(
+  name: string,
+  options?: { domain?: string; secure?: boolean; hostPrefix?: boolean }
+): string {
+  const parts = [
+    `${name}=`,
+    'Path=/',
+    'Expires=Thu, 01 Jan 1970 00:00:00 GMT',
+    'Max-Age=0',
+    'SameSite=Lax',
+  ];
+  if (options?.hostPrefix) {
+    parts.push('Secure');
+  } else {
+    parts.push('HttpOnly');
+    if (options?.domain) parts.push(`Domain=${options.domain}`);
+    if (options?.secure) parts.push('Secure');
+  }
+  return parts.join('; ');
+}
+
+/** Validate callback URL to prevent open redirect attacks. */
+function isAllowedCallbackUrl(url: string, baseUrl: string): boolean {
+  if (url.startsWith('/') && !url.startsWith('//')) return true;
+  try {
+    const parsed = new URL(url);
+    const base = new URL(baseUrl);
+    const allowedHosts = [base.hostname, `www.${base.hostname}`];
+    if (base.hostname.startsWith('www.')) {
+      allowedHosts.push(base.hostname.slice(4));
+    }
+    return allowedHosts.includes(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export async function GET(request: NextRequest) {
+  const session = await auth();
+  const searchParams = request.nextUrl.searchParams;
+  const rawCallbackUrl = searchParams.get('callbackUrl') || '/';
+  const queryIdToken = searchParams.get('id_token_hint');
+
+  const baseUrl = process.env.NEXTAUTH_URL || process.env.AUTH_URL || 'http://localhost:3000';
+  const callbackUrl = isAllowedCallbackUrl(rawCallbackUrl, baseUrl) ? rawCallbackUrl : '/';
+  const postLogoutRedirectUri = callbackUrl.startsWith('http')
+    ? callbackUrl
+    : `${baseUrl}${callbackUrl}`;
+
+  const keycloakIssuer = process.env.AUTH_KEYCLOAK_ISSUER;
+  if (!keycloakIssuer) {
+    console.error('[Federated Logout] Missing AUTH_KEYCLOAK_ISSUER');
+    return NextResponse.redirect(
+      new URL('/api/auth/signout?callbackUrl=' + encodeURIComponent(callbackUrl), request.url)
+    );
+  }
+
+  // Revoke refresh token (best-effort)
+  const jwtToken = await getToken({ req: request });
+  const refreshToken = jwtToken?.refreshToken as string | undefined;
+  if (refreshToken) {
+    try {
+      await fetch(`${keycloakIssuer}/protocol/openid-connect/revoke`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+          token: refreshToken,
+          token_type_hint: 'refresh_token',
+          ...(process.env.AUTH_KEYCLOAK_ID && { client_id: process.env.AUTH_KEYCLOAK_ID }),
+          ...(process.env.AUTH_KEYCLOAK_SECRET && {
+            client_secret: process.env.AUTH_KEYCLOAK_SECRET,
+          }),
+        }),
+      });
+    } catch {
+      // Best-effort — don't block logout
+    }
+  }
+
+  // Build Keycloak logout URL
+  const logoutUrl = new URL(`${keycloakIssuer}/protocol/openid-connect/logout`);
+  logoutUrl.searchParams.set('post_logout_redirect_uri', postLogoutRedirectUri);
+  if (process.env.AUTH_KEYCLOAK_ID) {
+    logoutUrl.searchParams.set('client_id', process.env.AUTH_KEYCLOAK_ID);
+  }
+  const idToken = session?.idToken || queryIdToken;
+  if (idToken) {
+    logoutUrl.searchParams.set('id_token_hint', idToken);
+  }
+
+  const escapedUrl = logoutUrl
+    .toString()
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+
+  const html = `<!DOCTYPE html>
+<html><head>
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0;url=${escapedUrl}">
+<title>Signing out...</title>
+<style>body{display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;font-family:system-ui,sans-serif;background:#0a0a0a;color:#fff}p{font-size:1.1rem;opacity:0.7}</style>
+</head><body>
+<p>Signing out&hellip;</p>
+<script>window.location.replace(${JSON.stringify(logoutUrl.toString()).replace(/</g, '\\u003c')});</script>
+</body></html>`;
+
+  const response = new NextResponse(html, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store, no-cache, must-revalidate',
+      Pragma: 'no-cache',
+    },
+  });
+
+  // Clear ALL Auth.js cookie variants
+  const isProduction = process.env.NODE_ENV === 'production';
+  const cookieNames = [
+    'authjs.session-token',
+    '__Secure-authjs.session-token',
+    'authjs.callback-url',
+    '__Secure-authjs.callback-url',
+    'authjs.csrf-token',
+    '__Secure-authjs.csrf-token',
+    'authjs.pkce.code_verifier',
+    '__Secure-authjs.pkce.code_verifier',
+    'authjs.state',
+    '__Secure-authjs.state',
+    // Legacy next-auth names
+    'next-auth.session-token',
+    '__Secure-next-auth.session-token',
+    'next-auth.callback-url',
+    '__Secure-next-auth.callback-url',
+    'next-auth.csrf-token',
+    '__Secure-next-auth.csrf-token',
+  ];
+
+  for (const name of cookieNames) {
+    const needsSecure = isProduction || name.startsWith('__Secure-');
+    response.headers.append('Set-Cookie', expireCookie(name, { secure: needsSecure }));
+  }
+
+  // __Host- prefix cookies
+  for (const name of ['__Host-authjs.csrf-token', '__Host-next-auth.csrf-token']) {
+    response.headers.append('Set-Cookie', expireCookie(name, { hostPrefix: true }));
+  }
+
+  return response;
+}

package/dist/templates/shared/auth/keycloak/web/auth.config.ts

@@ -0,0 +1,84 @@
+/**
+ * Auth.js Base Configuration (Edge-compatible)
+ *
+ * This file contains ONLY Edge-runtime-compatible configuration.
+ * It is imported by middleware.ts for Edge middleware auth.
+ *
+ * Server-only code (database sync, events) lives in auth.ts which
+ * extends this config. API routes and server components use auth.ts.
+ *
+ * IMPORTANT: Do NOT add any imports of server-only modules here
+ * (ioredis, pg, nodemailer, platform-core barrel, etc.)
+ */
+
+import Keycloak from 'next-auth/providers/keycloak';
+import type { NextAuthConfig } from 'next-auth';
+import {
+  buildKeycloakCallbacks,
+  buildAuthCookies,
+  buildRedirectCallback,
+} from '@digilogiclabs/platform-core/auth';
+
+// Extend the built-in session types
+declare module 'next-auth' {
+  interface Session {
+    user: {
+      id: string;
+      email?: string | null;
+      name?: string | null;
+      image?: string | null;
+      roles?: string[]; // Keycloak realm roles
+    };
+    idToken?: string; // For federated logout
+    accessToken?: string; // For API calls
+    // refreshToken intentionally NOT exposed to client — used server-side only via getToken()
+    error?: string; // Token refresh error — client should re-authenticate
+  }
+}
+
+/** Keycloak callbacks — JWT token storage, role parsing, automatic refresh, session mapping */
+const keycloakCallbacks = buildKeycloakCallbacks({
+  issuer: process.env.AUTH_KEYCLOAK_ISSUER!,
+  clientId: process.env.AUTH_KEYCLOAK_ID!,
+  clientSecret: process.env.AUTH_KEYCLOAK_SECRET!,
+});
+
+export const authConfig: NextAuthConfig = {
+  // Trust the host in production (required for Auth.js v5 behind reverse proxy)
+  trustHost: true,
+
+  // Cookie configuration for cross-domain OIDC (www/non-www compatibility).
+  // csrfToken uses __Host- prefix which CANNOT have a Domain attribute.
+  // The federated-logout route handles clearing all cookie variants.
+  cookies: buildAuthCookies(),
+
+  providers: [
+    Keycloak({
+      clientId: process.env.AUTH_KEYCLOAK_ID!,
+      clientSecret: process.env.AUTH_KEYCLOAK_SECRET!,
+      issuer: process.env.AUTH_KEYCLOAK_ISSUER!,
+    }),
+  ],
+
+  session: {
+    strategy: 'jwt',
+    maxAge: 30 * 24 * 60 * 60, // 30 days
+  },
+
+  callbacks: {
+    ...keycloakCallbacks,
+
+    async signIn() {
+      return true;
+    },
+
+    redirect: buildRedirectCallback(),
+  },
+
+  pages: {
+    signIn: '/auth/signin',
+    error: '/auth/signin',
+  },
+
+  debug: process.env.NODE_ENV === 'development',
+};

package/dist/templates/shared/auth/keycloak/web/auth.ts

@@ -0,0 +1,26 @@
+/**
+ * Auth.js Server Configuration
+ *
+ * Extends the Edge-compatible auth.config.ts with server-only features
+ * (database sync, events, etc.). This file is used by API routes and
+ * server components.
+ *
+ * Middleware uses auth.config.ts directly (Edge-compatible).
+ */
+
+import NextAuth from 'next-auth';
+import { authConfig } from './auth.config';
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  ...authConfig,
+
+  // Server-only events — add database sync, audit logging, etc.
+  events: {
+    async signIn({ user }) {
+      // Optional: sync user to your database on sign-in
+      // const db = await getDatabase();
+      // await db.upsert('users', { id: user.id, email: user.email, name: user.name });
+      console.log(`[Auth] User signed in: ${user.email}`);
+    },
+  },
+});

package/dist/templates/shared/beta/web/app/api/beta-settings/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * GET /api/beta-settings
+ *
+ * Returns beta mode configuration. Controlled via environment variables:
+ *   BETA_MODE           - 'true'/'false' (default: true)
+ *   REQUIRE_INVITE_CODE - 'true'/'false' (default: true)
+ *   BETA_MESSAGE        - Custom message shown to users
+ */
+export async function GET() {
+  const betaMode = process.env.BETA_MODE !== 'false';
+  const requireInviteCode = process.env.REQUIRE_INVITE_CODE !== 'false';
+  const betaMessage =
+    process.env.BETA_MESSAGE ||
+    'We are currently in private beta. Enter your invite code to continue.';
+
+  return NextResponse.json({
+    betaMode,
+    requireInviteCode,
+    betaMessage,
+  });
+}

package/dist/templates/shared/beta/web/app/api/validate-beta-code/route.ts

@@ -0,0 +1,67 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { enforceRateLimit, CommonRateLimits } from '@digilogiclabs/platform-core/auth';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * POST /api/validate-beta-code
+ *
+ * Validates a beta invite code against environment-defined codes.
+ * Rate limited to 5/min with 5-minute block to prevent brute force.
+ *
+ * Env vars:
+ *   BETA_CODES - Comma-separated list of valid codes (e.g. "CODE1,CODE2")
+ */
+export async function POST(request: NextRequest) {
+  // Rate limit: 5 attempts per minute, 5-minute block on exceed
+  const rateLimitResult = await enforceRateLimit(
+    request,
+    'validate-beta-code',
+    CommonRateLimits.betaValidation
+  );
+  if (rateLimitResult) return rateLimitResult;
+
+  try {
+    const body = await request.json();
+    const { code } = body;
+
+    if (!code || typeof code !== 'string') {
+      return NextResponse.json({ valid: false, message: 'Invalid code format' });
+    }
+
+    const normalizedCode = code.trim().toUpperCase();
+
+    if (normalizedCode.length < 3) {
+      return NextResponse.json({
+        valid: false,
+        message: 'Code must be at least 3 characters',
+      });
+    }
+
+    // Get valid codes from environment
+    const validCodesEnv = process.env.BETA_CODES || '';
+    const validCodes = validCodesEnv
+      .split(',')
+      .map((c) => c.trim().toUpperCase())
+      .filter(Boolean);
+
+    const allValidCodes = new Set(validCodes);
+
+    if (allValidCodes.has(normalizedCode)) {
+      return NextResponse.json({
+        valid: true,
+        message: 'Welcome to the beta! You can now continue.',
+      });
+    }
+
+    return NextResponse.json({
+      valid: false,
+      message: 'Invalid invite code. Please check your code and try again.',
+    });
+  } catch {
+    return NextResponse.json(
+      { valid: false, message: 'Unable to validate code. Please try again.' },
+      { status: 500 }
+    );
+  }
+}

package/dist/templates/shared/beta/web/lib/beta/settings.ts

@@ -0,0 +1,31 @@
+/**
+ * Beta Gate Client — thin wrapper over platform-core's createBetaClient.
+ *
+ * Pattern: each app provides its own config (endpoints, storage key,
+ * fail-safe defaults). The client handles all fetch/validate/store logic.
+ *
+ * Usage in components:
+ *   import { fetchBetaSettings, validateInviteCode, storeBetaCode } from '@/lib/beta/settings'
+ */
+import { createBetaClient, type BetaClientConfig } from '@digilogiclabs/platform-core/auth';
+
+export type { BetaSettings } from '@digilogiclabs/platform-core';
+
+const betaConfig: BetaClientConfig = {
+  storageKey: 'app_beta_code',
+  settingsEndpoint: '/api/beta-settings',
+  validateEndpoint: '/api/validate-beta-code',
+  failSafeDefaults: {
+    betaMode: true,
+    requireInviteCode: true,
+    betaMessage: 'We are currently in private beta. Enter your invite code to continue.',
+  },
+};
+
+const betaClient = createBetaClient(betaConfig);
+
+export const fetchBetaSettings = betaClient.fetchSettings;
+export const validateInviteCode = betaClient.validateCode;
+export const storeBetaCode = betaClient.storeCode;
+export const getStoredBetaCode = betaClient.getStoredCode;
+export const clearStoredBetaCode = betaClient.clearStoredCode;

package/dist/templates/shared/cache/web/lib/cache.ts

@@ -0,0 +1,44 @@
+/**
+ * Cache utilities — TTL presets and HTTP cache header helpers.
+ *
+ * Provides standardized cache durations and response header generation
+ * for CDN and browser caching.
+ */
+
+/** Standard cache TTL presets (in seconds) */
+export const CacheTTL = {
+  /** 5 minutes — frequently changing data */
+  SHORT: 300,
+  /** 1 hour — moderately stable data */
+  MEDIUM: 3600,
+  /** 6 hours — mostly stable data */
+  LONG: 21600,
+  /** 24 hours — rarely changing data */
+  DAY: 86400,
+  /** 7 days — static content */
+  WEEK: 604800,
+} as const;
+
+/**
+ * Generate HTTP cache headers for API responses.
+ *
+ * Returns an object suitable for NextResponse headers or Response init.
+ * Supports CDN-specific headers for Cloudflare, Vercel, and standard proxies.
+ *
+ * @param ttl - Cache duration in seconds
+ * @param revalidate - Stale-while-revalidate window in seconds (default: ttl)
+ */
+export function getCacheHeaders(ttl: number, revalidate?: number): Record<string, string> {
+  const swr = revalidate ?? ttl;
+  return {
+    'Cache-Control': `public, s-maxage=${ttl}, stale-while-revalidate=${swr}`,
+    'CDN-Cache-Control': `public, s-maxage=${ttl}, stale-while-revalidate=${swr}`,
+    'Vercel-CDN-Cache-Control': `public, s-maxage=${ttl}, stale-while-revalidate=${swr}`,
+  };
+}
+
+/** No-cache headers — prevent all caching */
+export const NO_CACHE_HEADERS: Record<string, string> = {
+  'Cache-Control': 'no-store, no-cache, must-revalidate',
+  Pragma: 'no-cache',
+};

package/dist/templates/shared/config/web/lib/config.ts

@@ -0,0 +1,112 @@
+/**
+ * Centralized environment configuration — fail fast on missing secrets.
+ *
+ * Uses platform-core/auth helpers (getRequiredEnv, getOptionalEnv, checkEnvVars)
+ * so the app crashes immediately on deploy if critical env vars are missing,
+ * rather than failing silently at runtime when a request hits an unset secret.
+ *
+ * Skipped during build (NEXT_PHASE=phase-production-build) since env
+ * vars aren't available at build time in Docker/Nixpacks builds.
+ *
+ * Import this module from any server-side code to get validated, typed
+ * access to environment variables.
+ */
+import 'server-only';
+import { getRequiredEnv, getOptionalEnv, checkEnvVars } from '@digilogiclabs/platform-core/auth';
+
+// ---------------------------------------------------------------------------
+// Startup validation — runs once on first import
+// ---------------------------------------------------------------------------
+
+const isBuildPhase = process.env.NEXT_PHASE === 'phase-production-build';
+
+if (!isBuildPhase) {
+  const envResult = checkEnvVars({
+    required: ['AUTH_KEYCLOAK_ID', 'AUTH_KEYCLOAK_SECRET', 'AUTH_KEYCLOAK_ISSUER', 'AUTH_SECRET'],
+  });
+
+  if (!envResult.valid) {
+    console.error('[App] Missing required environment variables:', envResult.missing);
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error(`Missing required environment variables: ${envResult.missing.join(', ')}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Centralized config — typed access to all env vars used across the app
+// ---------------------------------------------------------------------------
+
+/**
+ * Lazy config that reads env vars on first property access.
+ * Required vars use getRequiredEnv (throws if missing).
+ * Optional vars use getOptionalEnv (returns default).
+ *
+ * NOTE: Auth vars (AUTH_KEYCLOAK_*) are intentionally omitted here because
+ * auth.config.ts reads them at module scope for NextAuth configuration, and
+ * that file cannot import server-only modules.
+ */
+export const config = {
+  /** Admin bearer token for protected API routes. */
+  get adminSecret(): string | undefined {
+    return process.env.ADMIN_SECRET;
+  },
+  /** Cron job bearer token. */
+  get cronSecret(): string | undefined {
+    return process.env.CRON_SECRET;
+  },
+  db: {
+    /** Database connection string. */
+    get url(): string {
+      return getRequiredEnv('DATABASE_URL');
+    },
+  },
+  redis: {
+    /** Redis connection URL. */
+    get url(): string | undefined {
+      return process.env.REDIS_URL;
+    },
+    /** Redis key prefix for namespace isolation. */
+    get keyPrefix(): string {
+      return getOptionalEnv('REDIS_KEY_PREFIX', 'app:');
+    },
+  },
+  email: {
+    /** Resend API key. */
+    get apiKey(): string | undefined {
+      return process.env.RESEND_API_KEY;
+    },
+    /** Sender address. */
+    get from(): string {
+      return getOptionalEnv('EMAIL_FROM', 'noreply@example.com');
+    },
+  },
+  stripe: {
+    /** Stripe secret key. */
+    get secretKey(): string {
+      return getRequiredEnv('STRIPE_SECRET_KEY');
+    },
+    /** Stripe webhook secret. */
+    get webhookSecret(): string {
+      return getRequiredEnv('STRIPE_WEBHOOK_SECRET');
+    },
+  },
+  /** Base URL for the app (used in email links, redirects). */
+  get baseUrl(): string {
+    return getOptionalEnv('NEXT_PUBLIC_APP_URL', 'http://localhost:3000');
+  },
+  /** App name. */
+  get appName(): string {
+    return getOptionalEnv('NEXT_PUBLIC_APP_NAME', 'My App');
+  },
+  beta: {
+    /** Master beta mode toggle. Default: true (closed beta). */
+    get mode(): boolean {
+      return process.env.BETA_MODE !== 'false';
+    },
+    /** Require invite code for signup. Default: true. */
+    get requireInviteCode(): boolean {
+      return process.env.REQUIRE_INVITE_CODE !== 'false';
+    },
+  },
+} as const;

package/dist/templates/shared/config/web/next.config.mjs

@@ -0,0 +1,62 @@
+import { generateSecurityHeaders } from '@digilogiclabs/platform-core/security-headers';
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',
+
+  // Security headers — CSP, HSTS, X-Frame-Options, etc.
+  async headers() {
+    const keycloakIssuer = process.env.AUTH_KEYCLOAK_ISSUER || '';
+    const keycloakOrigin = keycloakIssuer ? new URL(keycloakIssuer).origin : '';
+
+    return generateSecurityHeaders({
+      cspConnectSrc: [
+        keycloakOrigin,
+        'https://api.stripe.com',
+      ].filter(Boolean),
+      cspFrameSrc: [
+        keycloakOrigin,
+        'https://js.stripe.com',
+        'https://hooks.stripe.com',
+      ].filter(Boolean),
+      cspScriptSrc: ['https://js.stripe.com'],
+      cspImgSrc: ['https://lh3.googleusercontent.com'],
+    });
+  },
+
+  webpack: (config, { isServer }) => {
+    // Stub server-only packages for client bundles.
+    // Use $ anchor to match exact package name — preserves subpath imports
+    // like @digilogiclabs/platform-core/auth (Edge-safe).
+    if (!isServer) {
+      config.resolve.fallback = {
+        ...config.resolve.fallback,
+        fs: false,
+        net: false,
+        tls: false,
+        dns: false,
+        child_process: false,
+        'node:stream': false,
+        'node:buffer': false,
+        'node:util': false,
+        'node:events': false,
+        'node:process': false,
+      };
+
+      config.resolve.alias = {
+        ...config.resolve.alias,
+        // Stub main barrel only — subpaths like /auth and /security-headers
+        // are Edge-safe and must NOT be stubbed.
+        '@digilogiclabs/platform-core$': false,
+        'ioredis$': false,
+        'pg$': false,
+        'nodemailer$': false,
+        'bullmq$': false,
+      };
+    }
+
+    return config;
+  },
+};
+
+export default nextConfig;