@airdraft/plugin-auth

Authentication plugin for Airdraft. Adds email/password login, OAuth (GitHub, Google), team invitations, and role-based access control to your CMS.

Installation

npm install @airdraft/plugin-auth

Usage

withAutoAuth (recommended)

Auto-selects the provider based on environment variables. Uses CredentialsProvider when AIRDRAFT_JWT_SECRET is set, falling back to a read-only API-key-only mode otherwise.

import { withAutoAuth } from '@airdraft/plugin-auth'

const auth = await withAutoAuth()

export const airdraft = defineConfig({
  adapter,
  collections,
  plugins: [auth],
})

withAuth (explicit)

import { withAuth, CredentialsProvider } from '@airdraft/plugin-auth'

const auth = withAuth({
  provider: CredentialsProvider({
    userStore,
    secret: process.env.AIRDRAFT_JWT_SECRET!,
  }),
  publicPaths: ['/api/cms/posts'],  // optional — bypass auth on specific routes
})

Providers

CredentialsProvider

Email/password login stored in .airdraft/users.json.

import { CredentialsProvider, UserStore } from '@airdraft/plugin-auth'

const userStore = new UserStore()  // reads .airdraft/users.json

CredentialsProvider({
  userStore,
  secret: process.env.AIRDRAFT_JWT_SECRET!,
  roles: { '[email protected]': 'admin' },  // optional per-email role overrides
  basePath: '/api/cms',
})

GitHubOAuthProvider

GitHub OAuth login. Supports allowlists by user login or organisation membership.

import { GitHubOAuthProvider } from '@airdraft/plugin-auth'

GitHubOAuthProvider({
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  secret: process.env.AIRDRAFT_JWT_SECRET!,
  allowedOrgs: ['my-org'],         // optional
  allowedUsers: ['my-user'],       // optional
  defaultRole: 'editor',           // default: 'editor'
})

GoogleOAuthProvider

Google OAuth login. Supports allowlists by email address or domain.

import { GoogleOAuthProvider } from '@airdraft/plugin-auth'

GoogleOAuthProvider({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  secret: process.env.AIRDRAFT_JWT_SECRET!,
  allowedDomains: ['mycompany.com'],
  defaultRole: 'editor',
})

UserStore

Manages users and invitations stored in .airdraft/users.json.

import { UserStore } from '@airdraft/plugin-auth'

const userStore = new UserStore()

// Add a user
await userStore.addUser({ email: '[email protected]', role: 'admin', passwordHash: '...' })

// Create an invite
const invite = await userStore.createInvite({ email: '[email protected]', role: 'editor' })

// Accept an invite
await userStore.acceptInvite(invite.token, { password: 'secure123' })

The JSON file path can be overridden:

const userStore = new UserStore({ path: './.airdraft/users.json' })

getRequestUser(req)

Extracts and verifies the current user from a request (checks cookie, Bearer token, and X-API-Key header). Returns AuthUser | null.

import { getRequestUser } from '@airdraft/plugin-auth'

const user = getRequestUser(request)

refreshTokenBlocklist

In-memory blocklist for invalidated refresh tokens. Automatically cleared of expired entries on each check.

import { refreshTokenBlocklist } from '@airdraft/plugin-auth'

refreshTokenBlocklist.add(token)
refreshTokenBlocklist.has(token)  // returns false after TTL expires

Exports

| Export | Description | |---|---| | withAuth(options) | Creates the auth plugin with an explicit provider | | withAutoAuth(options?) | Auto-configured auth plugin | | CredentialsProvider(options) | Email/password provider | | GitHubOAuthProvider(options) | GitHub OAuth provider | | GoogleOAuthProvider(options) | Google OAuth provider | | UserStore | User and invite store backed by .airdraft/users.json | | getRequestUser(req) | Extract AuthUser from a request | | refreshTokenBlocklist | In-memory refresh token blocklist | | ROLE_PERMISSIONS | Record<Role, RolePermissions> constant | | can(user) | Returns RolePermissions for a user |

Changelog

See CHANGELOG.md.