---
title: "Labels and information flow"
url: https://una-lang.org/en/docs/guides/labels/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/una-for-agents.md
---

# Labels and information flow

Every type may carry a label: a level, `public` (the default), `internal`, `confidential`, `secret` or `restricted`, and categories declared in `una.toml`, as in `secret[PII] Text`. Values flow up, never down: the result of an operation joins its operands' labels; branching on a labeled value raises the program counter, so what the branches produce is labeled too, and they may not fail; each operation argument is a sink bounded by its `accepts` (`Console.print` accepts `public`). `Env.get` and `Files.read` return `internal` text. A label labels one position of a type: in `internal Option[Int]` which variant the value is, `Some` or `None`, is `internal`, but the `Int` inside is `public`, so a function that returns a labeled element writes `internal Option[internal Int]`.

**Printing what you read from `Env` or `Files` takes a policy.** That text, and anything computed from it, even its length, is `internal`, so printing it is U4003, as in the second block below. No label of your program can be lowered to fix that: declassify the value through a `policy` in a trusted module, as the `journal` package after it does, and call the policy where you print. `una explain U4003` shows the same pattern for a name read from `Env`. Whether a variable is set is `public`, though, since `Env.get` returns a `public` `Option`: treat which variables are set as public configuration, and never encode a secret in it.

**Writes to a labeled path make file failures labeled.** The files a run finds depend on where earlier writes landed, in this run or an earlier one. So when a package writes to an `internal` path, or writes under an `internal` condition, the failure of every `Files.read` and `Files.write` in it is `internal`: handle it with `attempt` or `if error use`, not `if error pass` (U4002). A package whose writes go to public paths, at a public program counter, keeps public failures (S-14).

```una
module demo

pub kind Note
  day: Int
  body: secret Text

pub kind Mood = Calm | Busy

--- The answer depends on the text, so it is as secret as the text.
pub mood(note: Note) -> secret Mood = if note.body.len > 280 then Busy else Calm
```

```una
-- fails with U4003
module demo

pub main() -> Unit
  uses @console: Console[print]
  uses @env: Env[get]
=
  let name = @env.get("USER")
    if none use "nobody"
  @console.print("hello {name}")
```

Labels go down only through a `policy` in a module that its header and `una.toml` both mark trusted. The policy is the only entry to its private `via` function, and every call of it is listed in the build report with its purpose and owner:

`una.toml`
```toml
[package]
name = "journal"
version = "0.1.0"
edition = "0.2"

[labels]
categories = ["Private"]

[trusted]
modules = ["release"]
```

`src/release.una`
```una
trusted module release

pub policy length_band
  from confidential[Private] Text
  to public Nat
  via hundreds
  purpose "show how much was written without showing what"
  owner journal_owner

hundreds(text: confidential[Private] Text) -> public Nat = text.len / 100
```

`src/show.una`
```una
module show

import release (length_band)

pub size(text: confidential[Private] Text) -> Nat = length_band(text)
```

A generic function may decide something by comparing values of a type parameter. It must not hand the decided value to a function value it was given, because that function value was checked only against values of `T` passed through, and its result, effects or failures would reveal the comparison. The checker rejects the call where the decided value meets the function value, here at `each: k`, whether a prelude function such as `map`, `filter`, `first_where` or `fold` calls it or a generic function of the program does (U4001):

```una
-- fails with U4001
module demo

pub capability Log
  op write(n: Int) -> Unit

count_chosen[T: Eq](a: T, b: T, p: T, q: T, k: fn(T) -> Int) -> Unit
  uses @log: Log[write]
=
  let ns = [if a == b then p else q].map(each: k)
  @log.write(ns.sum())
```

Pass the values of `T` through unchanged (`[p, q].map(each: k)` is accepted), or give the decision to the caller as a `Bool` result. Edition `0.1` reports the same U4001 at `each: k`, and also the code where the decision would come out, U4003 at the sink or U4002 at a call with effects (#346, #350, #354). A written annotation that mentions `T` cannot hold such a value either; see section 13.
