Home / Learn / 12 Capabilities
12.2 The host's capabilities and grants
Page 3 of 10
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:
[package]
name = "hello"
version = "0.1.0"
edition = "0.2"
[run]
entry = "hello"
grants = ["console"]una run . prints:
The store is openThe 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:
[package]
name = "export"
version = "0.1.0"
edition = "0.2"
[run]
entry = "export"
grants = ["console"]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:
[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:
[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:
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}")- Three
useslines onmain. Each names one host capability and the operations it needs.mainmay write files, but not read them. @clock.now().Clock.nowgives the milliseconds since the Unix epoch, as anInt. Each call is an effect, so it goes on its own line.attempt @files.write("stock-export.csv", content: content).Files.writecan fail withFileError(NotFound,DeniedorIo).attemptkeeps the outcome, as in section 7.4, and thewhenreports either case."stock-export.csv". The path resolves insidesrc/, the directory of the grant"files:src:write"inuna.toml.
una run . prints:
export written: 3 linesand 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 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, 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/:
--- 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}"stock-export.csv: written
../stock-export.csv: Denied
/tmp/stock-export.csv: Deniedstock-export.csvis insidesrc/, and is written.../stock-export.csvclimbs out with.., so it isDenied./tmp/stock-export.csvis an absolute path, a path from the root of the disk, so it isDeniedtoo.
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
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 does, but cannot print it without a declared policy. Chapter 17 explains labels and how to release data legitimately.
12.2.7 Which grant to give
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 tries a fourth path, reports/../stock-export.csv. It contains ... What does it print for it?
Show the answer
reports/../stock-export.csv: writtenThe 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?
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. Either grant "files:src:write" or "files:src:read,write", or remove the write from main.