Perms#
A struct can name the perm each REST action on its rows requires, and so can
each of its fields and each route. A perm is a name your application gives
meaning to, such as secrets.read. Model checks a request against the perms
the model declares; your application says which perms a request’s user
holds.
Only the Go output enforces perms, and only with the auth feature enabled
(see Go features). Perms covers the
endpoints and Route perms the routes. The TypeScript
output describes them too, so a UI can check them
to grey out what its user may not do, but that check enforces nothing.
Struct perms#
type: struct
display: Secret
desc: A record only some may see
top_level: true
perms:
summarize: secrets.list
read: secrets.read
update: secrets.write
fields: { ... }
Key |
Guards |
Falls back to |
|---|---|---|
|
Listing a row by its summary: |
|
|
|
— |
|
|
|
|
|
— |
|
|
|
Each value is one of these:
A perm’s name. The request’s user must hold it.
authenticated. The request must have a user, but needs no perm.anonymous. Every request may take the action, even one with no user.false. No user holds it, so nobody may take the action. The endpoint is still served, and denies every request.null, or left out. The action takes the perm it falls back to. When nothing in the chain is set, the action needs no perm, as withanonymous.
anonymous and authenticated are reserved, so neither can be the name of a
perm. true is not a perm, and the build fails on one: write anonymous or
authenticated instead.
A struct with no perms is open to every request. perms guard the REST
endpoints of a top_level struct, and any struct such a struct embeds. See
Perms on embedded structs. On a struct no top_level struct reaches they
do nothing, and the build warns.
Perms by class#
A struct can instead give its perms the way unix does, by class. Whether a request may act on a row then depends on that row’s owner and group as well as on the action:
type: struct
display: Memo
desc: A note its author and their team may read
top_level: true
perms:
owner_field: author
group_field: team
create:
self: memos.write
any: memos.admin
user:
read: authenticated
update: authenticated
delete: authenticated
group:
read: authenticated
update: memos.edit
other:
summarize: memos.list
read: memos.read
update: memos.admin
summary:
fields: [title]
title: '{{.title}}'
fields: { ... }
owner_field names the field holding the ID of the user who owns the row, and
group_field names the field holding the name of its group. Each must be a
string, or a ref to a struct whose primary key is one string. A request
is in each class that matches it:
Class |
Its requests |
|---|---|
|
Those whose user owns the row. |
|
Those whose user is in the row’s group. |
|
Every request. |
A request may take an action when any class it is in allows it. So the author
of a memo may read it through user even without memos.read. A member of
the memo’s team may read it through group. Anyone else needs memos.read.
A perm in the group class is held in the row’s group: through what the
user’s membership of that group grants them, never through their account.
With the auth library, that is the roles an account holds in each of its
groups. So a member who holds memos.edit in ops may update the memos of
ops, but not those of another team they are in. Holding memos.edit for
their account gives them no team’s memos. A perm that holds in every group,
as an instance admin’s does, belongs in other, as memos.admin does here.
Each class takes summarize, read, update, and delete, which fall back
as a struct’s do: summarize to read and delete to update. Within a
class, each value is one of these:
authenticated. The class may take the action when the request has a user, with no perm. A request inuserorgroupalways has one.anonymous. The class may take the action, even with no user.A perm’s name. The class may take it when the request’s user holds the perm.
false, or left out. The class may not take it.
So a class allows nothing unless you say so, and a class you leave out allows
nothing at all. This is the reverse of the flat form, where a perm left out
requires nothing. A struct gives its perms by class when it sets any of
owner_field, group_field, user, group, or other, or gives create as
a mapping. It may not then also set the flat summarize, read, update, or
delete.
A row has no owner or group until it is created, so create is split by whose
row a request creates:
Key |
Guards |
Falls back to |
|---|---|---|
|
Creating a row whose |
|
|
Creating any row. |
— |
create can also be a single value, which then applies to both. When create
is left out, nobody may create a row. When a POST leaves out an optional
owner_field, the request’s user becomes the owner, so the row needs self.
owner_field is a field like any other, so to keep a request from giving its
row away, give the field its own update perm.
The user class and create’s self need owner_field, and the group class
needs group_field. A struct that names either field also needs a summary,
because each listing reads the owner and group from it. Listings therefore
show them, as they show the primary key, so neither field may set its own
read. The build fails if any of these is missing.
The Go auth feature finds out a request’s user ID, groups, and the perms
it holds in each from its mdl.Authorizer. The authorizer has to implement
mdl.Owner too, or every request is in other alone. See Perms.
What a denied request sees#
A request denied a perm gets a 404 Not Found when it has no user. That is the
same response as for a row that does not exist, so a stranger cannot tell what
exists. A request with a user gets a 403 Forbidden. With perms by class, a
request denied a row it may not summarize either gets the 404 too, because
no listing would have shown it the row.
With perms by class, every listing leaves out the rows that no class the
request is in may summarize. That covers the collection’s GET and QUERY,
the search of every table, referenced_by, related, and another summary
that includes the row.
When a request may not summarize rows of a struct, those rows are left out of the listings that span several structs:
The search of every table (
QUERYof the base path). Rows are filtered in the query, so a page is still full. It leaves out the rows a request may not read, too.referenced_by. Filtered the same way. A row is also left out when every field through which it refers to the listed row has areadperm that the request lacks, since the listing would show where the field points.related. Filtered the same way, through the fields of the row on either end of the reference: a row that the listed row refers to is left out when every field of the listed row that names it has areadperm the request lacks.Another struct’s summary that refers to one of the rows. The summary shows the row by its key, as when the row was not read.
Searches need read#
A search needs both summarize and read. The search lists rows by their
summaries, but which rows it matches depends on every searched column. A
request that could search rows it may not read could learn what they hold by
trying words one at a time. So QUERY of a collection is denied without
both perms. The search of every table leaves out the rows of a struct whose
perms the request lacks.
When a request may summarize a row but not read it, the row’s listing item has
no url and no urls. If the summary image is the row’s file, the item has
no image either.
Field perms#
A field may set read, create, and update. Each applies on top of the
struct’s own perm for the same action. create falls back to the field’s own
update, and an unset one adds nothing.
fields:
body:
display: Body
desc: The secret itself
type: string
required: true
perms:
read: secrets.body
level:
display: Level
desc: Which only an admin changes
type: integer
perms:
update: secrets.admin
Perm |
When the request lacks it |
|---|---|
|
The field is left out of the row, in JSON, YAML, and TOML alike. A field that sets |
|
A |
|
A |
A PUT that leaves out a field the request may not read keeps the stored
value, even a required one, and a blank string or an empty list or map counts
as left out. So a client can write back a row exactly as it read it, even one
that holds "" for a string or [] for a list it was never sent. 0 and
false are real values, so sending one sets the field. A field the request may
read is replaced, so leaving out a required one, or sending it blank, is a
422.
A request that may neither read a field nor update it is denied for providing
any value for it, even the stored one. If the stored value were allowed, the
answer would tell the request whether it had guessed that value. On a PUT,
what counts as left out above is still no value, so writing a row back as read
is unaffected. On a PATCH, naming the field is denied whatever the patch gives
it, null included, so a patch cannot test whether the field is set. This
holds at every depth, and for a union’s variant. A
file the request may not read is denied in the
same way even if it may update it, because only an upload sets one. When
anything is denied this way, the 403 names only that, and nothing is compared
with the stored row or validated, so a PATCH naming a required field with
null gets the 403 rather than a 422. Whether the row a patch would make is
valid can depend on what the request may not read, so it answers nothing here.
Only a PUT body that does not decode at all is answered first, as a body’s
syntax says nothing of the row.
A denied field write answers like a denied action: 404 with no user, and
403 with one. The 403’s problem body names each field in errors by its
data path, with the kind perm.
A field that the struct’s summary shows may not set read, because a summary is
shown to anyone who may summarize the row. That covers its fields, its
image, and a top_level struct’s primary key. The build fails if one does.
The build warns about a required field whose create is false, because
then no request can create the struct, unless the struct’s own create is
false too.
Perms on embedded structs#
A field of an embedded struct is guarded exactly as a direct field is, at any
depth, on every surface: the row’s body, its entity tag, searches, queries,
referenced_by and related, and a file reached through the embed.
A field’s guards for an action are its own perm and the perm of the struct it
embeds, and a request must pass all of them. read, create, and update each
map to the same action on the struct. The embedded struct is found through a
list or a map. A ref is not an embed, so it adds nothing.
type: struct
display: Billing
desc: How a customer pays
perms:
read: billing.read
update: billing.write
fields:
card:
display: Card
desc: The card on file
type: string
required: true
perms:
read: billing.card
A billing field of type Billing needs billing.read to read, and its card
needs billing.card as well.
A field’s class is the row’s.
userandgroupare checked against the owner and group of the top-level row, at every depth. Atop_levelstruct embedding a struct whose perms use a class must name that class’s field, or the build fails. An embedded struct’s ownowner_fieldapplies only where it is the row itself, and otherwise warns.A union’s variant is guarded per value. A variant’s struct perms apply only while the union holds that variant, so a union field with a guarded variant is optional in the clients. A field left out this way is absent. A list item or a map value left out this way is a
null, or an empty table or mapping in YAML and TOML, so that the rest keep their positions and keys.A summary shows an embed through the embed’s own summary, so a shown embed needs the embedded struct’s
summarizeto be open, and the build fails otherwise.
A denied write names the data path of what it may not change,
such as billing.card, items.2.note, or labels.'a'.note. Writes compare a
list’s items by position and a map’s entries by key:
On a |
What happens |
|---|---|
Reordering items |
Hidden values stay at their old positions, so they now belong to other items. To reorder them too, the request needs to read and update them. |
Adding an item or an entry |
It is checked as a |
Removing an item or an entry |
It is checked as an |
A PATCH replaces a list whole (RFC 7386), so it cannot leave a hidden value in
place. Changing a list holding hidden item values needs their update, and is
otherwise denied at the path of each one it changes.
A union that changes variant counts as a change to every guarded field of both variants.
Field perms by class#
A field of a struct whose perms are by class can give its
own perms by class too, under user, group, and other:
fields:
private_note:
display: Private Note
desc: A note only the memo's author may read or set
type: string
perms:
user:
read: authenticated
update: authenticated
pinned:
display: Pinned
desc: Which the author changes, and anyone else only with a perm
type: boolean
perms:
user:
update: authenticated
other:
update: memos.pin
Each class takes read, create, and update, whose values mean what they
do in a struct’s class: authenticated, anonymous, a perm’s name, or
false. Within a class, create falls back to update. The field may not
then also set the flat read, create, or update.
An action that no class sets adds nothing, just as an unset flat field perm
does: private_note above leaves who may update the memo to the memo’s
perms, and pinned who may read it. An action that any class sets is allowed
only to the classes that allow it, so only the author may read
private_note.
The classes are matched against the row’s owner and group as for the row’s own perms. A write over a row is matched against the row as stored, so its owner may set a field as they give the row away. Creating a row is matched against the row as created, after the request’s user becomes the owner of a row that names none.
The user class needs the struct’s owner_field, and the group class its
group_field; the build fails without them.
In the clients#
The TypeScript output and the Go client are for clients, so they describe what a response may hold:
A field whose
readis a perm’s name is optional, even if it isrequired, because a response leaves it out for a request without the perm. Its TypeScript metadata’sguaranteedisfalse, and in Go it is anmdl.Optional. A list or map reads as empty when it is missing, as an optional one always does.A union with a guarded variant is optional too, whatever its variants hold. Its items in a list or a map may be
null:Array<Lead | null>in TypeScript, and a nilLeadin Go.A field whose
readisfalseis left out completely. It has no entry in the schema, the shape, the metadata’sfields, the Svelte class, or the Go client’s struct. No response ever contains it, and aPUTthat leaves it out keeps the stored value. If a request may create or update it, the TypeScript metadata lists it in the struct’swriteOnly, so a form can label it.A row may say a hidden field is set. A struct with a field that can get a
$presententry has an optional$presentin its schema, its shape, and its Svelte class, whosetoJSONleaves it out. In the Go client each such field has a<Field>Presentmethod returning anmdl.Optional[bool]. Either way, nothing there means the response did not say.
A url cannot resolve against a field whose read is false, through either a
field base or a root base’s path, because a client never gets the base.
The build fails if one does.
Route perms#
A route takes one perm, perm, with the same values:
type: route
...
perm: messages.read
The route’s handler runs only for a request the perm allows: one whose user
holds it, one with a user for authenticated, and any for anonymous.
Otherwise the request is denied as above.
A root endpoint takes perm the same way, and every
file and listing it serves is guarded by it.
Checking perms in the client#
Warning
A check in the client is a hint for its UI, not a security boundary. The server enforces every perm on every request, whatever the client decides. What the client believes of its user may be stale, and the server may grant more than the client knows of, so a check may answer wrongly either way.
The TypeScript metadata carries each perm with its fallbacks already applied:
the perms of a struct a row reaches, a field’s perms when they add to the
struct’s, and a route’s perm. Each is spelled as the YAML spells it:
"anonymous" for a perm that requires nothing, "authenticated" for one any
user holds, false for one no user holds, or the perm’s name. An action on a
row has one for each class, user, group, and other; a struct whose perms
are not by class has false for user and group. A field’s perms hold a
list for each action, of its guards, which is empty when the action requires
nothing more.
@omniblack/model-runtime checks them against a Principal: the user’s ID,
as an owner field holds it, their groups, whether they hold a perm, and
whether they hold one in a group. principalFromPerms builds one from what a
server reports of its session; its groupPerms gives the perms held in each
group, and its all names a perm that grants every other, as the auth
library’s * does, in a group’s perms too.
import { may, mayCreate, mayField, principalFromPerms } from "@omniblack/model-runtime";
import { Memo } from "./model.mjs";
const me = principalFromPerms("ada", ["ops"], ["memos.write"], {
all: "*",
groupPerms: { ops: ["memos.edit"] },
});
may(me, Memo, "delete", memo); // may delete this memo
may(me, Memo, "update"); // may update some memo
mayCreate(me, Memo, { title: "Plans" }); // created as ada's
mayField(me, Memo, "pinned", "update", memo); // grey out the checkbox?
mayField takes both the struct’s perm for the action and each of the field’s
guards, as the server does, and checks create against the row as created.
For a field of an embedded struct, pass the top-level struct last: the row is
then the top-level row, whose owner and group decide the classes, and the
embedded struct’s perm counts as well.
mayField(me, Billing, "card", "read", customer, Customer);
Without a row, may and mayField answer whether the user may act on some row.
mayCall checks a route. @omniblack/auth-client builds the principal from the
session’s user.