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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
# Sputnik
A lightweight layer on top of [Hyper](https://hyper.rs/) to facilitate
building web applications.
Sputnik provides:
* convenience wrappers around hyper's `Request` & `Response`
* parse, set and delete cookies
(powered by the [cookie](https://crates.io/crates/cookie) crate)
* parse query strings and HTML form data (powered by the
[serde_urlencoded](https://crates.io/crates/serde_urlencoded) crate)
* cookie-based [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) tokens
* `Key`: a convenience wrapper around HMAC (stolen from the cookie crate, so
that you don't have to use `CookieJar`s if you don't need them)
* `decode_expiring_claim` & `encode_expiring_claim`, which can be combined with
`Key` to implement [signed & expiring cookies](#signed--expiring-cookies)
(with the expiry date encoded into the signed cookie value)
Sputnik does **not**:
* handle routing: for most web apps `match`ing on (method, path) suffices
* handle configuration: we recommend [toml](https://crates.io/crates/toml)
* handle persistence: we recommend [diesel](https://diesel.rs/)
* handle templating: we recommend [maud](https://maud.lambda.xyz/)
## CsrfToken example
```rust
use std::convert::Infallible;
use hyper::service::{service_fn, make_service_fn};
use hyper::{Method, Server};
use serde::Deserialize;
use sputnik::security::CsrfToken;
use sputnik::{Request, Response, Error};
async fn route(req: &mut Request) -> Result<Response,Error> {
match (req.method(), req.uri().path()) {
(&Method::GET, "/form") => get_form(req).await,
(&Method::POST, "/form") => post_form(req).await,
_ => return Err(Error::not_found("page not found".to_owned()))
}
}
async fn get_form(req: &mut Request) -> Result<Response, Error> {
let mut response = Response::new();
let csrf_token = CsrfToken::from_request(req, &mut response);
*response.body() = format!("<form method=post>
<input name=text>{}<button>Submit</button></form>", csrf_token.html_input()).into();
Ok(response)
}
#[derive(Deserialize)]
struct FormData {text: String}
async fn post_form(req: &mut Request) -> Result<Response, Error> {
let mut response = Response::new();
let csrf_token = CsrfToken::from_request(req, &mut response);
let msg: FormData = req.into_form_csrf(&csrf_token).await?;
*response.body() = format!("hello {}", msg.text).into();
Ok(response)
}
/// adapt between Hyper's types and Sputnik's convenience types
async fn service(req: hyper::Request<hyper::Body>) -> Result<hyper::Response<hyper::Body>, Infallible> {
match route(&mut req.into()).await {
Ok(res) => Ok(res.into()),
Err(err) => Ok(err.response_builder().body(err.message.into()).unwrap())
// you can easily wrap or log errors here
}
}
#[tokio::main]
async fn main() {
let service = make_service_fn(move |_| {
async move {
Ok::<_, hyper::Error>(service_fn(move |req| {
service(req)
}))
}
});
let addr = ([127, 0, 0, 1], 8000).into();
let server = Server::bind(&addr).serve(service);
println!("Listening on http://{}", addr);
server.await;
}
```
## Signed & expiring cookies
After a successful authentication you can build a session id cookie for
example as follows:
```rust
let expiry_date = OffsetDateTime::now_utc() + Duration::hours(24);
let mut cookie = Cookie::new("userid",
key.sign(
&encode_expiring_claim(&userid, expiry_date)
));
cookie.set_secure(Some(true));
cookie.set_expires(expiry_date);
cookie.set_same_site(SameSite::Lax);
resp.set_cookie(cookie);
```
This session id cookie can then be retrieved and verified as follows:
```rust
let userid = req.cookies().get("userid")
.ok_or_else(|| Error::unauthorized("expected userid cookie".to_owned()))
.and_then(|cookie| key.verify(cookie.value()).map_err(Error::unauthorized))
.and_then(|value| decode_expiring_claim(value).map_err(|e| Error::unauthorized(format!("failed to decode userid cookie: {}", e))))?;
```
Tip: If you want to store multiple claims in the cookie, you can
(de)serialize a struct with [serde_json](https://docs.serde.rs/serde_json/).
This approach can pose a lightweight alternative to JWT, if you don't care
about the standardization aspect.
|
