Guard / How Guard works
Real scenarios you can model today
The same Guards.attach declaration covers row access, field locks, redaction, related tables, UI hints, offline sync, AI agents, and file uploads.
Multi-tenant isolation, field locks, and redaction
Use always for rules every action must obey and no role can override. Use Write as shorthand for Create, Update, and Delete, Interaction.make for custom actions, Guards.on with Guards.explain or Guards.redact for custom denials, and [] (an empty OR list) to allow nobody:
import { Option, Schema } from 'effect'
import { Entity, Expr } from 'foldkit-entity'
import { Guards, Interaction } from 'foldkit-guard'
const Staff = Schema.Struct({
id: Schema.String,
orgId: Schema.String,
role: Schema.Literals(['admin', 'member']),
})
const TicketFields = Entity.define(
'Ticket',
Schema.Struct({
id: Schema.String,
orgId: Schema.String,
assigneeId: Schema.String,
internalNote: Schema.String,
}),
)
const G = Guards.declare(
'Tickets',
Staff,
guard => ({
isAdmin: guard.principal(),
inOrg: guard.row(TicketFields, p => Expr.eq(TicketFields.fields.orgId, p.orgId)),
isAssignee: guard.row(TicketFields, p => Expr.eq(TicketFields.fields.assigneeId, p.id)),
}),
{ key: p => p.id, unguarded: 'deny' },
)
const Close = Interaction.make('Close')
const Ticket = TicketFields.pipe(
Guards.attach(G, {
always: [G.inOrg],
row: { Read: [G.inOrg], Write: [G.isAssignee, G.isAdmin] },
interactions: {
[Close.key]: Guards.on([G.isAdmin], Guards.explain('Only an admin can close tickets.')),
},
members: {
orgId: { Update: [] },
internalNote: { Read: Guards.on([G.isAdmin], Guards.redact('[hidden]')) },
},
}),
)
const summary = Guards.matrix([Ticket])Guards.matrix([Ticket]) returns a plain-text audit table listing every rule: always: inOrg, Ticket.Read: inOrg → not_found, Ticket.Update: isAssignee | isAdmin → forbidden, Ticket.Close: isAdmin → explain("Only an admin can close tickets."), Ticket.orgId.Update: nobody → forbidden, and Ticket.internalNote.Read: isAdmin → redact("[hidden]"). By default, a denied Read returns not_found so callers cannot tell hidden rows exist, while a denied write returns forbidden. Because inOrg is in always, even an admin stays inside their own organization, and Update: [] makes orgId immutable.
Inherited and cross-row permissions
Use Entity.relate and Relation.one to link tables, then use Guards.inherit so child rows copy their parent's Read rule, or Expr.path to read a parent column directly:
import { Schema } from 'effect'
import { Entity, Expr, Relation } from 'foldkit-entity'
import { Guards } from 'foldkit-guard'
const User = Schema.Struct({ id: Schema.String, projectIds: Schema.Array(Schema.String) })
const ProjectFields = Entity.define('Project', Schema.Struct({ id: Schema.String }))
const TaskFields = Entity.define('Task', Schema.Struct({ id: Schema.String, title: Schema.String }))
const { Project: ProjectRel, Task: TaskRel } = Entity.relate(
{ Project: ProjectFields, Task: TaskFields },
{ Task: { project: Relation.one(ProjectFields) } },
)
const G = Guards.declare(
'Work',
User,
guard => ({
inProject: guard.row(ProjectRel, p => Expr.in(ProjectRel.fields.id, p.projectIds)),
projectMember: guard.row(TaskRel, p =>
Expr.in(Expr.path(TaskRel.relations.project, ProjectRel.fields.id), p.projectIds),
),
}),
{ key: p => p.id, unguarded: 'deny' },
)
const Project = ProjectRel.pipe(Guards.attach(G, { row: { Read: [G.inProject] } }))
const Task = TaskRel.pipe(
Guards.attach(G, { row: { Read: [Guards.inherit('project')], Update: [G.projectMember] } }),
)Expr.in checks membership in the user's projectIds list, and Guards.inherit('project') compiles to a SQL subquery over Project's Read rule (checking for cycles at startup). Cross-row rules (Expr.path or Expr.exists) work on Read, Update, and Delete, where SQL evaluates them in the statement. Guards.attach refuses cross-row rules on Create, members, or single-row handlers at setup time.
One declaration across every boundary
Every other Foldkit Plus package enforces the same attached rules through its own Guard subpath:
| Boundary | Subpath | What it enforces |
|---|---|---|
| SQL reads (Drizzle) | foldkit-guard/drizzle | Compiles Read and always into SQL WHERE clauses (GuardDrizzle.visible). |
Member reads & may | foldkit-guard/server | Omits or redacts hidden fields and computes may (GuardServer.filter). |
| Declared writes | foldkit-guard/server | Checks row, member, link, revision, and cascade rules (GuardServer.writer). |
| Custom handlers | foldkit-guard/server | Checks a named Interaction before running (GuardServer.mutation). |
| Route-level UI | foldkit-guard | Serves one Me row (signedIn, key, may) via Guards.me and GuardServer.me. |
| Offline Sync | foldkit-guard/sync | Guards sync journal opens, admits, and edits (GuardSync.document, admit). |
| AI agents | foldkit-guard/agent | Gates tool visibility and dispatch on may (GuardAgent.available, authorize). |
| File uploads | foldkit-guard/media | Checks principal guards on upload routes (GuardMedia.uploadPolicy). |
may is always a client hint. The browser never receives G.implement, and the server ignores client may values and re-checks every write when it commits.