https://github.com/sunfishcode/ambient-authority

Ambient Authority
https://github.com/sunfishcode/ambient-authority

Last synced: 12 days ago
JSON representation

Ambient Authority

• Host: GitHub
• URL: https://github.com/sunfishcode/ambient-authority
• Owner: sunfishcode
• License: other
• Created: 2021-04-09T04:53:16.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2023-06-30T16:23:37.000Z (over 1 year ago)
• Last Synced: 2024-05-09T14:39:45.308Z (6 months ago)
• Language: Rust
• Homepage:
• Size: 47.9 KB
• Stars: 19
• Watchers: 3
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md

Awesome Lists containing this project

README

        


  
ambient-authority


  


    Ambient Authority

  


  


    

    

    

  



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.

[cap-std]: https://docs.rs/cap-std/*/cap_std/

[clippy.toml]: https://github.com/sunfishcode/ambient-authority/blob/main/clippy.toml

[`AmbientAuthority`]: https://docs.rs/ambient-authority/latest/ambient_authority/struct.AmbientAuthority.html

[`ambient_authority`]: https://docs.rs/ambient-authority/latest/ambient_authority/func.ambient_authority.html