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

package/templates/app/api/v1/teams/[teamId]/usage/[limitSlug]/route.ts

@@ -16,16 +16,18 @@ interface RouteParams {
 }
 
 export const GET = withRateLimitTier(async function GET(request: NextRequest, props: RouteParams) {
-  // Authenticate request
-  const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const { auth, rateLimitResponse, errorResponse } = await validateAndAuthenticateRequest(request, { requiredScope: 'billing:read' })
   if (rateLimitResponse) return rateLimitResponse
+  if (!auth) return errorResponse ?? createApiError('Authentication required', 401, undefined, 'AUTHENTICATION_REQUIRED')
 
   const { teamId, limitSlug } = await props.params
 
   try {
     // Check if user has permission to view usage using MembershipService
     const membership = await MembershipService.get(auth.userId, teamId)
-    const actionResult = membership.canPerformAction('billing.view')
+    const actionResult = membership.canPerformAction('team.billing.view')
 
     if (!actionResult.allowed) {
       return NextResponse.json(
@@ -48,16 +50,18 @@ export const GET = withRateLimitTier(async function GET(request: NextRequest, pr
 }, 'read')
 
 export const POST = withRateLimitTier(async function POST(request: NextRequest, props: RouteParams) {
-  // Authenticate request
-  const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const { auth, rateLimitResponse, errorResponse } = await validateAndAuthenticateRequest(request, { requiredScope: 'billing:write' })
   if (rateLimitResponse) return rateLimitResponse
+  if (!auth) return errorResponse ?? createApiError('Authentication required', 401, undefined, 'AUTHENTICATION_REQUIRED')
 
   const { teamId, limitSlug } = await props.params
 
   try {
     // Check if user has permission to track usage using MembershipService
     const membership = await MembershipService.get(auth.userId, teamId)
-    const actionResult = membership.canPerformAction('billing.manage')
+    const actionResult = membership.canPerformAction('team.billing.manage')
 
     if (!actionResult.allowed) {
       return NextResponse.json(

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

@@ -8,7 +8,7 @@ import {
   handleCorsPreflightRequest,
   addCorsHeaders,
 } 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 { isSuperAdmin } from '@nextsparkjs/core/lib/api/auth/permissions'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { createTeamSchema, teamListQuerySchema } from '@nextsparkjs/core/lib/teams/schema'
@@ -17,21 +17,19 @@ import type { Team } from '@nextsparkjs/core/lib/teams/types'
 import { APP_CONFIG_MERGED } from '@nextsparkjs/core/lib/config/config-sync'
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest()
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request)
 }
 
 // GET /api/v1/teams - List user's teams
 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: 'teams:read' })
 
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      )
+      return createAuthFailureResponse(authResult)
     }
 
     if (authResult.rateLimitResponse) {
@@ -62,7 +60,7 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
         'Insufficient permissions. Superadmin access required for scope=all.',
         403
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Build WHERE clause based on filters
@@ -93,7 +91,7 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
     // Add pagination params
     queryValues.push(limit, offset)
 
-    let teams: (Team & { userRole: string | null; memberCount: string })[]
+    let teams: (Team & { userRole: string | null; joinedAt?: string; memberCount: string })[]
     let totalResult: { count: string }[]
 
     if (requestAllTeams) {
@@ -122,17 +120,27 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
       )
     } else {
       // Regular user query: filter by membership
-      teams = await queryWithRLS<Team & { userRole: string; memberCount: string }>(
+      // tm."joinedAt" is unambiguous here (not an aggregation concern): the
+      // WHERE clause already pins tm."userId" = the caller, so tm is exactly
+      // this user's own membership row in each team — the same "joinedAt"
+      // dual-auth.ts's getUserDefaultTeamId() uses to pick a default team.
+      // Its absence here (never selected, even though the client sorted by
+      // it) made TeamContext's #115 fix a no-op in production: every
+      // `joinedAt` came back undefined, so `new Date(undefined).getTime()`
+      // compared NaN to NaN and the client silently kept the API's row
+      // order instead of the earliest-joined team.
+      teams = await queryWithRLS<Team & { userRole: string; joinedAt: string; memberCount: string }>(
         `SELECT
           t.*,
           tm.role as "userRole",
+          tm."joinedAt" as "joinedAt",
           COUNT(DISTINCT tm2.id) as "memberCount"
         FROM "teams" t
         INNER JOIN "team_members" tm ON t.id = tm."teamId"
         LEFT JOIN "team_members" tm2 ON t.id = tm2."teamId"
         ${whereClause}
         GROUP BY t.id, t.name, t.slug, t.description, t."ownerId", t."avatarUrl",
-                 t.settings, t.metadata, t."createdAt", t."updatedAt", tm.role
+                 t.settings, t.metadata, t."createdAt", t."updatedAt", tm.role, tm."joinedAt"
         ORDER BY ${orderByClause}
         LIMIT $${paramCount++} OFFSET $${paramCount++}`,
         queryValues,
@@ -160,25 +168,23 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
     }))
 
     const response = createApiResponse(teamsWithMembers, paginationMeta)
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   } catch (error) {
     console.error('Error fetching teams:', error)
     const response = createApiError('Internal server error', 500)
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   }
 }), 'read')
 
 // POST /api/v1/teams - Create new team
 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: 'teams:write' })
 
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      )
+      return createAuthFailureResponse(authResult)
     }
 
     if (authResult.rateLimitResponse) {
@@ -199,7 +205,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
         null,
         'TEAM_CREATION_DISABLED'
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Validate allowCreateTeams option
@@ -220,7 +226,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
           null,
           'MAX_TEAMS_REACHED'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
     }
 
@@ -228,7 +234,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
     const slugAvailable = await TeamService.isSlugAvailable(validatedData.slug)
     if (!slugAvailable) {
       const response = createApiError('Team slug already exists', 409, null, 'SLUG_EXISTS')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Use transaction to ensure atomicity
@@ -280,7 +286,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
       }
 
       const response = createApiResponse(responseData, { created: true }, 201)
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     } catch (error) {
       await tx.rollback()
       throw error
@@ -289,11 +295,11 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
     if (error instanceof Error && error.name === 'ZodError') {
       const zodError = error as { issues?: unknown[] }
       const response = createApiError('Validation error', 400, zodError.issues, 'VALIDATION_ERROR')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     console.error('Error creating team:', error)
     const response = createApiError('Internal server error', 500)
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   }
 }), 'write')

package/templates/app/api/v1/teams/switch/route.ts

@@ -6,7 +6,7 @@ import {
   handleCorsPreflightRequest,
   addCorsHeaders,
 } 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 { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { TeamService } from '@nextsparkjs/core/lib/services'
 import { z } from 'zod'
@@ -16,21 +16,19 @@ const switchTeamSchema = z.object({
 })
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest()
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request)
 }
 
 // POST /api/v1/teams/switch - Switch active team context
 export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
   try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req)
+    // Authenticate using dual auth. Only teams:read: this endpoint changes
+    // which team the caller sees, it never writes team data (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'teams:read' })
 
     if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      )
+      return createAuthFailureResponse(authResult)
     }
 
     if (authResult.rateLimitResponse) {
@@ -61,7 +59,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
         maxAge: 60 * 60 * 24 * 365  // 1 year
       })
 
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     } catch (error) {
       if (error instanceof Error && error.message === 'User is not a member of this team') {
         const response = createApiError(
@@ -70,7 +68,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
           null,
           'NOT_TEAM_MEMBER'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       throw error
@@ -79,11 +77,11 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
     if (error instanceof Error && error.name === 'ZodError') {
       const zodError = error as { issues?: unknown[] }
       const response = createApiError('Validation error', 400, zodError.issues, 'VALIDATION_ERROR')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     console.error('Error switching team:', error)
     const response = createApiError('Internal server error', 500)
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   }
 }), 'write')

package/templates/app/api/v1/theme/[...path]/route.ts

@@ -12,6 +12,7 @@ import {
   type ThemeRegistryEntry
 } from '@nextsparkjs/registries/theme-registry'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { validateAndAuthenticateRequest } from '@nextsparkjs/core/lib/api/helpers'
 
 export const GET = withRateLimitTier(async (
   request: NextRequest,
@@ -111,6 +112,12 @@ async function handleThemeRequest(
       console.log(`[Theme API] No route found for ${requestPath}, method: ${method}`)
     }
 
+    // The endpoint catalog is only disclosed to authenticated callers.
+    // Anonymous requests still get theme info / 404, but never the route map.
+    const endpointCatalog = (await isAuthenticatedRequest(request))
+      ? { availableEndpoints: getThemeEndpoints(themeName) }
+      : {}
+
     // Default theme info endpoint
     if (!endpointPath && method === 'GET') {
       return NextResponse.json({
@@ -124,7 +131,7 @@ async function handleThemeRequest(
           entities: themeEntry.entities?.length || 0,
           routeFiles: themeEntry.routeFiles?.length || 0,
           plugins: themeEntry.plugins || [],
-          availableEndpoints: getThemeEndpoints(themeName)
+          ...endpointCatalog
         }
       })
     }
@@ -136,7 +143,7 @@ async function handleThemeRequest(
         theme: themeName,
         path: endpointPath,
         method,
-        availableEndpoints: getThemeEndpoints(themeName)
+        ...endpointCatalog
       },
       { status: 404 }
     )
@@ -154,6 +161,20 @@ async function handleThemeRequest(
   }
 }
 
+/**
+ * Check whether the request carries a valid session or API key.
+ * Used to gate the endpoint catalog (see #104 / #109): the list of registered
+ * theme routes must not be enumerable by anonymous callers.
+ */
+async function isAuthenticatedRequest(request: NextRequest): Promise<boolean> {
+  try {
+    const { auth, rateLimitResponse } = await validateAndAuthenticateRequest(request)
+    return !rateLimitResponse && Boolean(auth?.userId)
+  } catch {
+    return false
+  }
+}
+
 /**
  * Match route pattern with dynamic parameters
  * Example: 'orders/[orderId]/items' matches 'orders/123/items'

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

@@ -28,7 +28,7 @@ import {
   handleCorsPreflightRequest,
   addCorsHeaders,
 } 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'
 
@@ -41,8 +41,8 @@ const metadataValueSchema = z.object({
 })
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest()
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request)
 }
 
 /**
@@ -62,44 +62,29 @@ export const GET = withRateLimitTier(withApiLogging(async (
   { params }: { params: Promise<{ id: string; key: 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 || !authResult.user) {
-      return NextResponse.json(
-        createApiError('Authentication required', 401, null, 'AUTHENTICATION_FAILED'),
-        { status: 401 }
-      )
+      return createAuthFailureResponse(authResult)
     }
 
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse as NextResponse
     }
 
-    // Check required permissions
-    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 metadata.',
-        403
-      )
-      return addCorsHeaders(response)
-    }
-
     const { id, key } = await params
 
     // Validate parameters
     if (!id || id.trim() === '') {
       const response = createApiError('User ID is required', 400, null, 'MISSING_USER_ID')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     if (!key || key.trim() === '') {
       const response = createApiError('Metadata key is required', 400, null, 'MISSING_META_KEY')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Validate key length
@@ -110,7 +95,7 @@ export const GET = withRateLimitTier(withApiLogging(async (
         null,
         'INVALID_META_KEY'
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Get user metadata value using UserService
@@ -126,14 +111,14 @@ export const GET = withRateLimitTier(withApiLogging(async (
       key,
       value: metaValue ?? null,
     })
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   } catch (error) {
     const response = createApiError(
       'Failed to fetch user metadata',
       500,
       error instanceof Error ? error.message : undefined
     )
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   }
 }), 'read');
 
@@ -159,44 +144,29 @@ export const PUT = withRateLimitTier(withApiLogging(async (
   { params }: { params: Promise<{ id: string; key: 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 || !authResult.user) {
-      return NextResponse.json(
-        createApiError('Authentication required', 401, null, 'AUTHENTICATION_FAILED'),
-        { status: 401 }
-      )
+      return createAuthFailureResponse(authResult)
     }
 
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse as NextResponse
     }
 
-    // Check required permissions
-    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 metadata.',
-        403
-      )
-      return addCorsHeaders(response)
-    }
-
     const { id, key } = await params
 
     // Validate parameters
     if (!id || id.trim() === '') {
       const response = createApiError('User ID is required', 400, null, 'MISSING_USER_ID')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     if (!key || key.trim() === '') {
       const response = createApiError('Metadata key is required', 400, null, 'MISSING_META_KEY')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Validate key length
@@ -207,7 +177,7 @@ export const PUT = withRateLimitTier(withApiLogging(async (
         null,
         'INVALID_META_KEY'
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Parse and validate request body
@@ -223,7 +193,7 @@ export const PUT = withRateLimitTier(withApiLogging(async (
         null,
         'VALUE_TOO_LARGE'
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Update metadata using UserService
@@ -245,7 +215,7 @@ export const PUT = withRateLimitTier(withApiLogging(async (
       value: validatedData.value,
       updated: true,
     })
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   } catch (error) {
     // Handle validation errors
     if (error instanceof z.ZodError) {
@@ -255,7 +225,7 @@ export const PUT = withRateLimitTier(withApiLogging(async (
         error.issues,
         'VALIDATION_ERROR'
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     const response = createApiError(
@@ -263,7 +233,7 @@ export const PUT = withRateLimitTier(withApiLogging(async (
       500,
       error instanceof Error ? error.message : undefined
     )
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   }
 }), 'write');
 
@@ -287,44 +257,29 @@ export const DELETE = withRateLimitTier(withApiLogging(async (
   { params }: { params: Promise<{ id: string; key: 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 || !authResult.user) {
-      return NextResponse.json(
-        createApiError('Authentication required', 401, null, 'AUTHENTICATION_FAILED'),
-        { status: 401 }
-      )
+      return createAuthFailureResponse(authResult)
     }
 
     if (authResult.rateLimitResponse) {
       return authResult.rateLimitResponse as NextResponse
     }
 
-    // Check required permissions
-    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 metadata.',
-        403
-      )
-      return addCorsHeaders(response)
-    }
-
     const { id, key } = await params
 
     // Validate parameters
     if (!id || id.trim() === '') {
       const response = createApiError('User ID is required', 400, null, 'MISSING_USER_ID')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     if (!key || key.trim() === '') {
       const response = createApiError('Metadata key is required', 400, null, 'MISSING_META_KEY')
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Validate key length
@@ -335,7 +290,7 @@ export const DELETE = withRateLimitTier(withApiLogging(async (
         null,
         'INVALID_META_KEY'
       )
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
 
     // Delete metadata using UserService
@@ -346,13 +301,13 @@ export const DELETE = withRateLimitTier(withApiLogging(async (
       key,
       deleted: true,
     })
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   } catch (error) {
     const response = createApiError(
       'Failed to delete user metadata',
       500,
       error instanceof Error ? error.message : undefined
     )
-    return addCorsHeaders(response)
+    return addCorsHeaders(response, req)
   }
 }), 'write');