@nextsparkjs/core 0.1.0-beta.184 → 0.1.0-beta.186

package/templates/app/api/v1/users/[id]/route.ts

@@ -11,7 +11,7 @@ import {
   handleEntityMetadataInResponse,
   processEntityMetadata
 } from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth';
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth';
 import { z } from 'zod';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
 
@@ -24,8 +24,8 @@ const updateUserSchema = z.object({
 });
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest();
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request);
 }
 
 // GET /api/v1/users/:id - Get specific user
@@ -34,35 +34,24 @@ export const GET = withRateLimitTier(withApiLogging(async (
   { params }: { params: Promise<{ id: string }> }
 ): Promise<NextResponse> => {
   try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
+    // Authenticate using dual auth; the API-key scope is declared at the entry
+    // point, which fails closed for keys that lack it (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'users:read' });
+
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
 
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse as NextResponse;
     }
 
-    // Check required permissions - session users need admin role, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'users:read'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for user management.', 403);
-      return addCorsHeaders(response);
-    }
-
     const { id } = await params;
 
     // Validate that id is not empty
     if (!id || id.trim() === '') {
       const response = createApiError('User ID or email is required', 400, null, 'MISSING_IDENTIFIER');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // Search by ID or email
@@ -74,7 +63,7 @@ export const GET = withRateLimitTier(withApiLogging(async (
 
     if (!user) {
       const response = createApiError('User not found', 404, null, 'USER_NOT_FOUND');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // Handle metadata if requested (usando helper compartido)
@@ -82,11 +71,11 @@ export const GET = withRateLimitTier(withApiLogging(async (
     const userWithMeta = await includeEntityMetadataForSingle('user', user as { id: string }, metaParams, authResult.user!.id);
 
     const response = createApiResponse(userWithMeta);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   } catch (error) {
     console.error('Error fetching user:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'read');
 
@@ -96,35 +85,24 @@ export const PATCH = withRateLimitTier(withApiLogging(async (
   { params }: { params: Promise<{ id: string }> }
 ): Promise<NextResponse> => {
   try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
+    // Authenticate using dual auth; the API-key scope is declared at the entry
+    // point, which fails closed for keys that lack it (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'users:write' });
+
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
 
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse as NextResponse;
     }
 
-    // Check required permissions - session users need admin role, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'users:write'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for user management.', 403);
-      return addCorsHeaders(response);
-    }
-
     const { id } = await params;
 
     // Validate that id is not empty
     if (!id || id.trim() === '') {
       const response = createApiError('User ID or email is required', 400, null, 'MISSING_IDENTIFIER');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     const body = await req.json();
@@ -162,7 +140,7 @@ export const PATCH = withRateLimitTier(withApiLogging(async (
     
     if (!hasEntityFieldsToUpdate && !hasMetadataToUpdate) {
       const response = createApiError('No fields to update', 400, null, 'NO_FIELDS');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     let updatedUser;
@@ -183,7 +161,7 @@ export const PATCH = withRateLimitTier(withApiLogging(async (
 
       if (result.rows.length === 0) {
         const response = createApiError('User not found', 404, null, 'USER_NOT_FOUND');
-        return addCorsHeaders(response);
+        return addCorsHeaders(response, req);
       }
 
       updatedUser = result.rows[0];
@@ -197,7 +175,7 @@ export const PATCH = withRateLimitTier(withApiLogging(async (
 
       if (!user) {
         const response = createApiError('User not found', 404, null, 'USER_NOT_FOUND');
-        return addCorsHeaders(response);
+        return addCorsHeaders(response, req);
       }
 
       updatedUser = user;
@@ -214,16 +192,16 @@ export const PATCH = withRateLimitTier(withApiLogging(async (
     const responseData = await handleEntityMetadataInResponse('user', updatedUser as { id: string }, metadataWasProvided, authResult.user!.id);
 
     const response = createApiResponse(responseData);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   } catch (error) {
     if (error instanceof z.ZodError) {
       const response = createApiError('Validation error', 400, error.issues, 'VALIDATION_ERROR');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
     
     console.error('Error updating user:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'write');
 
@@ -233,35 +211,24 @@ export const DELETE = withRateLimitTier(withApiLogging(async (
   { params }: { params: Promise<{ id: string }> }
 ): Promise<NextResponse> => {
   try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
+    // Authenticate using dual auth; the API-key scope is declared at the entry
+    // point, which fails closed for keys that lack it (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'users:delete' });
+
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
 
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse as NextResponse;
     }
 
-    // Check required permissions - session users need admin role, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'users:delete'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for user management.', 403);
-      return addCorsHeaders(response);
-    }
-
     const { id } = await params;
 
     // Validate that id is not empty
     if (!id || id.trim() === '') {
       const response = createApiError('User ID or email is required', 400, null, 'MISSING_IDENTIFIER');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // First, get the user to check if it exists and prevent self-deletion
@@ -273,13 +240,13 @@ export const DELETE = withRateLimitTier(withApiLogging(async (
 
     if (!targetUser) {
       const response = createApiError('User not found', 404, null, 'USER_NOT_FOUND');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // Prevent self-deletion
     if ((targetUser as Record<string, unknown>).id === authResult.user!.id) {
       const response = createApiError('Cannot delete your own account via API', 403, null, 'SELF_DELETE_FORBIDDEN');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     const result = await mutateWithRLS(
@@ -290,14 +257,14 @@ export const DELETE = withRateLimitTier(withApiLogging(async (
 
     if (result.rows.length === 0) {
       const response = createApiError('User not found', 404, null, 'USER_NOT_FOUND');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     const response = createApiResponse({ deleted: true, id });
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   } catch (error) {
     console.error('Error deleting user:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'write');

package/templates/app/api/v1/users/route.ts

@@ -14,7 +14,7 @@ import {
   handleEntityMetadataInResponse,
   processEntityMetadata
 } from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth';
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth';
 import { hasAdminPermission } from '@nextsparkjs/core/lib/api/auth/permissions';
 import { z } from 'zod';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
@@ -34,21 +34,19 @@ const createUserSchema = z.object({
 
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest();
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request);
 }
 
 // GET /api/v1/users - List users with dual auth
 export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
   try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
+    // Authenticate using dual auth; the API-key scope is declared at the entry
+    // point, which fails closed for keys that lack it (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'users:read' });
+
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
 
     if (authResult.rateLimitResponse) {
@@ -58,7 +56,7 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
     // SECURITY: Only superadmins can list all users
     if (!hasAdminPermission(authResult, 'users:read')) {
       const response = createApiError('Insufficient permissions. Superadmin access required.', 403);
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     const metaParams = parseMetaParams(req);
@@ -103,25 +101,23 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
     const usersWithMeta = await includeEntityMetadata('user', users as { id: string }[], metaParams, authResult.user!.id);
 
     const response = createApiResponse(usersWithMeta, paginationMeta);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   } catch (error) {
     console.error('Error fetching users:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'read');
 
 // POST /api/v1/users - Create user with dual auth
 export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
   try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
+    // Authenticate using dual auth; the API-key scope is declared at the entry
+    // point, which fails closed for keys that lack it (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'users:write' });
+
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
+      return createAuthFailureResponse(authResult);
     }
 
     if (authResult.rateLimitResponse) {
@@ -131,7 +127,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
     // SECURITY: Only superadmins can create users
     if (!hasAdminPermission(authResult, 'users:write')) {
       const response = createApiError('Insufficient permissions. Superadmin access required.', 403);
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     const body = await req.json();
@@ -147,7 +143,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
 
     if (existingUser.length > 0) {
       const response = createApiError('Email already exists', 409, null, 'EMAIL_EXISTS');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     const newUserId = globalThis.crypto.randomUUID();
@@ -183,16 +179,16 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
     const responseData = await handleEntityMetadataInResponse('user', createdUser as { id: string }, metadataWasProvided, authResult.user!.id);
     
     const response = createApiResponse(responseData, { created: true }, 201);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   } catch (error) {
     if (error instanceof z.ZodError) {
       const response = createApiError('Validation error', 400, error.issues, 'VALIDATION_ERROR');
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
     
     console.error('Error creating user:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'write');
 

package/templates/app/dashboard/layout.tsx

@@ -3,7 +3,7 @@
 import { useAuth } from '@nextsparkjs/core/hooks/useAuth'
 import { useRouter } from 'next/navigation'
 import { useEffect, Suspense } from 'react'
-import { Loader2 } from 'lucide-react'
+import { DashboardAuthSkeleton } from '@nextsparkjs/core/components/dashboard/layouts/DashboardAuthSkeleton'
 import { DashboardProviders } from '@nextsparkjs/core/providers/DashboardProviders'
 import { DashboardTranslationPreloader } from '@nextsparkjs/core/lib/i18n/DashboardTranslationPreloader'
 import { TranslationDebugger } from '@nextsparkjs/core/utils/dev/TranslationDebugger'
@@ -35,11 +35,7 @@ function DashboardLayoutContent({ children }: { children: React.ReactNode }) {
   }, [user, isLoading, router])
 
   if (isLoading) {
-    return (
-      <div className="min-h-screen flex items-center justify-center">
-        <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
-      </div>
-    )
+    return <DashboardAuthSkeleton />
   }
 
   if (!user) {

package/templates/app/layout.ppr.tsx

@@ -55,27 +55,22 @@ export const metadata: Metadata = getMetadataOrDefault(
   defaultMetadata
 )
 
-export default function RootLayout({
+export default async function RootLayout({
   children,
 }: Readonly<{
   children: React.ReactNode
 }>) {
+  const billingHints = await getBillingResourceHints()
+
   return (
     <html lang={DEFAULT_LOCALE} suppressHydrationWarning>
       <head>
-        {(() => {
-          const hints = getBillingResourceHints()
-          return (
-            <>
-              {hints.preconnect.map((domain) => (
-                <link key={`pre-${domain}`} rel="preconnect" href={domain} />
-              ))}
-              {[...hints.preconnect, ...hints.dnsPrefetch].map((domain) => (
-                <link key={`dns-${domain}`} rel="dns-prefetch" href={domain} />
-              ))}
-            </>
-          )
-        })()}
+        {billingHints.preconnect.map((domain) => (
+          <link key={`pre-${domain}`} rel="preconnect" href={domain} />
+        ))}
+        {[...billingHints.preconnect, ...billingHints.dnsPrefetch].map((domain) => (
+          <link key={`dns-${domain}`} rel="dns-prefetch" href={domain} />
+        ))}
       </head>
       <body
         className={`${geistSans.variable} ${geistMono.variable} antialiased`}

package/templates/app/layout.tsx

@@ -5,6 +5,7 @@
  */
 
 import type { Metadata } from "next"
+import { Suspense } from "react"
 import { Geist, Geist_Mono } from "next/font/google"
 import { NextIntlClientProvider } from 'next-intl'
 import { getMessages } from 'next-intl/server'
@@ -13,11 +14,16 @@ import "./globals.css"
 import { getBillingResourceHints } from "@nextsparkjs/core/lib/billing/gateways/factory"
 import { ThemeProvider as NextThemeProvider } from "@nextsparkjs/core/providers/theme-provider"
 import { ThemeProvider as CustomThemeProvider } from "@nextsparkjs/core/lib/theme/ThemeProvider"
+import { Toaster } from "@nextsparkjs/core/components/ui/sonner"
+import { QueryProvider } from "@nextsparkjs/core/providers/query-provider"
+import { TeamProvider } from "@nextsparkjs/core/contexts/TeamContext"
+import { SubscriptionProvider } from "@nextsparkjs/core/contexts/SubscriptionContext"
 import { getUserLocale } from '@nextsparkjs/core/lib/locale'
 import { TranslationContextManager } from "@nextsparkjs/core/providers/TranslationContextManager"
+import { SessionCookieRefresher } from "@nextsparkjs/core/components/auth/SessionCookieRefresher"
 import { PluginService } from '@nextsparkjs/core/lib/services'
 import { getMetadataOrDefault } from '@nextsparkjs/core/lib/template-resolver'
-import { getDefaultThemeMode } from '@nextsparkjs/core/lib/theme/get-default-theme-mode'
+import { getThemeSettings } from '@nextsparkjs/core/lib/theme/get-default-theme-mode'
 
 const geistSans = Geist({
   variable: "--font-geist-sans",
@@ -53,24 +59,18 @@ export default async function RootLayout({
 
   const locale = await getUserLocale()
   const messages = await getMessages({ locale })
-  const defaultTheme = await getDefaultThemeMode()
+  const { defaultMode, allowUserToggle, forcedThemeRoutes } = await getThemeSettings()
+  const billingHints = await getBillingResourceHints()
 
   return (
     <html lang={locale} suppressHydrationWarning>
       <head>
-        {(() => {
-          const hints = getBillingResourceHints()
-          return (
-            <>
-              {hints.preconnect.map((domain) => (
-                <link key={`pre-${domain}`} rel="preconnect" href={domain} />
-              ))}
-              {[...hints.preconnect, ...hints.dnsPrefetch].map((domain) => (
-                <link key={`dns-${domain}`} rel="dns-prefetch" href={domain} />
-              ))}
-            </>
-          )
-        })()}
+        {billingHints.preconnect.map((domain) => (
+          <link key={`pre-${domain}`} rel="preconnect" href={domain} />
+        ))}
+        {[...billingHints.preconnect, ...billingHints.dnsPrefetch].map((domain) => (
+          <link key={`dns-${domain}`} rel="dns-prefetch" href={domain} />
+        ))}
       </head>
       <body
         className={`${geistSans.variable} ${geistMono.variable} antialiased`}
@@ -78,13 +78,33 @@ export default async function RootLayout({
         <NextIntlClientProvider locale={locale} messages={messages}>
           <NextThemeProvider
             attribute="class"
-            defaultTheme={defaultTheme}
-            enableSystem
+            defaultTheme={defaultMode}
+            // When allowUserToggle is false, force the theme and ignore localStorage/system
+            forcedTheme={!allowUserToggle ? defaultMode : undefined}
+            // Only detect OS preference when theme configures defaultMode: 'system' AND user can toggle
+            enableSystem={allowUserToggle && defaultMode === 'system'}
+            // Force a theme on the routes declared in theme.config.ts (forcedThemeRoutes)
+            forcedThemeRoutes={forcedThemeRoutes}
             disableTransitionOnChange
           >
             <CustomThemeProvider>
-              <TranslationContextManager />
-              <main>{children}</main>
+              {/* Team providers live here (not only in DashboardProviders) so the activeTeamId
+                  cookie is synced from any route, matching layout.ppr.tsx — see #115.
+                  DashboardProviders skips re-mounting them when already present. */}
+              <QueryProvider>
+                <TeamProvider>
+                  <SubscriptionProvider>
+                    <TranslationContextManager />
+                    {/* Real session-cookie renewal for installed PWAs: the render-time
+                        session reads above (getUserLocale/getThemeSettings) cannot
+                        write cookies, so the rolling refresh is triggered from the
+                        client through the auth Route Handler instead. */}
+                    <SessionCookieRefresher />
+                    <main>{children}</main>
+                    <Suspense><Toaster position="bottom-left" /></Suspense>
+                  </SubscriptionProvider>
+                </TeamProvider>
+              </QueryProvider>
             </CustomThemeProvider>
           </NextThemeProvider>
         </NextIntlClientProvider>

package/templates/contents/themes/starter/config/app.config.ts

@@ -115,6 +115,25 @@ export const APP_CONFIG_OVERRIDES = {
         enabled: false,
       },
     },
+    /**
+     * Login methods, in priority order. Core default = passwordless preset:
+     * a one-time code by email + Google, no password field (needs an email
+     * provider — RESEND_API_KEY — and GOOGLE_CLIENT_ID/SECRET for Google).
+     *
+     * Uncomment to switch to the classic email + password preset, or list both
+     * (the first email method is the form shown first):
+     */
+    // methods: ['email-password', 'google'],
+    // methods: ['email-otp', 'email-password', 'google'],
+
+    /**
+     * Session duration / renewal in seconds (defaults: 7 days, renewed daily).
+     * Long-lived sessions for an installed PWA, for example:
+     */
+    // session: {
+    //   expiresIn: 60 * 60 * 24 * 90, // 90 days
+    //   updateAge: 60 * 60 * 24 * 7,  // renew weekly
+    // },
     /**
      * Whether Better Auth automatically sends the verification email on signup.
      *

package/templates/contents/themes/starter/config/theme.config.ts

@@ -22,6 +22,12 @@ export const starterThemeConfig: ThemeConfig = {
   // ==========================================
   plugins: [],
 
+  // ==========================================
+  // THEME MODE (Optional)
+  // ==========================================
+  // defaultMode: 'system',                    // 'light' | 'dark' | 'system'
+  // forcedThemeRoutes: { '/login': 'light' }, // force a theme on route prefixes (longest wins)
+
   // ==========================================
   // STYLES CONFIGURATION
   // ==========================================

package/templates/contents/themes/starter/styles/globals.css

@@ -200,8 +200,12 @@
 /* =============================================
    BASE STYLES
    ============================================= */
-* {
-  border-color: var(--border);
+/* Must live in @layer base: un-layered rules beat every Tailwind v4 utility
+   (border-primary, border-destructive, ...) regardless of specificity. */
+@layer base {
+  * {
+    border-color: var(--border);
+  }
 }
 
 body {