@delmaredigital/payload-puck 0.8.3 → 0.9.0

package/README.md

@@ -10,6 +10,15 @@ A PayloadCMS plugin for integrating [Puck](https://puckeditor.com) visual page b
   <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdelmaredigital%2Fdd-starter&project-name=my-payload-site&build-command=pnpm%20run%20ci&env=PAYLOAD_SECRET,BETTER_AUTH_SECRET&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22productSlug%22%3A%22neon%22%2C%22integrationSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22blob%22%7D%5D"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="32"></a>
 </p>
 
+> 🔒 **Upgrading to 0.9? Security release — action required if you use the standalone route factories.**
+>
+> - **`createPuckApiRoutes`, `createPuckApiRoutesWithId`, `createPuckApiRoutesVersions` and `createPromptApiRoutes` now enforce Payload collection access control** ([GHSA-957g-hmmp-rchg](https://github.com/delmaredigital/payload-puck/security/advisories/GHSA-957g-hmmp-rchg)). They previously called Payload's Local API with the default `overrideAccess: true`, so collection and field `access` rules were **never evaluated** — any caller your `authenticate` hook accepted could read drafts and version history, restore versions over live content, publish, create and delete.
+> - **Action:** build `authenticate` on `payload.auth({ headers: request.headers })`. That works for **every** auth system — Better Auth, Clerk, NextAuth, custom strategies — and needs no other change. Do **not** return your auth library's session user, and do **not** map it back by email. Full steps in [Upgrading to 0.9.0](#upgrading-to-090-breaking-security).
+> - **Not affected:** the built-in `/api/puck/*` endpoints registered by `createPuckPlugin()`. Those were fixed in 0.6.23. If you never wired the standalone factories yourself, this release needs nothing from you.
+> - Also fixed: the AI context/prompts endpoints ([GHSA-rrx7-m589-5wfq](https://github.com/delmaredigital/payload-puck/security/advisories/GHSA-rrx7-m589-5wfq)) and the AI tools, which queried Payload unfiltered.
+
+---
+
 > 🎨 **Upgrading to 0.8?** The editor stylesheet is now built by your app, not by this plugin.
 >
 > - **`editorStylesheet`, `editorStylesheetCompiled` and `editorStylesheetUrls` are replaced by a single `editorStylesheets: string[]`** — an ordered list of URLs the editor iframe loads. The `/api/puck/styles` endpoint, the `/next` entry point and its `withPuckCSS()` wrapper, and the `postcss` / `postcss-load-config` peer dependencies are all removed.
@@ -49,10 +58,50 @@ pnpm add @delmaredigital/payload-puck @puckeditor/core
 | `next` | >= 15.4.8 (see security note below) |
 | `react` | >= 19.2.1 |
 
+> **Using [`@delmaredigital/payload-better-auth`](https://github.com/delmaredigital/payload-better-auth)?** Any published version works — its auth strategy stamps `collection` on the user, which is what 0.9's access resolution needs. **0.9.0 or later is recommended:** it is the first release where the recommended `payload.auth()` wiring, combined with the request headers 0.9 now forwards into Payload, is free of side effects for API-key requests. Current is `0.11.3`, which requires Better Auth `1.7`.
+
 > **Note:** Puck 0.21+ moved from `@measured/puck` to `@puckeditor/core`. This plugin requires the new package scope.
 
 > **Security:** If your app uses Next.js middleware (or proxy.ts) to protect dynamic routes, use `next` >= 15.5.16 / 16.2.5 to pick up the fix for [CVE-2026-44574](https://github.com/vercel/next.js/security/advisories/GHSA-492v-c6pp-mqqv) (middleware bypass via dynamic route parameter injection). Turbopack users need >= 15.5.18 / 16.2.6.
 
+### Upgrading to 0.9.0 (breaking, security)
+
+**Only affects apps that wired the standalone route factories from `@delmaredigital/payload-puck/api` or `/ai`.** The built-in `/api/puck/*` endpoints are unchanged.
+
+These factories now pass `overrideAccess: false` to Payload, so your collection `access` rules are enforced. To do that they must know **which Payload user** a request acts as. Build `authenticate` on `payload.auth()`:
+
+```ts
+import { getPayload } from 'payload'
+import config from '@payload-config'
+
+export const { GET, POST } = createPuckApiRoutes({
+  collection: 'pages',
+  payloadConfig: config,
+  auth: {
+    authenticate: async (request) => {
+      const payload = await getPayload({ config })
+      // Runs whatever auth strategies your Payload config registers.
+      const { user } = await payload.auth({ headers: request.headers })
+      if (!user) return { authenticated: false }
+      return { authenticated: true, user }
+    },
+  },
+})
+```
+
+This is the recommended wiring for **every** auth system, not just Payload's own. If you use Better Auth, keep `strategies: [betterAuthStrategy()]` on your users collection — that plus the snippet above is the whole integration.
+
+**Do not** return your auth library's session user (`auth.api.getSession()`, `getServerSession()`, `getServerUser()`, a decoded JWT). Those carry no `collection`, and these routes now fail closed on them with a `500` / `PUCK_ACCESS_MISCONFIGURED` and **no** database operation, with the fix printed to your server log.
+
+**Do not** map a session back to a user by email either — that is worse than the 500. A bare collection row silently drops the fields your auth strategy decorates onto the user; with `payload-better-auth` you lose `activeOrganizationId`, `organizationRole`, `apiKeyScopes` and `oauthScopes`, so an API-key caller can be judged as an ordinary session and an org-scoped rule evaluated with no organization at all.
+
+Two smaller behaviour changes fall out of this:
+
+- **Denials are now `403`,** not `500`. A Payload `Forbidden` previously arrived as a server error, indistinguishable from an outage. `404` and `409` are likewise passed through.
+- **Request headers now reach your access rules.** They are forwarded into every Payload operation, so a rule that inspects them — an API-key scope check, say — sees the same request the REST API would.
+
+If you are mid-migration and need to ship, `dangerouslyDisableCollectionAccessControl: true` restores the old behaviour and logs a warning once per factory. It leaves you with the vulnerability; treat it as a rollback, not a setting.
+
 ### Upgrading to 0.8.0 (breaking)
 
 **Editor CSS is now built by your app, not by this plugin.** Three options collapse into one, and `withPuckCSS` is gone.

package/dist/ai/plugins/promptApiRoutes.d.ts

@@ -17,6 +17,14 @@ export interface PromptApiRoutesConfig {
      * @default 'puck-ai-prompts'
      */
     collection?: string;
+    /**
+     * **SECURITY — see `PuckApiRoutesConfig.dangerouslyDisableCollectionAccessControl`.**
+     * Restores the pre-0.9.0 behaviour in which Payload collection access rules
+     * were not enforced on these routes.
+     *
+     * @default false
+     */
+    dangerouslyDisableCollectionAccessControl?: true;
 }
 /**
  * Creates API route handlers for /api/puck/ai-prompts

package/dist/ai/plugins/promptApiRoutes.js

@@ -1,4 +1,6 @@
 import { getPayload } from 'payload';
+import { createAccessResolver, accessMisconfigurationResponse } from '../../api/utils/access.js';
+import { payloadErrorResponse } from '../../utils/payloadErrors.js';
 /**
  * Creates API route handlers for /api/puck/ai-prompts
  *
@@ -36,12 +38,14 @@ import { getPayload } from 'payload';
  * ```
  */ export function createPromptApiRoutes(config) {
     const { payloadConfig, auth, collection = 'puck-ai-prompts' } = config;
+    // Resolves { overrideAccess, user } for every Payload call below.
+    const resolveAccess = createAccessResolver(config);
     return {
         GET: async (request)=>{
             try {
                 // Authenticate
                 const authResult = await auth.authenticate(request);
-                if (!authResult.authenticated) {
+                if (!authResult.authenticated || !authResult.user) {
                     return new Response(JSON.stringify({
                         error: 'Unauthorized'
                     }), {
@@ -56,8 +60,10 @@ import { getPayload } from 'payload';
                     config: await payloadConfig
                 });
                 // Fetch prompts
+                const access = await resolveAccess(authResult, request);
                 const result = await payload.find({
                     collection,
+                    ...access(),
                     sort: 'order',
                     limit: 100
                 });
@@ -68,6 +74,10 @@ import { getPayload } from 'payload';
                     }
                 });
             } catch (error) {
+                const misconfigured = accessMisconfigurationResponse(error);
+                if (misconfigured) return misconfigured;
+                const mapped = payloadErrorResponse(error);
+                if (mapped) return mapped;
                 console.error('[AI Prompts] Error fetching prompts:', error);
                 return new Response(JSON.stringify({
                     error: 'Failed to fetch prompts'
@@ -83,7 +93,7 @@ import { getPayload } from 'payload';
             try {
                 // Authenticate
                 const authResult = await auth.authenticate(request);
-                if (!authResult.authenticated) {
+                if (!authResult.authenticated || !authResult.user) {
                     return new Response(JSON.stringify({
                         error: 'Unauthorized'
                     }), {
@@ -100,8 +110,10 @@ import { getPayload } from 'payload';
                 // Parse body
                 const body = await request.json();
                 // Create prompt
+                const access = await resolveAccess(authResult, request);
                 const result = await payload.create({
                     collection,
+                    ...access(),
                     data: {
                         label: body.label,
                         prompt: body.prompt,
@@ -118,6 +130,10 @@ import { getPayload } from 'payload';
                     }
                 });
             } catch (error) {
+                const misconfigured = accessMisconfigurationResponse(error);
+                if (misconfigured) return misconfigured;
+                const mapped = payloadErrorResponse(error);
+                if (mapped) return mapped;
                 console.error('[AI Prompts] Error creating prompt:', error);
                 return new Response(JSON.stringify({
                     error: 'Failed to create prompt'
@@ -135,12 +151,14 @@ import { getPayload } from 'payload';
  * Creates API route handlers for /api/puck/ai-prompts/[id]
  */ export function createPromptApiRoutesWithId(config) {
     const { payloadConfig, auth, collection = 'puck-ai-prompts' } = config;
+    // Resolves { overrideAccess, user } for every Payload call below.
+    const resolveAccess = createAccessResolver(config);
     return {
         PATCH: async (request, context)=>{
             try {
                 // Authenticate
                 const authResult = await auth.authenticate(request);
-                if (!authResult.authenticated) {
+                if (!authResult.authenticated || !authResult.user) {
                     return new Response(JSON.stringify({
                         error: 'Unauthorized'
                     }), {
@@ -160,8 +178,10 @@ import { getPayload } from 'payload';
                 // Parse body
                 const body = await request.json();
                 // Update prompt
+                const access = await resolveAccess(authResult, request);
                 const result = await payload.update({
                     collection,
+                    ...access(),
                     id,
                     data: {
                         ...body.label !== undefined && {
@@ -187,6 +207,10 @@ import { getPayload } from 'payload';
                     }
                 });
             } catch (error) {
+                const misconfigured = accessMisconfigurationResponse(error);
+                if (misconfigured) return misconfigured;
+                const mapped = payloadErrorResponse(error);
+                if (mapped) return mapped;
                 console.error('[AI Prompts] Error updating prompt:', error);
                 return new Response(JSON.stringify({
                     error: 'Failed to update prompt'
@@ -202,7 +226,7 @@ import { getPayload } from 'payload';
             try {
                 // Authenticate
                 const authResult = await auth.authenticate(request);
-                if (!authResult.authenticated) {
+                if (!authResult.authenticated || !authResult.user) {
                     return new Response(JSON.stringify({
                         error: 'Unauthorized'
                     }), {
@@ -220,8 +244,10 @@ import { getPayload } from 'payload';
                     config: await payloadConfig
                 });
                 // Delete prompt
+                const access = await resolveAccess(authResult, request);
                 await payload.delete({
                     collection,
+                    ...access(),
                     id
                 });
                 return new Response(JSON.stringify({
@@ -233,6 +259,10 @@ import { getPayload } from 'payload';
                     }
                 });
             } catch (error) {
+                const misconfigured = accessMisconfigurationResponse(error);
+                if (misconfigured) return misconfigured;
+                const mapped = payloadErrorResponse(error);
+                if (mapped) return mapped;
                 console.error('[AI Prompts] Error deleting prompt:', error);
                 return new Response(JSON.stringify({
                     error: 'Failed to delete prompt'

package/dist/ai/tools/index.js

@@ -67,7 +67,7 @@
                     if (!context?.payload) {
                         throw new Error('Payload instance not available in tool context');
                     }
-                    const { payload } = context;
+                    const { payload, user } = context;
                     const query = {
                         collection: slug,
                         limit: input.limit || 10
@@ -97,7 +97,11 @@
                             ]
                         };
                     }
-                    const result = await payload.find(query);
+                    const result = await payload.find({
+                        ...query,
+                        overrideAccess: false,
+                        user
+                    });
                     return result.docs;
                 }
             };
@@ -117,7 +121,7 @@
                 if (!context?.payload) {
                     throw new Error('Payload instance not available in tool context');
                 }
-                const { payload } = context;
+                const { payload, user } = context;
                 const query = {
                     collection: mediaCollection,
                     limit: input.limit || 10
@@ -148,7 +152,11 @@
                         and: conditions
                     };
                 }
-                const result = await payload.find(query);
+                const result = await payload.find({
+                    ...query,
+                    overrideAccess: false,
+                    user
+                });
                 return result.docs.map((doc)=>({
                         id: doc.id,
                         url: doc.url,
@@ -173,7 +181,7 @@
                 if (!context?.payload) {
                     throw new Error('Payload instance not available in tool context');
                 }
-                const { payload } = context;
+                const { payload, user } = context;
                 const query = {
                     collection: config.pages,
                     limit: input.limit || 10
@@ -194,7 +202,11 @@
                         ]
                     };
                 }
-                const result = await payload.find(query);
+                const result = await payload.find({
+                    ...query,
+                    overrideAccess: false,
+                    user
+                });
                 return result.docs.map((doc)=>({
                         id: doc.id,
                         title: doc.title,
@@ -215,9 +227,11 @@
                     if (!context?.payload) {
                         throw new Error('Payload instance not available in tool context');
                     }
-                    const { payload } = context;
+                    const { payload, user } = context;
                     return await payload.findGlobal({
-                        slug: globalSlug
+                        slug: globalSlug,
+                        overrideAccess: false,
+                        user
                     });
                 }
             };

package/dist/api/createPuckApiRoutes.js

@@ -1,5 +1,7 @@
 import { NextResponse } from 'next/server';
 import { getPayload } from 'payload';
+import { createAccessResolver, accessMisconfigurationResponse } from './utils/access.js';
+import { payloadErrorResponse } from '../utils/payloadErrors.js';
 /**
  * Default Puck data for new pages
  */ const DEFAULT_PUCK_DATA = {
@@ -40,6 +42,9 @@ import { getPayload } from 'payload';
  * ```
  */ export function createPuckApiRoutes(routeConfig) {
     const { collection = 'pages', payloadConfig, auth, defaultPuckData = DEFAULT_PUCK_DATA, enableDrafts = true, onError } = routeConfig;
+    // Resolves { overrideAccess, user } for every Payload call below. Built once
+    // so the opt-out warning is logged per factory, not per request.
+    const resolveAccess = createAccessResolver(routeConfig);
     /**
    * GET /api/puck/pages
    * List all pages with optional filtering
@@ -112,8 +117,12 @@ import { getPayload } from 'payload';
             const where = conditions.length > 0 ? conditions.length === 1 ? conditions[0] : {
                 and: conditions
             } : undefined;
+            const access = await resolveAccess(authResult, request);
+            // Access control is evaluated by Payload, so the page list is filtered to
+            // documents the caller may actually read.
             const result = await payload.find({
                 collection,
+                ...access(),
                 page,
                 limit,
                 sort,
@@ -127,7 +136,13 @@ import { getPayload } from 'payload';
                     request
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error listing pages:', error);
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to list pages'
             }, {
@@ -182,9 +197,15 @@ import { getPayload } from 'payload';
             const payload = await getPayload({
                 config
             });
-            // Check if slug already exists
+            const access = await resolveAccess(authResult, request);
+            // Check if slug already exists. This runs under access control, so a
+            // caller cannot use it to probe for the existence of documents they may
+            // not read. The trade-off is that an unreadable collision is not caught
+            // here — Payload's unique constraint catches it on create below, and the
+            // ValidationError handler maps it back to the same 409.
             const existing = await payload.find({
                 collection,
+                ...access(),
                 where: {
                     slug: {
                         equals: slug
@@ -213,6 +234,7 @@ import { getPayload } from 'payload';
             // Create the page
             const newPage = await payload.create({
                 collection,
+                ...access(),
                 draft: enableDrafts,
                 data: {
                     title,
@@ -234,7 +256,33 @@ import { getPayload } from 'payload';
                     request
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error creating page:', error);
+            // A unique-constraint failure on slug means the page exists but was not
+            // visible to the pre-check above under access control. Report the same 409
+            // the pre-check would have, rather than a generic 500.
+            if (error instanceof Error && error.name === 'ValidationError') {
+                const validationError = error;
+                const fieldErrors = validationError.data?.errors || [];
+                if (fieldErrors.some((e)=>e.field === 'slug')) {
+                    return NextResponse.json({
+                        error: 'A page with this slug already exists'
+                    }, {
+                        status: 409
+                    });
+                }
+                return NextResponse.json({
+                    error: `Validation failed: ${fieldErrors.map((e)=>e.message || e.field).join(', ')}`,
+                    details: fieldErrors
+                }, {
+                    status: 400
+                });
+            }
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to create page'
             }, {

package/dist/api/createPuckApiRoutesVersions.js

@@ -1,6 +1,8 @@
 import { NextResponse } from 'next/server';
 import { getPayload } from 'payload';
 import { resolveLocaleFromNextRequest } from '../utils/locale.js';
+import { createAccessResolver, accessMisconfigurationResponse } from './utils/access.js';
+import { payloadErrorResponse } from '../utils/payloadErrors.js';
 /**
  * Create API route handlers for /api/puck/pages/[id]/versions
  *
@@ -27,6 +29,9 @@ import { resolveLocaleFromNextRequest } from '../utils/locale.js';
  * ```
  */ export function createPuckApiRoutesVersions(routeConfig) {
     const { collection = 'pages', payloadConfig, auth, onError } = routeConfig;
+    // Resolves { overrideAccess, user } for every Payload call below. Built once
+    // so the opt-out warning is logged per factory, not per request.
+    const resolveAccess = createAccessResolver(routeConfig);
     /**
    * GET /api/puck/pages/[id]/versions
    * Fetch version history for a page
@@ -72,9 +77,12 @@ import { resolveLocaleFromNextRequest } from '../utils/locale.js';
             const limit = parseInt(url.searchParams.get('limit') || '20', 10);
             const page = parseInt(url.searchParams.get('page') || '1', 10);
             const locale = resolveLocaleFromNextRequest(request);
-            // Fetch versions for this page
+            const access = await resolveAccess(authResult, request);
+            // Fetch versions for this page. Access control is evaluated by Payload so
+            // a caller only ever sees versions of documents they may read.
             const versions = await payload.findVersions({
                 collection,
+                ...access(),
                 where: {
                     parent: {
                         equals: id
@@ -105,7 +113,13 @@ import { resolveLocaleFromNextRequest } from '../utils/locale.js';
                     pageId: params.id
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error fetching versions:', error);
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to fetch versions'
             }, {
@@ -166,9 +180,12 @@ import { resolveLocaleFromNextRequest } from '../utils/locale.js';
             const payload = await getPayload({
                 config
             });
-            // Restore the version
+            const access = await resolveAccess(authResult, request);
+            // Restore the version. Payload evaluates `update` access on the parent
+            // document, so restoring is gated by the same rules as editing it.
             const restoredDoc = await payload.restoreVersion({
                 collection,
+                ...access(),
                 id: versionId
             });
             return NextResponse.json({
@@ -183,7 +200,13 @@ import { resolveLocaleFromNextRequest } from '../utils/locale.js';
                     pageId: params.id
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error restoring version:', error);
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to restore version'
             }, {

package/dist/api/createPuckApiRoutesWithId.js

@@ -1,6 +1,8 @@
 import { NextResponse } from 'next/server';
 import { getPayload } from 'payload';
 import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js';
+import { createAccessResolver, accessMisconfigurationResponse } from './utils/access.js';
+import { payloadErrorResponse } from '../utils/payloadErrors.js';
 /**
  * Create API route handlers for /api/puck/pages/[id]
  *
@@ -33,6 +35,9 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
  * ```
  */ export function createPuckApiRoutesWithId(routeConfig) {
     const { collection = 'pages', payloadConfig, auth, rootPropsMapping, onError } = routeConfig;
+    // Resolves { overrideAccess, user } for every Payload call below. Built once
+    // so the opt-out warning is logged per factory, not per request.
+    const resolveAccess = createAccessResolver(routeConfig);
     /**
    * GET /api/puck/pages/[id]
    * Fetch a single page by ID
@@ -77,8 +82,10 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
             // Default to draft=true for editor use (load latest draft)
             const url = new URL(request.url);
             const wantsDraft = url.searchParams.get('draft') !== 'false';
+            const access = await resolveAccess(authResult, request);
             const page = await payload.findByID({
                 collection,
+                ...access(),
                 id,
                 draft: wantsDraft
             });
@@ -101,7 +108,13 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
                     pageId: params.id
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error fetching page:', error);
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to fetch page'
             }, {
@@ -179,9 +192,11 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
             });
             // Handle homepage swap - if swapHomepage is true and isHomepage is being set,
             // unset the existing homepage first
+            const access = await resolveAccess(authResult, request);
             if (swapHomepage && isHomepage === true) {
                 const existingHomepage = await payload.find({
                     collection,
+                    ...access(),
                     where: {
                         and: [
                             {
@@ -202,6 +217,7 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
                 if (existingHomepage.docs.length > 0) {
                     await payload.update({
                         collection,
+                        ...access(),
                         id: existingHomepage.docs[0].id,
                         data: {
                             isHomepage: false
@@ -255,6 +271,7 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
             // When draft=false or omitted, updates the main collection
             const updateOptions = {
                 collection,
+                ...access(),
                 id,
                 data: updateData
             };
@@ -277,6 +294,8 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
                     pageId: params.id
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error updating page:', error);
             // Handle Payload validation errors gracefully
             if (error instanceof Error && error.name === 'ValidationError') {
@@ -301,6 +320,10 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
                     status: 400
                 });
             }
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to update page'
             }, {
@@ -348,8 +371,10 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
             const payload = await getPayload({
                 config
             });
+            const access = await resolveAccess(authResult, request);
             await payload.delete({
                 collection,
+                ...access(),
                 id
             });
             return NextResponse.json({
@@ -364,7 +389,13 @@ import { mapRootPropsToPayloadFields, deepMerge } from './utils/mapRootProps.js'
                     pageId: params.id
                 });
             }
+            const misconfigured = accessMisconfigurationResponse(error);
+            if (misconfigured) return misconfigured;
             console.error('Error deleting page:', error);
+            // An access denial is a 403, not a server fault. Mapping it keeps the
+            // access-control layer visible to clients and out of error monitoring.
+            const mapped = payloadErrorResponse(error);
+            if (mapped) return mapped;
             return NextResponse.json({
                 error: 'Failed to delete page'
             }, {

package/dist/api/index.d.ts

@@ -35,5 +35,7 @@
 export { createPuckApiRoutes } from './createPuckApiRoutes.js';
 export { createPuckApiRoutesWithId } from './createPuckApiRoutesWithId.js';
 export { createPuckApiRoutesVersions } from './createPuckApiRoutesVersions.js';
+export { isPayloadUser, resolvePayloadUser, createAccessResolver, accessMisconfigurationResponse, PuckApiAccessError, } from './utils/access.js';
+export type { PayloadAccessArgs, AccessResolverConfig } from './utils/access.js';
 export { mapRootPropsToPayloadFields, mapPayloadFieldsToRootProps, DEFAULT_ROOT_PROPS_MAPPINGS, setNestedValue, getNestedValue, mergeMappings, deepMerge, } from './utils/mapRootProps.js';
-export type { AuthenticatedUser, AuthResult, PermissionResult, PuckApiAuthHooks, RootPropsMapping, PuckApiRoutesConfig, ErrorContext, RouteHandler, RouteHandlerWithId, RouteHandlerContext, RouteHandlerWithIdContext, PuckApiRouteHandlers, PuckApiRouteWithIdHandlers, CreatePageBody, UpdatePageBody, ApiResponse, PageVersion, PuckApiVersionsRouteHandlers, } from './types.js';
+export type { AuthenticatedUser, PayloadUser, AuthResult, PermissionResult, PuckApiAuthHooks, RootPropsMapping, PuckApiRoutesConfig, ErrorContext, RouteHandler, RouteHandlerWithId, RouteHandlerContext, RouteHandlerWithIdContext, PuckApiRouteHandlers, PuckApiRouteWithIdHandlers, CreatePageBody, UpdatePageBody, ApiResponse, PageVersion, PuckApiVersionsRouteHandlers, } from './types.js';

package/dist/api/index.js

@@ -35,5 +35,7 @@
 export { createPuckApiRoutes } from './createPuckApiRoutes.js';
 export { createPuckApiRoutesWithId } from './createPuckApiRoutesWithId.js';
 export { createPuckApiRoutesVersions } from './createPuckApiRoutesVersions.js';
+// Access control
+export { isPayloadUser, resolvePayloadUser, createAccessResolver, accessMisconfigurationResponse, PuckApiAccessError } from './utils/access.js';
 // Utilities
 export { mapRootPropsToPayloadFields, mapPayloadFieldsToRootProps, DEFAULT_ROOT_PROPS_MAPPINGS, setNestedValue, getNestedValue, mergeMappings, deepMerge } from './utils/mapRootProps.js';