GizStack
View .mdOpen in ChatGPTOpen in Claude

gizmodel/gate

who may read and write which rows of a Shape. It is the one place that applies the Policy (grants on records and the ancestry of records, model/policy.giz) to a Shape's rows, so a page, an API, an agent's tool and a background job that act through a Db with a Scope (model/data.giz) are all judged the same way, by the same function.

A stored Shape is a record of the Policy named SPACE/table/NAME, and each of its rows is SPACE/NAME/KEY below it (or below the row that its @Within field names). A grant on the table reaches every row; a grant on one row reaches that row and its children. A read adds a condition to the query, so a row the actor may not read is never selected; a field the actor may not read is selected as NULL. A write is checked before it runs, and a row is placed in the Policy in the transaction that inserts it.

gizlang
import * as Gate from "gizmodel/gate";

Types

Scope

gizlang
type Scope = { space: string; actor: Security.Principal; now: i64; since: i64; kept: Ref<Policy.Kept>; }

Who acts: the actor, the Space whose records they are, and the time (ms since 1970) the Scope was made at, NOW, with the monotonic clock then, SINCE. A Scope keeps no decision: each read asks the Policy in its own snapshot at the time of that read (timeOf), so a Scope used again after a revoke, a rollback or past an expiry decides by what is true then: a job's or an agent's Scope that outlived a grant's expiry kept it (a lane keeps the Policy's answers for its snapshot: db/access.giz Answers). A Scope that kept its table decisions kept a revoked grant (DB-SCOPE-REVOKE). KEPT holds what the Policy read in one version of the data (Policy.Kept), never a decision: another version forgets it.

  • space: string
  • actor: gizlang_security.Principal
  • now: i64
  • since: i64
  • kept: Ref<M134.Kept>

Access

gizlang
type Access = { readable: Vec<bool>; writable: Vec<bool>; role: Security.Role; mayWrite: bool; }

What a role may do with the fields of a Shape. A field with a @Read role is read when the role is at least it; a field with a @Write role is written when the role is at least it and also the Shape's write role; a key and a computed field are never written.

  • readable: Vec<bool>
  • writable: Vec<bool>
  • role: gizlang_security.Role
  • mayWrite: bool

Plan

gizlang
type Plan = { set: Vec<bool>; writes: Vec<Policy.Write>; }

What a write sets: set flags the fields that it writes, and writes are the Policy statements that go in its transaction.

  • set: Vec<bool>
  • writes: Vec<M134.Write>

Plans

gizlang
type Plans = { sets: Vec<Vec<bool>>; writes: Vec<Policy.Write>; }

What a write of new rows sets: sets holds each row's Plan.set, and writes are the Policy statements of all the rows.

  • sets: Vec<Vec<bool>>
  • writes: Vec<M134.Write>

Functions

scope

gizlang
function scope(space: string, actor: Security.Principal, now: i64): Scope throws string

A Scope. A Space is named as a reference part is: 1 to 64 of a-z 0-9 _ . -

Effects: fail, write, io, alloc.

record

gizlang
function record(s: Scope, shape: Model.Shape, values: Vec<Value>): Security.ResourceRef throws Model.Rejection

The Policy record of the row with these values (its key fields are read): what a grant on the row is given on.

Effects: fail, alloc.

checked

gizlang
function checked(shape: Model.Shape): bool throws Model.Rejection

Whether a Shape can be judged: stored under a table that names a Policy record, with a key of text or integers.

Effects: fail, alloc.

keyOf

gizlang
function keyOf(shape: Model.Shape, values: Vec<Value>): string throws Model.Rejection

The key text of a row's values (the parts of a composite key are joined by /).

Effects: fail, alloc.

readable

gizlang
function readable(source: Source, s: Scope, shape: Model.Shape): Tree.Expression<bool> throws Model.Rejection

The condition that selects only the rows that the actor may read.

Effects: fail, read, write, console, io, alloc.

access

gizlang
function access(source: Source, s: Scope, shape: Model.Shape, ref: Security.ResourceRef): Access throws Model.Rejection

The access of the actor to the record ref (a row, or the table for a row that does not exist yet).

Effects: fail, read, write, console, io, alloc.

accessToTable

gizlang
function accessToTable(source: Source, s: Scope, shape: Model.Shape): Access throws Model.Rejection

The access to a row that is created below the table (the row is not there yet).

Effects: fail, read, write, console, io, alloc.

accessToRow

gizlang
function accessToRow(source: Source, s: Scope, shape: Model.Shape, values: Vec<Value>): Access throws Model.Rejection

The access to the row with these key values.

Effects: fail, read, write, console, io, alloc.

masks

gizlang
function masks(source: Source, s: Scope, shape: Model.Shape): Vec<Option<Tree.Expr>> throws Model.Rejection

The masks of the fields of SHAPE that the actor of S may read only on some rows: for each field the condition that is true on the rows where the actor may read it, none for a field that any reader sees (Model.selection). A role is judged once however many fields have it.

Effects: fail, read, write, console, io, alloc.

admitCreate

gizlang
function admitCreate(source: Source, s: Scope, shape: Model.Shape, values: Vec<Value>): Plan throws Model.Rejection

Admit a new row: the actor holds the Shape's write role on its parent. The Plan places the row.

Effects: fail, read, write, console, io, alloc.

admitCreates

gizlang
function admitCreates(source: Source, s: Scope, shape: Model.Shape, rows: Vec<Vec<Value>>): Plans throws Model.Rejection

Admit new rows as admitCreate admits each: one decision for each parent, and one placement for each PLACED rows below a parent.

Effects: fail, read, write, console, io, alloc.

admitUpdate

gizlang
function admitUpdate(source: Source, s: Scope, shape: Model.Shape, old: Vec<Value>, values: Vec<Value>): Plan throws Model.Rejection

Admit a change of the row old (as the actor reads it) to values: the actor holds the write role on the row, and on the new parent when a @Within field moves it.

Effects: fail, read, write, console, io, alloc.

admitRemove

gizlang
function admitRemove(source: Source, s: Scope, shape: Model.Shape, old: Vec<Value>): Plan throws Model.Rejection

Admit the removal of the row old: the actor holds the write role on it. The Plan removes its grants and its place.

Effects: fail, read, write, console, io, alloc.

provision

gizlang
function provision(s: Scope, shapes: Vec<Model.Shape>): Vec<Policy.Write> throws Model.Rejection

The statements that place the table record of each Shape (a scoped Db.install makes the Policy tables first), with the actor as its owner. Run them once for each Space; they can run again.

Effects: fail, io, alloc.