Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

Cookies and Sign-In

cx.set_cookie("theme", "dark"); // 400 days, HttpOnly, SameSite=Lax
let theme = cx.cookie_or("theme", "light".to_string());

cx.set_signed_cookie("user", name); // HMAC-SHA256, needs WISP_SECRET
let who = cx.signed_cookie("user"); // Some only if the signature holds

let me = cx.user()?; // signed-in row or redirect

Cookies

cx.set_cookie(name, value) takes any Display; an empty value deletes. It sets a site-wide cookie for 400 days, HttpOnly, SameSite=Lax. cx.cookie(name) reads within the same request. cx.cookie_or(name, default) and cx.signed_cookie_or(name, default) parse as FromStr. cx.delete_cookie(name) deletes one. For another path or domain use cx.set_cookie_with(name, value, CookieOptions { ... }):

FieldMeaning
max_ageNone ends with browser
script_readablenot HttpOnly
same_siteLax, Strict, None
partitionedadd Partitioned (CHIPS)
path, domainscope
signedsign it

Secure is added over HTTPS (behind a proxy when WISP_CLIENT_IP_HEADER is set, or ORIGIN is https://) and with SameSite=None or partitioned. partitioned keeps one copy of the cookie for each top-level site, for a cookie that a page embedded on other sites sets. Use it with same_site: SameSite::None: a browser can reject Partitioned with Lax or Strict. On a plain-http onion request it has no effect. #[derive(Cookie)] puts a struct in one cookie via Display and FromStr. The value is visitor input, so check it after reading.

Signed Cookies

cx.set_signed_cookie(name, value) adds an expiry and an HMAC-SHA256 signature keyed with WISP_SECRET. cx.signed_cookie(name) returns the value only if the signature holds and has not expired.

A release server whose app signs does not start without WISP_SECRET (openssl rand -hex 32). Dev builds keep one in .wisp/secret, used only on a loopback HOST; dev mode on any other address (a debug build in a container with HOST=0.0.0.0) signs with a key of its own process, so every signed cookie, session, token and guarded form stops holding on restart, and a copied .wisp/secret signs nothing. To rotate, move the old secret to WISP_SECRET_OLD.

Signing In

CallWhat it does
cx.signup(row).await?hash, 422 if taken, sign in
cx.login(email, password).await?check password
wisp::signup, wisp::loginsame without a Cx
cx.sign_in(id)signed cookie session, 30 days
cx.signed_in()?the id, else 303 to /login (401 for JSON). 503 while the server cannot read the sign-outs
cx.signed_in().ok()no redirect
cx.user()?the row
cx.sign_out()ends it on this browser

signup takes a #[model] with a hash field and email or name (an Account). These calls use the lone Table with a Password field in src/db.rs, else the one wisp::users(&db::USERS) names in init. wisp::sign_in_page("/enter") in init replaces /login. A page that reads the session is sent private, no-store.

login allows ten tries a minute per who, then a 429 with retry-after. Put a Backoff keyed by (&who, cx.visitor()) in front if lockout matters. RateLimit::per_minute(n).check(key)? limits anything else. A typed Password needs #[validate(min_len = 8)]. Set one by hand with Password::new(&typed).await?; a Plain one is refused with a 500.

Sign Out Everywhere

wisp::sign_out_everywhere(id) ends every copy of a session, including a stolen one. It keeps a count in the table wisp_sign_outs. With wisp::store, instances share it. It returns Err if the store cannot be read. Until the server reads the sign-outs once, cx.signed_in() gives a 503 to a visitor with a session. The native server tries to read them again each second. The edge tries on a check, at most once a second. A later read that fails keeps the counts that the server has. With wisp::store, the native server reads the counts again every 30 s. The edge reads them once, at the first session. Two sign-outs of one id at the same moment, on two instances, may save one count, because a store has no compare-and-set.

Passwords

wisp::password::hash(&password).await? stores and wisp::password::check(&typed, hash).await? checks. hash is Option<&str>: None hashes a stand-in, so timing hides which names exist. The format is PBKDF2-HMAC-SHA256, 600,000 rounds (OWASP), written $pbkdf2-sha256$i=600000$salt$key. wisp::password::outdated(&hash) says to hash again. A hash naming over 10,000,000 rounds is refused. A full hashing queue gives a 503 with retry-after. Hashing runs on its own threads, never the worker's.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.