Policies (PolicyDecl)

Generated from the doc schema (CatalogDocSchema, @canonify/kernel-catalog/doc): each field’s type, default and description are the schema’s own, and each example is a bundle file that readBundle decodes. A field’s Example is its value in one of those examples.

PolicyDecl

A policy: who may do what, on which rows and columns (authz).

The policies slot of the doc holds these, keyed by id. In a bundle each is one file, policies/<name>.json, named by its name, which the file then leaves out.

One of, told apart by mode:

PolicyDecl.permit

A permit: grants the operations (the union of every matching permit). A permit adds to the role baselines; it never narrows them. To narrow, write a restrict or a deny.

Field	Type	Required	Default	Example	Description
`id`	PolicyId	yes (propose assigns it; a new declaration leaves it out)	—	—	A policy id (`po_…`); renames keep it.
`name`	Ident	yes	—	`"members_own_orders"`	The policy name.
`label`	Text	yes	—	`"Members see their own orders"`	The words shown for it.
`subject`	Subject	yes	—	`{"role":"member"}`	Who it applies to.
`on`	ResourceSel	yes	—	`{"types":["ty_3f8v6h2n0c"]}`	What it is about.
`ops`	AccessOp[] (at least one)	yes	—	`["read","update"]`	The operations it is about.
`reason`	MsgRef	no	—	`{"text":"You can only work on your own orders."}`	What a refusal or a “why” shows for it.
`mode`	`"permit"`	yes	—	`"permit"`	permit: it grants the operations on the rows and columns it covers.
`rows`	Expr	no	—	`"owner == me.member"`	A CX condition over the type’s row and `me`: the rows it covers. Unknown on a row = not covered; absent = every row.
`check`	Expr	no	—	`"owner == me.member"`	A CX condition the row must hold after a create, update or transition (WITH CHECK); absent = the same as rows.
`columns`	ColumnSel	no	—	`{"mode":"mask","props":["pr_8b2f4h6j0k"]}`	The columns it shows, masks or hides; absent = every column.

policies/members_own_orders.json

{
  "label": "Members see their own orders",
  "mode": "permit",
  "subject": { "role": "member" },
  "on": { "types": ["ty_3f8v6h2n0c"] },
  "ops": ["read", "update"],
  "rows": "owner == me.member",
  "check": "owner == me.member",
  "columns": { "mode": "mask", "props": ["pr_8b2f4h6j0k"] },
  "reason": { "text": "You can only work on your own orders." }
}

PolicyDecl.restrict

A restrict: a wall on rows, which every grant must also pass.

Field	Type	Required	Default	Example	Description
`id`	PolicyId	yes (propose assigns it; a new declaration leaves it out)	—	—	A policy id (`po_…`); renames keep it.
`name`	Ident	yes	—	`"drivers_own_region"`	The policy name.
`label`	Text	yes	—	`"Drivers stay in their region"`	The words shown for it.
`subject`	Subject	yes	—	`{"group":"gr_5r7t9w1y3a"}`	Who it applies to.
`on`	ResourceSel	yes	—	`{"types":["ty_3f8v6h2n0c"]}`	What it is about.
`ops`	AccessOp[] (at least one)	yes	—	`["read"]`	The operations it is about.
`reason`	MsgRef	no	—	`{"text":"Drivers work only in the north region."}`	What a refusal or a “why” shows for it.
`mode`	`"restrict"`	yes	—	`"restrict"`	restrict: a wall; whatever else grants the operations, only the rows it covers.
`rows`	Expr	no	—	`"region == \"north\" \|\| lines.any(l => l.qty > 0)"`	A CX condition over the type’s row and `me`: the rows it covers. Unknown on a row = not covered; absent = every row.
`check`	Expr	no	—	`"region == \"north\""`	A CX condition the row must hold after a create, update or transition (WITH CHECK); absent = the same as rows.
`except`	Subject[] (at least one)	no	—	`[{"member":"u-01HZY8Q2:person"}]`	The actors it does not bind: an actor any of these names (at its standing and its stored standing alike) passes it. Absent = it binds every actor its subject names.
`direct`	`true`	no	—	`true`	true: it binds only writes made under the invoker’s own rights; an action that writes with its own rights (writeRights: action) passes it. Only on types and write ops.

policies/drivers_own_region.json

{
  "label": "Drivers stay in their region",
  "mode": "restrict",
  "subject": { "group": "gr_5r7t9w1y3a" },
  "on": { "types": ["ty_3f8v6h2n0c"] },
  "ops": ["read"],
  "rows": "region == \"north\" || lines.any(l => l.qty > 0)",
  "check": "region == \"north\"",
  "reason": { "text": "Drivers work only in the north region." }
}

policies/drivers_ship_north_themselves.json

{
  "label": "Drivers ship north orders themselves",
  "mode": "restrict",
  "subject": { "role": "member" },
  "on": { "types": ["ty_3f8v6h2n0c"] },
  "ops": [{ "transition": "tn_6s8v0x2z4b" }],
  "rows": "region == \"north\"",
  "except": [{ "member": "u-01HZY8Q2:person" }],
  "direct": true
}

PolicyDecl.deny

A deny: a bar on the resource or on some of its columns.

Field	Type	Required	Default	Example	Description
`id`	PolicyId	yes (propose assigns it; a new declaration leaves it out)	—	—	A policy id (`po_…`); renames keep it.
`name`	Ident	yes	—	`"drivers_no_money"`	The policy name.
`label`	Text	yes	—	`"Drivers never see money"`	The words shown for it.
`subject`	Subject	yes	—	`{"group":"gr_5r7t9w1y3a"}`	Who it applies to.
`on`	ResourceSel	yes	—	`{"types":["ty_3f8v6h2n0c"]}`	What it is about.
`ops`	AccessOp[] (at least one)	yes	—	`["read"]`	The operations it is about.
`reason`	MsgRef	no	—	`{"text":"Prices are for the office."}`	What a refusal or a “why” shows for it.
`mode`	`"deny"`	yes	—	`"deny"`	deny: a bar; the operations are refused, on the whole resource or on the columns it names.
`columns`	ColumnSel	no	—	`{"mode":"hide","props":["pr_8b2f4h6j0k"]}`	The columns it bars; absent = the whole resource.
`except`	Subject[] (at least one)	no	—	`[{"group":"gr_5r7t9w1y3a"}]`	The actors it does not bind: an actor any of these names (at its standing and its stored standing alike) passes it. Absent = it binds every actor its subject names.
`direct`	`true`	no	—	`true`	true: it binds only writes made under the invoker’s own rights; an action that writes with its own rights (writeRights: action) passes it. Only on types and write ops.

policies/drivers_no_money.json

{
  "label": "Drivers never see money",
  "mode": "deny",
  "subject": { "group": "gr_5r7t9w1y3a" },
  "on": { "types": ["ty_3f8v6h2n0c"] },
  "ops": ["read"],
  "columns": { "mode": "hide", "props": ["pr_8b2f4h6j0k"] },
  "reason": { "text": "Prices are for the office." }
}

policies/members_order_through_actions.json

{
  "label": "Members change orders only through actions",
  "mode": "deny",
  "subject": { "role": "member" },
  "on": { "types": ["ty_3f8v6h2n0c"] },
  "ops": ["create", "update", "delete"],
  "except": [{ "group": "gr_5r7t9w1y3a" }],
  "direct": true
}

policies/only_drivers_place_orders.json

{
  "label": "Only drivers place orders",
  "mode": "deny",
  "subject": { "role": "member" },
  "on": { "actions": ["ac_3h5k7n9q1s"] },
  "ops": [{ "invoke": "ac_3h5k7n9q1s" }],
  "except": [{ "group": "gr_5r7t9w1y3a" }]
}

Subject

Who it names: a role, a group, a member, the visitors of an app or form, everyone, or no one (a credential narrowing) (authz Subject, C56).

One of: