@serafort/cloudflare-workers

Enterprise IAM, Edge Tenant Routing, KV Token Caching, and Web Crypto JWT validation for Cloudflare Workers.

Features

• ⚡ Zero-Dependency Web Crypto: Local JWKS token validation in microseconds at the Cloudflare Edge using standard Web APIs.
• 🏢 Edge Tenant Routing: Subdomain (tenant.example.com) and header (X-Tenant-ID) resolution with cross-tenant boundary verification before reaching origin servers.
• 🛡️ Edge Middleware Wrapper: withSerafortAuth(handler, protectOptions, config) with wildcard RBAC (org:*), route exemptions, and automated 302 redirects or 401 JSON responses.
• 🗄️ Cloudflare KV Caching: KVCacheAdapter for fast caching of M2M tokens across globally distributed edge datacenters.
• 🔀 Header Decoration: Injects x-serafort-user-id, x-serafort-tenant-id, and x-serafort-roles headers for origin microservices.

Installation

npm install @serafort/cloudflare-workers @serafort/core

Quick Start

// src/index.ts
import { withSerafortAuth, type WorkerAuthContext } from '@serafort/cloudflare-workers';

interface Env {
  SERAFORT_ENDPOINT: string;
}

export default {
  fetch: withSerafortAuth<Env>(
    async (request, env, ctx, auth: WorkerAuthContext) => {
      return new Response(JSON.stringify({
        message: 'Hello from Cloudflare Edge!',
        userId: auth.user?.userId,
        tenantId: auth.tenantId,
      }), {
        headers: { 'Content-Type': 'application/json' },
      });
    },
    {
      roles: ['admin'],
      permissions: ['org:*'],
    },
    {
      endpoint: 'https://api.serafort.com',
      publicRoutes: ['/health', '/api/public/*'],
      tenantSubdomain: true,
      loginUrl: 'https://app.serafort.com/login',
    }
  ),
};

Contributing

Before committing, changes are checked with pnpm run type-check. This is wired up two ways — pick whichever fits your setup:

• Husky (npm-idiomatic, default for contributors who run pnpm install): the prepare script installs a Husky hook automatically, so once you've run pnpm install in a git checkout, git commit runs the check for you.
• .githooks/ (portable, no Husky/Node required to install): run git config core.hooksPath .githooks once to point git directly at the checked-in .githooks/pre-commit script, which runs the same check.

Both hooks run the same command, so pick one — you don't need both active at once.

CI (.github/workflows/ci.yml) runs type-check, test, and build on every push to main and on every pull request.

License

MIT — see LICENSE.