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:

ts
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:

ts
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:

BoundarySubpathWhat it enforces
SQL reads (Drizzle)foldkit-guard/drizzleCompiles Read and always into SQL WHERE clauses (GuardDrizzle.visible).
Member reads & mayfoldkit-guard/serverOmits or redacts hidden fields and computes may (GuardServer.filter).
Declared writesfoldkit-guard/serverChecks row, member, link, revision, and cascade rules (GuardServer.writer).
Custom handlersfoldkit-guard/serverChecks a named Interaction before running (GuardServer.mutation).
Route-level UIfoldkit-guardServes one Me row (signedIn, key, may) via Guards.me and GuardServer.me.
Offline Syncfoldkit-guard/syncGuards sync journal opens, admits, and edits (GuardSync.document, admit).
AI agentsfoldkit-guard/agentGates tool visibility and dispatch on may (GuardAgent.available, authorize).
File uploadsfoldkit-guard/mediaChecks 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.