Skip to main content

nitr_std/
utils.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2// This file is part of Nitr.
3// See https://nitrweb.com/ for more information
4// Copyright (C) 2024-present Jose Quintana <joseluisq.net>
5
6use mlua::{Function, Lua, Value};
7
8/// Builds an HMAC instance from a key of any length.
9///
10/// The single home of the "HMAC accepts any key length" invariant:
11/// `new_from_slice` is fallible only for fixed-key-length algorithms,
12/// which HMAC is not, so the `expect` cannot fire. Every MAC in the crate
13/// (signed cookies, `nitr.crypto.hmac_sha256`, JWT) constructs through
14/// here so key handling has one auditable site.
15pub(crate) fn new_hmac<M: hmac::digest::KeyInit>(key: &[u8]) -> M {
16    // Invariant: `new_from_slice` fails only for fixed-key-length
17    // algorithms, which HMAC is not.
18    #[allow(clippy::expect_used)]
19    <M as hmac::digest::KeyInit>::new_from_slice(key).expect("HMAC accepts any key length")
20}
21
22/// The deepest nesting a Lua value may have before it is serialized to
23/// JSON, deliberately mirroring serde_json's *deserialization* recursion
24/// limit so the two directions share one documented bound.
25///
26/// The limit exists because serialization has none of its own: serde_json
27/// recurses once per nesting level, and a script can build a table chain
28/// deep enough to overflow the Rust stack well within its Lua memory
29/// budget (verified empirically: ~30,000 levels aborts the process with
30/// SIGABRT on a default tokio worker stack). A stack overflow is an
31/// abort, not a panic — the containment boundary cannot catch
32/// it, so the bound must hold *before* a serializer recurses.
33pub(crate) const MAX_JSON_DEPTH: usize = 128;
34
35/// The most nodes a Lua value may expand to on the way to a serializer.
36///
37/// Depth alone is not a bound on *work*. A script can build
38/// `t = {a = prev, b = prev}` sixty times over: that value is sixty levels
39/// deep, so it passes [`MAX_JSON_DEPTH`] comfortably, but it is a DAG that
40/// a tree walk sees as 2^60 nodes. Neither execution budget covers the
41/// result — the walk is a tight Rust loop, so the instruction-count hook
42/// never fires (no Lua executes) and the async timeout never fires
43/// (nothing yields), which leaves a tokio worker wedged for good.
44///
45/// Counting *visits* rather than distinct nodes is the point: the visit
46/// count is precisely the work `serde_json` is about to redo, so a value
47/// that passes has a bounded serialization cost too.
48///
49/// What a full budget actually costs, measured rather than estimated:
50/// **~145 ms release, ~620 ms debug** for the cheapest shape that fills
51/// it. That is the ceiling on one request's unyieldable synchronous walk,
52/// and it is well above the ~10 ms this was first assumed to be — worth
53/// knowing, because `workers` concurrent requests can each spend it. It
54/// still does the job it exists for: turning an unbounded wedge (2^60
55/// visits, a worker gone for good) into a bounded pause with a catchable
56/// error. Lowering it would tighten that ceiling at the cost of refusing
57/// large-but-honest documents — a 1M-visit value is already a
58/// multi-megabyte response — so the number stays until a real workload
59/// argues otherwise. A const rather than a knob, for the same reason
60/// [`MAX_JSON_DEPTH`] is one.
61pub(crate) const MAX_JSON_NODES: usize = 1_000_000;
62
63/// Refuses a value that is nested deeper than [`MAX_JSON_DEPTH`] or
64/// expands to more than [`MAX_JSON_NODES`] nodes, with an ordinary
65/// catchable error, before any serializer recurses over it.
66///
67/// Every Lua-value-to-serializer site in the crate calls this first:
68/// `nitr.json` encoding and the JSON response helper, `cache:set` /
69/// `cache:remember`, `fetch` JSON bodies, JWT claims, sessions, SSE data,
70/// `nitr.etag`, `nitr.error` table bodies, `template:render` contexts, and
71/// log fields — so the bound has one auditable home. The walk itself
72/// recurses, but its depth is capped by the very bound it enforces; a
73/// cyclic table is infinitely deep and reports the depth error instead of
74/// hanging.
75///
76/// The JSON sites now enforce the same three rules inside the one
77/// serialization pass ([`crate::bounded`]) rather than through this
78/// pre-walk; there a cycle is refused by mlua's own recursion detection
79/// (`recursive table detected`) before the depth bound is reached. This
80/// walk remains the guard for renderers that are not serde serializers
81/// (`nitr.dbg`, the template context) and the reference the single-pass
82/// form is tested against.
83pub fn check_json_bounds(value: &Value) -> mlua::Result<()> {
84    let mut budget = MAX_JSON_NODES;
85    depth_walk(value, MAX_JSON_DEPTH, &mut budget, true)
86}
87
88/// The three refusals, shared with the single-pass form in
89/// [`crate::bounded`] so both spell the bound the same way.
90pub(crate) fn nodes_message() -> String {
91    format!(
92        "json value expands to more than {MAX_JSON_NODES} nodes (a shared subtree \
93         counts once per path to it)"
94    )
95}
96
97pub(crate) fn depth_message() -> String {
98    format!("json value nested deeper than {MAX_JSON_DEPTH} levels")
99}
100
101pub(crate) fn utf8_message() -> String {
102    "json value contains a string that is not valid UTF-8: encode binary data \
103     first (nitr.base64.encode)"
104        .into()
105}
106
107/// [`check_json_bounds`] without the UTF-8 rule, for renderers that show
108/// bytes as bytes (`nitr.dbg`'s `{:#?}`, the log placeholder path): a
109/// binary field is a legitimate thing to debug-print.
110pub(crate) fn check_value_bounds(value: &Value) -> mlua::Result<()> {
111    let mut budget = MAX_JSON_NODES;
112    depth_walk(value, MAX_JSON_DEPTH, &mut budget, false)
113}
114
115fn depth_walk(
116    value: &Value,
117    remaining: usize,
118    budget: &mut usize,
119    strict_utf8: bool,
120) -> mlua::Result<()> {
121    // Charged for every visit, scalars included, and a shared subtree
122    // counted once per path that reaches it — because that is what the
123    // serializer will do too.
124    if *budget == 0 {
125        return Err(mlua::Error::RuntimeError(nodes_message()));
126    }
127    *budget -= 1;
128    // mlua serializes a string that is not UTF-8 as *bytes*, which
129    // serde_json writes as an array of numbers — so a session field set
130    // to `nitr.crypto.random_bytes(16)` came back on the next request as a
131    // table of sixteen integers, with no error at save time. Refuse it
132    // here, where every serializer already passes through.
133    if strict_utf8
134        && let Value::String(s) = value
135        && s.to_str().is_err()
136    {
137        return Err(mlua::Error::RuntimeError(utf8_message()));
138    }
139    let Value::Table(table) = value else {
140        return Ok(());
141    };
142    if remaining == 0 {
143        return Err(mlua::Error::RuntimeError(depth_message()));
144    }
145    // Raw iteration, matching what serialization will walk; keys can be
146    // tables too, and a deep key must not slip past the check.
147    table.for_each(|key: Value, item: Value| {
148        depth_walk(&key, remaining - 1, budget, strict_utf8)?;
149        depth_walk(&item, remaining - 1, budget, strict_utf8)
150    })
151}
152
153/// A chain of `depth` nested tables (the root included).
154///
155/// Test-only, and deliberately shared rather than copied: the guard's own
156/// boundary tests and the per-site ones (`json`, `template`) must build
157/// the same shape, or a site can pass its test against a value the guard
158/// would never have seen.
159#[cfg(test)]
160pub(crate) fn deep_table(lua: &Lua, depth: usize) -> Value {
161    let root = lua.create_table().expect("table");
162    let mut cur = root.clone();
163    for _ in 1..depth {
164        let next = lua.create_table().expect("table");
165        cur.set("x", next.clone()).expect("set");
166        cur = next;
167    }
168    Value::Table(root)
169}
170
171/// A shared-subtree DAG: `t = {a = prev, b = prev}` applied `levels`
172/// times. Shallow (`levels + 1` deep) but `2^(levels + 1) - 1` table
173/// *visits*, which is the shape [`MAX_JSON_NODES`] exists to bound.
174#[cfg(test)]
175pub(crate) fn dag_table(lua: &Lua, levels: usize) -> Value {
176    let mut cur = lua.create_table().expect("table");
177    for _ in 0..levels {
178        let next = lua.create_table().expect("table");
179        next.set("a", cur.clone()).expect("set");
180        next.set("b", cur.clone()).expect("set");
181        cur = next;
182    }
183    Value::Table(cur)
184}
185
186/// `nitr.dbg(value)`: pretty-prints a Lua value at debug level.
187///
188/// Bounded by the same guard as every serializing builtin, because
189/// `{value:#?}` is a serializer too. mlua's pretty `Debug` recurses once
190/// per nesting level and carries only a *cycle* guard (a visited set of
191/// table pointers), which a chain of distinct tables never trips — so a
192/// deep enough value overflows the Rust stack, and that abort is not
193/// something the per-request `catch_unwind` can contain. Verified: a
194/// 30,000-deep table through `{:#?}` is a SIGABRT.
195///
196/// Degrades to a placeholder rather than raising, following
197/// [`crate::log`]: a diagnostic that fails the request it was added to
198/// diagnose is worse than one that says it could not render.
199pub(crate) fn create_debug_fn(lua: &Lua) -> mlua::Result<Function> {
200    lua.create_function(|_, value: Value| {
201        log_debug_value(&value);
202        Ok(value)
203    })
204}
205
206fn log_debug_value(value: &Value) {
207    // Nothing is walked or rendered unless the level is on.
208    if !tracing::enabled!(tracing::Level::DEBUG) {
209        return;
210    }
211    match check_value_bounds(value) {
212        Ok(()) => tracing::debug!("[lua] {value:#?}"),
213        Err(err) => tracing::debug!("[lua] <value not rendered: {err}>"),
214    }
215}
216
217/// Builds the structured error value the error model hands to Lua: the
218/// table `on_error` receives and `nitr.errinfo` returns. A plain table (it
219/// serializes to JSON for free) that stringifies — and concatenates — as
220/// the concise `kind: message (source:line)` form via a cached metatable.
221pub fn error_lua_value(lua: &Lua, info: &nitr_core::ErrorInfo) -> mlua::Result<mlua::Table> {
222    let t = lua.create_table()?;
223    t.raw_set("message", info.message.as_str())?;
224    t.raw_set("kind", info.kind)?;
225    if let Some(source) = &info.source {
226        t.raw_set("source", source.as_str())?;
227    }
228    if let Some(line) = info.line {
229        t.raw_set("line", line)?;
230    }
231    if let Some(module) = &info.module {
232        t.raw_set("module", module.as_str())?;
233    }
234    if let Some(traceback) = &info.traceback {
235        t.raw_set("traceback", traceback.as_str())?;
236    }
237    if !info.cause.is_empty() {
238        let causes = lua.create_table_from(
239            info.cause
240                .iter()
241                .enumerate()
242                .map(|(i, c)| (i + 1, c.as_str())),
243        )?;
244        t.raw_set("cause", causes)?;
245    }
246    t.raw_set("__concise", info.concise())?;
247    // For console prints: ANSI-colored on a terminal, identical to the
248    // concise form otherwise. `tostring`/`..` stay plain deliberately —
249    // those strings may end up in HTTP bodies and log files.
250    let pretty = if console_wants_color() {
251        info.concise_colored()
252    } else {
253        info.concise()
254    };
255    t.raw_set("pretty", pretty)?;
256    t.set_metatable(Some(error_metatable(lua)?))?;
257    Ok(t)
258}
259
260/// Whether `print`-style console output should carry color: stdout is a
261/// terminal and `NO_COLOR` is unset.
262fn console_wants_color() -> bool {
263    // Decided once: an `isatty` syscall and an environment lookup per
264    // error value is the wrong price on a path that runs under attack.
265    // Neither answer changes while the process lives.
266    static WANTS_COLOR: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
267    *WANTS_COLOR.get_or_init(|| {
268        use std::io::IsTerminal as _;
269        std::io::stdout().is_terminal() && std::env::var_os("NO_COLOR").is_none_or(|v| v.is_empty())
270    })
271}
272
273/// The shared metatable for error values, built once per state:
274/// `__tostring` for `tostring(err)` and `__concat` so `"prefix: " .. err`
275/// works directly in a log line.
276fn error_metatable(lua: &Lua) -> mlua::Result<mlua::Table> {
277    if let Ok(mt) = lua.named_registry_value::<mlua::Table>("nitr.error_mt") {
278        return Ok(mt);
279    }
280    let mt = lua.create_table()?;
281    mt.set(
282        "__tostring",
283        lua.create_function(|_, t: mlua::Table| t.raw_get::<String>("__concise"))?,
284    )?;
285    // Either operand may be the error value; Lua's own `tostring` applies
286    // the `__tostring` above for whichever side is.
287    mt.set(
288        "__concat",
289        lua.create_function(|lua, (a, b): (Value, Value)| {
290            let tostring: Function = lua.globals().get("tostring")?;
291            let a: String = tostring.call(a)?;
292            let b: String = tostring.call(b)?;
293            Ok(a + &b)
294        })?,
295    )?;
296    lua.set_named_registry_value("nitr.error_mt", &mt)?;
297    Ok(mt)
298}
299
300/// `nitr.errinfo(err)`: classifies whatever `pcall` caught into the same
301/// structured error value `on_error` receives. A Rust-side error arrives
302/// with its full chain (`Value::Error`); a Lua error arrives as a
303/// position-prefixed string; anything else is stringified. Idempotent on
304/// values that are already structured.
305pub(crate) fn create_errinfo_fn(lua: &Lua) -> mlua::Result<Function> {
306    lua.create_function(|lua, value: Value| {
307        let info = match &value {
308            Value::Error(err) => {
309                nitr_core::ErrorInfo::from_error(&nitr_core::Error::Lua((**err).clone()))
310            }
311            Value::String(s) => nitr_core::ErrorInfo::from_message(&s.to_string_lossy()),
312            Value::Table(t) if t.raw_get::<Option<String>>("__concise")?.is_some() => {
313                return Ok(t.clone());
314            }
315            other => {
316                let tostring: Function = lua.globals().get("tostring")?;
317                let text: String = tostring.call(other)?;
318                nitr_core::ErrorInfo::from_message(&text)
319            }
320        };
321        error_lua_value(lua, &info)
322    })
323}
324
325#[cfg(test)]
326mod tests {
327    use super::*;
328
329    #[test]
330    fn error_values_stringify_and_concatenate_as_the_concise_form() {
331        let lua = Lua::new();
332        let info = nitr_core::ErrorInfo::from_message("app.lua:7: boom");
333        let err = error_lua_value(&lua, &info).expect("value");
334        lua.globals().set("err", err).expect("set");
335
336        let (text, concat, message, line): (String, String, String, u32) = lua
337            .load(r#"return tostring(err), "got: " .. err, err.message, err.line"#)
338            .eval()
339            .expect("eval");
340        assert!(text.contains("boom"), "tostring: {text}");
341        assert!(text.contains("app.lua:7"), "tostring: {text}");
342        assert_eq!(concat, format!("got: {text}"));
343        assert_eq!(message, "boom");
344        assert_eq!(line, 7);
345    }
346
347    #[test]
348    fn errinfo_classifies_and_is_idempotent() {
349        let lua = Lua::new();
350        lua.globals()
351            .set("errinfo", create_errinfo_fn(&lua).expect("fn"))
352            .expect("set");
353        let (message, kind, twice_same): (String, String, bool) = lua
354            .load(
355                // `error(msg, 0)`: no position prefix, so the message is
356                // exactly what the script raised.
357                r#"local ok, caught = pcall(function() error("nope", 0) end)
358                   assert(not ok)
359                   local info = errinfo(caught)
360                   local again = errinfo(info)
361                   return info.message, info.kind, rawequal(info, again)"#,
362            )
363            .eval()
364            .expect("eval");
365        assert_eq!(message, "nope");
366        assert_eq!(kind, "lua");
367        assert!(twice_same, "a structured value passes through unchanged");
368    }
369
370    /// Binary strings are refused rather than silently becoming arrays.
371    #[test]
372    fn binary_strings_are_refused_not_serialized_as_byte_arrays() {
373        let lua = Lua::new();
374        let raw = lua.create_string(b"\xff\xfe").expect("string");
375        let err = check_json_bounds(&Value::String(raw.clone())).expect_err("binary");
376        assert!(err.to_string().contains("UTF-8"), "got: {err}");
377        let nested = lua.create_table().expect("table");
378        nested.set("k", raw.clone()).expect("set");
379        assert!(check_json_bounds(&Value::Table(nested)).is_err());
380        let text = lua.create_string("caf\u{e9}").expect("string");
381        check_json_bounds(&Value::String(text)).expect("UTF-8 passes");
382        // The debug renderer shows bytes as bytes and keeps accepting them.
383        check_value_bounds(&Value::String(raw)).expect("dbg accepts binary");
384    }
385
386    #[test]
387    fn json_depth_boundary_is_exact() {
388        let lua = Lua::new();
389        assert!(check_json_bounds(&deep_table(&lua, MAX_JSON_DEPTH)).is_ok());
390        let err = check_json_bounds(&deep_table(&lua, MAX_JSON_DEPTH + 1)).expect_err("129 deep");
391        assert!(
392            err.to_string().contains("nested deeper than 128 levels"),
393            "got: {err}"
394        );
395        // Scalars and shallow values pass untouched.
396        assert!(check_json_bounds(&Value::Integer(7)).is_ok());
397    }
398
399    /// A cyclic table is infinitely deep: the walk must report the depth
400    /// error, not hang or overflow.
401    #[test]
402    fn a_cyclic_table_reports_depth_instead_of_hanging() {
403        let lua = Lua::new();
404        let t = lua.create_table().expect("table");
405        t.set("me", t.clone()).expect("set");
406        let err = check_json_bounds(&Value::Table(t)).expect_err("cycle");
407        assert!(err.to_string().contains("nested deeper"), "got: {err}");
408    }
409
410    /// A shared subtree is shallow but expensive: 21 levels of
411    /// `{a = prev, b = prev}` is 22 deep — nowhere near the depth bound —
412    /// yet ~4.2 million table visits, which is the work the node budget
413    /// exists to refuse.
414    ///
415    /// The level count is chosen so this test *terminates either way*:
416    /// with the budget in place it stops after a million visits (~0.6 s
417    /// in the unoptimized profile `cargo test` uses), and with the budget
418    /// reverted it walks all ~4.2 M visits and fails in a few seconds
419    /// (measured ~3–5 s) rather than hanging. That distinction is the
420    /// whole point of picking 21 — a 60-level DAG, the shape an attacker
421    /// would actually send, never returns at all, and a test that hangs
422    /// on revert teaches nobody anything.
423    #[test]
424    fn a_shared_subtree_is_refused_by_node_count_not_depth() {
425        let lua = Lua::new();
426        let err = check_json_bounds(&dag_table(&lua, 21)).expect_err("21-level DAG");
427        assert!(
428            err.to_string().contains("expands to more than"),
429            "the node budget must be what refuses a DAG, not the depth bound: {err}"
430        );
431
432        // A DAG small enough to fit the budget still passes: the guard
433        // bounds work, it does not ban sharing.
434        check_json_bounds(&dag_table(&lua, 10)).expect("a 10-level DAG is ~2047 visits");
435    }
436
437    /// `nitr.dbg` formats with `{:#?}`, which is a serializer like any
438    /// other: mlua's pretty `Debug` recurses per nesting level behind only
439    /// a cycle guard, so an unguarded deep value is a stack overflow —
440    /// an abort, which `catch_unwind` cannot contain.
441    ///
442    /// Deleting the guard in `create_debug_fn` turns this test into a
443    /// SIGABRT that takes the whole test binary with it, which is exactly
444    /// the failure being prevented.
445    #[test]
446    fn dbg_returns_its_value() {
447        let lua = Lua::new();
448        lua.globals()
449            .set("dbg", create_debug_fn(&lua).expect("dbg"))
450            .expect("set");
451        let same: bool = lua
452            .load("local t = {} return dbg(t) == t and dbg(7) == 7")
453            .eval()
454            .expect("eval");
455        assert!(same);
456    }
457
458    #[test]
459    fn dbg_does_not_abort_on_a_deep_value() {
460        let lua = Lua::new();
461        let dbg = create_debug_fn(&lua).expect("dbg");
462        // Far past anything the guard admits, and past what the Rust
463        // stack survives being formatted.
464        dbg.call::<Value>(deep_table(&lua, 30_000))
465            .expect("dbg must degrade, not abort and not raise");
466        // A value within the bound still prints normally.
467        dbg.call::<Value>(deep_table(&lua, 8))
468            .expect("an ordinary value still prints");
469    }
470
471    /// Lua table keys can be tables too; a deep *key* must not slip past
472    /// the check and recurse in the serializer instead.
473    #[test]
474    fn deep_table_keys_are_bounded_too() {
475        let lua = Lua::new();
476        let outer = lua.create_table().expect("table");
477        outer
478            .set(deep_table(&lua, MAX_JSON_DEPTH), true)
479            .expect("set");
480        assert!(check_json_bounds(&Value::Table(outer)).is_err());
481    }
482}