Home / Docs / Examples

events

Release v0.4.0

Event check-in: attendees check in by phone number, the phone is used only through a keyed hash, and every check-in is audited.

This is the largest example, and it combines the ideas of the others in one realistic service. A phone number is personal data: the program validates it once, labels it secret[PII], and lets it out of its function only as a keyed hash, through a reviewed policy. The registration store and the audit log are capabilities that see only the hash. A business rule about sold-out events is a requirement with a proof. Read it after journal and shortlinks.

What it demonstrates:

Run it

From this directory:

sh
una check .   # copy examples/events
una test .
una report .
una run .
una build .
./target/una/events-example

una run . and the native executable print:

una run .Output
availability of Launch: open

main shows the availability of one event with 820 seats left. The check-in itself needs a registration store, an audit log and a key store, so it runs in the examples, against fakes. una test . runs the examples of the three modules that have them:

una test .Output
example events.checkin "a registered attendee is checked in and audited" ... ok
example events.checkin "an unknown attendee fails and is not audited" ... ok
example events.seating "an event without seats is sold out" ... ok
example events.seating "an event with many seats is open" ... ok
example events.seating "raw seat counts are clamped" ... ok
example events.types "malformed input is rejected" ... ok

6 examples: 6 passed, 0 failed

How it works

The package has five modules, one per concern:

Module Holds
events.types Phone, and parse_phone, the only way to get one
events.seating the sold-out rule, seats and availability
events.keys the trusted module: the policy that hashes a phone
events.checkin the check-in service, its capabilities, fakes and examples
events.main the program

The manifest

una.tomltoml
[labels]
categories = ["PII", "Location"]

[trusted]
modules = ["events.keys"]

[escape_budget]
checked_per_module = 1

The categories are the kinds of sensitive data that the package's labels may name. The trusted module is the one place where a label may go down. The escape budget allows each module one run-time check in place of a proof. Each of the three is a decision that a reviewer finds in one file.

A phone, validated once

src/events/types.unauna
pub kind Phone = Text where valid_phone(it)

...
pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

...
pub parse_phone(raw: Text) -> Phone
  fails PhoneError
=
  checked(raw, valid_phone(it)) else fail Malformed

The predicate is opaque: the solver sees only its name, so a Phone can only come from a test at run time, here in parse_phone. That one checked spends the module's escape budget, and una report . lists it.

A rule with a proof

src/events/seating.unauna
requirement EVENTS_3
  text "An event with no remaining seats is always shown as sold out"
  source policy "Box Office Handbook 2.1"
  owner box_office
  status active
src/events/seating.unauna
pub kind Seats = Int in 0..5000

...
pub availability(e: Event) -> Availability
  ensures e.remaining < 1 implies result is SoldOut
  derived from EVENTS_3
=
  when e.remaining
    in 0..0 -> SoldOut
    in 1..<20 -> Few
    in 20..5000 -> Open

The ensures is the requirement in logic, and derived from links the two. 1..<20 excludes its upper end. The solver proves the ensures and proves that the three ranges cover every Seats value. clamp_seats turns any Int into a Seats, and the solver proves that its result is in range.

Releasing a keyed hash: the policy

src/events/keys.unauna
trusted module events.keys

import events.types (Phone)

pub policy attendee_key
  from secret[PII] Phone
  to internal Hashed
  via hmac_phone
  purpose "attendee lookup and audit correlation"
  owner privacy

hmac_phone(phone: secret[PII] Phone) -> internal Hashed
  uses @keys: Keys[hmac]
  fails KeyError
=
  @keys.hmac(key_name: "phone_pepper", data: phone)
    if error pass

The policy lowers a secret[PII] Phone to an internal Hashed: a value that identifies the attendee for lookups, but from which the phone cannot be read back. Keys.hmac computes an HMAC-SHA-256 with a key that the host holds, so the program never sees the key either.

The policy can fail, for example when the host has no key of that name. A failure is observable, so the checker labels it. For most policies, the failure carries the label of the policy's result. This via function has a narrow shape: its only failure point is a Keys.hmac call with a literal key name, at the top level of its body, handled by if error pass, and the package installs no Keys handler of its own outside examples. Whether such a call fails depends on the key name, never on the phone, so the policy's failure stays public. That is why check_in may turn it into a failure of its own.

The check-in service

src/events/checkin.unauna
pub capability Registrations
  op find(key: internal Hashed) -> Option[Registration]
    fails StoreError
    accepts internal

The store's operation accepts internal data, so it may receive the hash. It is declared to take a Hashed, so it cannot receive the phone.

src/events/checkin.unauna
pub check_in(phone: secret[PII] Phone) -> Availability
  uses @registrations: Registrations[find]
  uses @audit: Audit[record]
  uses @keys: Keys[hmac]
  fails CheckInError
=
  let key = attendee_key(phone)
    if error fail Unavailable(reason: "keys")
  let registration = @registrations.find(key)
    if error fail Unavailable(reason: "registrations")
    if none fail NotRegistered
  let status = availability(registration.event)
  @audit.record(key, status)
    if error fail Unavailable(reason: "audit")
  status

The header says everything the function may do: find registrations, record audits, compute keyed hashes, and fail with CheckInError. The phone is used once, as the argument of the policy. From there on the function works only with key.

The examples install fake stores with given. The second example checks a negative: an unknown attendee fails with NotRegistered, and nothing is written to the audit log (expect not performed @audit.record).

What una check proves

una report . lists what a reviewer must still read or trust. Among its lines:

una report .Output
...
information:
  events.keys.attendee_key at src/events/checkin.una:30:13, purpose "attendee lookup and audit correlation", owner privacy
escapes:
  events.types: 1 checked, budget 1
assumptions:
  events.checkin.Audit: record
  events.checkin.Registrations: find
...

and, in the trusted base:

una report .Output
...
  trusted modules: events.keys (17 lines)
  host capabilities: Console, Keys
...

The assumptions are the stores: what a real Registrations returns is given by its signature, not proven. The trusted module is 17 lines: the only code in the package that can lower a label.

Common mistakes

Putting the phone in an error message

A tempting change for debugging: say which phone was not found. Replace if none fail NotRegistered with if none fail Unavailable(reason: "no registration for {phone}"):

Diagnostic
[U4001] Error: field `reason` of `Unavailable` is `Text`, and this value is `secret[PII] Text`: a flow from `secret[PII]` to `public`
    ╭─[ src/events/checkin.una:34:38 ]
    │
 34 │     if none fail Unavailable(reason: "no registration for {phone}")
    │                                      ──────────────┬──────────────
    │                                                    ╰──────────────── field `reason` of `Unavailable` is `Text`, and this value is `secret[PII] Text`: a flow from `secret[PII]` to `public`
    │
    │ Note: run `una explain U4001` for an explanation
────╯

Error messages end up in logs. The checker treats them like any other output.

Sending the phone to the store

Call the store with the phone, @registrations.find(phone). The capability's signature already stops it, before any label is checked:

Diagnostic
[U2001] Error: argument `key` of operation `Registrations.find` must be `Hashed`, found `Text`
    ╭─[ src/events/checkin.una:32:42 ]
    │
 32 │   let registration = @registrations.find(phone)
    │                                          ──┬──
    │                                            ╰──── argument `key` of operation `Registrations.find` must be `Hashed`, found `Text`
    │
    │ Note: run `una explain U2001` for an explanation
────╯

A key name the checker cannot see

In hmac_phone, move the key name into a binding: let pepper = "phone_pepper", then @keys.hmac(key_name: pepper, data: phone). The via function no longer has the shape described above, so the policy's failure carries the policy's result label, internal, and check_in may not turn it into a public failure:

Diagnostic
[U4002] Error: `if error fail` depends on `internal` data, so its failure would reveal it; return a labeled value instead of failing
    ╭─[ src/events/checkin.una:31:5 ]
    │
 30 │   let key = attendee_key(phone)
    │             ─────────┬─────────
    │                      ╰─────────── the labeled condition
 31 │     if error fail Unavailable(reason: "keys")
    │     ────────────────────┬────────────────────
    │                         ╰────────────────────── `if error fail` depends on `internal` data, so its failure would reveal it; return a labeled value instead of failing
    │
    │ Note: run `una explain U4002` for an explanation
────╯

Note

The rule is conservative on purpose. The checker accepts a public failure only for the shape that it can recognize as independent of the data. Any other via function keeps the label of its result on its failure.

Extend it

  1. A store that times out. Add a handler slow_registrations() whose find fails with Timeout, and an example: check_in fails with Unavailable, and the audit log is not written. Six examples become seven.
  2. Few seats left. Add an example to seating.una for an event with 5 seats left, and expect Few. Then change the first arm to in 0..1 -> SoldOut. una check . still accepts it: arms may overlap, the first match wins, and the ensures only says that no seats means sold out, not that sold out means no seats. Is that the rule that the box office wants? Strengthen the ensures so that the change is refuted.
  3. Check in from raw input. Add pub check_in_raw(raw: Text) -> Availability to events.checkin, which parses the phone and calls check_in. Decide what a malformed phone becomes in CheckInError, and give that path an example.

Learn more

Edition

Edition 0.1 (edition).

Files

una.tomltoml
[package]
name = "events-example"
version = "0.1.0"
edition = "0.1"

[labels]
categories = ["PII", "Location"]

[trusted]
modules = ["events.keys"]

[escape_budget]
checked_per_module = 1

[run]
entry = "events.main"
grants = ["console"]
src/events/checkin.unauna
module events.checkin

import events.keys (attendee_key)
import events.seating (Availability, Event, Registration, availability)
import events.types (Phone, parse_phone)
import std.testing (fake_hash)

pub kind CheckInError = NotRegistered | Unavailable(reason: Text)

pub kind StoreError = Timeout | Corrupted

pub capability Registrations
  op find(key: internal Hashed) -> Option[Registration]
    fails StoreError
    accepts internal

pub capability Audit
  op record(key: internal Hashed, status: Availability) -> Unit
    fails StoreError
    accepts internal

--- Looks up a registration by phone, shows its availability, and records it.
--- The phone never leaves this function: only its keyed hash does.
pub check_in(phone: secret[PII] Phone) -> Availability
  uses @registrations: Registrations[find]
  uses @audit: Audit[record]
  uses @keys: Keys[hmac]
  fails CheckInError
=
  let key = attendee_key(phone)
    if error fail Unavailable(reason: "keys")
  let registration = @registrations.find(key)
    if error fail Unavailable(reason: "registrations")
    if none fail NotRegistered
  let status = availability(registration.event)
  @audit.record(key, status)
    if error fail Unavailable(reason: "audit")
  status

handler one_registration(r: Registration) for Registrations
  op find(key) = Some(r)

handler no_registrations() for Registrations
  op find(key) = None

handler audit_log() for Audit
  op record(key, status) = unit

handler fake_keys() for Keys
  op hmac(key_name, data) = fake_hash(1)

example "a registered attendee is checked in and audited"
  given @registrations = one_registration(Registration(name: "Ana", event: Event(name: "Launch", remaining: 820)))
  given @audit = audit_log()
  given @keys = fake_keys()
  do check_in(parse_phone("12345678901"))
  expect result is Open
  expect performed @audit.record

example "an unknown attendee fails and is not audited"
  given @registrations = no_registrations()
  given @audit = audit_log()
  given @keys = fake_keys()
  do check_in(parse_phone("12345678901"))
  expect fails NotRegistered
  expect not performed @audit.record
src/events/keys.unauna
trusted module events.keys

import events.types (Phone)

pub policy attendee_key
  from secret[PII] Phone
  to internal Hashed
  via hmac_phone
  purpose "attendee lookup and audit correlation"
  owner privacy

hmac_phone(phone: secret[PII] Phone) -> internal Hashed
  uses @keys: Keys[hmac]
  fails KeyError
=
  @keys.hmac(key_name: "phone_pepper", data: phone)
    if error pass
src/events/main.unauna
module events.main

import events.seating (Event, availability, clamp_seats)

pub main() -> Unit
  uses @console: Console[print]
=
  let event = Event(name: "Launch", remaining: clamp_seats(820))
  let status = availability(event)
  let label = when status
    is SoldOut -> "sold out"
    is Few -> "few seats left"
    is Open -> "open"
  @console.print("availability of {event.name}: {label}")
src/events/seating.unauna
module events.seating

requirement EVENTS_3
  text "An event with no remaining seats is always shown as sold out"
  source policy "Box Office Handbook 2.1"
  owner box_office
  status active

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub kind Event
  name: Text
  remaining: Seats

pub kind Registration
  name: Text
  event: Event

--- Availability bands from the Box Office Handbook 2.1.
pub availability(e: Event) -> Availability
  ensures e.remaining < 1 implies result is SoldOut
  derived from EVENTS_3
=
  when e.remaining
    in 0..0 -> SoldOut
    in 1..<20 -> Few
    in 20..5000 -> Open

--- Clamps a raw seat count into the seat range.
pub clamp_seats(raw: Int) -> Seats = if raw < 0 then 0 else if raw > 5000 then 5000 else raw

example "an event without seats is sold out"
  do availability(Event(name: "Launch", remaining: 0))
  expect result is SoldOut

example "an event with many seats is open"
  do availability(Event(name: "Workshop", remaining: 820))
  expect result is Open

example "raw seat counts are clamped"
  do clamp_seats(9000)
  expect result == 5000
src/events/types.unauna
module events.types

--- A phone number of 11 digits, validated once at the boundary.
pub kind Phone = Text where valid_phone(it)

pub kind PhoneError = | Malformed

--- Format check only: eleven digits.
pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

--- The only way to obtain a Phone from untrusted text.
pub parse_phone(raw: Text) -> Phone
  fails PhoneError
=
  checked(raw, valid_phone(it)) else fail Malformed

example "malformed input is rejected"
  do parse_phone("123")
  expect fails Malformed