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

package/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/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/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/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/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/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/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/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/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

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

@@ -1,5 +1,5 @@
 import { NextRequest } from 'next/server'
-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 { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
 import { API_ERROR_CODES } from '@nextsparkjs/core/lib/api/api-error'
 import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
@@ -20,15 +20,11 @@ export const GET = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    // 1. Authenticate
-    const authResult = await authenticateRequest(request)
+    // 1. Authenticate; 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: 'media:read' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    // 2. Check permissions
-    if (!hasRequiredScope(authResult, 'media:read')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     // 3. Resolve and validate team context
@@ -76,15 +72,11 @@ export const PATCH = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    // 1. Authenticate
-    const authResult = await authenticateRequest(request)
+    // 1. Authenticate; 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: 'media:write' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    // 2. Check permissions
-    if (!hasRequiredScope(authResult, 'media:write')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     // 3. Resolve and validate team context
@@ -141,15 +133,11 @@ export const DELETE = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    // 1. Authenticate
-    const authResult = await authenticateRequest(request)
+    // 1. Authenticate; 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: 'media:delete' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    // 2. Check permissions
-    if (!hasRequiredScope(authResult, 'media:delete')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     // 3. Resolve and validate team context

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

@@ -1,5 +1,5 @@
 import { NextRequest } from 'next/server'
-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 { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
 import { API_ERROR_CODES } from '@nextsparkjs/core/lib/api/api-error'
 import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
@@ -25,13 +25,11 @@ export const GET = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:read' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:read')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)
@@ -70,13 +68,11 @@ export const POST = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:write' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:write')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)
@@ -124,13 +120,11 @@ export const PUT = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:write' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:write')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)
@@ -178,13 +172,11 @@ export const DELETE = withRateLimitTier(async (
   { params }: { params: Promise<{ id: string }> }
 ) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:write' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:write')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)

package/templates/app/api/v1/media/check-duplicates/route.ts

@@ -1,5 +1,5 @@
 import { NextRequest } from 'next/server'
-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 { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
 import { API_ERROR_CODES } from '@nextsparkjs/core/lib/api/api-error'
 import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
@@ -17,13 +17,11 @@ import { MediaService } from '@nextsparkjs/core/lib/services/media.service'
  */
 export const POST = withRateLimitTier(async (request: NextRequest) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:read' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:read')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)

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

@@ -1,5 +1,5 @@
 import { NextRequest } from 'next/server'
-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 { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
 import { API_ERROR_CODES } from '@nextsparkjs/core/lib/api/api-error'
 import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
@@ -26,15 +26,11 @@ import { mediaListQuerySchema } from '@nextsparkjs/core/lib/media/schemas'
  */
 export const GET = withRateLimitTier(async (request: NextRequest) => {
   try {
-    // 1. Authenticate
-    const authResult = await authenticateRequest(request)
+    // 1. Authenticate; 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: 'media:read' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    // 2. Check permissions
-    if (!hasRequiredScope(authResult, 'media:read')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     // 3. Resolve and validate team context

package/templates/app/api/v1/media/upload/route.ts

@@ -1,6 +1,6 @@
 import { NextRequest } from 'next/server'
 import { put } from '@vercel/blob'
-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 { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
 import { API_ERROR_CODES } from '@nextsparkjs/core/lib/api/api-error'
 import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
@@ -55,18 +55,12 @@ async function uploadToLocalStorageBuffer(buffer: Buffer, fileName: string): Pro
  */
 export const POST = withRateLimitTier(async (request: NextRequest) => {
   try {
-    // 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: 'media:write' })
 
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    // 2. Check permissions for media upload
-    const hasPermission = hasRequiredScope(authResult, 'media:write')
-
-    if (!hasPermission) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     // 3. Resolve and validate team context
@@ -237,18 +231,12 @@ export const POST = withRateLimitTier(async (request: NextRequest) => {
  */
 export const GET = withRateLimitTier(async (request: NextRequest) => {
   try {
-    // 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: 'media:read' })
 
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    // 2. Check permissions for media read
-    const hasPermission = hasRequiredScope(authResult, 'media:read')
-
-    if (!hasPermission) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     // 3. Resolve and validate team context

package/templates/app/api/v1/media-tags/route.ts

@@ -1,5 +1,5 @@
 import { NextRequest } from 'next/server'
-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 { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
 import { API_ERROR_CODES } from '@nextsparkjs/core/lib/api/api-error'
 import { checkPermission } from '@nextsparkjs/core/lib/permissions/check'
@@ -15,13 +15,11 @@ import { MediaService } from '@nextsparkjs/core/lib/services/media.service'
  */
 export const GET = withRateLimitTier(async (request: NextRequest) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:read' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:read')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)
@@ -51,13 +49,11 @@ export const GET = withRateLimitTier(async (request: NextRequest) => {
  */
 export const POST = withRateLimitTier(async (request: NextRequest) => {
   try {
-    const authResult = await authenticateRequest(request)
+    // Authenticate; 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: 'media:write' })
     if (!authResult.success) {
-      return createApiError('Unauthorized', 401)
-    }
-
-    if (!hasRequiredScope(authResult, 'media:write')) {
-      return createApiError('Insufficient permissions', 403, undefined, API_ERROR_CODES.INSUFFICIENT_SCOPE)
+      return createAuthFailureResponse(authResult)
     }
 
     const teamResult = await resolveTeamContext(request, authResult)

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

@@ -23,46 +23,38 @@ 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 { PatternUsageService } from '@nextsparkjs/core/lib/services'
 import { queryOneWithRLS } from '@nextsparkjs/core/lib/db'
 
 // Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest()
+export async function OPTIONS(request: NextRequest) {
+  return handleCorsPreflightRequest(request)
 }
 
 // GET /api/v1/patterns/:id/usages - Get pattern usages
 export const GET = withApiLogging(
   async (req: NextRequest, { params }: { params: Promise<{ id: string }> }): Promise<NextResponse> => {
     try {
-      // Authenticate using dual auth
-      const authResult = await authenticateRequest(req)
+      // Authenticate using dual auth; the required API-key scope is declared
+      // at the entry point (fail closed, #93).
+      const authResult = await authenticateRequest(req, { requiredScope: 'patterns: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
-      if (!hasRequiredScope(authResult, 'patterns:read')) {
-        const response = createApiError('Insufficient permissions', 403)
-        return addCorsHeaders(response)
-      }
-
       const { id: patternId } = await params
       const userId = authResult.user!.id
 
       // Validate that patternId is not empty
       if (!patternId || patternId.trim() === '') {
         const response = createApiError('Pattern ID is required', 400, null, 'MISSING_PATTERN_ID')
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Verify pattern exists and user has access
@@ -74,7 +66,7 @@ export const GET = withApiLogging(
 
       if (!pattern) {
         const response = createApiError('Pattern not found', 404, null, 'PATTERN_NOT_FOUND')
-        return addCorsHeaders(response)
+        return addCorsHeaders(response, req)
       }
 
       // Parse query parameters
@@ -106,11 +98,11 @@ export const GET = withApiLogging(
         entityType: entityType || 'all',
       })
 
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     } catch (error) {
       console.error('Error fetching pattern usages:', error)
       const response = createApiError('Internal server error', 500)
-      return addCorsHeaders(response)
+      return addCorsHeaders(response, req)
     }
   }
 )