zenstack-access-control — Claude Code skill for access rules
The zenstack-access-control Claude Code skill helps define access policies in a ZenStack V3 schema. It activates for @@allow, @@deny, auth(), and post-update rules.
MIT 556 installs ★ 3 updated 2026-10-28
npx skills add zenstackhq/skills --skill zenstack-access-control -a claude-codeWhat zenstack-access-control does
The skill guides access policy work in ZenStack V3 schemas. It covers model and field rules, binding the current user with $setAuth(), and configuring the policy plugin.
For policies to take effect at runtime, declare @zenstackhq/plugin-policy in the schema and install it with npm install @zenstackhq/plugin-policy. Run zen generate after editing policies; it also validates the schema. Use zen check to validate without regenerating the client.
Database cascade operations and triggers are outside policy enforcement. Raw SQL and query-builder access bypass policies; allowing raw SQL with the plugin requires dangerouslyAllowRawSql: true in v3.5.0+.
What it helps with
- define record access with
@@allowand@@deny - bind the current user to a client with
$setAuth() - restrict reads or updates to specific fields
- express conditions that must hold after an update
Example prompts for the agent
- Add
@@allowand@@denyrules to my ZenStack V3 models. - Configure
auth()and bind the current user with$setAuth(). - Hide a field from anonymous users and add a
post-updaterule.
How to install zenstack-access-control
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-access-control -a claude-code2Manually: put the files in place
~/.claude/skills/zenstack-access-control/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/zenstack-access-control/
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-access-control -a codex2Manually: put the files in place
.agents/skills/zenstack-access-control/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-access-control -a cursor2Manually: put the files in place
.cursor/skills/zenstack-access-control/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install zenstackhq/skills skills/zenstack-access-control2Manually: put the files in place
.github/skills/zenstack-access-control/SKILL.md1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-access-control -a gemini-cli2Platform CLI
gemini skills install https://github.com/zenstackhq/skills --path skills/zenstack-access-controlManually: put the files in place
.devin/skills/zenstack-access-control/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-access-control -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about zenstack-access-control
How do I install zenstack-access-control in Claude Code?
Run npx skills add zenstackhq/skills --skill zenstack-access-control -a claude-code. The skill file is at ~/.claude/skills/zenstack-access-control/SKILL.md.
What does zenstack-access-control do?
It helps define ZenStack V3 access policies for models and fields, connect them to auth(), and configure runtime policy enforcement.
What does zenstack-access-control need to work?
It requires a ZenStack V3 schema and the @zenstackhq/plugin-policy package, declared in the schema and installed with npm install @zenstackhq/plugin-policy. Run zen generate after changing policies to regenerate the client.
Source text
SKILL.md · MIT
---
name: zenstack-access-control
description: Add access control to a ZenStack V3 schema. Use when writing access policies (@@allow / @@deny), the auth() function, field-level rules, post-update rules, or setting up the policy plugin and $setAuth runtime. (For data validation — @email/@length/@@validate — see zenstack-querying.)
---
# 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:**
```ts
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.
```ts
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/`](references/):
- [access-control-overview.md](references/access-control-overview.md) — how access control works
- [write-policies.md](references/write-policies.md) — `@@allow`/`@@deny`, `auth()`, expressions
- [enforcing-policies.md](references/enforcing-policies.md) — policy plugin + `$setAuth` runtime
- [post-update.md](references/post-update.md) — `post-update` rules and `before()`
- [field-level.md](references/field-level.md) — field-level read/update policies
- [zmodel-expression-reference.md](references/zmodel-expression-reference.md) — policy expression reference
- [policy-plugin-reference.md](references/policy-plugin-reference.md) — policy plugin options
© zenstackhq · MIT · zenstackhq/skills