@nextsparkjs/core 0.1.0-beta.185 → 0.1.0-beta.187

package/dist/templates/app/api/v1/api-keys/route.ts

@@ -7,7 +7,7 @@ import {
   handleCorsPreflightRequest,
   addCorsHeaders
 } from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest, hasRequiredScope, resolveTeamContext } from '@nextsparkjs/core/lib/api/auth/dual-auth';
+import { authenticateRequest, createAuthFailureResponse, resolveTeamContext } from '@nextsparkjs/core/lib/api/auth/dual-auth';
 import { ApiKeyManager, API_SCOPES, API_KEY_LIMITS } from '@nextsparkjs/core/lib/api/keys';
 import { validateScopesForUser } from '@nextsparkjs/core/lib/api/auth';
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit';
@@ -20,36 +20,25 @@ const createApiKeySchema = z.object({
 });
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest();
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request);
 }
 
 // GET /api/v1/api-keys - List user's API keys 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. Session users have admin access; API keys
+    // need the scope declared here, enforced at the entry point (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'admin:api-keys' });
+
     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 have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
     const apiKeys = await queryWithRLS<{
       id: string;
       keyPrefix: string;
@@ -125,40 +114,29 @@ export const GET = withRateLimitTier(withApiLogging(async (req: NextRequest): Pr
     }));
 
     const response = createApiResponse(keysWithStats);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   } catch (error) {
     console.error('Error fetching API keys:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'strict');
 
 // POST /api/v1/api-keys - Create new API key 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. Session users have admin access; API keys
+    // need the scope declared here, enforced at the entry point (#93).
+    const authResult = await authenticateRequest(req, { requiredScope: 'admin:api-keys' });
+
     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 have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
     const body = await req.json();
     const validatedData = createApiKeySchema.parse(body);
 
@@ -174,7 +152,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
         },
         'INVALID_SCOPES'
       );
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // Validar que el usuario pueda crear API keys con estos scopes.
@@ -201,7 +179,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
         },
         'INSUFFICIENT_SCOPE_PERMISSIONS'
       );
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // Verificar límite de API keys por usuario (máximo 10)
@@ -218,7 +196,7 @@ export const POST = withRateLimitTier(withApiLogging(async (req: NextRequest): P
         null,
         'API_KEY_LIMIT_REACHED'
       );
-      return addCorsHeaders(response);
+      return addCorsHeaders(response, req);
     }
 
     // Generar API key
@@ -249,15 +227,15 @@ 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) {
     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 API key:', error);
     const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
+    return addCorsHeaders(response, req);
   }
 }), 'strict');

package/dist/templates/app/api/v1/auth/signup-with-invite/route.ts

@@ -14,8 +14,8 @@ import { withSignupContext } from '@nextsparkjs/core/lib/auth-context'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest()
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request)
 }
 
 interface SignupWithInviteBody {
@@ -41,14 +41,14 @@ export const POST = withRateLimitTier(withApiLogging(
           null,
           'MISSING_FIELDS'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Validate email format
       const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
       if (!emailRegex.test(email)) {
         const response = createApiError('Invalid email format', 400, null, 'INVALID_EMAIL')
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Validate password length (min 8 characters as per Better Auth config)
@@ -59,7 +59,7 @@ export const POST = withRateLimitTier(withApiLogging(
           null,
           'INVALID_PASSWORD'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Step 1: Validate the invitation token via the service pool (RLS bypass).
@@ -76,7 +76,7 @@ export const POST = withRateLimitTier(withApiLogging(
 
       if (!invitation) {
         const response = createApiError('Invitation not found', 404, null, 'INVITATION_NOT_FOUND')
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Verify invitation is for the correct email
@@ -87,7 +87,7 @@ export const POST = withRateLimitTier(withApiLogging(
           null,
           'EMAIL_MISMATCH'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Check if invitation is pending
@@ -98,14 +98,14 @@ export const POST = withRateLimitTier(withApiLogging(
           null,
           'INVITATION_NOT_PENDING'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Check if invitation has expired
       const expiresAt = new Date(invitation.expiresAt)
       if (expiresAt < new Date()) {
         const response = createApiError('Invitation has expired', 410, null, 'INVITATION_EXPIRED')
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Step 2: Create user using Better Auth's internal API
@@ -144,7 +144,7 @@ export const POST = withRateLimitTier(withApiLogging(
             null,
             'USER_ALREADY_EXISTS'
           )
-          return addCorsHeaders(response)
+          return addCorsHeaders(response, req)
         }
 
         const response = createApiError(
@@ -153,7 +153,7 @@ export const POST = withRateLimitTier(withApiLogging(
           null,
           'SIGNUP_FAILED'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Parse response to get user data
@@ -167,7 +167,7 @@ export const POST = withRateLimitTier(withApiLogging(
           null,
           'SIGNUP_FAILED'
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Steps 3-4 run via the service pool (RLS bypass). This is a trusted
@@ -228,7 +228,7 @@ export const POST = withRateLimitTier(withApiLogging(
           { created: true },
           201
         )
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       } catch (error) {
         await tx.rollback()
         throw error
@@ -236,7 +236,7 @@ export const POST = withRateLimitTier(withApiLogging(
     } catch (error) {
       console.error('Error in signup-with-invite:', error)
       const response = createApiError('Internal server error', 500)
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
   }
 ), 'auth')

package/dist/templates/app/api/v1/billing/cancel/route.ts

@@ -9,7 +9,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
-import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
 import { queryWithRLS } from '@nextsparkjs/core/lib/db'
@@ -29,11 +29,12 @@ const cancelSchema = z.object({
  * - reason: string (optional) - Reason for cancellation (stored in metadata)
  */
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // 1. Dual authentication
-  const authResult = await authenticateRequest(request)
+  // 1. Dual authentication; the API-key scope is declared at the entry
+  // point, which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'billing:write' })
 
   if (!authResult.success || !authResult.user) {
-    return createAuthError('Unauthorized', 401)
+    return createAuthFailureResponse(authResult)
   }
 
   // 2. Get team context
@@ -104,7 +105,7 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
 
   // 6. Cancel via billing gateway
   try {
-    const gateway = getBillingGateway()
+    const gateway = await getBillingGateway()
     if (immediate) {
       await gateway.cancelSubscriptionImmediately(subscription.externalSubscriptionId)
     } else {
@@ -171,7 +172,7 @@ async function handleReactivation(teamId: string) {
   }
 
   try {
-    const gateway = getBillingGateway()
+    const gateway = await getBillingGateway()
     await gateway.reactivateSubscription(subscription.externalSubscriptionId)
 
     // Update local DB

package/dist/templates/app/api/v1/billing/change-plan/route.ts

@@ -9,7 +9,7 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
-import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
@@ -27,11 +27,12 @@ const changePlanSchema = z.object({
  * - billingInterval: 'monthly' | 'yearly' (default: monthly)
  */
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // 1. Dual authentication
-  const authResult = await authenticateRequest(request)
+  // 1. Dual authentication; the API-key scope is declared at the entry
+  // point, which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'billing:write' })
 
   if (!authResult.success || !authResult.user) {
-    return createAuthError('Unauthorized', 401)
+    return createAuthFailureResponse(authResult)
   }
 
   // 2. Get team context

package/dist/templates/app/api/v1/billing/check-action/route.ts

@@ -10,7 +10,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { SubscriptionService } from '@nextsparkjs/core/lib/services'
 import { z } from 'zod'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
@@ -21,11 +21,13 @@ const checkActionSchema = z.object({
 })
 
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // 1. Dual authentication (API Key OR Session)
-  const authResult = await authenticateRequest(request)
+  // 1. Dual authentication (API Key OR Session); the API-key scope is
+  // declared at the entry point, which fails closed for keys that lack it
+  // (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'billing:read' })
 
   if (!authResult.success || !authResult.user) {
-    return createAuthError('Unauthorized', 401)
+    return createAuthFailureResponse(authResult)
   }
 
   // 2. Parse and validate request body

package/dist/templates/app/api/v1/billing/checkout/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { z } from 'zod'
@@ -20,11 +20,12 @@ const checkoutSchema = z.object({
 })
 
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // 1. Dual authentication
-  const authResult = await authenticateRequest(request)
+  // 1. Dual authentication; the API-key scope is declared at the entry
+  // point, which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'billing:write' })
 
   if (!authResult.success || !authResult.user) {
-    return createAuthError('Unauthorized', 401)
+    return createAuthFailureResponse(authResult)
   }
 
   // 2. Parse and validate request body
@@ -121,7 +122,8 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     const successUrl = `${appUrl}/dashboard/settings/billing?success=true`
     const cancelUrl = `${appUrl}/dashboard/settings/billing?canceled=true`
 
-    const session = await getBillingGateway().createCheckoutSession({
+    const gateway = await getBillingGateway()
+    const session = await gateway.createCheckoutSession({
       teamId,
       planSlug,
       billingPeriod,

package/dist/templates/app/api/v1/billing/plans/route.ts

@@ -14,16 +14,10 @@ import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 export const GET = withRateLimitTier(async (request: NextRequest) => {
   // Plans list is partially public (public plans visible to all, hidden plans only to superadmin)
-  let includeHidden = false
-
-  try {
-    const { auth } = await validateAndAuthenticateRequest(request)
-    // Check if user is superadmin (for full access including hidden plans)
-    includeHidden = auth.scopes.includes('*') || auth.scopes.includes('superadmin:all')
-  } catch {
-    // Not authenticated, only show public plans
-    includeHidden = false
-  }
+  // Anonymous callers resolve to a null auth (#112) and only see public plans.
+  // Public listing: any valid API key may call this; only the `*` scope unlocks hidden plans, decided below (#93).
+  const { auth } = await validateAndAuthenticateRequest(request, { allowAnyScope: true })
+  const includeHidden = !!auth && (auth.scopes.includes('*') || auth.scopes.includes('superadmin:all'))
 
   try {
     const plans = await PlanService.list({ includeHidden })
@@ -35,9 +29,11 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
 }, 'read');
 
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // 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')
 
   // Check superadmin permission
   if (!auth.scopes.includes('*') && !auth.scopes.includes('superadmin:all')) {

package/dist/templates/app/api/v1/billing/portal/route.ts

@@ -8,17 +8,18 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest, createAuthError } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import { getBillingGateway } from '@nextsparkjs/core/lib/billing/gateways/factory'
 import { SubscriptionService, MembershipService } from '@nextsparkjs/core/lib/services'
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // 1. Dual authentication
-  const authResult = await authenticateRequest(request)
+  // 1. Dual authentication; the API-key scope is declared at the entry
+  // point, which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'billing:write' })
 
   if (!authResult.success || !authResult.user) {
-    return createAuthError('Unauthorized', 401)
+    return createAuthFailureResponse(authResult)
   }
 
   // 2. Get team context
@@ -69,7 +70,8 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
     const appUrl = process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:5173'
     const returnUrl = `${appUrl}/dashboard/settings/billing`
 
-    const session = await getBillingGateway().createPortalSession({
+    const gateway = await getBillingGateway()
+    const session = await gateway.createPortalSession({
       customerId: subscription.externalCustomerId,
       returnUrl
     })

package/dist/templates/app/api/v1/billing/webhooks/polar/route.ts

@@ -52,7 +52,7 @@ async function handlePolarWebhook(request: NextRequest): Promise<NextResponse> {
   // 2. Verify webhook signature (MANDATORY for security)
   let event: { id: string; type: string; data: Record<string, unknown> }
   try {
-    const gateway = getBillingGateway()
+    const gateway = await getBillingGateway()
     event = gateway.verifyWebhookSignature(payload, headers)
   } catch (error) {
     console.error('[polar-webhook] Signature verification failed:', error)

package/dist/templates/app/api/v1/devtools/blocks/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import {
   canAccessDevtoolsApi,
   createDevtoolsAccessDeniedResponse,
@@ -19,11 +19,12 @@ import { TAGS_REGISTRY, COVERAGE_SUMMARY } from '@nextsparkjs/registries/testing
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 export const GET = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission

package/dist/templates/app/api/v1/devtools/features/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import {
   canAccessDevtoolsApi,
   createDevtoolsAccessDeniedResponse,
@@ -21,11 +21,12 @@ import {
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 export const GET = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission

package/dist/templates/app/api/v1/devtools/flows/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import {
   canAccessDevtoolsApi,
   createDevtoolsAccessDeniedResponse,
@@ -21,11 +21,12 @@ import {
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 export const GET = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission

package/dist/templates/app/api/v1/devtools/scheduled-actions/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import {
   canAccessDevtoolsApi,
   createDevtoolsAccessDeniedResponse,
@@ -21,11 +21,12 @@ import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { scheduleAction } from '@nextsparkjs/core/lib/scheduled-actions/scheduler'
 
 export const GET = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission
@@ -135,11 +136,12 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
  * }
  */
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission

package/dist/templates/app/api/v1/devtools/scheduled-actions/run/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import {
   canAccessDevtoolsApi,
   createDevtoolsAccessDeniedResponse,
@@ -20,11 +20,12 @@ import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { executeAction } from '@nextsparkjs/core/lib/scheduled-actions/processor'
 
 export const POST = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission

package/dist/templates/app/api/v1/devtools/testing/route.ts

@@ -8,7 +8,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { authenticateRequest, createAuthFailureResponse } from '@nextsparkjs/core/lib/api/auth/dual-auth'
 import {
   canAccessDevtoolsApi,
   createDevtoolsAccessDeniedResponse,
@@ -23,11 +23,12 @@ import {
 import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
 export const GET = withRateLimitTier(async (request: NextRequest) => {
-  // Authenticate request
-  const authResult = await authenticateRequest(request)
+  // Authenticate request; the API-key scope is declared at the entry point,
+  // which fails closed for keys that lack it (#93).
+  const authResult = await authenticateRequest(request, { requiredScope: 'admin:devtools' })
 
   if (!authResult.success) {
-    return createDevtoolsUnauthorizedResponse()
+    return authResult.type === 'api-key' ? createAuthFailureResponse(authResult) : createDevtoolsUnauthorizedResponse()
   }
 
   // Check DevTools access permission