scopes-rs 0.2.0

Strongly typed scoped authorization library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

# Scopes-rs

`scopes-rs` is a strongly typed scoped authorization library.

[![GitHub Release](https://img.shields.io/github/v/release/aripot007/scopes-rs)](https://github.com/aripot007/scopes-rs/releases/latest)
[![Crates.io Version](https://img.shields.io/crates/v/scopes-rs)](https://crates.io/crates/scopes-rs)
[![docs.rs](https://img.shields.io/docsrs/scopes-rs)](https://docs.rs/scopes-rs/latest/scopes_rs/)
[![codecov](https://codecov.io/github/aripot007/scopes-rs/graph/badge.svg?token=HE0TZTEACN)](https://codecov.io/github/aripot007/scopes-rs)

# Features

- Verify complex scope authorization policies
- Manipulate scopes in a strongly-typed fashion
- Generate boilerplate implementation with a derive macro
- Support for hierarchized scopes with the `hierarchy` feature

# Usage example

```rust
use std::str::FromStr;
use scopes_rs::{
    policy::IntoPolicy,
    derive::Scope
};


#[derive(Clone, PartialEq, Scope)]
enum ApiScope {
    Settings,
    SettingsReadonly,
    Profile,
    ProfileReadonly
}


pub fn main() {

    // Parse the scopes from a web request for example
    let scopes: Vec<ApiScope> = parse_scopes("profile settings.readonly");

    // Convert a single scope in a policy that requires this scope
    let policy = ApiScope::SettingsReadonly.into_policy();

    assert_eq!(true, policy.verify(&scopes));

    // Policies can also be combined together with &, | and !
    let other_policy = policy & ApiScope::ProfileReadonly;

    // With the hierarchy feature, "profile.readonly" is included in "profile", so this is accepted
    #[cfg(feature = "hierarchy")]
    assert_eq!(true, other_policy.verify(&scopes));

    // Otherwise, the scopes require an exact match
    #[cfg(not(feature = "hierarchy"))]
    assert_eq!(false, other_policy.verify(&scopes));
}

// You would usually parse the scopes from a request in a middleware with
// proper error handling, but this is sufficient here
fn parse_scopes(data: &str) -> Vec<ApiScope> {

    data.split_whitespace()
        .filter_map(|s| ApiScope::from_str(s).ok())
        .collect()
}
```

The [`examples`](https://github.com/aripot007/scopes-rs/tree/master/examples) directory
contains some other examples of how to use this library.

The docs also provide more code snippets and examples.

## License

Licensed under either of

 * Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
 * MIT license
   ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.