---
title: "12.2 The host's capabilities and grants"
url: https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/
release: v0.4.0
edition: "0.2"
---

# 12.2 The host's capabilities and grants

## 12.2.1 What the host is

The **host** is what runs your program: the una runtime on your computer or a server. It is the only part of the system that can really print, read a file or ask the time, so the capabilities for these things come from it. They are the **host capabilities**:

| Capability | Operations | What it does |
| --- | --- | --- |
| `Console` | `print(line: Text) -> Unit` | writes a line to the screen |
| `Clock` | `now() -> Int` | gives the milliseconds since the Unix epoch, 1 January 1970 |
| `Env` | `get(name: Text)` | reads an environment variable of the process |
| `Files` | `read(path: Text)`, `write(path: Text, content: Text)` | reads and writes files, and can fail with `FileError` |
| `Keys` | `hmac(key_name: Text, data: Text)` | computes a keyed hash with a secret key that never enters the program |
| `Http` | requests over the network (edition `0.2`) | talks to web services |

They are in scope in every module, with no `import`. But a function can hold one only if its caller hands it over, and the first caller of all is `main`. `main` gets its host capabilities from `una run`, and only those that the run **grants**.

## 12.2.2 What a grant is

A grant is the permission, written down, for the program to use a host capability when it runs. You have written one since chapter 1. The program that says the store is open has this manifest:

```toml include="steps/04-hello/una.toml" title="steps/04-hello/una.toml"
[package]
name = "hello"
version = "0.1.0"
edition = "0.2"

[run]
entry = "hello"
grants = ["console"]
```

`una run .` prints:

```text include="steps/04-hello/expected/output.txt"
The store is open
```

The two halves work together. The `uses @console: Console[print]` line of `main` is a promise to callers and reviewers: this function prints, and does nothing else outside the program. The line `grants = ["console"]` is the package's decision, in its manifest, about what a run may do: this run may print. A store's keycard works the same way: the card lists the doors, and the building still decides which doors are open tonight.

## 12.2.3 Why a program needs grants

You run programs you did not write: a tool from a colleague, a package from the internet, an example from a book. Its header says what it may do, but the header is part of the program, written by its author. The grants are what the package's manifest, or the person at the command line, allows the run to do.

Here is a stock export whose `main` writes a file. Its manifest grants only the console:

```toml include="steps/05-ungranted/una.toml" title="steps/05-ungranted/una.toml"
[package]
name = "export"
version = "0.1.0"
edition = "0.2"

[run]
entry = "export"
grants = ["console"]
```

```una include="steps/05-ungranted/src/export.una" title="steps/05-ungranted/src/export.una"
module export

--- Writes the end-of-day stock export. The manifest grants only the console.
pub main() -> Unit
  uses @console: Console[print]
  uses @files: Files[write]
=
  let outcome = attempt @files.write("stock-export.csv", content: "LAMP-01,4\n")
  @console.print("export: {outcome}")
```

`una check .` refuses it before anything runs:

```text include="steps/05-ungranted/expected/rendered.txt"
[U3012] Error: `main` uses `write` of `Files`, which `[run] grants` does not grant
   ╭─[ src/export.una:6:3 ]
   │
 6 │   uses @files: Files[write]
   │   ────────────┬────────────
   │               ╰────────────── `main` uses `write` of `Files`, which `[run] grants` does not grant
   │
   │ Help: repair 1 (widens grant: the program then gets this host authority when it runs): grant `write` of `Files` in `[run] grants` of `una.toml`, or with `--grant`
   │
   │ Note: run `una explain U3012` for an explanation
───╯
```

The message is U3012: `main` uses `write` of `Files`, "which `[run] grants` does not grant". The mark points at the `uses` line of `main`. The help line offers a repair that "widens grant": add the grant to `una.toml`. The people who maintain the package decide whether to, and the decision shows in review, as a changed line of the manifest.

## 12.2.4 How to write grants

### 12.2.4.1 `[run] grants` in `una.toml`

The grants are a list of texts under `[run]`, next to `entry`, which names the module whose `main` runs:

```toml include="steps/06-host/una.toml" title="steps/06-host/una.toml"
[package]
name = "export"
version = "0.1.0"
edition = "0.2"

[run]
entry = "export"
grants = ["console", "clock", "files:src:write"]
```

Each text grants one host capability:

| Grant | What `main` may use |
| --- | --- |
| `"console"` | `Console` |
| `"clock"` | `Clock` |
| `"files:src:read"` | `Files[read]`, inside the directory `src` |
| `"files:src:write"` | `Files[write]`, inside `src` |
| `"files:src:read,write"` | both operations, inside `src` |
| `"files:src/exports:write"` | `Files[write]`, inside `src/exports` only |
| `"env"` | `Env` |
| `"keys:<keyfile>"` | `Keys`, with the secret keys read from that file |
| `"http:<origin>"` or `"http:<origin>:<methods>"` | `Http`, toward that origin only, such as `https://api.example.invalid`, and only those methods when they are listed (edition `0.2`) |

A `Files` grant always carries a directory and a mode, so it says where the program may read or write, and which of the two.

### 12.2.4.2 `--grant` on the command line

`una run` also takes grants as flags, one per capability, such as `--grant clock` after `una run .`. They count for that run only, and nothing records them. Prefer the manifest: it is reviewed with the code.

### 12.2.4.3 The host capabilities in `main`

`main` declares what it uses, as any function does, and the grants must cover it. The step of this section writes an end-of-day stock export, stamped with the time, so it needs three grants, as its manifest shows.

## 12.2.5 An end-of-day stock export

The module reads the clock, writes the export, and reports the outcome:

:::steps
```una include="steps/06-host/src/export.una" title="steps/06-host/src/export.una" verified="check, run"
module export

--- The stock to export, one `SKU,units` line each.
stock_lines() -> List[Text] = ["LAMP-01,4", "DESK-02,1", "CHAIR-09,0"]

--- Writes the end-of-day stock export, stamped with the time it was taken.
pub main() -> Unit
  uses @console: Console[print]
  uses @clock: Clock[now]
  uses @files: Files[write]
=
  let taken = @clock.now()
  let body = stock_lines().join(separator: "\n")
  let content = "taken at {taken}\n{body}\n"
  let outcome = attempt @files.write("stock-export.csv", content: content)
  when outcome
    is Ok -> @console.print("export written: {stock_lines().len} lines")
    is Err(failure) -> @console.print("export failed: {failure}")
```

1. **Three `uses` lines on `main`.** Each names one host capability and the operations it needs. `main` may write files, but not read them.
2. **`@clock.now()`.** `Clock.now` gives the milliseconds since the Unix epoch, as an `Int`. Each call is an effect, so it goes on its own line.
3. **`attempt @files.write("stock-export.csv", content: content)`.** `Files.write` can fail with `FileError` (`NotFound`, `Denied` or `Io`). `attempt` keeps the outcome, as in [section 7.4](https://una-lang.org/en/learn/failure/failures-as-values-attempt-and-result/#s7-4), and the `when` reports either case.
4. **`"stock-export.csv"`.** The path resolves inside `src/`, the directory of the grant `"files:src:write"` in `una.toml`.
:::

`una run .` prints:

```text include="steps/06-host/expected/output.txt"
export written: 3 lines
```

and leaves the export in `src/stock-export.csv`. The time in it changes on every run, so the program does not print it.

## 12.2.6 How grants behave

### 12.2.6.1 What `una check` and `una run` compare

When `una.toml` lists grants under `[run]`, `una check` compares them with the `uses` of `main`: a host operation that the grants do not cover is U3012, as [Why a program needs grants](#why-a-program-needs-grants) showed.

`una run` grants the union of `[run] grants` and its `--grant` flags, for that run only, and it checks the `uses` of `main` against that union before anything runs: a host operation that neither grants is U3012 there too, and the program does not start. `una check` takes no `--grant` flag, so it reads only the manifest. A package whose manifest has no `grants` line gives `una check` no list to compare with, so its check passes. Whatever the manifest says, `una run .` stops with U3012 before anything runs when a host operation of `main` is not granted, until a grant is added in `una.toml` or with `--grant`. A package whose `grants` list lacks `"clock"`, as in [Using a host capability that is not granted](https://una-lang.org/en/learn/capabilities/common-mistakes/#using-a-host-capability-that-is-not-granted-u3012), fails `una check`, yet `una run . --grant clock` runs it. What a run may do is the manifest plus the command line, so read both.

### 12.2.6.2 Paths stay inside the grant

A `Files` grant fixes a directory when the program starts, and every path the program passes is read from that directory. A path that tries to leave it does not reach the file: the operation fails with `Denied`. The step tries four paths against a grant of `src/`:

```una include="steps/07-outside-grant/src/export.una#try_write" title="steps/07-outside-grant/src/export.una"
--- Writes one line to `path`, and says what happened.
try_write(path: Text) -> Text
  uses @files: Files[write]
=
  let outcome = attempt @files.write(path, content: "LAMP-01,4\n")
  when outcome
    is Ok -> "{path}: written"
    is Err(failure) -> "{path}: {failure}"
```

```text include="steps/07-outside-grant/expected/output.txt#L1-L3"
stock-export.csv: written
../stock-export.csv: Denied
/tmp/stock-export.csv: Denied
```

- **`stock-export.csv`** is inside `src/`, and is written.
- **`../stock-export.csv`** climbs out with `..`, so it is `Denied`.
- **`/tmp/stock-export.csv`** is an absolute path, a path from the root of the disk, so it is `Denied` too.

`Denied` is a failure like any other, so the program handles it and goes on. The grant, not the program, decides where its files may be.

### 12.2.6.3 Labels on what a program reads

> [!NOTE] What a program reads from files and the environment is labeled.
> `Files.read` returns `internal Text`, and `Env.get` returns `internal` values too. `Clock.now` returns a public `Int`. A label says how sensitive data is, and the console accepts only `public` data. So the program can write what it read to a file, as the back room of [section 12.1](https://una-lang.org/en/learn/capabilities/declaring-what-a-function-may-do-uses-in-full/#s12-1) does, but cannot print it without a declared policy. [Chapter 17](https://una-lang.org/en/learn/information-flow/) explains labels and how to release data legitimately.

## 12.2.7 Which grant to give

:::decide
**Which to use:**

| The program… | Grant |
| --- | --- |
| Prints | `"console"` |
| Reads the time | `"clock"` |
| Reads its input files | `"files:<dir>:read"`, on the directory that holds them |
| Writes its output | `"files:<dir>:write"`, on a directory of its own |
| Needs a capability for one run only, such as a trial of a new feature | `--grant` on that run |
:::

Grant the least that works: the narrowest directory, and only the modes the program uses. A grant that is not there cannot be misused.

## 12.2.8 Check yourself: grants

The step of [Paths stay inside the grant](#paths-stay-inside-the-grant) tries a fourth path, `reports/../stock-export.csv`. It contains `..`. What does it print for it?

:::answer Show the answer
```text include="steps/07-outside-grant/expected/output.txt#L4"
reports/../stock-export.csv: written
```

The path goes into `reports` and back out, so it ends inside `src/`: it names the same file as `stock-export.csv`, and the write is allowed. Only a `..` that leaves the granted directory is `Denied`.
:::

A package grants `["console", "files:src:read"]`. Its `main` declares `uses @console: Console[print]` and `uses @files: Files[write]`. Does `una check .` pass?

:::answer Show the answer
No. The grant covers reading files, not writing them, so `una check .` reports U3012 at the `uses @files` line of `main`, as in [Why a program needs grants](#why-a-program-needs-grants). Either grant `"files:src:write"` or `"files:src:read,write"`, or remove the write from `main`.
:::
