@delmaredigital/payload-better-auth 0.3.11 → 0.3.13

package/README.md

@@ -552,22 +552,48 @@ betterAuthStrategy({
 |--------|------|-------------|
 | `usersCollection` | `string` | The collection slug for users (default: `'users'`) |
 
-### `getServerSession(payload, headers)`
+### `getServerSession<TUser>(payload, headers)`
 
-Get the current session on the server.
+Get the current session on the server. Pass your Payload `User` type for full type safety:
 
 ```ts
-const session = await getServerSession(payload, headersList)
-// Returns: { user: { id, email, name, ... }, session: { id, expiresAt, ... } } | null
+import { getServerSession } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+const session = await getServerSession<User>(payload, headersList)
+// session.user.role, session.user.firstName, etc. are fully typed
 ```
 
-### `getServerUser(payload, headers)`
+### `getServerUser<TUser>(payload, headers)`
 
-Get the current user on the server (shorthand for `session.user`).
+Get the current user on the server (shorthand for `session.user`):
 
 ```ts
-const user = await getServerUser(payload, headersList)
-// Returns: { id, email, name, ... } | null
+import { getServerUser } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+const user = await getServerUser<User>(payload, headersList)
+// user.role, user.firstName, etc. are fully typed
+```
+
+### `createSessionHelpers<TUser>()`
+
+Create typed session helpers bound to your User type. Define once, import everywhere — no generics needed at call sites:
+
+```ts
+// lib/auth.ts
+import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+import type { User } from '@/payload-types'
+
+export const { getServerSession, getServerUser } = createSessionHelpers<User>()
+```
+
+```ts
+// app/page.tsx
+import { getServerSession } from '@/lib/auth'
+
+const session = await getServerSession(payload, headersList)
+// session.user is typed as User — no generic needed
 ```
 
 ### `withBetterAuthDefaults(options)`

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAn
 export type { ApiKeyInfo, ApiKeyAccessConfig, } from './utils/apiKeyAccess.js';
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 export type { AuthDetectionResult } from './utils/detectAuthConfig.js';
-export { getServerSession, getServerUser } from './utils/session.js';
+export { getServerSession, getServerUser, createSessionHelpers } from './utils/session.js';
 export type { Session } from './utils/session.js';
 export { firstUserAdminHooks } from './utils/firstUserAdmin.js';
 export type { FirstUserAdminOptions } from './utils/firstUserAdmin.js';

package/dist/index.js

@@ -20,7 +20,7 @@ export { extractApiKeyFromRequest, getApiKeyInfo, hasScope, hasAnyScope as hasAn
 // Auth config detection utility
 export { detectAuthConfig } from './utils/detectAuthConfig.js';
 // Session utilities
-export { getServerSession, getServerUser } from './utils/session.js';
+export { getServerSession, getServerUser, createSessionHelpers } from './utils/session.js';
 // First user admin hook utility
 export { firstUserAdminHooks } from './utils/firstUserAdmin.js';
 // Better Auth defaults utility

package/dist/utils/apiKeyAccess.js

@@ -19,9 +19,16 @@
  *   },
  * }
  * ```
- */ // ─────────────────────────────────────────────────────────────────────────────
+ */ 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>
@@ -40,16 +47,37 @@
  * Returns null if key not found or disabled.
  */ export async function getApiKeyInfo(req, apiKey, apiKeysCollection = 'apiKeys') {
     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: {
-                key: {
-                    equals: apiKey
-                },
-                enabled: {
-                    not_equals: false
-                }
+                and: [
+                    {
+                        enabled: {
+                            not_equals: false
+                        }
+                    },
+                    {
+                        or: [
+                            {
+                                key: {
+                                    equals: hashedKey
+                                }
+                            },
+                            {
+                                key: {
+                                    equals: apiKey
+                                }
+                            }
+                        ]
+                    }
+                ]
             },
             limit: 1,
             depth: 0
@@ -59,13 +87,29 @@
             const altSlug = apiKeysCollection === 'apiKeys' ? 'api-keys' : 'apiKeys';
             results = await req.payload.find({
                 collection: altSlug,
+                overrideAccess: true,
                 where: {
-                    key: {
-                        equals: apiKey
-                    },
-                    enabled: {
-                        not_equals: false
-                    }
+                    and: [
+                        {
+                            enabled: {
+                                not_equals: false
+                            }
+                        },
+                        {
+                            or: [
+                                {
+                                    key: {
+                                        equals: hashedKey
+                                    }
+                                },
+                                {
+                                    key: {
+                                        equals: apiKey
+                                    }
+                                }
+                            ]
+                        }
+                    ]
                 },
                 limit: 1,
                 depth: 0
@@ -83,8 +127,11 @@
                 if (Array.isArray(parsed)) {
                     scopes = parsed;
                 } else if (typeof parsed === 'object') {
-                    // If it's an object, extract keys or flatten
-                    scopes = Object.keys(parsed);
+                    // 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
@@ -115,6 +162,13 @@
                 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),
             userId,

package/dist/utils/session.d.ts

@@ -4,14 +4,15 @@
  * @packageDocumentation
  */
 import type { BasePayload } from 'payload';
-export type Session = {
-    user: {
-        id: string;
-        email: string;
-        name?: string;
-        image?: string;
-        [key: string]: unknown;
-    };
+type DefaultUser = {
+    id: string;
+    email: string;
+    name?: string;
+    image?: string;
+    [key: string]: unknown;
+};
+export type Session<TUser = DefaultUser> = {
+    user: TUser;
     session: {
         id: string;
         expiresAt: Date;
@@ -21,35 +22,43 @@ export type Session = {
 /**
  * Get the current session from headers.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ * Pass your Payload-generated `User` type for full type safety.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerSession } from '@delmare/payload-better-auth'
+ * import { getServerSession } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const session = await getServerSession(payload, headersList)
+ *   const session = await getServerSession<User>(payload, headersList)
  *
  *   if (!session) {
  *     redirect('/login')
  *   }
  *
+ *   // session.user.role is fully typed
  *   return <div>Hello {session.user.name}</div>
  * }
  * ```
  */
-export declare function getServerSession(payload: BasePayload, headers: Headers): Promise<Session | null>;
+export declare function getServerSession<TUser = DefaultUser>(payload: BasePayload, headers: Headers): Promise<Session<TUser> | null>;
 /**
  * Get the current user from the session.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerUser } from '@delmare/payload-better-auth'
+ * import { getServerUser } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const user = await getServerUser(payload, headersList)
+ *   const user = await getServerUser<User>(payload, headersList)
  *
  *   if (!user) {
  *     redirect('/login')
@@ -59,4 +68,32 @@ export declare function getServerSession(payload: BasePayload, headers: Headers)
  * }
  * ```
  */
-export declare function getServerUser(payload: BasePayload, headers: Headers): Promise<Session['user'] | null>;
+export declare function getServerUser<TUser = DefaultUser>(payload: BasePayload, headers: Headers): Promise<TUser | null>;
+/**
+ * Create typed session helpers bound to your User type.
+ *
+ * Define once in a shared file, then import the typed helpers
+ * everywhere — no generics needed at call sites.
+ *
+ * @example
+ * ```ts
+ * // lib/auth.ts
+ * import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
+ *
+ * export const { getServerSession, getServerUser } = createSessionHelpers<User>()
+ * ```
+ *
+ * ```ts
+ * // app/page.tsx
+ * import { getServerSession } from '@/lib/auth'
+ *
+ * const session = await getServerSession(payload, headersList)
+ * // session.user is typed as User — no generic needed
+ * ```
+ */
+export declare function createSessionHelpers<TUser = DefaultUser>(): {
+    getServerSession: (payload: BasePayload, headers: Headers) => Promise<Session<TUser> | null>;
+    getServerUser: (payload: BasePayload, headers: Headers) => Promise<TUser | null>;
+};
+export {};

package/dist/utils/session.js

@@ -5,19 +5,24 @@
  */ /**
  * Get the current session from headers.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ * Pass your Payload-generated `User` type for full type safety.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerSession } from '@delmare/payload-better-auth'
+ * import { getServerSession } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const session = await getServerSession(payload, headersList)
+ *   const session = await getServerSession<User>(payload, headersList)
  *
  *   if (!session) {
  *     redirect('/login')
  *   }
  *
+ *   // session.user.role is fully typed
  *   return <div>Hello {session.user.name}</div>
  * }
  * ```
@@ -40,14 +45,17 @@
 /**
  * Get the current user from the session.
  *
+ * Accepts an optional generic type parameter to narrow the user type.
+ *
  * @example
  * ```ts
  * import { headers } from 'next/headers'
- * import { getServerUser } from '@delmare/payload-better-auth'
+ * import { getServerUser } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
  *
  * export default async function Page() {
  *   const headersList = await headers()
- *   const user = await getServerUser(payload, headersList)
+ *   const user = await getServerUser<User>(payload, headersList)
  *
  *   if (!user) {
  *     redirect('/login')
@@ -60,3 +68,31 @@
     const session = await getServerSession(payload, headers);
     return session?.user ?? null;
 }
+/**
+ * Create typed session helpers bound to your User type.
+ *
+ * Define once in a shared file, then import the typed helpers
+ * everywhere — no generics needed at call sites.
+ *
+ * @example
+ * ```ts
+ * // lib/auth.ts
+ * import { createSessionHelpers } from '@delmaredigital/payload-better-auth'
+ * import type { User } from '@/payload-types'
+ *
+ * export const { getServerSession, getServerUser } = createSessionHelpers<User>()
+ * ```
+ *
+ * ```ts
+ * // app/page.tsx
+ * import { getServerSession } from '@/lib/auth'
+ *
+ * const session = await getServerSession(payload, headersList)
+ * // session.user is typed as User — no generic needed
+ * ```
+ */ export function createSessionHelpers() {
+    return {
+        getServerSession: (payload, headers)=>getServerSession(payload, headers),
+        getServerUser: (payload, headers)=>getServerUser(payload, headers)
+    };
+}

package/package.json

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