In capability-based security contexts, ambient authority means anything a
program can do that interacts with the outside world that isn't represented by
a handle.

This crate defines an empty function, ambient_authority, which returns a
value of type AmbientAuthority. This is an empty type used in function
signatures to declare that they use ambient authority. When an API uses
AmbientAuthority in all functions that use ambient authority, one can quickly
locate all the calls to such functions by scanning for calls to
ambient_authority.

To use the AmbientAuthroity type in an API:

• Add an AmbientAuthority argument at the end of the argument list of any
  function that uses ambient authroity, and add a # Ambient Authority
  section in the documentation comments for such functions explaining their
  use of ambient authority.

• Re-export the ambient_authority function and AmbientAuthority type
  from this crate, so that users can easily use the same version.

• Ensure that all other pub functions avoid using ambient authority,
  including mutable static state such as static Atomic, Cell, RefCell,
  Mutex, RwLock, or similar state, including once_cell or lazy_static
  state with initialization that uses ambient authority.

For example, see the cap-std crate's API, which follows these guidelines.

One of the cool things about capability-oriented APIs is that programs don't
need to be pure to take advantage of them. That said, for programs which do
which to aim for purity, this repository has a clippy configuration which can
help. To use it:

• Manually ensure that all immediate dependencies follow the above convention.

• Copy the clippy.toml file into the top level source directory, add
  #![deny(clippy::disallowed_methods)] to the root module (main.rs or
  lib.rs), and run cargo clippy or equivalent.