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

