sonicjs/docs/authentication.md
Lane cf66219986
fix: configurable JWT TTL with working refresh endpoint (#800) (#801)
* fix: configurable JWT TTL with working refresh endpoint (#800)

Replace the hardcoded 24h JWT expiration with configurable TTL (default 30d)
resolvable via JWT_EXPIRES_IN env var (ceiling) or admin Settings → Security
UI. Rewrite /auth/refresh to accept valid-or-recently-expired tokens within a
configurable grace window (default 7d), re-verifying the HS256 signature via
Web Crypto (since hono/jwt checks exp before signature) and re-validating the
user against the database before issuing a fresh token.

Updates every token-minting call site (auth routes, OTP plugin, magic-link
plugin, OAuth providers) to read the TTL from the DB-aware helper. Adds a
live Session / JWT card to Admin → Settings → Security with save/load and
matching persistence via SettingsService. Updates repo docs and the doc site
authentication page to describe the new configuration surface and refresh
semantics.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix: keep /auth/refresh 401 message and flex cookie Max-Age assertion

- Restore "Authentication required" as the error message when /auth/refresh is
  called without a token, matching the prior behavior the E2E contract expects.
- Update the cookie E2E to assert Max-Age is present (any positive value)
  instead of the old hardcoded 86400, since JWT TTL is now configurable.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-21 18:42:51 -07:00

38 KiB

Authentication & Security

SonicJS AI implements a comprehensive authentication and authorization system using JWT tokens, KV-based caching, and role-based access control (RBAC). This guide covers all aspects of user authentication, security, and permissions.

Table of Contents

Overview

SonicJS AI uses a modern authentication architecture built on:

  • JWT (JSON Web Tokens) for stateless authentication
  • Cloudflare KV for token verification caching (5-minute TTL)
  • SHA-256 password hashing with salt
  • RBAC (Role-Based Access Control) for fine-grained permissions
  • HTTP-only cookies and Bearer token support
  • Session tracking with activity logging
  • Invitation-based user onboarding

Authentication Flow

1. User Registration

Endpoint: POST /auth/register

// Request
{
  "email": "user@example.com",
  "password": "securePassword123",
  "username": "johndoe",
  "firstName": "John",
  "lastName": "Doe"
}

// Response
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "role": "viewer"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Process:

  1. Email normalized to lowercase
  2. Check for duplicate email/username
  3. Password hashed with SHA-256 + salt
  4. User created with default role: viewer
  5. JWT token generated (TTL from JWT_EXPIRES_IN, default 30 days)
  6. HTTP-only cookie set
  7. Token returned in response

2. User Login

Endpoint: POST /auth/login

// Request
{
  "email": "user@example.com",
  "password": "securePassword123"
}

// Response
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "role": "viewer"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Process:

  1. Email normalized to lowercase
  2. User lookup with KV caching
  3. Password verification with SHA-256
  4. JWT token generation
  5. HTTP-only cookie set (TTL from JWT_EXPIRES_IN, default 30 days)
  6. last_login_at timestamp updated
  7. User cache invalidated to ensure fresh data

3. Token Refresh

Endpoint: POST /auth/refresh

// Headers (or cookie)
Authorization: Bearer <current_or_recently_expired_token>

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 2592000
}

Accepts a JWT that is either still valid or has expired within the grace window (JWT_REFRESH_GRACE_SECONDS, default 7 days). Re-validates the user in the database and issues a freshly-signed token — no password/OTP required. This supports sliding-session auth so a long-lived session cookie can keep a user logged in across JWT rotations.

JWT Implementation

Token Structure

SonicJS AI uses JWTs with the following payload:

interface JWTPayload {
  userId: string;      // User's unique ID
  email: string;       // User's email (normalized)
  role: string;        // User's role (admin, editor, viewer)
  exp: number;         // Expiration timestamp (Unix)
  iat: number;         // Issued at timestamp (Unix)
}

Token Generation

import { AuthManager, getJwtExpirySeconds } from '../middleware/auth'

// Generate a token with the environment-configured TTL
const ttl = getJwtExpirySeconds(env)
const token = await AuthManager.generateToken(
  userId,
  email,
  role,
  env.JWT_SECRET,
  ttl
)

Configuring JWT Expiration

JWT TTL is controlled by the JWT_EXPIRES_IN environment variable. It accepts a plain number of seconds or a duration string:

Example value Meaning
2592000 30 days (default)
30d 30 days
12h 12 hours
3600s 1 hour

If JWT_EXPIRES_IN is not set, SonicJS defaults to 30 days.

The refresh endpoint also honors JWT_REFRESH_GRACE_SECONDS (default 7 days), which controls how long after expiration a token can still be used to obtain a fresh one via POST /auth/refresh.

Token Verification

// Verify and decode token
const payload = await AuthManager.verifyToken(token)

if (!payload) {
  // Token invalid or expired
  return c.json({ error: 'Invalid or expired token' }, 401)
}

// Token is valid, payload contains user info
console.log(payload.userId, payload.email, payload.role)

Implementation:

static async verifyToken(token: string): Promise<JWTPayload | null> {
  try {
    const payload = await verify(token, JWT_SECRET, 'HS256') as JWTPayload

    // Check if token is expired
    if (payload.exp < Math.floor(Date.now() / 1000)) {
      return null
    }

    return payload
  } catch (error) {
    console.error('Token verification failed:', error)
    return null
  }
}

Token Configuration

// Default configuration in src/middleware/auth.ts
const JWT_SECRET = 'your-super-secret-jwt-key-change-in-production'

// Token expiration: 24 hours
const TOKEN_EXPIRY = 60 * 60 * 24

Production Configuration:

# Set JWT_SECRET in wrangler.toml or Cloudflare dashboard
[vars]
JWT_SECRET = "your-256-bit-production-secret"

Token Caching with KV

SonicJS AI implements intelligent token verification caching using Cloudflare KV to reduce JWT verification overhead.

How It Works

// In requireAuth() middleware
export const requireAuth = () => {
  return async (c: Context, next: Next) => {
    // Get token from header or cookie
    let token = c.req.header('Authorization')?.replace('Bearer ', '')
    if (!token) {
      token = getCookie(c, 'auth_token')
    }

    // Try to get cached token verification from KV
    const kv = c.env?.KV
    let payload: JWTPayload | null = null

    if (kv) {
      const cacheKey = `auth:${token.substring(0, 20)}`
      const cached = await kv.get(cacheKey, 'json')
      if (cached) {
        payload = cached as JWTPayload
      }
    }

    // If not cached, verify token
    if (!payload) {
      payload = await AuthManager.verifyToken(token)

      // Cache the verified payload for 5 minutes
      if (payload && kv) {
        const cacheKey = `auth:${token.substring(0, 20)}`
        await kv.put(cacheKey, JSON.stringify(payload), {
          expirationTtl: 300 // 5 minutes
        })
      }
    }

    if (!payload) {
      return c.json({ error: 'Invalid or expired token' }, 401)
    }

    // Add user info to context
    c.set('user', payload)
    await next()
  }
}

Cache Strategy

  • Cache Key: auth:{first-20-chars-of-token}
  • TTL: 5 minutes (300 seconds)
  • Cache Miss: Verifies JWT and caches result
  • Cache Hit: Returns cached payload (faster)
  • Invalidation: Automatic after 5 minutes

Performance Benefits

  • Reduces JWT signature verification overhead
  • Faster response times for authenticated requests
  • Scales better under high load
  • Cloudflare KV provides global edge caching

Password Security

Hashing Algorithm

SonicJS AI uses SHA-256 with a salt for password hashing:

export class AuthManager {
  static async hashPassword(password: string): Promise<string> {
    // In Cloudflare Workers, we use Web Crypto API
    const encoder = new TextEncoder()
    const data = encoder.encode(password + 'salt-change-in-production')
    const hashBuffer = await crypto.subtle.digest('SHA-256', data)
    const hashArray = Array.from(new Uint8Array(hashBuffer))
    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
  }

  static async verifyPassword(password: string, hash: string): Promise<boolean> {
    const passwordHash = await this.hashPassword(password)
    return passwordHash === hash
  }
}

Important Notes

  1. Change the salt in production - Update 'salt-change-in-production' to a unique, secure value
  2. SHA-256 vs bcrypt - SHA-256 is used because bcrypt is not natively available in Cloudflare Workers
  3. Salt storage - The salt is currently hardcoded; consider using environment variables
  4. Password requirements - Minimum 8 characters (enforced in validation schemas)

Password Validation

// Registration schema
const registerSchema = z.object({
  email: z.string().email('Valid email is required'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  username: z.string().min(3, 'Username must be at least 3 characters'),
  firstName: z.string().min(1, 'First name is required'),
  lastName: z.string().min(1, 'Last name is required')
})

Password History

Passwords are tracked in the password_history table for security:

CREATE TABLE password_history (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  password_hash TEXT NOT NULL,
  created_at INTEGER NOT NULL
);

Role-Based Access Control

Available Roles

Role Description Typical Use Case
admin Full system access System administrators
editor Content management Content managers and editors
viewer Read-only access Basic users, guests

Note: The author role exists in team contexts but not as a global role.

Permission Matrix

Permission Category Admin Editor Viewer
Content
Create content ✅ ✅ ❌
Read content ✅ ✅ ✅
Update content ✅ ✅ ❌
Delete content ✅ ❌ ❌
Publish content ✅ ✅ ❌
Collections
Create collections ✅ ❌ ❌
Read collections ✅ ✅ ✅
Update collections ✅ ❌ ❌
Delete collections ✅ ❌ ❌
Manage fields ✅ ❌ ❌
Media
Upload media ✅ ✅ ❌
Read media ✅ ✅ ✅
Update media ✅ ✅ ❌
Delete media ✅ ❌ ❌
Users
Create/invite users ✅ ❌ ❌
Read users ✅ ✅ ✅
Update users ✅ ❌ ❌
Delete users ✅ ❌ ❌
Manage roles ✅ ❌ ❌
Settings
Read settings ✅ ❌ ❌
Update settings ✅ ❌ ❌
View activity logs ✅ ❌ ❌

Role Middleware

import { requireAuth, requireRole } from '../middleware/auth'

// Require authentication only
app.get('/protected', requireAuth(), (c) => {
  const user = c.get('user')
  return c.json({ message: 'Authenticated', user })
})

// Require specific role (single)
app.delete('/admin/users/:id',
  requireAuth(),
  requireRole('admin'),
  (c) => {
    // Admin-only endpoint
  }
)

// Require one of multiple roles
app.post('/content',
  requireAuth(),
  requireRole(['admin', 'editor']),
  (c) => {
    // Admin or editor can create content
  }
)

Implementation:

export const requireRole = (requiredRole: string | string[]) => {
  return async (c: Context, next: Next) => {
    const user = c.get('user') as JWTPayload

    if (!user) {
      return c.json({ error: 'Authentication required' }, 401)
    }

    const roles = Array.isArray(requiredRole) ? requiredRole : [requiredRole]

    if (!roles.includes(user.role)) {
      return c.json({ error: 'Insufficient permissions' }, 403)
    }

    return await next()
  }
}

Permission System

SonicJS AI implements a granular permission system on top of RBAC.

Permission Structure

export interface Permission {
  id: string;           // e.g., 'perm_content_create'
  name: string;         // e.g., 'content.create'
  description: string;  // Human-readable description
  category: string;     // content, users, collections, media, settings
}

export interface UserPermissions {
  userId: string;
  role: string;
  permissions: string[];                    // Global permissions
  teamPermissions?: Record<string, string[]>; // Team-specific permissions
}

Available Permissions

Content Permissions:

  • content.create - Create new content
  • content.read - View content
  • content.update - Edit existing content
  • content.delete - Delete content
  • content.publish - Publish/unpublish content

Collections Permissions:

  • collections.create - Create new collections
  • collections.read - View collections
  • collections.update - Edit collections
  • collections.delete - Delete collections
  • collections.fields - Manage collection fields

Media Permissions:

  • media.upload - Upload media files
  • media.read - View media files
  • media.update - Edit media metadata
  • media.delete - Delete media files

Users Permissions:

  • users.create - Invite new users
  • users.read - View user profiles
  • users.update - Edit user profiles
  • users.delete - Deactivate users
  • users.roles - Manage user roles

Settings Permissions:

  • settings.read - View system settings
  • settings.update - Modify system settings
  • activity.read - View activity logs

Permission Manager

import { PermissionManager } from '../middleware/permissions'

// Check if user has permission
const canEdit = await PermissionManager.hasPermission(
  db,
  userId,
  'content.update'
)

if (!canEdit) {
  return c.json({ error: 'Permission denied' }, 403)
}

// Check multiple permissions at once
const permissions = await PermissionManager.checkMultiplePermissions(
  db,
  userId,
  ['content.create', 'content.publish']
)

console.log(permissions)
// { 'content.create': true, 'content.publish': false }

Permission Middleware

import { requirePermission, requireAnyPermission } from '../middleware/permissions'

// Require specific permission
app.delete('/content/:id',
  requireAuth(),
  requirePermission('content.delete'),
  async (c) => {
    // User has content.delete permission
  }
)

// Require any of multiple permissions
app.post('/content/:id/publish',
  requireAuth(),
  requireAnyPermission(['content.publish', 'content.update']),
  async (c) => {
    // User has either content.publish OR content.update
  }
)

Team-Based Permissions

// Check team-specific permission
const canEditInTeam = await PermissionManager.hasPermission(
  db,
  userId,
  'content.update',
  teamId  // Optional team context
)

// Middleware with team context
app.put('/teams/:teamId/content/:contentId',
  requireAuth(),
  requirePermission('content.update', 'teamId'),
  async (c) => {
    // User has content.update permission in this specific team
  }
)

Permission Caching

The PermissionManager implements in-memory caching:

export class PermissionManager {
  private static permissionCache = new Map<string, UserPermissions>()
  private static cacheExpiry = new Map<string, number>()
  private static CACHE_TTL = 5 * 60 * 1000 // 5 minutes

  static async getUserPermissions(db: D1Database, userId: string): Promise<UserPermissions> {
    const cacheKey = `permissions:${userId}`
    const now = Date.now()

    // Check cache
    if (this.permissionCache.has(cacheKey)) {
      const expiry = this.cacheExpiry.get(cacheKey) || 0
      if (now < expiry) {
        return this.permissionCache.get(cacheKey)!
      }
    }

    // Fetch from database and cache...
  }

  // Clear cache when permissions change
  static clearUserCache(userId: string) {
    const cacheKey = `permissions:${userId}`
    this.permissionCache.delete(cacheKey)
    this.cacheExpiry.delete(cacheKey)
  }
}

Auth Routes & Endpoints

Login Page

GET /auth/login

Renders the login HTML form. Supports query parameters:

  • ?error=<message> - Display error message
  • ?message=<message> - Display info message

Registration Page

GET /auth/register

Renders the registration HTML form.

Login (API)

POST /auth/login

// Request body
{
  "email": "user@example.com",
  "password": "password123"
}

// Success response (200)
{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "username",
    "firstName": "John",
    "lastName": "Doe",
    "role": "viewer"
  },
  "token": "jwt-token"
}

// Error response (401)
{
  "error": "Invalid email or password"
}

Login (Form)

POST /auth/login/form

Handles HTML form submissions. Returns HTMX-compatible HTML response.

Register (API)

POST /auth/register

// Request body
{
  "email": "user@example.com",
  "password": "password123",
  "username": "johndoe",
  "firstName": "John",
  "lastName": "Doe"
}

// Success response (201)
{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "role": "viewer"
  },
  "token": "jwt-token"
}

// Error response (400)
{
  "error": "User with this email or username already exists"
}

Register (Form)

POST /auth/register/form

Handles HTML form submissions. First user registered gets admin role.

Logout

GET /auth/logout or POST /auth/logout

Clears the auth_token cookie and redirects to login page.

// GET response
// Redirects to /auth/login?message=You have been logged out successfully

// POST response (200)
{
  "message": "Logged out successfully"
}

Get Current User

GET /auth/me

Requires authentication.

// Headers
Authorization: Bearer <token>

// Response (200)
{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "johndoe",
    "first_name": "John",
    "last_name": "Doe",
    "role": "viewer",
    "created_at": 1234567890000
  }
}

Refresh Token

POST /auth/refresh

Requires authentication. Generates a new token with extended expiration.

// Headers
Authorization: Bearer <current-token>

// Response (200)
{
  "token": "new-jwt-token"
}

Seed Admin User (Development)

POST /auth/seed-admin

Creates default admin user for testing. Not for production use.

// Response (200)
{
  "message": "Admin user created successfully",
  "user": {
    "id": "admin-user-id",
    "email": "admin@sonicjs.com",
    "username": "admin",
    "role": "admin"
  }
}

// Default credentials
// Email: admin@sonicjs.com
// Password: sonicjs!

Session Management

HTTP-Only Cookies

SonicJS AI uses secure, HTTP-only cookies for session management:

setCookie(c, 'auth_token', token, {
  httpOnly: true,      // Cannot be accessed via JavaScript
  secure: true,        // HTTPS only in production
  sameSite: 'Strict',  // CSRF protection
  maxAge: 60 * 60 * 24 // 24 hours
})

Session Tracking

Sessions are tracked in the user_sessions table:

CREATE TABLE user_sessions (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  token_hash TEXT NOT NULL,
  ip_address TEXT,
  user_agent TEXT,
  is_active INTEGER NOT NULL DEFAULT 1,
  expires_at INTEGER NOT NULL,
  created_at INTEGER NOT NULL,
  last_used_at INTEGER
);

Token Extraction

The requireAuth() middleware supports multiple token sources:

// 1. Authorization header (Bearer token)
Authorization: Bearer <token>

// 2. HTTP-only cookie
Cookie: auth_token=<token>

// Priority: Header > Cookie

Session Expiration

  • Token expiration: 24 hours from issue time
  • Cookie expiration: 24 hours (maxAge)
  • Cache expiration: 5 minutes (KV TTL)

When a token expires:

  1. JWT verification fails
  2. User redirected to login (HTML requests)
  3. 401 error returned (API requests)

User Invitation System

Inviting Users

POST /admin/users/invite (admin-only)

{
  "email": "newuser@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "editor"
}

Process:

  1. Admin creates user record with is_active = 0
  2. Unique invitation_token generated
  3. Invitation email sent (or link returned for dev)
  4. User account inactive until accepted

Accepting Invitation

GET /auth/accept-invitation?token=<invitation-token>

Displays invitation acceptance form with:

  • Pre-filled user details (name, email, role)
  • Username input
  • Password input
  • Confirm password input

POST /auth/accept-invitation

// Form data
{
  "token": "invitation-token",
  "username": "janesmith",
  "password": "securePassword123",
  "confirm_password": "securePassword123"
}

Process:

  1. Validate invitation token
  2. Check token expiration (7 days)
  3. Verify username availability
  4. Hash password
  5. Activate user (is_active = 1)
  6. Clear invitation_token
  7. Auto-login with JWT token
  8. Redirect to admin dashboard

Invitation Expiration

Invitations expire after 7 days:

const invitationAge = Date.now() - invitedUser.invited_at
const maxAge = 7 * 24 * 60 * 60 * 1000 // 7 days

if (invitationAge > maxAge) {
  return c.json({ error: 'Invitation has expired' }, 400)
}

Password Reset Flow

Request Password Reset

POST /auth/request-password-reset

// Form data
{
  "email": "user@example.com"
}

// Response (always success to prevent email enumeration)
{
  "success": true,
  "message": "If an account with this email exists, a password reset link has been sent.",
  "reset_link": "http://localhost:8787/auth/reset-password?token=..." // Dev only
}

Process:

  1. Normalize email to lowercase
  2. Look up user (returns success even if not found)
  3. Generate unique password_reset_token
  4. Set expiration: 1 hour
  5. Update user record
  6. Send reset email (or return link in dev)
  7. Log activity

Reset Password Form

GET /auth/reset-password?token=<reset-token>

Displays password reset form if token is valid and not expired.

Reset Password

POST /auth/reset-password

// Form data
{
  "token": "reset-token",
  "password": "newPassword123",
  "confirm_password": "newPassword123"
}

Process:

  1. Validate reset token
  2. Check expiration (1 hour)
  3. Verify passwords match
  4. Hash new password
  5. Store old password in password_history
  6. Update user with new password
  7. Clear reset token
  8. Log activity
  9. Redirect to login

Reset Token Expiration

Reset tokens expire after 1 hour:

const resetExpires = Date.now() + (60 * 60 * 1000) // 1 hour

if (Date.now() > user.password_reset_expires) {
  return c.json({ error: 'Reset token has expired' }, 400)
}

Implementing Authentication in Routes

Basic Authentication

import { Hono } from 'hono'
import { requireAuth } from '../middleware/auth'

const app = new Hono()

// Public route
app.get('/public', (c) => {
  return c.json({ message: 'Public access' })
})

// Protected route
app.get('/protected', requireAuth(), (c) => {
  const user = c.get('user')
  return c.json({
    message: 'Authenticated access',
    userId: user.userId,
    email: user.email,
    role: user.role
  })
})

Role-Based Routes

import { requireAuth, requireRole } from '../middleware/auth'

// Admin only
app.delete('/admin/users/:id',
  requireAuth(),
  requireRole('admin'),
  async (c) => {
    const userId = c.req.param('id')
    // Delete user logic
    return c.json({ message: 'User deleted' })
  }
)

// Editor or Admin
app.post('/content',
  requireAuth(),
  requireRole(['admin', 'editor']),
  async (c) => {
    const data = await c.req.json()
    // Create content logic
    return c.json({ message: 'Content created' })
  }
)

Permission-Based Routes

import { requireAuth } from '../middleware/auth'
import { requirePermission, requireAnyPermission } from '../middleware/permissions'

// Single permission required
app.post('/content/:id/publish',
  requireAuth(),
  requirePermission('content.publish'),
  async (c) => {
    const contentId = c.req.param('id')
    // Publish content logic
    return c.json({ message: 'Content published' })
  }
)

// Any permission required
app.put('/content/:id',
  requireAuth(),
  requireAnyPermission(['content.update', 'content.publish']),
  async (c) => {
    const contentId = c.req.param('id')
    const data = await c.req.json()
    // Update content logic
    return c.json({ message: 'Content updated' })
  }
)

// Multiple permissions required
app.delete('/content/:id',
  requireAuth(),
  PermissionManager.requirePermissions(['content.delete', 'content.update']),
  async (c) => {
    const contentId = c.req.param('id')
    // Delete content logic
    return c.json({ message: 'Content deleted' })
  }
)

Optional Authentication

import { optionalAuth } from '../middleware/auth'

// Route accessible to both authenticated and anonymous users
app.get('/content/:id',
  optionalAuth(),
  async (c) => {
    const user = c.get('user') // May be undefined
    const contentId = c.req.param('id')

    if (user) {
      // Return full content for authenticated users
      return c.json({ content: fullContent })
    } else {
      // Return limited content for anonymous users
      return c.json({ content: publicContent })
    }
  }
)

Custom Authorization Logic

app.put('/content/:id',
  requireAuth(),
  async (c) => {
    const user = c.get('user')
    const contentId = c.req.param('id')
    const db = c.env.DB

    // Fetch content
    const content = await db.prepare('SELECT * FROM content WHERE id = ?')
      .bind(contentId)
      .first()

    // Custom authorization: user must be admin, editor, or content owner
    const canEdit =
      user.role === 'admin' ||
      user.role === 'editor' ||
      content.author_id === user.userId

    if (!canEdit) {
      return c.json({ error: 'You do not have permission to edit this content' }, 403)
    }

    // Update content logic
    return c.json({ message: 'Content updated' })
  }
)

Activity Logging

import { logActivity } from '../middleware/permissions'

app.delete('/content/:id',
  requireAuth(),
  requirePermission('content.delete'),
  async (c) => {
    const user = c.get('user')
    const contentId = c.req.param('id')
    const db = c.env.DB

    // Delete content
    await db.prepare('DELETE FROM content WHERE id = ?')
      .bind(contentId)
      .run()

    // Log the deletion
    await logActivity(
      db,
      user.userId,
      'content.deleted',
      'content',
      contentId,
      { title: 'Sample Content' },
      c.req.header('x-forwarded-for') || c.req.header('cf-connecting-ip'),
      c.req.header('user-agent')
    )

    return c.json({ message: 'Content deleted' })
  }
)

Full Example: Content API

import { Hono } from 'hono'
import { requireAuth, requireRole } from '../middleware/auth'
import { requirePermission } from '../middleware/permissions'
import { logActivity } from '../middleware/permissions'

const contentRoutes = new Hono<{ Bindings: Bindings; Variables: Variables }>()

// List content (public)
contentRoutes.get('/', async (c) => {
  const db = c.env.DB
  const { results } = await db.prepare('SELECT * FROM content WHERE status = ?')
    .bind('published')
    .all()
  return c.json({ content: results })
})

// Get single content (public)
contentRoutes.get('/:id', async (c) => {
  const db = c.env.DB
  const content = await db.prepare('SELECT * FROM content WHERE id = ?')
    .bind(c.req.param('id'))
    .first()

  if (!content) {
    return c.json({ error: 'Content not found' }, 404)
  }

  return c.json({ content })
})

// Create content (requires content.create permission)
contentRoutes.post('/',
  requireAuth(),
  requirePermission('content.create'),
  async (c) => {
    const user = c.get('user')
    const db = c.env.DB
    const data = await c.req.json()

    const contentId = crypto.randomUUID()
    const now = Date.now()

    await db.prepare(`
      INSERT INTO content (id, title, body, author_id, status, created_at, updated_at)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `).bind(
      contentId,
      data.title,
      data.body,
      user.userId,
      'draft',
      now,
      now
    ).run()

    // Log activity
    await logActivity(
      db, user.userId, 'content.created', 'content', contentId,
      { title: data.title },
      c.req.header('x-forwarded-for'),
      c.req.header('user-agent')
    )

    return c.json({ id: contentId, message: 'Content created' }, 201)
  }
)

// Update content (requires content.update permission OR ownership)
contentRoutes.put('/:id',
  requireAuth(),
  async (c) => {
    const user = c.get('user')
    const db = c.env.DB
    const contentId = c.req.param('id')
    const data = await c.req.json()

    // Check ownership or permission
    const content = await db.prepare('SELECT * FROM content WHERE id = ?')
      .bind(contentId)
      .first() as any

    if (!content) {
      return c.json({ error: 'Content not found' }, 404)
    }

    const canEdit =
      user.role === 'admin' ||
      user.role === 'editor' ||
      content.author_id === user.userId

    if (!canEdit) {
      return c.json({ error: 'Permission denied' }, 403)
    }

    await db.prepare('UPDATE content SET title = ?, body = ?, updated_at = ? WHERE id = ?')
      .bind(data.title, data.body, Date.now(), contentId)
      .run()

    await logActivity(
      db, user.userId, 'content.updated', 'content', contentId,
      { title: data.title },
      c.req.header('x-forwarded-for'),
      c.req.header('user-agent')
    )

    return c.json({ message: 'Content updated' })
  }
)

// Delete content (admin or editor only)
contentRoutes.delete('/:id',
  requireAuth(),
  requireRole(['admin', 'editor']),
  requirePermission('content.delete'),
  async (c) => {
    const user = c.get('user')
    const db = c.env.DB
    const contentId = c.req.param('id')

    await db.prepare('DELETE FROM content WHERE id = ?')
      .bind(contentId)
      .run()

    await logActivity(
      db, user.userId, 'content.deleted', 'content', contentId,
      {},
      c.req.header('x-forwarded-for'),
      c.req.header('user-agent')
    )

    return c.json({ message: 'Content deleted' })
  }
)

export { contentRoutes }

Security Best Practices

1. Production JWT Secret

Never use default JWT secret in production.

# Generate a secure random secret
openssl rand -base64 32

# Add to wrangler.toml
[vars]
JWT_SECRET = "your-secure-random-256-bit-secret"

2. Change Password Salt

Update the salt in src/middleware/auth.ts:

// BEFORE (insecure)
const data = encoder.encode(password + 'salt-change-in-production')

// AFTER (secure)
const SALT = c.env.PASSWORD_SALT || 'your-unique-production-salt'
const data = encoder.encode(password + SALT)

Better yet, use environment-specific salts:

# wrangler.toml
[vars]
PASSWORD_SALT = "your-unique-production-salt-value"

3. HTTPS Only

Always use HTTPS in production:

setCookie(c, 'auth_token', token, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production', // true in production
  sameSite: 'Strict',
  maxAge: 60 * 60 * 24
})

4. Rate Limiting

Implement rate limiting for auth endpoints:

// Example with Cloudflare rate limiting
const RATE_LIMITS = {
  login: 5,        // 5 attempts
  register: 3,     // 3 attempts
  resetPassword: 2 // 2 attempts
}

5. Password Requirements

Enforce strong passwords:

const strongPasswordSchema = z.string()
  .min(12, 'Password must be at least 12 characters')
  .regex(/[A-Z]/, 'Password must contain uppercase letter')
  .regex(/[a-z]/, 'Password must contain lowercase letter')
  .regex(/[0-9]/, 'Password must contain number')
  .regex(/[^A-Za-z0-9]/, 'Password must contain special character')

6. Email Verification

Implement email verification:

// On registration
const emailVerificationToken = crypto.randomUUID()

await db.prepare(`
  UPDATE users SET
    email_verified = 0,
    email_verification_token = ?
  WHERE id = ?
`).bind(emailVerificationToken, userId).run()

// Send verification email with token

7. Two-Factor Authentication (2FA)

Enable 2FA for sensitive accounts:

ALTER TABLE users ADD COLUMN two_factor_enabled INTEGER DEFAULT 0;
ALTER TABLE users ADD COLUMN two_factor_secret TEXT;

8. Audit Logging

Always log security-sensitive actions:

await logActivity(
  db,
  user.userId,
  'user.login',
  'users',
  user.userId,
  { ip: ipAddress, userAgent },
  ipAddress,
  userAgent
)

9. Secure Headers

Set security headers:

// In your main app
app.use('*', async (c, next) => {
  await next()
  c.header('X-Frame-Options', 'DENY')
  c.header('X-Content-Type-Options', 'nosniff')
  c.header('Referrer-Policy', 'strict-origin-when-cross-origin')
  c.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')
})

10. Token Rotation

Implement token rotation for long-lived sessions:

// Refresh token every 6 hours
const shouldRotate = (payload.iat + (6 * 60 * 60)) < Date.now() / 1000

if (shouldRotate) {
  const newToken = await AuthManager.generateToken(
    payload.userId,
    payload.email,
    payload.role
  )
  // Return new token in response header
  c.header('X-New-Token', newToken)
}

11. CORS Configuration

Configure CORS properly:

import { cors } from 'hono/cors'

app.use('*', cors({
  origin: ['https://yourdomain.com'],
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowHeaders: ['Content-Type', 'Authorization'],
  credentials: true
}))

12. Input Validation

Always validate and sanitize input:

import { z } from 'zod'
import { zValidator } from '@hono/zod-validator'

const updateUserSchema = z.object({
  firstName: z.string().min(1).max(100),
  lastName: z.string().min(1).max(100),
  email: z.string().email()
})

app.put('/user/:id',
  requireAuth(),
  zValidator('json', updateUserSchema),
  async (c) => {
    const data = c.req.valid('json') // Validated data
    // Update logic
  }
)

Troubleshooting

Token Validation Errors

Problem: Invalid or expired token

Solutions:

  1. Check JWT_SECRET matches between token generation and verification
  2. Verify token hasn't expired (check exp claim)
  3. Ensure token is properly formatted (Bearer )
  4. Check KV cache for stale data
// Debug token
const parts = token.split('.')
const payload = JSON.parse(atob(parts[1]))
console.log('Token payload:', payload)
console.log('Expired?', payload.exp < Date.now() / 1000)

Permission Denied Errors

Problem: Permission denied: content.update

Solutions:

  1. Check user role in database
  2. Verify role_permissions mapping
  3. Clear permission cache
  4. Check team membership (for team permissions)
-- Check user role
SELECT role FROM users WHERE id = 'user-id';

-- Check role permissions
SELECT p.name
FROM role_permissions rp
JOIN permissions p ON rp.permission_id = p.id
WHERE rp.role = 'editor';

-- Check user's team permissions
SELECT tm.role, tm.permissions
FROM team_memberships tm
WHERE tm.user_id = 'user-id';
// Clear permission cache
PermissionManager.clearUserCache(userId)
PermissionManager.clearAllCache()

Problem: Auth cookie not being sent/received

Solutions:

  1. Verify secure flag matches protocol (HTTP vs HTTPS)
  2. Check sameSite setting
  3. Ensure domain matches
  4. Check browser console for cookie errors
// Development (HTTP)
setCookie(c, 'auth_token', token, {
  httpOnly: true,
  secure: false,  // false for localhost HTTP
  sameSite: 'Lax', // Lax for development
  maxAge: 60 * 60 * 24
})

// Production (HTTPS)
setCookie(c, 'auth_token', token, {
  httpOnly: true,
  secure: true,   // true for HTTPS
  sameSite: 'Strict',
  maxAge: 60 * 60 * 24
})

KV Cache Issues

Problem: Stale cached data

Solutions:

  1. Wait for cache expiration (5 minutes)
  2. Manually clear KV keys
  3. Check KV namespace binding
// Clear cached token verification
const cacheKey = `auth:${token.substring(0, 20)}`
await kv.delete(cacheKey)

// Clear user cache
await cache.delete(`user:${userId}`)
await cache.delete(`user:email:${email}`)

Password Verification Failed

Problem: Valid password rejected

Solutions:

  1. Check salt matches between hash and verify
  2. Verify password_hash in database
  3. Check for encoding issues
  4. Ensure consistent salt usage
// Test password hashing
const password = 'test123'
const hash1 = await AuthManager.hashPassword(password)
const hash2 = await AuthManager.hashPassword(password)
console.log('Hashes match?', hash1 === hash2) // Should be true

const valid = await AuthManager.verifyPassword(password, hash1)
console.log('Verification works?', valid) // Should be true

Database Connection Issues

Problem: User not found or database errors

Solutions:

  1. Check D1 database binding in wrangler.toml
  2. Verify migrations have run
  3. Check table structure
# Check D1 binding
wrangler d1 execute DB --command "SELECT * FROM users LIMIT 1"

# Check table exists
wrangler d1 execute DB --command "SELECT name FROM sqlite_master WHERE type='table'"

# Run migrations
wrangler d1 execute DB --file=./migrations/001_initial_schema.sql

Invitation/Reset Token Issues

Problem: Token expired or invalid

Solutions:

  1. Check token expiration timestamps
  2. Verify token matches in database
  3. Ensure token hasn't been used
-- Check invitation token
SELECT id, email, invitation_token, invited_at, is_active
FROM users
WHERE invitation_token = 'token-value';

-- Check password reset token
SELECT id, email, password_reset_token, password_reset_expires
FROM users
WHERE password_reset_token = 'token-value';

Activity Logging Failures

Problem: Activity logs not being created

Solutions:

  1. Check activity_logs table exists
  2. Verify logActivity is awaited
  3. Check for silent failures
// Add error handling
try {
  await logActivity(db, userId, action, resourceType, resourceId, details, ip, ua)
} catch (error) {
  console.error('Failed to log activity:', error)
  // Continue - don't break main operation
}