Ir al contenido

Control de acceso

access decide quién puede hacer qué con una colección, un global o un campo. Se declara en el config, es código tuyo —una función que recibe a la persona de la sesión— y lo aplican las operaciones, no las puertas: la API local, la API REST, las subidas, el servidor de ficheros y el panel preguntan a la misma función, así que no pueden discrepar.

Sin access, nada cambia: cualquier sesión escribe en cualquier colección y en cualquier global, y solo access: { read: 'public' } abre la lectura a un visitante. La única excepción son las cuentas: en users, sin access propio, editar y borrar una cuenta ajena y cambiar los ajustes del sitio es cosa de quien administra (ver Las cuentas sin access). Con access, manda la función. El CMS no define roles ni una jerarquía —no sabe qué es un «editor» en tu proyecto—: da la columna role, las funciones y el motor que las aplica; la política la escribes tú.

Una colección, un global y un campo admiten claves distintas, porque no hacen lo mismo:

Dueño Clave Qué admite
Colección read 'public', o una función que devuelve boolean o una condición
create Una función que devuelve boolean
update, delete Una función que devuelve boolean o una condición
admin Una función que devuelve boolean. Solo en la colección auth: true (users): quién entra en el panel
settings Una función que devuelve boolean. Solo en la colección auth: true (users): quién cambia los ajustes del sitio
Global read 'public', o una función que devuelve boolean
update Una función que devuelve boolean
Campo read, update Una función que devuelve boolean

Tres reglas que explican la tabla:

  • Una escritura nunca es pública: create: 'public' no existe, y 'public' solo vale en read de una colección o un global.
  • Una condición necesita filas que filtrar. create no tiene fila todavía, un global es un único documento en KV y un campo no filtra filas: los tres devuelven solo boolean. Una función de esas que devuelve una condición es un error de tu proyecto, no del cliente (ver qué pasa si la función está mal).
  • Un global no se crea ni se borra, así que no tiene create ni delete. id, createdAt y updatedAt no admiten access.

defineConfig valida la forma entera al arrancar y lanza INVALID_ACCESS ante una clave que no existe —con la más parecida como sugerencia, así que udpate te dice update—, un valor que no es una función ni 'public', o un admin o un settings fuera de la colección de las cuentas.

Cada operación pregunta al motor, y el motor contesta con estas reglas, en este orden:

Situación Resultado
El código del proyecto (overrideAccess: true, los hooks) Todo permitido, sin llamar a ninguna función
Hay función declarada Se llama con { user, id, data }. true: todo. false: nada. Una condición: solo las filas que la cumplen
Sin función, lectura, read: 'public' Todo, también para un visitante
Sin función, lectura de otro modo Todo si hay sesión, nada si no
Sin función, create, update, delete, admin y update de un global Todo si hay sesión, nada si no. Salvo en users: ver Las cuentas sin access
Un campo sin función Hereda lo que la operación permita sobre su documento

La última fila de «sin función» es la que mantiene el comportamiento de siempre: un proyecto que no declara access solo nota un cambio, el de las cuentas (editar o borrar una ajena, y los ajustes del sitio, pasan a ser de quien administra), y lo explica la sección siguiente.

«Nada» no es un error genérico: es un 401 si no hay sesión y un 403 si la hay.

users es la única colección con un defecto propio, porque es la única cuya escritura toma el control del sitio: quien edita una cuenta ajena cambia su email, su name y su image, y quien borra la de otra persona le quita el acceso. Para cada operación que users no declare, el motor decide así:

Operación Sin función declarada en users
read Todo si hay sesión, nada si no. Sigue abierta a toda cuenta con sesión: los selectores de autor (relationship a users) la necesitan, y por eso el directorio de cuentas lo ve toda cuenta con sesión
update y delete La propia cuenta, o cualquiera si tu rol es el de admin.firstUserRole (admin si no lo declaras). Una cuenta sin ese rol que apunta a otra recibe un 403, exista o no ese id
settings Solo una cuenta con el rol de admin.firstUserRole (admin si no lo declaras)
create, admin Como cualquier otra colección: todo si hay sesión

Tres precisiones:

  • Se decide operación por operación. Declarar access.update en users no abre delete ni settings: cada una de las que falten recibe su defecto seguro, y las que declares mandan como siempre.
  • Una clave de API ve lo que ve su dueño. Actúa con la cuenta y el rol que esa cuenta tiene en cada petición, así que la clave de una cuenta sin rol tampoco edita ni borra las de otras ni cambia los ajustes.
  • Borrar la propia cuenta sigue sujeto a la guarda de la última cuenta: la última que queda no se borra con ningún access, overrideAccess: true incluido.

Es un cambio respecto a versiones anteriores, donde toda cuenta con sesión podía editar y borrar las demás. Lo único que se recupera con una línea son los ajustes: si tu proyecto dependía de que toda cuenta que inicia sesión los cambiara, declara solo settings:

cms.config.ts
defineCollection({
slug: 'users',
access: {
// Los ajustes los cambia toda cuenta que inicia sesión, como antes
settings: ({ user }) => user !== null,
},
fields: [],
})

Todas reciben un único objeto con { user } —la persona de la sesión, o null si no hay— y, según la operación, id y data:

Función Qué trae el objeto
read de una colección { user }; { user, id } en findByID
create { user, data }, con el cuerpo tal como llegó
update { user, id, data }
delete { user, id }
read de un campo { user }; { user, id } en findByID. En un listado no hay id: una función de campo no puede depender del documento
update de un campo { user, id, data }; en create, id es undefined
read de un global { user }
update de un global { user, data }, sin id: un global es un único documento y la función ya sabe en cuál está

La persona trae lo que better-auth guarda de la cuenta más su role. Es la misma si la sesión llega por cookie, por un token Bearer o por una clave de API: en la clave, la persona es su dueño y el rol, el que tenga en esa petición. El resultado se recuerda dentro de la llamada (una función no corre dos veces para la misma colección, operación e id) y nunca más allá de ella: un rol revocado o una sesión cerrada se ven en la petición siguiente.

En read, update y delete de una colección la función puede devolver un Where, el mismo de find. Se une con AND al filtro de quien llama dentro de la consulta SQL, así que «puedes editar tus propios posts» no es un bucle que lee todo y descarta después: es una cláusula, y la paginación sigue contando bien.

Falla cerrada:

  • Una condición vacía ({}, { and: [] }) no deja pasar nada: es el «nada» de arriba, nunca «sin filtro».
  • Un operando undefined —{ author: { equals: user?.id } } cuando no hay sesión— hace falsa esa hoja; ni se ignora ni lanza.

Una función de access mal escrita es un error de tu proyecto, no del cliente, y se trata como tal: un 500 con código ACCESS_ERROR en la API local, que REST contesta con el INTERNAL_ERROR genérico —el detalle va al log del Worker y nunca al cliente, para no filtrar tu política—. Lo provocan una función que devuelve algo que no es un boolean ni una condición (¿falta un return?), una condición que nombra un campo que no existe o un operador que no aplica, y una función de campo, de global o de create que devuelve una condición. Una excepción dentro de la función se propaga tal cual.

cms.config.ts
import { type AccessArgs, defineCollection, defineConfig } from '@kevolution-co/cms'
const isAdmin = ({ user }: AccessArgs) => user?.role === 'admin'
const posts = defineCollection({
slug: 'posts',
access: {
read: 'public',
create: ({ user }) => user !== null,
update: ({ user }) => user?.role === 'admin' || { author: { equals: user?.id } },
delete: isAdmin,
},
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'author', type: 'relationship', to: 'users' },
{ name: 'internalNotes', type: 'textarea', access: { read: isAdmin, update: isAdmin } },
],
})
export default defineConfig({
admin: { firstUserRole: 'admin' },
collections: [posts],
})

Léelo como lo leería el motor:

  • Cualquiera lee los posts, con sesión o sin ella. read: 'public' y no () => true: abren lo mismo, pero solo la cadena le dice al servidor de ficheros que puede cachear la respuesta de forma pública.
  • Crea quien tiene sesión.
  • Edita un administrador, o el autor del post: la condición se une a la consulta, así que para cualquier otra persona el post «no existe» (404).
  • Borra solo un administrador; una sesión que no lo es recibe un 403.
  • internalNotes se quita de lo que ve quien no es administrador, y escribirla se rechaza.

user?.role es string | null | undefined: toda política tiene que tratar role === null, porque las cuentas existentes quedan sin rol y solo la primera lo recibe.

El CMS da una columna, no una jerarquía. La colección users incluye un campo role de tipo text —un rol por cuenta— y lo deja en user.role de la sesión.

  • Es un text y no un select, a propósito: la lista de roles es tuya y better-auth escribe el campo como texto, así que el CMS no le impone opciones. Sin required ni defaultValue, la columna llega como una línea aditiva, sin NOT NULL ni DEFAULT.
  • La primera cuenta recibe el rol que tú nombres, y solo ese: admin.firstUserRole en el config. Sin esa opción no hay rol por defecto, y la primera cuenta queda con role en NULL igual que las demás.
  • Nadie se cambia el rol. El campo lleva un access.update que lo niega a toda persona: ni PATCH /api/cms/users/:id, ni el panel, ni /api/auth/update-user dejan que una cuenta se promocione. Lo escribe el servidor con overrideAccess: true, o tú por SQL. Si declaras tu propia función de access.update en el campo, la tuya gana, y es lo que abre la pantalla de cuentas del panel a dar y cambiar roles (ver Administrar cuentas desde el panel).
  • Una clave de API no tiene rol propio: actúa con el de su dueño, leído en cada petición. Cambiarle el rol a la cuenta cambia lo que la clave puede hacer, y suspender la cuenta (banned) corta la clave.
  • El plugin de administración de cuentas solo reconoce un rol, el de admin.firstUserRole (o admin), y no mira el access de tu config. Por eso sus endpoints (cambiar la contraseña de otra cuenta, suspenderla…) no están abiertos por HTTP: una cuenta con ese nombre de rol y permisos recortados en tu política tomaría la cuenta de un rol superior. El panel de usuarios (G2-C, #271) hace esas operaciones desde el servidor y con tu access decidiendo antes, así que un rol que el plugin no conoce (superadmin) también puede usarlas. Ver Cuentas suspendidas y administración de cuentas.
  • Un rol son letras, números, espacios y . _ - :, de hasta 64 caracteres y sin comas: el plugin de administración lee a,b como dos roles, y un rol con una coma le daría a la cuenta el del plugin. El panel lo rechaza al crear y al cambiar el rol.

El panel de /admin/collections/users da de alta cuentas, fija contraseñas, suspende, cierra sesiones y asigna roles, y está cerrado hasta que tu config declare quién puede: sin access.create (el alta) o access.update (lo demás) en users responde 403 y la pantalla dice qué declarar. Declarar esas funciones es lo que enciende el panel, y lo que escribas ahí decide quién toma las cuentas ajenas: una función abierta a toda cuenta que inicia sesión las entrega todas (ver el aviso de arriba). Con ellos declarados, cada acción pregunta a tu access de users antes de tocar nada:

  • Crear pregunta por create de users y, si el formulario trae un rol, por el access.update del campo role, con el cuerpo que se va a escribir (data.role).
  • Fijar la contraseña, suspender, levantar la suspensión y cerrar sesiones preguntan por read y por update de users con el documento de destino delante, así que una condición Where de tu política se evalúa contra esa fila.
  • Cambiar el rol pregunta además por el campo role, que por defecto lo niega a todo el mundo: es opt-in.
  • Suspender y levantar la suspensión preguntan además por banned, banReason y banExpires, que también niegan a todo el mundo por defecto: declara el access.update de los tres (se escriben los tres) o la pantalla no los ofrece. La función recibe lo que se va a escribir en data.

Escribe la jerarquía como una condición, y cuenta las cuentas sin rol:

const canBan = ({ user }: { user: { role?: string | null } | null }) =>
user?.role === 'superadmin' || user?.role === 'admin'
export default defineConfig({
admin: { firstUserRole: 'superadmin' },
collections: [
defineCollection({
slug: 'users',
fields: [
{
name: 'role',
type: 'text',
// El superadmin da cualquier rol; un admin solo puede dar `editor`
access: {
update: ({ user, data }) =>
user?.role === 'superadmin' ||
(user?.role === 'admin' && (data as { role?: unknown })?.role === 'editor'),
},
},
// Suspender: los tres campos, con la misma regla (si no declaras los tres, no hay suspensión)
{ name: 'banned', type: 'checkbox', access: { update: canBan } },
{ name: 'banReason', type: 'text', access: { update: canBan } },
{ name: 'banExpires', type: 'date', access: { update: canBan } },
],
access: {
read: ({ user }) => user !== null,
create: ({ user }) => user?.role === 'superadmin' || user?.role === 'admin',
update: ({ user }) =>
user?.role === 'superadmin' ||
(user?.role === 'admin' && {
or: [{ role: { exists: false } }, { role: { not_equals: 'superadmin' } }],
}),
},
}),
],
})

Con eso, un admin administra a los editor y a quien no tiene rol, pero recibe un 403 si intenta algo con un superadmin; y quien decide es tu access, no el plugin de better-auth, que solo conoce un nombre de rol (el de firstUserRole). Nadie se administra a sí mismo desde esa pantalla, y not_equals a secas dejaría fuera a las cuentas con role en NULL: falla cerrado, pero no era lo que querías.

No hay defecto abierto: sin access.create o access.update declarados en users, esas acciones responden 403 aunque el motor, sin función, dejara pasar a toda cuenta con sesión (que aquí sería tomar la cuenta del dueño del sitio).

Estas acciones escriben por internalAdapter de better-auth y no por la Local API de la colección, así que los hooks de la colección users de tu proyecto no se ejecutan al crear una cuenta, cambiar su rol ni suspenderla (un afterChange de auditoría, por ejemplo, no se entera). Si necesitas dejar rastro, hazlo en tu propio código alrededor del panel o en la base de datos.

Lo que no cambia: las rutas /api/auth/admin/* siguen cerradas, y un token Bearer o una X-API-Key no sirven para administrar cuentas ajenas aunque su dueño tenga permiso: solo vale la sesión del navegador.

Al actualizar a una versión con role, cms db:migrate genera ALTER TABLE users ADD role text. Léela y aplícala como cualquier migración: Schema y migraciones. Una cuenta que ya existía y debe ser administradora se promociona una vez, a mano:

Ventana de terminal
npx wrangler d1 execute DB --local --command "UPDATE users SET role = 'admin' WHERE email = 'tu@correo.com'"

La API local acepta, en cada operación, dos opciones nuevas:

Opción Qué hace
overrideAccess: true La llamada es del proyecto, no de nadie: se salta toda función de access
overrideAccess: false Aplica las funciones de access. Sin persona, la llamada es la de un visitante sin sesión
user: usuario La persona a la que se aplican, que sale de Astro.locals.cms.auth.getUser()

Si no dices nada, decide el valor por defecto, que es false: la llamada es anónima. El 401 que recibes en ese caso lleva una pista que te dice qué pasar.

Usa overrideAccess: true donde el servidor decide qué mostrar —una portada, un listado público, un seed—, y el usuario donde deba valer lo que esa persona puede:

src/pages/index.astro
---
export const prerender = false
// El servidor decide: la portada enseña los publicados, los vea o no quien visita.
const { docs } = await Astro.locals.cms.collections.posts.find({
where: { status: { equals: 'published' } },
overrideAccess: true,
})
---
src/pages/mis-notas.astro
---
export const prerender = false
const user = await Astro.locals.cms.auth.requireUser()
// Vale lo que esta persona puede leer: la condición de `notes.access.read` se aplica.
const { docs } = await Astro.locals.cms.collections.notes.find({ user })
---

Pasar { user } en cada llamada se vuelve pesado; forUser lo hace una vez. Devuelve { collections, globals } con cada método ya preajustado a ese usuario y a overrideAccess: false:

src/pages/mis-notas.astro
---
import { forUser } from '@kevolution-co/cms'
export const prerender = false
const user = await Astro.locals.cms.auth.getUser()
const cms = forUser(Astro.locals.cms, user)
const { docs } = await cms.collections.notes.find()
const total = await cms.collections.notes.count()
---

Lo que una llamada diga explícitamente gana al preajuste: cms.collections.posts.find({ overrideAccess: true }) sigue siendo la del sistema. Con getUser() en null, forUser actúa como un visitante.

overrideAccess: true se salta las funciones, no los invariantes del CMS: no abre el alta de cuentas en users, no deja escribir el email ni el emailVerified de nadie y no entra en las carpetas reservadas de la biblioteca (ver Lo que el acceso no ensancha).

Una relación hidratada es una lectura de la colección de destino, y se autoriza como tal: con el actor de la llamada, una vez por destino y nivel. Si no puede leer el destino, la relación se queda como id pelado, como cuando el documento se ha borrado. Si el read del destino es una condición, solo se hidrata lo que la cumple. Y los campos ilegibles del destino se recortan antes de sustituir el id.

El cms que recibe un hook corre como el sistema: un hook es código del proyecto, no de la petición, y no cambia de actor cuando cambia el valor por defecto. Un hook no recibe al usuario. Si necesita actuar como una persona, la llamada de dentro lo dice con { user, overrideAccess: false }.

Una función que contesta «nada» y un documento que una condición deja fuera no son lo mismo, y por eso no responden lo mismo:

Situación API local REST
Sin sesión, y la regla no deja pasar UnauthorizedError 401 UNAUTHORIZED
Con sesión, y la función dice false ForbiddenError 403 FORBIDDEN
La condición deja fuera el documento (findByID, update, delete) NotFoundError 404 NOT_FOUND, idéntico al de un id que no existe
La condición deja fuera filas de un listado Esas filas no salen, y pagination.totalDocs no las cuenta Igual

La razón del 404 es no revelar existencia: si un 403 distinguiera «existe y no es tuyo» de «no existe», cualquiera podría sondear ids ajenos. Un false, en cambio, se contesta antes de preguntar si el documento existe, así que tampoco revela nada.

Algunos detalles que importan:

  • Una condición que sale falsa también es un 404 para un visitante. En el ejemplo de arriba, un PATCH anónimo a un post responde 404, no 401, porque update devolvió una condición y no un false. Si prefieres el 401, devuelve false para user === null.
  • update con If-Match viejo sobre un documento fuera de la condición es un 404, nunca un 412.
  • Un delete con condición comprueba antes que el documento entra en ella: si no, 404, y ni beforeDelete ni la guarda de referencias llegan a correr.
  • Una función que no deja pasar una subida lo hace antes de tocar R2: no se escribe ni un byte.

Un campo con access se evalúa una vez por colección y operación, con { user } (y id en findByID):

  • Lo que no puede leer se quita, no se pone a null: la clave desaparece del documento, también de los documentos hidratados con depth. Los hooks sí ven el documento entero; el recorte va después de ellos.
  • where, sort y select sobre un campo ilegible lanzan el mismo QueryError que un campo que no existe, en cualquier nivel de and/or y también en count. No hay forma de adivinar su valor filtrando.
  • Escribir un campo que no puede escribir rechaza la petición entera, sin escribir nada y con todas las claves a la vez: READ_ONLY_FIELD si el campo se puede leer, UNKNOWN_FIELD si no. Solo cuentan las claves que vienen con un valor.
  • La respuesta de una escritura no se vuelve a comprobar contra el read de la colección: quien acaba de escribir un documento lo recibe, sin los campos que no puede leer.

Un global es un único documento en KV, así que su política es de todo o nada:

cms.config.ts
defineGlobal({
slug: 'site',
access: {
read: 'public',
update: ({ user }) => user?.role === 'admin',
},
fields: [{ name: 'tagline', type: 'text' }],
})

read recibe { user } y update recibe { user, data }, el cuerpo tal como llegó. Ninguna recibe id. Ambas se evalúan antes de tocar KV: quien no tiene permiso no aprende ni si falta el namespace.

El panel pregunta a la misma función en cada vista: oculta lo que la persona no puede leer, pinta en solo lectura lo que no puede editar y esconde los botones que la operación rechazaría. Es una ayuda para la vista: el rechazo real es de la operación, y un formulario fabricado a mano recibe el mismo 403.

Estas reglas valen para cualquier actor, overrideAccess: true incluido, y ninguna función las abre:

  • users no se crea escribiendo en ella. Un access.create: () => true en users no abre el alta: el registro lo cierra la primera cuenta. Tampoco se escriben el email ni el emailVerified de nadie. role, banned, banReason y banExpires solo los escribe el sistema (SQL, overrideAccess: true) o auth.api desde el servidor: ninguna función de access abre su PATCH a una persona.
  • Las carpetas reservadas de ssd (las que empiezan por .) no se tocan desde fuera.
  • media.access.list sigue gobernando el listado de la biblioteca por REST, y solo por REST.
  • El servidor de ficheros lee con el acceso de la colección del fichero, sin regla propia. Un fichero que una condición oculta responde 404, sin cuerpo ni ETag, y el Cache-Control es private, no-store para toda colección que no sea read: 'public' (la biblioteca ssd sigue con el público e immutable).
  • /api/cms/settings: leer los ajustes públicos pide sesión como siempre y, si el config declara access.admin, también que pase. Escribirlos (PATCH) además pide access.settings, o el rol de admin.firstUserRole si no lo declaras: una cuenta que no administra no puede cambiar el siteUrl ni el remitente de los correos por la puerta de atrás, ni con cookie ni con una clave de API.

Y una consecuencia para borrar un fichero: la guarda REFERENCED cuenta todo lo que lo usa, pero solo nombra lo que quien borra puede leer. Si no puede leer ninguna referencia, la negativa sale igual: «lo usan documentos que no puedes ver», con el recuento.

Lo que sigue es real y está comprobado; ninguna de estas cosas es un descuido que vaya a repararse sola.

Con funciones declaradas, REST lee el cuerpo antes del 401. Sin ninguna función en el proyecto, una escritura sin sesión recibe su 401 antes de que se lea nada. En cuanto declaras una, la decisión es de la operación, y la operación llega después de leer el cuerpo: una subida o el complete de una subida por trozos anónimos se leen enteros antes de que se conteste el 401, un JSON roto da su 400 antes que el 401, y un PATCH de un global con If-Match da su 412. Es un coste conocido que se documenta y se deja; si te preocupa, ponle delante una regla de rate limiting de Cloudflare en las rutas de subida.

Con funciones declaradas, una lectura pública también mira la sesión. Lo hace para saber si alguna función tiene algo que decir, y eso incluye cada fichero que sirve ssd: cuesta una consulta de sesión por descarga. Sin funciones en el config, una lectura pública no mira la sesión, salvo que la petición lleve una credencial de cabecera (Authorization: Bearer o X-API-Key): entonces se comprueba, para que un token caducado o una clave revocada reciba su 401 y no lo público.

La biblioteca ssd sigue siendo pública para la API local, y su acceso por funciones no existe todavía. Una llamada anónima a cms.collections.ssd.find() la lista, media.access.list solo gobierna REST, y no se puede declarar un access propio para ella. Sus escrituras sí piden sesión.

La pantalla «Sin autorización» no se hidrata: el botón de cerrar sesión es un formulario nativo.

No hay roles. Una cuenta tiene un solo role: una lista de roles no existe todavía.

Y estas fugas no las cierra un acceso por consulta, aunque conviene saberlas:

  • Un campo unique revela que un valor existe en un documento que la persona no puede leer: el error de duplicado lo dice.
  • Un onDelete: 'cascade' borra los documentos de otras colecciones sin evaluar su access.delete.
  • Una relación puede apuntar a un documento que quien escribe no puede leer.
  • La condición de update y delete se evalúa sobre la fila anterior a la escritura: un update puede sacar un documento de su propio alcance.
  • Si una consulta, con la condición de acceso incluida, supera los 100 parámetros que admite D1, sale como QueryError 400. Se documenta, no se arregla.