@delmaredigital/payload-better-auth 0.3.15 → 0.4.1

package/README.md

@@ -41,6 +41,7 @@ For additional documentation and references, visit: [https://deepwiki.com/delmar
 | `@payloadcms/next` | >= 3.69.0 |
 | `@payloadcms/ui` | >= 3.69.0 |
 | `better-auth` | >= 1.4.0 |
+| `@better-auth/passkey` | >= 1.4.18 (if using passkeys) |
 | `next` | >= 15.4.8 |
 | `react` | >= 19.2.1 |
 
@@ -48,6 +49,9 @@ For additional documentation and references, visit: [https://deepwiki.com/delmar
 
 ```bash
 pnpm add @delmaredigital/payload-better-auth better-auth
+
+# If using passkeys:
+pnpm add @better-auth/passkey
 ```
 
 ### Environment Variables
@@ -490,6 +494,27 @@ API keys can have granular permission scopes. By default, scopes are auto-genera
 | `includeCollectionScopes` | `boolean` | `true` when no custom scopes, `false` when custom scopes provided | Include auto-generated collection scopes |
 | `excludeCollections` | `string[]` | `['sessions', 'verifications', 'accounts', 'twoFactors', 'apikeys']` | Collections to exclude from auto-generated scopes |
 | `defaultScopes` | `string[]` | `[]` | Default scopes pre-selected when creating a key |
+| `requiredRole` | `string \| string[] \| null` | Inherits from `admin.login.requiredRole` or `'admin'` | Role(s) required to create/update/delete API keys. Set to `null` to allow any authenticated user (not recommended) |
+
+**Restricting API key management to admins:**
+
+If your `admin.login.requiredRole` includes non-admin roles (e.g., editors who need admin panel access but shouldn't manage API keys), set `requiredRole` explicitly:
+
+```typescript
+createBetterAuthPlugin({
+  createAuth,
+  admin: {
+    login: {
+      requiredRole: ['admin', 'content_editor'], // both can access admin panel
+    },
+    apiKey: {
+      requiredRole: 'admin', // only admins can create/update/delete API keys
+    },
+  },
+})
+```
+
+> **Note:** API key **verification** is not affected by this setting — existing keys continue to work regardless of who created them. This only restricts key management (create, update, delete).
 
 **Zero Config (recommended):**
 ```typescript
@@ -994,9 +1019,7 @@ The adapter uses Better Auth's `createAdapterFactory` which is **schema-aware**
 | API Keys | `better-auth` (core) | Auto-generates apikeys collection |
 | Organizations | `better-auth` (core) | Auto-generates organizations, members, invitations |
 | Admin | `better-auth` (core) | Adds admin fields to users |
-| Passkey | Bundled | Auto-generates passkeys collection |
-
-**Note:** The `@better-auth/passkey` package is bundled with this package - no separate installation required.
+| Passkey | `@better-auth/passkey` (peer dep) | Auto-generates passkeys collection |
 
 ### Example: Core Plugins
 

package/dist/components/management/SecurityNavLinks.d.ts

@@ -11,7 +11,7 @@ export type SecurityNavLinksProps = {
 /**
  * Navigation links for security management features.
  * Rendered in admin sidebar via afterNavLinks injection.
- * Uses Payload's nav CSS classes for native styling.
+ * Uses Payload's NavGroup and nav CSS classes for native styling.
  *
  * Links are conditionally shown based on which Better Auth plugins are enabled.
  */

package/dist/components/management/SecurityNavLinks.js

@@ -1,92 +1,45 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { NavGroup } from '@payloadcms/ui';
 /**
  * Navigation links for security management features.
  * Rendered in admin sidebar via afterNavLinks injection.
- * Uses Payload's nav CSS classes for native styling.
+ * Uses Payload's NavGroup and nav CSS classes for native styling.
  *
  * Links are conditionally shown based on which Better Auth plugins are enabled.
  */ export function SecurityNavLinks({ basePath = '/admin/security', showTwoFactor = true, showApiKeys = true, showPasskeys = true } = {}) {
-    // Build links based on enabled plugins
     const links = [];
     if (showTwoFactor) {
         links.push({
             href: `${basePath}/two-factor`,
-            label: 'Two-Factor Auth',
-            icon: '📱'
+            label: 'Two-Factor Auth'
         });
     }
     if (showApiKeys) {
         links.push({
             href: `${basePath}/api-keys`,
-            label: 'API Keys',
-            icon: '🔑'
+            label: 'API Keys'
         });
     }
     if (showPasskeys) {
         links.push({
             href: `${basePath}/passkeys`,
-            label: 'Passkeys',
-            icon: '🔐'
+            label: 'Passkeys'
         });
     }
-    // Don't render anything if no plugins are enabled
     if (links.length === 0) {
         return null;
     }
-    return /*#__PURE__*/ _jsxs("div", {
-        style: {
-            borderTop: '1px solid var(--theme-elevation-100)',
-            marginTop: 'var(--base)',
-            paddingTop: 'var(--base)'
-        },
-        children: [
-            /*#__PURE__*/ _jsx("div", {
-                style: {
-                    fontSize: '11px',
-                    fontWeight: 600,
-                    color: 'var(--theme-elevation-500)',
-                    padding: '0 calc(var(--base) * 0.75)',
-                    marginBottom: 'calc(var(--base) * 0.5)',
-                    textTransform: 'uppercase',
-                    letterSpacing: '0.5px'
-                },
-                children: "Security"
-            }),
-            links.map((link)=>/*#__PURE__*/ _jsxs("a", {
-                    href: link.href,
-                    className: "nav__link",
-                    style: {
-                        display: 'flex',
-                        alignItems: 'center',
-                        gap: 'calc(var(--base) * 0.5)',
-                        padding: 'calc(var(--base) * 0.5) calc(var(--base) * 0.75)',
-                        color: 'var(--theme-elevation-800)',
-                        textDecoration: 'none',
-                        fontSize: 'var(--font-size-small)',
-                        borderRadius: 'var(--style-radius-s)',
-                        transition: 'background-color 150ms ease'
-                    },
-                    onMouseEnter: (e)=>{
-                        e.currentTarget.style.backgroundColor = 'var(--theme-elevation-50)';
-                    },
-                    onMouseLeave: (e)=>{
-                        e.currentTarget.style.backgroundColor = 'transparent';
-                    },
-                    children: [
-                        /*#__PURE__*/ _jsx("span", {
-                            style: {
-                                fontSize: '14px'
-                            },
-                            children: link.icon
-                        }),
-                        /*#__PURE__*/ _jsx("span", {
-                            className: "nav__link-label",
-                            children: link.label
-                        })
-                    ]
-                }, link.href))
-        ]
+    return /*#__PURE__*/ _jsx(NavGroup, {
+        label: "Security",
+        children: links.map((link)=>/*#__PURE__*/ _jsx("a", {
+                href: link.href,
+                className: "nav__link",
+                children: /*#__PURE__*/ _jsx("span", {
+                    className: "nav__link-label",
+                    children: link.label
+                })
+            }, link.href))
     });
 }
 export default SecurityNavLinks;

package/dist/exports/client.d.ts

@@ -722,6 +722,8 @@ export declare const payloadAuthPlugins: readonly [{
                         responseHeaders?: Headers | undefined;
                     } & import("better-auth").PluginContext & import("better-auth").InfoContext & {
                         options: import("better-auth").BetterAuthOptions;
+                        appName: string;
+                        baseURL: string;
                         trustedOrigins: string[];
                         isTrustedOrigin: (url: string, settings?: {
                             allowRelativePaths: boolean;
@@ -790,8 +792,8 @@ export declare const payloadAuthPlugins: readonly [{
                         }) => Promise<void>;
                         skipOriginCheck: boolean | string[];
                         skipCSRFCheck: boolean;
-                        runInBackground: (promise: Promise<void>) => void;
-                        runInBackgroundOrAwait: (promise: Promise<unknown> | Promise<void> | void | unknown) => Promise<unknown>;
+                        runInBackground: (promise: Promise<unknown>) => void;
+                        runInBackgroundOrAwait: (promise: Promise<unknown> | void) => import("better-auth").Awaitable<unknown>;
                     }>;
                 }>;
             }[];

package/dist/plugin/index.js

@@ -5,6 +5,7 @@
  */ 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
@@ -115,7 +116,7 @@ let apiKeyScopesConfig = undefined;
 }
 /**
  * Creates the auth endpoint handler that proxies requests to Better Auth.
- */ function createAuthEndpointHandler() {
+ */ function createAuthEndpointHandler(adminOptions) {
     return async (req)=>{
         const payloadWithAuth = req.payload;
         const auth = payloadWithAuth.betterAuth;
@@ -170,6 +171,45 @@ let apiKeyScopesConfig = undefined;
                     }
                 }
             }
+            // Guard API key mutation 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 session = await auth.api.getSession({
+                    headers: req.headers
+                });
+                if (!session?.user?.id) {
+                    return new Response(JSON.stringify({
+                        error: 'Unauthorized'
+                    }), {
+                        status: 401,
+                        headers: {
+                            'Content-Type': 'application/json'
+                        }
+                    });
+                }
+                // Resolve required role: apiKey config > login config > default 'admin'
+                const requiredRole = apiKeyScopesConfig?.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';
+                    const user = await req.payload.findByID({
+                        collection: authSlug,
+                        id: session.user.id,
+                        depth: 0,
+                        overrideAccess: true
+                    });
+                    if (!hasAnyRole(user, normalizeRoles(requiredRole))) {
+                        return new Response(JSON.stringify({
+                            error: 'Forbidden: insufficient permissions to manage API keys'
+                        }), {
+                            status: 403,
+                            headers: {
+                                'Content-Type': 'application/json'
+                            }
+                        });
+                    }
+                }
+            }
             // 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);
@@ -199,8 +239,8 @@ let apiKeyScopesConfig = undefined;
 }
 /**
  * Generates Payload endpoints for Better Auth.
- */ function generateAuthEndpoints(basePath) {
-    const handler = createAuthEndpointHandler();
+ */ function generateAuthEndpoints(basePath, adminOptions) {
+    const handler = createAuthEndpointHandler(adminOptions);
     const methods = [
         'get',
         'post',
@@ -384,7 +424,7 @@ let apiKeyScopesConfig = undefined;
         // Inject management UI components
         config = injectManagementComponents(config, options);
         // Generate auth endpoints if enabled
-        const authEndpoints = autoRegisterEndpoints ? generateAuthEndpoints(authBasePath) : [];
+        const authEndpoints = autoRegisterEndpoints ? generateAuthEndpoints(authBasePath, options.admin) : [];
         // Merge endpoints
         const existingEndpoints = config.endpoints ?? [];
         // Get existing onInit

package/dist/types/apiKey.d.ts

@@ -50,6 +50,14 @@ export type ApiKeyScopesConfig = {
      * 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')
+     * - string[]: Any matching role grants access
+     * - null: Allow any authenticated user (not recommended)
+     * @default Inherits from admin.login.requiredRole, or 'admin' if unset
+     */
+    requiredRole?: string | string[] | null;
 };
 /**
  * Scope data passed to the API keys management client component.

package/dist/utils/betterAuthDefaults.d.ts

@@ -89,6 +89,8 @@ export declare function apiKeyWithDefaults(options?: ApiKeyPluginOptions): {
                     responseHeaders?: Headers | undefined;
                 } & import("better-auth").PluginContext & import("better-auth").InfoContext & {
                     options: BetterAuthOptions;
+                    appName: string;
+                    baseURL: string;
                     trustedOrigins: string[];
                     isTrustedOrigin: (url: string, settings?: {
                         allowRelativePaths: boolean;
@@ -157,8 +159,8 @@ export declare function apiKeyWithDefaults(options?: ApiKeyPluginOptions): {
                     }) => Promise<void>;
                     skipOriginCheck: boolean | string[];
                     skipCSRFCheck: boolean;
-                    runInBackground: (promise: Promise<void>) => void;
-                    runInBackgroundOrAwait: (promise: Promise<unknown> | Promise<void> | void | unknown) => Promise<unknown>;
+                    runInBackground: (promise: Promise<unknown>) => void;
+                    runInBackgroundOrAwait: (promise: Promise<unknown> | void) => import("better-auth").Awaitable<unknown>;
                 }>;
             }>;
         }[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-better-auth",
-  "version": "0.3.15",
+  "version": "0.4.1",
   "description": "Better Auth adapter and plugins for Payload CMS",
   "type": "module",
   "license": "MIT",
@@ -74,10 +74,8 @@
     "test:coverage": "vitest run --coverage",
     "prepublishOnly": "pnpm build"
   },
-  "dependencies": {
-    "@better-auth/passkey": "^1.4.17"
-  },
   "peerDependencies": {
+    "@better-auth/passkey": ">=1.4.18",
     "@payloadcms/next": ">=3.69.0",
     "@payloadcms/ui": ">=3.69.0",
     "better-auth": ">=1.4.0",
@@ -85,17 +83,23 @@
     "payload": ">=3.69.0",
     "react": ">=19.2.1"
   },
+  "peerDependenciesMeta": {
+    "@better-auth/passkey": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@payloadcms/next": "^3.73.0",
-    "@payloadcms/ui": "^3.73.0",
+    "@payloadcms/next": "^3.76.1",
+    "@payloadcms/ui": "^3.76.1",
     "@swc/cli": "^0.6.0",
-    "@swc/core": "^1.10.18",
-    "@types/node": "^25.0.10",
-    "@types/react": "^19.2.9",
+    "@swc/core": "^1.15.11",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^2.1.9",
-    "better-auth": "^1.4.17",
-    "next": "^16.1.4",
-    "payload": "^3.73.0",
+    "@better-auth/passkey": "^1.4.18",
+    "better-auth": "^1.4.18",
+    "next": "^16.1.6",
+    "payload": "^3.76.1",
     "react": "^19.2.4",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",