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#

Secret.yaml#
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

summarize

Listing a row by its summary: GET and QUERY of the collection, the search of every table, referenced_by, related, the row’s own .../summary, and another summary that includes the row.

read

read

GET of a row, its files, and its referenced_by and related listings; and, with summarize, QUERY of the collection and the search of every table.

—

create

POST of a row.

update

update

PUT and PATCH of a row.

—

delete

DELETE of a row.

update

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 with anonymous.

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:

Memo.yaml#
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

user

Those whose user owns the row.

group

Those whose user is in the row’s group.

other

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 in user or group always 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

self

Creating a row whose owner_field is the request’s user.

any

any

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 (QUERY of 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 a read perm 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 a read perm 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

read

The field is left out of the row, in JSON, YAML, and TOML alike. A field that sets read, whatever to, is never searched. A row that refers to another only through the field is left out of that row’s referenced_by and related, and the row the field names is left out of the row’s own related.

create

A POST that sets the field is denied.

update

A PUT or PATCH that changes the field is denied. A request that may read the field may send its current value back, except for a password, whose stored hash a plaintext never equals. A request that may not read it either may not provide a value at all.

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.

Billing.yaml#
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. user and group are checked against the owner and group of the top-level row, at every depth. A top_level struct embedding a struct whose perms use a class must name that class’s field, or the build fails. An embedded struct’s own owner_field applies 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 summarize to 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 PUT

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 create.

Removing an item or an entry

It is checked as an update to nothing, so removing a set hidden value needs that value’s update.

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.

Telling a client a hidden field is set#

A row says, for each field the request may write but not read, whether the field is set. That lets a form tell an API key that is set from one that is not. The value stays hidden, under the key $present, in JSON, YAML, and TOML alike:

{ "name": "Acme", "$present": { "api_key": true, "webhook_secret": false } }

A field gets an entry when the request may not read it, and passes both the struct’s update perm and the field’s own for the row. Any other field has no entry, and a row with no entries has no $present. create does not count, because $present describes a stored row.

A field holding "" or an empty list or map is not set, and 0 and false are. A file field never gets an entry, and neither do a summary or a route’s response.

A client may send $present back: it is ignored, so a row can still be written back as it was read. To clear a field, PATCH it to null, which takes its update perm, as a PUT that leaves it out, sets it to null, or sends it blank or as an empty list or map keeps the stored value.

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 read is a perm’s name is optional, even if it is required, because a response leaves it out for a request without the perm. Its TypeScript metadata’s guaranteed is false, and in Go it is an mdl.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 nil Lead in Go.

  • A field whose read is false is left out completely. It has no entry in the schema, the shape, the metadata’s fields, the Svelte class, or the Go client’s struct. No response ever contains it, and a PUT that leaves it out keeps the stored value. If a request may create or update it, the TypeScript metadata lists it in the struct’s writeOnly, so a form can label it.

  • A row may say a hidden field is set. A struct with a field that can get a $present entry has an optional $present in its schema, its shape, and its Svelte class, whose toJSON leaves it out. In the Go client each such field has a <Field>Present method returning an mdl.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:

RouteMessage.yaml#
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.