use std::sync::Mutex;
use base64::Engine as _;
use base64::engine::general_purpose::URL_SAFE_NO_PAD as B64;
use hmac::{Hmac, Mac as _};
use mlua::{Lua, MetaMethod, Table, UserData, UserDataMethods, Value};
use sha2::Sha256;
type HmacSha256 = Hmac<Sha256>;
pub struct RequestCookies(Vec<(String, String)>);
impl RequestCookies {
pub fn parse(header: &str) -> Self {
Self(
cookie::Cookie::split_parse(header)
.flatten()
.map(|c| (c.name().to_string(), c.value().to_string()))
.collect(),
)
}
#[doc(hidden)]
pub fn pairs(&self) -> &[(String, String)] {
&self.0
}
pub(crate) fn get(&self, name: &str) -> Option<&str> {
self.0
.iter()
.find(|(n, _)| n == name)
.map(|(_, v)| v.as_str())
}
}
impl UserData for RequestCookies {
fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
methods.add_meta_method(MetaMethod::Index, |lua, this, name: Value| {
let Value::String(name) = name else {
return Ok(Value::Nil);
};
match this.get(&name.to_string_lossy()) {
Some(v) => Ok(Value::String(lua.create_string(v)?)),
None => Ok(Value::Nil),
}
});
methods.add_method(
"verify",
|lua, this, (name, secret): (String, String)| match this
.get(&name)
.and_then(|raw| verify(&name, raw, &secret))
{
Some(v) => Ok(Value::String(lua.create_string(v)?)),
None => Ok(Value::Nil),
},
);
}
}
#[derive(Default)]
pub struct ResponseCookies(Mutex<Vec<String>>);
impl ResponseCookies {
pub fn values(&self) -> Vec<String> {
self.0.lock().map(|v| v.clone()).unwrap_or_default()
}
fn push(&self, value: String) -> mlua::Result<()> {
self.0
.lock()
.map_err(|_| mlua::Error::RuntimeError("the cookie list lock is poisoned".into()))?
.push(value);
Ok(())
}
}
impl UserData for ResponseCookies {
fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
methods.add_method(
"set",
|lua, this, (name, value, opts): (String, String, Option<Table>)| {
this.push(build_cookie(lua, &name, &value, opts.as_ref())?)
},
);
methods.add_method(
"set_signed",
|lua, this, (name, value, secret, opts): (String, String, String, Option<Table>)| {
this.push(build_cookie(
lua,
&name,
&sign(&name, &value, &secret),
opts.as_ref(),
)?)
},
);
}
}
pub(crate) fn attach_cookie(resp: &Table, cookie: String) -> mlua::Result<()> {
match resp.raw_get::<Value>("cookies")? {
Value::UserData(ud) => {
let cookies = ud.borrow::<ResponseCookies>().map_err(|_| {
mlua::Error::RuntimeError(
"the response `cookies` field is not a cookie builder".into(),
)
})?;
cookies.push(cookie)
}
Value::Nil => {
let cookies = ResponseCookies::default();
cookies.push(cookie)?;
resp.set("cookies", cookies)
}
other => Err(mlua::Error::RuntimeError(format!(
"invalid `cookies` field of type `{}` in the response table",
other.type_name()
))),
}
}
#[derive(Debug, Clone, Default)]
pub struct CookieDefaults {
pub secure: bool,
pub insecure_warning: Option<String>,
}
fn secure_default(lua: &Lua) -> bool {
lua.app_data_ref::<CookieDefaults>()
.is_some_and(|defaults| defaults.secure)
}
fn warn_insecure_once(lua: &Lua) -> bool {
static WARNED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
let Some(why) = lua
.app_data_ref::<CookieDefaults>()
.and_then(|defaults| defaults.insecure_warning.clone())
else {
return false;
};
if WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) {
return false;
}
tracing::warn!("{why}");
true
}
pub(crate) fn merge_cookie_opts(defaults: Table, caller: Option<&Table>) -> mlua::Result<Table> {
if let Some(caller) = caller {
for pair in caller.pairs::<Value, Value>() {
let (key, value) = pair?;
defaults.set(key, value)?;
}
}
defaults.set("http_only", true)?;
Ok(defaults)
}
pub(crate) fn build_cookie(
lua: &Lua,
name: &str,
value: &str,
opts: Option<&Table>,
) -> mlua::Result<String> {
check_cookie_name(name)?;
check_cookie_value(value)?;
let mut builder = cookie::Cookie::build((name.to_owned(), value.to_owned()));
let explicit_secure = match opts {
Some(opts) => opts.get::<Option<bool>>("secure")?,
None => None,
};
match explicit_secure {
Some(true) => builder = builder.secure(true),
Some(false) => {}
None if secure_default(lua) => builder = builder.secure(true),
None => {
warn_insecure_once(lua);
}
}
if let Some(opts) = opts {
if opts.get::<Option<bool>>("http_only")?.unwrap_or(false) {
builder = builder.http_only(true);
}
if let Some(path) = opts.get::<Option<String>>("path")? {
check_cookie_attribute("path", &path)?;
builder = builder.path(path);
}
if let Some(domain) = opts.get::<Option<String>>("domain")? {
check_cookie_attribute("domain", &domain)?;
builder = builder.domain(domain);
}
if let Some(secs) = opts.get::<Option<i64>>("max_age")? {
builder = builder.max_age(cookie::time::Duration::seconds(secs));
}
if let Some(same_site) = opts.get::<Option<String>>("same_site")? {
builder = builder.same_site(match same_site.to_ascii_lowercase().as_str() {
"strict" => cookie::SameSite::Strict,
"lax" => cookie::SameSite::Lax,
"none" => cookie::SameSite::None,
other => {
return Err(mlua::Error::RuntimeError(format!(
"invalid same_site value `{other}`: expected Strict, Lax or None"
)));
}
});
}
}
Ok(builder.build().to_string())
}
fn check_cookie_name(name: &str) -> mlua::Result<()> {
const SEPARATORS: &[u8] = b"()<>@,;:\\\"/[]?={} \t";
let ok = !name.is_empty()
&& name
.bytes()
.all(|b| b.is_ascii_graphic() && !SEPARATORS.contains(&b));
if ok {
Ok(())
} else {
Err(mlua::Error::RuntimeError(format!(
"invalid cookie name {name:?}: a name is one or more ASCII characters other \
than controls, whitespace and ()<>@,;:\\\"/[]?={{}}"
)))
}
}
fn check_cookie_value(value: &str) -> mlua::Result<()> {
let ok = value
.bytes()
.all(|b| b.is_ascii_graphic() && !matches!(b, b'"' | b',' | b';' | b'\\'));
if ok {
Ok(())
} else {
Err(mlua::Error::RuntimeError(
"invalid cookie value: values may not contain controls, whitespace, quotes, \
commas, semicolons or backslashes — encode it first (nitr.base64, or a signed \
cookie)"
.into(),
))
}
}
fn check_cookie_attribute(attr: &str, value: &str) -> mlua::Result<()> {
if value.bytes().all(|b| b.is_ascii_graphic() && b != b';') {
Ok(())
} else {
Err(mlua::Error::RuntimeError(format!(
"invalid cookie {attr} {value:?}: controls, whitespace and ';' are not allowed"
)))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SetCookie {
pub name: String,
pub value: String,
pub path: Option<String>,
pub domain: Option<String>,
pub max_age: Option<i64>,
pub expires: Option<i64>,
pub secure: bool,
pub http_only: bool,
pub same_site: Option<String>,
}
pub fn parse_set_cookie(line: &str) -> Option<SetCookie> {
let parsed = cookie::Cookie::parse(line).ok()?;
Some(SetCookie {
name: parsed.name().to_string(),
value: parsed.value().to_string(),
path: parsed.path().map(str::to_string),
domain: parsed.domain().map(str::to_string),
max_age: parsed.max_age().map(|age| age.whole_seconds()),
expires: parsed.expires_datetime().map(|at| at.unix_timestamp()),
secure: parsed.secure().unwrap_or(false),
http_only: parsed.http_only().unwrap_or(false),
same_site: parsed.same_site().map(|s| s.to_string()),
})
}
pub fn sign(name: &str, value: &str, secret: &str) -> String {
let payload = B64.encode(value);
format!(
"{payload}.{}",
B64.encode(mac_bytes(name, &payload, secret))
)
}
pub fn verify(name: &str, signed: &str, secret: &str) -> Option<String> {
let (payload, sig) = signed.rsplit_once('.')?;
let sig = B64.decode(sig).ok()?;
new_mac(name, payload, secret).verify_slice(&sig).ok()?;
String::from_utf8(B64.decode(payload).ok()?).ok()
}
fn new_mac(name: &str, payload: &str, secret: &str) -> HmacSha256 {
let mut mac: HmacSha256 = crate::utils::new_hmac(secret.as_bytes());
mac.update(name.as_bytes());
mac.update(b"=");
mac.update(payload.as_bytes());
mac
}
fn mac_bytes(name: &str, payload: &str, secret: &str) -> Vec<u8> {
new_mac(name, payload, secret)
.finalize()
.into_bytes()
.to_vec()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn signed_cookies_round_trip_and_reject_tampering() {
let signed = sign("session", "user-42", "s3cret");
assert_eq!(
verify("session", &signed, "s3cret").as_deref(),
Some("user-42")
);
assert_eq!(verify("session", &signed, "other"), None);
assert_eq!(verify("tracking", &signed, "s3cret"), None);
let tampered = format!("x{signed}");
assert_eq!(verify("session", &tampered, "s3cret"), None);
assert_eq!(verify("session", "garbage", "s3cret"), None);
}
#[test]
fn the_secure_default_applies_unless_the_caller_says_otherwise() {
for (default_secure, explicit, want_secure) in [
(None, None, false),
(Some(false), None, false),
(Some(true), None, true),
(Some(true), Some(false), false),
(Some(false), Some(true), true),
] {
let lua = mlua::Lua::new();
if let Some(secure) = default_secure {
lua.set_app_data(CookieDefaults {
secure,
insecure_warning: None,
});
}
let opts = match explicit {
Some(value) => {
let opts = lua.create_table().expect("table");
opts.set("secure", value).expect("set");
Some(opts)
}
None => None,
};
let cookie = build_cookie(&lua, "session", "abc", opts.as_ref()).expect("cookie");
assert_eq!(
cookie.contains("Secure"),
want_secure,
"default={default_secure:?} explicit={explicit:?} gave `{cookie}`"
);
}
}
#[test]
fn the_insecure_warning_fires_once_on_the_first_cookie_built_without_secure() {
let lua = mlua::Lua::new();
assert!(
!warn_insecure_once(&lua),
"nothing registered, nothing to say"
);
lua.set_app_data(CookieDefaults {
secure: false,
insecure_warning: Some("[tls] enabled = false".into()),
});
let opts = lua.create_table().expect("table");
opts.set("secure", false).expect("set");
build_cookie(&lua, "a", "1", Some(&opts)).expect("cookie");
assert!(
warn_insecure_once(&lua),
"an explicit false must not have spent the warning"
);
build_cookie(&lua, "b", "2", None).expect("cookie");
assert!(
!warn_insecure_once(&lua),
"spent by the cookie built without Secure"
);
}
#[test]
fn merging_cookie_options_keeps_the_defaults_a_caller_did_not_mention() {
let lua = mlua::Lua::new();
let defaults = lua.create_table().expect("table");
defaults.set("path", "/").expect("set");
defaults.set("same_site", "Lax").expect("set");
let caller = lua.create_table().expect("table");
caller.set("path", "/admin").expect("set");
let merged = merge_cookie_opts(defaults, Some(&caller)).expect("merge");
assert_eq!(
merged.get::<String>("path").expect("path"),
"/admin",
"the caller's value wins"
);
assert_eq!(
merged.get::<String>("same_site").expect("same_site"),
"Lax",
"a default the caller did not mention must survive"
);
assert!(
merged.get::<bool>("http_only").expect("http_only"),
"http_only must survive"
);
let defaults = lua.create_table().expect("table");
defaults.set("same_site", "Lax").expect("set");
let caller = lua.create_table().expect("table");
caller.set("http_only", false).expect("set");
caller.set("same_site", "None").expect("set");
let merged = merge_cookie_opts(defaults, Some(&caller)).expect("merge");
assert!(
merged.get::<bool>("http_only").expect("http_only"),
"http_only is forced, not merely defaulted"
);
assert_eq!(
merged.get::<String>("same_site").expect("same_site"),
"None",
"same_site is deliberately overridable"
);
}
#[test]
fn cookie_parts_that_would_inject_attributes_are_refused() {
let lua = mlua::Lua::new();
for (name, value) in [
("lang", "en; Domain=.example.com; SameSite=None"),
("lang", "a b"),
("lang", "x\"y"),
("lang", "a,b"),
("lang", "back\\slash"),
("bad name", "v"),
("bad=name", "v"),
("", "v"),
] {
let err = build_cookie(&lua, name, value, None).expect_err("injection");
assert!(
err.to_string().contains("invalid cookie"),
"{name}={value}: {err}"
);
}
for attr in ["path", "domain"] {
let opts = lua.create_table().expect("table");
opts.set(attr, "/x; Secure").expect("set");
let err = build_cookie(&lua, "n", "v", Some(&opts)).expect_err(attr);
assert!(err.to_string().contains(attr), "{err}");
}
for value in ["", "abc", "a-b_c.d~e=", "ZmZm.YWJj"] {
build_cookie(&lua, "ok", value, None).expect("plain value");
}
}
#[test]
fn cookies_serialize_their_options() {
let lua = mlua::Lua::new();
let opts: Table = lua
.load(r#"{ http_only = true, secure = true, same_site = "Lax", max_age = 3600, path = "/" }"#)
.eval()
.expect("opts table");
let cookie = build_cookie(&lua, "session", "abc", Some(&opts)).expect("cookie");
for part in [
"session=abc",
"HttpOnly",
"Secure",
"SameSite=Lax",
"Max-Age=3600",
"Path=/",
] {
assert!(cookie.contains(part), "`{cookie}` should contain `{part}`");
}
}
#[test]
fn set_cookie_lines_parse_into_their_attributes() {
let full = parse_set_cookie(
"sid=abc; Path=/app; Domain=example.com; Max-Age=60; \
Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly; SameSite=Strict",
)
.expect("parses");
assert_eq!(
full,
SetCookie {
name: "sid".into(),
value: "abc".into(),
path: Some("/app".into()),
domain: Some("example.com".into()),
max_age: Some(60),
expires: Some(1_445_412_480),
secure: true,
http_only: true,
same_site: Some("Strict".into()),
}
);
let bare = parse_set_cookie("theme=dark").expect("bare");
assert_eq!((bare.path, bare.max_age, bare.secure), (None, None, false));
let deleted = parse_set_cookie("sid=; Max-Age=0").expect("deletion");
assert_eq!((deleted.value.as_str(), deleted.max_age), ("", Some(0)));
assert_eq!(parse_set_cookie("no pair here"), None);
assert_eq!(parse_set_cookie(""), None);
}
#[test]
fn nitr_cookie_signs_and_verifies_like_the_cookie_builders() {
let lua = mlua::Lua::new();
let nitr = lua.create_table().expect("table");
super::super::register(&lua, &nitr).expect("register");
lua.globals().set("nitr", nitr).expect("global");
let (signed, back, forged, swapped): (String, String, Value, Value) = lua
.load(
r#"local s = nitr.cookie.sign("session", '{"user":"ann"}', "k")
return s, nitr.cookie.verify("session", s, "k"),
nitr.cookie.verify("session", s, "other"),
nitr.cookie.verify("tracking", s, "k")"#,
)
.eval()
.expect("eval");
assert_eq!(signed, sign("session", r#"{"user":"ann"}"#, "k"));
assert_eq!(back, r#"{"user":"ann"}"#);
assert!(forged.is_nil() && swapped.is_nil());
}
proptest::proptest! {
#[test]
fn prop_set_cookie_round_trip(
name in "[A-Za-z0-9_!#$%&'*+.^`|~-]{1,16}",
value in "[A-Za-z0-9!#$%&'()*+./:<=>?@^_`{|}~-]{0,32}",
path in proptest::option::of("/[A-Za-z0-9_./-]{0,16}"),
max_age in proptest::option::of(-10i64..100_000),
same_site in proptest::option::of(proptest::sample::select(vec!["Strict", "Lax", "None"])),
secure in proptest::bool::ANY,
http_only in proptest::bool::ANY,
) {
let lua = mlua::Lua::new();
let opts = lua.create_table().expect("opts");
opts.set("secure", secure).expect("secure");
opts.set("http_only", http_only).expect("http_only");
if let Some(path) = &path {
opts.set("path", path.as_str()).expect("path");
}
if let Some(age) = max_age {
opts.set("max_age", age).expect("max_age");
}
if let Some(same_site) = same_site {
opts.set("same_site", same_site).expect("same_site");
}
let line = build_cookie(&lua, &name, &value, Some(&opts)).expect("build");
let parsed = parse_set_cookie(&line).expect("parse back");
proptest::prop_assert_eq!(parsed.name, name);
proptest::prop_assert_eq!(parsed.value, value);
proptest::prop_assert_eq!(parsed.path, path);
proptest::prop_assert_eq!(parsed.max_age, max_age.map(|age| age.max(0)));
proptest::prop_assert_eq!(parsed.same_site.as_deref(), same_site);
proptest::prop_assert_eq!(parsed.secure, secure || same_site == Some("None"));
proptest::prop_assert_eq!(parsed.http_only, http_only);
}
#[test]
fn prop_signed_cookies_round_trip_and_any_tamper_fails(
name in "[ -~]{1,16}",
value in "[ -~]{0,48}",
secret in "[ -~]{1,32}",
pos in proptest::prelude::any::<proptest::sample::Index>(),
) {
let signed = sign(&name, &value, &secret);
let verified = verify(&name, &signed, &secret);
proptest::prop_assert_eq!(verified.as_deref(), Some(value.as_str()));
let mut tampered: Vec<char> = signed.chars().collect();
let pos = pos.index(tampered.len());
tampered[pos] = if tampered[pos] == 'A' { 'B' } else { 'A' };
let tampered: String = tampered.into_iter().collect();
proptest::prop_assert_eq!(verify(&name, &tampered, &secret), None);
proptest::prop_assert_eq!(verify(&name, &signed, "other-secret"), None);
proptest::prop_assert_eq!(verify("other-name", &signed, &secret), None);
}
}
}