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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
//! Minijinja environment + the `render` helper every handler uses.
//!
//! The environment is built once on first call (`OnceLock`) and includes
//! every admin template via `include_str!` so the binary ships
//! self-contained — no on-disk templates needed at runtime.
//!
//! `environment` (dev/test/prod) is exposed as a template global so
//! wrapper.html can gate the Tailwind CDN vs the precompiled admin.css.
use minijinja::Environment;
use umbral::web::Html;
use crate::AdminError;
static ENGINE: std::sync::OnceLock<Environment<'static>> = std::sync::OnceLock::new();
pub(crate) fn engine() -> &'static Environment<'static> {
ENGINE.get_or_init(|| {
let mut env = Environment::new();
env.set_auto_escape_callback(|_| minijinja::AutoEscape::Html);
// Percent-encode for safe embedding in query strings — used by
// the active-filter chip links and pagination URLs in
// data_table.html. Reuses the existing `urlencoding_simple`
// helper so we don't pull a new crate just to expose a filter.
env.add_filter("urlencode", |s: String| -> String {
crate::util::urlencoding_simple(&s)
});
// Serialise a value to JSON for safe embedding in an inline
// <script> block. Minijinja stable doesn't ship `tojson` by
// default; we route through serde_json so every kind a
// template might pass (string, array, object, number) lands as
// a valid JS literal. Falls back to `null` if serialisation
// refuses the input.
//
// Returns a `from_safe_string` Value so the auto-escape
// callback skips it — otherwise `{"foo":"bar"}` would land in
// a <script> block as `{"foo":"bar"}` and
// the JS parser would die on the first `&`. That cascade
// killed every JS function defined later in the same block,
// which is why the FK search input's oninput handler couldn't
// find `umbral._filterFkSearch`.
env.add_filter("tojson", |v: minijinja::Value| -> minijinja::Value {
let json = serde_json::to_string(&v).unwrap_or_else(|_| "null".to_string());
// WEB-3: this output is dropped into inline <script> blocks via
// `from_safe_string` (autoescape skipped). serde_json leaves
// `<`, `>`, `&` raw, so a filter value containing `</script>`
// would break out of the script element and run attacker JS in
// the admin origin. Escape those to their `\uXXXX` JSON forms
// (still valid JSON, parses to the same value) plus the U+2028/
// U+2029 line separators that terminate JS strings. Produces an
// inline JSON script block (a json_script-style embed).
let safe = json
.replace('<', "\\u003c")
.replace('>', "\\u003e")
.replace('&', "\\u0026")
.replace('\u{2028}', "\\u2028")
.replace('\u{2029}', "\\u2029");
minijinja::Value::from_safe_string(safe)
});
// Date/datetime humanizers. Templates render
// raw RFC3339 / SQL-shaped timestamps through one of these
// instead of dumping the unreadable `2026-06-08T21:23:20.619...`
// straight at the user:
//
// {{ item.at | humanize_date }} → "Jun 8, 2026 at 9:23 PM"
// {{ item.at | naturaltime }} → "2 hours ago"
//
// Both accept anything `chrono::DateTime::parse_from_rfc3339`
// or `NaiveDateTime::parse_from_str` can handle (the SQLite
// `datetime('now')` shape `2026-06-08 21:23:20` included).
// On parse failure the original value is returned untouched —
// a "couldn't humanize" template should still render legible
// text rather than throw.
env.add_filter("humanize_date", |s: String| -> String {
crate::util::humanize_date(&s)
});
env.add_filter("naturaltime", |s: String| -> String {
crate::util::naturaltime(&s)
});
env.add_template(
"admin/wrapper.html",
include_str!("../templates/wrapper.html"),
)
.expect("admin/wrapper.html parses");
env.add_template("admin/base.html", include_str!("../templates/base.html"))
.expect("admin/base.html parses");
env.add_template("admin/login.html", include_str!("../templates/login.html"))
.expect("admin/login.html parses");
env.add_template("admin/index.html", include_str!("../templates/index.html"))
.expect("admin/index.html parses");
env.add_template("admin/list.html", include_str!("../templates/list.html"))
.expect("admin/list.html parses");
env.add_template(
"admin/detail.html",
include_str!("../templates/detail.html"),
)
.expect("admin/detail.html parses");
env.add_template("admin/form.html", include_str!("../templates/form.html"))
.expect("admin/form.html parses");
env.add_template(
"admin/changelist.html",
include_str!("../templates/changelist.html"),
)
.expect("admin/changelist.html parses");
env.add_template(
"admin/sheet_preview.html",
include_str!("../templates/sheet_preview.html"),
)
.expect("admin/sheet_preview.html parses");
env.add_template(
"admin/sheet_edit.html",
include_str!("../templates/sheet_edit.html"),
)
.expect("admin/sheet_edit.html parses");
env.add_template(
"admin/sheet_create.html",
include_str!("../templates/sheet_create.html"),
)
.expect("admin/sheet_create.html parses");
env.add_template(
"admin/confirm_delete.html",
include_str!("../templates/confirm_delete.html"),
)
.expect("admin/confirm_delete.html parses");
env.add_template(
"admin/rows_fragment.html",
include_str!("../templates/rows_fragment.html"),
)
.expect("admin/rows_fragment.html parses");
env.add_template(
"admin/_macros/data_table.html",
include_str!("../templates/_macros/data_table.html"),
)
.expect("admin/_macros/data_table.html parses");
env.add_template(
"admin/_macros/sheet.html",
include_str!("../templates/_macros/sheet.html"),
)
.expect("admin/_macros/sheet.html parses");
env.add_template(
"admin/_macros/field_editor.html",
include_str!("../templates/_macros/field_editor.html"),
)
.expect("admin/_macros/field_editor.html parses");
env.add_template(
"admin/_macros/inlines.html",
include_str!("../templates/_macros/inlines.html"),
)
.expect("admin/_macros/inlines.html parses");
env.add_template(
"admin/_macros/confirm_dialog.html",
include_str!("../templates/_macros/confirm_dialog.html"),
)
.expect("admin/_macros/confirm_dialog.html parses");
env.add_template(
"admin/_macros/filter_dialog.html",
include_str!("../templates/_macros/filter_dialog.html"),
)
.expect("admin/_macros/filter_dialog.html parses");
env.add_template(
"admin/filter_dialog_fragment.html",
include_str!("../templates/filter_dialog_fragment.html"),
)
.expect("admin/filter_dialog_fragment.html parses");
// Phase 4 templates
env.add_template(
"admin/_macros/audit_timeline.html",
include_str!("../templates/_macros/audit_timeline.html"),
)
.expect("admin/_macros/audit_timeline.html parses");
env.add_template(
"admin/history.html",
include_str!("../templates/history.html"),
)
.expect("admin/history.html parses");
env.add_template(
"admin/dashboard.html",
include_str!("../templates/dashboard.html"),
)
.expect("admin/dashboard.html parses");
env.add_template(
"admin/widget_data.html",
include_str!("../templates/widget_data.html"),
)
.expect("admin/widget_data.html parses");
env.add_template(
"admin/palette.html",
include_str!("../templates/palette.html"),
)
.expect("admin/palette.html parses");
// Widget macros
env.add_template(
"admin/_macros/widgets/kpi.html",
include_str!("../templates/_macros/widgets/kpi.html"),
)
.expect("admin/_macros/widgets/kpi.html parses");
env.add_template(
"admin/_macros/widgets/bar.html",
include_str!("../templates/_macros/widgets/bar.html"),
)
.expect("admin/_macros/widgets/bar.html parses");
env.add_template(
"admin/_macros/widgets/card.html",
include_str!("../templates/_macros/widgets/card.html"),
)
.expect("admin/_macros/widgets/card.html parses");
env.add_template(
"admin/_macros/widgets/donut.html",
include_str!("../templates/_macros/widgets/donut.html"),
)
.expect("admin/_macros/widgets/donut.html parses");
env.add_template(
"admin/_macros/widgets/line.html",
include_str!("../templates/_macros/widgets/line.html"),
)
.expect("admin/_macros/widgets/line.html parses");
env.add_template(
"admin/_macros/widgets/feed.html",
include_str!("../templates/_macros/widgets/feed.html"),
)
.expect("admin/_macros/widgets/feed.html parses");
env.add_template(
"admin/_macros/widgets/table.html",
include_str!("../templates/_macros/widgets/table.html"),
)
.expect("admin/_macros/widgets/table.html parses");
env.add_template(
"admin/_macros/widgets/radial.html",
include_str!("../templates/_macros/widgets/radial.html"),
)
.expect("admin/_macros/widgets/radial.html parses");
env.add_template(
"admin/_macros/widgets/heatmap.html",
include_str!("../templates/_macros/widgets/heatmap.html"),
)
.expect("admin/_macros/widgets/heatmap.html parses");
env.add_template(
"admin/_macros/widgets/progress.html",
include_str!("../templates/_macros/widgets/progress.html"),
)
.expect("admin/_macros/widgets/progress.html parses");
// Preview macros
env.add_template(
"admin/_macros/previews/image.html",
include_str!("../templates/_macros/previews/image.html"),
)
.expect("admin/_macros/previews/image.html parses");
env.add_template(
"admin/_macros/previews/pdf.html",
include_str!("../templates/_macros/previews/pdf.html"),
)
.expect("admin/_macros/previews/pdf.html parses");
env.add_template(
"admin/_macros/previews/video_audio.html",
include_str!("../templates/_macros/previews/video_audio.html"),
)
.expect("admin/_macros/previews/video_audio.html parses");
env.add_template(
"admin/_macros/previews/code_text.html",
include_str!("../templates/_macros/previews/code_text.html"),
)
.expect("admin/_macros/previews/code_text.html parses");
env.add_template(
"admin/_macros/previews/download.html",
include_str!("../templates/_macros/previews/download.html"),
)
.expect("admin/_macros/previews/download.html parses");
// Expose the runtime environment ("dev" / "test" / "prod") as a
// template global. wrapper.html gates the Tailwind CDN script
// on this: dev loads the CDN, prod expects /static/admin/admin.css.
// Read from `umbral::settings::get_opt()` (Optional) so the engine
// builds even before `App::build` ran — tests bypass App::build
// and would otherwise panic in `settings::get()`.
let env_name: &'static str = umbral::settings::get_opt()
.map(|s| match s.environment {
umbral::Environment::Dev => "dev",
umbral::Environment::Test => "test",
umbral::Environment::Prod => "prod",
})
.unwrap_or("dev");
env.add_global("environment", minijinja::Value::from(env_name));
// Developer-supplied branding. Plugin::routes() seals
// AdminPlugin::site_title / site_description / brand_color
// into a static cell before the first render; we read it
// here and inject the values as template globals so every
// template can reference `site_title` / `brand_color` etc.
// without the handler having to thread them through context.
let branding = crate::branding::current();
env.add_global("site_title", minijinja::Value::from(branding.site_title));
env.add_global(
"site_description",
minijinja::Value::from(branding.site_description),
);
env.add_global("brand_color", minijinja::Value::from(branding.brand_color));
// Gap 107: the admin base path. Templates reference this
// via `{{ admin_base }}` so cross-page links and HTMX
// targets resolve under whatever prefix the developer
// configured. Defaults to `/admin`. Registered as a safe
// string so inline-script contexts (e.g.
// `htmx.ajax('GET', '{{ admin_base }}/api/...')`) don't
// HTML-entity-escape the leading slash. The value is a
// URL path under the framework's control, never user input.
env.add_global(
"admin_base",
minijinja::Value::from_safe_string(branding.base_path),
);
// gaps2 #33: expose the flag so the "Home" breadcrumb link in
// base.html can append `?dashboard=1` when the feature is on.
env.add_global(
"restore_last_path",
minijinja::Value::from(branding.restore_last_path),
);
// Unified static pipeline — register the `static()` global so
// admin templates resolve assets through the same `static_url`
// the core engine uses: `{{ static("admin/admin.css") }}` →
// `<static_url>admin/admin.css` (default `/static/admin/admin.css`).
// The admin engine builds its own minijinja `Environment`, so the
// core engine's `static()` function isn't inherited; we register an
// equivalent here, routing through `umbral::templates::resolve_static_url`
// so the resolution logic lives in one place.
env.add_function("static", |path: String| -> String {
umbral::templates::resolve_static_url(&path)
});
// Media-key resolver — mirrors `static()` but routes a stored
// file/image KEY through the ambient Storage backend's `url()`
// so changelist + preview templates render the public URL
// (`/media/<key>`) instead of the opaque key. An empty key
// yields an empty string (the template skips the markup); with
// no Storage backend wired the raw key falls through unchanged.
env.add_function("media_url", |key: String| -> String {
if key.is_empty() {
return String::new();
}
umbral::storage::storage_opt()
.map(|s| s.url(&key))
.unwrap_or(key)
});
env
})
}
/// Render a named template against the supplied context. Errors are
/// wrapped in `AdminError::Render` so handlers can early-return with
/// `?` like any other database/IO call.
pub(crate) fn render(name: &str, ctx: minijinja::Value) -> Result<Html<String>, AdminError> {
let tmpl = engine()
.get_template(name)
.map_err(|e| AdminError::Render(e.to_string()))?;
let body = tmpl
.render(umbral::templates::merge_ambient_value(ctx))
.map_err(|e| AdminError::Render(e.to_string()))?;
Ok(Html(body))
}
#[cfg(test)]
mod tojson_xss_tests {
/// WEB-3 regression: `tojson` output is interpolated into inline
/// `<script>` blocks (via `from_safe_string`, so autoescape is off).
/// A filter value containing `</script>` must be escaped to its
/// `\uXXXX` JSON form so it can't terminate the script element and
/// inject attacker JS into the admin origin.
#[test]
fn tojson_escapes_script_breakout_sequences() {
let env = super::engine();
let out = env
.render_str(
"{{ v | tojson }}",
minijinja::context! { v => "</script><script>alert(1)</script>" },
)
.expect("render tojson");
assert!(
!out.contains("</script>"),
"a raw </script> must not survive tojson: {out}"
);
assert!(
!out.contains("<script>"),
"a raw <script> must not survive tojson: {out}"
);
assert!(
out.contains("\\u003c"),
"`<` should be escaped to \\u003c: {out}"
);
// It must still be valid JSON that round-trips to the same string.
let parsed: String = serde_json::from_str(&out).expect("valid JSON");
assert_eq!(parsed, "</script><script>alert(1)</script>");
}
}