ZenStack V3 — Access Control

ZenStack enforces access policies declared in ZModel at the ORM layer. Policies live next to your models (see

zenstack-schema-modeling

); enforcement is opt-in via a runtime plugin. For client/query basics — and for data validation — see

zenstack-querying

After editing policies, run

zen generate

to regenerate the client (it also validates the schema, policy expressions included). If you only want to validate without regenerating, run

zen check

Runtime setup (required for policies to apply)

Policies do nothing until you (1) declare the plugin in the schema and (2) install it on the client.

Schema:

zmodel

plugin policy {
    provider = '@zenstackhq/plugin-policy'
}

Install the package:

npm install @zenstackhq/plugin-policy

Client:

import { ZenStackClient } from '@zenstackhq/orm';
import { PolicyPlugin } from '@zenstackhq/plugin-policy';

const db = new ZenStackClient(schema, { dialect });   // raw, unprotected
export const authDb = db.$use(new PolicyPlugin());     // access control enforced

ZenStackClient

instances are immutable —

$use()

and

$setAuth()

return new (cheap, shallow- clone) instances and never mutate the original. Query with

db

to bypass policies (e.g. trusted server code) and with the policy-enforced client for user-facing access.

The current user —

auth()

and

$setAuth()

Bind the authenticated user per request;

auth()

in policies resolves to it.

const userDb = authDb.$setAuth(user);   // user-bound client
await userDb.post.findMany();           // policies evaluated against `user`

No
```
$setAuth()
```
→ anonymous mode →
```
auth()
```
is
```
null
```
.
```
$setAuth(undefined)
```
forces anonymous.
Read the bound user back via
```
client.$auth
```
.

Define what
auth()
returns, by priority: a

model

type

annotated

@@auth

, otherwise a model literally named

User

, otherwise a compile error. Using a

type

decouples the auth shape from your tables:

zmodel

type Auth {
    id   Int
    role String
    @@auth
}

Policy rules —

@@allow

@@deny

@@allow(operation, condition)
@@deny(operation, condition)

Operations (comma-separate to combine):

create

read

update

delete

post-update

, and

all

(= create+read+update+delete, not post-update).

Evaluation (secure by default): any matching

@@deny

→ denied; else any matching

@@allow

→ allowed; else denied.

read

update

delete

silently filter out rows that fail, rather than erroring;

create

is checked before insert.

zmodel

model User {
    id    Int    @id @default(autoincrement())
    email String @unique
    posts Post[]

    @@allow('create,read', true)        // anyone can sign up; profiles public
    @@allow('all', auth().id == id)     // the user has full access to themselves
}

model Post {
    id        Int     @id @default(autoincrement())
    title     String
    published Boolean @default(false)
    author    User    @relation(fields: [authorId], references: [id])
    authorId  Int

    @@deny('all', auth() == null)       // no anonymous access
    @@allow('read', published)          // published posts readable by anyone
    @@allow('all', auth().id == authorId) // author has full access
}

Policy expressions

Operators:
```
==
```
```
!=
```
```
>
```
```
>=
```
```
<
```
```
<=
```
,
```
&&
```
```
||
```
```
!
```
, and field references.
To-one relations: dot access —
```
auth().city == profile.address.city
```
.

To-many relations: collection predicates

```
relation?[cond]
```
— some match
```
relation![cond]
```
— all match
```
relation^[cond]
```
— none match

zmodel

@@deny('delete', posts?[published == true])   // can't delete a user with published posts

Use

this

to escape the collection scope:

comments?[author.verified && this.published]

create
rules can only reference owned relations (those whose FK the model holds) — other relations don't exist yet at creation time.

check(relation [, op])
delegates the check to a to-one relation's policies, avoiding duplication:

@@allow('read', check(user))

@@allow('update', check(user, 'update'))

Helper functions usable in expressions:
```
contains
```
,
```
startsWith
```
,
```
endsWith
```
(each takes an optional case-insensitive flag),
```
has
```
,
```
hasSome
```
,
```
hasEvery
```
,
```
isEmpty
```
,
```
currentModel()
```
,
```
currentOperation()
```
.

Field-level policies (v3.2.0+, preview)

Single-

@allow

@deny

on a field, operations

read

and

update

only.

zmodel

model User {
    id    Int    @id
    email String @allow('update', auth() == this)  // only the owner can change it
    name  String @deny('read', auth() == null)     // hidden from anonymous readers
}

Failing a read policy nullifies the field (returned as
```
null
```
, still usable in SQL computations) — you can't distinguish a real
```
null
```
from a denied one.
Failing an update policy rejects the whole update (
```
ORMError
```
, reason
```
REJECTED_BY_POLICY
```
).

Post-update rules

post-update

expresses conditions that must hold after an update; field references see the new values, and

before()

reads the old values. (This replaces V2's

future()

zmodel

model Post {
    published Boolean @default(false)
    authorId  Int

    @@deny('post-update', published == true && auth().id != authorId)  // only author can publish
    @@deny('post-update', before().authorId != authorId)               // authorId is immutable
}

If a model has no

post-update

rule, an update only needs to pass

update

. If it has any, at least one

@@allow('post-update', ...)

must pass.

Execution order & error reasons

Per mutation, policies are checked before the database is touched (after any input validation — see

zenstack-querying

). Policy-related

ORMError.reason

values:

REJECTED_BY_POLICY

(policy) and

NOT_FOUND

(missing or filtered out by a read policy).

REJECTED_BY_POLICY

further carries

rejectedByPolicyReason

NO_ACCESS

CANNOT_READ_BACK

(mutation allowed but result not readable back), or

OTHER

Limitations

Database-level cascade deletes/updates and triggers are not policed by ZenStack.
Raw SQL (
```
$queryRaw
```
/
```
$executeRaw
```
) and query-builder access bypass policies. Allow raw SQL while the policy plugin is installed only via
```
new PolicyPlugin({ dangerouslyAllowRawSql: true })
```
(v3.5.0+).

Reference docs

Full ZenStack documentation for this topic is bundled under

references/

access-control-overview.md — how access control works
write-policies.md —
```
@@allow
```
/
```
@@deny
```
,
```
auth()
```
, expressions
enforcing-policies.md — policy plugin +
```
$setAuth
```
runtime
post-update.md —
```
post-update
```
rules and
```
before()
```
field-level.md — field-level read/update policies
zmodel-expression-reference.md — policy expression reference
policy-plugin-reference.md — policy plugin options

zenstack-access-control

NPX Install

Tags

SKILL.md Content

ZenStack V3 — Access Control

Runtime setup (required for policies to apply)

The current user —
`auth()`
and
`$setAuth()`

Policy rules —
`@@allow`
/
`@@deny`

Policy expressions

Field-level policies (v3.2.0+, preview)

Post-update rules

Execution order & error reasons

Limitations

Reference docs

zenstack-access-control

NPX Install

Tags

SKILL.md Content

ZenStack V3 — Access Control

Runtime setup (required for policies to apply)

The current user — auth() and $setAuth()

Policy rules — @@allow / @@deny

Policy expressions

Field-level policies (v3.2.0+, preview)

Post-update rules

Execution order & error reasons

Limitations

Reference docs

The current user —
`auth()`
and
`$setAuth()`

Policy rules —
`@@allow`
/
`@@deny`