Home / Docs / Configure a package

Authority of a dependency: may

What it does

A dependency holds no capability unless the package hands it one, at a call, with with, and within a ceiling the package writes for it. The ceiling is the may lines under the need: the most a call into the dependency may hand over. Without may lines it is empty, and a dependency then reaches no file, no network and no console, whatever its code says.

Every module of a dependency is a boundary (see [boundaries]): a call into it takes no capability by name from the caller (U3020), hands over only what fits the ceiling (U3021), and reaches no release of a label.

The lock records the ceiling it was written with. A wider may line is U7009 until una ita lock --accept-authority <package>, naming the package, records it, so every widening is explicit and shows in the lock's diff.

ita.unauna
ita shop
  version 0.1.0
  edition 0.4

needs
  util from path "deps/util"
    may Console[print]
    accept name
ita.lockuna
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0

package util 0.2.0
  from path "deps/util"
  digest "sha256:0000000000000000000000000000000000000000000000000000000000000000"
  granted by shop may Console[print]
deps/util/ita.unauna
ita util
  version 0.2.0
  edition 0.4
deps/util/src/say.unauna
module say

pub say(line: Text) -> Unit
  uses @console: Console[print]
=
  @console.print(line)
src/shop.unauna
module shop

import util.say (say)

pub main() -> Unit
  uses @console: Console[print]
=
  say("hi") with @console = @console[print]

Forms

text
needs
  <name> from path "<dir>"
    may <Capability>[<op>, ...], ...

Examples

A call that leaves the capability to the caller's own context is U3020:

ita.unauna
ita shop
  version 0.1.0
  edition 0.4

needs
  util from path "deps/util"
    may Console[print]
    accept name
ita.lockuna
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0

package util 0.2.0
  from path "deps/util"
  digest "sha256:0000000000000000000000000000000000000000000000000000000000000000"
  granted by shop may Console[print]
deps/util/ita.unauna
ita util
  version 0.2.0
  edition 0.4
deps/util/src/say.unauna
module say

pub say(line: Text) -> Unit
  uses @console: Console[print]
=
  @console.print(line)
src/shop.unauna
-- fails with U3020
module shop

import util.say (say)

pub main() -> Unit
  uses @console: Console[print]
=
  say("hi")

A grant beyond the ceiling, here an empty one, is U3021:

ita.unauna
ita shop
  version 0.1.0
  edition 0.4

needs
  util from path "deps/util"
    accept name
ita.lockuna
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0

package util 0.2.0
  from path "deps/util"
  digest "sha256:0000000000000000000000000000000000000000000000000000000000000000"
deps/util/ita.unauna
ita util
  version 0.2.0
  edition 0.4
deps/util/src/say.unauna
module say

pub say(line: Text) -> Unit
  uses @console: Console[print]
=
  @console.print(line)
src/shop.unauna
-- fails with U3021
module shop

import util.say (say)

pub main() -> Unit
  uses @console: Console[print]
=
  say("hi") with @console = @console[print]

A ceiling wider than the one the lock records is U7009, at the may line, until it is accepted:

ita.unauna
-- fails with U7009
ita shop
  version 0.1.0
  edition 0.4

needs
  util from path "deps/util"
    may Console[print]
    accept name
ita.lockuna
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0

package util 0.2.0
  from path "deps/util"
  digest "sha256:0000000000000000000000000000000000000000000000000000000000000000"
deps/util/ita.unauna
ita util
  version 0.2.0
  edition 0.4
deps/util/src/say.unauna
module say

pub say(line: Text) -> Unit
  uses @console: Console[print]
=
  @console.print(line)
src/shop.unauna
module shop

import util.say (say)

pub main() -> Unit
  uses @console: Console[print]
=
  say("hi") with @console = @console[print]
Terminal
$ una ita lock --accept-authority util
add util 0.2.0 (path deps/util): digest sha256:…; may Console[print]; uses Console[print]
wrote ita.lock

Edge cases

Diagnostics

Edition

Edition 0.4 and later, a preview.

Normative source