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 { ... }):
| Field | Meaning |
|---|---|
max_age | None ends with browser |
script_readable | not HttpOnly |
same_site | Lax, Strict, None |
partitioned | add Partitioned (CHIPS) |
path, domain | scope |
signed | sign 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
| Call | What it does |
|---|---|
cx.signup(row).await? | hash, 422 if taken, sign in |
cx.login(email, password).await? | check password |
wisp::signup, wisp::login | same 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?