@delmaredigital/payload-better-auth 0.5.6 → 0.6.1

package/dist/utils/apiKeyAccess.d.ts

@@ -1,46 +1,26 @@
 /**
- * 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 type { Access, PayloadRequest } from 'payload';
-export type ApiKeyInfo = {
-    /** The API key ID */
-    id: string;
-    /** Reference ID (user or organization) who owns this key */
-    referenceId: string;
-    /** Reference type - whether key is owned by a user or organization */
-    referenceType: 'user' | 'organization';
-    /** 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;
+export type ApiKeyPermissionConfig = {
     /**
      * Allow access if user is authenticated (non-API key session).
      * Useful for allowing both API keys and regular sessions.
@@ -53,121 +33,93 @@ export type ApiKeyAccessConfig = {
      */
     extractApiKey?: (req: PayloadRequest) => string | null;
 };
+/** A single permission check: resource + action */
+export type PermissionCheck = {
+    resource: string;
+    action: string;
+};
 /**
  * Extract API key from request headers.
  * Supports Bearer token format: Authorization: Bearer <api-key>
  */
 export declare function extractApiKeyFromRequest(req: PayloadRequest): string | null;
 /**
- * Look up API key info from the database.
- * Returns null if key not found or disabled.
- */
-export declare function getApiKeyInfo(req: PayloadRequest, apiKey: string, apiKeysCollection?: string): Promise<ApiKeyInfo | null>;
-/**
- * Check if an API key has a specific scope.
- * Supports wildcard patterns like 'posts:*' matching 'posts:read', 'posts:write', etc.
- */
-export declare function hasScope(keyScopes: string[], requiredScope: string): boolean;
-/**
- * Check if an API key has any of the specified scopes.
- */
-export declare function hasAnyScope(keyScopes: string[], requiredScopes: string[]): boolean;
-/**
- * Check if an API key has all of the specified scopes.
- */
-export declare function hasAllScopes(keyScopes: string[], requiredScopes: string[]): boolean;
-/**
- * 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 declare function requireScope(scope: string, config?: ApiKeyAccessConfig): Access;
+export declare function requirePermission(resource: string, action: string, config?: ApiKeyPermissionConfig): Access;
 /**
- * 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 declare function requireAnyScope(scopes: string[], config?: ApiKeyAccessConfig): Access;
+export declare function requireAnyPermission(permissions: PermissionCheck[], config?: ApiKeyPermissionConfig): Access;
 /**
- * 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 declare function requireAllScopes(scopes: string[], config?: ApiKeyAccessConfig): Access;
+export declare function requireAllPermissions(permissions: PermissionCheck[], config?: ApiKeyPermissionConfig): Access;
 /**
- * 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 declare function allowSessionOrScope(scope: string, config?: Omit<ApiKeyAccessConfig, 'allowAuthenticatedUsers'>): Access;
+export declare function allowSessionOrPermission(resource: string, action: string, config?: Omit<ApiKeyPermissionConfig, 'allowAuthenticatedUsers'>): Access;
 /**
- * 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
+ * Allow either authenticated session OR API key with any of the permissions.
  */
-export declare function allowSessionOrAnyScope(scopes: string[], config?: Omit<ApiKeyAccessConfig, 'allowAuthenticatedUsers'>): Access;
+export declare function allowSessionOrAnyPermission(permissions: PermissionCheck[], config?: Omit<ApiKeyPermissionConfig, 'allowAuthenticatedUsers'>): Access;
 /**
- * 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 declare function validateApiKey(req: PayloadRequest, apiKeysCollection?: string): Promise<ApiKeyInfo | null>;
+export declare function requireApiKey(config?: ApiKeyPermissionConfig): Access;