---
title: "Host capabilities and grants"
url: https://una-lang.org/en/docs/language/capabilities/host/
release: v0.4.0
edition: "0.1 and later"
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/language/capabilities/host.md
---

# Host capabilities and grants

## What it does

Host capabilities are the ones the runtime implements: `Console`, `Clock`, `Env`, `Files` and `Keys`, from edition `0.2` on also `Http`, and from edition `0.4` on also `HttpServer`, which a module imports from `std.host` (see [Serving HTTP](https://una-lang.org/en/docs/guides/serving-http/)). They enter a program only through `main`'s `uses` clauses, and the runtime provides them only when they are granted (allowed by whoever runs the program), in `una.toml` or with `--grant`. Other functions receive them from their callers by name, like any [capability](https://una-lang.org/en/docs/language/capabilities/capability/).

Learn more: [The host's capabilities and grants](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/).

`una.toml`

```toml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

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

`src/shop.una`

```una
module shop

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("The shop is open")
```

## Forms

The host capabilities:

| Capability | Operation | Fails | Accepts |
| --- | --- | --- | --- |
| `Console` | `print(line: Text) -> Unit` | | `public` |
| `Clock` | `now() -> Int` | | `public` |
| `Env` | `get(name: Text) -> Option[internal Text]` | | `public` |
| `Files` | `read(path: Text) -> internal Text` | `FileError` | `public` |
| `Files` | `write(path: Text, content: Text) -> Unit` | `FileError` | `internal` |
| `Keys` | `hmac(key_name: Text, data: Text) -> internal Hashed` | `KeyError` | `public` for `key_name`, any label for `data` |
| `Http` (edition `0.2`) | `get(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |
| `Http` (edition `0.2`) | `post(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |
| `Http` (edition `0.2`) | `put(url: Text, headers: List[Header], body: Text, key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |
| `Http` (edition `0.2`) | `delete(url: Text, headers: List[Header], key_name: Option[Text]) -> internal Response` | `HttpError` | `internal` |

`internal` is a label: a mark on data that says how sensitive it is, which the checker follows wherever the data goes (see [labels](https://una-lang.org/en/docs/language/information-flow/labels/)).

The grant specs:
- `console`, `clock` and `env`;
- `keys:<keyfile>`;
- `files:<path>:read`, `files:<path>:write` and `files:<path>:read,write`;
- from edition `0.2` on, `http:<origin>` and `http:<origin>:<methods>`.

They are given in `[run] grants` of `una.toml`, or as `--grant` flags of `una run`.

## Examples

A host operation of `main` that no grant allows is reported by `una check`, before the program runs:

`una.toml`

```toml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

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

`src/shop.una`

```una
-- fails with U3012
module shop

pub main() -> Unit
  uses @console: Console[print]
  uses @clock: Clock[now]
=
  let opened = @clock.now()
  @console.print("opened at {opened}")
```

What `Env.get` and `Files.read` return is `internal`, so printing it to the console, which accepts only `public`, is rejected. Lowering a label takes a [policy](https://una-lang.org/en/docs/language/information-flow/policy/), a declared and reviewed release of data:

`una.toml`

```toml
[package]
name = "shop"
version = "0.1.0"
edition = "0.2"

[run]
entry = "shop"
grants = ["console", "env"]
```

`src/shop.una`

```una
-- fails with U4003
module shop

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

## Edge cases

Further rules:

- **Files stay inside the grant.** A `Files` path is resolved against the grant's prefix (the directory the grant names). An absolute path, a `..` that leaves the prefix, or a final component that is a symbolic link (a file that points to another file) fails with `Denied`; path resolution never escapes the prefix.
- **Keys stay outside values.** `Keys` loads its keys from the grant's file, and key material never enters Una values. The result of `hmac` is labeled `internal`, joined with every label of the type of `data`, and lowering it takes a policy. `key_name` accepts only `public`, so a labeled key name, or a call under a raised program counter (when the conditions that decided whether this line runs read labeled data; see [Branches and failures: implicit flows](https://una-lang.org/en/learn/information-flow/branches-and-failures-implicit-flows/)), is U4003.
- **Labeled failures.** Whether a host operation fails is labeled by the arguments that decide it: the path of `Files`, not the content; the key name of `Keys.hmac`, not the data; and every argument of `Http`, so its failures are `internal`. A `Files.write` to an `internal` path fails `internal`, and every `Files` failure also carries the package's file-state label: the labels that decide where the package's writes land and whether they run.
- **Host text.** When `Files.read` or `Env.get` meets bytes that are not valid UTF-8, the run aborts with U6005.
- **Out of the model.** Races on a path, hard links, resource limits and other processes are outside what the checker reasons about, and `una report` lists such channels under `out_of_model`.
- **User handlers.** Code may implement a host capability with its own handler, such as a fake `Keys` in examples. The host implementations are used only by `una run` and by an executable that `una build` makes.
- **Declared in `std.host`.** A user capability with the same name is a different declaration.

## Diagnostics

- [U3012](https://una-lang.org/en/docs/errors/U3012/): a host operation of `main` that no grant allows, or a `uses` of `main` that no grant can provide.
- [U4003](https://una-lang.org/en/docs/errors/U4003/): labeled data sent to an operation that does not accept its label.
- [U6005](https://una-lang.org/en/docs/errors/U6005/): at run time, host text that is not valid UTF-8.

## Edition

The five host capabilities of v0.1 are in every edition. Edition `0.2` adds `Http`, with its grants `http:<origin>` and `http:<origin>:<methods>`. Edition `0.4`, a preview, adds `HttpServer`, imported from `std.host` and granted by a `serve:` grant (`spec/31 §1`, `spec/31 §2`), lets an `http` grant carry limits, and moves a package's grants to `ita.una`.

## Normative source

- `spec/05 §7`: host capabilities, rules 1 to 4.
- `spec/14 §3`: the operations, `Files` paths, `Keys`, labels and host text.
- `spec/13 §5`: grant specs and `una run`; `spec/13 §7`: `[run] grants`.
- `spec/07 §4`: sinks; `spec/07 §7` rule 4: labeled failures.
- `spec/24 §1`: the `Http` operations; `spec/24 §2`: `Http` grants; `spec/24 §5` rule 3: the labels of `Http` failures.
- `spec/31 §1`: `HttpServer`; `spec/31 §2`: `serve:` grants (edition `0.4`).
- Decision record: [ADR 0039](https://github.com/una-lang/una/blob/v0.4.0/docs/adr/0039-labels-of-keys-hmac.md), for the labels of `Keys.hmac`.
