@delmaredigital/payload-better-auth 0.5.5 → 0.6.0

package/dist/utils/apiKeyAccess.js

@@ -1,392 +1,236 @@
 /**
- * API Key Scope Enforcement Utilities
+ * API Key Permission 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.
+ * Thin wrappers around Better Auth's verifyApiKey() for use in
+ * Payload access control. Uses BA's native permission format.
  *
  * @example
  * ```ts
- * import { requireScope, requireAnyScope } from '@delmaredigital/payload-better-auth'
+ * import { requirePermission, allowSessionOrPermission } 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'),
+ *     read: requirePermission('posts', 'read'),
+ *     create: requirePermission('posts', 'write'),
+ *     update: requirePermission('posts', 'write'),
+ *     delete: requirePermission('posts', 'write'),
  *   },
  * }
  * ```
- */ import { createHash } from 'node:crypto';
-// ─────────────────────────────────────────────────────────────────────────────
+ */ // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
-/**
- * Hash an API key using the same algorithm as Better Auth's defaultKeyHasher.
- * Produces a SHA-256 hash encoded as Base64URL (no padding).
- */ function hashApiKey(key) {
-    return createHash('sha256').update(key).digest('base64url');
-}
 /**
  * Extract API key from request headers.
  * Supports Bearer token format: Authorization: Bearer <api-key>
  */ export function extractApiKeyFromRequest(req) {
     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, apiKey, apiKeysCollection = 'apiKeys') {
+ * Verify an API key has the required permission using Better Auth's native verifyApiKey.
+ * Returns true if the key is valid and has the permission, false otherwise.
+ *
+ * Includes backward compatibility: if the key was created with old CRUD actions
+ * (create/update/delete), a 'write' check will fall back to checking for those.
+ */ async function verifyKeyPermission(req, apiKey, resource, action) {
+    const auth = req.payload.betterAuth;
+    if (!auth) return false;
     try {
-        // Hash the raw API key to match Better Auth's storage format (SHA-256 + Base64URL).
-        // We query for both the hashed and raw key to support both modes:
-        // - Hashing enabled (default): only the hashed query matches
-        // - Hashing disabled (disableKeyHashing: true): only the plaintext query matches
-        const hashedKey = hashApiKey(apiKey);
-        // Try the provided collection name first
-        let results = await req.payload.find({
-            collection: apiKeysCollection,
-            overrideAccess: true,
-            where: {
-                and: [
-                    {
-                        enabled: {
-                            not_equals: false
-                        }
-                    },
-                    {
-                        or: [
-                            {
-                                key: {
-                                    equals: hashedKey
-                                }
-                            },
-                            {
-                                key: {
-                                    equals: apiKey
-                                }
-                            }
-                        ]
-                    }
-                ]
-            },
-            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,
-                overrideAccess: true,
-                where: {
-                    and: [
-                        {
-                            enabled: {
-                                not_equals: false
-                            }
-                        },
-                        {
-                            or: [
-                                {
-                                    key: {
-                                        equals: hashedKey
-                                    }
-                                },
-                                {
-                                    key: {
-                                        equals: apiKey
-                                    }
-                                }
-                            ]
-                        }
+        // Primary check: use BA's native permission verification
+        const result = await auth.api.verifyApiKey({
+            body: {
+                key: apiKey,
+                permissions: {
+                    [resource]: [
+                        action
                     ]
-                },
-                limit: 1,
-                depth: 0
-            }).catch(()=>null);
-        }
-        if (!results || results.docs.length === 0) {
-            return null;
-        }
-        const doc = results.docs[0];
-        // Parse scopes from permissions field (Better Auth format) or scopes array
-        let scopes = [];
-        if (doc.permissions) {
-            try {
-                const parsed = JSON.parse(doc.permissions);
-                if (Array.isArray(parsed)) {
-                    scopes = parsed;
-                } else if (typeof parsed === 'object') {
-                    // Flatten Better Auth permissions format {"resource": ["action1", "action2"]}
-                    // into scope strings like ["resource:action1", "resource:action2"]
-                    scopes = Object.entries(parsed).flatMap(([resource, actions])=>Array.isArray(actions) ? actions.map((action)=>`${resource}:${action}`) : [
-                            resource
-                        ]);
                 }
-            } 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 reference ID and type (BA 1.5 uses referenceId/referenceType instead of userId)
-        let referenceId;
-        let referenceType = 'user';
-        if (doc.referenceId) {
-            referenceId = String(doc.referenceId);
-            if (doc.referenceType === 'organization') {
-                referenceType = 'organization';
+        });
+        if (result.valid) return true;
+        // Backward compat: old keys stored CRUD actions instead of 'read'/'write'
+        const fallbackResult = await auth.api.verifyApiKey({
+            body: {
+                key: apiKey
             }
-        } else if (doc.userId) {
-            // Fallback for pre-1.5 schema
-            referenceId = String(doc.userId);
-        } else if (doc.user) {
-            // Fallback for relationship field
-            referenceId = typeof doc.user === 'object' ? String(doc.user.id) : String(doc.user);
-        } else {
-            return null;
+        });
+        if (!fallbackResult.valid || !fallbackResult.key?.permissions) return false;
+        const perms = fallbackResult.key.permissions;
+        const actions = perms[resource];
+        if (!Array.isArray(actions)) return false;
+        if (action === 'write') {
+            // Old 'write' stored as ['read', 'create', 'update'] or ['delete']
+            return actions.some((a)=>[
+                    'create',
+                    'update',
+                    'delete'
+                ].includes(a));
+        }
+        if (action === 'read') {
+            return actions.includes('read');
         }
-        // Parse metadata
-        let metadata;
-        if (doc.metadata) {
-            if (typeof doc.metadata === 'string') {
-                try {
-                    metadata = JSON.parse(doc.metadata);
-                } catch  {
-                // Ignore parse errors
-                }
-            } else {
-                metadata = doc.metadata;
-            }
-        }
-        // Prefer scope names from metadata (stored by admin UI as original scope strings
-        // like ["pages:read", "*"]) over permissions-derived scopes, because the permissions
-        // field uses Better Auth's internal format (e.g. {"pages": {"$": ["read"]}}) and
-        // Object.keys() on that only yields collection names, not proper scope strings.
-        if (metadata?.scopes && Array.isArray(metadata.scopes)) {
-            scopes = metadata.scopes;
-        }
-        return {
-            id: String(doc.id),
-            referenceId,
-            referenceType,
-            scopes,
-            keyPrefix: doc.start,
-            metadata
-        };
+        return false;
     } catch  {
-        return null;
+        return false;
     }
 }
 /**
- * Check if an API key has a specific scope.
- * Supports wildcard patterns like 'posts:*' matching 'posts:read', 'posts:write', etc.
- */ export function hasScope(keyScopes, requiredScope) {
-    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;
+ * Verify an API key without checking specific permissions.
+ * Returns true if the key is valid, false otherwise.
+ */ async function verifyKeyOnly(req, apiKey) {
+    const auth = req.payload.betterAuth;
+    if (!auth) return false;
+    try {
+        const result = await auth.api.verifyApiKey({
+            body: {
+                key: apiKey
+            }
+        });
+        return result.valid === true;
+    } catch  {
         return false;
-    });
-}
-/**
- * Check if an API key has any of the specified scopes.
- */ export function hasAnyScope(keyScopes, requiredScopes) {
-    return requiredScopes.some((scope)=>hasScope(keyScopes, scope));
-}
-/**
- * Check if an API key has all of the specified scopes.
- */ export function hasAllScopes(keyScopes, requiredScopes) {
-    return requiredScopes.every((scope)=>hasScope(keyScopes, scope));
+    }
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // Access Control Functions
 // ─────────────────────────────────────────────────────────────────────────────
 /**
- * Create an access control function that requires a specific scope.
+ * Require a specific permission on an API key.
  *
- * @param scope - The required scope string (e.g., 'posts:read')
- * @param config - Configuration options
+ * @param resource - Collection slug (e.g., 'posts')
+ * @param action - Permission action: 'read' or 'write'
+ * @param config - Optional configuration
  * @returns Payload access function
  *
  * @example
  * ```ts
  * access: {
- *   read: requireScope('posts:read'),
- *   create: requireScope('posts:write'),
+ *   read: requirePermission('posts', 'read'),
+ *   create: requirePermission('posts', 'write'),
  * }
  * ```
- */ export function requireScope(scope, config = {}) {
-    const { apiKeysCollection = 'apiKeys', allowAuthenticatedUsers = false, extractApiKey = extractApiKeyFromRequest } = config;
+ */ export function requirePermission(resource, action, config = {}) {
+    const { 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;
+        if (allowAuthenticatedUsers && req.user && !apiKey) {
+            return true;
         }
-        // Check scope
-        return hasScope(keyInfo.scopes, scope);
+        if (!apiKey) return false;
+        return verifyKeyPermission(req, apiKey, resource, action);
     };
 }
 /**
- * Create an access control function that requires any of the specified scopes.
+ * Require any one of the specified permissions.
  *
- * @param scopes - Array of acceptable scopes (at least one must match)
- * @param config - Configuration options
+ * @param permissions - Array of {resource, action} pairs (at least one must match)
+ * @param config - Optional configuration
  * @returns Payload access function
  *
  * @example
  * ```ts
  * access: {
- *   read: requireAnyScope(['posts:read', 'content:read', 'admin:*']),
+ *   read: requireAnyPermission([
+ *     { resource: 'posts', action: 'read' },
+ *     { resource: 'pages', action: 'read' },
+ *   ]),
  * }
  * ```
- */ export function requireAnyScope(scopes, config = {}) {
-    const { apiKeysCollection = 'apiKeys', allowAuthenticatedUsers = false, extractApiKey = extractApiKeyFromRequest } = config;
+ */ export function requireAnyPermission(permissions, config = {}) {
+    const { 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;
+        if (allowAuthenticatedUsers && req.user && !apiKey) {
+            return true;
         }
-        const keyInfo = await getApiKeyInfo(req, apiKey, apiKeysCollection);
-        if (!keyInfo) {
-            return false;
+        if (!apiKey) return false;
+        for (const perm of permissions){
+            if (await verifyKeyPermission(req, apiKey, perm.resource, perm.action)) {
+                return true;
+            }
         }
-        return hasAnyScope(keyInfo.scopes, scopes);
+        return false;
     };
 }
 /**
- * Create an access control function that requires all specified scopes.
+ * Require all of the specified permissions.
  *
- * @param scopes - Array of required scopes (all must be present)
- * @param config - Configuration options
+ * @param permissions - Array of {resource, action} pairs (all must match)
+ * @param config - Optional configuration
  * @returns Payload access function
  *
  * @example
  * ```ts
  * access: {
- *   delete: requireAllScopes(['posts:delete', 'admin:write']),
+ *   delete: requireAllPermissions([
+ *     { resource: 'posts', action: 'write' },
+ *     { resource: 'admin', action: 'write' },
+ *   ]),
  * }
  * ```
- */ export function requireAllScopes(scopes, config = {}) {
-    const { apiKeysCollection = 'apiKeys', allowAuthenticatedUsers = false, extractApiKey = extractApiKeyFromRequest } = config;
+ */ export function requireAllPermissions(permissions, config = {}) {
+    const { 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;
+        if (allowAuthenticatedUsers && req.user && !apiKey) {
+            return true;
         }
-        const keyInfo = await getApiKeyInfo(req, apiKey, apiKeysCollection);
-        if (!keyInfo) {
-            return false;
+        if (!apiKey) return false;
+        for (const perm of permissions){
+            if (!await verifyKeyPermission(req, apiKey, perm.resource, perm.action)) {
+                return false;
+            }
         }
-        return hasAllScopes(keyInfo.scopes, scopes);
+        return true;
     };
 }
 /**
- * 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
+ * Allow either authenticated session OR API key with permission.
  *
  * @example
  * ```ts
  * access: {
- *   read: allowSessionOrScope('posts:read'),
+ *   read: allowSessionOrPermission('posts', 'read'),
  * }
  * ```
- */ export function allowSessionOrScope(scope, config = {}) {
-    return requireScope(scope, {
+ */ export function allowSessionOrPermission(resource, action, config = {}) {
+    return requirePermission(resource, action, {
         ...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, config = {}) {
-    return requireAnyScope(scopes, {
+ * Allow either authenticated session OR API key with any of the permissions.
+ */ export function allowSessionOrAnyPermission(permissions, config = {}) {
+    return requireAnyPermission(permissions, {
         ...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
+ * Require a valid API key (no specific permissions checked).
+ * Useful for apps that use role-based access and just need to verify the key exists.
  *
  * @example
  * ```ts
- * const keyInfo = await validateApiKey(req)
- * if (keyInfo) {
- *   console.log('Valid API key for:', keyInfo.referenceId, keyInfo.referenceType)
- *   console.log('Scopes:', keyInfo.scopes)
+ * access: {
+ *   read: requireApiKey(),
  * }
  * ```
- */ export async function validateApiKey(req, apiKeysCollection = 'apiKeys') {
-    const apiKey = extractApiKeyFromRequest(req);
-    if (!apiKey) return null;
-    return getApiKeyInfo(req, apiKey, apiKeysCollection);
+ */ export function requireApiKey(config = {}) {
+    const { allowAuthenticatedUsers = false, extractApiKey = extractApiKeyFromRequest } = config;
+    return async ({ req })=>{
+        const apiKey = extractApiKey(req);
+        if (allowAuthenticatedUsers && req.user && !apiKey) {
+            return true;
+        }
+        if (!apiKey) return false;
+        return verifyKeyOnly(req, apiKey);
+    };
 }

package/dist/utils/generatePermissions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate permission definitions from Payload collections for the admin UI.
+ */
+import type { CollectionConfig } from 'payload';
+import type { PermissionDefinition } from '../types/apiKey.js';
+/**
+ * Generate permission definitions from Payload collections.
+ * Returns a list of collections with their available actions (read/write)
+ * for display in the API key management UI.
+ */
+export declare function generateCollectionPermissions(collections: CollectionConfig[], excludeCollections?: string[]): PermissionDefinition[];

package/dist/utils/generatePermissions.js

@@ -0,0 +1,30 @@
+/**
+ * Generate permission definitions from Payload collections for the admin UI.
+ */ /** Default collections to exclude from permissions UI */ const DEFAULT_EXCLUDED_COLLECTIONS = [
+    'sessions',
+    'verifications',
+    'accounts',
+    'twoFactors',
+    'apiKeys',
+    'api-keys'
+];
+/**
+ * Convert slug to human-readable label.
+ * e.g., 'blog-posts' -> 'Blog Posts'
+ */ function slugToLabel(slug) {
+    return slug.split('-').map((s)=>s.charAt(0).toUpperCase() + s.slice(1)).join(' ');
+}
+/**
+ * Generate permission definitions from Payload collections.
+ * Returns a list of collections with their available actions (read/write)
+ * for display in the API key management UI.
+ */ export function generateCollectionPermissions(collections, excludeCollections = DEFAULT_EXCLUDED_COLLECTIONS) {
+    return collections.filter((c)=>!excludeCollections.includes(c.slug)).map((c)=>({
+            slug: c.slug,
+            label: (typeof c.labels?.plural === 'string' ? c.labels.plural : null) ?? slugToLabel(c.slug) + 's',
+            actions: [
+                'read',
+                'write'
+            ]
+        }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-better-auth",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Better Auth adapter and plugins for Payload CMS",
   "type": "module",
   "license": "MIT",

package/dist/utils/generateScopes.d.ts

@@ -1,20 +0,0 @@
-/**
- * Auto-generate API key scopes from Payload collections.
- */
-import type { CollectionConfig } from 'payload';
-import type { ScopeDefinition, ApiKeyScopesConfig, AvailableScope } from '../types/apiKey.js';
-/**
- * Generate scopes from Payload collections.
- * Creates {collection}:read, {collection}:write, {collection}:delete for each collection.
- */
-export declare function generateScopesFromCollections(collections: CollectionConfig[], excludeCollections?: string[]): Record<string, ScopeDefinition>;
-/**
- * Build the final scopes configuration from plugin options and collections.
- * Handles merging custom scopes with auto-generated collection scopes.
- */
-export declare function buildAvailableScopes(collections: CollectionConfig[], config?: ApiKeyScopesConfig): AvailableScope[];
-/**
- * Convert selected scopes to Better Auth permission format.
- * Used when creating an API key.
- */
-export declare function scopesToPermissions(selectedScopeIds: string[], availableScopes: AvailableScope[]): Record<string, string[]>;