worker-auth-providers

0.0.14-beta.10 verified Sat Apr 25 auth: no javascript

worker-auth-providers is an open-source library providing authentication providers for Cloudflare Workers. The current version is 0.0.14-beta.10, released as a beta with irregular cadence. It supports OAuth and OTP authentication for providers like GitHub, Google, Facebook, Discord, Spotify, Twilio, Mailgun, SendGrid, and AWS SNS. Designed specifically for Cloudflare Workers, it is lightweight with minimal dependencies. Key differentiators vs. alternatives like Auth0 or Passport.js: it runs at the edge with no external server, is framework-agnostic, and uses KV storage for OTPs. Types included.

Common errors

error TypeError: Cannot read properties of undefined (reading 'clientId') ↓

cause clientId option not passed or undefined in redirect call.

fix

Ensure options object is passed: github.redirect({ options: { clientId: 'YOUR_CLIENT_ID' } })

error Error: KV namespace not found ↓

cause WORKER_AUTH_PROVIDERS_STORE KV namespace not bound in wrangler.toml.

fix

Add kv_namespaces binding: [[kv_namespaces]] binding = "WORKER_AUTH_PROVIDERS_STORE" id = "your-kv-namespace-id"

error SyntaxError: Unexpected token 'export' ↓

cause Using CommonJS require() on ESM-only package.

fix

Use import syntax or set "type": "module" in package.json.

Warnings

breaking Package is pre-1.0.0 (beta) and APIs may change without notice. ↓

fix Pin to an exact version and update carefully.

deprecated apple provider was on roadmap but not yet exported; may be added in future. ↓

fix Check documentation for Apple export availability.

gotcha OTP providers (awsSNS, twilio, etc.) require a KV namespace named WORKER_AUTH_PROVIDERS_STORE for storing OTPs. ↓

fix Bind a KV namespace to WORKER_AUTH_PROVIDERS_STORE in wrangler.toml.

gotcha Some providers (e.g., facebook, discord, spotify) may have different options shapes; check types. ↓

fix Use TypeScript to validate options at compile time.

Install

npm install worker-auth-providers

yarn add worker-auth-providers

pnpm add worker-auth-providers

Imports

github

wrong

const github = require('worker-auth-providers')

correct

import { github } from 'worker-auth-providers'

Package is ESM-only; CJS require() will fail.

google

wrong

import Google from 'worker-auth-providers'

correct

import { google } from 'worker-auth-providers'

Google is a named export, not default.

awsSNS

import { awsSNS } from 'worker-auth-providers'

Available for OTP via AWS SNS.

Quickstart

Demonstrates GitHub OAuth login redirect and user retrieval in a Cloudflare Worker.

import { github, google } from 'worker-auth-providers';

async function handleRequest(request) {
  const clientId = process.env.GITHUB_CLIENT_ID ?? '';
  const clientSecret = process.env.GITHUB_CLIENT_SECRET ?? '';

  // Redirect to GitHub OAuth
  if (request.url.includes('/login/github')) {
    const githubLoginUrl = await github.redirect({
      options: { clientId },
    });
    return new Response(null, {
      status: 302,
      headers: { location: githubLoginUrl },
    });
  }

  // Handle callback and get user
  if (request.url.includes('/callback/github')) {
    const url = new URL(request.url);
    const code = url.searchParams.get('code');
    const { user, tokens } = await github.users({
      options: { clientSecret, clientId },
      request,
    });
    return new Response(JSON.stringify({ user, tokens }), {
      headers: { 'content-type': 'application/json' },
    });
  }

  return new Response('Hello Worker Auth!');
}

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});