@airdraft/auth

Low-level JWT utilities and RBAC types for Airdraft. Used internally by @airdraft/plugin-auth and @airdraft/next. You typically don't need this package directly unless you're building custom auth middleware or an Airdraft adapter.

Installation

npm install @airdraft/auth

RBAC

Roles

type Role = 'admin' | 'publisher' | 'editor'

| Role | Description | |---|---| | admin | Full access — manage schema, team, and content | | publisher | Can publish and delete published entries; no team/schema management | | editor | Can create and edit drafts; cannot publish or delete published entries |

RolePermissions

interface RolePermissions {
  publish: boolean
  deletePublished: boolean
  manageSchema: boolean
  manageTeam: boolean
}

ROLE_PERMISSIONS

import { ROLE_PERMISSIONS } from '@airdraft/auth'

ROLE_PERMISSIONS.admin     // { publish: true, deletePublished: true, manageSchema: true, manageTeam: true }
ROLE_PERMISSIONS.publisher // { publish: true, deletePublished: true, manageSchema: false, manageTeam: false }
ROLE_PERMISSIONS.editor    // { publish: false, deletePublished: false, manageSchema: false, manageTeam: false }

can(user)

Returns RolePermissions for the given user:

import { can } from '@airdraft/auth'

const perms = can(user)
if (perms.manageTeam) { /* ... */ }

Tokens

signAccessToken(user, secret, ttl?)

Signs a JWT access token. TTL defaults to ACCESS_TOKEN_TTL (15 minutes).

signRefreshToken()

Generates a random opaque refresh token string.

verifyAccessToken(token, secret)

Returns AuthUser | null. Returns null on expiry or invalid signature.

Token TTLs

import { ACCESS_TOKEN_TTL, REFRESH_TOKEN_TTL } from '@airdraft/auth'

ACCESS_TOKEN_TTL   // 14400 seconds (4 hours)
REFRESH_TOKEN_TTL  // 2592000 seconds (30 days)

API Keys

generateApiKey()

Generates a new API key pair. The returned key is a secret to be given to the client; hash is a SHA-256 hex digest to store server-side.

import { generateApiKey } from '@airdraft/auth'

const { key, hash } = generateApiKey()
// key: 'ntk_<64-char-hex>' — send to client once
// hash: '<sha256-hex>'    — store in database

verifyApiKey(raw, hash)

Returns true if the raw key matches the stored hash.

import { verifyApiKey } from '@airdraft/auth'

const valid = verifyApiKey(incoming, stored.hash)

Embed Tokens

Short-lived HMAC-SHA256 signed tokens for public read-only embeds. Tokens are base64url-encoded and verified with crypto.timingSafeEqual to prevent timing attacks.

import { generateEmbedToken, verifyEmbedToken } from '@airdraft/auth'

const token = generateEmbedToken(
  {
    projectId: 'proj_123',
    allowedOrigin: 'https://my-site.com',
    ttlSeconds: 3600,       // default 3600, max 86400
    claims: { collections: ['posts'] },  // optional
  },
  process.env.EMBED_TOKEN_SECRET!,
)

const result = verifyEmbedToken(token, process.env.EMBED_TOKEN_SECRET!, requestOrigin)
if (result.valid) {
  console.log(result.payload.projectId)
} else {
  // result.reason: 'expired' | 'origin_mismatch' | 'invalid_signature' | 'malformed'
}

Breaking change (v0.1.5): The embed token signature algorithm changed from a concatenated SHA-256 hash to proper HMAC-SHA256 (createHmac). Tokens issued by earlier versions will fail verification. Reissue any live embed tokens after upgrading.

Types

interface AuthUser {
  id: string
  email: string
  name?: string
  role: Role
  meta?: Record<string, unknown>
}

interface ApiKeyPair {
  key: string   // 'ntk_<64-char-hex>' — send to client once
  hash: string  // SHA-256 hex digest — store server-side, never return to clients
}

Changelog

See CHANGELOG.md.