Home / Learn / 17 Information flow

Release v0.4.0Edition 0.2

17.6 Day-to-day: shipping notices with labels

Page 7 of 11

17.6.1 What changes from chapter 12

Now the service from chapter 12, with the customers' data labeled. Four changes make it safe: labels on the fields of Customer, an accepts clause on Mailer, a label on the result of notice, and a policy in a new trusted module, privacy, which notices.una imports and notify calls. The doc comments of Customer, Mailer, notice and notify change to say so. The rest of the code is chapter 12's, and so are its examples, with one expected value changed and two examples added for the policy (section 17.7). Each part below says what it is for, and which idea of this chapter it uses.

17.6.2 Labels on the data

A customer's name and address are personal data, so both fields are secret[PII] (section 17.4). The id and the notice preference stay public: the log needs the id, and the program branches on the preference.

day-to-day/src/notices.unauna
--- A customer, as the customer directory knows them. Name and address are personal data.
pub kind Customer
  id: Text
  name: secret[PII] Text
  email: secret[PII] Text
  wants_notices: Bool

17.6.3 A mail service that may receive them

The mail service must receive the real address and a notice that names the customer. So its operation is a sink whose ceiling is personal data (section 17.2). Without accepts secret[PII], the call that sends the notice would be U4003 twice, once for the address and once for the body (a sink without accepts shows it).

day-to-day/src/notices.unauna
--- The mail service, a service on the network. It may receive personal data.
pub capability Mailer
  op send(to: Text, subject: Text, body: Text) -> Unit
    fails ServiceError
    accepts secret[PII]

17.6.4 A notice that carries the label

The text of the notice interpolates the customer's name, so it joins the name's label: its result is secret[PII] Text (How labels follow data). Only the mail service, which accepts that label, receives it.

day-to-day/src/notices.unauna
--- The text of a shipping notice. It holds the customer's name, so it carries the name's label.
pub notice(customer: Customer, shipment: Shipment) -> secret[PII] Text = "Hello {customer.name}, your order {shipment.order} is on its way with {shipment.carrier}."

17.6.5 The leak the checker stops

In chapter 12, notify returned the address it wrote to, and the log printed it. Keep that design, with the label it now needs, and the checker finds the log line:

src/notices.unadiff
--- a/src/notices.una
+++ b/src/notices.una
@@ -37,5 +37,4 @@
 
---- Finds the customer of a shipment and emails them the notice. Returns the masked address,
---- which the log may show.
-pub notify(shipment: Shipment) -> Text
+--- Finds the customer of a shipment and emails them the notice. Returns the address.
+pub notify(shipment: Shipment) -> secret[PII] Text
   uses @customers: Customers[find]
@@ -52,3 +51,3 @@
       if error fail MailDown
-    masked_email(customer.email)
+    customer.email
 
@@ -64,3 +63,3 @@
 --- One line of the dispatch log.
-pub log_line(shipment: Shipment, outcome: Result[Text, NoticeError]) -> Text
+pub log_line(shipment: Shipment, outcome: Result[secret[PII] Text, NoticeError]) -> secret[PII] Text
 =
Diagnostic
[U4003] Error: `@log.print` accepts `public` data, and this argument is `secret[PII]`
    ╭─[ src/notices.una:78:16 ]
    │
 78 │     @log.print(log_line(shipment, outcome: outcome))
    │                ──────────────────┬─────────────────
    │                                  ╰─────────────────── `@log.print` accepts `public` data, and this argument is `secret[PII]`

The message points at @log.print, in dispatch, although the address came from notify, two functions away. The label followed the address through notify's result, the Result of attempt, and the text log_line built from it.

17.6.6 The release that is allowed

The operator needs to see which customer each notice went to, not the address itself. A policy in a trusted module, privacy, releases a masked form: the first letter of the mailbox and the domain (section 17.5).

day-to-day/src/privacy.unacheckruntestuna
trusted module privacy

--- Releases what a log may show of an email address: its first letter and its domain.
pub policy masked_email
  from secret[PII] Text
  to public Text
  via mask_email
  purpose "show in the dispatch log which address a notice went to"
  owner support

mask_email(address: secret[PII] Text) -> public Text
=
  let parts = address.split(on: "@")
  if parts.len != 2 or address.len < 3
    "(hidden)"
  else
    let domain = parts.at(index: 1)
      if none use ""
    "{address.slice(start: 0, end: 1)}***@{domain}"

mask_email never returns more than one character of the mailbox. An address it cannot read is hidden whole, rather than shown in part. Its result is written public Text, so a reader sees at once that it lowers the label. notify is the only function that needs the raw address, so it is where the release happens: it sends the real address to the mail service, then returns the masked form, which is public. The rest of the program never holds the address, so the log line is public too:

day-to-day/src/notices.unauna
--- Finds the customer of a shipment and emails them the notice. Returns the masked address,
--- which the log may show.
pub notify(shipment: Shipment) -> Text
  uses @customers: Customers[find]
  uses @mailer: Mailer[send]
  fails NoticeError
=
  let customer = @customers.find(shipment.customer)
    if error fail DirectoryDown
    if none fail UnknownCustomer(id: shipment.customer)
  if not customer.wants_notices
    fail OptedOut(id: customer.id)
  else
    @mailer.send(customer.email, subject: "Order {shipment.order} has shipped", body: notice(customer, shipment: shipment))
      if error fail MailDown
    masked_email(customer.email)

Look at what did not change in notify. It still fails with OptedOut and UnknownCustomer, because the conditions it branches on, the Option from the directory and the field wants_notices, are public. Reading customer.email gives a secret[PII] Text, while customer.wants_notices stays a public Bool: a field keeps its own label. A branch on the address itself, followed by a fail, would be U4002, as exercise 3 shows.

The call of the policy obeys the program counter too. masked_email releases to public, so it may be called only where the program counter is public: here, after the checks of the directory and of wants_notices, which are public. A call of masked_email inside a branch on labeled data would be U4002, since its public result would reveal the condition. Put each release to public on a path that public data alone decides.

17.6.7 The manifest

The manifest declares the category, so that secret[PII] is allowed (section 17.4), and the trusted module, so that privacy may hold a policy (section 17.5):

day-to-day/una.tomltoml
[package]
name = "notices"
version = "0.1.0"
edition = "0.2"

[labels]
categories = ["PII"]

[trusted]
modules = ["privacy"]

[run]
entry = "notices"
grants = ["console"]

17.6.8 Running it

una run . prints the log shown in What you'll build. una report . lists every call of privacy.masked_email under information, with its place, purpose and owner: the one in notify, and the two in the policy's examples (section 17.7). It lists privacy under tcb, with its line count, as the code the guarantee trusts. dispatch, log_line, reason, main, the kinds Shipment, ServiceError and NoticeError, and the handlers directory, outbox, mail_down and directory_down are those of chapter 12, unchanged.

So the whole change to chapter 12's program is: one import line, three labels (on name, on email and on the result of notice), one accepts clause, one call of a policy in notify, the doc comments of Customer, Mailer, notice and notify, a module of 19 lines, and in the examples, the address the first one expects and two examples of the policy. In exchange, a later change outside the trusted module that prints a name or an address fails una check instead of reaching the log. The via functions are the exception: their labels are not checked (section 17.5). A reviewer who wants to know what personal data leaves the program reads the accepts clauses and the trusted module, line by line, and not every other line.

17.6.9 The whole program

The whole file, to read in one piece or to copy:

day-to-day/src/notices.unathe whole programcheckruntestuna
module notices

import privacy (masked_email)

--- A customer, as the customer directory knows them. Name and address are personal data.
pub kind Customer
  id: Text
  name: secret[PII] Text
  email: secret[PII] Text
  wants_notices: Bool

--- An order that has left the warehouse and waits for its shipping notice.
pub kind Shipment
  order: Text
  customer: Text
  carrier: Text

--- How a remote service can fail.
pub kind ServiceError = | Timeout

--- Why a shipment got no notice. Each variant carries what an operator needs to act on it.
pub kind NoticeError = UnknownCustomer(id: Text) | OptedOut(id: Text) | DirectoryDown | MailDown

--- The customer directory, a service on the network.
pub capability Customers
  op find(id: Text) -> Option[Customer]
    fails ServiceError

--- The mail service, a service on the network. It may receive personal data.
pub capability Mailer
  op send(to: Text, subject: Text, body: Text) -> Unit
    fails ServiceError
    accepts secret[PII]

--- The text of a shipping notice. It holds the customer's name, so it carries the name's label.
pub notice(customer: Customer, shipment: Shipment) -> secret[PII] Text = "Hello {customer.name}, your order {shipment.order} is on its way with {shipment.carrier}."

--- Finds the customer of a shipment and emails them the notice. Returns the masked address,
--- which the log may show.
pub notify(shipment: Shipment) -> Text
  uses @customers: Customers[find]
  uses @mailer: Mailer[send]
  fails NoticeError
=
  let customer = @customers.find(shipment.customer)
    if error fail DirectoryDown
    if none fail UnknownCustomer(id: shipment.customer)
  if not customer.wants_notices
    fail OptedOut(id: customer.id)
  else
    @mailer.send(customer.email, subject: "Order {shipment.order} has shipped", body: notice(customer, shipment: shipment))
      if error fail MailDown
    masked_email(customer.email)

--- What an operator reads in the dispatch log.
pub reason(failure: NoticeError) -> Text
=
  when failure
    is UnknownCustomer(id) -> "no customer has the id {id}"
    is OptedOut(id) -> "customer {id} asked for no notices"
    is DirectoryDown -> "the customer directory did not answer; retry later"
    is MailDown -> "the mail service did not answer; retry later"

--- One line of the dispatch log.
pub log_line(shipment: Shipment, outcome: Result[Text, NoticeError]) -> Text
=
  when outcome
    is Ok(address) -> "sent     {shipment.order} to {address}"
    is Err(failure) -> "skipped  {shipment.order}: {reason(failure)}"

--- Sends a notice for every shipment and logs each outcome. One failure does not stop the batch.
pub dispatch(shipments: List[Shipment]) -> Unit
  uses @customers: Customers[find]
  uses @mailer: Mailer[send]
  uses @log: Console[print]
=
  for shipment in shipments
    let outcome = attempt notify(shipment)
    @log.print(log_line(shipment, outcome: outcome))

--- A directory held in memory, for this run and for tests.
handler directory(customers: Map[Text, Customer]) for Customers
  op find(id) = customers.get(key: id)

--- A mail service that accepts every message and delivers none: a fake for this run and for tests.
handler outbox() for Mailer
  op send(to, subject, body) = unit

--- A mail service that never answers.
handler mail_down() for Mailer
  op send(to, subject, body) = fail Timeout

--- A directory that never answers.
handler directory_down() for Customers
  op find(id) = fail Timeout

--- The customers of this run and of the examples. Every address is fictional.
pub sample_customers() -> Map[Text, Customer]
=
  let rosa = Customer(id: "C-17", name: "Rosa", email: "rosa@example.invalid", wants_notices: true)
  let tomas = Customer(id: "C-20", name: "Tomas", email: "tomas@example.invalid", wants_notices: true)
  let ines = Customer(id: "C-21", name: "Ines", email: "ines@example.invalid", wants_notices: false)
  empty_map().with(key: rosa.id, value: rosa).with(key: tomas.id, value: tomas).with(key: ines.id, value: ines)

pub main() -> Unit
  uses @console: Console[print]
=
  let customers = sample_customers()
  let morning = [Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"), Shipment(order: "A-1002", customer: "C-20", carrier: "Parcelo"), Shipment(order: "A-1003", customer: "C-99", carrier: "Parcelo"), Shipment(order: "A-1004", customer: "C-21", carrier: "Parcelo")]
  dispatch(morning) with @customers = directory(customers), @mailer = outbox(), @log = @console
  let late = [Shipment(order: "A-1005", customer: "C-17", carrier: "Rapida")]
  dispatch(late) with @customers = directory(customers), @mailer = mail_down(), @log = @console

example "a customer who wants notices gets one"
  given @customers = directory(sample_customers())
  given @mailer = outbox()
  do notify(Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect result == "r***@example.invalid"

example "an unknown customer is rejected before any mail is sent"
  given @customers = directory(sample_customers())
  given @mailer = mail_down()
  do notify(Shipment(order: "A-1003", customer: "C-99", carrier: "Parcelo"))
  expect fails UnknownCustomer

example "a customer who asked for no notices is rejected before any mail is sent"
  given @customers = directory(sample_customers())
  given @mailer = mail_down()
  do notify(Shipment(order: "A-1004", customer: "C-21", carrier: "Parcelo"))
  expect fails OptedOut

example "a directory that does not answer is DirectoryDown, before any mail is sent"
  given @customers = directory_down()
  given @mailer = mail_down()
  do notify(Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect fails DirectoryDown

example "a mail service that does not answer is MailDown"
  given @customers = directory(sample_customers())
  given @mailer = mail_down()
  do notify(Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect fails MailDown

example "the notice names the customer, the order and the carrier"
  do notice(Customer(id: "C-17", name: "Rosa", email: "rosa@example.invalid", wants_notices: true), shipment: Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect result == "Hello Rosa, your order A-1001 is on its way with Parcelo."

example "a skipped shipment says why in the log"
  do log_line(Shipment(order: "A-1005", customer: "C-17", carrier: "Rapida"), outcome: Err(MailDown))
  expect result == "skipped  A-1005: the mail service did not answer; retry later"

example "the log shows the first letter and the domain of an address"
  do masked_email("tomas@example.invalid")
  expect result == "t***@example.invalid"

example "an address the mask cannot read is hidden"
  do masked_email("no address")
  expect result == "(hidden)"

Next:17.7 Testing it