# gizlang:security

Shared identity, session proof and authorization decisions. Protocols adapt credentials and persistence; they do not define a second permission system.

```gizlang
import * as Security from "gizlang:security";
```

## Types

### `Signed`

```gizlang
type Signed = { who: string; issued: i64; }
```

A signed claim: who it names and when it was issued (ms since 1970).

- `who`: `string`
- `issued`: `i64`

### `Identity`

```gizlang
type Identity = { identity: string; tenant: string; role: string; secret: bytes; }
```

A registered identity: its name, tenant, role and secret.

- `identity`: `string`
- `tenant`: `string`
- `role`: `string`
- `secret`: `bytes`

### `Registration`

```gizlang
type Registration = { principal: Identity; enabled: bool; revokedBefore: i64; revision: i64; }
```

The registration of an identity: whether it is enabled, the time before which its sessions are void, and its revision.

- `principal`: `gizlang_security.Identity`
- `enabled`: `bool`
- `revokedBefore`: `i64`
- `revision`: `i64`

### `Authority`

```gizlang
type Authority
```

Share this authority across DB, HTTP and Agent entrypoints. Registry edits
are immediately visible to every holder; authenticated sessions pin a revision.

Opaque: create and use it through this module's functions.

### `ResourceRef`

```gizlang
type ResourceRef = { space: string; type: string; key: string; }
```

One reference to any record: its Space, the stable declaration of its record
type and its key. Trusted adapters supply the target and all its ancestors,
including itself. Its one text form is SPACE/TYPE/KEY (see ResourceRef.text).

- `space`: `string`
- `type`: `string`
- `key`: `string`

### `Role`

```gizlang
type Role = | { kind: "none"; } | { kind: "viewer"; } | { kind: "commenter"; } | { kind: "editor"; } | { kind: "manager"; } | { kind: "owner"; }
```

A role, from none to owner, in the order none < viewer < commenter < editor < manager < owner.

- `none`
- `viewer`
- `commenter`
- `editor`
- `manager`
- `owner`

### `Principal`

```gizlang
type Principal = | { kind: "person"; id: string; } | { kind: "agent"; id: string; ceiling: Role; onBehalf: string; } | { kind: "group"; team: ResourceRef; } | { kind: "link"; digest: bytes; } | { kind: "public"; }
```

Who acts or holds a grant. A group holds grants and never acts: a person who
holds a role on the group's reference (type `group`) is a member of it.

- `person`
- `agent`
- `group`
- `link`
- `public`

### `Grant`

```gizlang
type Grant = { principal: Principal; target: ResourceRef; role: Role; expires: i64; }
```

A grant of a role on a record to a principal, until `expires` (0 never).

- `principal`: `gizlang_security.Principal`
- `target`: `gizlang_security.ResourceRef`
- `role`: `gizlang_security.Role`
- `expires`: `i64`

### `Decision`

```gizlang
type Decision = { allowed: bool; role: Role; reason: string; }
```

The answer of a Policy decision: whether it is allowed, the role that the actor holds, and the reason.

- `allowed`: `bool`
- `role`: `gizlang_security.Role`
- `reason`: `string`

### `Capability`

```gizlang
type Capability = { principal: Principal; target: ResourceRef; role: Role; expires: i64; revision: i64; }
```

A signed, short-lived permission: `principal` holds `role` on `target` until
`expires`, as decided at policy `revision`. A holder of the key verifies it with
no lookup, so HTTP, S3, the mount and a CDN decide alike.

- `principal`: `gizlang_security.Principal`
- `target`: `gizlang_security.ResourceRef`
- `role`: `gizlang_security.Role`
- `expires`: `i64`
- `revision`: `i64`

## Functions

### `authority`

```gizlang
function authority(): Authority
```

An authority with no principals.

Effects: fail, write.

### `token`

```gizlang
function token(secret: bytes, principal: string, issued: i64): string
```

A session token for PRINCIPAL issued at ISSUED (milliseconds), signed with SECRET (HMAC-SHA-256).

Effects: fail.

### `verified`

```gizlang
function verified(secret: bytes, text: string, now: i64): Option<Signed>
```

The principal and issue time of the token TEXT when its signature with SECRET is valid, else none.

Effects: fail.

### `validSession`

```gizlang
function validSession(signed: Signed, enabled: bool, revokedBefore: i64, now: i64): bool
```

Whether the session SIGNED is valid at NOW: the principal is enabled, the token is newer than REVOKEDBEFORE, and its
age is within the session life.

Effects: fail.

### `parseResourceRef`

```gizlang
function parseResourceRef(text: string): ResourceRef throws string
```

The reference of the text SPACE/TYPE/KEY (ResourceRef.text). It fails on any other form.

Effects: fail.

### `rank`

```gizlang
function rank(role: Role): i64 effects {}
```

The only role order: none < viewer < commenter < editor < manager < owner. An
Operation names the least role that it needs; viewer marks a read.

### `roleText`

```gizlang
function roleText(role: Role): string effects {}
```

The one text of a role: its kind.

### `parseRole`

```gizlang
function parseRole(text: string): Role throws string
```

The role of its text ("none", "viewer", "commenter", "editor", "manager", "owner"). It fails on any other text.

Effects: fail.

### `principalText`

```gizlang
function principalText(p: Principal): string
```

The one text of a grantee: person:ID, agent:ID, group:SPACE/group/KEY, link:HEX
or public. An agent's text names the agent only: its ceiling and its person come
from the actor, never from a grant.

Effects: fail.

### `parsePrincipal`

```gizlang
function parsePrincipal(text: string): Principal throws string
```

The principal of its text ("public", "person:ID", "agent:ID", "group:REF" or "link:HEX"). It fails on any other
text.

Effects: fail.

### `decide`

```gizlang
function decide(actor: Principal, ancestry: Vec<ResourceRef>, grants: Vec<Grant>, needed: Role, now: i64): Decision effects { fail }
```

Total, pure authorization: whether `actor` holds at least `needed` on the first
reference of `ancestry`, through grants on it or on its ancestors. Grants only
add; there is no deny. Public and link grants match only that actor. A person
also holds the grants of its groups (the membership grants are in `grants`).
Agents need their own grant and their person's grant, under their ceiling. A
grant never supplies an agent's trusted ceiling or delegation identity. A group
never acts. The compiler marks bounded Vec iteration as fail; no state or IO is used.

Effects: fail.

### `capability`

```gizlang
function capability(key: bytes, granted: Capability, now: i64): string throws string
```

The token of a capability that `decide` admitted: HEX(body).HEX(HMAC-SHA256).

Effects: fail.

### `admitCapability`

```gizlang
function admitCapability(key: bytes, token: string, now: i64): Capability throws string
```

The capability of a token that `key` signed and that is still live at `now`.

Effects: fail.

### `policyDigest`

```gizlang
function policyDigest(domain: string, definitions: Vec<string>): bytes
```

General policy identity; adapters provide canonical observed facts.

Effects: fail.

### `digest`

```gizlang
function digest(data: bytes): string
```

The SHA-256 of `data` in lowercase hex: the one content digest of tokens, keys and cache names.

Effects: fail.

### `passwordHash`

```gizlang
function passwordHash(password: string, salt: string): string
```

A password's stored hash under `salt`: PBKDF2-SHA-256, 32 bytes, in lowercase hex.

Effects: fail.

## Methods

### `Authority.register`

```gizlang
function Authority.register(self: Authority, principal: Identity): bool throws string
```

Adds PRINCIPAL. It fails when the principal is not valid or its identity is already registered.

Effects: fail, read, write.

### `Authority.lookup`

```gizlang
function Authority.lookup(self: Authority, identity: string): Option<Registration>
```

The registration of IDENTITY, or none.

Effects: fail, read.

### `Authority.authenticate`

```gizlang
function Authority.authenticate(self: Authority, identity: string, credential: bytes): Option<Registration>
```

The registration of IDENTITY when CREDENTIAL (32 bytes) matches its secret and it is enabled, else none.

Effects: fail, read.

### `Authority.replace`

```gizlang
function Authority.replace(self: Authority, principal: Identity, enabled: bool, revokedBefore: i64): bool throws string
```

Revocation/change occurs at the trusted authority, not in client claims.

Effects: fail, read, write.

### `Authority.current`

```gizlang
function Authority.current(self: Authority, evidence: Registration): bool
```

Whether EVIDENCE is still the current revision of an enabled registration.

Effects: fail, read.

### `Authority.resolve`

```gizlang
function Authority.resolve(self: Authority, signed: Signed, now: i64): Option<Registration>
```

The registration of the session SIGNED when it is valid at NOW, else none.

Effects: fail, read.

### `ResourceRef.text`

```gizlang
function ResourceRef.text(self: ResourceRef): string
```

SPACE/TYPE/KEY: SPACE and TYPE are 1 to 64 of a-z 0-9 _ . - and KEY is the
percent-encoded UTF-8 key (Http.encode). At most 512 bytes. Equal texts are
equal references: parseResourceRef accepts only this form.

Effects: fail.

## Constants

### `SESSION_LIFE`

```gizlang
const SESSION_LIFE = 2592000000
```

How long a session lasts, in milliseconds (30 days).

### `CAPABILITY_LIFE`

```gizlang
const CAPABILITY_LIFE = 300000
```

The longest life of a capability: the revocation bound of reads that check no grant.

### `PASSWORD_ROUNDS`

```gizlang
const PASSWORD_ROUNDS = 120000
```

How many rounds a password hash takes.

gizlang:security

Shared identity, session proof and authorization decisions. Protocols adapt credentials and persistence; they do not define a second permission system.

gizlang

import * as Security from "gizlang:security";

Types

`Signed`

gizlang

type Signed = { who: string; issued: i64; }

A signed claim: who it names and when it was issued (ms since 1970).

who: string
issued: i64

`Identity`

gizlang

type Identity = { identity: string; tenant: string; role: string; secret: bytes; }

A registered identity: its name, tenant, role and secret.

identity: string
tenant: string
role: string
secret: bytes

`Registration`

gizlang

type Registration = { principal: Identity; enabled: bool; revokedBefore: i64; revision: i64; }

The registration of an identity: whether it is enabled, the time before which its sessions are void, and its revision.

principal: gizlang_security.Identity
enabled: bool
revokedBefore: i64
revision: i64

`Authority`

gizlang

type Authority

Share this authority across DB, HTTP and Agent entrypoints. Registry edits are immediately visible to every holder; authenticated sessions pin a revision.

Opaque: create and use it through this module's functions.

`ResourceRef`

gizlang

type ResourceRef = { space: string; type: string; key: string; }

One reference to any record: its Space, the stable declaration of its record type and its key. Trusted adapters supply the target and all its ancestors, including itself. Its one text form is SPACE/TYPE/KEY (see ResourceRef.text).

space: string
type: string
key: string

`Role`

gizlang

type Role = | { kind: "none"; } | { kind: "viewer"; } | { kind: "commenter"; } | { kind: "editor"; } | { kind: "manager"; } | { kind: "owner"; }

A role, from none to owner, in the order none < viewer < commenter < editor < manager < owner.

none
viewer
commenter
editor
manager
owner

`Principal`

gizlang

type Principal = | { kind: "person"; id: string; } | { kind: "agent"; id: string; ceiling: Role; onBehalf: string; } | { kind: "group"; team: ResourceRef; } | { kind: "link"; digest: bytes; } | { kind: "public"; }

Who acts or holds a grant. A group holds grants and never acts: a person who holds a role on the group's reference (type group) is a member of it.

person
agent
group
link
public

`Grant`

gizlang

type Grant = { principal: Principal; target: ResourceRef; role: Role; expires: i64; }

A grant of a role on a record to a principal, until expires (0 never).

principal: gizlang_security.Principal
target: gizlang_security.ResourceRef
role: gizlang_security.Role
expires: i64

`Decision`

gizlang

type Decision = { allowed: bool; role: Role; reason: string; }

The answer of a Policy decision: whether it is allowed, the role that the actor holds, and the reason.

allowed: bool
role: gizlang_security.Role
reason: string

`Capability`

gizlang

type Capability = { principal: Principal; target: ResourceRef; role: Role; expires: i64; revision: i64; }

A signed, short-lived permission: principal holds role on target until expires, as decided at policy revision. A holder of the key verifies it with no lookup, so HTTP, S3, the mount and a CDN decide alike.

principal: gizlang_security.Principal
target: gizlang_security.ResourceRef
role: gizlang_security.Role
expires: i64
revision: i64

Functions

`authority`

gizlang

function authority(): Authority

An authority with no principals.

Effects: fail, write.

`token`

gizlang

function token(secret: bytes, principal: string, issued: i64): string

A session token for PRINCIPAL issued at ISSUED (milliseconds), signed with SECRET (HMAC-SHA-256).

Effects: fail.

`verified`

gizlang

function verified(secret: bytes, text: string, now: i64): Option<Signed>

The principal and issue time of the token TEXT when its signature with SECRET is valid, else none.

Effects: fail.

`validSession`

gizlang

function validSession(signed: Signed, enabled: bool, revokedBefore: i64, now: i64): bool

Whether the session SIGNED is valid at NOW: the principal is enabled, the token is newer than REVOKEDBEFORE, and its age is within the session life.

Effects: fail.

`parseResourceRef`

gizlang

function parseResourceRef(text: string): ResourceRef throws string

The reference of the text SPACE/TYPE/KEY (ResourceRef.text). It fails on any other form.

Effects: fail.

`rank`

gizlang

function rank(role: Role): i64 effects {}

The only role order: none < viewer < commenter < editor < manager < owner. An Operation names the least role that it needs; viewer marks a read.

`roleText`

gizlang

function roleText(role: Role): string effects {}

The one text of a role: its kind.

`parseRole`

gizlang

function parseRole(text: string): Role throws string

The role of its text ("none", "viewer", "commenter", "editor", "manager", "owner"). It fails on any other text.

Effects: fail.

`principalText`

gizlang

function principalText(p: Principal): string

The one text of a grantee: person:ID, agent:ID, group:SPACE/group/KEY, link:HEX or public. An agent's text names the agent only: its ceiling and its person come from the actor, never from a grant.

Effects: fail.

`parsePrincipal`

gizlang

function parsePrincipal(text: string): Principal throws string

The principal of its text ("public", "person:ID", "agent:ID", "group:REF" or "link:HEX"). It fails on any other text.

Effects: fail.

`decide`

gizlang

function decide(actor: Principal, ancestry: Vec<ResourceRef>, grants: Vec<Grant>, needed: Role, now: i64): Decision effects { fail }

Total, pure authorization: whether actor holds at least needed on the first reference of ancestry, through grants on it or on its ancestors. Grants only add; there is no deny. Public and link grants match only that actor. A person also holds the grants of its groups (the membership grants are in grants). Agents need their own grant and their person's grant, under their ceiling. A grant never supplies an agent's trusted ceiling or delegation identity. A group never acts. The compiler marks bounded Vec iteration as fail; no state or IO is used.

Effects: fail.

`capability`

gizlang

function capability(key: bytes, granted: Capability, now: i64): string throws string

The token of a capability that decide admitted: HEX(body).HEX(HMAC-SHA256).

Effects: fail.

`admitCapability`

gizlang

function admitCapability(key: bytes, token: string, now: i64): Capability throws string

The capability of a token that key signed and that is still live at now.

Effects: fail.

`policyDigest`

gizlang

function policyDigest(domain: string, definitions: Vec<string>): bytes

General policy identity; adapters provide canonical observed facts.

Effects: fail.

`digest`

gizlang

function digest(data: bytes): string

The SHA-256 of data in lowercase hex: the one content digest of tokens, keys and cache names.

Effects: fail.

`passwordHash`

gizlang

function passwordHash(password: string, salt: string): string

A password's stored hash under salt: PBKDF2-SHA-256, 32 bytes, in lowercase hex.

Effects: fail.

Methods

`Authority.register`

gizlang

function Authority.register(self: Authority, principal: Identity): bool throws string

Adds PRINCIPAL. It fails when the principal is not valid or its identity is already registered.

Effects: fail, read, write.

`Authority.lookup`

gizlang

function Authority.lookup(self: Authority, identity: string): Option<Registration>

The registration of IDENTITY, or none.

Effects: fail, read.

`Authority.authenticate`

gizlang

function Authority.authenticate(self: Authority, identity: string, credential: bytes): Option<Registration>

The registration of IDENTITY when CREDENTIAL (32 bytes) matches its secret and it is enabled, else none.

Effects: fail, read.

`Authority.replace`

gizlang

function Authority.replace(self: Authority, principal: Identity, enabled: bool, revokedBefore: i64): bool throws string

Revocation/change occurs at the trusted authority, not in client claims.

Effects: fail, read, write.

`Authority.current`

gizlang

function Authority.current(self: Authority, evidence: Registration): bool

Whether EVIDENCE is still the current revision of an enabled registration.

Effects: fail, read.

`Authority.resolve`

gizlang

function Authority.resolve(self: Authority, signed: Signed, now: i64): Option<Registration>

The registration of the session SIGNED when it is valid at NOW, else none.

Effects: fail, read.

`ResourceRef.text`

gizlang

function ResourceRef.text(self: ResourceRef): string

SPACE/TYPE/KEY: SPACE and TYPE are 1 to 64 of a-z 0-9 _ . - and KEY is the percent-encoded UTF-8 key (Http.encode). At most 512 bytes. Equal texts are equal references: parseResourceRef accepts only this form.

Effects: fail.

Constants

`SESSION_LIFE`

gizlang

const SESSION_LIFE = 2592000000

How long a session lasts, in milliseconds (30 days).

`CAPABILITY_LIFE`

gizlang

const CAPABILITY_LIFE = 300000

The longest life of a capability: the revocation bound of reads that check no grant.

`PASSWORD_ROUNDS`

gizlang

const PASSWORD_ROUNDS = 120000

How many rounds a password hash takes.