Authentication

Secure your SonicJS application with JWT authentication and role-based access control.

Overview

SonicJS uses JWT (JSON Web Tokens) for authentication with:

• 24-hour token expiration
• HTTP-only cookie storage for web clients
• Bearer token support for API clients
• KV-based token caching (5-minute TTL)
• Role-based access control (RBAC)
• Permission system for fine-grained access

JWT Authentication

Login

curl -X POST http://localhost:8787/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@sonicjs.com",
    "password": "sonicjs!"
  }'

Response (200 OK):

{
  "user": {
    "id": "admin-user-id",
    "email": "admin@sonicjs.com",
    "username": "admin",
    "firstName": "Admin",
    "lastName": "User",
    "role": "admin"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Token

Include the token in the Authorization header for authenticated requests:

curl http://localhost:8787/admin/content \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

For browser-based applications, the token is automatically stored as an HTTP-only cookie named auth_token.

Passwordless Authentication

SonicJS offers multiple passwordless authentication methods through plugins. These plugins are inactive by default and need to be enabled in the admin panel.

OTP Login Plugin

The OTP (One-Time Password) Login Plugin provides email-based authentication with temporary codes.

Features:

• Configurable OTP code length (4-8 digits)
• Code expiration (5-60 minutes, default: 10 minutes)
• Rate limiting (default: 5 codes per hour)
• Max verification attempts (default: 3)
• Optional new user registration support

Installation:

1. Navigate to Admin → Plugins
2. Find OTP Login plugin
3. Click Activate
4. Configure settings:
   • Code Length: 4-8 digits (default: 6)
   • Code Expiration: 5-60 minutes (default: 10)
   • Max Attempts: 3-10 (default: 3)
   • Rate Limit: Codes per hour (default: 5)
   • Allow Registration: Enable if you want new users to register via OTP

API Usage:

# Step 1: Request OTP code
curl -X POST http://localhost:8787/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

# Response: { "message": "OTP code sent to email" }

Database Schema:

The OTP plugin creates a new table otp_codes:

CREATE TABLE otp_codes (
  id TEXT PRIMARY KEY,
  user_email TEXT NOT NULL,
  code TEXT NOT NULL,
  expires_at INTEGER NOT NULL,
  attempts INTEGER DEFAULT 0,
  created_at INTEGER DEFAULT (unixepoch())
);

Magic Link Authentication Plugin

The Magic Link Plugin enables passwordless login via email links.

Features:

• One-click email authentication
• No password required
• Secure token-based links
• Optional user registration

Installation:

1. Navigate to Admin → Plugins
2. Find Magic Link Auth plugin
3. Click Activate
4. Configure email settings (requires Email Plugin)

API Usage:

# Step 1: Request magic link
curl -X POST http://localhost:8787/auth/magic-link/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

# Response: { "message": "Magic link sent to email" }

Choosing an Authentication Method

OAuth / Social Login

SonicJS supports OAuth2 social login through the OAuth Providers plugin, allowing users to sign in with GitHub, Google, and other providers using the standard authorization code flow.

Supported Providers

Quick Setup

1. Create an OAuth app on the provider (GitHub or Google)
2. Navigate to Admin > Plugins > OAuth Providers
3. Enter your Client ID and Client Secret for each provider
4. Toggle Enable and save

OAuth Endpoints

Usage

Add social login buttons that point to the OAuth authorization endpoints:

<a href="/auth/oauth/github">Sign in with GitHub</a>
<a href="/auth/oauth/google">Sign in with Google</a>

When a user authenticates via OAuth:

• Existing OAuth link — the user is logged in directly
• Email matches an existing account — the OAuth provider is automatically linked to the existing account
• New user — an account is created from the OAuth profile with the viewer role

Account Linking and Unlinking

Authenticated users can link additional OAuth providers or unlink existing ones:

curl -X POST http://localhost:8787/auth/oauth/link \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{ "provider": "google" }'

# Response: { "redirectUrl": "https://accounts.google.com/..." }
# Redirect the user to the returned URL to complete linking

Choosing an Authentication Method (Updated)

User Management

User Registration

curl -X POST http://localhost:8787/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "username": "newuser",
    "firstName": "John",
    "lastName": "Doe"
  }'

User Profiles

SonicJS includes configurable user profiles that let you define custom fields for your users without modifying database migrations. Custom data is stored as JSON in the user_profiles.data column and rendered automatically in the admin UI.

Configuring Custom Profile Fields

Define custom fields at app boot using defineUserProfile():

import { SonicJS, defineUserProfile } from "@sonicjs-cms/core"

defineUserProfile({
  fields: [
    {
      name: "plan",
      label: "Subscription Plan",
      type: "select",
      options: ["free", "pro", "enterprise"],
      default: "free"
    },
    {
      name: "company_size",
      label: "Company Size",
      type: "number",
      required: true,
      validation: { min: 1, max: 10000 }
    },
    {
      name: "industry",
      label: "Industry",
      type: "select",
      options: ["tech", "healthcare", "finance", "education", "other"]
    },
    {
      name: "onboarding_completed",
      label: "Onboarding Completed",
      type: "boolean",
      default: false
    }
  ],
  // Optional: which custom fields appear on the registration form
  registrationFields: ["plan", "company_size"],
})

const app = SonicJS({ /* ... */ })

Custom fields support the same field types as collections: string, number, boolean, select, textarea, json, and object (for nested fields).

Field Definition Properties

Profile API Endpoints

Returns the configured field schema so frontend apps can render profile forms dynamically.

{
  "userId": "usr-xyz",
  "customData": {
    "plan": "pro",
    "company_size": 50,
    "industry": "tech"
  }
}

curl -X PUT http://localhost:8787/api/user-profiles/usr-xyz \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "customData": {
      "plan": "enterprise",
      "company_size": 200
    }
  }'

Validation errors return a structured response:

{
  "error": "Validation failed",
  "errors": {
    "plan": "Plan must be one of: free, pro, enterprise"
  }
}

Admin UI Integration

Custom profile fields appear automatically in:

• User edit page (/admin/users/:id/edit) — admins can edit any user's custom fields
• Profile page (/admin/profile) — users can edit their own custom fields

Fields are rendered below the standard profile fields (display name, bio, company, etc.) using the same dynamic field renderer as collections.

Registration Form Integration

When registrationFields is specified in the config, those custom fields are included in the registration form at /auth/register. Defaults from the field config are applied for any fields not included in registrationFields.

Built-in Profile Fields

Every user profile includes these standard fields out of the box:

Custom fields defined via defineUserProfile() extend these — they do not replace them.

RBAC

User Roles

SonicJS supports four built-in roles with specific enforcement across the system:

Permission Matrix

Default Roles

• The first registered user is automatically assigned the admin role
• All subsequent self-registered users default to the viewer role
• Admins can change user roles via the admin panel

Middleware

Protect routes with authentication and role-based middleware:

// Require authentication
app.use('/admin/*', requireAuth())

// Require specific role
app.use('/admin/*', requireRole(['admin', 'editor']))

// Require permission
app.use('/admin/settings/*', requirePermission('manage:settings'))

// Optional authentication
app.use('/api/*', optionalAuth())

The requireRole() middleware returns a 403 JSON response for API requests or redirects to /auth/login for browser requests. Role checking uses constant-time comparison to prevent timing attacks.

Security

Password Hashing

SonicJS uses PBKDF2-SHA256 with strong parameters for password storage:

• 100,000 iterations (NIST-recommended minimum)
• 16-byte random salt per password
• 256-bit derived key
• Format: pbkdf2:<iterations>:<salt_hex>:<hash_hex>

Legacy SHA-256 hashes are automatically upgraded to PBKDF2 on next successful login.

Rate Limiting

Authentication endpoints are protected with KV-based rate limiting:

Rate limiting uses Cloudflare KV for distributed state and gracefully degrades if KV is unavailable. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

CSRF Protection

SonicJS implements a signed double-submit cookie pattern for CSRF protection:

• Tokens are HMAC-SHA256 signed using the JWT_SECRET
• Validation checks the X-CSRF-Token header against the csrf_token cookie
• Falls back to reading _csrf from form body for traditional form submissions
• Cookie settings: sameSite: 'Strict', secure: true in production, 24-hour expiry

Exempt paths: Login, registration, public form submissions, and API-key-only requests are exempt from CSRF validation.

Security Headers

All responses include security headers:

Next Steps