@delmaredigital/payload-better-auth 0.5.6 → 0.6.1

package/dist/components/management/views/ApiKeysView.js

@@ -2,8 +2,53 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DefaultTemplate } from '@payloadcms/next/templates';
 import { getVisibleEntities } from '@payloadcms/ui/shared';
 import { ApiKeysManagementClient } from '../ApiKeysManagementClient.js';
-import { getApiKeyScopesConfig } from '../../../plugin/index.js';
-import { buildAvailableScopes } from '../../../utils/generateScopes.js';
+import { getApiKeyPermissionsConfig } from '../../../plugin/index.js';
+import { generateCollectionPermissions } from '../../../utils/generatePermissions.js';
+/**
+ * Fetch organizations the current user belongs to.
+ * Returns an empty array if the members/organizations collections don't exist.
+ */ async function getUserOrganizations(payload, userId) {
+    try {
+        // Check if members and organizations collections exist
+        const collectionSlugs = payload.config.collections.map((c)=>c.slug);
+        if (!collectionSlugs.includes('members') || !collectionSlugs.includes('organizations')) {
+            return [];
+        }
+        // Find all memberships for this user
+        const memberships = await payload.find({
+            collection: 'members',
+            where: {
+                user: {
+                    equals: userId
+                }
+            },
+            limit: 100,
+            depth: 0,
+            overrideAccess: true
+        });
+        if (memberships.docs.length === 0) return [];
+        // Fetch organization details
+        const orgIds = memberships.docs.map((m)=>m.organization);
+        const orgs = await payload.find({
+            collection: 'organizations',
+            where: {
+                id: {
+                    in: orgIds
+                }
+            },
+            limit: 100,
+            depth: 0,
+            overrideAccess: true
+        });
+        return orgs.docs.map((org)=>({
+                id: org.id,
+                name: org.name || String(org.id)
+            }));
+    } catch  {
+        // Collections might not exist or have different schemas — return empty
+        return [];
+    }
+}
 /**
  * API Keys management view for Payload admin panel.
  * Server component that provides the admin layout.
@@ -16,11 +61,12 @@ import { buildAvailableScopes } from '../../../utils/generateScopes.js';
     const visibleEntities = getVisibleEntities({
         req
     });
-    // Build available scopes from plugin config and collections
-    const scopesConfig = getApiKeyScopesConfig();
-    const availableScopes = buildAvailableScopes(payload.config.collections, scopesConfig);
-    // Get default scopes from config
-    const defaultScopes = scopesConfig?.defaultScopes ?? [];
+    // Build permission definitions from collections
+    const permissionsConfig = getApiKeyPermissionsConfig();
+    const permissions = generateCollectionPermissions(payload.config.collections, permissionsConfig?.excludeCollections);
+    // Fetch user's organizations if the organization plugin is in use
+    const userId = req.user?.id;
+    const organizations = userId ? await getUserOrganizations(payload, userId) : [];
     return /*#__PURE__*/ _jsx(DefaultTemplate, {
         i18n: req.i18n,
         locale: req.locale,
@@ -31,8 +77,8 @@ import { buildAvailableScopes } from '../../../utils/generateScopes.js';
         user: req.user ?? undefined,
         visibleEntities: visibleEntities,
         children: /*#__PURE__*/ _jsx(ApiKeysManagementClient, {
-            availableScopes: availableScopes,
-            defaultScopes: defaultScopes
+            permissions: permissions,
+            organizations: organizations
         })
     });
 }

package/dist/index.d.ts

@@ -10,16 +10,16 @@ export { payloadAdapter, detectDbType, resolveIdType } from './adapter/index.js'
 export type { PayloadAdapterConfig, DbType } from './adapter/index.js';
 export { betterAuthCollections } from './adapter/collections.js';
 export type { BetterAuthCollectionsOptions } from './adapter/collections.js';
-export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyScopesConfig, } from './plugin/index.js';
+export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyPermissionsConfig, } from './plugin/index.js';
 export type { Auth, CreateAuthFunction, BetterAuthPluginOptions, BetterAuthPluginAdminOptions, BetterAuthStrategyOptions, } from './plugin/index.js';
 export type { BetterAuthReturn, PayloadWithAuth, PayloadRequestWithBetterAuth, CollectionHookWithBetterAuth, EndpointWithBetterAuth, RoleArray, } from './types/betterAuth.js';
 export type { User, Session as BetterAuthSession, Account, Verification, Apikey, Passkey, Organization, Member, Invitation, Team, TeamMember, TwoFactor, BaseUserFields, BaseSessionFields, BaseAccountFields, UserPluginFields, SessionPluginFields, BetterAuthFullSchema, ModelKey, PluginId, } from './generated-types.js';
-export type { ScopeDefinition, ApiKeyScopesConfig, AvailableScope, } from './types/apiKey.js';
-export { generateScopesFromCollections, buildAvailableScopes, scopesToPermissions, } from './utils/generateScopes.js';
+export type { PermissionDefinition, ApiKeyPermissionsConfig, } from './types/apiKey.js';
+export { generateCollectionPermissions, } from './utils/generatePermissions.js';
 export { normalizeRoles, hasAnyRole, hasAllRoles, hasAdminRoles, isAdmin, isAdminField, isAdminOrSelf, canUpdateOwnFields, isAuthenticated, isAuthenticatedField, hasRole, hasRoleField, requireAllRoles, } from './utils/access.js';
 export type { RoleCheckConfig, SelfAccessConfig, FieldUpdateConfig, } from './utils/access.js';
-export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAnyScopeKey, hasAllScopes as hasAllScopesKey, requireScope, requireAnyScope, requireAllScopes as requireAllScopesKey, allowSessionOrScope, allowSessionOrAnyScope, validateApiKey, } from './utils/apiKeyAccess.js';
-export type { ApiKeyInfo, ApiKeyAccessConfig, } from './utils/apiKeyAccess.js';
+export { extractApiKeyFromRequest, requirePermission, requireAnyPermission, requireAllPermissions, allowSessionOrPermission, allowSessionOrAnyPermission, requireApiKey, } from './utils/apiKeyAccess.js';
+export type { ApiKeyPermissionConfig, PermissionCheck, } from './utils/apiKeyAccess.js';
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 export type { AuthDetectionResult } from './utils/detectAuthConfig.js';
 export { getServerSession, getServerUser, createSessionHelpers } from './utils/session.js';

package/dist/index.js

@@ -10,13 +10,13 @@ export { payloadAdapter, detectDbType, resolveIdType } from './adapter/index.js'
 // Collection generator plugin
 export { betterAuthCollections } from './adapter/collections.js';
 // Payload plugin and strategy
-export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyScopesConfig } from './plugin/index.js';
-// Scope utilities
-export { generateScopesFromCollections, buildAvailableScopes, scopesToPermissions } from './utils/generateScopes.js';
+export { createBetterAuthPlugin, betterAuthStrategy, resetAuthInstance, getApiKeyPermissionsConfig } from './plugin/index.js';
+// Permission utilities
+export { generateCollectionPermissions } from './utils/generatePermissions.js';
 // Access control utilities
 export { normalizeRoles, hasAnyRole, hasAllRoles, hasAdminRoles, isAdmin, isAdminField, isAdminOrSelf, canUpdateOwnFields, isAuthenticated, isAuthenticatedField, hasRole, hasRoleField, requireAllRoles } from './utils/access.js';
-// API key scope enforcement utilities
-export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAnyScopeKey, hasAllScopes as hasAllScopesKey, requireScope, requireAnyScope, requireAllScopes as requireAllScopesKey, allowSessionOrScope, allowSessionOrAnyScope, validateApiKey } from './utils/apiKeyAccess.js';
+// API key permission enforcement utilities
+export { extractApiKeyFromRequest, requirePermission, requireAnyPermission, requireAllPermissions, allowSessionOrPermission, allowSessionOrAnyPermission, requireApiKey } from './utils/apiKeyAccess.js';
 // Auth config detection utility
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 // Session utilities

package/dist/plugin/index.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Plugin, AuthStrategy, BasePayload } from 'payload';
 import type { betterAuth, BetterAuthOptions } from 'better-auth';
-import type { ApiKeyScopesConfig } from '../types/apiKey.js';
+import type { ApiKeyPermissionsConfig } from '../types/apiKey.js';
 export type Auth = ReturnType<typeof betterAuth>;
 export type { PayloadWithAuth } from '../types/betterAuth.js';
 export type CreateAuthFunction = (payload: BasePayload) => any;
@@ -97,11 +97,11 @@ export type BetterAuthPluginAdminOptions = {
         passkeys?: string;
     };
     /**
-     * API key scopes configuration.
-     * Controls which permission scopes are available when creating API keys.
-     * When not provided, scopes are auto-generated from Payload collections.
+     * API key permissions configuration.
+     * Controls which permissions are available when creating API keys.
+     * When not provided, permissions are auto-generated from Payload collections.
      */
-    apiKey?: ApiKeyScopesConfig;
+    apiKey?: ApiKeyPermissionsConfig;
 };
 export type BetterAuthPluginOptions = {
     /**
@@ -133,10 +133,10 @@ export type BetterAuthPluginOptions = {
     admin?: BetterAuthPluginAdminOptions;
 };
 /**
- * Get the configured API key scopes config.
- * Used by the ApiKeysView to build available scopes.
+ * Get the stored API key permissions config.
+ * Used by the ApiKeysView server component to generate permission definitions.
  */
-export declare function getApiKeyScopesConfig(): ApiKeyScopesConfig | undefined;
+export declare function getApiKeyPermissionsConfig(): ApiKeyPermissionsConfig | undefined;
 /**
  * Payload plugin that initializes Better Auth.
  *

package/dist/plugin/index.js

@@ -4,22 +4,25 @@
  * @packageDocumentation
  */ import { detectAuthConfig } from '../utils/detectAuthConfig.js';
 import { detectEnabledPlugins } from '../utils/detectEnabledPlugins.js';
-import { buildAvailableScopes, scopesToPermissions } from '../utils/generateScopes.js';
 import { hasAnyRole, normalizeRoles } from '../utils/access.js';
 // Track auth instance for HMR
 let authInstance = null;
-// Store API key scopes config for access by management views
-let apiKeyScopesConfig = undefined;
+// Store API key permissions config for access by management views
+let apiKeyPermissionsConfig = undefined;
 /**
- * Get the configured API key scopes config.
- * Used by the ApiKeysView to build available scopes.
- */ export function getApiKeyScopesConfig() {
-    return apiKeyScopesConfig;
+ * Get the stored API key permissions config.
+ * Used by the ApiKeysView server component to generate permission definitions.
+ */ export function getApiKeyPermissionsConfig() {
+    return apiKeyPermissionsConfig;
 }
 /**
- * Handle API key creation with scopes server-side.
- * Converts scopes to permissions and calls Better Auth's server API.
- */ async function handleApiKeyCreateWithScopes(authApi, payload, headers, body) {
+ * Handle API key creation server-side.
+ * Passes permissions directly from the client to Better Auth's server API.
+ *
+ * When `organizationId` is provided in the body, it is validated against the
+ * user's memberships and stored in the API key's metadata. This allows the
+ * `betterAuthStrategy` to resolve organization context for API key requests.
+ */ async function handleApiKeyCreate(authApi, headers, body, payload, membersCollection = 'members') {
     try {
         // Get the current session to find the user
         const session = await authApi.getSession({
@@ -35,16 +38,51 @@ let apiKeyScopesConfig = undefined;
                 }
             });
         }
-        // Extract scopes from the request body
-        const scopes = body.scopes ?? [];
-        // Build permissions from scopes if any are provided
-        let permissions;
-        if (scopes.length > 0) {
-            const scopesConfig = getApiKeyScopesConfig();
-            const availableScopes = buildAvailableScopes(payload.config.collections, scopesConfig);
-            permissions = scopesToPermissions(scopes, availableScopes);
+        // If organizationId is provided, validate that the user is a member
+        const organizationId = body.organizationId;
+        if (organizationId && payload) {
+            try {
+                const memberships = await payload.find({
+                    collection: membersCollection,
+                    where: {
+                        and: [
+                            {
+                                user: {
+                                    equals: session.user.id
+                                }
+                            },
+                            {
+                                organization: {
+                                    equals: organizationId
+                                }
+                            }
+                        ]
+                    },
+                    limit: 1,
+                    depth: 0
+                });
+                if (memberships.docs.length === 0) {
+                    return new Response(JSON.stringify({
+                        error: 'You are not a member of this organization'
+                    }), {
+                        status: 403,
+                        headers: {
+                            'Content-Type': 'application/json'
+                        }
+                    });
+                }
+            } catch  {
+            // Members collection might not exist — allow creation without org binding
+            }
         }
-        // Build the API key creation options
+        // Permissions come directly from the client in BA's native format
+        const permissions = body.permissions;
+        // Merge organizationId into metadata if provided
+        const existingMetadata = body.metadata;
+        const metadata = organizationId ? {
+            ...existingMetadata || {},
+            organizationId
+        } : existingMetadata;
         const createOptions = {
             body: {
                 name: body.name,
@@ -52,10 +90,7 @@ let apiKeyScopesConfig = undefined;
                 expiresIn: body.expiresIn,
                 prefix: body.prefix,
                 permissions: permissions && Object.keys(permissions).length > 0 ? permissions : undefined,
-                metadata: scopes.length > 0 ? {
-                    ...body.metadata,
-                    scopes
-                } : body.metadata
+                metadata: metadata && Object.keys(metadata).length > 0 ? metadata : undefined
             }
         };
         // Call Better Auth's server-side API
@@ -69,38 +104,13 @@ let apiKeyScopesConfig = undefined;
                 }
             });
         }
-        try {
-            const result = await authApi.createApiKey(createOptions);
-            return new Response(JSON.stringify(result), {
-                status: 200,
-                headers: {
-                    'Content-Type': 'application/json'
-                }
-            });
-        } catch (createError) {
-            // Check if error is due to metadata being disabled
-            const errorMessage = createError instanceof Error ? createError.message : String(createError);
-            const isMetadataDisabled = errorMessage.toLowerCase().includes('metadata') && errorMessage.toLowerCase().includes('disabled');
-            if (isMetadataDisabled && createOptions.body.metadata) {
-                // Retry without metadata - key will still work, just won't show scopes in UI
-                console.warn('[better-auth] Metadata disabled, creating API key without scope metadata. Enable metadata with apiKey({ enableMetadata: true }) for better UX.');
-                const optionsWithoutMetadata = {
-                    body: {
-                        ...createOptions.body,
-                        metadata: undefined
-                    }
-                };
-                const result = await authApi.createApiKey(optionsWithoutMetadata);
-                return new Response(JSON.stringify(result), {
-                    status: 200,
-                    headers: {
-                        'Content-Type': 'application/json'
-                    }
-                });
+        const result = await authApi.createApiKey(createOptions);
+        return new Response(JSON.stringify(result), {
+            status: 200,
+            headers: {
+                'Content-Type': 'application/json'
             }
-            // Re-throw other errors
-            throw createError;
-        }
+        });
     } catch (error) {
         console.error('[better-auth] API key creation error:', error);
         const message = error instanceof Error ? error.message : 'Failed to create API key';
@@ -171,9 +181,10 @@ let apiKeyScopesConfig = undefined;
                     }
                 }
             }
-            // Guard API key mutation endpoints — require admin role
+            // Guard API key mutation and list endpoints — require admin role
             const isApiKeyMutation = req.method === 'POST' && (pathname.endsWith('/api-key/create') || pathname.endsWith('/api-key/update') || pathname.endsWith('/api-key/delete'));
-            if (isApiKeyMutation) {
+            const isApiKeyList = req.method === 'GET' && pathname.endsWith('/api-key/list');
+            if (isApiKeyMutation || isApiKeyList) {
                 const session = await auth.api.getSession({
                     headers: req.headers
                 });
@@ -188,7 +199,7 @@ let apiKeyScopesConfig = undefined;
                     });
                 }
                 // Resolve required role: apiKey config > login config > default 'admin'
-                const requiredRole = apiKeyScopesConfig?.requiredRole ?? adminOptions?.login?.requiredRole ?? 'admin';
+                const requiredRole = apiKeyPermissionsConfig?.requiredRole ?? adminOptions?.login?.requiredRole ?? 'admin';
                 if (requiredRole !== null) {
                     // Find the auth collection slug from Payload's config
                     const authSlug = req.payload.config.collections.find((c)=>typeof c.auth === 'object' || c.auth === true)?.slug ?? 'users';
@@ -210,11 +221,10 @@ let apiKeyScopesConfig = undefined;
                     }
                 }
             }
-            // Intercept API key creation requests with scopes
-            // Better Auth's API key create endpoint is POST /api-key/create
-            const isApiKeyCreate = req.method === 'POST' && pathname.endsWith('/api-key/create') && parsedBody?.scopes && Array.isArray(parsedBody.scopes);
+            // Intercept API key creation requests to inject userId from session
+            const isApiKeyCreate = req.method === 'POST' && pathname.endsWith('/api-key/create');
             if (isApiKeyCreate && parsedBody) {
-                return handleApiKeyCreateWithScopes(auth.api, req.payload, req.headers, parsedBody);
+                return handleApiKeyCreate(auth.api, req.headers, parsedBody, req.payload);
             }
             // Create a new Request for Better Auth
             const request = new Request(url.toString(), {
@@ -436,8 +446,8 @@ let apiKeyScopesConfig = undefined;
  * ```
  */ export function createBetterAuthPlugin(options) {
     const { createAuth, authBasePath = '/auth', autoRegisterEndpoints = true, autoInjectAdminComponents = true } = options;
-    // Store API key scopes config for access by management views
-    apiKeyScopesConfig = options.admin?.apiKey;
+    // Store API key permissions config for access by management views
+    apiKeyPermissionsConfig = options.admin?.apiKey;
     return (incomingConfig)=>{
         // Inject admin components if enabled
         let config = autoInjectAdminComponents ? injectAdminComponents(incomingConfig, options) : incomingConfig;
@@ -601,6 +611,64 @@ let apiKeyScopesConfig = undefined;
                     // Members collection might not exist (org plugin not used), silently ignore
                     }
                 }
+                // If activeOrganizationId is not set (common with API key mock sessions),
+                // check if the API key has an organizationId in its metadata
+                if (!sessionFields.activeOrganizationId) {
+                    const apiKeyHeader = headers.get('x-api-key') || headers.get('authorization')?.replace('Bearer ', '');
+                    if (apiKeyHeader) {
+                        const auth = payloadWithAuth.betterAuth;
+                        const verifyApiKey = auth.api.verifyApiKey;
+                        if (typeof verifyApiKey === 'function') {
+                            try {
+                                const verifyResult = await verifyApiKey({
+                                    body: {
+                                        key: apiKeyHeader
+                                    }
+                                });
+                                if (verifyResult.valid && verifyResult.key?.metadata) {
+                                    const metadata = typeof verifyResult.key.metadata === 'string' ? JSON.parse(verifyResult.key.metadata) : verifyResult.key.metadata;
+                                    if (metadata.organizationId) {
+                                        // Coerce to number if using serial IDs
+                                        let orgId = metadata.organizationId;
+                                        if (idType === 'number' && typeof orgId === 'string' && /^\d+$/.test(orgId)) {
+                                            orgId = parseInt(orgId, 10);
+                                        }
+                                        // Verify the user is actually a member of this org
+                                        try {
+                                            const memberships = await payload.find({
+                                                collection: membersCollection,
+                                                where: {
+                                                    and: [
+                                                        {
+                                                            user: {
+                                                                equals: sessionData.user.id
+                                                            }
+                                                        },
+                                                        {
+                                                            organization: {
+                                                                equals: orgId
+                                                            }
+                                                        }
+                                                    ]
+                                                },
+                                                limit: 1,
+                                                depth: 0
+                                            });
+                                            if (memberships.docs.length > 0) {
+                                                sessionFields.activeOrganizationId = orgId;
+                                                organizationRole = memberships.docs[0].role;
+                                            }
+                                        } catch  {
+                                        // Members collection might not exist, continue without org context
+                                        }
+                                    }
+                                }
+                            } catch  {
+                            // API key verification failed, continue without org context
+                            }
+                        }
+                    }
+                }
                 return {
                     user: {
                         ...users.docs[0],

package/dist/types/apiKey.d.ts

@@ -1,55 +1,34 @@
 /**
- * API Key Scope Types
+ * API Key Permission Types
  *
- * Provides typed configuration for API key permission scopes.
+ * Uses Better Auth's native permission format: Record<string, string[]>
+ * where keys are resource names (collection slugs) and values are action arrays.
+ *
+ * Convention: two actions per collection — 'read' and 'write'.
+ * - read: view records
+ * - write: full access (create, update, delete) — implies read
  */
 /**
- * A single permission scope definition.
- * Scopes are human-readable permission groups (like GitHub OAuth scopes).
+ * A permission definition for the admin UI.
+ * Describes a collection's available permission levels.
  */
-export type ScopeDefinition = {
-    /** Human-readable label for the scope (e.g., "Read Content") */
+export type PermissionDefinition = {
+    /** Collection slug (e.g., 'posts') */
+    slug: string;
+    /** Human-readable label (e.g., 'Posts') */
     label: string;
-    /** Description of what this scope allows (e.g., "View posts, pages, and comments") */
-    description: string;
-    /**
-     * Permission mapping: { resourceType: ['action1', 'action2'] }
-     * Maps to Better Auth's permission format.
-     * Use '*' for resource to match all resources.
-     * Use '*' in actions array to grant all actions on a resource.
-     */
-    permissions: Record<string, string[]>;
-    /** If true, only admin users can create keys with this scope */
-    adminOnly?: boolean;
+    /** Available actions — always ['read', 'write'] for auto-generated */
+    actions: string[];
 };
 /**
- * Configuration options for API key scopes.
- * Can be used in plugin options to customize available scopes.
+ * Configuration options for API key permissions.
  */
-export type ApiKeyScopesConfig = {
-    /**
-     * Custom scope definitions.
-     * Key is the scope ID (e.g., 'content:read'), value is the scope definition.
-     */
-    scopes?: Record<string, ScopeDefinition>;
-    /**
-     * Include auto-generated collection scopes.
-     * When true (default), generates {collection}:read, {collection}:write, {collection}:delete
-     * for each Payload collection.
-     * @default true when no custom scopes provided, false when custom scopes provided
-     */
-    includeCollectionScopes?: boolean;
+export type ApiKeyPermissionsConfig = {
     /**
-     * Collections to exclude from auto-generated scopes.
-     * Useful for hiding sensitive collections like 'sessions' or 'verifications'.
-     * @default ['sessions', 'verifications', 'accounts', 'twoFactors']
+     * Collections to exclude from the permissions UI.
+     * @default ['sessions', 'verifications', 'accounts', 'twoFactors', 'apiKeys']
      */
     excludeCollections?: string[];
-    /**
-     * Default scopes assigned to new API keys when user doesn't select any.
-     * If not provided, keys without scopes will have no permissions.
-     */
-    defaultScopes?: string[];
     /**
      * Role(s) required to create, update, and delete API keys.
      * - string: Single role required (e.g., 'admin')
@@ -59,10 +38,3 @@ export type ApiKeyScopesConfig = {
      */
     requiredRole?: string | string[] | null;
 };
-/**
- * Scope data passed to the API keys management client component.
- */
-export type AvailableScope = ScopeDefinition & {
-    /** The scope ID (e.g., 'content:read') */
-    id: string;
-};

package/dist/types/apiKey.js

@@ -1,10 +1,15 @@
 /**
- * API Key Scope Types
+ * API Key Permission Types
  *
- * Provides typed configuration for API key permission scopes.
+ * Uses Better Auth's native permission format: Record<string, string[]>
+ * where keys are resource names (collection slugs) and values are action arrays.
+ *
+ * Convention: two actions per collection — 'read' and 'write'.
+ * - read: view records
+ * - write: full access (create, update, delete) — implies read
  */ /**
- * A single permission scope definition.
- * Scopes are human-readable permission groups (like GitHub OAuth scopes).
+ * A permission definition for the admin UI.
+ * Describes a collection's available permission levels.
  */ /**
- * Scope data passed to the API keys management client component.
+ * Configuration options for API key permissions.
  */ export { };