Home / Learn / 12 Capabilities

Release v0.4.0Edition 0.2

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:

steps/04-hello/una.tomltoml
[package]
name = "hello"
version = "0.1.0"
edition = "0.2"

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

una run . prints:

Output
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:

steps/05-ungranted/una.tomltoml
[package]
name = "export"
version = "0.1.0"
edition = "0.2"

[run]
entry = "export"
grants = ["console"]
steps/05-ungranted/src/export.unauna
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:

Diagnostic
[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:

steps/06-host/una.tomltoml
[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/06-host/src/export.unacheckrununa
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, 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:

Output
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 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/:

steps/07-outside-grant/src/export.unauna
--- 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}"
Output
stock-export.csv: written
../stock-export.csv: Denied
/tmp/stock-export.csv: Denied

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
Output
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?

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.

Next:12.3 Your own capabilities and handlers