JWT Authentication Guide

Fast-Crawl now supports JWT token authentication using the @elysiajs/jwt plugin. This service validates JWT tokens but does not create them - external services must provide valid encrypted JWT tokens.

Configuration

Set the JWT secret using the JWT_SECRET environment variable:

export JWT_SECRET="your-secret-key-for-jwt-validation"

Authentication Flow

1. Token Creation: External services create JWT tokens using the same secret
2. Token Validation: Fast-Crawl validates incoming JWT tokens using the configured secret
3. Request Processing: Valid tokens allow access to all API endpoints

Usage Examples

With JWT Token (Recommended)

# Using curl with JWT token
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     "http://localhost:3000/v1/search?q=typescript"

// Using fetch in JavaScript
const response = await fetch("http://localhost:3000/v1/search?q=typescript", {
  headers: {
    Authorization: "Bearer YOUR_JWT_TOKEN",
  },
});

With API Key (Legacy Support)

# Using curl with API key (still supported)
curl -H "x-api-key: YOUR_API_KEY" \
     "http://localhost:3000/v1/search?q=typescript"

Authentication Priority

1. JWT Token: If Authorization: Bearer <token> header is present, JWT validation is used
2. API Key: If no JWT token, falls back to x-api-key header validation
3. Development Mode: If neither JWT_SECRET nor API_KEY is configured, requests are allowed

Token Requirements

• Format: Standard JWT token structure (header.payload.signature)
• Algorithm: Supports HMAC and RSA algorithms
• Headers: Must be provided as Authorization: Bearer <token>
• Validation: Token must be signed with the same secret configured on the server

Error Responses

Invalid JWT Token

{
  "error": "Unauthorized: Invalid JWT token"
}

JWT Verification Failed

{
  "error": "Unauthorized: JWT token verification failed"
}

No JWT Configuration

{
  "error": "JWT authentication is not configured on the server"
}

Security Notes

• JWT tokens are validated but not created by this service
• External services must use the same secret to create valid tokens
• Both JWT and API key authentication can coexist
• JWT takes priority over API key if both are provided
• All endpoints require valid authentication when JWT_SECRET or API_KEY is configured

tRPC Integration

JWT authentication works seamlessly with both REST endpoints and tRPC procedures:

import { createTRPCClient, httpBatchLink } from "@trpc/client";
import type { AppRouter } from "./src/client-types";

const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: "http://localhost:3000/trpc",
      headers: {
        Authorization: "Bearer YOUR_JWT_TOKEN",
      },
    }),
  ],
});

// All tRPC calls will include JWT authentication
const results = await client.search.mutate({
  query: "typescript tutorial",
  providers: ["google", "bing"],
  count: 10,
});