Policies

A policy is a boolean expression evaluated on every row access. It lives beside your entities.

import { policy } from "@pylonsync/sdk";

const noteOwner = policy({
  name: "note_owner",
  entity: "Note",
  allowRead: "true",
  allowInsert: "auth.userId == data.authorId",
  allowUpdate: "auth.userId == data.authorId",
  allowDelete: "auth.userId == data.authorId",
});

What the expressions see

Binding	Type	Contains
`auth.userId`	`string \| null`	Current user’s id, `null` if unauthenticated
`auth.isAdmin`	`boolean`	`true` for the `admin` role / admin token / Studio session
`auth.tenantId`	`string \| null`	Selected organization id (multi-tenant apps)
`data.*`	`object`	The row: incoming payload on insert; the stored row on read/delete; on update, see `allowUpdate` below
`existing.*`	`object`	Synonym for `data.*`
`now`	`string`	Current UTC time as an ISO-8601 string, for time windows
`ago("30d")`	`string`	The instant that long before `now`, for rolling windows. Units `s`/`m`/`h`/`d`/`w`, compound allowed (`"1d12h"`). A malformed duration fails at boot, not silently at evaluation
`len(data.bio)`	`number \| null`	The length of a string field in characters (Unicode code points). `null` when the value is not a string, so a comparison with it denies

Roles are checked with the auth.hasRole("x") / auth.hasAnyRole("a", "b") functions (below). There is no auth.roles array and no auth.email binding in policy expressions. (Email/roles live on the session and the SSR page auth prop, just not in the policy evaluator.)

Each action

allowRead — runs on query results. If false, row is filtered out.
allowInsert — runs against the proposed data (the incoming row).
allowUpdate — runs twice, and both must pass. First on the stored row, so a caller can’t edit a row it doesn’t own. Then on the row after the write (the stored row with the patched fields applied), so a caller can’t move a row out of its scope. With auth.tenantId == data.orgId, a member can edit their org’s rows, but a patch of { orgId: "<other org>" } is denied. data and existing both name the row being checked in each pass. This is the same as a Postgres RLS USING clause that also serves as WITH CHECK. It applies to every client write: PATCH /api/entities, /api/sync/push, /api/link, /api/unlink, and CRDT pushes. A state change the rule forbids for the new row (for example data.status == "draft" and an edit that publishes) is denied; make that change in a server function.
allowDelete — runs against the stored row (data / existing).

If a policy is omitted, that action is denied by default.

Operators

The policy language is deliberately tiny. The complete operator set is:

==    !=                       // equality
<     <=    >    >=            // ordering (see below)
&&    ||    !                  // boolean logic
true  false  null              // literals
42    -3    4.5                // numeric literals (int / float / negative)
"string"  'string'             // string literals (either quote)

Plus these built-in forms:

auth.hasRole("admin")               // role check
auth.hasAnyRole("admin", "owner")   // any-of role check
ago("30d")                          // timestamp that duration before now (s/m/h/d/w)
len(data.bio)                       // string length in characters
exists(Entity where field == <expr> [and field == <expr>]*)   // correlated subquery

Ordering (< <= > >=) compares numbers numerically, two strings chronologically when both are valid ISO-8601 timestamps (else lexicographically), and is deny-safe otherwise: comparing null, a boolean, or a number against a non-numeric string is always false. This is what makes data.publishAt <= now deny rows that aren’t published yet. There is still no in, no ends_with/starts_with, and no arithmetic (+ - * /). Membership is expressed with exists(...), not in. String prefix/suffix matching belongs in a function.

Examples

Public read, author-only write

policy({
  name: "post_public",
  entity: "Post",
  allowRead: "true",
  allowInsert: "auth.userId == data.authorId",
  allowUpdate: "auth.userId == existing.authorId",
  allowDelete: "auth.userId == existing.authorId",
});

Members of an org

Membership lives in a join entity (OrgMember { orgId, userId }) and is checked with exists(...):

policy({
  name: "org_member",
  entity: "Document",
  allowRead: "exists(OrgMember where orgId == existing.orgId and userId == auth.userId)",
  allowInsert: "exists(OrgMember where orgId == data.orgId and userId == auth.userId)",
  allowUpdate: "exists(OrgMember where orgId == existing.orgId and userId == auth.userId)",
});

Adding or removing a membership changes who may read the documents without changing the documents. When a synced entity’s read policy or sync scope uses exists(Source where ... field == auth.userId), a change to a Source row tells the user that row names (before and after the change) to re-sync that entity: their open pages get the rows they may now read and drop the rows they may not. Three limits apply:

The user is told only if they may read the Source row, so a private row never reveals itself.
An update is told only when it changes a field the exists() conditions name.
An exists() with no == auth.userId condition names no user.

In those cases the change reaches open pages at the next reconnect or tab focus.

Admin override

policy({
  name: "admin_all",
  entity: "AuditLog",
  allowRead: "auth.isAdmin",          // or: auth.hasRole("admin")
  allowInsert: "auth.isAdmin",
});

Time window (scheduled publishing)

now plus an ordering comparison gates rows by time — public once published, with the author still able to preview:

policy({
  name: "post_published",
  entity: "Post",
  allowRead: "data.publishAt <= now || auth.userId == data.authorId",
});

Rolling time window

ago(...) compares against a moving cutoff instead of a stored timestamp. As a read policy it hides old rows everywhere; more commonly it belongs in a sync scope (sync: { where: ... } on the entity), where it bounds the client replica of an append-only table — recent rows stay live, old rows stay reachable through direct reads and queries:

const Event = entity(
  "Event",
  { name: field.string(), createdAt: field.datetime() },
  // Replicate only the last 30 days into browsers; the table itself
  // grows forever without growing every client's replica or catch-up.
  { sync: { where: 'data.createdAt >= ago("30d")', limit: 20_000 } },
);

Policy composition

Multiple policies on the same entity AND together — all must pass. Use this to layer a broad rule with a narrow exception:

const readable = policy({ name: "readable", entity: "Doc", allowRead: "true" });
const noDrafts = policy({
  name: "no_drafts",
  entity: "Doc",
  allowRead: "existing.status != 'draft' || auth.userId == existing.authorId",
});

Server functions bypass policies

Policies guard the raw /api/entities/* endpoints. Server functions (ctx.db.insert, ctx.db.update, etc.) run with elevated access — they trust you to enforce your own checks inside the handler. This lets you write escape-hatch operations (admin tools, batch imports) without contorting your policy language.

Functions

Write server logic for anything policies can’t express.

Live queries

Policies also filter subscription results.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

What the expressions see

Each action

Operators

Examples

Public read, author-only write

Members of an org

Admin override

Time window (scheduled publishing)

Rolling time window

Policy composition

Server functions bypass policies

Next

Functions

Live queries

​What the expressions see

​Each action

​Operators

​Examples

​Public read, author-only write

​Members of an org

​Admin override

​Time window (scheduled publishing)

​Rolling time window

​Policy composition

​Server functions bypass policies

​Next

Functions

Live queries

What the expressions see

Each action

Operators

Examples

Public read, author-only write

Members of an org

Admin override

Time window (scheduled publishing)

Rolling time window

Policy composition

Server functions bypass policies

Next