Authentication

import { createSurf } from '@surfjs/core'
 
const surf = await createSurf({
  name: 'My Store',
  auth: { type: 'bearer', description: 'JWT Bearer token' },
 
  // Auth verifier — called automatically for commands that need auth
  authVerifier: async (token, command) => {
    const decoded = await verifyJWT(token)
    if (!decoded) return { valid: false, reason: 'Invalid token' }
    return { valid: true, claims: { userId: decoded.sub, role: decoded.role } }
  },
 
  commands: {
    // Public — no auth needed
    search: {
      description: 'Search products',
      auth: 'none', // default
      params: { query: { type: 'string', required: true } },
      run: async ({ query }) => db.search(query),
    },
 
    // Auth required — returns 401 if no token, 403 if invalid
    'order.create': {
      description: 'Create a new order',
      auth: 'required',
      run: async (params, ctx) => {
        // ctx.claims is populated by authVerifier
        return orders.create(ctx.claims!.userId, params)
      },
    },
 
    // Auth optional — works without token, enriched with token
    recommendations: {
      description: 'Get recommendations',
      auth: 'optional',
      run: async (_, ctx) => {
        if (ctx.claims) return personalized(ctx.claims.userId)
        return popular()
      },
    },
 
    // Hidden — not in manifest unless authed
    'admin.analytics': {
      description: 'Dashboard analytics',
      auth: 'hidden',
      run: async (_, ctx) => getAnalytics(ctx.claims!.role),
    },
  },
})

import { createSurf, bearerVerifier } from '@surfjs/core'
 
const surf = await createSurf({
  name: 'My API',
  authVerifier: bearerVerifier(['sk-secret-token-1', 'sk-secret-token-2']),
  commands: { /* ... */ },
})