events
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:
- a refinement by an
opaquepredicate, established withchecked; - a requirement proven by an
ensureson awhenover ranges; - labels with a category,
secret[PII], and apolicyin atrusted modulethat releases a keyed hash through the host capabilityKeys; - capabilities that
accepts internaldata, and handlers that fake them inexampleblocks; - three settings of
una.toml: label categories, trusted modules and the escape budget.
Run it
From this directory:
una check . # copy examples/events
una test .
una report .
una run .
una build .
./target/una/events-exampleuna run . and the native executable print:
availability of Launch: openmain 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:
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 failedHow 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
[labels]
categories = ["PII", "Location"]
[trusted]
modules = ["events.keys"]
[escape_budget]
checked_per_module = 1The 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
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 MalformedThe 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
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 activepub 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 -> OpenThe 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
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 passThe 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
pub capability Registrations
op find(key: internal Hashed) -> Option[Registration]
fails StoreError
accepts internalThe 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.
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")
statusThe 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
availabilityshows an event without seats as sold out, asEVENTS_3requires, and itswhencovers every seat count.- Every seat count is in
0..5000, and everyPhonecame fromparse_phone. - The phone reaches the registrations and the audit log only as its keyed hash, through
attendee_key.
una report . lists what a reviewer must still read or trust. Among its lines:
...
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:
...
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}"):
[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:
[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:
[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
- A store that times out. Add a handler
slow_registrations()whosefindfails withTimeout, and an example:check_infails withUnavailable, and the audit log is not written. Six examples become seven. - Few seats left. Add an example to
seating.unafor an event with 5 seats left, and expectFew. Then change the first arm toin 0..1 -> SoldOut.una check .still accepts it: arms may overlap, the first match wins, and theensuresonly says that no seats means sold out, not that sold out means no seats. Is that the rule that the box office wants? Strengthen theensuresso that the change is refuted. - Check in from raw input. Add
pub check_in_raw(raw: Text) -> Availabilitytoevents.checkin, which parses the phone and callscheck_in. Decide what a malformed phone becomes inCheckInError, and give that path an example.
Learn more
- Construct pages: predicates,
checked,requirement, labels,policy,trusted module,capability,handler,if error,example. - Configuration:
categories, trustedmodules,checked_per_module. - Learn, the tutorial on the Una website: "Results and failures" (
/learn/failure/); "Information flow" (/learn/information-flow/); "Testing" (/learn/testing/). - Specification: policies (spec/07 §5), trusted modules (spec/07 §6),
checked(spec/06 §6), requirements (spec/08 §1), examples (spec/08 §2), host capabilities (spec/14 §3), the build report (spec/13 §6).
Edition
Edition 0.1 (edition).
Files
[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"]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.recordtrusted 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 passmodule 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}")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 == 5000module 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