@delmaredigital/payload-better-auth 0.3.6 → 0.3.8

package/src/utils/apiKeyAccess.ts

@@ -0,0 +1,443 @@
+/**
+ * API Key Scope Enforcement Utilities
+ *
+ * These utilities help enforce API key scopes in Payload access control.
+ * They extract the API key from requests, validate scopes, and provide
+ * type-safe access control functions.
+ *
+ * @example
+ * ```ts
+ * import { requireScope, requireAnyScope } from '@delmaredigital/payload-better-auth'
+ *
+ * export const Posts: CollectionConfig = {
+ *   slug: 'posts',
+ *   access: {
+ *     read: requireAnyScope(['posts:read', 'content:read']),
+ *     create: requireScope('posts:write'),
+ *     update: requireScope('posts:write'),
+ *     delete: requireScope('posts:delete'),
+ *   },
+ * }
+ * ```
+ */
+
+import type { Access, PayloadRequest } from 'payload'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ApiKeyInfo = {
+  /** The API key ID */
+  id: string
+  /** User ID who owns this key */
+  userId: string
+  /** Array of granted scope strings */
+  scopes: string[]
+  /** The raw key (only first/last chars visible) */
+  keyPrefix?: string
+  /** Optional metadata */
+  metadata?: Record<string, unknown>
+}
+
+export type ApiKeyAccessConfig = {
+  /**
+   * API keys collection slug.
+   * @default 'apiKeys' or 'api-keys' (auto-detected)
+   */
+  apiKeysCollection?: string
+  /**
+   * Allow access if user is authenticated (non-API key session).
+   * Useful for allowing both API keys and regular sessions.
+   * @default false
+   */
+  allowAuthenticatedUsers?: boolean
+  /**
+   * Custom function to extract API key from request.
+   * By default, extracts from Authorization: Bearer <key> header.
+   */
+  extractApiKey?: (req: PayloadRequest) => string | null
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract API key from request headers.
+ * Supports Bearer token format: Authorization: Bearer <api-key>
+ */
+export function extractApiKeyFromRequest(req: PayloadRequest): string | null {
+  const authHeader = req.headers?.get('authorization')
+  if (!authHeader) return null
+
+  // Support "Bearer <key>" format
+  if (authHeader.startsWith('Bearer ')) {
+    return authHeader.slice(7).trim()
+  }
+
+  // Support raw key in Authorization header
+  return authHeader.trim()
+}
+
+/**
+ * Look up API key info from the database.
+ * Returns null if key not found or disabled.
+ */
+export async function getApiKeyInfo(
+  req: PayloadRequest,
+  apiKey: string,
+  apiKeysCollection = 'apiKeys'
+): Promise<ApiKeyInfo | null> {
+  try {
+    // Try the provided collection name first
+    let results = await req.payload.find({
+      collection: apiKeysCollection,
+      where: {
+        key: { equals: apiKey },
+        enabled: { not_equals: false },
+      },
+      limit: 1,
+      depth: 0,
+    }).catch(() => null)
+
+    // If not found, try alternative slug
+    if (!results || results.docs.length === 0) {
+      const altSlug = apiKeysCollection === 'apiKeys' ? 'api-keys' : 'apiKeys'
+      results = await req.payload.find({
+        collection: altSlug,
+        where: {
+          key: { equals: apiKey },
+          enabled: { not_equals: false },
+        },
+        limit: 1,
+        depth: 0,
+      }).catch(() => null)
+    }
+
+    if (!results || results.docs.length === 0) {
+      return null
+    }
+
+    const doc = results.docs[0] as {
+      id: string | number
+      user?: string | number | { id: string | number }
+      userId?: string | number
+      permissions?: string
+      scopes?: string[]
+      start?: string
+      metadata?: string | Record<string, unknown>
+    }
+
+    // Parse scopes from permissions field (Better Auth format) or scopes array
+    let scopes: string[] = []
+    if (doc.permissions) {
+      try {
+        const parsed = JSON.parse(doc.permissions)
+        if (Array.isArray(parsed)) {
+          scopes = parsed
+        } else if (typeof parsed === 'object') {
+          // If it's an object, extract keys or flatten
+          scopes = Object.keys(parsed)
+        }
+      } catch {
+        // If not JSON, treat as comma-separated
+        scopes = doc.permissions.split(',').map((s) => s.trim()).filter(Boolean)
+      }
+    } else if (Array.isArray(doc.scopes)) {
+      scopes = doc.scopes
+    }
+
+    // Get user ID (handle both direct field and relationship)
+    let userId: string
+    if (doc.userId) {
+      userId = String(doc.userId)
+    } else if (doc.user) {
+      userId = typeof doc.user === 'object' ? String(doc.user.id) : String(doc.user)
+    } else {
+      return null
+    }
+
+    // Parse metadata
+    let metadata: Record<string, unknown> | undefined
+    if (doc.metadata) {
+      if (typeof doc.metadata === 'string') {
+        try {
+          metadata = JSON.parse(doc.metadata)
+        } catch {
+          // Ignore parse errors
+        }
+      } else {
+        metadata = doc.metadata
+      }
+    }
+
+    return {
+      id: String(doc.id),
+      userId,
+      scopes,
+      keyPrefix: doc.start,
+      metadata,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check if an API key has a specific scope.
+ * Supports wildcard patterns like 'posts:*' matching 'posts:read', 'posts:write', etc.
+ */
+export function hasScope(keyScopes: string[], requiredScope: string): boolean {
+  return keyScopes.some((scope) => {
+    // Exact match
+    if (scope === requiredScope) return true
+
+    // Wildcard match: 'posts:*' matches 'posts:read'
+    if (scope.endsWith(':*')) {
+      const prefix = scope.slice(0, -1) // Remove '*', keep ':'
+      return requiredScope.startsWith(prefix)
+    }
+
+    // Global wildcard
+    if (scope === '*') return true
+
+    return false
+  })
+}
+
+/**
+ * Check if an API key has any of the specified scopes.
+ */
+export function hasAnyScope(keyScopes: string[], requiredScopes: string[]): boolean {
+  return requiredScopes.some((scope) => hasScope(keyScopes, scope))
+}
+
+/**
+ * Check if an API key has all of the specified scopes.
+ */
+export function hasAllScopes(keyScopes: string[], requiredScopes: string[]): boolean {
+  return requiredScopes.every((scope) => hasScope(keyScopes, scope))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Access Control Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create an access control function that requires a specific scope.
+ *
+ * @param scope - The required scope string (e.g., 'posts:read')
+ * @param config - Configuration options
+ * @returns Payload access function
+ *
+ * @example
+ * ```ts
+ * access: {
+ *   read: requireScope('posts:read'),
+ *   create: requireScope('posts:write'),
+ * }
+ * ```
+ */
+export function requireScope(
+  scope: string,
+  config: ApiKeyAccessConfig = {}
+): Access {
+  const {
+    apiKeysCollection = 'apiKeys',
+    allowAuthenticatedUsers = false,
+    extractApiKey = extractApiKeyFromRequest,
+  } = config
+
+  return async ({ req }) => {
+    // If authenticated users are allowed and user is logged in without API key
+    if (allowAuthenticatedUsers && req.user) {
+      const apiKey = extractApiKey(req)
+      if (!apiKey) {
+        return true // User authenticated via session, no API key = allow
+      }
+    }
+
+    // Extract API key from request
+    const apiKey = extractApiKey(req)
+    if (!apiKey) {
+      return false
+    }
+
+    // Look up API key
+    const keyInfo = await getApiKeyInfo(req, apiKey, apiKeysCollection)
+    if (!keyInfo) {
+      return false
+    }
+
+    // Check scope
+    return hasScope(keyInfo.scopes, scope)
+  }
+}
+
+/**
+ * Create an access control function that requires any of the specified scopes.
+ *
+ * @param scopes - Array of acceptable scopes (at least one must match)
+ * @param config - Configuration options
+ * @returns Payload access function
+ *
+ * @example
+ * ```ts
+ * access: {
+ *   read: requireAnyScope(['posts:read', 'content:read', 'admin:*']),
+ * }
+ * ```
+ */
+export function requireAnyScope(
+  scopes: string[],
+  config: ApiKeyAccessConfig = {}
+): Access {
+  const {
+    apiKeysCollection = 'apiKeys',
+    allowAuthenticatedUsers = false,
+    extractApiKey = extractApiKeyFromRequest,
+  } = config
+
+  return async ({ req }) => {
+    // If authenticated users are allowed and user is logged in without API key
+    if (allowAuthenticatedUsers && req.user) {
+      const apiKey = extractApiKey(req)
+      if (!apiKey) {
+        return true
+      }
+    }
+
+    const apiKey = extractApiKey(req)
+    if (!apiKey) {
+      return false
+    }
+
+    const keyInfo = await getApiKeyInfo(req, apiKey, apiKeysCollection)
+    if (!keyInfo) {
+      return false
+    }
+
+    return hasAnyScope(keyInfo.scopes, scopes)
+  }
+}
+
+/**
+ * Create an access control function that requires all specified scopes.
+ *
+ * @param scopes - Array of required scopes (all must be present)
+ * @param config - Configuration options
+ * @returns Payload access function
+ *
+ * @example
+ * ```ts
+ * access: {
+ *   delete: requireAllScopes(['posts:delete', 'admin:write']),
+ * }
+ * ```
+ */
+export function requireAllScopes(
+  scopes: string[],
+  config: ApiKeyAccessConfig = {}
+): Access {
+  const {
+    apiKeysCollection = 'apiKeys',
+    allowAuthenticatedUsers = false,
+    extractApiKey = extractApiKeyFromRequest,
+  } = config
+
+  return async ({ req }) => {
+    // If authenticated users are allowed and user is logged in without API key
+    if (allowAuthenticatedUsers && req.user) {
+      const apiKey = extractApiKey(req)
+      if (!apiKey) {
+        return true
+      }
+    }
+
+    const apiKey = extractApiKey(req)
+    if (!apiKey) {
+      return false
+    }
+
+    const keyInfo = await getApiKeyInfo(req, apiKey, apiKeysCollection)
+    if (!keyInfo) {
+      return false
+    }
+
+    return hasAllScopes(keyInfo.scopes, scopes)
+  }
+}
+
+/**
+ * Create an access control function that allows either:
+ * 1. Authenticated users (via session)
+ * 2. API key with required scope
+ *
+ * This is useful for endpoints that should work with both auth methods.
+ *
+ * @param scope - The required scope for API key access
+ * @param config - Configuration options
+ * @returns Payload access function
+ *
+ * @example
+ * ```ts
+ * access: {
+ *   read: allowSessionOrScope('posts:read'),
+ * }
+ * ```
+ */
+export function allowSessionOrScope(
+  scope: string,
+  config: Omit<ApiKeyAccessConfig, 'allowAuthenticatedUsers'> = {}
+): Access {
+  return requireScope(scope, { ...config, allowAuthenticatedUsers: true })
+}
+
+/**
+ * Create an access control function that allows either:
+ * 1. Authenticated users (via session)
+ * 2. API key with any of the required scopes
+ *
+ * @param scopes - Array of acceptable scopes for API key access
+ * @param config - Configuration options
+ * @returns Payload access function
+ */
+export function allowSessionOrAnyScope(
+  scopes: string[],
+  config: Omit<ApiKeyAccessConfig, 'allowAuthenticatedUsers'> = {}
+): Access {
+  return requireAnyScope(scopes, { ...config, allowAuthenticatedUsers: true })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Better Auth Integration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate an API key and get its info.
+ *
+ * This performs a database lookup to validate the key and retrieve
+ * its associated scopes and user.
+ *
+ * @param req - Payload request
+ * @param apiKeysCollection - The API keys collection slug
+ * @returns API key info if valid, null otherwise
+ *
+ * @example
+ * ```ts
+ * const keyInfo = await validateApiKey(req)
+ * if (keyInfo) {
+ *   console.log('Valid API key for user:', keyInfo.userId)
+ *   console.log('Scopes:', keyInfo.scopes)
+ * }
+ * ```
+ */
+export async function validateApiKey(
+  req: PayloadRequest,
+  apiKeysCollection = 'apiKeys'
+): Promise<ApiKeyInfo | null> {
+  const apiKey = extractApiKeyFromRequest(req)
+  if (!apiKey) return null
+  return getApiKeyInfo(req, apiKey, apiKeysCollection)
+}

package/src/utils/betterAuthDefaults.ts

@@ -0,0 +1,102 @@
+/**
+ * Utility to apply sensible defaults to Better Auth options.
+ *
+ * @packageDocumentation
+ */
+
+import type { BetterAuthOptions } from 'better-auth'
+import { apiKey as betterAuthApiKey } from 'better-auth/plugins'
+
+type ApiKeyPluginOptions = Parameters<typeof betterAuthApiKey>[0]
+
+/**
+ * API Key plugin with sensible defaults for use with this package.
+ *
+ * Enables metadata storage by default so that scopes can be displayed
+ * in the admin UI after key creation.
+ *
+ * @example
+ * ```ts
+ * import { apiKeyWithDefaults } from '@delmaredigital/payload-better-auth'
+ *
+ * export const betterAuthOptions = {
+ *   plugins: [
+ *     apiKeyWithDefaults(),  // metadata enabled by default
+ *   ],
+ * }
+ * ```
+ *
+ * @example With custom options
+ * ```ts
+ * apiKeyWithDefaults({
+ *   rateLimit: { max: 100, window: 60 },
+ *   // enableMetadata is already true
+ * })
+ * ```
+ */
+export function apiKeyWithDefaults(options?: ApiKeyPluginOptions) {
+  return betterAuthApiKey({
+    enableMetadata: true,
+    ...options,
+  })
+}
+
+/**
+ * Applies sensible defaults to Better Auth options.
+ *
+ * Currently applies the following defaults:
+ * - `trustedOrigins`: If not explicitly provided but `baseURL` is set,
+ *   defaults to `[baseURL]`. This handles the common single-domain case
+ *   where the app's origin should be trusted for auth requests.
+ *
+ * Multi-domain setups can still explicitly set `trustedOrigins` to include
+ * multiple origins.
+ *
+ * @example Simple case - trustedOrigins defaults to [baseURL]
+ * ```ts
+ * import { withBetterAuthDefaults } from '@delmaredigital/payload-better-auth'
+ *
+ * const auth = betterAuth(withBetterAuthDefaults({
+ *   baseURL: 'https://myapp.com',
+ *   // trustedOrigins automatically becomes ['https://myapp.com']
+ * }))
+ * ```
+ *
+ * @example Multi-domain case - explicit trustedOrigins respected
+ * ```ts
+ * const auth = betterAuth(withBetterAuthDefaults({
+ *   baseURL: 'https://myapp.com',
+ *   trustedOrigins: ['https://myapp.com', 'https://other-domain.com'],
+ *   // trustedOrigins stays as explicitly provided
+ * }))
+ * ```
+ *
+ * @example With createBetterAuthPlugin
+ * ```ts
+ * createBetterAuthPlugin({
+ *   createAuth: (payload) => betterAuth(withBetterAuthDefaults({
+ *     database: payloadAdapter({ payloadClient: payload }),
+ *     baseURL: process.env.BETTER_AUTH_URL,
+ *   })),
+ * })
+ * ```
+ */
+export function withBetterAuthDefaults<T extends BetterAuthOptions>(
+  options: T
+): T {
+  // If trustedOrigins is explicitly provided, use it as-is
+  if (options.trustedOrigins !== undefined) {
+    return options
+  }
+
+  // If baseURL is set, default trustedOrigins to [baseURL]
+  if (options.baseURL) {
+    return {
+      ...options,
+      trustedOrigins: [options.baseURL],
+    }
+  }
+
+  // No defaults to apply
+  return options
+}

package/src/utils/detectAuthConfig.ts

@@ -0,0 +1,47 @@
+/**
+ * Utility to detect auth configuration in Payload config
+ */
+
+import type { Config, CollectionConfig } from 'payload'
+
+export type AuthDetectionResult = {
+  /** Whether any collection has disableLocalStrategy: true */
+  hasDisableLocalStrategy: boolean
+  /** The slug of the auth collection (if found) */
+  authCollectionSlug: string | null
+  /** The auth collection config (if found) */
+  authCollectionConfig: CollectionConfig | null
+}
+
+/**
+ * Scans Payload config to detect if any collection uses disableLocalStrategy.
+ * Used to determine whether to auto-inject admin components.
+ */
+export function detectAuthConfig(config: Config): AuthDetectionResult {
+  const collections = config.collections ?? []
+
+  for (const collection of collections) {
+    if (collection.auth) {
+      const auth = collection.auth
+      // disableLocalStrategy can be `true` or an object with options
+      if (
+        auth === true ||
+        (typeof auth === 'object' && auth.disableLocalStrategy)
+      ) {
+        return {
+          hasDisableLocalStrategy:
+            auth === true ||
+            (typeof auth === 'object' && !!auth.disableLocalStrategy),
+          authCollectionSlug: collection.slug,
+          authCollectionConfig: collection,
+        }
+      }
+    }
+  }
+
+  return {
+    hasDisableLocalStrategy: false,
+    authCollectionSlug: null,
+    authCollectionConfig: null,
+  }
+}

package/src/utils/detectEnabledPlugins.ts

@@ -0,0 +1,69 @@
+/**
+ * Utility to detect which Better Auth plugins are enabled
+ */
+
+import type { BetterAuthOptions } from 'better-auth'
+
+export type EnabledPluginsResult = {
+  hasAdmin: boolean
+  hasApiKey: boolean
+  hasTwoFactor: boolean
+  hasPasskey: boolean
+  hasMagicLink: boolean
+  hasMultiSession: boolean
+  hasOrganization: boolean
+}
+
+/**
+ * Detects which Better Auth plugins are enabled from the options.
+ * Inspects the plugins array by checking plugin identifiers.
+ *
+ * @param options - Better Auth options containing plugins array
+ * @returns Object with boolean flags for each supported plugin
+ */
+export function detectEnabledPlugins(
+  options?: Partial<BetterAuthOptions>
+): EnabledPluginsResult {
+  const plugins = options?.plugins ?? []
+
+  const result: EnabledPluginsResult = {
+    hasAdmin: false,
+    hasApiKey: false,
+    hasTwoFactor: false,
+    hasPasskey: false,
+    hasMagicLink: false,
+    hasMultiSession: false,
+    hasOrganization: false,
+  }
+
+  for (const plugin of plugins) {
+    // Better Auth plugins have an id property
+    const id = (plugin as { id?: string }).id
+
+    switch (id) {
+      case 'admin':
+        result.hasAdmin = true
+        break
+      case 'api-key':
+        result.hasApiKey = true
+        break
+      case 'two-factor':
+        result.hasTwoFactor = true
+        break
+      case 'passkey':
+        result.hasPasskey = true
+        break
+      case 'magic-link':
+        result.hasMagicLink = true
+        break
+      case 'multi-session':
+        result.hasMultiSession = true
+        break
+      case 'organization':
+        result.hasOrganization = true
+        break
+    }
+  }
+
+  return result
+}