Building a Production-Ready REST API with Rork, Hono.js & Cloudflare Workers — JWT Auth, D1, R2, and Rate Limiting

-- migrations/001_initial.sql
CREATE TABLE IF NOT EXISTS users (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  display_name TEXT,
  avatar_url TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now'))
);
 
CREATE TABLE IF NOT EXISTS sessions (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  token_hash TEXT UNIQUE NOT NULL,
  expires_at TEXT NOT NULL,
  created_at TEXT DEFAULT (datetime('now'))
);
 
CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id);
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);

# Run locally first
wrangler d1 execute rork_app_db --local --file=migrations/001_initial.sql
 
# Then apply to production
wrangler d1 execute rork_app_db --remote --file=migrations/001_initial.sql

// src/index.ts
import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { secureHeaders } from 'hono/secure-headers'
import { authRouter } from './routes/auth'
import { usersRouter } from './routes/users'
import { filesRouter } from './routes/files'
import { rateLimitMiddleware } from './middleware/rateLimit'
import { errorHandler } from './middleware/errorHandler'
 
// Cloudflare Workers Bindings type
type Bindings = {
  DB: D1Database
  SESSION_KV: KVNamespace
  STORAGE: R2Bucket
  JWT_SECRET: string
  ENVIRONMENT: string
}
 
const app = new Hono<{ Bindings: Bindings }>()
 
// Global middleware stack
app.use('*', logger())
app.use('*', secureHeaders())
app.use('*', cors({
  origin: ['https://yourrorkapp.com', 'exp://localhost'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization'],
  maxAge: 86400,
}))
app.use('*', rateLimitMiddleware)
 
// Global error handler
app.onError(errorHandler)
 
// Health check
app.get('/health', (c) => c.json({
  status: 'ok',
  environment: c.env.ENVIRONMENT,
  timestamp: new Date().toISOString(),
}))
 
// Route registration
app.route('/api/v1/auth', authRouter)
app.route('/api/v1/users', usersRouter)
app.route('/api/v1/files', filesRouter)
 
app.notFound((c) => c.json({ error: 'Not Found', path: c.req.path }, 404))
 
export default app

// src/middleware/auth.ts
import { Context, Next } from 'hono'
import { verify } from 'hono/jwt'
 
export type JWTPayload = {
  sub: string   // user ID
  email: string
  iat: number
  exp: number
}
 
export const authMiddleware = async (c: Context, next: Next) => {
  const authHeader = c.req.header('Authorization')
 
  if (!authHeader?.startsWith('Bearer ')) {
    return c.json({ error: 'Unauthorized: No token provided' }, 401)
  }
 
  const token = authHeader.slice(7)
 
  try {
    const payload = await verify(token, c.env.JWT_SECRET) as JWTPayload
 
    if (payload.exp < Math.floor(Date.now() / 1000)) {
      return c.json({ error: 'Unauthorized: Token expired' }, 401)
    }
 
    c.set('jwtPayload', payload)
    c.set('userId', payload.sub)
 
    await next()
  } catch {
    return c.json({ error: 'Unauthorized: Invalid token' }, 401)
  }
}

// src/routes/auth.ts
import { Hono } from 'hono'
import { sign } from 'hono/jwt'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
import { hashPassword, verifyPassword } from '../utils/crypto'
 
type Bindings = { DB: D1Database; SESSION_KV: KVNamespace; JWT_SECRET: string }
 
export const authRouter = new Hono<{ Bindings: Bindings }>()
 
const registerSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  displayName: z.string().min(1).max(50).optional(),
})
 
// Registration endpoint
authRouter.post('/register', zValidator('json', registerSchema), async (c) => {
  const { email, password, displayName } = c.req.valid('json')
 
  const existing = await c.env.DB.prepare(
    'SELECT id FROM users WHERE email = ?'
  ).bind(email).first()
 
  if (existing) {
    return c.json({ error: 'An account with this email already exists' }, 409)
  }
 
  const passwordHash = await hashPassword(password)
  const userId = crypto.randomUUID()
 
  await c.env.DB.prepare(
    'INSERT INTO users (id, email, password_hash, display_name) VALUES (?, ?, ?, ?)'
  ).bind(userId, email, passwordHash, displayName ?? null).run()
 
  const token = await sign(
    {
      sub: userId,
      email,
      iat: Math.floor(Date.now() / 1000),
      exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30, // 30 days
    },
    c.env.JWT_SECRET
  )
 
  return c.json({ message: 'Account created', token, user: { id: userId, email, displayName } }, 201)
})
 
// Login endpoint
const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(1),
})
 
authRouter.post('/login', zValidator('json', loginSchema), async (c) => {
  const { email, password } = c.req.valid('json')
 
  const user = await c.env.DB.prepare(
    'SELECT id, email, password_hash, display_name FROM users WHERE email = ?'
  ).bind(email).first<{ id: string; email: string; password_hash: string; display_name: string | null }>()
 
  if (!user) {
    // Constant-time response to prevent timing attacks
    await hashPassword('dummy_timing_attack_prevention')
    return c.json({ error: 'Invalid email or password' }, 401)
  }
 
  const isValid = await verifyPassword(password, user.password_hash)
  if (!isValid) {
    return c.json({ error: 'Invalid email or password' }, 401)
  }
 
  const token = await sign(
    {
      sub: user.id,
      email: user.email,
      iat: Math.floor(Date.now() / 1000),
      exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30,
    },
    c.env.JWT_SECRET
  )
 
  return c.json({ token, user: { id: user.id, email: user.email, displayName: user.display_name } })
})

// src/routes/files.ts
import { Hono } from 'hono'
import { authMiddleware } from '../middleware/auth'
 
type Bindings = { STORAGE: R2Bucket }
type Variables = { userId: string }
 
export const filesRouter = new Hono<{ Bindings: Bindings; Variables: Variables }>()
 
filesRouter.use('*', authMiddleware)
 
filesRouter.post('/upload', async (c) => {
  const userId = c.get('userId')
  const formData = await c.req.formData()
  const file = formData.get('file') as File | null
 
  if (!file) return c.json({ error: 'No file provided' }, 400)
 
  const MAX_SIZE = 10 * 1024 * 1024 // 10 MB
  if (file.size > MAX_SIZE) {
    return c.json({ error: 'File exceeds 10 MB limit' }, 413)
  }
 
  const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'image/gif']
  if (!ALLOWED_TYPES.includes(file.type)) {
    return c.json({ error: 'Supported formats: JPEG, PNG, WebP, GIF' }, 415)
  }
 
  const ext = file.name.split('.').pop()?.toLowerCase() ?? 'bin'
  const objectKey = `uploads/${userId}/${crypto.randomUUID()}.${ext}`
 
  await c.env.STORAGE.put(objectKey, await file.arrayBuffer(), {
    httpMetadata: {
      contentType: file.type,
      cacheControl: 'public, max-age=31536000',
    },
    customMetadata: {
      uploadedBy: userId,
      originalName: file.name,
    },
  })
 
  const publicUrl = `https://assets.yourapp.com/${objectKey}`
  return c.json({ url: publicUrl, key: objectKey }, 201)
})
 
filesRouter.delete('/:key', async (c) => {
  const userId = c.get('userId')
  const key = c.req.param('key')
 
  const object = await c.env.STORAGE.head(`uploads/${userId}/${key}`)
  if (!object) return c.json({ error: 'File not found' }, 404)
 
  await c.env.STORAGE.delete(`uploads/${userId}/${key}`)
  return c.json({ message: 'File deleted' })
})

// src/middleware/rateLimit.ts
import { Context, Next } from 'hono'
 
type Bindings = { SESSION_KV: KVNamespace }
 
const RATE_LIMIT = {
  windowMs: 60 * 1000,
  maxRequests: 60,
  authMaxRequests: 5,
}
 
export const rateLimitMiddleware = async (
  c: Context<{ Bindings: Bindings }>,
  next: Next
) => {
  const clientIp = c.req.header('CF-Connecting-IP') ?? '0.0.0.0'
  const path = c.req.path
  const now = Math.floor(Date.now() / 1000)
  const windowStart = now - (now % 60)
 
  const isAuthEndpoint = path.includes('/auth/')
  const maxRequests = isAuthEndpoint
    ? RATE_LIMIT.authMaxRequests
    : RATE_LIMIT.maxRequests
 
  const kvKey = `rate_limit:${clientIp}:${path.split('/')[3]}:${windowStart}`
  const current = await c.env.SESSION_KV.get(kvKey)
  const count = current ? parseInt(current, 10) + 1 : 1
 
  if (count > maxRequests) {
    return c.json(
      {
        error: 'Too Many Requests',
        message: 'Rate limit exceeded. Please try again in a minute.',
        retryAfter: windowStart + 60 - now,
      },
      429,
      {
        'Retry-After': String(windowStart + 60 - now),
        'X-RateLimit-Limit': String(maxRequests),
        'X-RateLimit-Remaining': '0',
        'X-RateLimit-Reset': String(windowStart + 60),
      }
    )
  }
 
  await c.env.SESSION_KV.put(kvKey, String(count), { expirationTtl: 65 })
  c.header('X-RateLimit-Limit', String(maxRequests))
  c.header('X-RateLimit-Remaining', String(maxRequests - count))
  c.header('X-RateLimit-Reset', String(windowStart + 60))
 
  await next()
}

// lib/apiClient.ts (inside your Rork project)
import AsyncStorage from '@react-native-async-storage/async-storage'
 
const API_BASE_URL = 'https://rork-api-backend.YOUR_SUBDOMAIN.workers.dev/api/v1'
 
class ApiClient {
  private async getToken(): Promise<string | null> {
    return AsyncStorage.getItem('auth_token')
  }
 
  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
    const token = await this.getToken()
    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
    if (token) headers['Authorization'] = `Bearer ${token}`
 
    const response = await fetch(`${API_BASE_URL}${path}`, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    })
 
    if (!response.ok) {
      const error = await response.json() as { error: string }
      throw new Error(error.error ?? `HTTP ${response.status}`)
    }
 
    return response.json() as T
  }
 
  async register(email: string, password: string, displayName?: string) {
    return this.request<{ token: string; user: User }>(
      'POST', '/auth/register', { email, password, displayName }
    )
  }
 
  async login(email: string, password: string) {
    return this.request<{ token: string; user: User }>(
      'POST', '/auth/login', { email, password }
    )
  }
 
  async getProfile() {
    return this.request<User>('GET', '/users/me')
  }
 
  async uploadAvatar(imageUri: string) {
    const token = await this.getToken()
    const formData = new FormData()
    formData.append('file', { uri: imageUri, type: 'image/jpeg', name: 'avatar.jpg' } as unknown as Blob)
 
    const response = await fetch(`${API_BASE_URL}/files/upload`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${token}` },
      body: formData,
    })
 
    if (!response.ok) throw new Error('Upload failed')
    return response.json() as Promise<{ url: string }>
  }
}
 
export const apiClient = new ApiClient()
export type User = { id: string; email: string; displayName: string | null }

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Workers
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run typecheck
      - run: npm test
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

# Securely store the secret in Workers' encrypted environment
wrangler secret put JWT_SECRET
# Enter a random string of at least 32 characters when prompted
 
# For local development only:
echo 'JWT_SECRET="your-super-secret-key-minimum-32-chars"' >> .dev.vars

// Avoid: fetching related data in a loop
const users = await db.prepare('SELECT * FROM users').all()
for (const user of users.results) {
  const posts = await db.prepare('SELECT * FROM posts WHERE user_id = ?')
    .bind(user.id).all()
}
 
// Prefer: a single JOIN query
const { results } = await db.prepare(`
  SELECT u.id, u.email, COUNT(p.id) as post_count
  FROM users u
  LEFT JOIN posts p ON p.user_id = u.id
  GROUP BY u.id
  LIMIT 50
`).all()

async function getCachedUser(userId: string, kv: KVNamespace, db: D1Database) {
  const cacheKey = `user:${userId}`
  const cached = await kv.get(cacheKey, 'json')
  if (cached) return cached
 
  const user = await db.prepare(
    'SELECT id, email, display_name, avatar_url FROM users WHERE id = ?'
  ).bind(userId).first()
 
  if (user) {
    await kv.put(cacheKey, JSON.stringify(user), { expirationTtl: 300 }) // 5-minute TTL
  }
 
  return user
}

// src/middleware/errorHandler.ts
import { Context } from 'hono'
 
export const errorHandler = (err: Error, c: Context) => {
  const isProd = c.env.ENVIRONMENT === 'production'
 
  console.error('[Error]', {
    path: c.req.path,
    method: c.req.method,
    error: err.message,
    stack: err.stack,
  })
 
  if (err.name === 'ZodError') {
    return c.json({ error: 'Validation Error', details: isProd ? undefined : err.message }, 400)
  }
 
  return c.json(
    {
      error: 'Internal Server Error',
      message: isProd ? 'Something went wrong on our end.' : err.message,
    },
    500
  )
}

// src/types/context.ts
import type { JWTPayload } from '../middleware/auth'
 
// Define all variables your middleware can set on the context
export type AppVariables = {
  jwtPayload: JWTPayload
  userId: string
  userRole: 'admin' | 'member' | 'guest'
}
 
// A reusable app type for authenticated routes
export type AuthenticatedHono = Hono<{
  Bindings: Bindings
  Variables: AppVariables
}>

// src/middleware/rbac.ts
import { Context, Next } from 'hono'
import { AppVariables } from '../types/context'
 
type RequiredRole = 'admin' | 'member'
 
export const requireRole = (role: RequiredRole) => {
  return async (c: Context<{ Variables: AppVariables }>, next: Next) => {
    const userRole = c.get('userRole')
 
    const roleHierarchy: Record<string, number> = {
      guest: 0,
      member: 1,
      admin: 2,
    }
 
    if ((roleHierarchy[userRole] ?? 0) < roleHierarchy[role]) {
      return c.json(
        { error: 'Forbidden', message: `This action requires ${role} permissions` },
        403
      )
    }
 
    await next()
  }
}
 
// Usage in a route file:
// adminRouter.delete('/users/:id', authMiddleware, requireRole('admin'), async (c) => { ... })

// src/routes/users.ts (partial)
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
 
const updateProfileSchema = z.object({
  displayName: z
    .string()
    .min(1, 'Display name cannot be empty')
    .max(50, 'Display name cannot exceed 50 characters')
    .optional(),
  avatarUrl: z
    .string()
    .url('Must be a valid URL')
    .optional(),
}).strict() // Rejects any extra keys sent by the client
 
usersRouter.put(
  '/me',
  authMiddleware,
  zValidator('json', updateProfileSchema, (result, c) => {
    // Custom error response format
    if (!result.success) {
      return c.json({
        error: 'Validation failed',
        fields: result.error.flatten().fieldErrors,
      }, 400)
    }
  }),
  async (c) => {
    const userId = c.get('userId')
    const updates = c.req.valid('json')
 
    const setClauses: string[] = []
    const values: unknown[] = []
 
    if (updates.displayName !== undefined) {
      setClauses.push('display_name = ?')
      values.push(updates.displayName)
    }
    if (updates.avatarUrl !== undefined) {
      setClauses.push('avatar_url = ?')
      values.push(updates.avatarUrl)
    }
 
    if (setClauses.length === 0) {
      return c.json({ message: 'Nothing to update' })
    }
 
    setClauses.push('updated_at = datetime(\'now\')')
    values.push(userId)
 
    await c.env.DB.prepare(
      `UPDATE users SET ${setClauses.join(', ')} WHERE id = ?`
    ).bind(...values).run()
 
    return c.json({ message: 'Profile updated successfully' })
  }
)

// src/middleware/requestLogger.ts
import { Context, Next } from 'hono'
 
export const requestLogger = async (c: Context, next: Next) => {
  const start = Date.now()
  const method = c.req.method
  const path = c.req.path
  const ip = c.req.header('CF-Connecting-IP') ?? 'unknown'
  const country = c.req.header('CF-IPCountry') ?? 'XX'
 
  await next()
 
  const duration = Date.now() - start
  const status = c.res.status
 
  // Cloudflare Workers captures console.log output in real-time logs
  console.log(JSON.stringify({
    ts: new Date().toISOString(),
    method,
    path,
    status,
    duration_ms: duration,
    ip,
    country,
    // Log slow requests (>200ms) for D1 query analysis
    slow: duration > 200,
  }))
}

# Stream live logs from your production Worker
wrangler tail --format pretty
 
# Filter to errors only
wrangler tail --format pretty --status error

// Utility for timed D1 queries in development
async function timedQuery<T>(
  label: string,
  query: D1PreparedStatement
): Promise<D1Result<T>> {
  const start = Date.now()
  const result = await query.all<T>()
  const elapsed = Date.now() - start
 
  if (elapsed > 100) {
    console.warn(`[SLOW QUERY] ${label}: ${elapsed}ms`)
  }
 
  return result
}
 
// Usage
const { results } = await timedQuery(
  'list-users',
  db.prepare('SELECT id, email FROM users ORDER BY created_at DESC LIMIT 20')
)

npm install --save-dev vitest @cloudflare/vitest-pool-workers

// vitest.config.ts
import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  test: {
    pool: '@cloudflare/vitest-pool-workers',
    poolOptions: {
      workers: {
        wrangler: { configPath: './wrangler.toml' },
      },
    },
  },
})

// src/routes/auth.test.ts
import { describe, it, expect, beforeEach } from 'vitest'
import { env, SELF } from 'cloudflare:test'
import app from '../index'
 
describe('POST /api/v1/auth/register', () => {
  it('creates a new user and returns a JWT token', async () => {
    const res = await SELF.fetch('http://localhost/api/v1/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'test@example.com',
        password: 'SecurePass123!',
        displayName: 'Test User',
      }),
    })
 
    expect(res.status).toBe(201)
    const body = await res.json() as { token: string; user: { id: string } }
    expect(body.token).toBeTruthy()
    expect(body.user.id).toBeTruthy()
  })
 
  it('rejects duplicate email addresses', async () => {
    // Register once
    await SELF.fetch('http://localhost/api/v1/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'dupe@example.com', password: 'SecurePass123!' }),
    })
 
    // Register again with the same email
    const res = await SELF.fetch('http://localhost/api/v1/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'dupe@example.com', password: 'AnotherPass456!' }),
    })
 
    expect(res.status).toBe(409)
  })
 
  it('returns 400 for invalid email format', async () => {
    const res = await SELF.fetch('http://localhost/api/v1/auth/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'not-an-email', password: 'SecurePass123!' }),
    })
 
    expect(res.status).toBe(400)
  })
})

npx vitest run
# Or in watch mode during development:
npx vitest