API Reference

Core

WorkersAuth(config)

Creates the auth instance with handler, authenticate, authorize middleware, and admin API.

import { WorkersAuth } from 'workers-auth';

Config: WorkersAuthConfig

Returns: WorkersAuthInstance

---

Strategies

MagicLinkStrategy(config)

Passwordless email authentication via magic links.

import { MagicLinkStrategy } from 'workers-auth/authn/magic-link';

Config: { provider: EmailProvider, template: EmailTemplate, linkExpiry?: number }

Docs: Magic Links

GitHubStrategy(config)

GitHub OAuth 2.0 authentication.

import { GitHubStrategy } from 'workers-auth/authn/github';

Config: { clientId: string, clientSecret: string, scopes?: string[] }

Docs: GitHub OAuth

---

Authorization

RBACPolicy(config)

Role-based access control policy.

import { RBACPolicy } from 'workers-auth/authz/rbac';

Config: { roles: Record<string, string[]>, defaultRole: string }

Docs: RBAC

---

Adapters

D1Adapter(binding)

Database adapter for Cloudflare D1. Implements DatabaseAdapter.

import { D1Adapter } from 'workers-auth/adapters/d1';

Docs: D1 Adapter

KVAdapter(binding)

Cache adapter for Cloudflare Workers KV. Implements CacheAdapter.

import { KVAdapter } from 'workers-auth/adapters/kv';

Docs: KV Adapter

---

Providers

ResendProvider(config)

Email provider using the Resend API. Implements EmailProvider.

import { ResendProvider } from 'workers-auth/providers/resend';

Config: { apiKey: string, from: string }

Docs: Resend Provider

---

Templates

defaultTemplate

Built-in email template for magic link emails.

import { defaultTemplate } from 'workers-auth/templates/default';

---

Types

All types are exported from the main entry point:

import type {
  User,
  Session,
  AuthStrategy,
  AuthorizationPolicy,
  EmailProvider,
  EmailTemplate,
  DatabaseAdapter,
  CacheAdapter,
  SessionConfig,
  SessionManager,
  AuthzRequirement,
  WorkersAuthConfig,
  AuthContext,
  WorkersAuthInstance,
} from 'workers-auth';

WorkersAuthConfig

interface WorkersAuthConfig {
  database: (binding: any) => DatabaseAdapter;
  cache: (binding: any) => CacheAdapter;
  authn: {
    strategies: AuthStrategy[];
    session?: SessionConfig;
  };
  authz?: AuthorizationPolicy;
  redirectUrl: string;
}

WorkersAuthInstance

interface WorkersAuthInstance {
  handler: Hono<any>;
  authenticate: (c: any, next: any) => Promise<Response | void>;
  authorize: (type: 'role' | 'permission', value: string) => (c: any, next: any) => Promise<Response | void>;
  admin: Hono<any>;
}

SessionConfig

interface SessionConfig {
  duration?: number;    // seconds, default 30 days (2592000)
  rolling?: boolean;    // extend on activity, default true
  cookieName?: string;  // default 'session'
  secret?: string;      // HMAC signing secret
}

User

interface User {
  id: string;
  email: string;
  status: 'active' | 'banned';
  createdAt: number;
  updatedAt: number;
}

Session

interface Session {
  id: string;
  userId: string;
  expiresAt: number;
  createdAt: number;
}

DatabaseAdapter

interface DatabaseAdapter {
  initialize(): Promise<void>;
  findUserByEmail(email: string): Promise<User | null>;
  findUserById(id: string): Promise<User | null>;
  createUser(email: string): Promise<User>;
  createSession(userId: string, expiresAt: number): Promise<Session>;
  getSession(sessionId: string): Promise<Session | null>;
  deleteSession(sessionId: string): Promise<void>;
  deleteUserSessions(userId: string): Promise<string[]>;
  listUsers(limit: number, offset: number): Promise<{ users: User[]; total: number }>;
  updateUserStatus(userId: string, status: 'active' | 'banned'): Promise<void>;
  getUserRoles(userId: string): Promise<string[]>;
  setUserRoles(userId: string, roles: string[]): Promise<void>;
  addUserRole(userId: string, role: string): Promise<void>;
  removeUserRole(userId: string, role: string): Promise<void>;
}

CacheAdapter

interface CacheAdapter {
  get(key: string): Promise<string | null>;
  set(key: string, value: string, ttl?: number): Promise<void>;
  delete(key: string): Promise<void>;
}

EmailProvider

interface EmailProvider {
  send(options: { to: string; subject: string; html: string }): Promise<void>;
}

EmailTemplate

type EmailTemplate = (props: {
  url: string;
  email: string;
  expiresIn: string;
}) => { subject: string; html: string };

AuthStrategy

interface AuthStrategy {
  name: string;
  routes(ctx: AuthContext): Hono<any>;
}

AuthorizationPolicy

interface AuthorizationPolicy {
  name: string;
  initialize(db: DatabaseAdapter): Promise<void>;
  onUserCreated(userId: string, db: DatabaseAdapter): Promise<void>;
  check(user: User, requirement: AuthzRequirement, db: DatabaseAdapter): Promise<boolean>;
  getUserRoles(userId: string, db: DatabaseAdapter): Promise<string[]>;
  getUserPermissions(userId: string, db: DatabaseAdapter): Promise<string[]>;
  assignRole(userId: string, role: string, db: DatabaseAdapter): Promise<void>;
  removeRole(userId: string, role: string, db: DatabaseAdapter): Promise<void>;
}

AuthzRequirement

type AuthzRequirement =
  | { type: 'role'; value: string }
  | { type: 'permission'; value: string };